@openparachute/vault 0.4.9-rc.11 → 0.4.9-rc.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.9-rc.11",
+  "version": "0.4.9-rc.12",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/auth-hub-jwt.test.ts

@@ -30,6 +30,7 @@ import { writeVaultConfig, readVaultConfig } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
 import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
 import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
+import { generateToken, createToken } from "./token-store.ts";
 
 interface Keypair {
   privateKey: CryptoKey;
@@ -665,3 +666,117 @@ describe("authenticateVaultRequest — hub JWT tag-scoping (auth-unification C0)
     });
   }
 });
+
+// ---------------------------------------------------------------------------
+// pvt_* deprecation warning (vault#282 Stage 1 — soft deprecation, NON-BREAKING)
+//
+// Every successful pvt_* (vault-DB token-store) authentication emits a
+// one-time-per-token deprecation warning signalling that pvt_* tokens will be
+// REJECTED at vault 0.6.0. Auth OUTCOMES are unchanged: the token still
+// validates + authorizes exactly as before. Hub-issued JWTs — the migration
+// target — never trigger the pvt_* warning.
+//
+// The `warnPvtDeprecationOnce` cache is process-global and keyed on the
+// token's display id (`t_<hashprefix>`). Each test mints a fresh random pvt_*,
+// so display ids never collide across tests; the "warns once" assertion holds
+// within a single test by making two requests with the same token.
+// ---------------------------------------------------------------------------
+
+/** Mint a fresh pvt_* token directly into a vault's DB and return it. */
+function mintPvtToken(vaultName: string): string {
+  const store = getVaultStore(vaultName);
+  const { fullToken } = generateToken();
+  createToken(store.db, fullToken, { label: "deprecation-test", permission: "full" });
+  return fullToken;
+}
+
+describe("pvt_* deprecation warning (vault#282 Stage 1)", () => {
+  test("pvt_* auth still SUCCEEDS and emits the deprecation warning once", async () => {
+    seedVault("journal");
+    const token = mintPvtToken("journal");
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      // First request: auth outcome unchanged (full permission), warning fires.
+      const r1 = await authenticateVaultRequest(bearer(token), config, store.db);
+      expect("error" in r1).toBe(false);
+      if (!("error" in r1)) {
+        expect(r1.permission).toBe("full");
+        expect(r1.scopes).toContain("vault:admin");
+      }
+
+      const deprecationCalls = warnSpy.mock.calls.filter((c) =>
+        String(c[0]).includes("[deprecation]"),
+      );
+      expect(deprecationCalls.length).toBe(1);
+      const msg = String(deprecationCalls[0]![0]);
+      // Shape: names pvt_*, the 0.6.0 rejection, the issue, the mint paths, the guide.
+      expect(msg).toContain("pvt_* token");
+      expect(msg).toContain("DEPRECATED");
+      expect(msg).toContain("REJECTED at vault 0.6.0");
+      expect(msg).toContain("vault#282");
+      expect(msg).toContain("parachute vault mcp-install");
+      expect(msg).toContain("parachute auth mint-token");
+      expect(msg).toContain("UPGRADING.md");
+      // The display id of the presented token appears in the message.
+      expect(msg).toMatch(/pvt_\* token t_[0-9a-f]+ authenticated/);
+
+      // Second request with the SAME token: still authorizes, no second warn.
+      const r2 = await authenticateVaultRequest(bearer(token), config, store.db);
+      expect("error" in r2).toBe(false);
+      const stillOne = warnSpy.mock.calls.filter((c) =>
+        String(c[0]).includes("[deprecation]"),
+      );
+      expect(stillOne.length).toBe(1);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("pvt_* auth on the global (unified) surface also SUCCEEDS and warns once", async () => {
+    seedVault("journal");
+    const token = mintPvtToken("journal");
+
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = await authenticateGlobalRequest(bearer(token));
+      expect("error" in result).toBe(false);
+      if (!("error" in result)) expect(result.permission).toBe("full");
+
+      const deprecationCalls = warnSpy.mock.calls.filter((c) =>
+        String(c[0]).includes("[deprecation]"),
+      );
+      expect(deprecationCalls.length).toBe(1);
+      expect(String(deprecationCalls[0]![0])).toContain("vault#282");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("hub-JWT auth does NOT emit the pvt_* deprecation warning", async () => {
+    seedVault("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+    });
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = await authenticateVaultRequest(bearer(token), config, store.db);
+      // Auth succeeds (the migration target works) ...
+      expect("error" in result).toBe(false);
+      // ... and no pvt_* deprecation warning is emitted for a hub JWT.
+      const deprecationCalls = warnSpy.mock.calls.filter((c) =>
+        String(c[0]).includes("[deprecation]"),
+      );
+      expect(deprecationCalls.length).toBe(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});

package/src/auth.ts

@@ -169,6 +169,40 @@ export function warnLegacyOnce(cacheKey: string, context: string): void {
   );
 }
 
+/**
+ * Doc link operators are sent to when a `pvt_*` token authenticates. Points
+ * at the pvt_* → hub-JWT migration section of vault's UPGRADING.md.
+ */
+const PVT_MIGRATION_DOC =
+  "https://github.com/ParachuteComputer/parachute-vault/blob/main/UPGRADING.md#pvt_-token-deprecation--will-be-rejected-at-060";
+
+// One-shot pvt_* deprecation warning tracker, keyed by the token's display id
+// (`t_<hashprefix>`) so each distinct token warns exactly once per process.
+const warnedPvtTokens = new Set<string>();
+
+/**
+ * Log a one-time (per token-hash) deprecation warning for a successfully-
+ * authenticated `pvt_*` vault-DB token. Stage 1 of vault#282: pvt_* still
+ * AUTHENTICATES and AUTHORIZES exactly as before — this only signals that the
+ * credential is on a deprecation clock and will be REJECTED at vault 0.6.0.
+ *
+ * Keyed on the token's display id (`t_<hashprefix>` — the `jti` ResolvedToken
+ * surfaces) so a given token logs once per process regardless of how many
+ * requests it makes or whether it carries explicit scopes. Folds in the
+ * narrower pre-existing "vault token without scopes column" warning — a legacy-
+ * derived pvt_* gets THIS warning, not both, so we never double-warn one token.
+ */
+export function warnPvtDeprecationOnce(displayId: string): void {
+  if (warnedPvtTokens.has(displayId)) return;
+  warnedPvtTokens.add(displayId);
+  console.warn(
+    `[deprecation] pvt_* token ${displayId} authenticated — pvt_* tokens are DEPRECATED and will be REJECTED at vault 0.6.0 (vault#282). ` +
+      "Migrate to a hub-issued JWT: run `parachute vault mcp-install` (MCP clients) or " +
+      "`parachute auth mint-token --scope vault:<name>:<verb>` (scripts). " +
+      `Guide: ${PVT_MIGRATION_DOC}.`,
+  );
+}
+
 /** Read-only tools (the only tools allowed for "read" permission). */
 const READ_TOOLS = new Set([
   "query-notes",
@@ -292,9 +326,12 @@ export async function authenticateVaultRequest(
             ),
           };
         }
-        if (resolved.legacyDerived) {
-          warnLegacyOnce(`vault-token:${vaultConfig.name ?? ""}`, "vault token without scopes column");
-        }
+        // vault#282 Stage 1: every successful pvt_* (vault-DB token-store)
+        // authentication is on a deprecation clock. One-time per token-hash
+        // (keyed on the display id). Folds in the old narrower "vault token
+        // without scopes column" warning — a legacy-derived pvt_* gets THIS
+        // warning, not both. Auth OUTCOME is unchanged; this only signals.
+        warnPvtDeprecationOnce(resolved.jti);
         return {
           permission: resolved.permission,
           scopes: resolved.scopes,
@@ -621,9 +658,10 @@ export async function authenticateGlobalRequest(
       const store = getVaultStore(vaultName);
       const resolved = resolveToken(store.db, key);
       if (resolved) {
-        if (resolved.legacyDerived) {
-          warnLegacyOnce(`vault-token:${vaultName}`, "vault token without scopes column");
-        }
+        // vault#282 Stage 1: pvt_* resolved on the unified surface is on the
+        // same deprecation clock. One-time per token-hash; folds in the old
+        // narrower legacy-scopes warning. Auth OUTCOME unchanged.
+        warnPvtDeprecationOnce(resolved.jti);
         return {
           permission: resolved.permission,
           scopes: resolved.scopes,