@forgezero/access 0.1.0 → 0.1.2

package/README.md

@@ -66,10 +66,50 @@ integration suite.
 | `/client` | the browser half, including the 428 replay |
 | `/testing` | decide without a server |
 | `/pipeline` · `/authenticator` | the resolver, and WebAuthn |
+| `/header` | verified header identities with fresh, host-owned RBAC assignments |
+| `/principal` | generic multi-assignment principals, route groups, methods and expiry |
+| `/principal-session` | short-lived server sessions bound to an opaque client identity |
+
+Header identities are a separate principal, not a browser session. A source
+verifier authenticates one configured header and returns only a stable subject;
+the host resolves that subject's role assignments on every request. Roles are
+never accepted from the header value, and a header principal cannot satisfy a
+session or fresh-action factor. Multiple source adapters can coexist, but a
+request presenting more than one source is refused as ambiguous.
+
+`accessGroup` is the single open, host-defined route classification used by
+generic principal assignments—`public`, `user`, `admin`, `custody`,
+`orchestration`, or any future product vocabulary. Session policies remain the
+generic package's authentication boundary; ForgeZero additionally requires its
+`public` group to use anonymous authentication and rejects contradictions at
+boot. The package does not hard-code a purpose or identity type.
 
-Full documentation: **https://forgezero.net/docs/access**
+```ts
+import { headerIdentityResolver } from '@forgezero/access/header';
+import { decidePrincipalAccess } from '@forgezero/access/principal';
+
+const resolveHeader = headerIdentityResolver(
+  [{
+    key: 'partner-sso',
+    header: 'x-partner-identity',
+    verify: ({ value, request }) => verifyPartnerAssertion(value, request)
+  }],
+  // Read the current admin/custodian assignment. Do not cache it in the token.
+  ({ principalKey }) => memberships.assignments(principalKey)
+);
+
+const principal = await resolveHeader(request);
+const decision = decidePrincipalAccess({
+  access, principal, roles: await policy.roles(), routeKey: 'api/orders/write', method: 'POST'
+});
+if (!decision.allow) {
+  return new Response('Forbidden', { status: 403 });
+}
+```
+
+Full documentation: **https://www.forgezero.net/docs/access**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys — and usable entirely on its own, with no ForgeZero account.

package/dist/conditions.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }
@@ -288,7 +291,10 @@ function required(state, name, condition) {
 function loadTarget(options) {
   const as = options.as ?? "target";
   const code = options.code ?? "NOT_FOUND";
-  const readId = options.id ?? ((context) => context.params.id);
+  const readId = options.id ?? ((context) => {
+    const id = context.params.id;
+    return typeof id === "string" ? id : undefined;
+  });
   return define("loadTarget", options.routes, [{ status: 404, code, when: "no record matches the identifier" }], async (context) => {
     const id = readId(context);
     if (!id)

package/dist/effects.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }

package/dist/elysia.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }
@@ -286,6 +289,46 @@ function defineHandlers(routes, handlers) {
   }
   return handlers;
 }
+function recordFromValidator(value, part) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  throw new AccessError("VALIDATOR_RESULT_INVALID", `The validator returned an unusable ${part} value.`);
+}
+function headersFromValidator(value) {
+  try {
+    return new Headers(value);
+  } catch {
+    throw new AccessError("VALIDATOR_RESULT_INVALID", "The validator returned an unusable headers value.");
+  }
+}
+function urlWithQuery(url, query) {
+  const validated = new URL(url);
+  validated.search = "";
+  for (const [name, value] of Object.entries(query)) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const item of values) {
+      if (item !== undefined && item !== null)
+        validated.searchParams.append(name, String(item));
+    }
+  }
+  return validated;
+}
+async function responsePayload(response, routeKey) {
+  let text;
+  try {
+    text = await response.clone().text();
+  } catch {
+    throw new AccessError("RESPONSE_UNREADABLE", `"${routeKey}" returned a response that could not be inspected.`);
+  }
+  if (text.length === 0)
+    return;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new AccessError("RESPONSE_NOT_JSON", `"${routeKey}" returned a non-JSON body for a declared response.`);
+  }
+}
 var WINDOWS = { s: 1, m: 60, h: 3600, d: 86400 };
 function windowSeconds(window) {
   const match = /^(\d+)([smhd])$/.exec(window);
@@ -370,13 +413,15 @@ function createPipeline(options) {
       }
     }
     let body;
-    const query = Object.fromEntries(url.searchParams);
+    let validatedParams = params;
+    let validatedQuery = Object.fromEntries(url.searchParams);
+    let validatedHeaders = new Headers(request.headers);
     if (validator) {
       const checks = [];
       if (route.params)
         checks.push(["params", route.params, params]);
       if (route.query)
-        checks.push(["query", route.query, query]);
+        checks.push(["query", route.query, validatedQuery]);
       if (route.headers)
         checks.push(["headers", route.headers, Object.fromEntries(request.headers)]);
       if (route.body) {
@@ -393,8 +438,20 @@ function createPipeline(options) {
             errors: result2.errors
           });
         }
-        if (where === "body")
-          body = result2.value;
+        switch (where) {
+          case "params":
+            validatedParams = recordFromValidator(result2.value, "params");
+            break;
+          case "query":
+            validatedQuery = recordFromValidator(result2.value, "query");
+            break;
+          case "headers":
+            validatedHeaders = headersFromValidator(result2.value);
+            break;
+          case "body":
+            body = result2.value;
+            break;
+        }
       }
     } else if (route.body) {
       body = await request.json().catch(() => {
@@ -404,11 +461,11 @@ function createPipeline(options) {
     const context = {
       route: routeKey,
       method: route.method,
-      url,
-      params,
-      query,
+      url: route.query && validator ? urlWithQuery(url, validatedQuery) : url,
+      params: validatedParams,
+      query: validatedQuery,
       body,
-      headers: request.headers,
+      headers: validatedHeaders,
       session,
       realm,
       stage,
@@ -508,16 +565,19 @@ function createPipeline(options) {
     }
     const result = await (telemetry ? telemetry.span("handler", { "access.route": routeKey }, async () => handler(context, state)) : handler(context, state));
     if (validateResponses && validator && route.response) {
-      const schema = route.response[200];
-      if (schema && !(result instanceof Response)) {
-        const check = validator.validate(schema, result);
-        if (!check.ok) {
-          throw new AccessError("RESPONSE_MISMATCH", `"${routeKey}" returned a shape it does not declare: ${check.errors[0]?.message}`);
-        }
+      const status = result instanceof Response ? result.status : 200;
+      const schema = route.response[status];
+      if (!schema) {
+        throw new AccessError("RESPONSE_STATUS_UNDECLARED", `"${routeKey}" returned undeclared status ${status}.`);
+      }
+      const payload = result instanceof Response ? await responsePayload(result, routeKey) : result;
+      const check = validator.validate(schema, payload);
+      if (!check.ok) {
+        throw new AccessError("RESPONSE_MISMATCH", `"${routeKey}" returned status ${status} with a body that does not match its declaration.`);
       }
     }
     runAfter(result);
-    record({ "access.outcome": "allowed", "access.status": 200 });
+    record({ "access.outcome": "allowed", "access.status": result instanceof Response ? result.status : 200 });
     return result instanceof Response ? result : new Response(JSON.stringify(result), { headers: { "content-type": "application/json" } });
   };
 }

package/dist/fetch.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }
@@ -286,6 +289,46 @@ function defineHandlers(routes, handlers) {
   }
   return handlers;
 }
+function recordFromValidator(value, part) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  throw new AccessError("VALIDATOR_RESULT_INVALID", `The validator returned an unusable ${part} value.`);
+}
+function headersFromValidator(value) {
+  try {
+    return new Headers(value);
+  } catch {
+    throw new AccessError("VALIDATOR_RESULT_INVALID", "The validator returned an unusable headers value.");
+  }
+}
+function urlWithQuery(url, query) {
+  const validated = new URL(url);
+  validated.search = "";
+  for (const [name, value] of Object.entries(query)) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const item of values) {
+      if (item !== undefined && item !== null)
+        validated.searchParams.append(name, String(item));
+    }
+  }
+  return validated;
+}
+async function responsePayload(response, routeKey) {
+  let text;
+  try {
+    text = await response.clone().text();
+  } catch {
+    throw new AccessError("RESPONSE_UNREADABLE", `"${routeKey}" returned a response that could not be inspected.`);
+  }
+  if (text.length === 0)
+    return;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new AccessError("RESPONSE_NOT_JSON", `"${routeKey}" returned a non-JSON body for a declared response.`);
+  }
+}
 var WINDOWS = { s: 1, m: 60, h: 3600, d: 86400 };
 function windowSeconds(window) {
   const match = /^(\d+)([smhd])$/.exec(window);
@@ -370,13 +413,15 @@ function createPipeline(options) {
       }
     }
     let body;
-    const query = Object.fromEntries(url.searchParams);
+    let validatedParams = params;
+    let validatedQuery = Object.fromEntries(url.searchParams);
+    let validatedHeaders = new Headers(request.headers);
     if (validator) {
       const checks = [];
       if (route.params)
         checks.push(["params", route.params, params]);
       if (route.query)
-        checks.push(["query", route.query, query]);
+        checks.push(["query", route.query, validatedQuery]);
       if (route.headers)
         checks.push(["headers", route.headers, Object.fromEntries(request.headers)]);
       if (route.body) {
@@ -393,8 +438,20 @@ function createPipeline(options) {
             errors: result2.errors
           });
         }
-        if (where === "body")
-          body = result2.value;
+        switch (where) {
+          case "params":
+            validatedParams = recordFromValidator(result2.value, "params");
+            break;
+          case "query":
+            validatedQuery = recordFromValidator(result2.value, "query");
+            break;
+          case "headers":
+            validatedHeaders = headersFromValidator(result2.value);
+            break;
+          case "body":
+            body = result2.value;
+            break;
+        }
       }
     } else if (route.body) {
       body = await request.json().catch(() => {
@@ -404,11 +461,11 @@ function createPipeline(options) {
     const context = {
       route: routeKey,
       method: route.method,
-      url,
-      params,
-      query,
+      url: route.query && validator ? urlWithQuery(url, validatedQuery) : url,
+      params: validatedParams,
+      query: validatedQuery,
       body,
-      headers: request.headers,
+      headers: validatedHeaders,
       session,
       realm,
       stage,
@@ -508,16 +565,19 @@ function createPipeline(options) {
     }
     const result = await (telemetry ? telemetry.span("handler", { "access.route": routeKey }, async () => handler(context, state)) : handler(context, state));
     if (validateResponses && validator && route.response) {
-      const schema = route.response[200];
-      if (schema && !(result instanceof Response)) {
-        const check = validator.validate(schema, result);
-        if (!check.ok) {
-          throw new AccessError("RESPONSE_MISMATCH", `"${routeKey}" returned a shape it does not declare: ${check.errors[0]?.message}`);
-        }
+      const status = result instanceof Response ? result.status : 200;
+      const schema = route.response[status];
+      if (!schema) {
+        throw new AccessError("RESPONSE_STATUS_UNDECLARED", `"${routeKey}" returned undeclared status ${status}.`);
+      }
+      const payload = result instanceof Response ? await responsePayload(result, routeKey) : result;
+      const check = validator.validate(schema, payload);
+      if (!check.ok) {
+        throw new AccessError("RESPONSE_MISMATCH", `"${routeKey}" returned status ${status} with a body that does not match its declaration.`);
       }
     }
     runAfter(result);
-    record({ "access.outcome": "allowed", "access.status": 200 });
+    record({ "access.outcome": "allowed", "access.status": result instanceof Response ? result.status : 200 });
     return result instanceof Response ? result : new Response(JSON.stringify(result), { headers: { "content-type": "application/json" } });
   };
 }

package/dist/header.d.ts

@@ -0,0 +1,41 @@
+import { type PrincipalAssignment, type RbacPrincipal } from './principal';
+export interface HeaderIdentity {
+    subject: string;
+    /** Authentication facts established by the source, never RBAC assignments. */
+    claims?: Readonly<Record<string, string>>;
+}
+/** A header is transport; this verifier is the authentication boundary. */
+export interface HeaderIdentitySource {
+    key: string;
+    header: string;
+    verify(input: {
+        value: string;
+        request: Request;
+        source: string;
+    }): Promise<HeaderIdentity | undefined>;
+}
+export interface HeaderPrincipal extends RbacPrincipal {
+    kind: 'header-identity';
+    /** Stable RBAC principal key. Safe to persist in a membership row. */
+    principalKey: string;
+    source: string;
+    subject: string;
+    claims: Readonly<Record<string, string>>;
+}
+/**
+ * The host owns assignments. It may read a database, configuration service or
+ * code policy; the credential itself never supplies roles. This is called for
+ * every request so assignment, disablement and revocation take effect at once.
+ */
+export interface HeaderAssignmentResolver {
+    (input: {
+        principalKey: string;
+        source: string;
+        subject: string;
+        claims: Readonly<Record<string, string>>;
+        request: Request;
+    }): Promise<readonly PrincipalAssignment[]>;
+}
+export declare function defineHeaderIdentitySources<const T extends readonly HeaderIdentitySource[]>(sources: T): T;
+/** Resolve exactly one authenticated header source and its fresh RBAC assignment. */
+export declare function headerIdentityResolver(sourcesInput: readonly HeaderIdentitySource[], resolveAssignments: HeaderAssignmentResolver): (request: Request) => Promise<HeaderPrincipal | undefined>;