@cat-factory/gatekeeper-worker 0.3.1

package/dist/gatekeeper.js

@@ -0,0 +1,162 @@
+// The composition root: everything a request needs, assembled from the environment once.
+//
+// It also holds the flows that are neither pure policy nor pure transport: enrolling this
+// Gatekeeper as an outbound webhook endpoint, taking delivery of one, and retiring an actor.
+//
+// The POLICY arrives as an argument, never as an import. This package is the base a deployment
+// installs; the policy is the one thing that deployment writes, so a `policy.config.ts` this
+// module reached for would be a file the base owns and the operator cannot replace without
+// forking it.
+import { CatFactoryClient } from '@cat-factory/sdk';
+import { buildCapability } from './capability.js';
+import { requireVar } from './env.js';
+import { GatekeeperError } from './errors.js';
+import { KeyBroker } from './keys.js';
+import { compilePolicy, tierForActor, } from './policy/compile.js';
+import { cardEffectOf, readDelivery, SUBSCRIBED_CARD_TYPES } from './webhook/delivery.js';
+import { verifyDelivery } from './webhook/signature.js';
+/** Identifies this integration in the deployment's logs, beside the SDK's own version. */
+const USER_AGENT = 'cat-factory-gatekeeper';
+export class Gatekeeper {
+    #env;
+    #policy;
+    #state;
+    #keys;
+    constructor(env, policy) {
+        this.#env = env;
+        this.#policy = policy;
+        const baseUrl = requireVar(env, 'CAT_FACTORY_BASE_URL');
+        const clientFor = (apiKey) => new CatFactoryClient({ baseUrl, apiKey, userAgent: USER_AGENT });
+        // One durable object per PAIRED DEPLOYMENT, named for the origin it is paired with. The name
+        // is the pairing's own identity, so pointing this Worker at a different cat-factory gets a
+        // different object rather than inheriting the previous one's cards and minted keys.
+        this.#state = env.STATE.get(env.STATE.idFromName(baseUrl));
+        this.#keys = new KeyBroker({
+            state: this.#state,
+            provisioning: clientFor(requireVar(env, 'PROVISIONING_KEY')),
+            clientFor,
+            now: () => Date.now(),
+        });
+    }
+    /**
+     * Assemble against the deployment's own policy, compiling it.
+     *
+     * Throws a `PolicyError` on a policy an operator has to fix, and a `ConfigError` on a binding
+     * they have not set. Both are refusals the request path answers as a 503 naming the cause, which
+     * is why the compile happens per assembly rather than once at module load: a Worker whose policy
+     * threw while its module evaluated serves nothing at all, not even the refusal that says why.
+     */
+    static create(env, policy) {
+        return new Gatekeeper(env, compilePolicy(policy));
+    }
+    /** Whether the presented bearer token is this Gatekeeper's own. */
+    authorize(header) {
+        const expected = requireVar(this.#env, 'OS_SHARED_TOKEN');
+        const presented = header?.startsWith('Bearer ') === true ? header.slice('Bearer '.length) : '';
+        return timingSafeEqualStrings(presented, expected);
+    }
+    /**
+     * The capability for one actor the OS has authenticated.
+     *
+     * The tier is resolved from the Gatekeeper's OWN policy, never from anything the caller sent:
+     * an agent that could name its tier would be its own authorization.
+     */
+    capabilityFor(actor) {
+        const tier = tierForActor(this.#policy, actor.id);
+        if (tier === null) {
+            throw new GatekeeperError('unknown_actor', `No tier is granted to '${actor.id}'. Add them to this Gatekeeper's policy under ` +
+                'grants, or set a defaultTier if this deployment means every OS user to have one.');
+        }
+        return buildCapability({ actor, tier, keys: this.#keys, state: this.#state });
+    }
+    /**
+     * Retire an actor: revoke every key this Gatekeeper minted for them, upstream and here.
+     *
+     * Exposed on the ADMIN surface rather than on a capability, because it is the OS deployment's
+     * offboarding action and not something an agent acting AS someone should be able to do to them.
+     */
+    async retire(actorId) {
+        return await this.#keys.revoke({ id: actorId });
+    }
+    /**
+     * Register this Worker as a named outbound webhook endpoint, idempotently.
+     *
+     * Safe to call on every cron tick and on demand: the route is keyed on the caller-chosen id, so
+     * re-asserting the registration heals a deployment whose endpoint was edited or removed without
+     * ever displacing a sibling integration's slot.
+     */
+    async enroll() {
+        const webhookId = requireVar(this.#env, 'WEBHOOK_ID');
+        const url = new URL('/webhook', requireVar(this.#env, 'PUBLIC_URL')).toString();
+        const provisioning = new CatFactoryClient({
+            baseUrl: requireVar(this.#env, 'CAT_FACTORY_BASE_URL'),
+            apiKey: requireVar(this.#env, 'PROVISIONING_KEY'),
+            userAgent: USER_AGENT,
+        });
+        await provisioning.webhook.setNamed(webhookId, {
+            url,
+            name: 'Cloudflare OS gatekeeper',
+            secret: requireVar(this.#env, 'WEBHOOK_SECRET'),
+            enabled: true,
+            // Subscribe to exactly the card types the inbox raises something for, rather than leaving
+            // `types` unset for the platform's default tail: the defaults and this Gatekeeper's list are
+            // close but not equal, and the gap would arrive as cards that never appear (a type acted on
+            // but not subscribed) or cards nobody can do anything with (the reverse). What each type
+            // OFFERS is the card's `disposition`, so the list can carry a `notice` without the inbox
+            // presenting it as answerable.
+            types: [...SUBSCRIBED_CARD_TYPES],
+            // The lifecycle family is what lets a status Gadget close a run out without polling: it
+            // lands as a `runs_watched()` record, and a terminal event settles the run's open cards. It
+            // is opt-in per event on purpose, so name all three: a Gatekeeper that hears only
+            // `run.started` shows every run as forever in flight.
+            runEvents: ['run.started', 'run.completed', 'run.failed'],
+        });
+        return { webhookId, url };
+    }
+    /**
+     * Take delivery of one webhook POST.
+     *
+     * Order matters and is the whole security story of this method: verify the MAC over the RAW
+     * bytes FIRST, parse SECOND, and hand the dedupe and the effect to durable state as ONE call.
+     * Parsing before verifying would run this deployment's JSON decoder over unauthenticated input.
+     * Deduping in a call of its own would be worse than useless: a marker committed before the card
+     * write turns a failed write into a `duplicate` on the platform's retry, so the approval never
+     * reaches the inbox and nothing anywhere reports that it did not.
+     */
+    async takeDelivery(request, now) {
+        const rawBody = await request.text();
+        const verdict = await verifyDelivery(request.headers, rawBody, requireVar(this.#env, 'WEBHOOK_SECRET'), now);
+        if (!verdict.ok)
+            return { handled: 'rejected', reason: verdict.reason };
+        let parsed;
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            return { handled: 'unparseable' };
+        }
+        const delivery = readDelivery(parsed);
+        if (delivery === null)
+            return { handled: 'unparseable' };
+        const applied = await this.#state.applyDelivery(delivery.deliveryId, cardEffectOf(delivery), now);
+        if (!applied.applied)
+            return { handled: 'duplicate', deliveryId: delivery.deliveryId };
+        return { handled: 'accepted', deliveryId: delivery.deliveryId, effect: applied.effect };
+    }
+}
+/**
+ * Compare two secrets without an early exit on the first differing character.
+ *
+ * Lengths are compared first and that difference does leak, which is acceptable for a token the
+ * caller supplies: the alternative (hashing both to a fixed width) buys nothing here, since the
+ * expected token's length is a deployment constant an attacker cannot vary their way into.
+ */
+function timingSafeEqualStrings(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+//# sourceMappingURL=gatekeeper.js.map

package/dist/gatekeeper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatekeeper.js","sourceRoot":"","sources":["../src/gatekeeper.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createGatekeeperWorker, type GatekeeperWorkerOptions } from './worker.js';
+export { Gatekeeper, type DeliveryOutcome } from './gatekeeper.js';
+export { GatekeeperState, type ApprovalCard, type DeliveryApplication, type DeliveryEffect, type MintClaim, type MintTicket, type RunState, type StoredKey, } from './state.js';
+export { ConfigError, type GatekeeperEnv } from './env.js';
+export { buildCapability, type CardInspection, type SessionDependencies, type TierSummary, } from './capability.js';
+export { KeyBroker, type Actor, type KeyBrokerDependencies, type LeasedClient } from './keys.js';
+export { answerCard, assertAnswerable, describeStale, pendingParks, type AnswerInput, type AnswerOutcome, type BindingInvoker, type DecisionListShape, type PendingPark, } from './approvals.js';
+export { cardEffectOf, dispositionOf, PARKED_DECISION_CARD_TYPES, readDelivery, SUBSCRIBED_CARD_TYPES, type CardDisposition, type Delivery, } from './webhook/delivery.js';
+export { DEFAULT_MAX_SKEW_MS, verifyDelivery, type VerificationResult, } from './webhook/signature.js';
+export * from './policy/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,sBAAsB,EAAE,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAIlE,OAAO,EACL,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,SAAS,GACf,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAA;AAC1D,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,KAAK,EAAE,KAAK,qBAAqB,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAA;AAEhG,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,0BAA0B,EAC1B,YAAY,EACZ,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAA;AAI/B,cAAc,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,23 @@
+// `@cat-factory/gatekeeper-worker`: the Gatekeeper machinery a deployment INSTALLS, as opposed to
+// the policy and the wiring it WRITES (`deploy/gatekeeper` is the template for those).
+//
+// The split is what makes an upgrade a dependency bump. Everything here is deployment-neutral: the
+// Cap'n Web capability surface, the per-actor key broker, the delivery receiver and its verifier,
+// the approval inbox and the per-park answerers, the Durable Object all four keep their state in.
+// What is NOT here is the one thing that differs per deployment, the policy, which arrives as an
+// argument to `createGatekeeperWorker`.
+export { createGatekeeperWorker } from './worker.js';
+export { Gatekeeper } from './gatekeeper.js';
+// The Durable Object class. A deployment re-exports it from its own entry module, because
+// wrangler's `class_name` binding resolves against the Worker's exports, not this package's.
+export { GatekeeperState, } from './state.js';
+export { ConfigError } from './env.js';
+export { buildCapability, } from './capability.js';
+export { KeyBroker } from './keys.js';
+export { answerCard, assertAnswerable, describeStale, pendingParks, } from './approvals.js';
+export { cardEffectOf, dispositionOf, PARKED_DECISION_CARD_TYPES, readDelivery, SUBSCRIBED_CARD_TYPES, } from './webhook/delivery.js';
+export { DEFAULT_MAX_SKEW_MS, verifyDelivery, } from './webhook/signature.js';
+// The policy vocabulary, also reachable on its own at `@cat-factory/gatekeeper-worker/policy` for
+// a policy file that should not have to load a Worker runtime to be read or tested.
+export * from './policy/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,uFAAuF;AACvF,EAAE;AACF,mGAAmG;AACnG,kGAAkG;AAClG,kGAAkG;AAClG,iGAAiG;AACjG,wCAAwC;AAExC,OAAO,EAAE,sBAAsB,EAAgC,MAAM,aAAa,CAAA;AAClF,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAA;AAElE,0FAA0F;AAC1F,6FAA6F;AAC7F,OAAO,EACL,eAAe,GAQhB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,WAAW,EAAsB,MAAM,UAAU,CAAA;AAC1D,OAAO,EACL,eAAe,GAIhB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,SAAS,EAA6D,MAAM,WAAW,CAAA;AAEhG,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,GAMb,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,0BAA0B,EAC1B,YAAY,EACZ,qBAAqB,GAGtB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,mBAAmB,EACnB,cAAc,GAEf,MAAM,wBAAwB,CAAA;AAE/B,kGAAkG;AAClG,oFAAoF;AACpF,cAAc,mBAAmB,CAAA"}

package/dist/keys.d.ts

@@ -0,0 +1,62 @@
+import { CatFactoryClient } from '@cat-factory/sdk';
+import type { PublicApiScope } from '@cat-factory/gatekeeper-bindings';
+import type { GatekeeperState } from './state.js';
+/** Who the OS says is calling. The Gatekeeper trusts this and NOTHING else the caller sends. */
+export interface Actor {
+    /** The OS's own identity for the person. Rides `externalIdentity` onto every minted key. */
+    id: string;
+    /** Optional display name, used only to label the key for a human reading the key list. */
+    label?: string;
+}
+export interface KeyBrokerDependencies {
+    /** The paired workspace's durable state, holding minted keys. */
+    state: DurableObjectStub<GatekeeperState>;
+    /** A client on the Gatekeeper's own `admin` provisioning key. */
+    provisioning: CatFactoryClient;
+    /** Build a client on a minted key. */
+    clientFor: (apiKey: string) => CatFactoryClient;
+    now: () => number;
+    /** Wait, injected so the claim-contention path is testable without real time. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * A leased client, paired with the key it is authenticated as.
+ *
+ * The key id travels with it because the caller needs it on failure, not on success: dropping a
+ * rejected credential has to name WHICH one it is dropping, or a concurrent call that has already
+ * minted the replacement loses it.
+ */
+export interface LeasedClient {
+    client: CatFactoryClient;
+    keyId: string;
+}
+export declare class KeyBroker {
+    #private;
+    constructor(deps: KeyBrokerDependencies);
+    /**
+     * Run one call as `actor`, at `scope`, re-minting once if the credential is rejected.
+     *
+     * The retry is deliberately narrow: ONE re-mint, on a 401 only, after dropping the row that
+     * produced it. Anything wider would turn a genuinely unusable deployment into a mint loop, and
+     * anything narrower would make the documented "rotate the provisioning key" kill switch a
+     * permanent outage for every actor whose key was cached.
+     *
+     * The scope is the TIER's, never the caller's request: a caller asking for a better key is
+     * asking the wrong side of the boundary.
+     */
+    run<T>(actor: Actor, scope: PublicApiScope, call: (client: CatFactoryClient) => Promise<T>): Promise<T>;
+    /**
+     * Revoke every key minted for an actor, for when the OS says they are gone.
+     *
+     * Revoked UPSTREAM FIRST, then forgotten, and only what was actually revoked is forgotten. The
+     * other order can leave a live cat-factory key that this Gatekeeper no longer knows exists,
+     * which is a credential nobody can find to revoke; this order can at worst re-revoke an id,
+     * which the platform documents as idempotent. A revoke that fails part-way leaves the rest of
+     * the rows in place, so a second call finishes the job rather than losing track of them.
+     */
+    revoke(actor: Actor): Promise<{
+        revoked: string[];
+        remaining: string[];
+    }>;
+}
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,gBAAgB,EAA+B,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,YAAY,CAAA;AAE5D,gGAAgG;AAChG,MAAM,WAAW,KAAK;IACpB,4FAA4F;IAC5F,EAAE,EAAE,MAAM,CAAA;IACV,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAWD,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,KAAK,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAA;IACzC,iEAAiE;IACjE,YAAY,EAAE,gBAAgB,CAAA;IAC9B,sCAAsC;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,CAAA;IAC/C,GAAG,EAAE,MAAM,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,qBAAa,SAAS;;IAIpB,YAAY,IAAI,EAAE,qBAAqB,EAGtC;IAED;;;;;;;;;;OAUG;IACG,GAAG,CAAC,CAAC,EACT,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAwBZ;IAED;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAgB9E;CAiDF"}

package/dist/keys.js

@@ -0,0 +1,152 @@
+// Per-actor credentials: the reason an OS user's run is attributable at all.
+//
+// A Gatekeeper could forward every call on one shared workspace key, and every run would then be
+// started by "the integration". That loses the two things the platform builds on the caller's
+// identity: `externalIdentity` mapping a run back to a person without cat-factory holding your
+// directory (slice 3), and role-scoped merge policy, which refuses a landing a shared credential
+// should not make (ADR 0037/0039). So each actor gets their OWN key, minted at the tier's scope
+// and stamped with their identity.
+//
+// Minting is CACHED, not per call. `POST /api/v1/keys` returns the raw secret exactly once, so a
+// Gatekeeper that re-mints per call both spends a key row per operation and leaves a growing set
+// of live credentials it has already forgotten how to revoke.
+//
+// Two things follow from "the mint is a real, non-idempotent side effect that returns its secret
+// once", and both are the difference between a cache and a leak:
+//
+//   - IT IS CLAIMED BEFORE IT RUNS. A read-then-mint-then-write has two pipelined calls for one
+//     actor both seeing "no key yet"; both mint, the second write wins, and the loser's key stays
+//     live upstream with nothing here recording that it exists. The claim is taken atomically in
+//     the Durable Object and expires, so a Worker that dies mid-mint does not wedge the actor out.
+//   - A REJECTED KEY IS DROPPED, NOT RETRIED FOREVER. The documented kill switch is revoking the
+//     provisioning key, which revokes every key it minted; a cache with no invalidation answers
+//     every call after that with the same dead secret and a 401 nobody can clear short of wiping
+//     the object. A 401 drops the row and re-mints ONCE, so a rotation heals itself and a genuinely
+//     unusable credential still fails rather than looping.
+import { CatFactoryClient, CatFactoryUnauthorizedError } from '@cat-factory/sdk';
+import { GatekeeperError } from './errors.js';
+/** The label cap the key contract enforces. */
+const MAX_LABEL_LENGTH = 120;
+/** How many times a caller re-reads a claim another call is holding before giving up. */
+const MINT_CLAIM_POLLS = 20;
+/** How long between those reads. Short: the claim is held across one `POST /api/v1/keys`. */
+const MINT_CLAIM_POLL_MS = 100;
+export class KeyBroker {
+    #deps;
+    #sleep;
+    constructor(deps) {
+        this.#deps = deps;
+        this.#sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /**
+     * Run one call as `actor`, at `scope`, re-minting once if the credential is rejected.
+     *
+     * The retry is deliberately narrow: ONE re-mint, on a 401 only, after dropping the row that
+     * produced it. Anything wider would turn a genuinely unusable deployment into a mint loop, and
+     * anything narrower would make the documented "rotate the provisioning key" kill switch a
+     * permanent outage for every actor whose key was cached.
+     *
+     * The scope is the TIER's, never the caller's request: a caller asking for a better key is
+     * asking the wrong side of the boundary.
+     */
+    async run(actor, scope, call) {
+        const leased = await this.#lease(actor, scope);
+        try {
+            return await call(leased.client);
+        }
+        catch (error) {
+            if (!(error instanceof CatFactoryUnauthorizedError))
+                throw error;
+            const dropped = await this.#deps.state.forgetKeyIfCurrent(actor.id, scope, leased.keyId);
+            if (!dropped) {
+                // Another call already replaced it, so the credential in hand is simply stale. Retrying on
+                // the replacement is the same one-shot, not a second one.
+                return await call((await this.#lease(actor, scope)).client);
+            }
+            const fresh = await this.#lease(actor, scope);
+            try {
+                return await call(fresh.client);
+            }
+            catch (retryError) {
+                if (!(retryError instanceof CatFactoryUnauthorizedError))
+                    throw retryError;
+                throw new GatekeeperError('credential_rejected', `A freshly minted '${scope}' key for '${actor.id}' was refused by the deployment. The ` +
+                    'provisioning key is the likely cause: check it is still live and still `admin`-scoped.');
+            }
+        }
+    }
+    /**
+     * Revoke every key minted for an actor, for when the OS says they are gone.
+     *
+     * Revoked UPSTREAM FIRST, then forgotten, and only what was actually revoked is forgotten. The
+     * other order can leave a live cat-factory key that this Gatekeeper no longer knows exists,
+     * which is a credential nobody can find to revoke; this order can at worst re-revoke an id,
+     * which the platform documents as idempotent. A revoke that fails part-way leaves the rest of
+     * the rows in place, so a second call finishes the job rather than losing track of them.
+     */
+    async revoke(actor) {
+        const stored = await this.#deps.state.listKeys(actor.id);
+        const revoked = [];
+        const revokedScopes = [];
+        for (const { scope, key } of stored) {
+            await this.#deps.provisioning.keys.revoke(key.keyId);
+            revoked.push(key.keyId);
+            revokedScopes.push(scope);
+        }
+        await this.#deps.state.forgetKeys(actor.id, revokedScopes);
+        return {
+            revoked,
+            remaining: stored
+                .filter(({ scope }) => !revokedScopes.includes(scope))
+                .map(({ key }) => key.keyId),
+        };
+    }
+    async #lease(actor, scope) {
+        for (let attempt = 0; attempt <= MINT_CLAIM_POLLS; attempt++) {
+            const ticket = await this.#deps.state.claimKeyMint(actor.id, scope, this.#deps.now());
+            if (ticket.outcome === 'existing') {
+                return { client: this.#deps.clientFor(ticket.key.secret), keyId: ticket.key.keyId };
+            }
+            if (ticket.outcome === 'claimed')
+                return await this.#mint(actor, scope);
+            await this.#sleep(Math.min(MINT_CLAIM_POLL_MS, ticket.retryAfterMs));
+        }
+        throw new GatekeeperError('credential_rejected', `Minting a '${scope}' key for '${actor.id}' is still in flight on another request after ` +
+            `${MINT_CLAIM_POLLS * MINT_CLAIM_POLL_MS}ms. Retry; if it persists, the deployment's ` +
+            '`POST /api/v1/keys` is failing in a way that leaves the claim to expire.');
+    }
+    /**
+     * Mint under a held claim.
+     *
+     * The claim is RELEASED on failure rather than left to expire: a deployment that is briefly
+     * unreachable should not lock the actor out for the claim's whole TTL, and the release is safe
+     * precisely because nothing was minted.
+     */
+    async #mint(actor, scope) {
+        let created;
+        try {
+            created = await this.#deps.provisioning.keys.create({
+                label: keyLabel(actor, scope),
+                scope: scope,
+                externalIdentity: actor.id,
+            });
+        }
+        catch (error) {
+            await this.#deps.state.releaseKeyMint(actor.id, scope);
+            throw error;
+        }
+        const key = {
+            keyId: created.key.id,
+            secret: created.secret,
+            mintedAt: this.#deps.now(),
+        };
+        // Stored BEFORE the client is handed out: the secret came back exactly once, so losing it
+        // between here and the caller would leave a live credential nobody can revoke.
+        await this.#deps.state.commitKeyMint(actor.id, scope, key);
+        return { client: this.#deps.clientFor(key.secret), keyId: key.keyId };
+    }
+}
+function keyLabel(actor, scope) {
+    return `gatekeeper ${scope}: ${actor.label ?? actor.id}`.slice(0, MAX_LABEL_LENGTH);
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,iGAAiG;AACjG,8FAA8F;AAC9F,+FAA+F;AAC/F,iGAAiG;AACjG,gGAAgG;AAChG,mCAAmC;AACnC,EAAE;AACF,iGAAiG;AACjG,iGAAiG;AACjG,8DAA8D;AAC9D,EAAE;AACF,iGAAiG;AACjG,iEAAiE;AACjE,EAAE;AACF,gGAAgG;AAChG,kGAAkG;AAClG,iGAAiG;AACjG,mGAAmG;AACnG,iGAAiG;AACjG,gGAAgG;AAChG,iGAAiG;AACjG,oGAAoG;AACpG,2DAA2D;AAE3D,OAAO,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAW7C,+CAA+C;AAC/C,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAE5B,yFAAyF;AACzF,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAE3B,6FAA6F;AAC7F,MAAM,kBAAkB,GAAG,GAAG,CAAA;AA0B9B,MAAM,OAAO,SAAS;IACX,KAAK,CAAuB;IAC5B,MAAM,CAA+B;IAE9C,YAAY,IAA2B;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,CACP,KAAY,EACZ,KAAqB,EACrB,IAA8C;QAE9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAC9C,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,2BAA2B,CAAC;gBAAE,MAAM,KAAK,CAAA;YAChE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;YACxF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,2FAA2F;gBAC3F,0DAA0D;gBAC1D,OAAO,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;YAC7D,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;YAC7C,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;YACjC,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,IAAI,CAAC,CAAC,UAAU,YAAY,2BAA2B,CAAC;oBAAE,MAAM,UAAU,CAAA;gBAC1E,MAAM,IAAI,eAAe,CACvB,qBAAqB,EACrB,qBAAqB,KAAK,cAAc,KAAK,CAAC,EAAE,uCAAuC;oBACrF,wFAAwF,CAC3F,CAAA;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CAAC,KAAY;QACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACxD,MAAM,OAAO,GAAa,EAAE,CAAA;QAC5B,MAAM,aAAa,GAAa,EAAE,CAAA;QAClC,KAAK,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,MAAM,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACpD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACvB,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,aAAa,CAAC,CAAA;QAC1D,OAAO;YACL,OAAO;YACP,SAAS,EAAE,MAAM;iBACd,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;iBACrD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC;SAC/B,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAY,EAAE,KAAqB;QAC9C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,gBAAgB,EAAE,OAAO,EAAE,EAAE,CAAC;YAC7D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;YACrF,IAAI,MAAM,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBAClC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;YACrF,CAAC;YACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;gBAAE,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;YACvE,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC,CAAA;QACtE,CAAC;QACD,MAAM,IAAI,eAAe,CACvB,qBAAqB,EACrB,cAAc,KAAK,cAAc,KAAK,CAAC,EAAE,gDAAgD;YACvF,GAAG,gBAAgB,GAAG,kBAAkB,8CAA8C;YACtF,0EAA0E,CAC7E,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,KAAY,EAAE,KAAqB;QAC7C,IAAI,OAAgE,CAAA;QACpE,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;gBAClD,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;gBAC7B,KAAK,EAAE,KAAoC;gBAC3C,gBAAgB,EAAE,KAAK,CAAC,EAAE;aAC3B,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;YACtD,MAAM,KAAK,CAAA;QACb,CAAC;QAED,MAAM,GAAG,GAAc;YACrB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE;YACrB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;SAC3B,CAAA;QACD,0FAA0F;QAC1F,+EAA+E;QAC/E,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;QAC1D,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAA;IACvE,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAY,EAAE,KAAqB;IACnD,OAAO,cAAc,KAAK,KAAK,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAA;AACrF,CAAC"}

package/dist/masking.d.ts

@@ -0,0 +1,9 @@
+/** What a masked leaf becomes. Stated, never removed. */
+export declare const MASKED = "[masked by gatekeeper policy]";
+/**
+ * Apply every masked path to one result, returning a copy. The input is never mutated: the same
+ * decoded body may be handed to more than one consumer (a card derivation and the caller's
+ * result), and a mask applied in place would silently redact the other one too.
+ */
+export declare function applyMask(value: unknown, paths: readonly string[]): unknown;
+//# sourceMappingURL=masking.d.ts.map

package/dist/masking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"masking.d.ts","sourceRoot":"","sources":["../src/masking.ts"],"names":[],"mappings":"AAYA,yDAAyD;AACzD,eAAO,MAAM,MAAM,kCAAkC,CAAA;AAiBrD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAQ3E"}

package/dist/masking.js

@@ -0,0 +1,43 @@
+// Field masking: dropping a value from a result before it reaches the caller.
+//
+// The one rule worth stating is that masking REPLACES rather than deletes. A removed key and a
+// key the deployment had no value for read identically to the agent consuming the result, and
+// they are different facts: "your policy hides this" is a question for an operator, while "the
+// platform said null" is an answer about the run. So a masked leaf becomes the sentinel below,
+// which says which of the two happened, in the shape every other value already has.
+//
+// Paths are dotted and traverse arrays element-wise (`steps.status` masks the status of every
+// step). A path that matches nothing is not an error: a result shape legitimately varies by
+// operation, and a policy naming a field some responses do not carry is not a misconfiguration.
+/** What a masked leaf becomes. Stated, never removed. */
+export const MASKED = '[masked by gatekeeper policy]';
+function maskIn(value, segments) {
+    const [head, ...rest] = segments;
+    if (head === undefined)
+        return MASKED;
+    if (Array.isArray(value)) {
+        return value.map((element) => maskIn(element, segments));
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const source = value;
+    if (!(head in source))
+        return value;
+    return { ...source, [head]: maskIn(source[head], rest) };
+}
+/**
+ * Apply every masked path to one result, returning a copy. The input is never mutated: the same
+ * decoded body may be handed to more than one consumer (a card derivation and the caller's
+ * result), and a mask applied in place would silently redact the other one too.
+ */
+export function applyMask(value, paths) {
+    let masked = value;
+    for (const path of paths) {
+        const segments = path.split('.').filter((segment) => segment.length > 0);
+        if (segments.length === 0)
+            continue;
+        masked = maskIn(masked, segments);
+    }
+    return masked;
+}
+//# sourceMappingURL=masking.js.map

package/dist/masking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"masking.js","sourceRoot":"","sources":["../src/masking.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,+FAA+F;AAC/F,8FAA8F;AAC9F,+FAA+F;AAC/F,+FAA+F;AAC/F,oFAAoF;AACpF,EAAE;AACF,8FAA8F;AAC9F,4FAA4F;AAC5F,gGAAgG;AAEhG,yDAAyD;AACzD,MAAM,CAAC,MAAM,MAAM,GAAG,+BAA+B,CAAA;AAErD,SAAS,MAAM,CAAC,KAAc,EAAE,QAA2B;IACzD,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAA;IAChC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAA;IAErC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC1D,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAE7D,MAAM,MAAM,GAAG,KAAgC,CAAA;IAC/C,IAAI,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC;QAAE,OAAO,KAAK,CAAA;IAEnC,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,CAAA;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,KAAwB;IAChE,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACxE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QACnC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/policy/compile.d.ts

@@ -0,0 +1,88 @@
+import { type GatekeeperBinding, type PublicApiScope } from '@cat-factory/gatekeeper-bindings';
+/**
+ * What one tier of caller may do.
+ *
+ * `keyScope` is the scope of the cat-factory key the Gatekeeper mints for callers at this tier,
+ * and it is also the ceiling on what the tier can be granted. The two being ONE value is what
+ * keeps the credential and the capability from disagreeing.
+ */
+export interface TierPolicy {
+    /** Prose an OS deployment shows beside the tier. */
+    description: string;
+    /** The scope of the per-actor key this tier's calls are made with. */
+    keyScope: PublicApiScope;
+    /** Binding names to grant, or `'*'` for every binding within `keyScope`. */
+    allow: readonly string[] | '*';
+    /** Binding names to subtract from `allow`. Applied last, so a deny always wins. */
+    deny?: readonly string[];
+    /**
+     * Dotted paths masked out of every result before it reaches the caller, e.g.
+     * `run.pullRequestUrl`. Masking is REDACTION, not omission: see `masking.ts`.
+     */
+    mask?: readonly string[];
+}
+/** The whole policy: the tiers, and which OS actor gets which. */
+export interface GatekeeperPolicy {
+    /** The tier an actor with no explicit grant is given. Name `null` to refuse unknown actors. */
+    defaultTier: string | null;
+    tiers: Record<string, TierPolicy>;
+    /** OS user identity (whatever the OS authenticates) to tier name. */
+    grants: Record<string, string>;
+}
+/** Why a binding the deployment serves is not on a capability. */
+export type WithheldReason = 'not_in_policy' | 'denied_by_policy' | 'above_key_scope' | 'not_relayable';
+/** One binding the tier does not carry, and why. */
+export interface WithheldBinding {
+    name: string;
+    reason: WithheldReason;
+    detail: string;
+}
+/** A tier, resolved against the live operation table. */
+export interface CompiledTier {
+    name: string;
+    description: string;
+    keyScope: PublicApiScope;
+    granted: readonly GatekeeperBinding[];
+    /**
+     * Every binding this tier does NOT carry, with the reason. Published on the capability
+     * (`withheld()`) because an agent that cannot tell "policy withheld this" from "the deployment
+     * does not have it" will report the wrong one to whoever has to fix it.
+     */
+    withheld: readonly WithheldBinding[];
+    mask: readonly string[];
+}
+/** The policy, resolved once and read per request. */
+export interface CompiledPolicy {
+    defaultTier: string | null;
+    tiers: ReadonlyMap<string, CompiledTier>;
+    grants: ReadonlyMap<string, string>;
+}
+/**
+ * Compile a policy against the live operation table, or throw a {@link PolicyError} naming the
+ * first thing an operator has to fix.
+ */
+export declare function compilePolicy(policy: GatekeeperPolicy): CompiledPolicy;
+/**
+ * The tier an actor holds, or a refusal.
+ *
+ * Note what is NOT here: nothing the CALLER sends picks a tier. The OS authenticates the person
+ * and the Gatekeeper resolves what that person may do, so a compromised or confused agent cannot
+ * ask for a better one.
+ */
+export declare function tierForActor(policy: CompiledPolicy, actorId: string): CompiledTier | null;
+/**
+ * What the OS needs to run its own approval governance over a call: the consequence the platform
+ * annotates, with the cautious default already applied.
+ */
+export declare function describeBinding(binding: GatekeeperBinding): {
+    name: string;
+    summary: string;
+    minScope: PublicApiScope;
+    readOnly: boolean;
+    destructive: boolean;
+    idempotent: boolean;
+    pathParams: readonly string[];
+    queryParams: readonly string[];
+    hasBody: boolean;
+};
+//# sourceMappingURL=compile.d.ts.map

package/dist/policy/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/policy/compile.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,kCAAkC,CAAA;AAGzC;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,QAAQ,EAAE,cAAc,CAAA;IACxB,4EAA4E;IAC5E,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAA;IAC9B,mFAAmF;IACnF,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzB;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACjC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,kEAAkE;AAClE,MAAM,MAAM,cAAc,GACtB,eAAe,GACf,kBAAkB,GAClB,iBAAiB,GACjB,eAAe,CAAA;AAEnB,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,cAAc,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,cAAc,CAAA;IACxB,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACrC;;;;OAIG;IACH,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;IACpC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACxB;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACxC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACpC;AA2HD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,cAAc,CAqBtE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAIzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG;IAC3D,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,cAAc,CAAA;IACxB,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,OAAO,EAAE,OAAO,CAAA;CACjB,CAaA"}