@fonderie/admin 0.5.0 → 0.7.0

package/README.md

@@ -111,6 +111,62 @@ fonderie admin log --limit 20 # who did what
 
 `FONDERIE_ADMIN_PREFIX` when the surface was moved off `/_admin`.
 
+## The served dashboard
+
+```ts
+app.register(new AdminModule({ adminToken, store, ui: true }));
+```
+
+`GET /_admin/ui` then serves the React shell — the same
+`@fonderie/react-admin-screens` you would otherwise mount yourself, compiled
+into one file (82 KB gzipped) and shipped in this package. No frontend build,
+no extra dependency: React and the screens are devDependencies here, bundled
+at publish time.
+
+Off by default, because most deployments reach the surface through their own
+frontend and would rather not serve the bundle.
+
+- **The two static routes are unguarded, deliberately.** A browser navigating
+  to a page cannot send an `Authorization` header, and neither file carries
+  data — the HTML is an empty shell and the script is the same code npm
+  serves. The page asks for a token and sends it itself, so every request that
+  *reads* anything is guarded and logged as usual. The two asset fetches are
+  not logged: they carry no token to attribute.
+- **The token lives in `sessionStorage`** — this tab only, never on the
+  server. Give it a `read` token (below) and the dashboard cannot reveal a
+  secret or change anything.
+- **The page shows only what is mounted.** It reads the manifest first and
+  builds a client per brick that actually described routes, so a deployment
+  without billing has no Money pages rather than pages that 404.
+- The script path is derived from the request, so the page works under a
+  `basePath`, under a moved `path`, and with or without a trailing slash.
+
+## Scoped tokens
+
+The `adminToken` you configure is the **root**: every scope, and the only
+credential that can issue or revoke tokens — a scoped token can never mint
+one. With a store (and the package's migrations), issue tokens for daily
+use and for the shell:
+
+```sh
+fonderie admin token issue dashboard --scopes read --days 90   # root token in FONDERIE_ADMIN_TOKEN
+fonderie admin token revoke <id>
+```
+
+| Scope | Allows |
+|---|---|
+| `read` | every `GET` — except anything under `/secrets` |
+| `write` | every mutation (plans, grants, templates, config, suspend, sign-out) — implies `read` |
+| `secrets` | anything under `/secrets`, including the plaintext reveal — implies both |
+
+The scope a route needs is derived from the route itself, never annotated.
+Only the token's hash is stored; the plaintext is shown once. A valid token
+short of the scope is `403`; an unknown, revoked or expired one is the same
+`401` as a missing one. In the admin log the actor is `token:<name>` unless
+`X-Actor` says otherwise. `GET /_admin/access/tokens` lists what was issued
+(never a hash). Without a store, only the root token works and issuing is
+off — the tokens page says `issued: null`.
+
 ## The admin log
 
 ```ts

package/brain/outcomes.md

@@ -25,6 +25,20 @@ request_id               TEXT
 client_ip                TEXT
 ```
 
+### `fonderie_admin_tokens`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+name                     TEXT NOT NULL
+token_hash               TEXT NOT NULL UNIQUE
+scopes                   TEXT[] NOT NULL
+created_by               TEXT NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+expires_at               TIMESTAMPTZ
+revoked_at               TIMESTAMPTZ
+last_used_at             TIMESTAMPTZ
+```
+
 Raw SQL ships in `node_modules/@fonderie/admin/dist/migrations/sql/` — read it there if you must; never download tarballs.
 
 ## HTTP routes registered
@@ -32,7 +46,9 @@ Raw SQL ships in `node_modules/@fonderie/admin/dist/migrations/sql/` — read it
 | Method | Path | Middleware chain (auth / validation / handler) |
 |---|---|---|
 | GET | `/_admin` | `async () => setApiResponse( HTTP.OK, 'ADMIN_ATTENTION', 'What needs attention', attention(app, await doctor()), )` |
-| GET | `/_admin/access/tokens` | `async () => setApiResponse(HTTP.OK, 'ADMIN_TOKENS', 'Admin tokens', tokensReport(app, this.name))` |
+| GET | `/_admin/access/tokens` | `async () => setApiResponse( HTTP.OK, 'ADMIN_TOKENS', 'Admin tokens', tokensReport(app, this.name, store ? await listTokens(store) : null), )` |
+| POST | `/_admin/access/tokens` | `[ validate(issueTokenSchema), async (ctx) => { const body = ctx.meta['body'] as { name: string; scopes: AdminScope[]; expiresInDays?: number; }; const createdBy = ctx.request.headers.get('x-actor') || 'admin-token'; const { token: plaintext, record } = await issueToken(store, { ...body, createdBy, }); // The plaintext is returned once and never stored. return setApiResponse(HTTP.CREATED, 'TOKEN_ISSUED', 'Token issued — shown once', { token: plaintext, ...record, }); }, ]` |
+| DELETE | `/_admin/access/tokens/:id` | `[ async (ctx) => { const ok = await revokeToken(store, ctx.meta.params?.['id'] ?? ''); return ok ? setApiResponse(HTTP.OK, 'TOKEN_REVOKED', 'Token revoked') : setApiResponse(HTTP.NOT_FOUND, 'NOT_FOUND', 'No such live token'); }, ]` |
 | GET | `/_admin/activity/admin-log` | `async (ctx) => { const q = new URL(ctx.request.url).searchParams; const limit = Number(q.get('limit')) || undefined; const before = q.get('before') ?? undefined; const page = await readAdminLog(store, { ...(limit ? { limit } : {}), ...(before ? { before } : {}), }); return setApiResponse(HTTP.OK, 'ADMIN_LOG', 'Admin activity', page); }` |
 | GET | `/_admin/config` | `async () => setApiResponse( HTTP.OK, 'ADMIN_CONFIG', 'Declared vs held', configReport(app, this.options.env ?? []), )` |
 | GET | `/_admin/doctor` | `async () => setApiResponse(HTTP.OK, 'ADMIN_DOCTOR', 'Reconciliation checks', await doctor())` |

package/brain/signatures.md

@@ -40,13 +40,30 @@ function configReport(app: IFonderieApp, env: string[]): IAdminConfigReport
 
 function routesReport(app: IFonderieApp, adminModule: string): IAdminRoutesReport
 
-function tokensReport(app: IFonderieApp, adminModule: string): IAdminTokensReport
+function tokensReport(app: IFonderieApp, adminModule: string, issued: IAdminTokenRecord[] | null): IAdminTokensReport
+
+function requireAdminScope(bootstrap: string, store: IStoreAdapter | undefined, needed: AdminScope | "root"): Middleware
+
+function scopeFor(method: string, path: string): AdminScope
+
+function grants(held: readonly AdminScope[], needed: AdminScope): boolean
+
+function issueToken(store: IStoreAdapter, input: { name: string; scopes: AdminScope[]; expiresInDays?: number; createdBy: string; }): Promise<{ token: string; record: IAdminTokenRecord; }>
+
+function revokeToken(store: IStoreAdapter, id: string): Promise<boolean>
+
+function listTokens(store: IStoreAdapter): Promise<IAdminTokenRecord[]>
+
+function hashToken(token: string): string
+
+const SCOPES: readonly AdminScope[]
 
 interface IAdminOptions {
     adminToken?: string;
     path?: string;
     checks?: IAdminCheck[];
     checkTimeoutMs?: number;
+    ui?: boolean;
     store?: IStoreAdapter;
     env?: string[];
 }
@@ -151,5 +168,19 @@ interface IAdminTokensReport {
         problems: IReadinessReport['problems'];
     };
     legacy: IAdminTokenEntry[];
+    issued: IAdminTokenRecord[] | null;
+}
+
+type AdminScope = 'read' | 'write' | 'secrets';
+
+interface IAdminTokenRecord {
+    id: string;
+    name: string;
+    scopes: AdminScope[];
+    createdBy: string;
+    createdAt: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
 }
 ```

package/dist/index.cjs

@@ -26,20 +26,33 @@ __export(index_exports, {
   DEFAULT_ADMIN_PATH: () => DEFAULT_ADMIN_PATH,
   DEFAULT_CHECK_TIMEOUT_MS: () => DEFAULT_CHECK_TIMEOUT_MS,
   MAX_PAGE: () => MAX_PAGE,
+  SCOPES: () => SCOPES,
   adminLog: () => adminLog,
   attention: () => attention,
   buildManifest: () => buildManifest,
   collectChecks: () => collectChecks,
   configReport: () => configReport,
+  grants: () => grants,
+  hashToken: () => hashToken,
+  issueToken: () => issueToken,
+  listTokens: () => listTokens,
   readAdminLog: () => readAdminLog,
+  requireAdminScope: () => requireAdminScope,
+  revokeToken: () => revokeToken,
   routesReport: () => routesReport,
   runDoctor: () => runDoctor,
+  scopeFor: () => scopeFor,
   tokensReport: () => tokensReport
 });
 module.exports = __toCommonJS(index_exports);
 
+// ../../node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
 // src/module.ts
-var import_core = require("@fonderie/core");
+var import_node_fs = require("fs");
+var import_core3 = require("@fonderie/core");
 var import_middlewares = require("@fonderie/core/middlewares");
 
 // src/doctor.ts
@@ -107,15 +120,19 @@ function attention(app, doctor) {
 }
 
 // src/log.ts
+var import_core = require("@fonderie/core");
 var DEFAULT_ACTOR = "admin-token";
 function adminLog(store, route, module2) {
   return async (ctx, next) => {
     const started = Date.now();
     const res = await next();
     const row = {
-      actor: ctx.request.headers.get("x-actor") || DEFAULT_ACTOR,
+      // A scoped token names itself; X-Actor refines it; the root token is 'admin-token'.
+      actor: ctx.request.headers.get("x-actor") || (typeof ctx.meta["adminTokenName"] === "string" ? `token:${ctx.meta["adminTokenName"]}` : DEFAULT_ACTOR),
       method: ctx.request.method,
-      path: new URL(ctx.request.url).pathname,
+      // Normalized, so '/x' and '/x/' are one row for one route — the same
+      // path the router matched and `route` below records the pattern of.
+      path: (0, import_core.normalizeRequestPath)(new URL(ctx.request.url).pathname),
       route,
       module: module2,
       status: res.status,
@@ -232,7 +249,7 @@ function routesReport(app, adminModule) {
     }))
   };
 }
-function tokensReport(app, adminModule) {
+function tokensReport(app, adminModule, issued) {
   const report = app.securityReport();
   const adminProblems = report.readiness.problems.filter((p) => p.module === adminModule);
   const legacyOwners = new Set(
@@ -241,7 +258,8 @@ function tokensReport(app, adminModule) {
   return {
     generatedAt: report.generatedAt,
     admin: { ok: !adminProblems.some((p) => p.severity === "error"), problems: adminProblems },
-    legacy: report.modules.map(({ name }) => ({ module: name, set: legacyOwners.has(name) })).filter((e) => e.set)
+    legacy: report.modules.map(({ name }) => ({ module: name, set: legacyOwners.has(name) })).filter((e) => e.set),
+    issued
   };
 }
 function isLegacyAdminPath(method, path) {
@@ -250,14 +268,127 @@ function isLegacyAdminPath(method, path) {
   return /\/billing\/wallet\/grant$/.test(path);
 }
 
+// src/tokens.ts
+var import_node_crypto = require("crypto");
+var import_core2 = require("@fonderie/core");
+var SCOPES = ["read", "write", "secrets"];
+function scopeFor(method, path) {
+  if (/\/secrets(\/|$)/.test(path)) return "secrets";
+  return method.toUpperCase() === "GET" ? "read" : "write";
+}
+function grants(held, needed) {
+  if (held.includes("secrets")) return true;
+  if (needed === "secrets") return false;
+  if (held.includes("write")) return true;
+  return needed === "read" && held.includes("read");
+}
+var hashToken = (token) => (0, import_node_crypto.createHash)("sha256").update(token).digest("hex");
+var mintToken = () => `fad_${(0, import_node_crypto.randomBytes)(24).toString("base64url")}`;
+var COLUMNS = `id, name, scopes, created_by AS "createdBy", created_at AS "createdAt",
+                 expires_at AS "expiresAt", revoked_at AS "revokedAt", last_used_at AS "lastUsedAt"`;
+async function listTokens(store) {
+  return store.query(
+    `SELECT ${COLUMNS} FROM fonderie_admin_tokens ORDER BY created_at DESC`
+  );
+}
+async function issueToken(store, input) {
+  const token = mintToken();
+  const expiresAt = input.expiresInDays ? new Date(Date.now() + input.expiresInDays * 864e5) : null;
+  const [record] = await store.query(
+    `INSERT INTO fonderie_admin_tokens (name, token_hash, scopes, created_by, expires_at)
+		 VALUES ($1, $2, $3, $4, $5) RETURNING ${COLUMNS}`,
+    [input.name, hashToken(token), input.scopes, input.createdBy, expiresAt]
+  );
+  if (!record) throw new Error("[admin] token insert returned no row");
+  return { token, record };
+}
+async function revokeToken(store, id) {
+  const rows = await store.query(
+    `UPDATE fonderie_admin_tokens SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL RETURNING id`,
+    [id]
+  );
+  return rows.length > 0;
+}
+async function findLive(store, token) {
+  const [row] = await store.query(
+    `SELECT ${COLUMNS} FROM fonderie_admin_tokens
+		  WHERE token_hash = $1 AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now())`,
+    [hashToken(token)]
+  );
+  return row ?? null;
+}
+var bearer = (ctx) => {
+  const h = ctx.request.headers.get("authorization") ?? "";
+  return h.startsWith("Bearer ") ? h.slice(7) : "";
+};
+var UNAUTHORIZED = () => (0, import_core2.setApiResponse)(import_core2.HTTP.UNAUTHORIZED, "UNAUTHORIZED", "Missing or invalid admin token");
+function requireAdminScope(bootstrap, store, needed) {
+  return async (ctx, next) => {
+    const token = bearer(ctx);
+    if (!token) return UNAUTHORIZED();
+    if ((0, import_core2.constantTimeEqual)(token, bootstrap)) return next();
+    if (needed === "root" || !store) return UNAUTHORIZED();
+    const record = await findLive(store, token);
+    if (!record) return UNAUTHORIZED();
+    if (!grants(record.scopes, needed)) {
+      return (0, import_core2.setApiResponse)(import_core2.HTTP.FORBIDDEN, "FORBIDDEN", `This token lacks the '${needed}' scope`);
+    }
+    ctx.meta["adminTokenName"] = record.name;
+    void store.query(`UPDATE fonderie_admin_tokens SET last_used_at = now() WHERE id = $1`, [record.id]).catch(() => void 0);
+    return next();
+  };
+}
+var issueTokenSchema = {
+  safeParse(input) {
+    const fail = (path, message) => ({
+      success: false,
+      error: { issues: [{ path: [path], message }] }
+    });
+    const b = input ?? {};
+    const name = typeof b["name"] === "string" ? b["name"].trim() : "";
+    if (!name || name.length > 100) return fail("name", "name is required (1\u2013100 chars)");
+    const scopes = b["scopes"];
+    if (!Array.isArray(scopes) || scopes.length === 0 || !scopes.every((s) => SCOPES.includes(s)))
+      return fail("scopes", `scopes must be a non-empty list of ${SCOPES.join(", ")}`);
+    const days = b["expiresInDays"];
+    if (days !== void 0 && (!Number.isInteger(days) || days < 1 || days > 3650))
+      return fail("expiresInDays", "expiresInDays must be an integer between 1 and 3650");
+    return {
+      success: true,
+      data: {
+        name,
+        scopes: [...new Set(scopes)],
+        ...days !== void 0 ? { expiresInDays: days } : {}
+      }
+    };
+  }
+};
+
+// src/ui/html.ts
+var uiHtml = (scriptPath) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Admin</title>
+<style>html,body{margin:0;background:#fff;color:#111}</style>
+</head>
+<body>
+<div id="root"></div>
+<script src="${scriptPath}" defer></script>
+</body>
+</html>
+`;
+
 // src/module.ts
 var DEFAULT_ADMIN_PATH = "/_admin";
 var DEFAULT_CHECK_TIMEOUT_MS = 1e4;
-var ADMIN_VERSION = "0.5.0";
+var ADMIN_VERSION = "0.7.0";
 var AdminModule = class {
   constructor(options = {}) {
     this.options = options;
-    this.path = (options.path ?? DEFAULT_ADMIN_PATH).replace(/\/+$/, "");
+    this.path = (0, import_core3.normalizeMountPath)(options.path ?? DEFAULT_ADMIN_PATH);
   }
   options;
   name = "@fonderie/admin";
@@ -267,7 +398,6 @@ var AdminModule = class {
     const token = this.options.adminToken;
     if (!token) return;
     app.reserve(this.path);
-    const guard = (0, import_middlewares.requireAdminToken)(token);
     const at = (p) => this.path + p.slice(DEFAULT_ADMIN_PATH.length);
     const store = this.options.store;
     const checks = collectChecks(app, this.options.checks ?? []);
@@ -277,8 +407,8 @@ var AdminModule = class {
       [
         "GET",
         "/_admin",
-        async () => (0, import_core.setApiResponse)(
-          import_core.HTTP.OK,
+        async () => (0, import_core3.setApiResponse)(
+          import_core3.HTTP.OK,
           "ADMIN_ATTENTION",
           "What needs attention",
           attention(app, await doctor())
@@ -287,8 +417,8 @@ var AdminModule = class {
       [
         "GET",
         "/_admin/manifest",
-        async () => (0, import_core.setApiResponse)(
-          import_core.HTTP.OK,
+        async () => (0, import_core3.setApiResponse)(
+          import_core3.HTTP.OK,
           "ADMIN_MANIFEST",
           "Deployment manifest",
           buildManifest(app, { version: this.version, log: Boolean(store) })
@@ -297,13 +427,13 @@ var AdminModule = class {
       [
         "GET",
         "/_admin/doctor",
-        async () => (0, import_core.setApiResponse)(import_core.HTTP.OK, "ADMIN_DOCTOR", "Reconciliation checks", await doctor())
+        async () => (0, import_core3.setApiResponse)(import_core3.HTTP.OK, "ADMIN_DOCTOR", "Reconciliation checks", await doctor())
       ],
       [
         "GET",
         "/_admin/config",
-        async () => (0, import_core.setApiResponse)(
-          import_core.HTTP.OK,
+        async () => (0, import_core3.setApiResponse)(
+          import_core3.HTTP.OK,
           "ADMIN_CONFIG",
           "Declared vs held",
           configReport(app, this.options.env ?? [])
@@ -312,12 +442,17 @@ var AdminModule = class {
       [
         "GET",
         "/_admin/routes",
-        async () => (0, import_core.setApiResponse)(import_core.HTTP.OK, "ADMIN_ROUTES", "Exposed routes", routesReport(app, this.name))
+        async () => (0, import_core3.setApiResponse)(import_core3.HTTP.OK, "ADMIN_ROUTES", "Exposed routes", routesReport(app, this.name))
       ],
       [
         "GET",
         "/_admin/access/tokens",
-        async () => (0, import_core.setApiResponse)(import_core.HTTP.OK, "ADMIN_TOKENS", "Admin tokens", tokensReport(app, this.name))
+        async () => (0, import_core3.setApiResponse)(
+          import_core3.HTTP.OK,
+          "ADMIN_TOKENS",
+          "Admin tokens",
+          tokensReport(app, this.name, store ? await listTokens(store) : null)
+        )
       ]
     ];
     if (store) {
@@ -332,12 +467,43 @@ var AdminModule = class {
             ...limit ? { limit } : {},
             ...before ? { before } : {}
           });
-          return (0, import_core.setApiResponse)(import_core.HTTP.OK, "ADMIN_LOG", "Admin activity", page);
+          return (0, import_core3.setApiResponse)(import_core3.HTTP.OK, "ADMIN_LOG", "Admin activity", page);
         }
       ]);
     }
+    const rootOnly = store ? [
+      [
+        "POST",
+        "/_admin/access/tokens",
+        [
+          (0, import_middlewares.validate)(issueTokenSchema),
+          async (ctx) => {
+            const body = ctx.meta["body"];
+            const createdBy = ctx.request.headers.get("x-actor") || "admin-token";
+            const { token: plaintext, record } = await issueToken(store, {
+              ...body,
+              createdBy
+            });
+            return (0, import_core3.setApiResponse)(import_core3.HTTP.CREATED, "TOKEN_ISSUED", "Token issued \u2014 shown once", {
+              token: plaintext,
+              ...record
+            });
+          }
+        ]
+      ],
+      [
+        "DELETE",
+        "/_admin/access/tokens/:id",
+        [
+          async (ctx) => {
+            const ok = await revokeToken(store, ctx.meta.params?.["id"] ?? "");
+            return ok ? (0, import_core3.setApiResponse)(import_core3.HTTP.OK, "TOKEN_REVOKED", "Token revoked") : (0, import_core3.setApiResponse)(import_core3.HTTP.NOT_FOUND, "NOT_FOUND", "No such live token");
+          }
+        ]
+      ]
+    ] : [];
     const mounted = /* @__PURE__ */ new Map();
-    const mount = (module2, method, path, handlers) => {
+    const mount = (module2, method, path, handlers, needed) => {
       const key = `${method.toUpperCase()} ${path}`;
       const prior = mounted.get(key);
       if (prior) {
@@ -346,10 +512,46 @@ var AdminModule = class {
         );
       }
       mounted.set(key, module2);
+      const guard = requireAdminScope(token, store, needed ?? scopeFor(method, path));
       const chain = store ? [adminLog(store, path, module2), guard, ...handlers] : [guard, ...handlers];
       app.addRoute(method, path, ...chain);
     };
+    if (this.options.ui) {
+      const scriptPath = at("/_admin/ui/app.js");
+      let js = null;
+      const loadJs = () => {
+        if (js === null) {
+          try {
+            js = (0, import_node_fs.readFileSync)(new URL("./ui/app.global.js", importMetaUrl), "utf8");
+          } catch {
+            js = "";
+          }
+        }
+        return js || null;
+      };
+      app.addRoute("GET", at("/_admin/ui"), async (ctx) => {
+        const here = (0, import_core3.normalizeRequestPath)(new URL(ctx.request.url).pathname);
+        return new Response(uiHtml(`${here}/app.js`), {
+          headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }
+        });
+      });
+      app.addRoute("GET", scriptPath, async () => {
+        const body = loadJs();
+        return body ? new Response(body, {
+          headers: {
+            "content-type": "text/javascript; charset=utf-8",
+            "cache-control": "public, max-age=300"
+          }
+        }) : (0, import_core3.setApiResponse)(
+          import_core3.HTTP.SERVICE_UNAVAILABLE,
+          "UI_NOT_BUILT",
+          "This copy of @fonderie/admin has no built dashboard (dist/ui). Install the published package, or run its build."
+        );
+      });
+    }
     for (const [method, path, handler] of own) mount(this.name, method, at(path), [handler]);
+    for (const [method, path, handlers] of rootOnly)
+      mount(this.name, method, at(path), handlers, "root");
     for (const { module: module2, description } of app.adminDescriptions()) {
       for (const r of description.routes ?? [])
         mount(module2, r.method, this.path + r.path, r.handlers);
@@ -367,14 +569,22 @@ var AdminModule = class {
   DEFAULT_ADMIN_PATH,
   DEFAULT_CHECK_TIMEOUT_MS,
   MAX_PAGE,
+  SCOPES,
   adminLog,
   attention,
   buildManifest,
   collectChecks,
   configReport,
+  grants,
+  hashToken,
+  issueToken,
+  listTokens,
   readAdminLog,
+  requireAdminScope,
+  revokeToken,
   routesReport,
   runDoctor,
+  scopeFor,
   tokensReport
 });
 //# sourceMappingURL=index.cjs.map