@forgezero/access 0.1.1 → 0.1.3

package/dist/principal-session.js

@@ -0,0 +1,548 @@
+// 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/security.ts
+var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));
+function toHex(bytes) {
+  let out = "";
+  for (const byte of bytes)
+    out += HEX[byte];
+  return out;
+}
+function fromHex(hex) {
+  if (hex.length % 2 !== 0)
+    throw new Error("Hex string must have an even length.");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0;index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+function toBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - padded.length % 4) % 4));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+function randomToken(bytes = 32) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toBase64Url(buffer);
+}
+function randomHex(bytes = 32) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toHex(buffer);
+}
+function randomDigits(length = 6) {
+  let digits = "";
+  for (let index = 0;index < length; index += 1)
+    digits += randomInt(10).toString();
+  return digits;
+}
+function randomInt(max) {
+  if (max <= 0 || max > 256)
+    throw new Error("randomInt supports 1..256.");
+  const limit = Math.floor(256 / max) * max;
+  const buffer = new Uint8Array(1);
+  for (;; ) {
+    crypto.getRandomValues(buffer);
+    if (buffer[0] < limit)
+      return buffer[0] % max;
+  }
+}
+async function sha256(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return toHex(new Uint8Array(digest));
+}
+var hashToken = sha256;
+async function hmacSha256(key, message) {
+  const keyBytes = typeof key === "string" ? new TextEncoder().encode(key) : key;
+  const imported = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", imported, new TextEncoder().encode(message));
+  return toHex(new Uint8Array(signature));
+}
+async function verifyHmac(key, message, signature) {
+  return timingSafeEqual(await hmacSha256(key, message), signature);
+}
+async function hkdf(secret, info, length = 32, salt = new Uint8Array(32)) {
+  const key = await crypto.subtle.importKey("raw", secret, "HKDF", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info: new TextEncoder().encode(info) }, key, length * 8);
+  return new Uint8Array(bits);
+}
+async function seal(key, plaintext, aad) {
+  const iv = new Uint8Array(12);
+  crypto.getRandomValues(iv);
+  const imported = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv,
+    ...aad ? { additionalData: new TextEncoder().encode(aad) } : {}
+  }, imported, new TextEncoder().encode(plaintext));
+  return { iv: toBase64Url(iv), ciphertext: toBase64Url(new Uint8Array(ciphertext)) };
+}
+async function open(key, sealed, aad) {
+  const imported = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
+  const plaintext = await crypto.subtle.decrypt({
+    name: "AES-GCM",
+    iv: fromBase64Url(sealed.iv),
+    ...aad ? { additionalData: new TextEncoder().encode(aad) } : {}
+  }, imported, fromBase64Url(sealed.ciphertext));
+  return new TextDecoder().decode(plaintext);
+}
+var nowSeconds = () => Math.floor(Date.now() / 1000);
+var isLive = (expiresAtSec, at = nowSeconds()) => expiresAtSec > at;
+var SECRET_NAME = /token|secret|password|passphrase|credential|authorization|cookie|apikey|api_key|private/i;
+function redact(value) {
+  const out = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (SECRET_NAME.test(name))
+      out[name] = "[redacted]";
+    else if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      out[name] = redact(entry);
+    } else
+      out[name] = entry;
+  }
+  return out;
+}
+// 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/principal-session.ts
+var DEFAULT_PRINCIPAL_IDLE_TTL_MS = 30 * 60 * 1000;
+var DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS = 8 * 60 * 60 * 1000;
+var MAX_PRINCIPAL_IDLE_TTL_MS = 60 * 60 * 1000;
+var MAX_PRINCIPAL_ABSOLUTE_TTL_MS = 24 * 60 * 60 * 1000;
+function validTtl(value, maximum) {
+  return Number.isSafeInteger(value) && value > 0 && value <= maximum;
+}
+async function issuePrincipalSession(args) {
+  if (args.clientIdentity.length < 16 || args.clientIdentity.length > 256 || /[\0\r\n]/.test(args.clientIdentity)) {
+    throw new AccessError("PRINCIPAL_CLIENT_IDENTITY_INVALID", "Client identity must be a bounded opaque value.");
+  }
+  const idleTtlMs = args.idleTtlMs ?? DEFAULT_PRINCIPAL_IDLE_TTL_MS;
+  const absoluteTtlMs = args.absoluteTtlMs ?? DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS;
+  if (!validTtl(idleTtlMs, MAX_PRINCIPAL_IDLE_TTL_MS) || !validTtl(absoluteTtlMs, MAX_PRINCIPAL_ABSOLUTE_TTL_MS) || idleTtlMs > absoluteTtlMs) {
+    throw new AccessError("PRINCIPAL_SESSION_TTL_INVALID", "Principal session TTLs are invalid or exceed package limits.");
+  }
+  const principal = defineRbacPrincipal({
+    kind: args.kind,
+    principalKey: args.principalKey,
+    assignments: args.assignments ?? []
+  });
+  const credential = randomToken(32);
+  const now = args.now ?? Date.now();
+  return {
+    credential,
+    record: {
+      sessionKey: randomToken(24),
+      principalKey: principal.principalKey,
+      kind: principal.kind,
+      status: "active",
+      credentialHash: await hashToken(credential),
+      clientIdentityHash: await hashToken(args.clientIdentity),
+      assignments: principal.assignments,
+      createdAtMs: now,
+      lastActiveAtMs: now,
+      idleTtlMs,
+      absoluteExpiresAtMs: now + absoluteTtlMs
+    }
+  };
+}
+function principalSessionIsActive(record, now = Date.now()) {
+  return record.status === "active" && now < record.absoluteExpiresAtMs && now < record.lastActiveAtMs + record.idleTtlMs;
+}
+async function authenticatePrincipalSession(record, args) {
+  if (!principalSessionIsActive(record, args.now))
+    return;
+  if (!timingSafeEqual(await hashToken(args.credential), record.credentialHash) || !timingSafeEqual(await hashToken(args.clientIdentity), record.clientIdentityHash))
+    return;
+  return defineRbacPrincipal({
+    kind: record.kind,
+    principalKey: record.principalKey,
+    assignments: record.assignments
+  });
+}
+function touchPrincipalSession(record, now = Date.now()) {
+  return principalSessionIsActive(record, now) ? { ...record, lastActiveAtMs: now } : record;
+}
+export {
+  touchPrincipalSession,
+  principalSessionIsActive,
+  issuePrincipalSession,
+  authenticatePrincipalSession,
+  MAX_PRINCIPAL_IDLE_TTL_MS,
+  MAX_PRINCIPAL_ABSOLUTE_TTL_MS,
+  DEFAULT_PRINCIPAL_IDLE_TTL_MS,
+  DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS
+};

package/dist/principal.d.ts

@@ -0,0 +1,56 @@
+import { type AccessControl, type Method, type Role, type RouteRegistry } from './index';
+/** One independently revocable RBAC layer on a principal. */
+export interface PrincipalAssignment {
+    assignmentKey: string;
+    roleKeys: readonly string[];
+    accessGroups: readonly string[];
+    methods: readonly Method[];
+    /** Session-level facts copied only by a trusted delegation issuer. */
+    sessionFactors: readonly string[];
+    /** Optional sliding-idle boundary. Omit for a persistent admin assignment. */
+    idleTtlMs?: number;
+    lastActiveAtMs?: number;
+    /** A sliding touch can never move this hard boundary. */
+    absoluteExpiresAtMs?: number;
+    delegatedBy?: {
+        userKey: string;
+        sessionKey: string;
+        atMs: number;
+    };
+}
+export interface RbacPrincipal {
+    kind: string;
+    principalKey: string;
+    assignments: readonly PrincipalAssignment[];
+}
+export type PrincipalAccessDecision = {
+    allow: true;
+    public: boolean;
+    assignmentKey?: string;
+} | {
+    allow: false;
+    status: 401 | 403 | 404 | 428;
+    code: 'NOT_FOUND' | 'AUTH_REQUIRED' | 'ACCESS_DENIED' | 'SECURITY_REQUIRED' | 'ACTION_REQUIRED';
+    missing?: readonly string[];
+    required?: number;
+};
+/** Validate persisted/external principal data before it becomes authority. */
+export declare function defineRbacPrincipal<T extends RbacPrincipal>(principal: T): T;
+export declare function assignmentIsActive(assignment: PrincipalAssignment, now?: number): boolean;
+/** Pure sliding-idle update; persistence and compare-and-swap remain host-owned. */
+export declare function touchPrincipalAssignment(assignment: PrincipalAssignment, now?: number): PrincipalAssignment;
+/**
+ * One authorization decision shared by browser-delegated and verified-header
+ * principals. Authentication is deliberately outside this function.
+ */
+export declare function decidePrincipalAccess<R extends RouteRegistry>(args: {
+    access: AccessControl<R>;
+    routeKey: string;
+    method?: Method;
+    stage?: string;
+    realm?: string;
+    principal?: RbacPrincipal;
+    roles: readonly Role[];
+    actionProofSatisfied?: boolean;
+    now?: number;
+}): PrincipalAccessDecision;