@openparachute/vault 0.2.4 → 0.3.0

package/src/scopes.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Unit tests for scope primitives — parse, match, inheritance, legacy
+ * permission fallback. Integration tests for scope enforcement at the
+ * HTTP boundary live in routing.test.ts + vault.test.ts.
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  SCOPE_READ,
+  SCOPE_WRITE,
+  SCOPE_ADMIN,
+  parseScopes,
+  parseScopeFlags,
+  resolveCreateTokenFlags,
+  hasScope,
+  scopeForMethod,
+  legacyPermissionToScopes,
+  serializeScopes,
+} from "./scopes.ts";
+
+describe("parseScopes", () => {
+  test("returns [] for null or empty input", () => {
+    expect(parseScopes(null)).toEqual([]);
+    expect(parseScopes(undefined)).toEqual([]);
+    expect(parseScopes("")).toEqual([]);
+    expect(parseScopes("   ")).toEqual([]);
+  });
+
+  test("splits on whitespace and trims", () => {
+    expect(parseScopes("vault:read vault:write")).toEqual([SCOPE_READ, SCOPE_WRITE]);
+    expect(parseScopes("  vault:read   vault:write  ")).toEqual([SCOPE_READ, SCOPE_WRITE]);
+    expect(parseScopes("vault:read\tvault:write\nvault:admin")).toEqual([
+      SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN,
+    ]);
+  });
+
+  test("collapses vault:<name>:<verb> synonym to vault:<verb>", () => {
+    expect(parseScopes("vault:journal:read")).toEqual([SCOPE_READ]);
+    expect(parseScopes("vault:journal:write vault:work:admin")).toEqual([
+      SCOPE_WRITE, SCOPE_ADMIN,
+    ]);
+  });
+
+  test("preserves unrecognized scopes verbatim", () => {
+    expect(parseScopes("profile email")).toEqual(["profile", "email"]);
+    expect(parseScopes("vault:unknown:frob")).toEqual(["vault:unknown:frob"]);
+  });
+
+  test("empty name segment does NOT collapse (vault::read stays literal)", () => {
+    // Guard against a hand-crafted DB row with `vault::read` satisfying a
+    // `vault:read` check by accident. Only reachable via direct DB write,
+    // not API input, but the parser stays honest.
+    expect(parseScopes("vault::read")).toEqual(["vault::read"]);
+    expect(hasScope(parseScopes("vault::read"), SCOPE_READ)).toBe(false);
+  });
+});
+
+describe("hasScope — inheritance admin ⊇ write ⊇ read", () => {
+  test("exact match succeeds", () => {
+    expect(hasScope([SCOPE_READ], SCOPE_READ)).toBe(true);
+    expect(hasScope([SCOPE_WRITE], SCOPE_WRITE)).toBe(true);
+    expect(hasScope([SCOPE_ADMIN], SCOPE_ADMIN)).toBe(true);
+  });
+
+  test("vault:write satisfies vault:read", () => {
+    expect(hasScope([SCOPE_WRITE], SCOPE_READ)).toBe(true);
+  });
+
+  test("vault:admin satisfies vault:read and vault:write", () => {
+    expect(hasScope([SCOPE_ADMIN], SCOPE_READ)).toBe(true);
+    expect(hasScope([SCOPE_ADMIN], SCOPE_WRITE)).toBe(true);
+  });
+
+  test("vault:read does NOT satisfy vault:write or vault:admin", () => {
+    expect(hasScope([SCOPE_READ], SCOPE_WRITE)).toBe(false);
+    expect(hasScope([SCOPE_READ], SCOPE_ADMIN)).toBe(false);
+  });
+
+  test("vault:write does NOT satisfy vault:admin", () => {
+    expect(hasScope([SCOPE_WRITE], SCOPE_ADMIN)).toBe(false);
+  });
+
+  test("empty granted list fails", () => {
+    expect(hasScope([], SCOPE_READ)).toBe(false);
+    expect(hasScope([], SCOPE_WRITE)).toBe(false);
+    expect(hasScope([], SCOPE_ADMIN)).toBe(false);
+  });
+
+  test("non-vault scopes require exact match — no inheritance", () => {
+    expect(hasScope(["profile"], "profile")).toBe(true);
+    expect(hasScope(["profile"], "email")).toBe(false);
+    expect(hasScope([SCOPE_ADMIN], "profile")).toBe(false);
+  });
+});
+
+describe("scopeForMethod", () => {
+  test("read methods → vault:read", () => {
+    expect(scopeForMethod("GET")).toBe(SCOPE_READ);
+    expect(scopeForMethod("HEAD")).toBe(SCOPE_READ);
+    expect(scopeForMethod("OPTIONS")).toBe(SCOPE_READ);
+    expect(scopeForMethod("get")).toBe(SCOPE_READ); // case-insensitive
+  });
+
+  test("write methods → vault:write", () => {
+    expect(scopeForMethod("POST")).toBe(SCOPE_WRITE);
+    expect(scopeForMethod("PATCH")).toBe(SCOPE_WRITE);
+    expect(scopeForMethod("PUT")).toBe(SCOPE_WRITE);
+    expect(scopeForMethod("DELETE")).toBe(SCOPE_WRITE);
+  });
+
+  test("unknown method falls back to vault:write (default-deny)", () => {
+    expect(scopeForMethod("TRACE")).toBe(SCOPE_WRITE);
+  });
+});
+
+describe("legacyPermissionToScopes", () => {
+  test("'read' → [vault:read]", () => {
+    expect(legacyPermissionToScopes("read")).toEqual([SCOPE_READ]);
+  });
+
+  test("'full' and anything else → [read, write, admin]", () => {
+    expect(legacyPermissionToScopes("full")).toEqual([SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN]);
+    expect(legacyPermissionToScopes("admin")).toEqual([SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN]);
+    expect(legacyPermissionToScopes("write")).toEqual([SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN]);
+  });
+});
+
+describe("parseScopeFlags", () => {
+  test("returns null scopes when --scope is absent", () => {
+    expect(parseScopeFlags([])).toEqual({ scopes: null, error: null });
+    expect(parseScopeFlags(["--vault", "default", "--label", "x"]))
+      .toEqual({ scopes: null, error: null });
+  });
+
+  test("single --scope with one value", () => {
+    expect(parseScopeFlags(["--scope", "vault:read"]))
+      .toEqual({ scopes: [SCOPE_READ], error: null });
+  });
+
+  test("single --scope with comma-separated values", () => {
+    expect(parseScopeFlags(["--scope", "vault:read,vault:write"]))
+      .toEqual({ scopes: [SCOPE_READ, SCOPE_WRITE], error: null });
+  });
+
+  test("repeated --scope flags", () => {
+    expect(parseScopeFlags(["--scope", "vault:read", "--scope", "vault:write"]))
+      .toEqual({ scopes: [SCOPE_READ, SCOPE_WRITE], error: null });
+  });
+
+  test("dedupes while preserving first-occurrence order", () => {
+    expect(parseScopeFlags(["--scope", "vault:write,vault:read,vault:write"]))
+      .toEqual({ scopes: [SCOPE_WRITE, SCOPE_READ], error: null });
+  });
+
+  test("trims whitespace around each scope", () => {
+    expect(parseScopeFlags(["--scope", "  vault:read ,  vault:write  "]))
+      .toEqual({ scopes: [SCOPE_READ, SCOPE_WRITE], error: null });
+  });
+
+  test("rejects unknown scopes with a helpful error", () => {
+    const result = parseScopeFlags(["--scope", "vault:frob"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("Unknown scope");
+    expect(result.error).toContain("vault:frob");
+    expect(result.error).toContain("vault:read, vault:write, vault:admin");
+  });
+
+  test("rejects a mixed list with one invalid scope", () => {
+    const result = parseScopeFlags(["--scope", "vault:read,admin"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("admin");
+  });
+
+  test("rejects --scope with no value (end of argv)", () => {
+    const result = parseScopeFlags(["--scope"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("--scope requires a value");
+  });
+
+  test("rejects --scope followed by another flag", () => {
+    const result = parseScopeFlags(["--scope", "--label", "x"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("--scope requires a value");
+  });
+
+  test("rejects --scope with an empty value", () => {
+    const result = parseScopeFlags(["--scope", ""]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("empty");
+  });
+
+  test("rejects --scope with only commas", () => {
+    const result = parseScopeFlags(["--scope", ",,"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("empty");
+  });
+});
+
+describe("resolveCreateTokenFlags", () => {
+  test("no flags → full scope, full permission (historical default)", () => {
+    expect(resolveCreateTokenFlags([]))
+      .toEqual({ scopes: undefined, permission: "full", error: null });
+  });
+
+  test("--read alone → [vault:read], read permission", () => {
+    expect(resolveCreateTokenFlags(["--read"]))
+      .toEqual({ scopes: [SCOPE_READ], permission: "read", error: null });
+  });
+
+  test("--scope vault:read alone → read permission", () => {
+    expect(resolveCreateTokenFlags(["--scope", "vault:read"]))
+      .toEqual({ scopes: [SCOPE_READ], permission: "read", error: null });
+  });
+
+  test("--scope vault:write,vault:read → full permission (any write surface → full)", () => {
+    expect(resolveCreateTokenFlags(["--scope", "vault:write,vault:read"]))
+      .toEqual({ scopes: [SCOPE_WRITE, SCOPE_READ], permission: "full", error: null });
+  });
+
+  test("--scope vault:admin alone → full permission", () => {
+    expect(resolveCreateTokenFlags(["--scope", "vault:admin"]))
+      .toEqual({ scopes: [SCOPE_ADMIN], permission: "full", error: null });
+  });
+
+  test("--permission read → no scopes (token-store default), read permission", () => {
+    expect(resolveCreateTokenFlags(["--permission", "read"]))
+      .toEqual({ scopes: undefined, permission: "read", error: null });
+  });
+
+  test("--permission full → no scopes, full permission", () => {
+    expect(resolveCreateTokenFlags(["--permission", "full"]))
+      .toEqual({ scopes: undefined, permission: "full", error: null });
+  });
+
+  test("--scope + --read errors and mentions both flags", () => {
+    const result = resolveCreateTokenFlags(["--scope", "vault:write", "--read"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("--scope");
+    expect(result.error).toContain("--read");
+    expect(result.error).toContain("cannot be combined");
+  });
+
+  test("--scope + --permission errors", () => {
+    const result = resolveCreateTokenFlags(["--scope", "vault:read", "--permission", "full"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("--scope");
+    expect(result.error).toContain("--permission");
+    expect(result.error).toContain("cannot be combined");
+  });
+
+  test("--read + --permission errors", () => {
+    const result = resolveCreateTokenFlags(["--read", "--permission", "full"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("--read");
+    expect(result.error).toContain("--permission");
+    expect(result.error).toContain("cannot be combined");
+  });
+
+  test("invalid --permission value errors with prefer-scope hint", () => {
+    const result = resolveCreateTokenFlags(["--permission", "admin"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("admin");
+    expect(result.error).toContain("full");
+    expect(result.error).toContain("read");
+    expect(result.error).toContain("--scope");
+  });
+
+  test("--permission with no value errors", () => {
+    expect(resolveCreateTokenFlags(["--permission"]).error).toContain("requires a value");
+    expect(resolveCreateTokenFlags(["--permission", "--label", "x"]).error).toContain("requires a value");
+  });
+
+  test("surfaces parseScopeFlags errors unchanged", () => {
+    const result = resolveCreateTokenFlags(["--scope", "vault:frob"]);
+    expect(result.error).toContain("Unknown scope");
+  });
+
+  test("ignores unrelated flags", () => {
+    const result = resolveCreateTokenFlags(["--vault", "journal", "--label", "r", "--read"]);
+    expect(result).toEqual({ scopes: [SCOPE_READ], permission: "read", error: null });
+  });
+});
+
+describe("serializeScopes — round-trips with parseScopes", () => {
+  test("joins with spaces", () => {
+    expect(serializeScopes([SCOPE_READ, SCOPE_WRITE])).toBe("vault:read vault:write");
+    expect(serializeScopes([])).toBe("");
+  });
+
+  test("serialize then parse is the identity (for known scopes)", () => {
+    const scopes = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN];
+    expect(parseScopes(serializeScopes(scopes))).toEqual(scopes);
+  });
+});

package/src/scopes.ts

@@ -0,0 +1,253 @@
+/**
+ * Scope primitives for Phase 2 enforcement.
+ *
+ * Tokens carry OAuth-standard whitespace-separated scopes. This module parses,
+ * normalizes, and matches them — including the `admin ⊇ write ⊇ read`
+ * inheritance rule and the `vault:<name>:<verb>` future-shape synonym
+ * (narrowed per-vault scopes are Phase 2+; today we treat them as equivalent
+ * to `vault:<verb>`).
+ *
+ * Legacy back-compat: tokens without any `vault:*` scope — but with a
+ * 0.2.x-era `permission = "full" | "read"` — are mapped to the appropriate
+ * scope set on the fly. `legacyPermissionToScopes` is marked deprecated and
+ * should be removed one release after enforcement lands.
+ */
+
+export const SCOPE_READ = "vault:read" as const;
+export const SCOPE_WRITE = "vault:write" as const;
+export const SCOPE_ADMIN = "vault:admin" as const;
+
+/** All first-class vault scopes in inheritance order (lowest → highest). */
+export const VAULT_SCOPES = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN] as const;
+export type VaultScope = (typeof VAULT_SCOPES)[number];
+
+/**
+ * Parse a whitespace-separated scope string into a normalized scope list.
+ *
+ * Normalization:
+ *   - Empty / null → []
+ *   - Trim + split on any whitespace
+ *   - `vault:<name>:<verb>` collapses to `vault:<verb>` (per-vault narrowing
+ *     is Phase 2+; today it's treated as a synonym)
+ *   - Unrecognized scopes are preserved as-is (they just won't match anything)
+ */
+export function parseScopes(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(/\s+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => normalizeScope(s));
+}
+
+function normalizeScope(scope: string): string {
+  // `vault:<name>:<verb>` → `vault:<verb>` (synonym collapse). Reject an empty
+  // name segment (`vault::read`) — preserve it as-is so it can't accidentally
+  // satisfy a `vault:read` check. Only reachable via direct DB write, but the
+  // one-liner keeps the parser honest.
+  const parts = scope.split(":");
+  if (parts.length === 3 && parts[0] === "vault" && parts[1].length > 0) {
+    const verb = parts[2];
+    if (verb === "read" || verb === "write" || verb === "admin") {
+      return `vault:${verb}`;
+    }
+  }
+  return scope;
+}
+
+/**
+ * Return true iff `granted` satisfies `required` under the inheritance rule
+ * `admin ⊇ write ⊇ read`. Exact-match required for non-vault scopes.
+ */
+export function hasScope(granted: string[], required: string): boolean {
+  if (granted.includes(required)) return true;
+
+  // Inheritance: admin ⊇ write ⊇ read
+  if (required === SCOPE_READ) {
+    return granted.includes(SCOPE_WRITE) || granted.includes(SCOPE_ADMIN);
+  }
+  if (required === SCOPE_WRITE) {
+    return granted.includes(SCOPE_ADMIN);
+  }
+  return false;
+}
+
+/**
+ * Pick the required scope for a given API request.
+ *   - GET/HEAD/OPTIONS → read
+ *   - POST/PATCH/PUT/DELETE → write
+ *
+ * Admin-gated endpoints (like `/.parachute/config`) don't go through this
+ * helper — they call `hasScope(auth.scopes, SCOPE_ADMIN)` directly.
+ */
+export function scopeForMethod(method: string): VaultScope {
+  const m = method.toUpperCase();
+  if (m === "GET" || m === "HEAD" || m === "OPTIONS") return SCOPE_READ;
+  return SCOPE_WRITE;
+}
+
+/**
+ * Map a 0.2.x legacy `permission` column value to scopes. Kept for back-compat
+ * during the one-release-cycle deprecation window — after that, every token
+ * row will carry an explicit `scopes` column and this can go.
+ *
+ * @deprecated Remove one release after v0.4 scope enforcement lands.
+ */
+export function legacyPermissionToScopes(permission: string): string[] {
+  // "full", "admin", "write" all historically meant unrestricted access
+  if (permission === "read") return [SCOPE_READ];
+  return [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN];
+}
+
+/** Serialize a scope list to an OAuth-standard whitespace-separated string. */
+export function serializeScopes(scopes: string[]): string {
+  return scopes.join(" ");
+}
+
+/**
+ * Parse `--scope` flag values from an argv list into a validated scope list.
+ *
+ * Accepts repeatable `--scope vault:read --scope vault:write` and
+ * comma-separated `--scope vault:read,vault:write` (and a mix of the two).
+ * Scopes are validated against `VAULT_SCOPES` — we refuse to mint a token
+ * with a scope the server has no way to enforce.
+ *
+ * Return shape: `{scopes}` is `null` when no `--scope` appears anywhere, so
+ * the caller can distinguish "flag not set" from "flag set to empty." On
+ * validation failure, `error` is a human-readable message suitable for
+ * `console.error` + `process.exit(1)`.
+ */
+export function parseScopeFlags(
+  args: string[],
+): { scopes: string[] | null; error: string | null } {
+  const validList = VAULT_SCOPES.join(", ");
+  const raw: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--scope") continue;
+    const val = args[i + 1];
+    if (val === undefined || val.startsWith("--")) {
+      return { scopes: null, error: `--scope requires a value. Valid scopes: ${validList}` };
+    }
+    raw.push(val);
+    i++;
+  }
+  if (raw.length === 0) return { scopes: null, error: null };
+
+  const expanded = raw
+    .flatMap((v) => v.split(","))
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (expanded.length === 0) {
+    return { scopes: null, error: `--scope value was empty. Valid scopes: ${validList}` };
+  }
+
+  const validSet = new Set<string>(VAULT_SCOPES);
+  const invalid = expanded.filter((s) => !validSet.has(s));
+  if (invalid.length > 0) {
+    return {
+      scopes: null,
+      error: `Unknown scope(s): ${invalid.join(", ")}. Valid scopes: ${validList}`,
+    };
+  }
+
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const s of expanded) {
+    if (!seen.has(s)) {
+      seen.add(s);
+      deduped.push(s);
+    }
+  }
+  return { scopes: deduped, error: null };
+}
+
+/**
+ * Resolve `parachute vault tokens create` argv into a concrete scope set +
+ * legacy `permission` column value, or an actionable error.
+ *
+ * Precedence is **exclusive**: `--scope`, `--read`, and `--permission` all
+ * narrow the token, but combining them is always an error — a user who
+ * writes `--scope vault:write --read` almost certainly expects one of the
+ * two to win, and silently picking would mint the opposite of what at
+ * least one reading intended. Fail loud for anything token-minting.
+ *
+ * With no narrowing flag, falls back to a full-scope token for back-compat.
+ */
+export function resolveCreateTokenFlags(args: string[]): {
+  scopes: string[] | undefined;
+  permission: "full" | "read";
+  error: string | null;
+} {
+  const scopeResult = parseScopeFlags(args);
+  if (scopeResult.error) {
+    return { scopes: undefined, permission: "full", error: scopeResult.error };
+  }
+  const hasScopeFlag = scopeResult.scopes !== null;
+  const hasReadFlag = args.includes("--read");
+  const permIdx = args.indexOf("--permission");
+  const hasPermFlag = permIdx !== -1;
+
+  if (hasScopeFlag && hasReadFlag) {
+    return {
+      scopes: undefined,
+      permission: "full",
+      error:
+        "--scope and --read cannot be combined. Pick one:\n" +
+        "  --read                     # shorthand for --scope vault:read\n" +
+        "  --scope vault:read         # equivalent, explicit\n" +
+        "  --scope vault:write        # write scope",
+    };
+  }
+  if (hasScopeFlag && hasPermFlag) {
+    return {
+      scopes: undefined,
+      permission: "full",
+      error:
+        "--scope and --permission cannot be combined. --scope is the canonical way to narrow a token; --permission is legacy.",
+    };
+  }
+  if (hasReadFlag && hasPermFlag) {
+    return {
+      scopes: undefined,
+      permission: "full",
+      error: "--read and --permission cannot be combined. --read is a shorthand for --permission read.",
+    };
+  }
+
+  if (hasPermFlag) {
+    const rawPerm = args[permIdx + 1];
+    if (!rawPerm || rawPerm.startsWith("--")) {
+      return {
+        scopes: undefined,
+        permission: "full",
+        error: `--permission requires a value ("full" or "read"). Prefer --scope for new scripts.`,
+      };
+    }
+    if (!["full", "read"].includes(rawPerm)) {
+      return {
+        scopes: undefined,
+        permission: "full",
+        error: `Invalid --permission: ${rawPerm}. Must be "full" or "read". Prefer --scope for new scripts.`,
+      };
+    }
+  }
+
+  if (scopeResult.scopes) {
+    const scopes = scopeResult.scopes;
+    const permission: "full" | "read" =
+      scopes.includes(SCOPE_WRITE) || scopes.includes(SCOPE_ADMIN) ? "full" : "read";
+    return { scopes, permission, error: null };
+  }
+  if (hasReadFlag) {
+    return { scopes: [SCOPE_READ], permission: "read", error: null };
+  }
+  if (hasPermFlag) {
+    const rawPerm = args[permIdx + 1];
+    return {
+      scopes: undefined,
+      permission: rawPerm === "read" ? "read" : "full",
+      error: null,
+    };
+  }
+  return { scopes: undefined, permission: "full", error: null };
+}

package/src/scribe-env.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "bun:test";
+import { resolveScribeAuthToken } from "./scribe-env.ts";
+
+function captureWarn() {
+  const calls: unknown[][] = [];
+  return { logger: { warn: (...args: unknown[]) => calls.push(args) }, calls };
+}
+
+describe("resolveScribeAuthToken", () => {
+  test("returns SCRIBE_AUTH_TOKEN when set (canonical)", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken(
+      { SCRIBE_AUTH_TOKEN: "canonical-v1" } as NodeJS.ProcessEnv,
+      logger,
+    );
+    expect(token).toBe("canonical-v1");
+    // Canonical path is silent — no deprecation warning.
+    expect(calls.length).toBe(0);
+  });
+
+  test("prefers canonical over legacy when both set", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken(
+      { SCRIBE_AUTH_TOKEN: "new", SCRIBE_TOKEN: "old" } as NodeJS.ProcessEnv,
+      logger,
+    );
+    expect(token).toBe("new");
+    expect(calls.length).toBe(0);
+  });
+
+  test("falls back to SCRIBE_TOKEN with deprecation warning", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken(
+      { SCRIBE_TOKEN: "legacy-v0" } as NodeJS.ProcessEnv,
+      logger,
+    );
+    expect(token).toBe("legacy-v0");
+    expect(calls.length).toBe(1);
+    expect(String(calls[0][0])).toContain("SCRIBE_TOKEN is deprecated");
+    expect(String(calls[0][0])).toContain("SCRIBE_AUTH_TOKEN");
+  });
+
+  test("returns undefined when neither is set (loopback back-compat)", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken({} as NodeJS.ProcessEnv, logger);
+    expect(token).toBeUndefined();
+    expect(calls.length).toBe(0);
+  });
+});

package/src/scribe-env.ts

@@ -0,0 +1,33 @@
+/**
+ * Env-var plumbing for the scribe integration (transcription worker + triggers).
+ *
+ * Lives in its own module so the boot-time token resolution in server.ts is
+ * testable without running the rest of server.ts (which has side effects:
+ * triggers, auto-init, Bun.serve). Keep this module pure and dependency-free.
+ */
+
+/**
+ * Resolve the scribe auth token. `SCRIBE_AUTH_TOKEN` is the canonical name
+ * (matches the CLI's install-time auto-wire); `SCRIBE_TOKEN` is a legacy alias
+ * kept for one release — when only the legacy name is set, we warn once so
+ * users notice and rename.
+ *
+ * Returns `undefined` when neither is set; callers must treat that as "no
+ * Authorization header" (back-compat with loopback-trust deployments).
+ */
+export function resolveScribeAuthToken(
+  env: NodeJS.ProcessEnv = process.env,
+  logger: { warn: (...args: unknown[]) => void } = console,
+): string | undefined {
+  const canonical = env.SCRIBE_AUTH_TOKEN;
+  if (canonical) return canonical;
+  const legacy = env.SCRIBE_TOKEN;
+  if (legacy) {
+    logger.warn(
+      "[transcribe] SCRIBE_TOKEN is deprecated; rename to SCRIBE_AUTH_TOKEN. " +
+      "The legacy name will stop being read in the next release.",
+    );
+    return legacy;
+  }
+  return undefined;
+}