@humwick/server 0.130.1 → 0.130.2

package/node_modules/@humwick/kernel/control-authz.ts

@@ -1,281 +0,0 @@
-import type { OpenAPIHono } from "@hono/zod-openapi";
-import type { Context } from "hono";
-import type { Grant, ResolvedIdentity } from "./contract";
-import type { InvocationIdentity, ModuleHost } from "./module-host";
-import { type HttpTransportOptions, type IdentityResolver, createHttpApp } from "./http-transport";
-import {
-  type ControlModule,
-  CONTROL_ADMIN_GRANT,
-  CONTROL_READ_GRANT,
-  CONTROL_WRITE_GRANT,
-  SYSTEM_ADMIN_GRANT,
-} from "./control";
-
-/**
- * K1-6 — the control-module scope→grant bridge + fail-closed edge identity for the `/api/kernel`
- * transport. The kernel invoker is default-deny over FLAT, EXACT grants (`admin` does NOT imply
- * `read`/`write` — see `identity.ts:isAuthorized`) and carries no cwd constraints, so the transport
- * edge must translate the caller's authenticated scopes into the exact grants the control ops declare
- * before an op is invoked — exactly as the timers pilot does at its MCP boundary
- * (`src/services/kernel-timers-authz.ts:timerInvocationIdentity`).
- *
- * ── O2 — the admin-token expansion (why a bare admin scope is not enough) ───────────────────────────
- * Under the exact-grant model an identity holding ONLY `control:admin` (or `system:admin`) 403s on
- * every exposed op: `listInstances` requires `control:read`, `cancel` requires `control:write`, and
- * neither is implied by an admin grant. So an admin token MUST expand to `control:read + control:write`
- * PLUS the admin grant — mirroring the timers bridge's `admin ⇒ timers:write + timers:read`. Only then
- * can an admin identity actually invoke the read + control surface (not merely the `*System` twins).
- *
- * ── G-M2 / O4 — fail-closed, per-user, no blanket admin (#389 avoidance) ────────────────────────────
- * {@link controlHttpIdentity} resolves a PER-USER identity from the request and returns a NO-GRANT
- * identity when the request carries no control-scoped credential — so an anonymous/unauthenticated
- * request yields `{grants: []}` and the invoker 403s it (G-M2). It deliberately does NOT reuse the src
- * `authContextFromRequest` fallback, which maps a credential-less request to a full-reach `*` system
- * principal (the #389 route fail-open): mounting the derived app must resolve real caller scopes, never
- * a server-side superuser (O4). The token-reading step is injected (the src mount supplies it), keeping
- * this mapping transport-scope-driven and testable in isolation.
- */
-
-/** The authenticated caller facts the bridge maps to grants: WHO (actor) and WHAT scopes the token
- *  carries. `resolvedIdentity` is the opaque server-resolved creator blob carried through verbatim for
- *  durable-effect identity freezing (P2-7), never interpreted here. */
-export interface ControlAuthClaims {
-  readonly actor: string;
-  readonly scopes: readonly string[];
-  readonly resolvedIdentity?: ResolvedIdentity;
-}
-
-/** A module-private brand. It is a real runtime symbol (so the mint can stamp it) but is NEVER
- *  exported, so no code outside this file can reference it — which is exactly what makes
- *  {@link VerifiedControlClaims} unforgeable from a raw object literal. */
-const VERIFIED_BRAND: unique symbol = Symbol("kernel.control.verifiedClaims");
-
-/**
- * {@link ControlAuthClaims} that have been minted from a verified token — the ONLY value type the control
- * mount's claims-resolver ({@link VerifiedClaimsResolver}) may return, and the ONLY shape
- * {@link createControlHttpApp} accepts. The brand cannot be produced from an object literal
- * (`VERIFIED_BRAND` is module-private), and the low-level mint is itself un-exported (W4d), so the ONLY
- * mint out-of-kernel code can reach is {@link controlClaimsFromComponentToken}. A future `/api/kernel`
- * mount therefore physically cannot hand the mount a bag of fields it scraped off a request header: it
- * must present a verified {@link VerifiedComponentToken}, whose derivation is the explicit, reviewable
- * "these are VERIFIED, server-resolved facts — from `getComponentAuth`, not a spoofable `actor` header"
- * assertion (§4.1/§4.2, #389 avoidance). */
-export interface VerifiedControlClaims extends ControlAuthClaims {
-  readonly [VERIFIED_BRAND]: true;
-}
-
-/**
- * The low-level mint for {@link VerifiedControlClaims}. MODULE-PRIVATE by design (W4d, W4b-http finding 1):
- * it is deliberately NOT exported, so the only mint reachable from out-of-kernel code is
- * {@link controlClaimsFromComponentToken}, which forces the caller to present a token-shaped
- * {@link VerifiedComponentToken} rather than an arbitrary `{actor, scopes}` bag. That closes the footgun
- * where a future mount could hand-mint a `control:admin` grant from client-controlled `actor`/`scopes`
- * fields it scraped off a request. This function does NOT itself verify anything — verification is the
- * caller's earlier step; the brand only guarantees a resolver can reach {@link createControlHttpApp} ONLY
- * by passing through the explicit token-derivation gate, so the misuse is never silent. The scopes still
- * flow through the fail-closed {@link controlGrantsForScopes} allowlist downstream, so even an over-broad
- * claim can only earn the exact grants that map. */
-function verifiedControlClaims(claims: ControlAuthClaims): VerifiedControlClaims {
-  return {
-    actor: claims.actor,
-    scopes: claims.scopes,
-    ...(claims.resolvedIdentity ? { resolvedIdentity: claims.resolvedIdentity } : {}),
-    [VERIFIED_BRAND]: true,
-  };
-}
-
-/**
- * The minimal shape of a VERIFIED component token the control mount derives its claims from (sol
- * finding 1). A `/api/kernel` mount must produce this ONLY from a signature+revocation-verified
- * component token (the src edge reads it from `getComponentAuth(req)`); a missing/invalid/non-component
- * credential yields no token at all and the resolver denies. The kernel treats `constraints` as an
- * opaque blob — it never interprets it (the src edge derives the caller-agent from it).
- */
-export interface VerifiedComponentToken {
-  /** The token subject (`sub`) — the default actor when no finer caller-agent resolves. */
-  readonly sub: string;
-  /** The token's authenticated transport scopes. These become the claims' scopes VERBATIM — the only
-   *  source of scope authority, so a client can never inject a scope through a header/body/query. */
-  readonly scope?: readonly string[];
-  /** The token's opaque signed constraint blob (agent/cwd axes). Server-resolved; never client-named. */
-  readonly constraints?: Readonly<Record<string, unknown>>;
-}
-
-/**
- * Derive branded {@link VerifiedControlClaims} STRICTLY from a verified {@link VerifiedComponentToken}
- * — the sol-finding-1 strengthening of the guard. The point: `actor`, `scopes`, and `resolvedIdentity`
- * all originate in the verified token, NEVER in arbitrary caller-supplied fields:
- *
- *   • `scopes`           ← `token.scope` verbatim (a client cannot name its own scope).
- *   • `resolvedIdentity` ← the token's own kind/scopes/constraints (server-resolved; frozen for P2-7).
- *   • `actor`            ← `resolveActor(token)`, which receives ONLY the token (not the request), so a
- *                          mount cannot read a spoofable `x-actor` header here. The src mount passes
- *                          `resolveCallerAgentId(token.constraints, …) ?? token.sub` (the resolver
- *                          contract), deriving the caller-agent solely from the token's signed
- *                          constraints.
- *
- * Because `resolveActor` is handed the token and nothing else, and scopes/resolvedIdentity are read off
- * the token directly, there is no path from a header/body/query value into the resulting claims — the
- * spoof surface #389 warns about is closed at the mint, not merely at the branding gate. The scopes
- * still flow through the fail-closed {@link controlGrantsForScopes} allowlist downstream, so an
- * over-broad token still only earns the exact grants that map.
- */
-export function controlClaimsFromComponentToken(
-  token: VerifiedComponentToken,
-  resolveActor: (token: VerifiedComponentToken) => string,
-): VerifiedControlClaims {
-  return verifiedControlClaims({
-    actor: resolveActor(token),
-    scopes: token.scope ?? [],
-    resolvedIdentity: {
-      kind: "component",
-      ...(token.scope ? { scopes: token.scope } : {}),
-      ...(token.constraints ? { constraints: token.constraints } : {}),
-    },
-  });
-}
-
-/** The per-request claims producer {@link createControlHttpApp} requires: it returns VERIFIED claims or
- *  `null` (⇒ anonymous default-deny). Typed to a {@link VerifiedControlClaims} producer, NOT a raw
- *  {@link IdentityResolver} — the mount cannot supply an arbitrary `(c)=>InvocationIdentity` and thereby
- *  hand-pick grants (e.g. mapping an anonymous caller straight to `control:admin`); every identity is
- *  forced through the branded-claims → {@link controlGrantsForScopes} allowlist path. */
-export type VerifiedClaimsResolver = (c: Context) => VerifiedControlClaims | null;
-
-/** The deny identity an anonymous/credential-less edge request resolves to: a valid actor label with
- *  ZERO grants, so the invoker's default-deny 403s it before any handler runs (G-M2). */
-const ANONYMOUS_DENY: InvocationIdentity = Object.freeze({ actor: "anonymous", grants: [] as readonly Grant[] });
-
-/**
- * Map a caller's authenticated transport scopes to the exact kernel grants the control ops declare
- * (O2). Fail-closed: an unrecognized scope contributes nothing, and an empty/absent scope set yields
- * NO grants (⇒ default-deny 403). The two admin scopes expand to the full read+control grant set so an
- * admin identity can actually invoke the exposed surface, not just cross-creator-reach it:
- *
- *   `control:read`  ⇒ control:read
- *   `control:write` ⇒ control:write
- *   `control:admin` ⇒ control:admin + control:read + control:write   (module-matched admin; reaches all)
- *   `system:admin`  ⇒ system:admin  + control:read + control:write   (global admin; crosses creators)
- *
- * The `*System` twins are NOT reachable via any grant here — they carry `expose.mcp/http/cli:false`
- * and so are excluded from every transport derivation (K-C2 / O1); grants alone never surface them.
- */
-export function controlGrantsForScopes(scopes: Iterable<string>): Grant[] {
-  const held = new Set<string>(scopes);
-  const grants = new Set<Grant>();
-  const isAdmin = held.has(CONTROL_ADMIN_GRANT) || held.has(SYSTEM_ADMIN_GRANT);
-  if (held.has(CONTROL_READ_GRANT)) grants.add(CONTROL_READ_GRANT);
-  if (held.has(CONTROL_WRITE_GRANT)) grants.add(CONTROL_WRITE_GRANT);
-  if (isAdmin) {
-    // O2: an admin token must hold the entry grants the exposed ops gate on, or it 403s on every one.
-    grants.add(CONTROL_READ_GRANT);
-    grants.add(CONTROL_WRITE_GRANT);
-  }
-  if (held.has(CONTROL_ADMIN_GRANT)) grants.add(CONTROL_ADMIN_GRANT);
-  if (held.has(SYSTEM_ADMIN_GRANT)) grants.add(SYSTEM_ADMIN_GRANT);
-  return [...grants];
-}
-
-/**
- * Build the per-request {@link InvocationIdentity} for the control transport from authenticated claims:
- * the actor becomes the kernel owner key (the per-creator ownership basis, exactly the timers
- * `callerAgentId ?? actor.id` precedent) and the scopes map to grants via {@link controlGrantsForScopes}.
- * A caller with no control scopes gets an empty grant set (default-deny). The trusted server-resolved
- * `resolvedIdentity` rides through verbatim — never anything the client named.
- */
-export function controlInvocationIdentity(claims: ControlAuthClaims): InvocationIdentity {
-  return {
-    actor: claims.actor,
-    grants: controlGrantsForScopes(claims.scopes),
-    ...(claims.resolvedIdentity ? { resolvedIdentity: claims.resolvedIdentity } : {}),
-  };
-}
-
-/**
- * The fail-closed {@link IdentityResolver} the control transport runs. `resolveClaims` reads the REAL
- * caller from the request as VERIFIED claims (the src mount injects a reader over the component token —
- * NOT `authContextFromRequest`, whose credential-less `*` fallback is the #389 fail-open); returning
- * `null` means "no authenticated control caller", which resolves to the zero-grant {@link ANONYMOUS_DENY}
- * identity ⇒ the invoker 403s (G-M2). It requires a {@link VerifiedClaimsResolver}, so there is no path
- * that hand-picks grants or mints a blanket-admin identity for the app (O4): every non-anonymous
- * identity is the caller's own, scoped to exactly the grants {@link controlGrantsForScopes} maps.
- * Prefer {@link createControlHttpApp}, which wires this internally and never exposes a raw `identify`.
- */
-export function controlHttpIdentity(resolveClaims: VerifiedClaimsResolver): IdentityResolver {
-  return (c: Context): InvocationIdentity => {
-    const claims = resolveClaims(c);
-    if (claims === null) return ANONYMOUS_DENY;
-    return controlInvocationIdentity(claims);
-  };
-}
-
-/**
- * The SAFE-by-construction way to mount the control module over HTTP (the export the `/api/kernel` src
- * mount must consume). It wraps {@link createHttpApp} and wires {@link controlHttpIdentity} internally,
- * so the control app's `identify` is not caller-supplied: a mount CANNOT pass a raw
- * `(c)=>InvocationIdentity` and thereby (a) map an unauthenticated/`system` principal directly to a
- * recognized admin grant, nor (b) fabricate grants from a spoofable header — the only knob it exposes is
- * `resolveClaims`, a {@link VerifiedClaimsResolver} that must return branded {@link VerifiedControlClaims}
- * (mintable only via the explicit {@link verifiedControlClaims} gate) whose scopes then flow through the
- * fail-closed {@link controlGrantsForScopes} allowlist. `options` intentionally omits `identify`; the
- * remaining {@link HttpTransportOptions} (docPath / serveOpenApiDoc / info) pass through unchanged.
- *
- * ── §2.4 — the OpenAPI doc is scope-gated, not served to any authenticated caller ──────────────────────
- * The generic {@link createHttpApp} serves its OpenAPI document from an UNAUTHENTICATED route
- * (`app.doc(...)`), which is route + schema disclosure. On the control mount that is too open: the outer
- * coarse gate treats a bare `*` (wildcard) token as universal, so it clears that gate — yet `*` maps to
- * ZERO control grants through {@link controlGrantsForScopes} (which does NOT expand `*`), so it could
- * still read the full spec while being 403'd on every op. So this wrapper WITHHOLDS the built-in doc route
- * (`serveOpenApiDoc:false` to `createHttpApp`) and re-serves the document behind
- * {@link mountGatedControlDoc}, which runs the SAME {@link VerifiedClaimsResolver} the op routes do: only a
- * caller whose verified claims earn at least one control grant receives the document; anonymous /
- * no-control-grant callers get 403 — the identical fail-closed floor the op surface enforces.
- */
-export function createControlHttpApp(
-  host: ModuleHost,
-  control: ControlModule,
-  resolveClaims: VerifiedClaimsResolver,
-  options: Omit<HttpTransportOptions, "identify"> = {},
-): OpenAPIHono {
-  const serveDoc = options.serveOpenApiDoc !== false;
-  const docPath = options.docPath ?? "/openapi.json";
-  const app = createHttpApp(host, control, {
-    ...options,
-    identify: controlHttpIdentity(resolveClaims),
-    // Withhold the built-in UNAUTHENTICATED doc route; the scope-gated route below replaces it (§2.4).
-    serveOpenApiDoc: false,
-  });
-  if (serveDoc) mountGatedControlDoc(app, control, resolveClaims, docPath, options.info);
-  return app;
-}
-
-/**
- * Serve the control OpenAPI document ONLY to a caller whose VERIFIED claims earn at least one control
- * grant (§2.4). This closes the last unauthenticated read on the control mount: a null (anonymous)
- * resolver result OR a scope set that maps — through the fail-closed {@link controlGrantsForScopes}
- * allowlist — to ZERO control grants (e.g. a bare `*` token that cleared the outer coarse gate but which
- * `*` does not expand into any control grant) is 403'd, exactly as the op routes 403 a zero-grant identity.
- * A real control scope — including `control:admin`/`system:admin`, which the allowlist expands — IS served.
- * The document is byte-identical to the served surface (`getOpenAPIDocument` walks the same registered
- * routes). The doc route itself is not OpenAPI-registered, so it never appears in the spec.
- */
-function mountGatedControlDoc(
-  app: OpenAPIHono,
-  control: ControlModule,
-  resolveClaims: VerifiedClaimsResolver,
-  docPath: string,
-  info: HttpTransportOptions["info"],
-): void {
-  let cachedDoc: unknown;
-  app.get(docPath, (c: Context) => {
-    const claims = resolveClaims(c);
-    if (claims === null || controlGrantsForScopes(claims.scopes).length === 0) {
-      return c.json({ error: { code: "unauthorized", message: "kernel control document requires a control scope" } }, 403);
-    }
-    cachedDoc ??= app.getOpenAPIDocument({
-      openapi: "3.0.0",
-      info: { title: info?.title ?? control.title, version: info?.version ?? "0.0.0" },
-    });
-    return c.json(cachedDoc as never);
-  });
-}