@cat-factory/gatekeeper-worker 0.3.1

package/dist/capability.d.ts

@@ -0,0 +1,61 @@
+import { RpcTarget } from 'capnweb';
+import type { Actor, KeyBroker } from './keys.js';
+import { type CompiledTier } from './policy/compile.js';
+import type { ApprovalCard, GatekeeperState } from './state.js';
+export interface SessionDependencies {
+    actor: Actor;
+    tier: CompiledTier;
+    keys: KeyBroker;
+    state: DurableObjectStub<GatekeeperState>;
+}
+/** What `tier()` answers: enough for an OS Gadget to render who the caller is acting as. */
+export interface TierSummary {
+    actorId: string;
+    tier: string;
+    description: string;
+    keyScope: string;
+}
+/**
+ * What `approvals_inspect()` answers: the card, what the run is ACTUALLY parked on now, and which
+ * verbs this tier can reach.
+ *
+ * The reason this exists beside `approvals_answer` is the same one `withheld()` exists beside
+ * `bindings()`: an agent composing an answer needs to know what the park takes and whether its own
+ * tier holds the operation, and deriving either from a doc is how an integration ends up posting a
+ * body the platform refuses with a 422 that names a field the agent never chose.
+ */
+export interface CardInspection {
+    card: ApprovalCard;
+    /** The run's live decision list, verbatim. The webhook is a trigger; this is the truth. */
+    decisions: unknown;
+    /** What the run is parked on and can be answered from here, with the verbs each takes. */
+    parks: {
+        kind: string;
+        summary: string;
+        actions: {
+            action: string;
+            binding: string;
+            summary: string;
+            /** False when this tier was not granted the binding: the verb exists, this caller cannot use it. */
+            granted: boolean;
+            fields: readonly {
+                name: string;
+                required: boolean;
+                choices?: readonly string[];
+                detail: string;
+            }[];
+        }[];
+    }[];
+    /** Present only when nothing is answerable, saying which of the several reasons it is. */
+    stale?: string;
+}
+/**
+ * Build the capability for one connected actor.
+ *
+ * Returns an `RpcTarget` whose prototype carries exactly the granted operations plus the reserved
+ * methods above. Each call resolves the actor's own key (minted once, cached durably) and
+ * forwards through the binding's `invoke` thunk, so retry, encoding and error mapping stay the
+ * SDK's job and this layer only ever decides WHO and WHETHER.
+ */
+export declare function buildCapability(deps: SessionDependencies): RpcTarget;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAYnC,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAEjD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAY,MAAM,YAAY,CAAA;AAoBzE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAA;IACZ,IAAI,EAAE,YAAY,CAAA;IAClB,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAA;CAC1C;AAED,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAA;IAClB,2FAA2F;IAC3F,SAAS,EAAE,OAAO,CAAA;IAClB,0FAA0F;IAC1F,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE;YACP,MAAM,EAAE,MAAM,CAAA;YACd,OAAO,EAAE,MAAM,CAAA;YACf,OAAO,EAAE,MAAM,CAAA;YACf,oGAAoG;YACpG,OAAO,EAAE,OAAO,CAAA;YAChB,MAAM,EAAE,SAAS;gBACf,IAAI,EAAE,MAAM,CAAA;gBACZ,QAAQ,EAAE,OAAO,CAAA;gBACjB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;gBAC3B,MAAM,EAAE,MAAM,CAAA;aACf,EAAE,CAAA;SACJ,EAAE,CAAA;KACJ,EAAE,CAAA;IACH,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,CAwGpE"}

package/dist/capability.js

@@ -0,0 +1,125 @@
+// The object-capability itself: what an OS workspace agent actually holds.
+//
+// The design rule that makes this a capability rather than a permission check is that the granted
+// operations are the object's METHODS. A tier without `tasks_delete` does not get a `tasks_delete`
+// that refuses; it gets an object with no such method, so the refusal is a `TypeError` from the
+// caller's own runtime and there is no allow-list to get backwards. What policy CAN still get
+// wrong (which names are granted) is checked once, at compile time, against the live operation
+// table; what it cannot get wrong is checked by JavaScript.
+//
+// Methods live on a per-session PROTOTYPE, never on the instance. Cap'n Web deliberately refuses
+// to serve an RpcTarget's own instance properties (they would leak private internals), so an
+// instance-property capability would be a set of methods no caller can reach.
+import { RpcTarget } from 'capnweb';
+import { answerCard, assertAnswerable, pendingParks, describeStale, } from './approvals.js';
+import { GatekeeperError, PolicyError } from './errors.js';
+import { applyMask } from './masking.js';
+import { describeBinding } from './policy/compile.js';
+/**
+ * The methods a capability carries beyond its granted bindings.
+ *
+ * Reserved rather than merely used: a future `/api/v1` resource group called `approvals` would
+ * generate a binding named `approvals_list`, and silently overwriting one of these with it (or
+ * the other way round) is the kind of collision that reads as a missing feature. It is checked at
+ * build time and refused as a policy error, because the fix is a rename in this file.
+ */
+const RESERVED_METHODS = [
+    'tier',
+    'bindings',
+    'withheld',
+    'approvals_list',
+    'approvals_inspect',
+    'approvals_answer',
+    'runs_watched',
+];
+/**
+ * Build the capability for one connected actor.
+ *
+ * Returns an `RpcTarget` whose prototype carries exactly the granted operations plus the reserved
+ * methods above. Each call resolves the actor's own key (minted once, cached durably) and
+ * forwards through the binding's `invoke` thunk, so retry, encoding and error mapping stay the
+ * SDK's job and this layer only ever decides WHO and WHETHER.
+ */
+export function buildCapability(deps) {
+    const { tier } = deps;
+    const granted = new Map(tier.granted.map((binding) => [binding.name, binding]));
+    for (const reserved of RESERVED_METHODS) {
+        if (granted.has(reserved)) {
+            throw new PolicyError(`Binding '${reserved}' collides with a reserved capability method. Rename the reserved ` +
+                'method in capability.ts; a granted operation must never be shadowed by one.');
+        }
+    }
+    const invoke = async (name, args) => {
+        const binding = granted.get(name);
+        if (binding === undefined) {
+            throw new GatekeeperError('binding_not_granted', `Tier '${tier.name}' does not grant '${name}'.`);
+        }
+        const result = await deps.keys.run(deps.actor, tier.keyScope, (client) => binding.invoke(client, args));
+        return applyMask(result, tier.mask);
+    };
+    class Capability extends RpcTarget {
+    }
+    const proto = Capability.prototype;
+    for (const binding of tier.granted) {
+        proto[binding.name] = (args = {}) => invoke(binding.name, args);
+    }
+    proto.tier = () => ({
+        actorId: deps.actor.id,
+        tier: tier.name,
+        description: tier.description,
+        keyScope: tier.keyScope,
+    });
+    // The two halves of "what can I do here", answered separately on purpose. `bindings()` carries
+    // the consequence annotations with the cautious default applied, so the OS can run its own
+    // approval governance over a call without re-deriving what "destructive" means.
+    proto.bindings = () => tier.granted.map(describeBinding);
+    // `withheld()` is the degrade-loudly half: an agent that cannot tell "your policy hides this"
+    // from "this deployment does not have it" reports the wrong one to whoever has to fix it.
+    proto.withheld = () => tier.withheld;
+    proto.approvals_list = () => deps.state.listCards();
+    // The lifecycle projection the `run.*` subscription feeds. Without it those deliveries would be
+    // verified, deduped and dropped, and a status Gadget would be back to polling `tasks_get_run`
+    // for a transition the platform already pushed.
+    proto.runs_watched = () => deps.state.listRunStates();
+    proto.approvals_inspect = async (cardId) => {
+        const card = await deps.state.getCard(cardId);
+        if (card === null) {
+            throw new GatekeeperError('card_not_found', `No approval card '${cardId}'. It may have been raised against a different paired ` +
+                'workspace, or predate this Gatekeeper.');
+        }
+        const list = (await invoke('decisions_list', { runId: card.runId }));
+        const parks = pendingParks(list).map((park) => ({
+            kind: park.kind,
+            summary: park.summary,
+            actions: park.verbs.map((verb) => ({
+                action: verb.action,
+                binding: verb.binding,
+                summary: verb.summary,
+                granted: granted.has(verb.binding),
+                fields: verb.fields,
+            })),
+        }));
+        return {
+            card,
+            decisions: list,
+            parks,
+            ...(parks.length === 0 ? { stale: describeStale(list) } : {}),
+        };
+    };
+    proto.approvals_answer = async (cardId, input) => {
+        const card = assertAnswerable(await deps.state.getCard(cardId), cardId);
+        const outcome = await answerCard(card, input, invoke);
+        // Only an answer that left the run UNPARKED settles the card. An approval short of quorum, or
+        // a reply the incorporation has not folded in yet, leaves it open because the next answerer
+        // still has to see it. A `stale` answer settles nothing either: the run may be held by a wait
+        // a person has to clear elsewhere, and destroying the card would remove the one pointer to it
+        // that the inbox had. The platform re-delivers a card under a new notification id, so a
+        // wrongly settled one is never re-raised.
+        if (outcome.status === 'answered') {
+            await deps.state.resolveCard(cardId, `${outcome.kind}:${outcome.action}`, Date.now());
+        }
+        return outcome;
+    };
+    return new Capability();
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

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

package/dist/env.d.ts

@@ -0,0 +1,45 @@
+import type { GatekeeperState } from './state.js';
+export interface GatekeeperEnv {
+    /** The cat-factory deployment's origin, e.g. `https://cat-factory.example.com`. */
+    CAT_FACTORY_BASE_URL: string;
+    /**
+     * The webhook id this Gatekeeper enrols under. Caller-chosen and idempotent by design, so a
+     * cold-booting Worker writes its own well-known id with no create-or-discover round trip.
+     */
+    WEBHOOK_ID: string;
+    /** This Worker's own public origin, the URL the platform delivers to. */
+    PUBLIC_URL: string;
+    /** An `admin` cat-factory key. Mints per-actor keys and nothing else; never leaves the Worker. */
+    PROVISIONING_KEY: string;
+    /** The signing secret this Gatekeeper registers, and verifies every delivery against. */
+    WEBHOOK_SECRET: string;
+    /** The bearer token the paired Cloudflare OS deployment presents on every RPC call. */
+    OS_SHARED_TOKEN: string;
+    STATE: DurableObjectNamespace<GatekeeperState>;
+}
+/** How an operator supplies one binding. */
+export type BindingKind = 'var' | 'secret' | 'durable-object';
+type Binding = keyof GatekeeperEnv;
+/** A configuration binding this deployment has not set. */
+export declare class ConfigError extends Error {
+    readonly binding: Binding;
+    constructor(binding: Binding);
+}
+type StringBinding = Exclude<Binding, 'STATE'>;
+/** Read a required string binding, or refuse naming it. */
+export declare function requireVar(env: GatekeeperEnv, binding: StringBinding): string;
+/**
+ * Every binding this deployment has not set, in ONE pass.
+ *
+ * `requireVar` answers the first binding the path a request happened to take reads, which is the
+ * right answer for that request and the wrong one for a health check: an operator wiring a
+ * deployment learns the next unset name only after fixing this one and redeploying. So the health
+ * check asks the whole table at once, and derives it from `GatekeeperEnv` rather than a
+ * transcribed list, because a binding this check silently passed over is a binding whose absence
+ * reads as a healthy Gatekeeper.
+ */
+export declare function missingBindings(env: GatekeeperEnv): Binding[];
+/** The refusal an operator can act on: every unset binding, each with how to set it. */
+export declare function describeMissingBindings(missing: readonly Binding[]): string;
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,oBAAoB,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAA;IAClB,kGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAA;IACxB,yFAAyF;IACzF,cAAc,EAAE,MAAM,CAAA;IACtB,uFAAuF;IACvF,eAAe,EAAE,MAAM,CAAA;IACvB,KAAK,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAA;CAC/C;AAED,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAsB7D,KAAK,OAAO,GAAG,MAAM,aAAa,CAAA;AAgBlC,2DAA2D;AAC3D,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB,YAAY,OAAO,EAAE,OAAO,EAI3B;CACF;AAED,KAAK,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAE9C,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAI7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,EAAE,CAG7D;AAYD,wFAAwF;AACxF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAG3E"}

package/dist/env.js

@@ -0,0 +1,90 @@
+// The deployment's configuration, and the one rule about reading it: a missing value is a
+// REFUSAL that names the binding, never a default.
+//
+// Every field below is either a credential or the identity of the thing it talks to, and there is
+// no safe stand-in for either. A Gatekeeper that booted with an empty webhook secret would accept
+// unsigned deliveries; one that booted with an empty shared token would serve capabilities to
+// anybody who found the route. So configuration is validated at the edge of each request and
+// answered as a 503 naming the binding an operator has to set, which is the same shape the
+// platform's own unwired-capability refusals take.
+//
+// A request reads the bindings its own path needs, so it can only name the first one it trips on.
+// `/health` is the other question ("could this deployment serve at all"), and it takes the other
+// route through this file: `missingBindings` over the whole table in one pass.
+/**
+ * Which mechanism each binding arrives through, and the one place that fact is stated.
+ *
+ * A var and a Durable Object namespace are written in `wrangler.toml`; a secret is put with
+ * `wrangler secret put` and belongs in no file the repository carries. That distinction is the one
+ * an operator gets wrong, and "set it in wrangler.toml OR with `wrangler secret put`" invites the
+ * wrong half, so every refusal names the mechanism that binding actually takes. It is a
+ * `Record` over `GatekeeperEnv`'s own keys, so a binding added above fails to compile until it
+ * says how it is supplied.
+ */
+const BINDING_KINDS = {
+    CAT_FACTORY_BASE_URL: 'var',
+    WEBHOOK_ID: 'var',
+    PUBLIC_URL: 'var',
+    PROVISIONING_KEY: 'secret',
+    WEBHOOK_SECRET: 'secret',
+    OS_SHARED_TOKEN: 'secret',
+    STATE: 'durable-object',
+};
+/** Where an operator sets one binding, phrased as the remedy a refusal ends on. */
+function howToSet(binding) {
+    // The declared return type is the exhaustiveness guard: a `BindingKind` added with no case here
+    // widens this to `string | undefined` and fails the build.
+    switch (BINDING_KINDS[binding]) {
+        case 'var':
+            return 'set it as a var in wrangler.toml';
+        case 'secret':
+            return `put it with \`wrangler secret put ${binding}\`, never in wrangler.toml`;
+        case 'durable-object':
+            return 'bind it in wrangler.toml as a durable_objects binding to the GatekeeperState class';
+    }
+}
+/** A configuration binding this deployment has not set. */
+export class ConfigError extends Error {
+    binding;
+    constructor(binding) {
+        super(`${binding} is not configured on this Gatekeeper: ${howToSet(binding)}.`);
+        this.name = 'ConfigError';
+        this.binding = binding;
+    }
+}
+/** Read a required string binding, or refuse naming it. */
+export function requireVar(env, binding) {
+    const value = env[binding];
+    if (typeof value !== 'string' || value.length === 0)
+        throw new ConfigError(binding);
+    return value;
+}
+/**
+ * Every binding this deployment has not set, in ONE pass.
+ *
+ * `requireVar` answers the first binding the path a request happened to take reads, which is the
+ * right answer for that request and the wrong one for a health check: an operator wiring a
+ * deployment learns the next unset name only after fixing this one and redeploying. So the health
+ * check asks the whole table at once, and derives it from `GatekeeperEnv` rather than a
+ * transcribed list, because a binding this check silently passed over is a binding whose absence
+ * reads as a healthy Gatekeeper.
+ */
+export function missingBindings(env) {
+    const bindings = Object.keys(BINDING_KINDS);
+    return bindings.filter((binding) => !isSet(env, binding));
+}
+function isSet(env, binding) {
+    if (BINDING_KINDS[binding] === 'durable-object') {
+        // A namespace this Worker can reach, rather than merely a truthy property: an unbound
+        // `durable_objects` entry is a plain `undefined`, and a bound one always answers `idFromName`.
+        return typeof env.STATE?.idFromName === 'function';
+    }
+    const value = env[binding];
+    return typeof value === 'string' && value.length > 0;
+}
+/** The refusal an operator can act on: every unset binding, each with how to set it. */
+export function describeMissingBindings(missing) {
+    const remedies = missing.map((binding) => `${binding} (${howToSet(binding)})`).join('; ');
+    return `This Gatekeeper is not fully configured, so it can accept no traffic. Unset: ${remedies}.`;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,mDAAmD;AACnD,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,8FAA8F;AAC9F,6FAA6F;AAC7F,2FAA2F;AAC3F,mDAAmD;AACnD,EAAE;AACF,kGAAkG;AAClG,iGAAiG;AACjG,+EAA+E;AA0B/E;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAG;IACpB,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE,KAAK;IACjB,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,QAAQ;IAC1B,cAAc,EAAE,QAAQ;IACxB,eAAe,EAAE,QAAQ;IACzB,KAAK,EAAE,gBAAgB;CACoC,CAAA;AAI7D,mFAAmF;AACnF,SAAS,QAAQ,CAAC,OAAgB;IAChC,gGAAgG;IAChG,2DAA2D;IAC3D,QAAQ,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,KAAK,KAAK;YACR,OAAO,kCAAkC,CAAA;QAC3C,KAAK,QAAQ;YACX,OAAO,qCAAqC,OAAO,4BAA4B,CAAA;QACjF,KAAK,gBAAgB;YACnB,OAAO,oFAAoF,CAAA;IAC/F,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,OAAO,CAAS;IAEzB,YAAY,OAAgB;QAC1B,KAAK,CAAC,GAAG,OAAO,0CAA0C,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC/E,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;CACF;AAID,2DAA2D;AAC3D,MAAM,UAAU,UAAU,CAAC,GAAkB,EAAE,OAAsB;IACnE,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,OAAO,CAAC,CAAA;IACnF,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAc,CAAA;IACxD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAA;AAC3D,CAAC;AAED,SAAS,KAAK,CAAC,GAAkB,EAAE,OAAgB;IACjD,IAAI,aAAa,CAAC,OAAO,CAAC,KAAK,gBAAgB,EAAE,CAAC;QAChD,sFAAsF;QACtF,+FAA+F;QAC/F,OAAO,OAAO,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,UAAU,CAAA;IACpD,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAA;AACtD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,uBAAuB,CAAC,OAA2B;IACjE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,OAAO,KAAK,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzF,OAAO,gFAAgF,QAAQ,GAAG,CAAA;AACpG,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/** A refusal the operator fixes, raised while compiling the policy. */
+export declare class PolicyError extends Error {
+    constructor(message: string);
+}
+/** Every machine-readable cause a live Gatekeeper answers with. */
+export type GatekeeperReason = 'unknown_actor' | 'unknown_tier' | 'binding_not_granted' | 'card_not_found' | 'card_already_resolved' | 'unsupported_action'
+/** The verb needs a field the caller did not send. Named rather than defaulted. */
+ | 'invalid_answer'
+/** The run holds no pending decision of the kind the caller named. */
+ | 'no_such_park'
+/** The run is parked on more than one thing and the caller named none. */
+ | 'ambiguous_park'
+/** The platform sent a parked decision without the id every answer to it addresses. */
+ | 'malformed_decision'
+/** A minted credential was refused upstream and re-minting it was refused too. */
+ | 'credential_rejected';
+/** A refusal the caller (or the OS deployment operating it) acts on. */
+export declare class GatekeeperError extends Error {
+    readonly reason: GatekeeperReason;
+    constructor(reason: GatekeeperReason, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAcA,uEAAuE;AACvE,qBAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,cAAc,GACd,qBAAqB,GACrB,gBAAgB,GAChB,uBAAuB,GACvB,oBAAoB;AACtB,mFAAmF;GACjF,gBAAgB;AAClB,sEAAsE;GACpE,cAAc;AAChB,0EAA0E;GACxE,gBAAgB;AAClB,uFAAuF;GACrF,oBAAoB;AACtB,kFAAkF;GAChF,qBAAqB,CAAA;AAEzB,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IAEjC,YAAY,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAIpD;CACF"}

package/dist/errors.js

@@ -0,0 +1,30 @@
+// The two refusals a Gatekeeper makes, kept apart because they need different fixes.
+//
+// A `PolicyError` is the OPERATOR's: the policy this deployment handed the Gatekeeper names
+// something the surface does not have, or grants something its key could never call. (Named by
+// what it IS, never by the file it arrived in: that file is the operator's to place, and the
+// template's `policy.config.ts` is one choice of name rather than this package's to assume.) It is
+// raised while the policy is compiled, before any capability exists, so a misconfigured Gatekeeper
+// serves nothing rather than serving a capability whose every method 403s.
+//
+// A `GatekeeperError` is the CALLER's: a request that reached a live Gatekeeper and was refused
+// by it (an unknown actor, an approval card that no longer exists). It carries a machine-readable
+// `reason` for the same purpose the platform's own `details.reason` serves: an OS Gadget maps it
+// to copy and a remedy, and prose is what a human reads afterwards.
+/** A refusal the operator fixes, raised while compiling the policy. */
+export class PolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyError';
+    }
+}
+/** A refusal the caller (or the OS deployment operating it) acts on. */
+export class GatekeeperError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'GatekeeperError';
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,4FAA4F;AAC5F,+FAA+F;AAC/F,6FAA6F;AAC7F,mGAAmG;AACnG,mGAAmG;AACnG,2EAA2E;AAC3E,EAAE;AACF,gGAAgG;AAChG,kGAAkG;AAClG,iGAAiG;AACjG,oEAAoE;AAEpE,uEAAuE;AACvE,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;CACF;AAqBD,wEAAwE;AACxE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAkB;IAEjC,YAAY,MAAwB,EAAE,OAAe;QACnD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF"}

package/dist/gatekeeper.d.ts

@@ -0,0 +1,78 @@
+import { type GatekeeperEnv } from './env.js';
+import { type Actor } from './keys.js';
+import { type GatekeeperPolicy } from './policy/compile.js';
+import { type VerificationResult } from './webhook/signature.js';
+/** Why a delivery was refused, drawn from the verifier so the two cannot drift. */
+type RejectionReason = Extract<VerificationResult, {
+    ok: false;
+}>['reason'];
+/** What taking delivery of one webhook POST did. */
+export type DeliveryOutcome = {
+    handled: 'rejected';
+    reason: RejectionReason;
+} | {
+    handled: 'unparseable';
+} | {
+    handled: 'duplicate';
+    deliveryId: string;
+} | {
+    handled: 'accepted';
+    deliveryId: string;
+    effect: 'opened' | 'superseded' | 'run-event' | 'none';
+};
+export declare class Gatekeeper {
+    #private;
+    private constructor();
+    /**
+     * 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: GatekeeperEnv, policy: GatekeeperPolicy): Gatekeeper;
+    /** Whether the presented bearer token is this Gatekeeper's own. */
+    authorize(header: string | null): boolean;
+    /**
+     * 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: Actor): import("capnweb").RpcTarget;
+    /**
+     * 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.
+     */
+    retire(actorId: string): Promise<{
+        revoked: string[];
+        remaining: string[];
+    }>;
+    /**
+     * 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.
+     */
+    enroll(): Promise<{
+        webhookId: string;
+        url: string;
+    }>;
+    /**
+     * 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.
+     */
+    takeDelivery(request: Request, now: number): Promise<DeliveryOutcome>;
+}
+export {};
+//# sourceMappingURL=gatekeeper.d.ts.map

package/dist/gatekeeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatekeeper.d.ts","sourceRoot":"","sources":["../src/gatekeeper.ts"],"names":[],"mappings":"AAYA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,UAAU,CAAA;AAEzD,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,WAAW,CAAA;AACjD,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAKhF,mFAAmF;AACnF,KAAK,eAAe,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;AAE3E,oDAAoD;AACpD,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,aAAa,CAAA;CAAE,GAC1B;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5C;IACE,OAAO,EAAE,UAAU,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,CAAA;CACvD,CAAA;AAEL,qBAAa,UAAU;;IAMrB,OAAO,eAiBN;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAEtE;IAED,mEAAmE;IACnE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIxC;IAED;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,+BAUzB;IAED;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAEjF;IAED;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CA2B1D;IAED;;;;;;;;;OASG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA0B1E;CACF"}