@forgezero/access 0.1.1 → 0.1.3

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. */

package/dist/index.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/pipeline.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/principal-session.d.ts

@@ -0,0 +1,47 @@
+import { type PrincipalAssignment, type RbacPrincipal } from './principal';
+export declare const DEFAULT_PRINCIPAL_IDLE_TTL_MS: number;
+export declare const DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS: number;
+export declare const MAX_PRINCIPAL_IDLE_TTL_MS: number;
+export declare const MAX_PRINCIPAL_ABSOLUTE_TTL_MS: number;
+export interface PrincipalSessionRecord {
+    sessionKey: string;
+    principalKey: string;
+    kind: string;
+    status: 'active' | 'revoked';
+    /** Only hashes are persisted. Browser-generated identity is a binding, not authentication. */
+    credentialHash: string;
+    clientIdentityHash: string;
+    assignments: readonly PrincipalAssignment[];
+    createdAtMs: number;
+    lastActiveAtMs: number;
+    idleTtlMs: number;
+    absoluteExpiresAtMs: number;
+}
+export interface IssuedPrincipalSession {
+    /** Returned once. Store in an HttpOnly Secure cookie, never localStorage. */
+    credential: string;
+    record: PrincipalSessionRecord;
+}
+/**
+ * Create a purpose-neutral delegated session. The browser may persist
+ * `clientIdentity`, but that value is only bound to the server credential and
+ * proves nothing by itself.
+ */
+export declare function issuePrincipalSession(args: {
+    kind: string;
+    principalKey: string;
+    clientIdentity: string;
+    assignments?: readonly PrincipalAssignment[];
+    idleTtlMs?: number;
+    absoluteTtlMs?: number;
+    now?: number;
+}): Promise<IssuedPrincipalSession>;
+export declare function principalSessionIsActive(record: PrincipalSessionRecord, now?: number): boolean;
+/** Resolve only after looking up the record by its non-secret session key. */
+export declare function authenticatePrincipalSession(record: PrincipalSessionRecord, args: {
+    credential: string;
+    clientIdentity: string;
+    now?: number;
+}): Promise<RbacPrincipal | undefined>;
+/** Host persists this with compare-and-swap after successful authentication. */
+export declare function touchPrincipalSession(record: PrincipalSessionRecord, now?: number): PrincipalSessionRecord;