npm - @openparachute/vault - Versions diffs - 0.3.1 → 0.4.0 - Mend

@openparachute/vault 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (82) hide show

package/.parachute/module.json +15 -0
package/README.md +9 -5
package/core/src/core.test.ts +2252 -7
package/core/src/links.ts +1 -1
package/core/src/mcp.ts +801 -67
package/core/src/note-schemas.ts +232 -0
package/core/src/notes.ts +313 -35
package/core/src/obsidian.ts +3 -3
package/core/src/paths.ts +1 -1
package/core/src/query-operators.ts +23 -7
package/core/src/schema-defaults.ts +287 -0
package/core/src/schema.ts +393 -9
package/core/src/store.ts +248 -6
package/core/src/tag-hierarchy.ts +137 -0
package/core/src/tag-schemas.ts +242 -42
package/core/src/types.ts +100 -6
package/core/src/wikilinks.ts +3 -3
package/package.json +13 -3
package/src/admin-spa.test.ts +161 -0
package/src/admin-spa.ts +161 -0
package/src/auth-hub-jwt.test.ts +231 -0
package/src/auth-status.ts +84 -0
package/src/auth.test.ts +135 -23
package/src/auth.ts +144 -15
package/src/backup.ts +4 -7
package/src/cli.ts +384 -78
package/src/config.test.ts +44 -0
package/src/config.ts +68 -40
package/src/hub-jwt.test.ts +296 -0
package/src/hub-jwt.ts +79 -0
package/src/init-summary.test.ts +133 -0
package/src/init-summary.ts +90 -0
package/src/init.test.ts +216 -0
package/src/mcp-http.ts +30 -28
package/src/mcp-install.ts +1 -1
package/src/mcp-tools.ts +294 -6
package/src/module-config.ts +1 -1
package/src/oauth.test.ts +345 -0
package/src/oauth.ts +85 -14
package/src/owner-auth.ts +57 -1
package/src/prompt.ts +31 -14
package/src/routes.ts +686 -58
package/src/routing.test.ts +466 -1
package/src/routing.ts +108 -24
package/src/scopes.test.ts +66 -8
package/src/scopes.ts +163 -37
package/src/server.ts +24 -2
package/src/services-manifest.test.ts +20 -0
package/src/services-manifest.ts +9 -2
package/src/stop-signal.test.ts +85 -0
package/src/storage.test.ts +92 -0
package/src/tag-scope.ts +118 -0
package/src/token-store.test.ts +47 -0
package/src/token-store.ts +128 -13
package/src/tokens-routes.test.ts +720 -0
package/src/tokens-routes.ts +392 -0
package/src/transcription-worker.test.ts +5 -0
package/src/triggers.ts +1 -1
package/src/two-factor.ts +2 -2
package/src/vault-create.test.ts +193 -0
package/src/vault-name.test.ts +123 -0
package/src/vault-name.ts +80 -0
package/src/vault.test.ts +868 -3
package/tsconfig.json +8 -1
package/.claude/settings.local.json +0 -8
package/.dockerignore +0 -8
package/.env.example +0 -9
package/CHANGELOG.md +0 -175
package/CLAUDE.md +0 -125
package/Caddyfile +0 -3
package/Dockerfile +0 -22
package/bun.lock +0 -219
package/bunfig.toml +0 -2
package/deploy/parachute-vault.service +0 -20
package/docker-compose.yml +0 -50
package/docs/HTTP_API.md +0 -434
package/docs/auth-model.md +0 -340
package/fly.toml +0 -24
package/package/package.json +0 -32
package/railway.json +0 -14
package/scripts/migrate-audio-to-opus.test.ts +0 -237
package/scripts/migrate-audio-to-opus.ts +0 -499

package/src/admin-spa.test.ts ADDED Viewed

@@ -0,0 +1,161 @@
+/**
+ * Tests for the admin SPA static-file mount (`src/admin-spa.ts`).
+ *
+ * The routing layer's responsibility is just "dispatch /admin/* to the SPA";
+ * this file tests the SPA-serving behavior itself with a tmp dist dir so
+ * the assertions don't depend on `bun run build` having been run in
+ * `web/ui/`. The integration check (admin path → SPA dispatch) lives in
+ * `routing.test.ts`.
+ */
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { isAdminSpaPath, serveAdminSpa } from "./admin-spa.ts";
+const fixtureDir = join(tmpdir(), `vault-admin-spa-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+beforeAll(() => {
+  mkdirSync(join(fixtureDir, "assets"), { recursive: true });
+  writeFileSync(join(fixtureDir, "index.html"), "<!doctype html><html><body>shell</body></html>");
+  writeFileSync(join(fixtureDir, "assets", "index-abc.js"), "console.log('bundle');");
+  writeFileSync(join(fixtureDir, "assets", "index-abc.css"), "body { color: red; }");
+});
+afterAll(() => {
+  rmSync(fixtureDir, { recursive: true, force: true });
+});
+describe("isAdminSpaPath", () => {
+  test("matches /vault/<name>/admin and /vault/<name>/admin/...", () => {
+    expect(isAdminSpaPath("/vault/work/admin")).toBe(true);
+    expect(isAdminSpaPath("/vault/work/admin/")).toBe(true);
+    expect(isAdminSpaPath("/vault/work/admin/tokens")).toBe(true);
+    expect(isAdminSpaPath("/vault/boulder/admin/assets/index.js")).toBe(true);
+    // Vault names with URL-safe punctuation should still match — the regex
+    // captures up to the next "/" so dashes / dots / digits all pass.
+    expect(isAdminSpaPath("/vault/my-vault.2/admin")).toBe(true);
+  });
+  test("does not match adjacent paths under the same vault", () => {
+    expect(isAdminSpaPath("/vault/work")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/api/notes")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/tokens")).toBe(false);
+    // Bare `admin-foo` suffix must not trigger — only the SPA mount itself.
+    expect(isAdminSpaPath("/vault/work/admin-foo")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/administrative")).toBe(false);
+  });
+  test("does not match origin-rooted /admin (legacy mount retired)", () => {
+    expect(isAdminSpaPath("/admin")).toBe(false);
+    expect(isAdminSpaPath("/admin/")).toBe(false);
+    expect(isAdminSpaPath("/admin/tokens")).toBe(false);
+  });
+  test("does not match unrelated paths", () => {
+    expect(isAdminSpaPath("/")).toBe(false);
+    expect(isAdminSpaPath("/vaults")).toBe(false);
+    expect(isAdminSpaPath("/auth/status")).toBe(false);
+  });
+});
+describe("serveAdminSpa", () => {
+  test("503 when the dist dir is absent (unbuilt)", async () => {
+    const res = await serveAdminSpa("/nonexistent/dist/dir", "/vault/work/admin/");
+    expect(res.status).toBe(503);
+    const body = await res.text();
+    expect(body).toContain("not found");
+    expect(body).toContain("bun run build");
+  });
+  test("bare /vault/<name>/admin redirects to trailing-slash form (301)", async () => {
+    // Vite's relative asset URLs (./assets/...) resolve against the
+    // *directory* of the current document — without a trailing slash,
+    // /vault/foo/admin's directory is /vault/foo/ and assets 404 against
+    // the per-vault auth wall. Hub's resolveManagementUrl generates the
+    // bare form, so this redirect is the load-bearing canonicalization.
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin");
+    expect(res.status).toBe(301);
+    expect(res.headers.get("Location")).toBe("/vault/work/admin/");
+  });
+  test("/vault/<name>/admin/ returns the SPA index", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("shell");
+  });
+  test("client-routed path (no extension) falls through to index.html", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/tokens");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("shell");
+  });
+  test("real asset path returns the asset with the right content-type", async () => {
+    const jsRes = await serveAdminSpa(fixtureDir, "/vault/work/admin/assets/index-abc.js");
+    expect(jsRes.status).toBe(200);
+    expect(jsRes.headers.get("content-type")).toContain("application/javascript");
+    expect(await jsRes.text()).toContain("console.log");
+    const cssRes = await serveAdminSpa(fixtureDir, "/vault/work/admin/assets/index-abc.css");
+    expect(cssRes.status).toBe(200);
+    expect(cssRes.headers.get("content-type")).toContain("text/css");
+  });
+  test("vault names with URL-safe punctuation strip cleanly", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/my-vault.2/admin/assets/index-abc.js");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/javascript");
+  });
+  test("typo'd asset path falls through to index.html (not a 404)", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/assets/missing-xyz.js");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+  });
+  test("path traversal (..) cannot escape dist dir", async () => {
+    // Triggers the asset-shape filter (.. is rejected) so this falls through
+    // to the SPA shell rather than reading something outside dist/.
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/../../etc/passwd");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    const body = await res.text();
+    expect(body).toContain("shell");
+    expect(body).not.toContain("root:");
+  });
+});
+describe("hub <-> vault managementUrl contract", () => {
+  // Browsers drop the URL fragment when following a 301 (RFC 7231 SHOULD
+  // preserve, but Chrome/Firefox/Safari are inconsistent in practice). The
+  // hub-issued JWT travels in `#token=...`, so a redirected click loses the
+  // token and the SPA boots unauthenticated. Hub's resolveManagementUrl joins
+  // the per-vault module URL with module.json's `managementUrl` verbatim — if
+  // it ends with "/" the canonical click target is `/vault/<name>/admin/`
+  // (no redirect, fragment preserved). Without the trailing slash hub emits
+  // `/vault/<name>/admin`, the server 301s, and the fragment is gone.
+  test("module.json managementUrl ends with '/' so hub emits the no-redirect form", () => {
+    const moduleJson = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
+    );
+    expect(moduleJson.managementUrl).toMatch(/\/$/);
+  });
+  test("the canonical hub-emitted URL serves the SPA shell directly (no 301)", async () => {
+    // Mirror hub's resolveManagementUrl shape: per-vault module URL +
+    // managementUrl. With managementUrl="/admin/" the result is
+    // /vault/<name>/admin/ — which serveAdminSpa returns as 200, not 301.
+    const moduleJson = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
+    );
+    const canonical = `/vault/work${moduleJson.managementUrl}`;
+    const res = await serveAdminSpa(fixtureDir, canonical);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Location")).toBeNull();
+  });
+});

package/src/admin-spa.ts ADDED Viewed

@@ -0,0 +1,161 @@
+/**
+ * Admin SPA mount. Serves `web/ui/dist/` under `/vault/<name>/admin/*`.
+ *
+ * The vault HTTP server hosts an admin SPA (vault#216) co-located in the
+ * source tree at `web/ui/`. Vite produces the bundle in `web/ui/dist/`
+ * (gitignored — built locally before publish, or by a release pipeline).
+ * This module turns the bundle into a static-file response.
+ *
+ * Per-vault mount (vault#252): the SPA lives under `/vault/<name>/admin/*`
+ * rather than the origin-rooted `/admin/*` it shipped with. The hub only
+ * proxies `/vault/<name>/*` paths (per parachute-patterns/module-protocol),
+ * so an origin-rooted SPA is unreachable through the hub. Asset URLs are
+ * relative (Vite `base: "./"`), so the same bundle works at any mount
+ * point — no rebuild per vault.
+ *
+ * Mirrors `parachute-hub/src/hub-server.ts:serveSpa` — the conventions
+ * (strip mount, asset-shape filter, `.html` fallthrough for client routes)
+ * are identical so an operator who knows one knows the other.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Regex anchoring the per-vault SPA mount. Matches `/vault/<name>/admin`
+ * exactly and any subpath under it. The `<name>` capture is reused by the
+ * prefix-strip below — keep the two in sync if this regex moves.
+ */
+const ADMIN_SPA_MOUNT_RE = /^\/vault\/([^/]+)\/admin(?=\/|$)/;
+/**
+ * Resolve the default SPA bundle dir. Anchored to this file's location so
+ * a `bun src/server.ts` from any cwd still finds `<repo>/web/ui/dist/`.
+ * Tests / production override via the `spaDistDir` argument to
+ * `serveAdminSpa`.
+ */
+export function defaultAdminSpaDistDir(): string {
+  // import.meta.dir is the dir holding *this* file (`src/`); the SPA bundle
+  // sits at `<repo>/web/ui/dist/`.
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "web", "ui", "dist");
+}
+/**
+ * Pick a content type for static assets the SPA build produces. Vite's
+ * fingerprinted output is the realistic surface — js / css / svg / png /
+ * woff2 / ico. Mismatches show up loud (a `.js` served as `text/html` is
+ * unmistakable) and the list is trivially extensible if a future feature
+ * adds an asset type.
+ */
+function spaContentType(pathname: string): string {
+  const ext = pathname.slice(pathname.lastIndexOf(".") + 1).toLowerCase();
+  switch (ext) {
+    case "html":
+      return "text/html; charset=utf-8";
+    case "js":
+    case "mjs":
+      return "application/javascript; charset=utf-8";
+    case "css":
+      return "text/css; charset=utf-8";
+    case "svg":
+      return "image/svg+xml";
+    case "png":
+      return "image/png";
+    case "ico":
+      return "image/x-icon";
+    case "woff2":
+      return "font/woff2";
+    case "woff":
+      return "font/woff";
+    case "json":
+    case "map":
+      return "application/json";
+    case "txt":
+      return "text/plain; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}
+/**
+ * Serve a single file under the SPA mount, falling back to `index.html`
+ * for client-side-routed paths (anything that doesn't resolve to a real
+ * file under `dist/`). Path-traversal is blocked twice: the asset-shape
+ * filter rejects sub-paths containing "..", and the resolved absolute
+ * path is checked to start with `dist/` before any read.
+ *
+ * No auth is enforced at this seam — the SPA's `index.html` and bundle are
+ * static assets and reveal nothing privileged. The data fetches the SPA
+ * issues land on existing per-vault routes that already enforce
+ * `vault:<name>:read` / `vault:<name>:admin`. This keeps the SPA loadable
+ * even before a token has been minted (so the operator can actually see
+ * the empty / auth-required state we render in `VaultDetail.tsx`).
+ */
+export async function serveAdminSpa(spaDistDir: string, pathname: string): Promise<Response> {
+  if (!existsSync(spaDistDir)) {
+    return new Response(
+      "vault admin SPA bundle not found — run `bun run build` in web/ui/ to produce dist/",
+      { status: 503, headers: { "content-type": "text/plain; charset=utf-8" } },
+    );
+  }
+  // Strip the mount prefix:
+  //   /vault/foo/admin       → ""
+  //   /vault/foo/admin/      → "/"
+  //   /vault/foo/admin/x.js  → "/x.js"
+  const sub = pathname.replace(ADMIN_SPA_MOUNT_RE, "");
+  // Canonicalize the bare mount → trailing-slash form. Vite emits
+  // *relative* asset URLs (`./assets/index-abc.js`) since `<name>` isn't
+  // known at build time, and browsers resolve relative URLs against the
+  // **directory** of the current document — not the document itself. So:
+  //   /vault/foo/admin/  → asset resolves to /vault/foo/admin/assets/...  ✓
+  //   /vault/foo/admin   → asset resolves to /vault/foo/assets/...        ✗
+  // Without this redirect, the bare-form URL hub#162 generates (per
+  // `resolveManagementUrl` — strip trailing slash, append `/admin`)
+  // would 404 every asset against the per-vault auth wall, and the SPA
+  // would never boot. Same canonicalization the notes-server `--mount`
+  // path does for the same reason.
+  if (sub === "") {
+    return Response.redirect(`${pathname}/`, 301);
+  }
+  const indexPath = join(spaDistDir, "index.html");
+  // Empty / mount-root / any non-asset request → SPA shell. The router
+  // takes it from there. First defense against traversal: bare paths and
+  // anything containing ".." never enter the asset branch — they fall
+  // through to the shell below.
+  const looksLikeAsset = sub.length > 0 && /\.[a-z0-9]+$/i.test(sub) && !sub.includes("..");
+  if (!looksLikeAsset) {
+    return new Response(Bun.file(indexPath), {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+  }
+  const filePath = resolve(spaDistDir, `.${sub}`);
+  // Second defense: even if a future tweak loosens looksLikeAsset, refuse
+  // any resolved path that escapes dist/. Belt-and-braces.
+  if (!filePath.startsWith(`${spaDistDir}/`)) {
+    return new Response("not found", { status: 404 });
+  }
+  if (!existsSync(filePath)) {
+    // Asset request that doesn't resolve to a real file → SPA shell.
+    // (e.g. `/admin/vault/foo` with a typo'd extension shouldn't 404 the
+    // page.)
+    return new Response(Bun.file(indexPath), {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+  }
+  return new Response(Bun.file(filePath), {
+    headers: { "content-type": spaContentType(filePath) },
+  });
+}
+/**
+ * Match `/vault/<name>/admin` or `/vault/<name>/admin/...`. Bare
+ * `/vault/<name>/admin-foo` and `/vault/<name>` (the metadata endpoint)
+ * must NOT trigger this — only the SPA mount root and its true subpaths.
+ */
+export function isAdminSpaPath(pathname: string): boolean {
+  return ADMIN_SPA_MOUNT_RE.test(pathname);
+}

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

@@ -0,0 +1,231 @@
+/**
+ * End-to-end auth tests for the hub-JWT path.
+ *
+ * `hub-jwt.test.ts` covers `validateHubJwt` in isolation. This file exercises
+ * the full request path: a JWT bearer arrives at `authenticateVaultRequest`,
+ * goes through `authenticateHubJwt`, and the result either resolves into an
+ * `AuthResult` or surfaces as a 401 Response. The cases that matter most:
+ *
+ *   - happy path with narrowed scopes
+ *   - broad `vault:<verb>` scope rejected (forced narrowing per #180)
+ *   - `aud=vault.<other>` rejected (audience mismatch)
+ *   - JWT path rejected at the global (cross-vault) entrypoint
+ *
+ * Each test owns a fresh `PARACHUTE_HOME` and JWKS fixture, like the auth.test
+ * peer file. The JWKS fixture mirrors the one in hub-jwt.test.ts; duplicating
+ * ~30 lines is cheaper than introducing a shared test-helper module.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { generateKeyPair, exportJWK, SignJWT } from "jose";
+import { writeVaultConfig, readVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
+import { resetJwksCache } from "./hub-jwt.ts";
+interface Keypair {
+  privateKey: CryptoKey;
+  publicJwk: { kty: string; n: string; e: string; kid: string; alg: string; use: string };
+  kid: string;
+}
+async function makeKeypair(kid: string): Promise<Keypair> {
+  const { privateKey, publicKey } = await generateKeyPair("RS256", { extractable: true });
+  const jwk = await exportJWK(publicKey);
+  return {
+    privateKey,
+    publicJwk: { kty: "RSA", n: jwk.n!, e: jwk.e!, kid, alg: "RS256", use: "sig" },
+    kid,
+  };
+}
+interface JwksFixture {
+  origin: string;
+  stop: () => void;
+}
+function startJwksFixture(keys: Keypair[]): JwksFixture {
+  const server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname !== "/.well-known/jwks.json") {
+        return new Response("not found", { status: 404 });
+      }
+      return Response.json({ keys: keys.map((k) => k.publicJwk) });
+    },
+  });
+  return {
+    origin: `http://127.0.0.1:${server.port}`,
+    stop: () => server.stop(true),
+  };
+}
+interface SignOpts {
+  iss: string;
+  aud: string;
+  scope: string;
+  sub?: string;
+  ttlSeconds?: number;
+}
+async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
+  const iat = Math.floor(Date.now() / 1000);
+  const exp = iat + (opts.ttlSeconds ?? 60);
+  return await new SignJWT({ scope: opts.scope, client_id: "test-client" })
+    .setProtectedHeader({ alg: "RS256", kid: kp.kid })
+    .setIssuer(opts.iss)
+    .setSubject(opts.sub ?? "user-1")
+    .setAudience(opts.aud)
+    .setIssuedAt(iat)
+    .setExpirationTime(exp)
+    .setJti(`jti-${Math.random().toString(36).slice(2)}`)
+    .sign(kp.privateKey);
+}
+function bearer(token: string): Request {
+  return new Request("https://vault.test/x", {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}
+let tmpHome: string;
+let prevHome: string | undefined;
+let prevHubOrigin: string | undefined;
+let fixture: JwksFixture;
+let kp: Keypair;
+beforeEach(async () => {
+  tmpHome = join(
+    tmpdir(),
+    `vault-auth-jwt-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+  kp = await makeKeypair("k1");
+  fixture = startJwksFixture([kp]);
+  prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  resetJwksCache();
+});
+afterEach(() => {
+  fixture.stop();
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+  else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  // Touch the store so the DB file exists (matches the routing path's expectation).
+  getVaultStore(name);
+}
+describe("authenticateVaultRequest — hub JWT integration", () => {
+  test("narrowed scope + matching aud → AuthResult with permission derived from verb", 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 result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toEqual(["vault:journal:write"]);
+      expect(result.legacyDerived).toBe(false);
+    }
+  });
+  test("narrowed read scope → permission='read'", async () => {
+    seedVault("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+    });
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) expect(result.permission).toBe("read");
+  });
+  test("broad vault:write scope from a JWT → 401 with explanatory message", async () => {
+    seedVault("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:write",
+    });
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+      const body = (await result.error.json()) as { error: string; message: string };
+      expect(body.error).toBe("Unauthorized");
+      expect(body.message).toContain("broad vault scope");
+      expect(body.message).toContain("vault:write");
+    }
+  });
+  test("aud=vault.work cannot reach /vault/journal/* → 401 audience mismatch", async () => {
+    seedVault("journal");
+    seedVault("work");
+    // Token is correctly stamped for work, but presented at journal's endpoint.
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.work",
+      scope: "vault:work:write",
+    });
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+    const result = await authenticateVaultRequest(
+      bearer(token),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+      const body = (await result.error.json()) as { error: string; message: string };
+      expect(body.message).toMatch(/audience mismatch.*vault\.journal.*vault\.work/);
+    }
+  });
+  test("hub JWT at the global (cross-vault) entrypoint → 401 with vault-bound hint", async () => {
+    seedVault("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+    });
+    const result = await authenticateGlobalRequest(bearer(token));
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+      const body = (await result.error.json()) as { error: string; message: string };
+      expect(body.message).toContain("vault-bound");
+      expect(body.message).toContain("/vault/<name>");
+    }
+  });
+});

package/src/auth-status.ts ADDED Viewed

@@ -0,0 +1,84 @@
+/**
+ * Public auth-state probe — read-only summary that lets a first-contact
+ * client decide which token to mint before doing anything authenticated.
+ *
+ * Mirrors the consumer shape that `parachute-hub/src/vault/auth-status.ts`
+ * already computes by snooping vault's filesystem; this endpoint replaces
+ * that out-of-process coupling with an in-process read.
+ *
+ * What gets exposed:
+ *   - `initialized` — at least one vault exists
+ *   - `auth_modes`  — accepted bearer formats (pvt_*, hub-issued JWT)
+ *   - `vaults`      — list of `{ name, url }` for client-side dispatch
+ *   - `hasOwnerPassword`, `hasTotp` — OAuth consent prerequisites
+ *   - `hasTokens`   — boolean | null. `null` ≈ "we couldn't read all DBs,
+ *     don't trust this answer"; `true`/`false` are honest yes/no signals.
+ *
+ * What is deliberately NOT exposed: token counts, hashes, descriptions,
+ * timestamps, owner-password hash, totp secret, backup codes. The endpoint
+ * is unauthenticated — anything sensitive belongs behind /vaults or
+ * /vault/<name>/.
+ */
+import { Database } from "bun:sqlite";
+import { existsSync } from "fs";
+import { listVaults, readGlobalConfig, vaultDbPath } from "./config.ts";
+export interface AuthStatusResponse {
+  initialized: boolean;
+  auth_modes: ("pvt_token" | "hub_jwt")[];
+  vaults: { name: string; url: string }[];
+  hasOwnerPassword: boolean;
+  hasTotp: boolean;
+  hasTokens: boolean | null;
+}
+/**
+ * Probe a single vault's `tokens` table for *existence* (not count). We open
+ * the DB read-only and `LIMIT 1` so we never block a writer or fight for a
+ * lock. Any failure (missing DB, schema drift, lock contention) is the
+ * caller's signal to degrade `hasTokens` to `null`.
+ */
+function vaultHasTokens(dbPath: string): boolean {
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const row = db.prepare("SELECT 1 FROM tokens LIMIT 1").get();
+    return row !== null && row !== undefined;
+  } finally {
+    db.close();
+  }
+}
+function readTokenPresence(vaultNames: string[]): boolean | null {
+  if (vaultNames.length === 0) return false;
+  let any = false;
+  for (const name of vaultNames) {
+    const dbPath = vaultDbPath(name);
+    if (!existsSync(dbPath)) continue;
+    try {
+      if (vaultHasTokens(dbPath)) {
+        any = true;
+        // Don't early-return — keep probing so a later locked DB still
+        // surfaces as `null` rather than a misleading `true`.
+      }
+    } catch {
+      return null;
+    }
+  }
+  return any;
+}
+export function buildAuthStatus(): AuthStatusResponse {
+  const globalConfig = readGlobalConfig();
+  const vaultNames = listVaults();
+  return {
+    initialized: vaultNames.length > 0,
+    auth_modes: ["pvt_token", "hub_jwt"],
+    vaults: vaultNames.map((name) => ({ name, url: `/vault/${name}` })),
+    hasOwnerPassword: typeof globalConfig.owner_password_hash === "string"
+      && globalConfig.owner_password_hash.length > 0,
+    hasTotp: typeof globalConfig.totp_secret === "string"
+      && globalConfig.totp_secret.length > 0,
+    hasTokens: readTokenPresence(vaultNames),
+  };
+}