@openparachute/vault 0.3.1 → 0.4.0

package/src/mcp-tools.ts

@@ -9,8 +9,14 @@ import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
 import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { hasScope, SCOPE_WRITE } from "./scopes.ts";
+import { hasScopeForVault } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
+import {
+  expandTokenTagScope,
+  noteWithinTagScope,
+  tagsWithinScope,
+} from "./tag-scope.ts";
+import { findTokensReferencingTag } from "./token-store.ts";
 
 /**
  * Get the MCP server instruction for a vault.
@@ -46,10 +52,291 @@ export function generateScopedMcpTools(vaultName: string, auth?: AuthResult): Mc
   const tools = generateMcpTools(store);
 
   overrideVaultInfo(tools, vaultName, auth);
+  applyTagDependencyGuards(tools, vaultName);
+  applyTagScopeWrappers(tools, vaultName, auth);
 
   return tools;
 }
 
+/**
+ * Tag-delete and (future) tag-merge always check for tag-scoped tokens
+ * referencing the doomed tag — regardless of whether the *deleter* is
+ * itself tag-scoped. A successful delete that orphans an allowlist would
+ * silently widen surface area downstream. Mirrors the REST 409
+ * `tag_in_use_by_tokens` envelope.
+ */
+function applyTagDependencyGuards(tools: McpToolDef[], vaultName: string): void {
+  const store = getVaultStore(vaultName);
+  wrapReadTool(tools, "delete-tag", async (orig, params) => {
+    const tag = (params as any).tag ?? (params as any).name;
+    if (typeof tag === "string") {
+      const referenced_by = findTokensReferencingTag(store.db, tag);
+      if (referenced_by.length > 0) {
+        return {
+          error: "TagInUseByTokens",
+          error_type: "tag_in_use_by_tokens",
+          message: `Tag "${tag}" is referenced by ${referenced_by.length} tag-scoped token(s); revoke or re-mint them before deleting.`,
+          tag,
+          referenced_by,
+        };
+      }
+    }
+    return await orig(params);
+  });
+}
+
+/**
+ * Wrap read-tool execute() functions to filter results down to what the
+ * token's `scoped_tags` allowlist permits. No-op when the token is
+ * unscoped — the wrappers fast-path on `auth.scoped_tags === null` so
+ * unscoped sessions retain identical pre-tag-scope behavior.
+ *
+ * Read tools handled here:
+ *   - query-notes:      filter single-note returns + result lists
+ *   - list-tags:        filter to allowlisted tags + descendants
+ *   - find-path:        require both endpoints (and every hop) in scope
+ *   - synthesize-notes: anchor + neighbors all gated by scope
+ *
+ * Write-tool gating happens in handleScopedMcp at the verb-scope layer
+ * AND inside each tool's wrapper here (so a tag-scoped `vault:write`
+ * token can't write outside its allowlist). See applyTagScopeWriteGuards.
+ */
+function applyTagScopeWrappers(
+  tools: McpToolDef[],
+  vaultName: string,
+  auth: AuthResult | undefined,
+): void {
+  if (!auth || !auth.scoped_tags || auth.scoped_tags.length === 0) return;
+  const store = getVaultStore(vaultName);
+  // Lazy: only build the expanded allowlist on first tool call.
+  let allowedPromise: Promise<Set<string> | null> | null = null;
+  const getAllowed = (): Promise<Set<string> | null> => {
+    if (!allowedPromise) {
+      allowedPromise = expandTokenTagScope(store, auth.scoped_tags);
+    }
+    return allowedPromise;
+  };
+  const rawTags = auth.scoped_tags;
+
+  wrapReadTool(tools, "query-notes", async (orig, params) => {
+    const allowed = await getAllowed();
+    const result = await orig(params);
+    if (!allowed) return result;
+    // Single-note shape (`{...note}` with `id`) vs list shape (array).
+    if (Array.isArray(result)) {
+      return result.filter((n: any) => noteWithinTagScope(n, allowed, rawTags));
+    }
+    if (result && typeof result === "object" && "id" in result && "tags" in result) {
+      return noteWithinTagScope(result as any, allowed, rawTags)
+        ? result
+        : { error: "Note not found", id: (result as any).id };
+    }
+    return result;
+  });
+
+  wrapReadTool(tools, "list-tags", async (orig, params) => {
+    const allowed = await getAllowed();
+    const result = await orig(params);
+    if (!allowed || !Array.isArray(result)) return result;
+    return result.filter((t: any) => allowed.has(t.name));
+  });
+
+  wrapReadTool(tools, "find-path", async (orig, params) => {
+    const allowed = await getAllowed();
+    const result = await orig(params);
+    if (!allowed || !result || typeof result !== "object" || !("path" in result)) return result;
+    const ids = (result as any).path as string[];
+    for (const id of ids) {
+      const note = await store.getNote(id);
+      if (!note || !noteWithinTagScope(note, allowed, rawTags)) {
+        return null;
+      }
+    }
+    return result;
+  });
+
+  wrapReadTool(tools, "synthesize-notes", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    // Verify the anchor is in scope first — out-of-scope anchor 404s as if
+    // the note doesn't exist, mirroring the REST find-path semantics.
+    const anchorId = (params as any).id ?? (params as any).note_id;
+    if (anchorId) {
+      const anchor = await store.getNote(anchorId as string);
+      if (!anchor || !noteWithinTagScope(anchor, allowed, rawTags)) {
+        return { error: "Note not found", id: anchorId };
+      }
+    }
+    const result = await orig(params);
+    // Filter neighbors to those in scope. The synthesize-notes shape exposes
+    // `neighbors` (array of note objects with tags) — mirror the query-notes
+    // filter pattern here.
+    if (result && typeof result === "object" && Array.isArray((result as any).neighbors)) {
+      (result as any).neighbors = (result as any).neighbors.filter((n: any) =>
+        noteWithinTagScope(n, allowed, rawTags),
+      );
+    }
+    return result;
+  });
+
+  // ---- Write-side guards ----
+  //
+  // The verb-scope check (`vault:write`) is enforced at the dispatch layer
+  // in handleScopedMcp. These wrappers add the second axis: a scoped
+  // `vault:write` token can only mutate within its tag-allowlist, never
+  // outside it. Tag operations (`update-tag`, `delete-tag`) gate on the
+  // tag name itself; note operations gate on the prospective tag set.
+
+  const forbidden = (msg: string): unknown => ({
+    error: "Forbidden",
+    error_type: "tag_scope_violation",
+    message: `${msg} (token tag-allowlist: ${rawTags.join(", ")})`,
+    scoped_tags: rawTags,
+  });
+
+  wrapReadTool(tools, "create-note", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    // Single or batch shape: `{notes: [...]}` is the batch form (mirrors HTTP).
+    const items = Array.isArray((params as any).notes)
+      ? (params as any).notes
+      : [params];
+    for (const item of items) {
+      const itemTags = Array.isArray((item as any).tags) ? ((item as any).tags as string[]) : [];
+      if (!tagsWithinScope(itemTags, allowed, rawTags)) {
+        return forbidden("create-note: every note must carry at least one tag in the token's allowlist");
+      }
+    }
+    return await orig(params);
+  });
+
+  wrapReadTool(tools, "update-note", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const items = Array.isArray((params as any).notes)
+      ? (params as any).notes
+      : [params];
+    for (const item of items) {
+      const id = (item as any).id ?? (item as any).note_id;
+      if (!id) continue;
+      const existing = await store.getNote(id as string);
+      if (!existing || !noteWithinTagScope(existing, allowed, rawTags)) {
+        return { error: "Note not found", id };
+      }
+      const removed = new Set<string>((item as any).tags?.remove ?? []);
+      const projected = new Set<string>((existing.tags ?? []).filter((t) => !removed.has(t)));
+      for (const t of ((item as any).tags?.add ?? []) as string[]) projected.add(t);
+      if (!tagsWithinScope([...projected], allowed, rawTags)) {
+        return forbidden("update-note: post-update tag set must satisfy the token's allowlist");
+      }
+    }
+    return await orig(params);
+  });
+
+  wrapReadTool(tools, "delete-note", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const id = (params as any).id ?? (params as any).note_id;
+    if (id) {
+      const existing = await store.getNote(id as string);
+      if (!existing || !noteWithinTagScope(existing, allowed, rawTags)) {
+        return { error: "Note not found", id };
+      }
+    }
+    return await orig(params);
+  });
+
+  wrapReadTool(tools, "update-tag", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const tag = (params as any).tag ?? (params as any).name;
+    if (typeof tag === "string" && !allowed.has(tag)) {
+      return forbidden(`update-tag: tag "${tag}" is outside the token's allowlist`);
+    }
+    return await orig(params);
+  });
+
+  wrapReadTool(tools, "delete-tag", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const tag = (params as any).tag ?? (params as any).name;
+    if (typeof tag === "string" && !allowed.has(tag)) {
+      return forbidden(`delete-tag: tag "${tag}" is outside the token's allowlist`);
+    }
+    return await orig(params);
+  });
+
+  // Note-schemas mappings — same auth boundary as REST `handleNoteSchemas`.
+  // `tag`-kind mappings are tag-scoped data; `path_prefix`-kind mappings carry
+  // no tag-axis information and stay visible/writable. The single-tag check
+  // delegates to `tagsWithinScope` so the string-form fallback is honored.
+
+  wrapReadTool(tools, "list-note-schemas", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const result = await orig(params);
+    const filterMappings = (mappings: any[]): any[] =>
+      mappings.filter(
+        (m: any) => m.match_kind !== "tag" || tagsWithinScope([m.match_value], allowed, rawTags),
+      );
+    if (Array.isArray(result)) {
+      return result.map((s: any) =>
+        Array.isArray(s.mappings) ? { ...s, mappings: filterMappings(s.mappings) } : s,
+      );
+    }
+    if (result && typeof result === "object" && Array.isArray((result as any).mappings)) {
+      return { ...(result as any), mappings: filterMappings((result as any).mappings) };
+    }
+    return result;
+  });
+
+  wrapReadTool(tools, "set-schema-mapping", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const match_kind = (params as any).match_kind;
+    const match_value = (params as any).match_value;
+    if (
+      match_kind === "tag" &&
+      typeof match_value === "string" &&
+      !tagsWithinScope([match_value], allowed, rawTags)
+    ) {
+      return forbidden(`set-schema-mapping: tag "${match_value}" is outside the token's allowlist`);
+    }
+    return await orig(params);
+  });
+
+  wrapReadTool(tools, "delete-schema-mapping", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const match_kind = (params as any).match_kind;
+    const match_value = (params as any).match_value;
+    if (
+      match_kind === "tag" &&
+      typeof match_value === "string" &&
+      !tagsWithinScope([match_value], allowed, rawTags)
+    ) {
+      return forbidden(`delete-schema-mapping: tag "${match_value}" is outside the token's allowlist`);
+    }
+    return await orig(params);
+  });
+}
+
+function wrapReadTool(
+  tools: McpToolDef[],
+  name: string,
+  wrapper: (orig: (params: Record<string, unknown>) => Promise<unknown>, params: Record<string, unknown>) => Promise<unknown>,
+): void {
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) return;
+  // McpToolDef.execute returns `unknown | Promise<unknown>` (sync OR async).
+  // Adapt to the wrapper's strictly-async signature so wrappers can `await
+  // orig(params)` uniformly without re-checking each tool.
+  const orig = tool.execute;
+  const origAsync = (params: Record<string, unknown>): Promise<unknown> =>
+    Promise.resolve(orig(params));
+  tool.execute = (params) => wrapper(origAsync, params);
+}
+
 function overrideVaultInfo(
   tools: McpToolDef[],
   vaultName: string,
@@ -64,12 +351,13 @@ function overrideVaultInfo(
 
     if (params.description !== undefined) {
       // Secondary scope check: vault-info is read-gated so read-only callers
-      // can fetch stats, but mutating the vault description requires write.
-      // Without this, a vault:read token could bypass the outer gate by
-      // passing `description` to a tool the outer gate considers read-only.
-      if (!auth || !hasScope(auth.scopes, SCOPE_WRITE)) {
+      // can fetch stats, but mutating the vault description requires write
+      // for THIS vault. Without this, a vault:read token could bypass the
+      // outer gate by passing `description` to a tool the outer gate
+      // considers read-only.
+      if (!auth || !hasScopeForVault(auth.scopes, vaultName, "write")) {
         throw new Error(
-          `Forbidden: updating the vault description requires the '${SCOPE_WRITE}' scope. Granted scopes: ${auth?.scopes.join(" ") || "(none)"}.`,
+          `Forbidden: updating the vault description requires the 'vault:write' scope (or 'vault:${vaultName}:write'). Granted scopes: ${auth?.scopes.join(" ") || "(none)"}.`,
         );
       }
       config.description = params.description as string;

package/src/module-config.ts

@@ -84,7 +84,7 @@ export function buildConfigSchema(): ModuleConfigSchema {
 export function buildConfigValues(
   vaultConfig: VaultConfig,
   globalConfig: GlobalConfig,
-  env: { SCRIBE_URL?: string } = process.env,
+  env: { SCRIBE_URL?: string | undefined } = process.env as { SCRIBE_URL?: string },
 ): Record<string, unknown> {
   return {
     audio_retention: vaultConfig.audio_retention ?? "keep",

package/src/oauth.test.ts

@@ -280,6 +280,28 @@ describe("OAuth authorization", () => {
     expect(location.searchParams.get("state")).toBe("mystate");
   });
 
+  test("POST authorize without scope is rejected (no silent default to 'full', #197)", async () => {
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeChallenge } = generatePkce();
+    const req = makeRequest("https://vault.test/oauth/authorize", {
+      method: "POST",
+      body: new URLSearchParams({
+        action: "authorize",
+        client_id: clientId,
+        redirect_uri: "https://example.com/callback",
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+        // No scope field — pre-#197 this silently consented to "full".
+        owner_token: ownerToken,
+      }),
+    });
+    const res = await handleAuthorizePost(req, db);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error?: string };
+    expect(body.error).toBe("invalid_request");
+  });
+
   test("POST authorize (deny) redirects with error", async () => {
     const clientId = await registerClient();
     const { codeChallenge } = generatePkce();
@@ -1809,3 +1831,326 @@ describe("OAuth Phase 0: PARACHUTE_HUB_ORIGIN", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Per-vault rate limiter + memory cap (#93)
+// ---------------------------------------------------------------------------
+
+describe("OAuth consent — per-vault rate limiting (#93)", () => {
+  test("getAuthorizeRateLimiter returns the same instance for the same vault name", async () => {
+    const { getAuthorizeRateLimiter, resetVaultAuthorizeRateLimiters } =
+      await import("./owner-auth.ts");
+    resetVaultAuthorizeRateLimiters();
+    const a1 = getAuthorizeRateLimiter("alpha");
+    const a2 = getAuthorizeRateLimiter("alpha");
+    expect(a1).toBe(a2);
+  });
+
+  test("getAuthorizeRateLimiter returns distinct instances per vault", async () => {
+    const { getAuthorizeRateLimiter, resetVaultAuthorizeRateLimiters } =
+      await import("./owner-auth.ts");
+    resetVaultAuthorizeRateLimiters();
+    const work = getAuthorizeRateLimiter("work");
+    const personal = getAuthorizeRateLimiter("personal");
+    expect(work).not.toBe(personal);
+  });
+
+  test("a lockout on one vault's limiter does not lock the same IP on another vault's limiter", async () => {
+    const { getAuthorizeRateLimiter, resetVaultAuthorizeRateLimiters } =
+      await import("./owner-auth.ts");
+    resetVaultAuthorizeRateLimiters();
+    const ip = "192.0.2.55";
+    const work = getAuthorizeRateLimiter("work");
+    // Pump enough failures on `work` to trip the default 10-failure threshold.
+    for (let i = 0; i < 10; i++) work.recordFailure(ip);
+    expect(work.check(ip).allowed).toBe(false);
+    // The unrelated vault's limiter should still allow this IP.
+    const personal = getAuthorizeRateLimiter("personal");
+    expect(personal.check(ip).allowed).toBe(true);
+  });
+
+  test("entry count is hard-capped — oldest IP is evicted FIFO when full", async () => {
+    const { RateLimiter } = await import("./owner-auth.ts");
+    // Tiny cap (3) so we don't have to hammer the limiter to prove eviction.
+    const limiter = new RateLimiter(10, 60_000, 60_000, 3);
+    limiter.recordFailure("10.0.0.1");
+    limiter.recordFailure("10.0.0.2");
+    limiter.recordFailure("10.0.0.3");
+    expect(limiter.size()).toBe(3);
+    // Adding a 4th IP must evict the oldest (10.0.0.1) to stay at the cap.
+    limiter.recordFailure("10.0.0.4");
+    expect(limiter.size()).toBe(3);
+    // The evicted IP is treated as untracked → fresh check is allowed.
+    expect(limiter.check("10.0.0.1").allowed).toBe(true);
+    // Newer entries remain locked into their failure state.
+    expect(limiter.check("10.0.0.4").allowed).toBe(true); // still under threshold
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Server-bound scope at /authorize, subset enforcement at /token (#94)
+// ---------------------------------------------------------------------------
+
+describe("OAuth scope binding (#94, RFC 6749 §3.3 / §6)", () => {
+  test("/authorize floors selected scope to requested — form cannot smuggle a broader scope", async () => {
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeChallenge } = generatePkce();
+    const redirectUri = "https://example.com/callback";
+
+    const authRes = await handleAuthorizePost(
+      makeRequest("https://vault.test/oauth/authorize", {
+        method: "POST",
+        body: new URLSearchParams({
+          action: "authorize",
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+          scope: "read",            // requested = read
+          selected_scope: "full",   // smuggled broader value
+          owner_token: ownerToken,
+        }),
+      }),
+      db,
+      { vaultName: "default" },
+    );
+    expect(authRes.status).toBe(302);
+    const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+
+    // The bound scope on the issued auth code must be the narrower of the two.
+    const row = db
+      .prepare("SELECT scope FROM oauth_codes WHERE code = ?")
+      .get(code) as { scope: string };
+    expect(row.scope).toBe("read");
+  });
+
+  test("/token rejects requested scope broader than bound (read → full)", async () => {
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = "https://example.com/callback";
+
+    const authRes = await handleAuthorizePost(
+      makeRequest("https://vault.test/oauth/authorize", {
+        method: "POST",
+        body: new URLSearchParams({
+          action: "authorize",
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+          scope: "read",
+          owner_token: ownerToken,
+        }),
+      }),
+      db,
+      { vaultName: "default" },
+    );
+    const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+
+    const tokenRes = await handleToken(
+      makeRequest("https://vault.test/oauth/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          code_verifier: codeVerifier,
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          scope: "full", // attempt to broaden
+        }).toString(),
+      }),
+      db,
+      "default",
+    );
+    expect(tokenRes.status).toBe(400);
+    const body = (await tokenRes.json()) as { error?: string };
+    expect(body.error).toBe("invalid_scope");
+  });
+
+  test("/token accepts a narrower requested scope (full → read) and reflects it on the token", async () => {
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = "https://example.com/callback";
+
+    const authRes = await handleAuthorizePost(
+      makeRequest("https://vault.test/oauth/authorize", {
+        method: "POST",
+        body: new URLSearchParams({
+          action: "authorize",
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+          scope: "full",
+          owner_token: ownerToken,
+        }),
+      }),
+      db,
+      { vaultName: "default" },
+    );
+    const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+
+    const tokenRes = await handleToken(
+      makeRequest("https://vault.test/oauth/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          code_verifier: codeVerifier,
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          scope: "read", // narrower than bound
+        }).toString(),
+      }),
+      db,
+      "default",
+    );
+    expect(tokenRes.status).toBe(200);
+    const body = (await tokenRes.json()) as { scope?: string };
+    expect(body.scope).toBe("vault:read");
+  });
+
+  test("/token treats whitespace-only scope as absent and falls through to bound scope (#196)", async () => {
+    // Guard at oauth.ts checks `scope !== null && scope.trim().length > 0`.
+    // A client sending `scope=   ` is the same as omitting `scope` — we
+    // must not run subset enforcement against the whitespace string and
+    // reject it as invalid.
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = "https://example.com/callback";
+
+    const authRes = await handleAuthorizePost(
+      makeRequest("https://vault.test/oauth/authorize", {
+        method: "POST",
+        body: new URLSearchParams({
+          action: "authorize",
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+          scope: "read",
+          owner_token: ownerToken,
+        }),
+      }),
+      db,
+      { vaultName: "default" },
+    );
+    const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+
+    const tokenRes = await handleToken(
+      makeRequest("https://vault.test/oauth/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          code_verifier: codeVerifier,
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          scope: "   ", // whitespace only — should fall through to bound
+        }).toString(),
+      }),
+      db,
+      "default",
+    );
+    expect(tokenRes.status).toBe(200);
+    const body = (await tokenRes.json()) as { scope?: string };
+    expect(body.scope).toBe("vault:read");
+  });
+
+  test("/token rejects unknown scope strings even when the bound scope is broad", async () => {
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = "https://example.com/callback";
+
+    const authRes = await handleAuthorizePost(
+      makeRequest("https://vault.test/oauth/authorize", {
+        method: "POST",
+        body: new URLSearchParams({
+          action: "authorize",
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+          scope: "full",
+          owner_token: ownerToken,
+        }),
+      }),
+      db,
+      { vaultName: "default" },
+    );
+    const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+
+    const tokenRes = await handleToken(
+      makeRequest("https://vault.test/oauth/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          code_verifier: codeVerifier,
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          scope: "vault:admin", // not in the consent vocabulary
+        }).toString(),
+      }),
+      db,
+      "default",
+    );
+    expect(tokenRes.status).toBe(400);
+    const body = (await tokenRes.json()) as { error?: string };
+    expect(body.error).toBe("invalid_scope");
+  });
+
+  test("/token uses the bound scope when no scope param is sent (regression)", async () => {
+    const ownerToken = createOwnerToken();
+    const clientId = await registerClient();
+    const { codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = "https://example.com/callback";
+
+    const authRes = await handleAuthorizePost(
+      makeRequest("https://vault.test/oauth/authorize", {
+        method: "POST",
+        body: new URLSearchParams({
+          action: "authorize",
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+          scope: "read",
+          owner_token: ownerToken,
+        }),
+      }),
+      db,
+      { vaultName: "default" },
+    );
+    const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+
+    const tokenRes = await handleToken(
+      makeRequest("https://vault.test/oauth/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          code_verifier: codeVerifier,
+          client_id: clientId,
+          redirect_uri: redirectUri,
+          // no scope param
+        }).toString(),
+      }),
+      db,
+      "default",
+    );
+    expect(tokenRes.status).toBe(200);
+    const body = (await tokenRes.json()) as { scope?: string };
+    expect(body.scope).toBe("vault:read");
+  });
+});