JSPM

@ory/amp

0.10.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 327
  • Score
    100M100P100Q10340F
  • License Apache-2.0

Ory plugin for Amp (Sourcegraph's coding agent): a permission delegate that authorizes every tool call plus an in-process plugin for session auth and audit tracing

Package Exports

  • @ory/amp

Readme

Ory Agent Plugin: Amp

Ory bundled into Amp (Sourcegraph's coding agent): skills that scaffold Ory authentication into your codebase, a local Ory stack you can spin up in one command, and (when pointed at an Ory project) authentication, authorization, and audit for every tool Amp runs.

You don't need an Ory account or any prior Ory experience to start.

New to Ory?

Ory is an open-source identity and access platform — login, registration, sessions, social sign-in, multi-factor auth, and fine-grained permissions, so you don't have to build any of that yourself. Two things make it easy to try with no prior experience:

  • Ory Elements are prebuilt, themeable UI components for the auth pages. The scaffolding skills wire them into your app for you.
  • The local Ory stack is a complete Ory running on your laptop in Docker — no account, no signup, no API key.

What this plugin does

Two independent things, and you can use either on its own:

  1. Build auth into your app. Have Amp scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This needs nothing but Docker.
  2. Govern the agent itself. Authenticate Amp's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See Agent security.

Prerequisites

  • Amp installed
  • Node.js ≥ 22
  • Docker (only needed for the local Ory stack)
  • macOS or Linux. Windows works via WSL2.

Install

npx -y -p @ory/amp ory-amp install

install performs two registrations and materializes the Ory skills:

  1. Registers the Ory permission delegate in Amp's settings (~/.config/amp/settings.json) under the flat top-level amp.permissions key as { tool: "*", action: "delegate", to: "ory-amp-permission" } — this is the blocking gate.
  2. Writes the in-process plugin loader at <project>/.amp/plugins/ory.ts so Amp's Bun TypeScript runtime discovers it for session auth and audit tracing.

The Ory skill playbooks land under <project>/.agents/skills/ (Amp's project skills directory).

npx -y -p @ory/amp ory-amp status      # confirm delegate + plugin registration
npx -y -p @ory/amp ory-amp uninstall   # remove the delegate, plugin, and skills

status prints configuration, user and agent identity, per-tool permission coverage, whether the delegate and in-process plugin are registered, and a tail of recent debug logs.

Quickstart (≈ 3 minutes)

From any project where you'd like Ory authentication, inside Amp:

  1. Start a local Ory instance. Ask Amp "start the local Ory stack" or run /local-up. A banner prints the seeded test user's email and password — note them.
  2. Scaffold Ory into your project. Ask Amp "add Ory auth to this app" (the ory-auth-setup skill). It installs Ory Elements, wires the SDK, and generates the login / registration / recovery / settings pages, all targeting the local stack.
  3. Sign in. Start your app, visit the login page, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, zero configuration.

Continue to Agent security when you're ready to enforce.

How the integration works

Amp's Ory integration is a hybrid of two mechanisms:

  • Blocking gate — a permission delegate helper (ory-amp-permission). Registered in amp.permissions, Amp invokes it per tool call with the tool params on stdin and decides by exit code: 0 = allow, 1 = ask, ≥2 = reject (stderr is surfaced to the model). This is the only part that can block. Amp enforces a 10-second delegate timeout, so the Ory check fails open (allows) on slow or unreachable backends.
  • Advisory in-process plugin (.amp/plugins/ory.ts). Discovered by Amp's Bun runtime, it handles session-start auth (advisory — it cannot hard-block at session start) and post-tool audit tracing.

The phases map as:

  • Session start (in-process plugin) — run the user and agent auth gates; advisory.
  • Per-tool decision (delegate) — check the tool against Ory Permissions; in enforce mode a deny exits 2 (reject), in observe mode it records a permission.observe_deny span and allows (exit 0).
  • Post-tool (in-process plugin) — trace-only audit spans.

The plugin is fail-open on its own infrastructure failures (network errors, rate limits, missing config): the agent always starts, and enforcement is only as strong as your permission grants.

Agent security

Once pointed at an Ory project (local or hosted), Amp's session and every tool call can be governed by Ory.

  • Authentication. The human at the keyboard (the user) authenticates interactively via Ory Identities when user login is on (ORY_USER_LOGIN=true, off by default — browser PKCE flow on first session, persisted thereafter). The Amp process (the agent) gets its own OAuth2 identity via Dynamic Client Registration (RFC 7591) on first run.
  • Authorization. Before any tool runs, the delegate checks Ory Permissions (Zanzibar-style relations) against the user's subject and rejects on deny.
  • Audit. Every decision is recorded as a structured trace span (NDJSON file and/or OTLP export).

Permission modes: observe → enforce

After install the integration runs in observe mode: every tool call is checked, but a deny is recorded as a permission.observe_deny audit span and the tool runs anyway.

# Grant the current user `use` on every built-in tool (idempotent):
npx -y -p @ory/amp ory-amp permissions bootstrap

# See allowed/denied per tool:
npx -y -p @ory/amp ory-amp permissions status

# Turn on hard blocking once the observe-mode logs look right:
npx -y -p @ory/amp ory-amp permissions enforce

Switch back any time with permissions observe. To disable Ory entirely (audit logging only), run ory-amp configure --audit-only.

Pointing at a real Ory project

The Quickstart uses the local stack. To point at a hosted Ory Network project:

npx -y -p @ory/amp ory-amp configure \
  --project-url https://<id>.projects.oryapis.com \
  --oauth2-client-id <public OAuth2 client id>

--oauth2-client-id is required whenever --project-url is set — the user PKCE flow needs a public OAuth2 client registered with the four loopback redirect URIs (http://127.0.0.1:47823..47826/callback). See the repo README and AGENTS.md for the full environment-variable reference and permission-mode semantics. Config is shared across every Ory agent plugin at ~/.config/ory-agent-plugins/config.json.

Without configuration the plugin still loads cleanly and runs in pass-through mode: skills work, but nothing is blocked.

License

Apache-2.0