@openparachute/vault 0.4.5 → 0.4.6

package/src/auth.ts

@@ -20,6 +20,7 @@ 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,
@@ -30,8 +31,69 @@ import {
   SCOPE_READ,
   SCOPE_WRITE,
 } from "./scopes.ts";
+import { enforceVaultScope } from "@openparachute/scope-guard";
 import { HubJwtError, looksLikeJwt, validateHubJwt } from "./hub-jwt.ts";
 
+/**
+ * Server-wide operator bearer token, sourced from the `VAULT_AUTH_TOKEN`
+ * environment variable.
+ *
+ * Read dynamically per request (not cached at import time) so test seams
+ * that mutate `process.env.VAULT_AUTH_TOKEN` work without re-importing.
+ * In production the env var is set at container start and doesn't change.
+ *
+ * Empty / whitespace-only values are treated as unset — the operator
+ * either commits to bearer auth or doesn't, no degraded "empty token
+ * always matches" failure mode.
+ */
+function getServerWideAuthToken(env: NodeJS.ProcessEnv = process.env): string | null {
+  const raw = env.VAULT_AUTH_TOKEN;
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+/**
+ * Constant-time string equality. Returns false when lengths differ
+ * (timingSafeEqual throws on length mismatch; we want a quiet false).
+ */
+function constantTimeEquals(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return crypto.timingSafeEqual(aBuf, bBuf);
+}
+
+/**
+ * If `VAULT_AUTH_TOKEN` is set and the provided bearer matches it
+ * (constant-time), return a full-admin AuthResult that's accepted by
+ * every vault on the server.
+ *
+ * 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.
+ *
+ * Scope set is broad (`vault:admin`) — the env-var bearer is an
+ * operator credential, not a user credential. Tag-scoping doesn't
+ * apply; we represent it as unscoped (`scoped_tags: null`).
+ */
+function tryServerWideAuth(
+  providedKey: string,
+  env: NodeJS.ProcessEnv = process.env,
+): AuthResult | null {
+  const configured = getServerWideAuthToken(env);
+  if (configured === null) return null;
+  if (!constantTimeEquals(providedKey, configured)) return null;
+  return {
+    permission: "full",
+    scopes: [SCOPE_ADMIN, SCOPE_WRITE, SCOPE_READ],
+    legacyDerived: false,
+    scoped_tags: null,
+    vault_name: null,
+  };
+}
+
 /** Result of a successful auth check. */
 export interface AuthResult {
   permission: TokenPermission;
@@ -168,12 +230,27 @@ export async function authenticateVaultRequest(
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Server-wide operator token (vault#339). When VAULT_AUTH_TOKEN is set,
+  // 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.
+  const serverWide = tryServerWideAuth(key);
+  if (serverWide !== null) return serverWide;
+
   // 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.
+  // one vault can't reach another. `vault_scope` claim additionally checked
+  // against `vaultConfig.name` so a per-user vault pin refuses cross-vault
+  // access even if a scope-string somehow named the wrong vault (multi-user
+  // Phase 1 defense-in-depth — see hub#283 + scope-guard 0.3.0).
   if (looksLikeJwt(key)) {
-    return await authenticateHubJwt(key, { expectedAudience: `vault.${vaultConfig.name}` });
+    return await authenticateHubJwt(key, {
+      expectedAudience: `vault.${vaultConfig.name}`,
+      vaultName: vaultConfig.name,
+    });
   }
 
   // Try vault's token DB first
@@ -249,10 +326,20 @@ export async function authenticateVaultRequest(
  * here — Phase B2 settled that hub tokens always name the resource. Per-
  * vault audience enforcement happens inside `validateHubJwt` via
  * `opts.expectedAudience`.
+ *
+ * Per-user vault-pin enforcement (multi-user Phase 1 PR 5): when
+ * `opts.vaultName` is set, the token's `vault_scope` claim is checked
+ * against it via scope-guard's `enforceVaultScope`. Non-admin tokens
+ * (`vault_scope: [<assigned_vault>]`) refuse cross-vault access with a
+ * 403 + `vault_scope_mismatch` error code. Admin tokens (`vault_scope:
+ * []`) and pre-PR-4 tokens (claim absent → surfaced as `[]`) pass
+ * 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.
  */
 async function authenticateHubJwt(
   token: string,
-  opts: { expectedAudience: string | null },
+  opts: { expectedAudience: string | null; vaultName?: string },
 ): Promise<{ error: Response } | AuthResult> {
   try {
     const claims = await validateHubJwt(token, { expectedAudience: opts.expectedAudience });
@@ -268,6 +355,43 @@ async function authenticateHubJwt(
         ),
       };
     }
+    // Defense-in-depth vault-pin check (multi-user Phase 1 PR 5). Runs
+    // AFTER the broad-scope check — a malformed token gets the more-
+    // descriptive scope-shape error rather than a generic pin-mismatch.
+    // When `vaultName` is unset (no per-vault binding known at this
+    // call site), the check is skipped — the audience strict-check
+    // inside validateHubJwt is the primary pin in that case.
+    if (opts.vaultName !== undefined && !enforceVaultScope(claims, opts.vaultName)) {
+      // Invariant: by the contract of `enforceVaultScope`, the false
+      // branch requires `claims.vaultScope.length > 0` — an empty
+      // `vaultScope` always returns true. The defensive assertion
+      // pins that so a future refactor can't slip an empty-scope
+      // request into this branch (which would render an empty
+      // parenthesised list in the message and break the diagnostic).
+      // Body shape: client gets `required_vault` + a message naming
+      // the conflict. The token's pinned vault is intentionally NOT
+      // echoed back — the attacker holds the token (and can decode
+      // claims locally), so the message would only leak the pin to a
+      // legitimate operator looking at a 403 log line. They already
+      // know which user they assigned where; the required_vault is
+      // the actionable piece.
+      if (claims.vaultScope.length === 0) {
+        throw new Error(
+          "unreachable: enforceVaultScope returned false on an empty vaultScope",
+        );
+      }
+      return {
+        error: Response.json(
+          {
+            error: "Forbidden",
+            error_type: "vault_scope_mismatch",
+            message: `token's vault_scope (${claims.vaultScope.join(", ")}) does not include the requested vault '${opts.vaultName}'`,
+            required_vault: opts.vaultName,
+          },
+          { status: 403 },
+        ),
+      };
+    }
     const permission: TokenPermission =
       hasScope(claims.scopes, SCOPE_WRITE) || hasScope(claims.scopes, SCOPE_ADMIN)
         ? "full"
@@ -326,6 +450,14 @@ export async function authenticateGlobalRequest(
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Server-wide operator token (vault#339). When VAULT_AUTH_TOKEN is set,
+  // a matching bearer authenticates as full/admin on cross-vault routes
+  // (/vaults metadata listing, /health detail). Checked first so a
+  // container-host operator-channel call doesn't depend on any per-vault
+  // DB lookup.
+  const serverWide = tryServerWideAuth(key);
+  if (serverWide !== null) return serverWide;
+
   // 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