axis-platform-sdk 0.2.0

package/src/authorizer.js

@@ -0,0 +1,101 @@
+/**
+ * The Authorizer port + the free-tier SwitchAuthorizer.
+ *
+ * Owyhee (and any platform) always does IDENTITY verification first — is this a
+ * real, non-revoked agent with a trustworthy effective_scope (verifyAgent ->
+ * registry). That part is fixed and never pluggable.
+ *
+ * The authorization DECISION is the pluggable, monetizable layer. Every
+ * Authorizer implements the same shape:
+ *
+ *     authorize(token, gateId, { registryBaseUrl, fetchImpl }) -> verdict
+ *
+ * where `verdict` is exactly what verifyAgent returns
+ * ({ accepted, reason?, code?, agent_id?, operator_id?, effective_scope?, tier?, ... }).
+ *
+ * Profiles (Josh's "simple on/off -> granular -> really complicated"):
+ *   - SwitchAuthorizer  (this file)  — FREE tier. Config-driven on/off gates
+ *                                      + optional tier / scope / operator rules.
+ *   - EngineAuthorizer  (not here)   — PAID. Same port, delegates the decision
+ *                                      to Permify / OpenFGA (sidecar) for
+ *                                      relationship/attribute rules.
+ *   - EnterpriseAuthorizer (not here)— full ReBAC/ABAC, same port.
+ *
+ * The SwitchAuthorizer's `policy` object is exactly what a "Door policy" screen
+ * edits and saves.
+ */
+import { verifyAgent } from './verify.js';
+import { extractToken } from './gate.js';
+
+const deny = (reason, code, extra = {}) => ({ accepted: false, reason, code, ...extra });
+
+/**
+ * Free-tier gate engine: a set of named gates, each on/off, with optional
+ * minimum tier, required scopes, and operator allow/block lists.
+ *
+ * policy = {
+ *   audience: 'comments.mysite.com',   // your platform id; applied to every gate
+ *   defaultAllow: false,               // posture for a gateId with no policy
+ *   blockedOperators: [],              // global blocklist, applied to all gates
+ *   gates: {
+ *     'comments:write': {
+ *       enabled: true,
+ *       minTier: 'domain',             // optional
+ *       requireScopes: ['comments:write'], // optional
+ *       blockedOperators: [],          // optional, gate-specific
+ *       approvedOperators: null        // optional allowlist
+ *     }
+ *   }
+ * }
+ */
+export class SwitchAuthorizer {
+  constructor(policy = {}) {
+    this.policy = policy || {};
+  }
+
+  /** The verifyAgent options this policy implies for a given gate. */
+  optsForGate(gateId) {
+    const p = this.policy;
+    const gate = (p.gates && p.gates[gateId]) || null;
+    return {
+      audience: p.audience,
+      requireScopes: (gate && gate.requireScopes) || [],
+      minTier: gate && gate.minTier,
+      blockedOperators: [...(p.blockedOperators || []), ...((gate && gate.blockedOperators) || [])],
+      approvedOperators: (gate && gate.approvedOperators) || null,
+    };
+  }
+
+  /**
+   * Decide whether `token` may act at `gateId`. Denies if the gate is turned
+   * off, or unknown when the posture is closed. Otherwise runs identity
+   * verification + this gate's policy.
+   */
+  async authorize(token, gateId, { registryBaseUrl, fetchImpl } = {}) {
+    const p = this.policy;
+    const gate = (p.gates && p.gates[gateId]) || null;
+
+    if (!gate) {
+      if (p.defaultAllow) {
+        return verifyAgent(token, {
+          audience: p.audience,
+          blockedOperators: p.blockedOperators || [],
+          registryBaseUrl,
+          fetchImpl,
+        });
+      }
+      return deny(`No policy for gate '${gateId}' and the default posture is closed`, 'gate_unknown');
+    }
+
+    if (gate.enabled === false) {
+      return deny(`Gate '${gateId}' is turned off`, 'gate_closed');
+    }
+
+    return verifyAgent(token, { ...this.optsForGate(gateId), registryBaseUrl, fetchImpl });
+  }
+
+  /** Bind this authorizer to a gateId as a request gate: (request) => verdict. */
+  gate(gateId, opts = {}) {
+    return async (request) => this.authorize(extractToken(request), gateId, opts);
+  }
+}

package/src/blocklist.js

@@ -0,0 +1,183 @@
+/**
+ * Persistent block / allow list — the runtime, stateful counterpart to the
+ * static `blockedOperators` / `approvedOperators` arrays that verifyAgent and
+ * SwitchAuthorizer already take.
+ *
+ * The static lists are policy-at-config-time (what the door policy screen
+ * saves). This is policy-at-runtime: a platform operator clicks "boot this
+ * agent" and the decision sticks in the platform's OWN store, no redeploy. It
+ * adds two things the static arrays don't have:
+ *
+ *   1. Agent-level blocking (block one misbehaving agent without blocking its
+ *      whole operator).
+ *   2. Mutation at runtime (block / unblock) backed by a pluggable store.
+ *
+ * Canonical adapter: Owyhee "The Door" (governor#27) ships the OPERATOR-level
+ * half of this port as its `operator_blocks` table + `blockedOperators()`,
+ * merged into the SwitchAuthorizer policy at authorize time. This module is the
+ * library form of that, plus the AGENT-level half The Door does not have yet
+ * (an additive `agent_blocks` table is the natural way for it to adopt it — a
+ * fast-follow, not a requirement). Block metadata is `{ reason, created_at }`
+ * (epoch ms), matching The Door's columns so the shapes are one.
+ *
+ * Same adapter shape as the ledger — a tiny CRUD port a platform implements
+ * against D1 / SQLite / Postgres. Default is in-memory.
+ *
+ * --- Adapter shape -------------------------------------------------------
+ * A store is any object implementing:
+ *
+ *   async add(kind, id, meta)     -> void              // kind: 'operator'|'agent'
+ *   async remove(kind, id)        -> void
+ *   async has(kind, id)           -> boolean
+ *   async list(kind)              -> { id, meta }[]     // all entries of a kind
+ *
+ * Integration: build the verifyAgent opts from a Blocklist and merge them with
+ * your static policy (`opts(staticBlocked)` -> { blockedOperators }), and call
+ * `checkVerdict(verdict)` AFTER verifyAgent to catch agent-level blocks (the
+ * registry verdict carries operator_id and agent_id, and operator blocking is
+ * already enforced by verifyAgent via blockedOperators, but agent-level
+ * blocking needs the resolved agent_id, which only exists post-verify).
+ */
+
+/** Default in-memory block/allow store. */
+export class MemoryBlocklistStore {
+  constructor() {
+    this._sets = { operator: new Map(), agent: new Map() };
+  }
+
+  async add(kind, id, meta = {}) {
+    const m = this._sets[kind];
+    if (!m) throw new Error(`MemoryBlocklistStore: unknown kind '${kind}'`);
+    m.set(id, { ...meta, created_at: meta.created_at || Date.now() });
+  }
+
+  async remove(kind, id) {
+    const m = this._sets[kind];
+    if (m) m.delete(id);
+  }
+
+  async has(kind, id) {
+    const m = this._sets[kind];
+    return !!(m && m.has(id));
+  }
+
+  async list(kind) {
+    const m = this._sets[kind];
+    if (!m) return [];
+    return [...m.entries()].map(([id, meta]) => ({ id, meta }));
+  }
+}
+
+/**
+ * Runtime block list. Holds two kinds of blocks — by operator_id and by
+ * agent_id — over a pluggable store.
+ */
+export class Blocklist {
+  constructor({ store } = {}) {
+    this.store = store || new MemoryBlocklistStore();
+  }
+
+  /** Block an operator (every agent under it). `reason` is recorded as meta. */
+  async blockOperator(operatorId, reason) {
+    await this.store.add('operator', operatorId, { reason });
+  }
+
+  /** Block a single agent without blocking its whole operator. */
+  async blockAgent(agentId, reason) {
+    await this.store.add('agent', agentId, { reason });
+  }
+
+  async unblockOperator(operatorId) {
+    await this.store.remove('operator', operatorId);
+  }
+
+  async unblockAgent(agentId) {
+    await this.store.remove('agent', agentId);
+  }
+
+  async isOperatorBlocked(operatorId) {
+    if (!operatorId) return false;
+    return this.store.has('operator', operatorId);
+  }
+
+  async isAgentBlocked(agentId) {
+    if (!agentId) return false;
+    return this.store.has('agent', agentId);
+  }
+
+  /** All blocked operator ids (for merging into verifyAgent's blockedOperators). */
+  async blockedOperatorIds() {
+    return (await this.store.list('operator')).map((e) => e.id);
+  }
+
+  async listOperators() {
+    return this.store.list('operator');
+  }
+
+  async listAgents() {
+    return this.store.list('agent');
+  }
+
+  /**
+   * The verifyAgent option fragment this blocklist implies. Merge with your
+   * static policy so a runtime-blocked operator is denied BEFORE the scope/tier
+   * checks run:
+   *
+   *   const dyn = await blocklist.verifyOpts();
+   *   const verdict = await verifyAgent(token, {
+   *     ...staticOpts,
+   *     blockedOperators: [...(staticOpts.blockedOperators||[]), ...dyn.blockedOperators],
+   *   });
+   *   const final = await blocklist.checkVerdict(verdict); // agent-level catch
+   */
+  async verifyOpts() {
+    return { blockedOperators: await this.blockedOperatorIds() };
+  }
+
+  /**
+   * Post-verify agent-level enforcement. verifyAgent already denies blocked
+   * OPERATORS (when you fed it `blockedOperators`), but agent-level blocking
+   * needs the resolved agent_id, which only exists after the registry verify.
+   * Pass an accepted verdict through this; it flips it to denied if the agent
+   * (or, as a safety net, the operator) is blocked. Pass-through otherwise.
+   */
+  async checkVerdict(verdict) {
+    if (!verdict || !verdict.accepted) return verdict;
+    if (await this.isAgentBlocked(verdict.agent_id)) {
+      return {
+        accepted: false,
+        code: 'agent_blocked',
+        reason: 'Agent is blocked at this platform',
+        agent_id: verdict.agent_id,
+        operator_id: verdict.operator_id,
+      };
+    }
+    if (await this.isOperatorBlocked(verdict.operator_id)) {
+      return {
+        accepted: false,
+        code: 'operator_blocked',
+        reason: 'Operator is blocked at this platform',
+        agent_id: verdict.agent_id,
+        operator_id: verdict.operator_id,
+      };
+    }
+    return verdict;
+  }
+}
+
+/**
+ * Wrap a gate so a runtime-blocked agent/operator is denied even if it's
+ * globally valid and within policy. Sits OUTSIDE the verify call: it merges the
+ * dynamic operator blocks into the verdict path via checkVerdict (agent-level)
+ * and is the simplest way to bolt a Blocklist onto an existing gate.
+ *
+ * Note: operator-level dynamic blocks are most efficiently injected by feeding
+ * `await blocklist.blockedOperatorIds()` into the gate's policy, but checkVerdict
+ * also catches them here as a safety net, so this wrapper is correct on its own.
+ */
+export function gatedWithBlocklist(gate, blocklist) {
+  return async function blocklistGate(request) {
+    const verdict = await gate(request);
+    return blocklist.checkVerdict(verdict);
+  };
+}

package/src/client.js

@@ -0,0 +1,82 @@
+/**
+ * Thin registry-call helpers. The registry does the cryptographic heavy
+ * lifting (signature, revocation, delegation chain walk) at its public
+ * endpoints; these wrappers just call them.
+ */
+
+export const DEFAULT_REGISTRY = 'https://registry.axisprime.ai';
+
+/**
+ * GET a registry path. `fetchImpl` is injectable for testing. Returns
+ * { status, body } where body is the parsed JSON (or { raw } if not JSON).
+ */
+export async function registryGet(base, path, { headers, fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(`${base}${path}`, headers ? { headers } : undefined);
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = { raw: text };
+  }
+  return { status: res.status, body };
+}
+
+/**
+ * Tier rank for minimum-tier gating. Higher = stronger verification.
+ * `kyb_business` is an accepted legacy alias for `kyb_organization`.
+ */
+export const TIER_RANK = {
+  email: 1,
+  domain: 2,
+  verified: 3,
+  kyb_individual: 4,
+  kyb_organization: 5,
+  kyb_business: 5,
+};
+
+/**
+ * Resolve an agent's presentation layer (display_name, operator verification
+ * tier, etc.). Pass the agent's AIT to unlock the presentation layer; without
+ * it you get only the public layer.
+ *
+ * @returns {{ agent_id, did, display_name, tier, status, raw }}
+ */
+export async function enrich(agentId, token, { registryBaseUrl = DEFAULT_REGISTRY, fetchImpl = fetch } = {}) {
+  const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
+  const { body } = await registryGet(registryBaseUrl, `/agents/${encodeURIComponent(agentId)}`, { headers, fetchImpl });
+  return {
+    agent_id: body.agent_id || agentId,
+    did: body.did || null,
+    display_name: body.display_name || null,
+    tier: pickTier(body),
+    status: body.status || null,
+    raw: body,
+  };
+}
+
+/**
+ * Read an operator's verification tier from a resolved agent record.
+ * Defensive across the field shapes the registry uses for the tier.
+ */
+export function pickTier(agentBody) {
+  if (!agentBody) return null;
+  return (
+    agentBody.operator_verification_tier ||
+    (agentBody.operator && agentBody.operator.verification_tier) ||
+    agentBody.verification_tier ||
+    null
+  );
+}
+
+/**
+ * Load a platform's published access policy (`/.well-known/axis-access`).
+ * Useful if you want your gate to read its own door policy rather than
+ * hard-coding it.
+ */
+export async function loadAccessPolicy(platformBaseUrl, { fetchImpl = fetch } = {}) {
+  const base = String(platformBaseUrl || '').replace(/\/$/, '');
+  const res = await fetchImpl(`${base}/.well-known/axis-access`);
+  if (!res.ok) throw new Error(`axis-access fetch failed: ${res.status}`);
+  return res.json();
+}

package/src/decode.js

@@ -0,0 +1,22 @@
+/**
+ * Decode an AIT (AXIS Identity Token, a JWT) payload WITHOUT verifying it.
+ *
+ * The cryptographic verification (signature, revocation, delegation chain)
+ * happens server-side at the registry's GET /verify endpoint. The only reason
+ * a platform decodes locally is to read the `aud` (audience) claim so it can
+ * confirm the agent actually meant to present to THIS platform. The registry
+ * enforces that `aud` is present and non-empty, but it does not know which
+ * platform is asking, so audience-matching is the platform's job.
+ *
+ * Returns the parsed payload object, or null if the token is malformed.
+ */
+export function decodeAitPayload(token) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) return null;
+  try {
+    const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    return JSON.parse(atob(b64));
+  } catch {
+    return null;
+  }
+}

package/src/gate.js

@@ -0,0 +1,70 @@
+/**
+ * aitGate — a drop-in request gate for a consuming platform (the "bouncer").
+ *
+ * Wrap your handler: pull the AIT off the incoming request, verify it against
+ * the registry + your policy, and either let it through or bounce it.
+ *
+ *   import { aitGate, denialResponse } from 'axis-platform-sdk';
+ *
+ *   const gate = aitGate({ audience: 'comments.mysite.com', requireScopes: ['comments:write'] });
+ *
+ *   export default {
+ *     async fetch(request) {
+ *       const verdict = await gate(request);
+ *       if (!verdict.accepted) return denialResponse(verdict);
+ *       // ...verdict.agent_id is verified; proceed.
+ *     }
+ *   };
+ */
+import { verifyAgent } from './verify.js';
+
+/**
+ * Pull the AIT off a request. Accepts a Fetch API Request, or any object with
+ * a `headers` (Headers or plain object) and optional `url`. Looks at, in order:
+ * Authorization: Bearer <ait>, X-AXIS-Token, ?ait= query param.
+ */
+export function extractToken(request) {
+  const h = request && request.headers;
+  const get = (k) => {
+    if (!h) return null;
+    if (typeof h.get === 'function') return h.get(k);
+    return h[k] || h[k.toLowerCase()] || null;
+  };
+  const auth = get('authorization') || get('Authorization');
+  if (auth && /^Bearer\s+/i.test(auth)) return auth.replace(/^Bearer\s+/i, '').trim();
+  const xa = get('x-axis-token') || get('X-AXIS-Token');
+  if (xa) return xa;
+  try {
+    if (request && request.url) {
+      const q = new URL(request.url).searchParams.get('ait');
+      if (q) return q;
+    }
+  } catch {
+    /* not a URL; ignore */
+  }
+  return null;
+}
+
+/**
+ * Build a gate function bound to your platform's policy. Returns
+ * `(request) => Promise<verdict>`.
+ */
+export function aitGate(opts = {}) {
+  return async function gate(request) {
+    const token = extractToken(request);
+    return verifyAgent(token, opts);
+  };
+}
+
+/**
+ * Turn a denied verdict into an HTTP Response (403 by default). 401 when no
+ * token was presented at all.
+ */
+export function denialResponse(verdict, status) {
+  const code = verdict && verdict.code;
+  const httpStatus = status || (code === 'no_token' ? 401 : 403);
+  return new Response(
+    JSON.stringify({ error: code || 'denied', message: verdict ? verdict.reason : 'Denied' }),
+    { status: httpStatus, headers: { 'Content-Type': 'application/json' } }
+  );
+}

package/src/index.js

@@ -0,0 +1,31 @@
+/**
+ * axis-platform-sdk — the platform/verifier ("bouncer") side of AXIS.
+ *
+ * When an AXIS agent shows up at your platform and wants to act, verify its
+ * identity + delegation + scope and decide: accept, scope, or boot.
+ *
+ * The whole point: the registry already does the cryptography (signature,
+ * revocation, delegation chain walk) server-side. This SDK packages the
+ * verdict + policy layer so a platform integrates in a few lines instead of
+ * hand-rolling it.
+ */
+export { verifyAgent } from './verify.js';
+export { SwitchAuthorizer } from './authorizer.js';
+export { aitGate, extractToken, denialResponse } from './gate.js';
+export { scopeCovers, coversAll } from './scope.js';
+export { enrich, loadAccessPolicy, registryGet, pickTier, TIER_RANK, DEFAULT_REGISTRY } from './client.js';
+export { decodeAitPayload } from './decode.js';
+
+// --- Stateful platform store (the "who showed up / who's blocked" half) ---
+export { AccessLedger, MemoryLedgerStore, loggedGate, recordEntry } from './ledger.js';
+export { Blocklist, MemoryBlocklistStore, gatedWithBlocklist } from './blocklist.js';
+export {
+  reportFlag,
+  blockAndReport,
+  getPlatformKey,
+  buildAttestation,
+  signAttestation,
+  verifyAttestation,
+  MemoryKeyStore,
+  DEFAULT_REPUTATION_URL,
+} from './reportback.js';

package/src/ledger.js

@@ -0,0 +1,171 @@
+/**
+ * Access ledger — the platform's "who showed up at my door" record.
+ *
+ * Every time an agent presents and the gate reaches a verdict, the platform can
+ * log the arrival here. This is the STATEFUL half of the bouncer: verifyAgent /
+ * aitGate are stateless verdict machines; the ledger is the platform's own
+ * append-only record of what those verdicts were, kept in the platform's OWN
+ * store. Zero-infra by default (in-memory); a real platform plugs in D1 /
+ * SQLite / Postgres via the adapter shape below.
+ *
+ * Canonical adapter: Owyhee "The Door" (kipple-governor, governor#27) is the
+ * shipped, D1-backed product instance of this port — its `arrivals` table +
+ * `recordArrival()` ARE this ledger over D1. This module is the library form
+ * (the shape + an in-memory default); The Door is the production adapter. The
+ * entry shape below is deliberately byte-compatible with The Door's
+ * `ArrivalRecord` / `arrivals` columns so there is ONE arrival record across
+ * the SDK and the product, not two.
+ *
+ * Trust note: the only scope worth recording is `effective_scope` (the
+ * registry's chain-walked, trustworthy scope), which is exactly what a verdict
+ * carries. We never persist the AIT's self-declared scope.
+ *
+ * --- Adapter shape -------------------------------------------------------
+ * A store is any object implementing:
+ *
+ *   async append(entry)                  -> void     // persist one arrival
+ *   async recent({ limit })              -> entry[]  // newest first
+ *   async byOperator(operatorId, { limit }) -> entry[] // newest first
+ *
+ * `entry` is the record shape produced by `recordEntry()` — the same fields The
+ * Door's `arrivals` table holds (minus the adapter's own PK/org columns):
+ *   {
+ *     agent_id, operator_id, created_at,          // created_at = epoch ms (Date.now())
+ *     tier, delegation_valid, effective_scope: string[],
+ *     gate_id, requested_action, display_name,
+ *     decision: 'auto_allow'|'denied'|'held'|'approved'|'booted',
+ *     reason, audience
+ *   }
+ *
+ * The same adapter shape is shared with blocklist.js (a tiny CRUD port). A
+ * platform implements both against whatever it already runs. The defaults here
+ * keep the demo and the free tier zero-infra.
+ */
+
+/**
+ * Default in-memory ledger store. Newest-first iteration. Bounded so a
+ * long-running Worker isolate doesn't grow without limit; override `max` (0 =
+ * unbounded) when you want the full history and have a real store behind it.
+ */
+export class MemoryLedgerStore {
+  constructor({ max = 10000 } = {}) {
+    this._entries = []; // chronological; newest pushed to the end
+    this.max = max;
+  }
+
+  async append(entry) {
+    this._entries.push(entry);
+    if (this.max && this._entries.length > this.max) {
+      this._entries.splice(0, this._entries.length - this.max);
+    }
+  }
+
+  async recent({ limit = 50 } = {}) {
+    const out = this._entries.slice(-limit);
+    out.reverse();
+    return out;
+  }
+
+  async byOperator(operatorId, { limit = 50 } = {}) {
+    const out = [];
+    for (let i = this._entries.length - 1; i >= 0 && out.length < limit; i--) {
+      if (this._entries[i].operator_id === operatorId) out.push(this._entries[i]);
+    }
+    return out;
+  }
+}
+
+/**
+ * Normalize a verdict (from verifyAgent) into a ledger entry. The output is
+ * byte-compatible with The Door's `ArrivalRecord` (governor#27) so the SDK and
+ * the product share one arrival shape.
+ *
+ * `decision` defaults from the verdict (accepted -> 'auto_allow', else
+ * 'denied'); a caller may override it with a manual-review state a real bouncer
+ * needs ('held' | 'approved' | 'booted'). `created_at` is epoch ms (Date.now()),
+ * matching The Door's column; for an ISO string use
+ * `new Date(entry.created_at).toISOString()`.
+ *
+ * @param {object} verdict             A verifyAgent verdict.
+ * @param {object} [fields]
+ * @param {string} [fields.audience]          Platform audience (optional metadata; The Door doesn't persist it).
+ * @param {string} [fields.gate_id]           Which gate was requested.
+ * @param {string} [fields.requested_action]  Human-facing action label.
+ * @param {string} [fields.display_name]      Enriched presentation name.
+ * @param {string} [fields.decision]          Override decision ('held'|'approved'|'booted').
+ * @param {number} [fields.created_at]        Override timestamp (epoch ms).
+ */
+export function recordEntry(verdict, { audience, gate_id, requested_action, display_name, decision, created_at } = {}) {
+  const v = verdict || {};
+  return {
+    agent_id: v.agent_id || null,
+    operator_id: v.operator_id || null,
+    created_at: created_at || Date.now(),
+    tier: v.tier || null,
+    delegation_valid: v.delegation_valid === true,
+    effective_scope: Array.isArray(v.effective_scope) ? v.effective_scope : [],
+    gate_id: gate_id || null,
+    requested_action: requested_action || null,
+    display_name: display_name || null,
+    decision: decision || (v.accepted ? 'auto_allow' : 'denied'),
+    reason: v.accepted ? null : v.reason || v.code || 'denied',
+    audience: audience || null,
+  };
+}
+
+/**
+ * The platform's access ledger. Wraps a store and gives you the log helpers a
+ * "who's using my platform" view needs.
+ */
+export class AccessLedger {
+  constructor({ store } = {}) {
+    this.store = store || new MemoryLedgerStore();
+  }
+
+  /**
+   * Log a verdict. Returns the persisted entry. `fields` carries the same
+   * optional arrival fields as `recordEntry` (audience, gate_id,
+   * requested_action, display_name, decision override).
+   */
+  async record(verdict, fields = {}) {
+    const entry = recordEntry(verdict, fields);
+    await this.store.append(entry);
+    return entry;
+  }
+
+  /** Most recent arrivals, newest first. */
+  async recent(opts = {}) {
+    return this.store.recent(opts);
+  }
+
+  /** Recent arrivals from a single operator, newest first. */
+  async byOperator(operatorId, opts = {}) {
+    return this.store.byOperator(operatorId, opts);
+  }
+}
+
+/**
+ * Wrap a gate (or any `(request) => Promise<verdict>`) so every verdict is
+ * logged to a ledger before it's returned. Drop-in around `aitGate(...)` or
+ * `authorizer.gate(gateId)`:
+ *
+ *   const ledger = new AccessLedger();
+ *   const gate = loggedGate(aitGate({ audience }), ledger, { audience, gate_id });
+ *   const verdict = await gate(request);   // logged as a side effect
+ *
+ * `fields` are the static arrival fields to stamp on every entry (audience,
+ * gate_id, requested_action, display_name). Logging failures never block the
+ * request — a store hiccup must not turn an accepted agent away. The verdict is
+ * always returned.
+ */
+export function loggedGate(gate, ledger, fields = {}) {
+  return async function loggingGate(request) {
+    const verdict = await gate(request);
+    try {
+      await ledger.record(verdict, fields);
+    } catch {
+      /* never let a ledger write failure change the verdict */
+    }
+    return verdict;
+  };
+}