@openparachute/vault 0.4.9-rc.9 → 0.5.0-rc.2

package/src/auth.ts

@@ -1,27 +1,30 @@
 /**
  * Authentication and authorization for the vault server.
  *
- * Token-based auth with two permission levels:
- *   - "full" — unrestricted access (CRUD + delete + token management)
- *   - "read" — read-only (query, list, find-path, vault-info)
+ * As of 0.5.0 vault is a PURE HUB RESOURCE-SERVER (vault#282 Stage 2). The
+ * opaque `pvt_*` vault-DB token was dropped — vault no longer mints or
+ * validates it. Three auth paths survive:
  *
- * Tokens live in each vault's SQLite database (tokens table, schema v7).
+ *   1. Hub-issued JWT — the user-credential path. JWT-shaped bearers are
+ *      validated against the hub's JWKS (`authenticateHubJwt` → hub-jwt.ts →
+ *      scope-guard), audience-pinned to `vault.<name>`, scope-narrowed.
+ *   2. VAULT_AUTH_TOKEN — the server-wide operator bearer (env var,
+ *      constant-time compare). Short-circuits both auth entry points.
+ *   3. Legacy YAML api_keys — hashed keys in vault.yaml / config.yaml. A
+ *      separate deprecation axis from pvt_*; still validated here.
  *
- * Backward compatibility: config.yaml API keys are still checked as a fallback.
- * Those keys resolve as full-access tokens. Legacy "admin" and "write" values
- * in the DB are normalized to "full" at read time.
+ * Permission levels remain "full" / "read"; legacy "admin"/"write" DB values
+ * normalize to "full" at read time.
  *
- * The unified /mcp endpoint uses only legacy global config.yaml keys, since
- * tokens are per-vault and the unified endpoint spans all vaults.
+ * The unified /mcp endpoint accepts only VAULT_AUTH_TOKEN + global config.yaml
+ * keys — hub JWTs are vault-bound (aud=vault.<name>) and have no single
+ * audience to strict-check on the cross-vault surface.
  */
 
-import { readGlobalConfig, writeVaultConfig, writeGlobalConfig, verifyKey, listVaults, readVaultConfig } from "./config.ts";
+import { readGlobalConfig, writeVaultConfig, writeGlobalConfig, verifyKey } from "./config.ts";
 import type { VaultConfig, StoredKey } from "./config.ts";
-import { resolveToken } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
-import type { Database } from "bun:sqlite";
 import crypto from "node:crypto";
-import { getVaultStore } from "./vault-store.ts";
 import {
   findBroadVaultScopes,
   hasScope,
@@ -71,8 +74,8 @@ function constantTimeEquals(a: string, b: string): boolean {
  *
  * The operator-channel auth shape for non-loopback deploys (Render,
  * sibling-container setups, vault#339). Hub uses this to call vault
- * across a container boundary; end-user OAuth tokens still take the
- * per-vault hub-JWT / pvt_* paths below. See `docs/auth-model.md` §2.
+ * across a container boundary; end-user OAuth tokens take the per-vault
+ * hub-JWT path below. See `docs/auth-model.md` §2.
  *
  * Scope set is broad (`vault:admin`) — the env-var bearer is an
  * operator credential, not a user credential. Tag-scoping doesn't
@@ -127,12 +130,11 @@ export interface AuthResult {
    */
   vault_name: string | null;
   /**
-   * Session identifier (v19). For `pvt_*` tokens this is the display id
-   * (`t_<hashprefix>`) of the presented token. For hub JWTs it's the
-   * `jti` claim, when present. NULL for legacy YAML keys / server-wide
-   * env-var tokens / hub JWTs without a `jti`. Used by the manage-token
-   * MCP tool to stamp child tokens with `parent_jti` so list/revoke can
-   * scope to this session's mints. See vault#376.
+   * Session identifier. For hub JWTs this is the `jti` claim, when present.
+   * NULL for legacy YAML keys / server-wide env-var tokens / hub JWTs
+   * without a `jti`. Used by the manage-token MCP tool to stamp child
+   * mints with `parent_jti` so list/revoke can scope to this session's
+   * mints. See vault#376.
    */
   caller_jti: string | null;
 }
@@ -225,21 +227,19 @@ function validateKey(keys: StoredKey[], providedKey: string): StoredKey | null {
 /**
  * Authenticate for a specific vault.
  *
- * Token shape decides the path:
+ * Token shape decides the path (vault#282 Stage 2 — vault is a pure hub
+ * resource-server, the `pvt_*` vault-DB lookup is GONE):
+ *   - VAULT_AUTH_TOKEN match → server-wide operator bearer (checked first).
  *   - 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.
+ *     commit to JWT validation; we don't fall through on failure, since a
+ *     malformed JWT was never going to be a valid local credential anyway.
+ *   - Anything else → legacy YAML api_keys (vault.yaml, then config.yaml).
+ *     A `pvt_*`-prefixed bearer is not JWT-shaped and matches no `key_hash`,
+ *     so it falls through to the 401 — pvt_* is unvalidatable post-DROP.
  */
 export async function authenticateVaultRequest(
   req: Request,
   vaultConfig: VaultConfig,
-  vaultDb?: Database,
 ): Promise<{ error: Response } | AuthResult> {
   const key = extractApiKey(req);
   if (!key) {
@@ -250,8 +250,8 @@ export async function authenticateVaultRequest(
   // a matching bearer authenticates as full/admin against any vault. This
   // is the cross-container path for Render / sibling-service deployments
   // where hub talks to vault over HTTP. Checked first so it short-circuits
-  // both JWT validation and per-vault DB lookups — the operator token is
-  // a credential the operator opts into, not one we'd ever fall through.
+  // JWT validation — the operator token is a credential the operator opts
+  // into, not one we'd ever fall through.
   const serverWide = tryServerWideAuth(key);
   if (serverWide !== null) return serverWide;
 
@@ -269,46 +269,6 @@ export async function authenticateVaultRequest(
     });
   }
 
-  // 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");
-        }
-        return {
-          permission: resolved.permission,
-          scopes: resolved.scopes,
-          legacyDerived: resolved.legacyDerived,
-          scoped_tags: resolved.scoped_tags,
-          vault_name: resolved.vault_name,
-          caller_jti: resolved.jti,
-        };
-      }
-    } catch {
-      // Token table might not exist yet — fall through to legacy auth
-    }
-  }
-
   // Legacy: check per-vault keys from vault.yaml
   const vaultKey = validateKey(vaultConfig.api_keys, key);
   if (vaultKey) {
@@ -328,9 +288,102 @@ export async function authenticateVaultRequest(
     }
   }
 
+  if (looksLikeDroppedPvtToken(key)) {
+    return { error: droppedPvtTokenResponse() };
+  }
   return { error: Response.json({ error: "Unauthorized", message: "Invalid API key" }, { status: 401 }) };
 }
 
+/**
+ * A bearer of the dropped `pvt_*` shape (vault#282 Stage 2 — vault no longer
+ * mints or validates the per-vault opaque token). Detected by prefix so a
+ * caller still presenting one gets a pointed 401 instead of the generic
+ * "Invalid API key" — the prefix is the user-meaningful signal, and a real
+ * hub JWT / `pvk_` / `VAULT_AUTH_TOKEN` never starts with `pvt_`.
+ */
+function looksLikeDroppedPvtToken(key: string): boolean {
+  return key.startsWith("pvt_");
+}
+
+function droppedPvtTokenResponse(): Response {
+  return Response.json(
+    {
+      error: "Unauthorized",
+      message:
+        "pvt_* tokens are no longer supported (vault 0.5.0). Re-add this vault via your hub to get an access token.",
+    },
+    { status: 401 },
+  );
+}
+
+/**
+ * Sentinel thrown when a hub JWT carries a `permissions.scoped_tags` claim
+ * that is present but malformed (not an array of non-empty strings). See
+ * `parseScopedTagsFromPermissions` for why this MUST fail closed.
+ */
+class MalformedScopedTagsError extends Error {}
+
+/**
+ * Map a validated hub JWT's `permissions` claim into the `scoped_tags`
+ * allowlist for `AuthResult` (auth-unification arc, C0 — the READ side).
+ *
+ * Wire contract (the shape the SPA + manage-token mint sides target):
+ *
+ *   permissions: { scoped_tags: string[] }   // root tag names
+ *
+ * Each entry is a ROOT tag name; the token sees notes carrying that tag or a
+ * sub-tag thereof (hierarchy expansion happens in tag-scope.ts).
+ *
+ * Three outcomes, chosen for a strict FAIL-CLOSED invariant — tag-scoping is
+ * always a RESTRICTION, so a misread must NEVER widen access:
+ *
+ *   1. Claim absent (no `permissions`, or no `scoped_tags` key) → returns
+ *      `null` = UNSCOPED = full vault. This is legitimate and is today's
+ *      behavior for every hub JWT. Absence genuinely means "not tag-scoped".
+ *
+ *   2. `scoped_tags` is a non-empty array of non-empty strings → returns
+ *      that array. The token is tag-scoped; the allowlist is enforced.
+ *
+ *   3. `scoped_tags` is present but MALFORMED — a string, a number, an
+ *      object, an array containing a non-string / empty-string, or an empty
+ *      array `[]` — throws `MalformedScopedTagsError`. The caller REJECTS
+ *      the request (401). We do NOT coerce to `null` or `[]`:
+ *
+ *      - Coercing to `null` would WIDEN a token that was MEANT to be scoped
+ *        up to full-vault — a privilege leak. Forbidden.
+ *      - Coercing to `[]` is NOT reliably fail-closed across enforcement
+ *        paths. The MCP read-tool wrappers fast-path out on
+ *        `scoped_tags.length === 0` (mcp-tools.ts ~L178) and the REST path
+ *        collapses `[]` → null inside `expandTokenTagScope` (tag-scope.ts
+ *        ~L35) — both treat `[]` as UNSCOPED = full vault. So `[]` would
+ *        ALSO widen. (Note: `filterNotesByTagScope`/`noteWithinTagScope`
+ *        would treat a raw `[]` as "matches nothing", but the call sites
+ *        never reach them with `[]` because of the upstream short-circuits —
+ *        the two enforcement paths disagree on `[]`, which is exactly why we
+ *        refuse to manufacture it here.)
+ *
+ *      The only correct fail-closed action for a present-but-unreadable
+ *      scope is to reject the whole request — never serve it wide.
+ */
+function parseScopedTagsFromPermissions(
+  permissions: Record<string, unknown> | undefined,
+): string[] | null {
+  if (!permissions || !("scoped_tags" in permissions)) return null;
+  const raw = permissions.scoped_tags;
+  if (raw === null || raw === undefined) return null; // explicit "unscoped"
+  if (
+    Array.isArray(raw) &&
+    raw.length > 0 &&
+    raw.every((t) => typeof t === "string" && t.length > 0)
+  ) {
+    return raw as string[];
+  }
+  // Present but malformed (incl. `[]`): fail closed — never widen.
+  throw new MalformedScopedTagsError(
+    "hub JWT permissions.scoped_tags is present but not a non-empty array of tag names",
+  );
+}
+
 /**
  * Validate a JWT-shaped bearer and convert the result into an `AuthResult`.
  * The token's scope claim becomes the granted scopes; permission is derived
@@ -353,6 +406,12 @@ export async function authenticateVaultRequest(
  * unchanged. The 403 (not 401) signals "your credential is valid but
  * doesn't grant access to this vault" — distinct from authentication
  * failures upstream. See hub#283 + scope-guard 0.3.0 for the mint side.
+ *
+ * Tag-scoping (auth-unification arc, C0): the token's `permissions.scoped_tags`
+ * claim (when present and well-formed) maps into `AuthResult.scoped_tags`,
+ * restricting which notes the token sees. A present-but-malformed claim FAILS
+ * CLOSED with a 401 rather than widening to full-vault — see
+ * `parseScopedTagsFromPermissions`.
  */
 async function authenticateHubJwt(
   token: string,
@@ -413,11 +472,15 @@ async function authenticateHubJwt(
       hasScope(claims.scopes, SCOPE_WRITE) || hasScope(claims.scopes, SCOPE_ADMIN)
         ? "full"
         : "read";
+    // C0: read tag-scoping from the validated token's `permissions` claim.
+    // Throws MalformedScopedTagsError (caught below → 401) on a present-but-
+    // malformed claim so we never widen access on a misread.
+    const scoped_tags = parseScopedTagsFromPermissions(claims.permissions);
     return {
       permission,
       scopes: claims.scopes,
       legacyDerived: false,
-      scoped_tags: null,
+      scoped_tags,
       vault_name: null,
       // claims.jti is `undefined` when the issuer didn't stamp one. Pass it
       // through verbatim — manage-token's session-pin will be null in that
@@ -425,6 +488,19 @@ async function authenticateHubJwt(
       caller_jti: claims.jti ?? null,
     };
   } catch (err) {
+    if (err instanceof MalformedScopedTagsError) {
+      // Fail-closed (C0): a present-but-malformed `permissions.scoped_tags`
+      // means the token wanted to be tag-scoped but we can't read the
+      // allowlist. Reject rather than widen to full-vault. The audit log
+      // carries the diagnostic; the client gets a generic 401.
+      console.warn(`[auth] hub JWT rejected: ${err.message}`);
+      return {
+        error: Response.json(
+          { error: "Unauthorized", message: "token has a malformed tag-scope claim" },
+          { status: 401 },
+        ),
+      };
+    }
     if (err instanceof HubJwtError) {
       // Revocation-related codes get sanitized client messages: server-side
       // audit log carries the full diagnostic (jti for `revoked`,
@@ -464,10 +540,12 @@ async function authenticateHubJwt(
 }
 
 /**
- * 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.
+ * Authenticate for the unified /mcp endpoint (cross-vault: /vaults metadata,
+ * /health detail). Accepts only VAULT_AUTH_TOKEN + global config.yaml keys
+ * (vault#282 Stage 2 — the per-vault pvt_* DB fallback is GONE). Hub JWTs are
+ * vault-bound (aud=vault.<name>) and have no single audience to strict-check
+ * across every vault, so they're rejected here with a redirect hint to the
+ * per-vault `/vault/<name>/*` surface.
  */
 export async function authenticateGlobalRequest(
   req: Request,
@@ -516,35 +594,8 @@ export async 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. 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);
-      const resolved = resolveToken(store.db, key);
-      if (resolved) {
-        if (resolved.legacyDerived) {
-          warnLegacyOnce(`vault-token:${vaultName}`, "vault token without scopes column");
-        }
-        return {
-          permission: resolved.permission,
-          scopes: resolved.scopes,
-          legacyDerived: resolved.legacyDerived,
-          scoped_tags: resolved.scoped_tags,
-          vault_name: resolved.vault_name,
-          caller_jti: resolved.jti,
-        };
-      }
-    } catch {
-      // Skip vaults that can't be opened
-    }
+  if (looksLikeDroppedPvtToken(key)) {
+    return { error: droppedPvtTokenResponse() };
   }
-
   return { error: Response.json({ error: "Unauthorized", message: "Invalid API key" }, { status: 401 }) };
 }