@openparachute/vault 0.3.3 → 0.4.3

package/src/auth.test.ts

@@ -83,7 +83,7 @@ function bearer(token: string): Request {
 }
 
 describe("auth — per-vault routing", () => {
-  test("token minted in a vault authenticates at its own /vault/<name>/* endpoints", () => {
+  test("token minted in a vault authenticates at its own /vault/<name>/* endpoints", async () => {
     seedVault("journal");
     const token = mintTokenInVault("journal");
     const journalConfig = readVaultConfig("journal")!;
@@ -91,44 +91,44 @@ describe("auth — per-vault routing", () => {
 
     // /vault/journal/api/* and /vault/journal/mcp both funnel into
     // authenticateVaultRequest with journal's config + DB.
-    const vaultAuth = authenticateVaultRequest(bearer(token), journalConfig, journalStore.db);
+    const vaultAuth = await authenticateVaultRequest(bearer(token), journalConfig, journalStore.db);
     expect("error" in vaultAuth).toBe(false);
     if (!("error" in vaultAuth)) expect(vaultAuth.permission).toBe("full");
 
     // /vaults (global metadata listing) uses authenticateGlobalRequest which
     // scans every vault's DB. Since the token is in journal's DB, it must resolve.
-    const global = authenticateGlobalRequest(bearer(token));
+    const global = await authenticateGlobalRequest(bearer(token));
     expect("error" in global).toBe(false);
   });
 
   // HTTP-level routing stand-in. Mirrors routing.ts: every vault-scoped path
   // matches `/vault/<name>/...`, we look the vault up, then authenticate the
   // request against that vault's DB.
-  function dispatchAuthFromPath(path: string, req: Request): {
+  async function dispatchAuthFromPath(path: string, req: Request): Promise<{
     status: number;
     permission?: string;
-  } {
+  }> {
     const match = path.match(/^\/vault\/([^/]+)(\/.*)?$/);
     if (!match) return { status: 404 };
-    const vaultName = match[1];
+    const vaultName = match[1]!;
     const vaultConfig = readVaultConfig(vaultName);
     if (!vaultConfig) return { status: 404 };
     const store = getVaultStore(vaultName);
-    const res = authenticateVaultRequest(req, vaultConfig, store.db);
+    const res = await authenticateVaultRequest(req, vaultConfig, store.db);
     if ("error" in res) return { status: res.error.status };
     return { status: 200, permission: res.permission };
   }
 
-  test("routing: /vault/<name>/api/health accepts a token minted in that vault", () => {
+  test("routing: /vault/<name>/api/health accepts a token minted in that vault", async () => {
     seedVault("journal");
     const token = mintTokenInVault("journal");
 
-    const result = dispatchAuthFromPath("/vault/journal/api/health", bearer(token));
+    const result = await dispatchAuthFromPath("/vault/journal/api/health", bearer(token));
     expect(result.status).toBe(200);
     expect(result.permission).toBe("full");
   });
 
-  test("routing: /vault/A/api/* rejects a token issued for vault B", () => {
+  test("routing: /vault/A/api/* rejects a token issued for vault B", async () => {
     // The privilege-escalation barrier: a valid token for vault A must not
     // authenticate at vault B's endpoint, even though the token is valid
     // for some vault. This is the point of per-vault DBs.
@@ -136,44 +136,103 @@ describe("auth — per-vault routing", () => {
     seedVault("work");
     const workToken = mintTokenInVault("work");
 
-    const crossVault = dispatchAuthFromPath("/vault/journal/api/health", bearer(workToken));
+    const crossVault = await dispatchAuthFromPath("/vault/journal/api/health", bearer(workToken));
     expect(crossVault.status).toBe(401);
   });
 
-  test("routing: /vault/<unknown> returns 404 (not 401)", () => {
+  test("routing: /vault/<unknown> returns 404 (not 401)", async () => {
     seedVault("journal");
     const token = mintTokenInVault("journal");
-    const result = dispatchAuthFromPath("/vault/nonexistent/api/health", bearer(token));
+    const result = await dispatchAuthFromPath("/vault/nonexistent/api/health", bearer(token));
     expect(result.status).toBe(404);
   });
 });
 
 describe("auth — cross-vault isolation", () => {
-  test("token minted in a non-default vault authenticates via scoped and global paths", () => {
+  test("token minted in a non-default vault authenticates via scoped and global paths", async () => {
     seedVault("journal", { isDefault: true });
     seedVault("work");
     const workToken = mintTokenInVault("work");
     const workConfig = readVaultConfig("work")!;
     const workStore = getVaultStore("work");
 
-    const scoped = authenticateVaultRequest(bearer(workToken), workConfig, workStore.db);
+    const scoped = await authenticateVaultRequest(bearer(workToken), workConfig, workStore.db);
     expect("error" in scoped).toBe(false);
 
     // Global auth scans every vault, must find the token in work's DB.
-    const global = authenticateGlobalRequest(bearer(workToken));
+    const global = await authenticateGlobalRequest(bearer(workToken));
     expect("error" in global).toBe(false);
   });
 
-  test("a work-vault token does NOT authenticate against the journal vault", () => {
+  test("a work-vault token does NOT authenticate against the journal vault", async () => {
     seedVault("journal", { isDefault: true });
     seedVault("work");
     const workToken = mintTokenInVault("work");
     const journalConfig = readVaultConfig("journal")!;
     const journalStore = getVaultStore("journal");
 
-    const res = authenticateVaultRequest(bearer(workToken), journalConfig, journalStore.db);
+    const res = await authenticateVaultRequest(bearer(workToken), journalConfig, journalStore.db);
     expect("error" in res).toBe(true);
   });
+
+  test("v16 vault_name binding rejects with 403 when the row is cross-vault", async () => {
+    // Per-vault DB scoping is the first line of defense (a token only
+    // resolves against the DB it was minted in). The v16 vault_name column
+    // is defense-in-depth: if a token row somehow lives in vault A's DB
+    // but its vault_name says "B" (e.g. an out-of-band copy, or a future
+    // mistake in the mint path), the binding mismatch must reject. We
+    // simulate that by minting into journal's DB with vault_name="work".
+    seedVault("journal", { isDefault: true });
+    seedVault("work");
+    const journalStore = getVaultStore("journal");
+    const { fullToken } = generateToken();
+    createToken(journalStore.db, fullToken, {
+      label: "mis-bound",
+      permission: "full",
+      vault_name: "work",
+    });
+    const journalConfig = readVaultConfig("journal")!;
+
+    const res = await authenticateVaultRequest(bearer(fullToken), journalConfig, journalStore.db);
+    expect("error" in res).toBe(true);
+    if ("error" in res) {
+      expect(res.error.status).toBe(403);
+    }
+  });
+
+  test("v16 vault_name binding accepts when token is bound to the requested vault", async () => {
+    seedVault("work");
+    const workStore = getVaultStore("work");
+    const { fullToken } = generateToken();
+    createToken(workStore.db, fullToken, {
+      label: "bound",
+      permission: "full",
+      vault_name: "work",
+    });
+    const workConfig = readVaultConfig("work")!;
+
+    const res = await authenticateVaultRequest(bearer(fullToken), workConfig, workStore.db);
+    expect("error" in res).toBe(false);
+    if (!("error" in res)) {
+      expect(res.vault_name).toBe("work");
+    }
+  });
+
+  test("legacy NULL-bound tokens still authenticate against any vault", async () => {
+    // Backwards compatibility: pre-v16 tokens (and legacy YAML keys, and
+    // hub JWTs) all carry vault_name = null. They keep working at any
+    // vault — the migration is lenient by design.
+    seedVault("work");
+    const workToken = mintTokenInVault("work");
+    const workConfig = readVaultConfig("work")!;
+    const workStore = getVaultStore("work");
+
+    const res = await authenticateVaultRequest(bearer(workToken), workConfig, workStore.db);
+    expect("error" in res).toBe(false);
+    if (!("error" in res)) {
+      expect(res.vault_name).toBeNull();
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -256,11 +315,11 @@ describe("OAuth-minted tokens — per-vault coherence", () => {
     const store = getVaultStore("journal");
 
     // /vault/journal/api/* and /vault/journal/mcp both reach this auth call.
-    const vaultAuth = authenticateVaultRequest(bearer(token), cfg, store.db);
+    const vaultAuth = await authenticateVaultRequest(bearer(token), cfg, store.db);
     expect("error" in vaultAuth).toBe(false);
 
     // /vaults (authenticated listing) uses authenticateGlobalRequest.
-    const global = authenticateGlobalRequest(bearer(token));
+    const global = await authenticateGlobalRequest(bearer(token));
     expect("error" in global).toBe(false);
   });
 
@@ -272,17 +331,70 @@ describe("OAuth-minted tokens — per-vault coherence", () => {
     const workStore = getVaultStore("work");
 
     // Valid at work's own endpoints.
-    const scoped = authenticateVaultRequest(bearer(token), workCfg, workStore.db);
+    const scoped = await authenticateVaultRequest(bearer(token), workCfg, workStore.db);
     expect("error" in scoped).toBe(false);
 
     // Global auth finds the token in work's DB.
-    const global = authenticateGlobalRequest(bearer(token));
+    const global = await authenticateGlobalRequest(bearer(token));
     expect("error" in global).toBe(false);
 
     // Isolation: the token is NOT usable against the journal vault.
     const journalCfg = readVaultConfig("journal")!;
     const journalStore = getVaultStore("journal");
-    const crossCheck = authenticateVaultRequest(bearer(token), journalCfg, journalStore.db);
+    const crossCheck = await authenticateVaultRequest(bearer(token), journalCfg, journalStore.db);
     expect("error" in crossCheck).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Legacy YAML global keys — scope must round-trip through the parser
+// ---------------------------------------------------------------------------
+
+describe("auth — legacy global YAML keys honor declared scope", () => {
+  test("scope: read on a global config.yaml key resolves to read permission, not full", async () => {
+    // Regression: the global parser used to drop the `scope` field, leaving
+    // `globalKey.scope` undefined. The auth check `=== "read"` then resolved
+    // any undefined value to "full", silently escalating read-only keys.
+    const { fullKey, keyId } = generateApiKey();
+    writeGlobalConfig({
+      port: 1940,
+      api_keys: [
+        {
+          id: keyId,
+          label: "reader",
+          scope: "read",
+          key_hash: hashKey(fullKey),
+          created_at: new Date().toISOString(),
+        },
+      ],
+    });
+
+    const result = await authenticateGlobalRequest(bearer(fullKey));
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("read");
+    }
+  });
+
+  test("scope: write on a global config.yaml key resolves to full permission", async () => {
+    const { fullKey, keyId } = generateApiKey();
+    writeGlobalConfig({
+      port: 1940,
+      api_keys: [
+        {
+          id: keyId,
+          label: "writer",
+          scope: "write",
+          key_hash: hashKey(fullKey),
+          created_at: new Date().toISOString(),
+        },
+      ],
+    });
+
+    const result = await authenticateGlobalRequest(bearer(fullKey));
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+    }
+  });
+});

package/src/auth.ts

@@ -21,7 +21,16 @@ import { resolveToken } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
 import type { Database } from "bun:sqlite";
 import { getVaultStore } from "./vault-store.ts";
-import { hasScope, legacyPermissionToScopes, SCOPE_ADMIN, SCOPE_READ, SCOPE_WRITE } from "./scopes.ts";
+import {
+  findBroadVaultScopes,
+  hasScope,
+  hasScopeForVault,
+  legacyPermissionToScopes,
+  SCOPE_ADMIN,
+  SCOPE_READ,
+  SCOPE_WRITE,
+} from "./scopes.ts";
+import { HubJwtError, looksLikeJwt, validateHubJwt } from "./hub-jwt.ts";
 
 /** Result of a successful auth check. */
 export interface AuthResult {
@@ -34,6 +43,21 @@ export interface AuthResult {
    * one-time deprecation warning when they encounter `legacyDerived: true`.
    */
   legacyDerived: boolean;
+  /**
+   * Tag-allowlist (root tag names) for tag-scoped tokens. NULL = unscoped
+   * (current full-vault behavior). Hub-issued JWTs and legacy YAML keys
+   * always have null — tag scoping is a per-token vault-DB attribute, not
+   * an OAuth-claim concern. See patterns/tag-scoped-tokens.md.
+   */
+  scoped_tags: string[] | null;
+  /**
+   * Per-vault binding (v16). Non-null = token can only authenticate against
+   * this vault. authenticateVaultRequest enforces the match before this
+   * result returns; callers downstream can read it for additional scoping
+   * (e.g. cross-vault filtering at the unified /mcp endpoint). NULL =
+   * legacy / server-wide / hub JWT — no per-vault binding. See vault#257.
+   */
+  vault_name: string | null;
 }
 
 /**
@@ -46,17 +70,11 @@ function legacyAuthResult(permission: TokenPermission): AuthResult {
     permission,
     scopes: legacyPermissionToScopes(permission),
     legacyDerived: true,
+    scoped_tags: null,
+    vault_name: null,
   };
 }
 
-/**
- * Guard: does the authenticated request carry the required scope?
- * Uses `hasScope` inheritance: admin ⊇ write ⊇ read.
- */
-export function requireScope(auth: AuthResult, required: string): boolean {
-  return hasScope(auth.scopes, required);
-}
-
 // One-shot deprecation warning tracker, keyed by token hash / legacy label so
 // we don't spam the log on every request.
 const warnedLegacyTokens = new Set<string>();
@@ -128,23 +146,59 @@ function validateKey(keys: StoredKey[], providedKey: string): StoredKey | null {
 
 /**
  * Authenticate for a specific vault.
- * Checks the vault's token DB first, then falls back to legacy YAML keys.
+ *
+ * Token shape decides the path:
+ *   - JWT-shaped (`eyJ…`) → validate against the hub's JWKS. JWT-shaped tokens
+ *     commit to JWT validation; we don't fall through to `pvt_*` lookup on
+ *     failure, since a malformed JWT was never going to be a valid local
+ *     token anyway.
+ *   - Anything else → try the vault's token DB, then legacy YAML keys.
+ *
+ * Dual-validate window: both paths are live during this release cycle so
+ * existing `pvt_*` callers continue to work. A follow-up issue retires the
+ * legacy path.
  */
-export function authenticateVaultRequest(
+export async function authenticateVaultRequest(
   req: Request,
   vaultConfig: VaultConfig,
   vaultDb?: Database,
-): { error: Response } | AuthResult {
+): Promise<{ error: Response } | AuthResult> {
   const key = extractApiKey(req);
   if (!key) {
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // JWT path: hub-issued tokens. Trust pinned to the hub origin via `iss`
+  // verification inside validateHubJwt; signature checked against hub's JWKS.
+  // Audience strict-checked against `vault.<name>` so a token stamped for
+  // one vault can't reach another.
+  if (looksLikeJwt(key)) {
+    return await authenticateHubJwt(key, { expectedAudience: `vault.${vaultConfig.name}` });
+  }
+
   // Try vault's token DB first
   if (vaultDb) {
     try {
       const resolved = resolveToken(vaultDb, key);
       if (resolved) {
+        // Per-vault binding (v16): tokens minted via /vault/<name>/tokens
+        // carry vault_name = <name>. Reject if presented at a different
+        // vault. NULL = legacy / server-wide; accept anywhere. The DB
+        // lookup itself already filters by per-vault DB scoping (resolve
+        // only succeeds if the token row lives in this vault's DB), so
+        // a mismatch here would only happen if a token row was copied
+        // across vault DBs out-of-band — defense-in-depth.
+        if (resolved.vault_name !== null && resolved.vault_name !== vaultConfig.name) {
+          return {
+            error: Response.json(
+              {
+                error: "Unauthorized",
+                message: `token is bound to vault '${resolved.vault_name}'; cannot be used against vault '${vaultConfig.name}'`,
+              },
+              { status: 403 },
+            ),
+          };
+        }
         if (resolved.legacyDerived) {
           warnLegacyOnce(`vault-token:${vaultConfig.name ?? ""}`, "vault token without scopes column");
         }
@@ -152,6 +206,8 @@ export function authenticateVaultRequest(
           permission: resolved.permission,
           scopes: resolved.scopes,
           legacyDerived: resolved.legacyDerived,
+          scoped_tags: resolved.scoped_tags,
+          vault_name: resolved.vault_name,
         };
       }
     } catch {
@@ -181,20 +237,115 @@ export function authenticateVaultRequest(
   return { error: Response.json({ error: "Unauthorized", message: "Invalid API key" }, { status: 401 }) };
 }
 
+/**
+ * Validate a JWT-shaped bearer and convert the result into an `AuthResult`.
+ * The token's scope claim becomes the granted scopes; permission is derived
+ * for back-compat with code paths that still branch on `permission` (MCP
+ * tool gating, view auth). `legacyDerived` is `false` — JWT-issued scopes
+ * are explicit, never inferred.
+ *
+ * Scope-shape policy: hub-issued tokens MUST carry resource-narrowed
+ * `vault:<name>:<verb>` scopes. Broad `vault:<verb>` scopes are rejected
+ * here — Phase B2 settled that hub tokens always name the resource. Per-
+ * vault audience enforcement happens inside `validateHubJwt` via
+ * `opts.expectedAudience`.
+ */
+async function authenticateHubJwt(
+  token: string,
+  opts: { expectedAudience: string | null },
+): Promise<{ error: Response } | AuthResult> {
+  try {
+    const claims = await validateHubJwt(token, { expectedAudience: opts.expectedAudience });
+    const broad = findBroadVaultScopes(claims.scopes);
+    if (broad.length > 0) {
+      return {
+        error: Response.json(
+          {
+            error: "Unauthorized",
+            message: `hub JWT carries broad vault scope(s): ${broad.join(" ")}. Hub-issued tokens must use resource-narrowed scopes (vault:<name>:<verb>).`,
+          },
+          { status: 401 },
+        ),
+      };
+    }
+    const permission: TokenPermission =
+      hasScope(claims.scopes, SCOPE_WRITE) || hasScope(claims.scopes, SCOPE_ADMIN)
+        ? "full"
+        : "read";
+    return { permission, scopes: claims.scopes, legacyDerived: false, scoped_tags: null, vault_name: null };
+  } catch (err) {
+    if (err instanceof HubJwtError) {
+      // Revocation-related codes get sanitized client messages: server-side
+      // audit log carries the full diagnostic (jti for `revoked`,
+      // implementation-detail phrasing for `revocation_unavailable`); the
+      // unauthenticated caller gets a code-shaped sentence with no internals.
+      // This is the inheritable pattern across vault/scribe/agent — keep all
+      // revocation-related diagnostics server-side. Other HubJwtError codes
+      // (signature, audience, expired, etc.) carry generic messages and are
+      // forwarded as-is; the existing test suite pins those exact strings.
+      if (err.code === "revoked") {
+        console.warn(`[auth] hub JWT rejected: ${err.message}`);
+        return {
+          error: Response.json(
+            { error: "Unauthorized", message: "token has been revoked" },
+            { status: 401 },
+          ),
+        };
+      }
+      if (err.code === "revocation_unavailable") {
+        console.warn(`[auth] hub JWT rejected: ${err.message}`);
+        return {
+          error: Response.json(
+            {
+              error: "Unauthorized",
+              message: "token cannot be validated: revocation list unavailable",
+            },
+            { status: 401 },
+          ),
+        };
+      }
+      return { error: Response.json({ error: "Unauthorized", message: err.message }, { status: 401 }) };
+    }
+    // Unknown failure shape — surface the message but stay 401.
+    const msg = err instanceof Error ? err.message : "JWT validation failed";
+    return { error: Response.json({ error: "Unauthorized", message: msg }, { status: 401 }) };
+  }
+}
+
 /**
  * Authenticate for the unified /mcp endpoint.
  * Checks legacy global config.yaml keys first, then falls back to checking
  * each vault's token DB. This allows OAuth-minted pvt_ tokens to work on
  * the unified endpoint.
  */
-export function authenticateGlobalRequest(
+export async function authenticateGlobalRequest(
   req: Request,
-): { error: Response } | AuthResult {
+): Promise<{ error: Response } | AuthResult> {
   const key = extractApiKey(req);
   if (!key) {
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Hub-issued JWTs are always vault-bound (aud=vault.<name>). The unified
+  // /vaults / /health surface spans every vault and has no single audience to
+  // strict-check against, so JWTs aren't accepted here. Cross-vault listing
+  // for hub-authenticated callers will land alongside the `parachute:host:*`
+  // scope namespace; until then, callers wanting `/vaults` from a JWT
+  // context use a per-vault token at `/vault/<name>` and rely on services.json
+  // for the broader catalog.
+  if (looksLikeJwt(key)) {
+    return {
+      error: Response.json(
+        {
+          error: "Unauthorized",
+          message:
+            "Hub-issued JWTs are vault-bound; use /vault/<name>/* endpoints. Cross-vault routes accept legacy config.yaml keys or per-vault tokens.",
+        },
+        { status: 401 },
+      ),
+    };
+  }
+
   // Legacy: check global keys from config.yaml
   const globalConfig = readGlobalConfig();
   if (globalConfig.api_keys) {
@@ -208,7 +359,12 @@ export function authenticateGlobalRequest(
 
   // Fall through to vault token DBs — check each vault for the token.
   // This enables OAuth-minted pvt_ tokens and CLI-created tokens to
-  // authenticate against the unified /mcp endpoint.
+  // authenticate against the unified /mcp endpoint. The token's vault
+  // binding (if any) is propagated via AuthResult.vault_name; downstream
+  // handlers that operate on a specific vault are responsible for
+  // checking that binding matches their target. The unified surface
+  // itself doesn't reject here — a vault-bound token authenticating to
+  // call back into its own vault via /mcp is legitimate.
   for (const vaultName of listVaults()) {
     try {
       const store = getVaultStore(vaultName);
@@ -221,6 +377,8 @@ export function authenticateGlobalRequest(
           permission: resolved.permission,
           scopes: resolved.scopes,
           legacyDerived: resolved.legacyDerived,
+          scoped_tags: resolved.scoped_tags,
+          vault_name: resolved.vault_name,
         };
       }
     } catch {

package/src/backup.ts

@@ -97,7 +97,7 @@ export function backupFilename(timestamp: string): string {
 export function parseBackupFilename(name: string): { timestamp: string } | null {
   const m = name.match(/^parachute-backup-(.+)\.tar\.gz$/);
   if (!m) return null;
-  return { timestamp: m[1] };
+  return { timestamp: m[1]! };
 }
 
 // ---------------------------------------------------------------------------
@@ -298,13 +298,10 @@ async function writeToDestination(
       const pruned = pruneRetention(target, retention);
       return { destination: dest, writtenPath: out, pruned };
     }
-    // Exhaustiveness guard — if a future destination kind is added to the
-    // type union but not handled here, the compiler fails the build.
-    default: {
-      const _exhaustive: never = dest;
-      throw new Error(`Unsupported destination kind: ${JSON.stringify(_exhaustive)}`);
-    }
   }
+  // Unreachable while BackupDestination only has "local"; once a second
+  // kind is added, restore an exhaustiveness `never` check here.
+  throw new Error(`Unsupported destination kind: ${JSON.stringify(dest)}`);
 }
 
 // ---------------------------------------------------------------------------