@openparachute/vault 0.4.9-rc.3 → 0.4.9-rc.4

package/src/mirror-routes.test.ts

@@ -16,7 +16,11 @@ import {
   MirrorManager,
   type MirrorDeps,
 } from "./mirror-manager.ts";
-import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
+import {
+  handleMirrorGet,
+  handleMirrorPut,
+  handleMirrorRunNow,
+} from "./mirror-routes.ts";
 
 // Same env-restore pattern as mirror-manager.test.ts — keeps HOME +
 // PARACHUTE_HOME from leaking between test files.
@@ -378,3 +382,57 @@ describe("handleMirrorPut", () => {
     await manager.stop();
   });
 });
+
+// ---------------------------------------------------------------------------
+// POST /.parachute/mirror/run-now
+// ---------------------------------------------------------------------------
+
+describe("handleMirrorRunNow", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  test("returns 400 when mirror is disabled (avoids stale-status no-op)", async () => {
+    home = tmp("mirror-runnow-disabled-");
+    const { manager, exportCalls } = makeManager(home);
+    const res = await handleMirrorRunNow(manager);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string; message: string };
+    expect(body.error).toContain("not enabled");
+    // The disabled-guard short-circuits BEFORE manager.runNow(), so no
+    // export attempt happens — pinning this distinguishes the guard from
+    // a "200 with stale status" pass-through that would have looked
+    // identical to the operator.
+    expect(exportCalls()).toHaveLength(0);
+  });
+
+  test("fires an export pass and returns the updated config+status on success", async () => {
+    home = tmp("mirror-runnow-happy-");
+    const { manager, deps, exportCalls } = makeManager(home);
+    deps.writeMirrorConfig({
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal",
+      watch: false,
+      auto_commit: false,
+    });
+    await manager.start();
+    // The initial export from start() already ran once. We pin the
+    // delta — run-now must trigger a SECOND export pass and the
+    // response must carry the updated status.
+    const exportsBefore = exportCalls().length;
+    const res = await handleMirrorRunNow(manager);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      config: MirrorConfig;
+      status: { enabled: boolean; last_export_at: string | null; mirror_path: string };
+    };
+    expect(body.config.enabled).toBe(true);
+    expect(body.status.enabled).toBe(true);
+    expect(body.status.last_export_at).not.toBeNull();
+    expect(body.status.mirror_path).toContain("mirror");
+    expect(exportCalls().length).toBe(exportsBefore + 1);
+    await manager.stop();
+  });
+});

package/src/mirror-routes.ts

@@ -1,8 +1,9 @@
 /**
  * HTTP surface for the mirror lifecycle.
  *
- *   GET  /vault/<name>/.parachute/mirror — read current config + runtime status
- *   PUT  /vault/<name>/.parachute/mirror — update config + reload watch loop
+ *   GET  /vault/<name>/.parachute/mirror         — read current config + runtime status
+ *   PUT  /vault/<name>/.parachute/mirror         — update config + reload watch loop
+ *   POST /vault/<name>/.parachute/mirror/run-now — fire a one-shot export+commit+push pass
  *
  * URL note: the design doc names this `/admin/mirror`, but vault's
  * existing routing already mounts the admin SPA's static-file bundle at
@@ -137,6 +138,44 @@ export async function handleMirrorPut(
   );
 }
 
+/**
+ * `POST /vault/<name>/.parachute/mirror/run-now` — fire a one-shot export
+ * cycle right now (export → optional commit → optional push), using the
+ * persisted config. Same response shape as GET so the admin SPA reuses
+ * one decoder for both initial-load and after-trigger refresh.
+ *
+ * Refuses to fire (400) when the mirror is disabled: `runNow()` would
+ * already no-op in that case, but returning a 200 with stale status
+ * lets a misclick look successful. The 400 is the actionable surface
+ * — "enable the mirror first, then re-trigger."
+ *
+ * Mutating verb, vault:admin-gated upstream in `routing.ts` (alongside
+ * the GET/PUT). Auth is already enforced by the time this handler runs.
+ */
+export async function handleMirrorRunNow(
+  manager: MirrorManager,
+): Promise<Response> {
+  const status = manager.getStatus();
+  if (!status.enabled) {
+    return Response.json(
+      {
+        error: "Mirror not enabled",
+        message:
+          "Mirror must be enabled (and successfully bootstrapped) before a manual run can fire. Enable it via PUT /.parachute/mirror first.",
+      },
+      { status: 400 },
+    );
+  }
+  const updated = await manager.runNow();
+  return Response.json(
+    {
+      config: manager.getConfig(),
+      status: updated,
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
 /**
  * Convenience for tests + future callers: build the GET response from a
  * known-good config without needing a real MirrorManager.

package/src/routing.test.ts

@@ -1822,3 +1822,76 @@ describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
     expect([405, 503]).toContain(res.status);
   });
 });
+
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/mirror/run-now — manual-trigger endpoint added
+// alongside the SPA UI. Tests pin the auth gate matches the parent
+// endpoint; handler-shape coverage lives in mirror-routes.test.ts.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/mirror/run-now — auth + dispatch", () => {
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, { method: "POST" }),
+      p,
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, {
+      label: "reader",
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("admin token reaches the handler — 503 when manager not wired, 400 when wired+disabled", async () => {
+    // Mirrors the parent endpoint's harness behavior: test ordering
+    // determines whether a previous test wired a manager. Either way
+    // the auth gate passed, which is what this routing-level test pins.
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    expect([400, 503]).toContain(res.status);
+  });
+
+  test("non-POST methods return 405 when manager is wired", async () => {
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    // 503 short-circuits the method check when no manager is wired.
+    expect([405, 503]).toContain(res.status);
+  });
+});

package/src/routing.ts

@@ -72,7 +72,7 @@ import {
 } from "./oauth-discovery.ts";
 import { handleConfigSchema, handleConfig } from "./module-config.ts";
 import { buildAuthStatus } from "./auth-status.ts";
-import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
+import { handleMirrorGet, handleMirrorPut, handleMirrorRunNow } from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 
 /**
@@ -511,6 +511,39 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/mirror/run-now — fire a one-shot export+commit+push pass.
+  // Same admin gate as the GET/PUT above; same manager presence check.
+  // POST-only — a GET would imply "read the result of running" which
+  // isn't the verb (the rolling status is already available on the
+  // parent GET endpoint).
+  if (subpath === "/.parachute/mirror/run-now") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const manager = getMirrorManager();
+    if (!manager) {
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired a mirror manager yet (no vaults exist, or boot failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+    if (req.method === "POST") return handleMirrorRunNow(manager);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
   const apiMatch = subpath.match(/^\/api(\/.*)?$/);
   if (!apiMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });

package/src/token-store.ts

@@ -63,6 +63,26 @@ export interface Token {
   expires_at: string | null;
   created_at: string;
   last_used_at: string | null;
+  /**
+   * Provenance (v19). 'mcp_mint' = minted via manage-token MCP tool;
+   * NULL = pre-v19 / CLI / REST / YAML-import. Used by manage-token list
+   * to restrict the surface to MCP-session-managed tokens. See vault#376.
+   */
+  created_via: string | null;
+  /**
+   * Session pin (v19). When this token was minted via manage-token, this
+   * is the display id (`t_<prefix>`) of the calling session's token (for
+   * pvt_* MCP sessions) or the hub JWT's jti claim (for hub-issued
+   * sessions). NULL otherwise.
+   */
+  parent_jti: string | null;
+  /**
+   * Soft-revoke timestamp (v19). When set, `resolveToken` returns null
+   * and the row stays in place for audit history. manage-token revoke is
+   * idempotent — calling revoke a second time on the same jti is a no-op
+   * with ok=true. NULL = active.
+   */
+  revoked_at: string | null;
 }
 
 export interface ResolvedToken {
@@ -88,6 +108,12 @@ export interface ResolvedToken {
    * vault. See vault#257.
    */
   vault_name: string | null;
+  /**
+   * Display id (`t_<hashprefix>`) of THIS token. Surfaced so callers that
+   * later mint child tokens (manage-token MCP tool) can stamp parent_jti
+   * without re-derivation. Pre-v19 lookups still compute this on the fly.
+   */
+  jti: string;
 }
 
 /**
@@ -149,6 +175,17 @@ export function createToken(
      */
     vault_name?: string | null;
     expires_at?: string | null;
+    /**
+     * Provenance tag (v19). `'mcp_mint'` for tokens minted via the
+     * manage-token MCP tool; omit/null for CLI / REST / YAML paths.
+     */
+    created_via?: string | null;
+    /**
+     * Session pin (v19). Display id (`t_<prefix>`) or hub JWT `jti` of the
+     * caller that minted this token via manage-token. Used by the
+     * manage-token list/revoke surface to scope itself to one session.
+     */
+    parent_jti?: string | null;
   },
 ): Token {
   const tokenHash = hashKey(fullToken);
@@ -159,10 +196,12 @@ export function createToken(
   const scopedTags = opts.scoped_tags && opts.scoped_tags.length > 0 ? opts.scoped_tags : null;
   const scopedTagsStr = scopedTags ? JSON.stringify(scopedTags) : null;
   const vaultName = opts.vault_name ?? null;
+  const createdVia = opts.created_via ?? null;
+  const parentJti = opts.parent_jti ?? null;
 
   db.prepare(`
-    INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, scope_tag, scope_path_prefix, expires_at, created_at, vault_name)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, scope_tag, scope_path_prefix, expires_at, created_at, vault_name, created_via, parent_jti)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     tokenHash,
     opts.label,
@@ -174,6 +213,8 @@ export function createToken(
     opts.expires_at ?? null,
     now,
     vaultName,
+    createdVia,
+    parentJti,
   );
 
   return {
@@ -187,6 +228,9 @@ export function createToken(
     expires_at: opts.expires_at ?? null,
     created_at: now,
     last_used_at: null,
+    created_via: createdVia,
+    parent_jti: parentJti,
+    revoked_at: null,
   };
 }
 
@@ -200,8 +244,15 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   // preimage, which is computationally infeasible regardless of timing leaks.
   const candidateHash = hashKey(providedToken);
 
+  // Defensive SELECT for revoked_at: the column exists post-v19, but a
+  // freshly-opened ResolvedToken-only test fixture might run on a DB the
+  // migration hasn't touched. SQLite returns NULL for missing columns when
+  // the table is queried via prepared statements only after migration; here
+  // initSchema fires on every store-open path, so the column is guaranteed
+  // present in production. Tests instantiating bare DBs against this
+  // module are expected to call initSchema first.
   const row = db.prepare(`
-    SELECT token_hash, permission, scopes, scoped_tags, expires_at, vault_name
+    SELECT token_hash, permission, scopes, scoped_tags, expires_at, vault_name, revoked_at
     FROM tokens WHERE token_hash = ?
   `).get(candidateHash) as {
     token_hash: string;
@@ -210,10 +261,16 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
     scoped_tags: string | null;
     expires_at: string | null;
     vault_name: string | null;
+    revoked_at: string | null;
   } | null;
 
   if (!row) return null;
 
+  // Soft-revoked tokens never authenticate (v19). The row stays in place
+  // for audit; resolveToken just treats it as not-found from the caller's
+  // perspective.
+  if (row.revoked_at) return null;
+
   // Check expiry
   if (row.expires_at && new Date(row.expires_at) < new Date()) {
     return null;
@@ -229,8 +286,9 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   const scopes = hasVaultScope ? parsed : legacyPermissionToScopes(permission);
   const legacyDerived = !hasVaultScope;
   const scoped_tags = parseScopedTags(row.scoped_tags);
+  const jti = `t_${row.token_hash.slice(7, 19)}`;
 
-  return { permission, scopes, legacyDerived, scoped_tags, vault_name: row.vault_name };
+  return { permission, scopes, legacyDerived, scoped_tags, vault_name: row.vault_name, jti };
 }
 
 /**
@@ -252,7 +310,8 @@ export function listTokens(
   const params = opts.vaultName ? [opts.vaultName] : [];
   const rows = db.prepare(`
     SELECT token_hash, label, permission, scope_tag, scope_path_prefix,
-           scoped_tags, vault_name, expires_at, created_at, last_used_at
+           scoped_tags, vault_name, expires_at, created_at, last_used_at,
+           created_via, parent_jti, revoked_at
     FROM tokens ${where}
     ORDER BY created_at DESC
   `).all(...params) as (Omit<Token, "scoped_tags"> & { scoped_tags: string | null })[];
@@ -266,6 +325,100 @@ export function listTokens(
   }));
 }
 
+/**
+ * List tokens minted via the manage-token MCP tool by a given session
+ * (parent_jti). Used by `manage-token` action="list" to scope its surface
+ * to its own session's mints — operators with multiple MCP sessions open
+ * don't see each other's tokens, and CLI/REST-minted tokens never appear.
+ *
+ * Returns metadata only (no token-hash exposure beyond the display id);
+ * the display id is what the caller uses to revoke. Includes `revoked_at`
+ * so the UI can render a tombstone for soft-revoked rows.
+ */
+export function listMcpMintedTokens(
+  db: Database,
+  parentJti: string,
+  vaultName: string,
+): Array<{
+  jti: string;
+  label: string;
+  scopes: string[];
+  scoped_tags: string[] | null;
+  created_at: string;
+  expires_at: string | null;
+  revoked_at: string | null;
+}> {
+  const rows = db.prepare(`
+    SELECT token_hash, label, scopes, scoped_tags, created_at, expires_at, revoked_at
+    FROM tokens
+    WHERE created_via = 'mcp_mint'
+      AND parent_jti = ?
+      AND vault_name = ?
+    ORDER BY created_at DESC
+  `).all(parentJti, vaultName) as {
+    token_hash: string;
+    label: string;
+    scopes: string | null;
+    scoped_tags: string | null;
+    created_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+  }[];
+  return rows.map((r) => ({
+    jti: `t_${r.token_hash.slice(7, 19)}`,
+    label: r.label,
+    scopes: parseScopes(r.scopes),
+    scoped_tags: parseScopedTags(r.scoped_tags),
+    created_at: r.created_at,
+    expires_at: r.expires_at,
+    revoked_at: r.revoked_at,
+  }));
+}
+
+/**
+ * Soft-revoke a token minted via manage-token, scoped to the session that
+ * minted it. Idempotent: revoking an already-revoked or never-existent jti
+ * returns the same shape; second-call to revoke is intentionally still
+ * ok=true so the AI's revoke step doesn't surface a confusing failure on a
+ * retry after a network blip. The row stays in place for audit trail —
+ * resolveToken treats revoked_at-set rows as not-found.
+ *
+ * `parentJti` + `vaultName` scope the lookup: a token minted by a
+ * different MCP session (or against a different vault) returns ok=false.
+ * Returns { ok: true, already_revoked? } when the operation matched a row.
+ */
+export function softRevokeMcpToken(
+  db: Database,
+  jti: string,
+  parentJti: string,
+  vaultName: string,
+): { ok: true; already_revoked: boolean } | { ok: false; reason: "not_found" } {
+  if (!jti.startsWith("t_")) {
+    return { ok: false, reason: "not_found" };
+  }
+  const hashPrefix = jti.slice(2);
+  const row = db.prepare(`
+    SELECT token_hash, revoked_at FROM tokens
+    WHERE token_hash LIKE ?
+      AND created_via = 'mcp_mint'
+      AND parent_jti = ?
+      AND vault_name = ?
+    LIMIT 1
+  `).get(`sha256:${hashPrefix}%`, parentJti, vaultName) as {
+    token_hash: string;
+    revoked_at: string | null;
+  } | null;
+
+  if (!row) return { ok: false, reason: "not_found" };
+  if (row.revoked_at) {
+    // Second revoke: idempotent — already done, surface true with the flag.
+    return { ok: true, already_revoked: true };
+  }
+  db.prepare("UPDATE tokens SET revoked_at = ? WHERE token_hash = ?")
+    .run(new Date().toISOString(), row.token_hash);
+  return { ok: true, already_revoked: false };
+}
+
 /**
  * Find tokens whose `scoped_tags` allowlist references the given root tag.
  * Used by tag-delete and tag-merge to fail-closed (409) when removing a