@forgezero/access 0.1.1 → 0.1.2

package/README.md

@@ -66,6 +66,46 @@ 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.
+
+```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**
 

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 };
   }

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 };
   }

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 };
   }

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>;

package/dist/header.js

@@ -0,0 +1,432 @@
+// src/index.ts
+var SCHEMA_VERSION = 1;
+function assertReadable(document, what) {
+  const version = document.version ?? 1;
+  if (version > SCHEMA_VERSION) {
+    throw new AccessError("ACCESS_VERSION_TOO_NEW", `${what} is version ${version}; this build reads ${SCHEMA_VERSION}. Upgrade @forgezero/access.`);
+  }
+}
+
+class AccessError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AccessError";
+  }
+}
+
+class Refusal extends Error {
+  status;
+  code;
+  details;
+  retryable;
+  refusal = true;
+  constructor(status, code, message, details = {}, retryable = false) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.retryable = retryable;
+    this.name = "Refusal";
+  }
+}
+function isRefusal(error) {
+  return typeof error === "object" && error !== null && error.refusal === true;
+}
+
+class Settled extends Error {
+  value;
+  status;
+  headers;
+  settled = true;
+  constructor(value, status = 200, headers = {}) {
+    super("Already settled.");
+    this.value = value;
+    this.status = status;
+    this.headers = headers;
+    this.name = "Settled";
+  }
+}
+function isSettled(error) {
+  return typeof error === "object" && error !== null && error.settled === true;
+}
+function defineFactors(factors) {
+  for (const [id, factor] of Object.entries(factors)) {
+    if (factor.status === "shipped" && !(factor.tests?.length ?? 0)) {
+      throw new AccessError("FACTOR_UNTESTED", `Factor "${id}" is marked shipped with no tests. A method nobody exercises is a claim.`);
+    }
+  }
+  return factors;
+}
+function page(label, options = {}) {
+  return { kind: "page", label, accessGroup: "default", ...options };
+}
+function 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/.`);
+    }
+    if (route.kind === "action" && route.page && !(route.page in routes)) {
+      throw new AccessError("ROUTE_DANGLING_PAGE", `"${key}" names page "${route.page}", which does not exist.`);
+    }
+    if (route.kind === "action" && route.response) {
+      for (const status of Object.keys(route.response)) {
+        if (!route.response[Number(status)]) {
+          throw new AccessError("ROUTE_EMPTY_RESPONSE", `"${key}" declares status ${status} with no schema.`);
+        }
+      }
+    }
+  }
+  return routes;
+}
+function codePolicy(config) {
+  return {
+    roles: async () => config.roles,
+    enabledFactors: async () => config.enabledFactors
+  };
+}
+function externalPolicy(reader) {
+  return {
+    async roles() {
+      const roles = await reader.roles();
+      for (const role of roles)
+        assertReadable(role, `role "${role.roleKey}"`);
+      return roles;
+    },
+    enabledFactors: () => reader.enabledFactors()
+  };
+}
+function stemOf(routeKey, strip) {
+  const withoutApi = routeKey.startsWith("api/") ? routeKey.slice(4) : routeKey;
+  return strip ? withoutApi.replace(strip, "") : withoutApi;
+}
+function grantsRoute(grants, routeKey, options = {}) {
+  const { mode = "inherit", sharesGrantWith, strip } = options;
+  const stem = stemOf(routeKey, strip);
+  const shared = sharesGrantWith ? stemOf(sharesGrantWith, strip) : undefined;
+  return grants.some((grant) => {
+    const granted = stemOf(grant, strip);
+    if (stem === granted || granted === routeKey)
+      return true;
+    if (shared !== undefined && (granted === shared || granted === sharesGrantWith))
+      return true;
+    return mode === "inherit" && stem.startsWith(granted + "/");
+  });
+}
+function fulfilledActionFactors() {
+  return [];
+}
+function defineAccessControl(config) {
+  assertReadable(config, "access control");
+  const routeKeys = new Set(Object.keys(config.routes));
+  const actionKeys = Object.entries(config.routes).filter(([, route]) => route.kind === "action").map(([key]) => key);
+  const checkKeys = (listName, name, keys) => {
+    if (keys.length === 0) {
+      throw new AccessError("POLICY_ORPHANED", `${listName} "${name}" binds no routes.`);
+    }
+    for (const key of keys) {
+      if (!routeKeys.has(key)) {
+        throw new AccessError("POLICY_UNKNOWN_ROUTE", `${listName} "${name}" names "${key}", which is not a route.`);
+      }
+    }
+  };
+  const sessionOf = new Map;
+  for (const [name, policy] of Object.entries(config.sessionPolicies)) {
+    checkKeys("Session policy", name, policy.routes);
+    for (const key of policy.routes) {
+      if (sessionOf.has(key)) {
+        throw new AccessError("SESSION_DUPLICATE", `"${key}" is in more than one session policy.`);
+      }
+      sessionOf.set(key, policy);
+    }
+    for (const factor of policy.factors) {
+      const spec = config.factors[factor];
+      if (!spec)
+        throw new AccessError("FACTOR_UNKNOWN", `Session policy "${name}" names unknown factor "${factor}".`);
+      if (spec.kind === "action") {
+        throw new AccessError("FACTOR_WRONG_KIND", `"${factor}" is action-only and cannot establish a session.`);
+      }
+    }
+  }
+  const unclassified = [...routeKeys].filter((key) => !sessionOf.has(key));
+  if (unclassified.length > 0) {
+    throw new AccessError("SESSION_INCOMPLETE", `No session policy covers: ${unclassified.join(", ")}. Every route needs exactly one.`);
+  }
+  const actionOf = new Map;
+  for (const [name, policy] of Object.entries(config.actionPolicies ?? {})) {
+    checkKeys("Action policy", name, policy.routes);
+    if (policy.required < 1 || policy.required > policy.factors.length) {
+      throw new AccessError("ACTION_UNSATISFIABLE", `Action policy "${name}" requires ${policy.required} of ${policy.factors.length} factors.`);
+    }
+    for (const factor of policy.factors) {
+      const spec = config.factors[factor];
+      if (!spec)
+        throw new AccessError("FACTOR_UNKNOWN", `Action policy "${name}" names unknown factor "${factor}".`);
+      if (spec.kind === "session") {
+        throw new AccessError("FACTOR_WRONG_KIND", `"${factor}" is session-only and cannot authorise an action.`);
+      }
+    }
+    for (const key of policy.routes) {
+      if (actionOf.has(key)) {
+        throw new AccessError("ACTION_DUPLICATE", `"${key}" is in more than one action policy.`);
+      }
+      actionOf.set(key, policy);
+    }
+  }
+  const rateOf = new Map;
+  const rateLists = Object.entries(config.ratePolicies ?? {});
+  for (const [name, policy] of rateLists) {
+    checkKeys("Rate policy", name, policy.routes);
+    for (const key of policy.routes) {
+      if (rateOf.has(key)) {
+        throw new AccessError("RATE_DUPLICATE", `"${key}" is in more than one rate policy.`);
+      }
+      rateOf.set(key, policy);
+    }
+  }
+  if (rateLists.length > 0) {
+    const unrated = actionKeys.filter((key) => !rateOf.has(key));
+    if (unrated.length > 0) {
+      throw new AccessError("RATE_INCOMPLETE", `No rate policy covers: ${unrated.join(", ")}. Declaring any means declaring all.`);
+    }
+  }
+  const beforeOf = new Map;
+  for (const [name, handler] of Object.entries(config.beforeHandlers ?? {})) {
+    checkKeys("Before handler", name, handler.routes);
+    for (const key of handler.routes) {
+      beforeOf.set(key, [...beforeOf.get(key) ?? [], handler]);
+    }
+  }
+  const afterOf = new Map;
+  for (const [name, handler] of Object.entries(config.afterHandlers ?? {})) {
+    checkKeys("After handler", name, handler.routes);
+    for (const key of handler.routes) {
+      afterOf.set(key, [...afterOf.get(key) ?? [], handler]);
+    }
+  }
+  const features = config.features ?? [];
+  return {
+    version: config.version ?? SCHEMA_VERSION,
+    routes: config.routes,
+    features,
+    source: config.source,
+    keys: () => Object.keys(config.routes),
+    get: (key) => config.routes[key],
+    exists(key, context) {
+      const route = config.routes[key];
+      if (!route)
+        return false;
+      if (route.feature && !features.includes(route.feature))
+        return false;
+      if (context?.stage && route.stages && !route.stages.includes(context.stage))
+        return false;
+      if (context?.realm && route.realms && !route.realms.includes(context.realm))
+        return false;
+      return true;
+    },
+    sessionPolicyFor: (key) => sessionOf.get(key),
+    actionPolicyFor: (key) => actionOf.get(key),
+    ratePolicyFor: (key) => rateOf.get(key),
+    beforeFor: (key) => beforeOf.get(key) ?? [],
+    afterFor: (key) => afterOf.get(key) ?? []
+  };
+}
+function authorise(args) {
+  const { access, routeKey, stage, realm, session, roles } = args;
+  if (!access.exists(routeKey, { stage, realm })) {
+    return { allow: false, status: 404, code: "NOT_FOUND" };
+  }
+  const policy = access.sessionPolicyFor(routeKey);
+  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));
+  if (missing.length > 0) {
+    return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
+  }
+  const grants = roles.filter((role) => session.roleKeys.includes(role.roleKey)).flatMap((role) => role.grants);
+  if (!grantsRoute(grants, routeKey)) {
+    return { allow: false, status: 403, code: "ACCESS_DENIED" };
+  }
+  return { allow: true };
+}
+function resolveActionFactors(policy, enabled) {
+  const available = policy.factors.filter((factor) => enabled.includes(factor));
+  return { available, required: policy.required, satisfiable: available.length >= policy.required };
+}
+function impactOfDisabling(access, enabledAfter) {
+  const broken = [];
+  for (const key of access.keys()) {
+    const policy = access.actionPolicyFor(key);
+    if (!policy)
+      continue;
+    const { available, required, satisfiable } = resolveActionFactors(policy, enabledAfter);
+    if (!satisfiable)
+      broken.push({ route: key, available: available.length, required });
+  }
+  return broken;
+}
+var VERSION = "0.1.0";
+
+// src/principal.ts
+var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
+var GROUP = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/;
+var METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+function uniqueAtoms(values, max, pattern = ATOM) {
+  return values.length <= max && new Set(values).size === values.length && values.every((value) => pattern.test(value));
+}
+function defineRbacPrincipal(principal) {
+  if (!ATOM.test(principal.kind) || !ATOM.test(principal.principalKey) || principal.assignments.length > 32) {
+    throw new AccessError("PRINCIPAL_INVALID", "The principal kind, key, or assignment count is invalid.");
+  }
+  const assignmentKeys = new Set;
+  for (const assignment of principal.assignments) {
+    if (!ATOM.test(assignment.assignmentKey) || assignmentKeys.has(assignment.assignmentKey) || !uniqueAtoms(assignment.roleKeys, 128) || !uniqueAtoms(assignment.accessGroups, 32, GROUP) || !uniqueAtoms(assignment.sessionFactors, 32) || assignment.methods.length === 0 || assignment.methods.length > METHODS.size || new Set(assignment.methods).size !== assignment.methods.length || assignment.methods.some((method) => !METHODS.has(method))) {
+      throw new AccessError("PRINCIPAL_ASSIGNMENT_INVALID", "A principal assignment is malformed, duplicate, or unbounded.");
+    }
+    if (assignment.idleTtlMs === undefined !== (assignment.lastActiveAtMs === undefined) || assignment.idleTtlMs !== undefined && (!Number.isSafeInteger(assignment.idleTtlMs) || assignment.idleTtlMs <= 0) || assignment.lastActiveAtMs !== undefined && (!Number.isSafeInteger(assignment.lastActiveAtMs) || assignment.lastActiveAtMs < 0) || assignment.absoluteExpiresAtMs !== undefined && (!Number.isSafeInteger(assignment.absoluteExpiresAtMs) || assignment.absoluteExpiresAtMs < 0)) {
+      throw new AccessError("PRINCIPAL_ASSIGNMENT_INVALID", "Assignment expiry coordinates are incomplete or invalid.");
+    }
+    if (assignment.delegatedBy && (!ATOM.test(assignment.delegatedBy.userKey) || !ATOM.test(assignment.delegatedBy.sessionKey) || !Number.isSafeInteger(assignment.delegatedBy.atMs))) {
+      throw new AccessError("PRINCIPAL_ASSIGNMENT_INVALID", "Assignment delegation binding is invalid.");
+    }
+    assignmentKeys.add(assignment.assignmentKey);
+  }
+  return principal;
+}
+function assignmentIsActive(assignment, now = Date.now()) {
+  if (assignment.absoluteExpiresAtMs !== undefined && now >= assignment.absoluteExpiresAtMs)
+    return false;
+  if (assignment.idleTtlMs !== undefined && assignment.lastActiveAtMs !== undefined && now >= assignment.lastActiveAtMs + assignment.idleTtlMs)
+    return false;
+  return true;
+}
+function touchPrincipalAssignment(assignment, now = Date.now()) {
+  if (!assignmentIsActive(assignment, now) || assignment.idleTtlMs === undefined)
+    return assignment;
+  return { ...assignment, lastActiveAtMs: now };
+}
+function decidePrincipalAccess(args) {
+  const route = args.access.get(args.routeKey);
+  if (!route || !args.access.exists(args.routeKey, { stage: args.stage, realm: args.realm }) || route.kind === "action" && args.method !== undefined && route.method !== args.method) {
+    return { allow: false, status: 404, code: "NOT_FOUND" };
+  }
+  if (route.accessGroup === "public")
+    return { allow: true, public: true };
+  if (!args.principal)
+    return { allow: false, status: 401, code: "AUTH_REQUIRED" };
+  const principal = defineRbacPrincipal(args.principal);
+  const policy = args.access.sessionPolicyFor(args.routeKey);
+  const requiredFactors = policy?.factors ?? [];
+  let missing;
+  for (const assignment of principal.assignments) {
+    if (!assignmentIsActive(assignment, args.now) || !assignment.accessGroups.includes(route.accessGroup) || route.kind === "action" && !assignment.methods.includes(route.method))
+      continue;
+    const absent = requiredFactors.filter((factor) => !assignment.sessionFactors.includes(factor));
+    if (absent.length > 0) {
+      missing = missing === undefined ? absent : [...new Set([...missing, ...absent])];
+      continue;
+    }
+    const grants = args.roles.filter((role) => assignment.roleKeys.includes(role.roleKey)).flatMap((role) => role.grants);
+    if (!grantsRoute(grants, args.routeKey, {
+      mode: route.grantMode,
+      sharesGrantWith: route.sharesGrantWith
+    }))
+      continue;
+    const action2 = args.access.actionPolicyFor(args.routeKey);
+    if (action2 && !args.actionProofSatisfied) {
+      return {
+        allow: false,
+        status: 428,
+        code: "ACTION_REQUIRED",
+        missing: action2.factors,
+        required: action2.required
+      };
+    }
+    return { allow: true, public: false, assignmentKey: assignment.assignmentKey };
+  }
+  if (missing?.length)
+    return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
+  return { allow: false, status: 403, code: "ACCESS_DENIED" };
+}
+
+// src/header.ts
+var HEADER = /^[a-z][a-z0-9-]{0,62}$/;
+var KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+var ATOM2 = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
+var CLAIM_KEY = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/;
+function defineHeaderIdentitySources(sources) {
+  if (sources.length > 16)
+    throw new AccessError("HEADER_SOURCE_LIMIT", "At most 16 header identity sources may be active.");
+  const keys = new Set;
+  const headers = new Set;
+  for (const source of sources) {
+    const header = source.header.trim().toLowerCase();
+    if (!KEY.test(source.key) || !HEADER.test(header)) {
+      throw new AccessError("HEADER_SOURCE_INVALID", "Header identity source keys and names must be bounded atoms.");
+    }
+    if (["cookie", "authorization", "x-fz-key", "x-fz-node", "x-fz-signature"].includes(header)) {
+      throw new AccessError("HEADER_SOURCE_RESERVED", `Header identity source "${source.key}" uses a reserved credential header.`);
+    }
+    if (keys.has(source.key) || headers.has(header)) {
+      throw new AccessError("HEADER_SOURCE_DUPLICATE", "Header identity source keys and header names must be unique.");
+    }
+    keys.add(source.key);
+    headers.add(header);
+  }
+  return sources;
+}
+function headerIdentityResolver(sourcesInput, resolveAssignments) {
+  const sources = defineHeaderIdentitySources(sourcesInput);
+  return async (request) => {
+    const presented = sources.flatMap((source2) => {
+      const value2 = request.headers.get(source2.header)?.trim();
+      return value2 ? [{ source: source2, value: value2 }] : [];
+    });
+    if (presented.length === 0)
+      return;
+    if (presented.length !== 1) {
+      throw new AccessError("HEADER_IDENTITY_AMBIGUOUS", "Exactly one header identity source may authenticate a request.");
+    }
+    const [{ source, value }] = presented;
+    if (value.length > 8192 || /[\0\r\n]/.test(value)) {
+      throw new AccessError("HEADER_IDENTITY_INVALID", "The header identity credential is malformed.");
+    }
+    const identity = await source.verify({ value, request, source: source.key });
+    if (!identity)
+      return;
+    const claims = identity.claims ?? {};
+    if (!ATOM2.test(identity.subject) || Object.keys(claims).length > 32 || Object.entries(claims).some(([key, claim]) => !CLAIM_KEY.test(key) || typeof claim !== "string" || claim.length > 512 || /[\0\r\n]/.test(claim))) {
+      throw new AccessError("HEADER_IDENTITY_INVALID", "The verified header identity has an invalid subject or bounded claim set.");
+    }
+    const principalKey = `header:${source.key}:${identity.subject}`;
+    const assignments = [...await resolveAssignments({
+      principalKey,
+      source: source.key,
+      subject: identity.subject,
+      claims,
+      request
+    })];
+    return defineRbacPrincipal({
+      kind: "header-identity",
+      principalKey,
+      source: source.key,
+      subject: identity.subject,
+      assignments,
+      claims
+    });
+  };
+}
+export {
+  headerIdentityResolver,
+  defineHeaderIdentitySources
+};

package/dist/index.d.ts

@@ -129,6 +129,8 @@ export interface RouteContract {
 }
 export interface RouteBase extends RouteContract {
     label: string;
+    /** Open host vocabulary used to scope delegated role assignments. */
+    accessGroup: string;
     /** Disabled feature → 404, never 403. A 403 confirms the route exists. */
     feature?: string;
     /** Outside its stage → 404, for the same reason. */