@cat-factory/gatekeeper-worker 0.4.3 → 0.6.0

package/dist/os/resource-core.d.ts

@@ -0,0 +1,115 @@
+import type { GatekeeperEnv } from '../env.js';
+import type { GatekeeperPolicy } from '../policy/compile.js';
+import type { ActionKind, ApprovalQueue, ResourceDescription, ResourceObject } from './protocol.js';
+/**
+ * What the account imbues a resource object with when it hands the class to the workspace.
+ *
+ * The account and NOTHING else. The URL the workspace matched is deliberately not here: under this
+ * Gatekeeper's own model a resource IS the paired workspace, so every URL that matches the pattern
+ * binds the same one and the matched URL decides nothing. Carrying it would be state whose only
+ * effect is that the next reader has to work out it decides nothing, and it had already been
+ * assigned the pattern rather than the match without anything noticing. A consumer that genuinely
+ * needs the bound URL adds it back WITH the reader that wants it, which is also the change that
+ * would say which of the two it meant.
+ */
+export interface ResourceProps {
+    /** The account this resource is bound for. Every key minted through it is stamped with this. */
+    accountId: string;
+}
+/**
+ * What a resource needs beyond its own environment: the Worker's exports.
+ *
+ * A hook's controller is one of this Worker's own named exports, resolved as
+ * `ctx.exports.CatFactoryHookController` against the DEPLOYMENT's entry module, and the shell is
+ * the only place that bag exists. It is a dependency rather than a lookup so this core stays
+ * drivable in process, where the suite supplies its own.
+ */
+export interface ResourceDependencies {
+    /** The Worker's own exports, as the object model reaches them. */
+    exports: unknown;
+}
+/** One bound resource: the session it opens, its types, and the action lifecycle behind it. */
+export declare class ResourceCore implements ResourceObject {
+    #private;
+    constructor(env: GatekeeperEnv, policy: GatekeeperPolicy, props: ResourceProps, deps: ResourceDependencies);
+    describe(): Promise<ResourceDescription>;
+    /**
+     * The session's own types, rendered for the tier this account holds.
+     *
+     * Tier-specific rather than a copy of the vendor's, because this is the one the contract points a
+     * caller at: `ResourceDescription.tsType` must name an export of THIS method's output, and a
+     * session carries exactly its granted operations.
+     */
+    getTypeScriptTypes(): Promise<string>;
+    /**
+     * Open a governed session.
+     *
+     * The queue is not optional and not a decoration: every operation the returned object carries
+     * funnels through the one `invoke` closure, which submits actions to this queue and authorizes
+     * observations against it. The tier policy underneath is the FLOOR, so an operation the policy
+     * never granted is absent from the object rather than something the queue has to refuse.
+     *
+     * The queue passed here is OWNED by the session that comes back: it is released, along with
+     * every action that session left undecided, when the session is disposed. A caller reaching this
+     * over RPC therefore hands in a reference of its own rather than the parameter it received (see
+     * `resource.ts`), because the parameter's lifetime ends when this call returns and the session's
+     * does not.
+     */
+    startSession(approvalQueue: ApprovalQueue): Promise<unknown>;
+    /**
+     * How many submitted actions this object is still holding, across every live session.
+     *
+     * Exposed for the same reason the ledger counts them: the ONE unbounded thing about a long-lived
+     * resource object is this set, and a count that does not fall back to zero when the sessions are
+     * gone is the leak rather than a slow day.
+     */
+    get pendingActionCount(): number;
+    /**
+     * The action kinds this Gatekeeper may auto-apply, if the user opted into the kind.
+     *
+     * Derived from the same table and the same consequence reading `describeAction` stamps onto each
+     * submission, so a pre-approval UI listing kinds before any action exists and the `autoApprovable`
+     * flag on an action that has been submitted cannot disagree.
+     *
+     * TODAY THIS IS EMPTY, and that is the honest answer rather than a gap. The public surface
+     * annotates a consequence only where the stakes are real money or a merged pull request, so every
+     * other mutation is unannotated, and the table's documented reading of an unannotated mutation is
+     * that it is destructive. Offering those for unattended auto-approval would mean inverting that
+     * default here, which is precisely the misreading `resolveConsequence` exists to stop. If the
+     * surface ever states that a write is safe, it appears here with no further decision.
+     */
+    getAutoApprovableActions(): Promise<ActionKind[]>;
+    /** The workspace approved an action: perform it, and hand the result to the waiting call. */
+    applyAction(action: number): Promise<void>;
+    /** The workspace rejected an action: the waiting call throws and nothing is performed. */
+    rejectAction(action: number): Promise<void>;
+    /**
+     * Reverting is not something this Gatekeeper can do, which every action it submits already states
+     * (`implementsRevert: false`).
+     *
+     * It answers rather than throwing because the caller is the workspace UI on behalf of a person who
+     * wants their change undone: a message naming what they have to do themselves is the useful
+     * answer, where an exception would surface as a failed revert they might retry.
+     */
+    revertAction(_action: number): Promise<{
+        message: string;
+        canRetry: false;
+    }>;
+    /**
+     * Share this resource's observations onward, if the observer could have read them all directly.
+     *
+     * The contract's requirement, answered rather than declined: the observer names an account this
+     * deployment minted, its policy resolves that account's tier, and the share is admitted only
+     * when that tier reaches everything the tier THIS resource is bound at reaches. `sharing.ts`
+     * holds the tests and why each is the one the contract asks for, including why the account has
+     * to be recognised before its tier means anything.
+     *
+     * Nothing is recorded about an admitted observer, and that is a property of the rule rather than
+     * an omission: every accepted observer can read everything this resource could ever have
+     * observed, so there is never an observation to exclude from them afterwards.
+     */
+    addObserver(id: string, user: unknown): Promise<void>;
+    /** Idempotent by contract: nothing is recorded about an observer, so nothing is forgotten. */
+    removeObserver(_id: string): Promise<void>;
+}
+//# sourceMappingURL=resource-core.d.ts.map

package/dist/os/resource-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-core.d.ts","sourceRoot":"","sources":["../../src/os/resource-core.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9C,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG1E,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAKnG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,+FAA+F;AAC/F,qBAAa,YAAa,YAAW,cAAc;;IAOjD,YACE,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,oBAAoB,EAM3B;IAEK,QAAQ,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAW7C;IAED;;;;;;OAMG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1C;IAED;;;;;;;;;;;;;OAaG;IACG,YAAY,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBjE;IAED;;;;;;OAMG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;;;;;;;;;;;OAaG;IACG,wBAAwB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAKtD;IAED,6FAA6F;IACvF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;IAED,0FAA0F;IACpF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhD;IAED;;;;;;;OAOG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAA;KAAE,CAAC,CAOjF;IAED;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1D;IAED,8FAA8F;IACxF,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAG;CASpD"}

package/dist/os/resource-core.js

@@ -0,0 +1,172 @@
+// What a bound resource DOES, separated from the Durable Object it lives in.
+//
+// The split is not ceremony. A Durable Object can only be constructed by workerd from a real
+// `DurableObjectState`, and the props-imbued class this Gatekeeper hands the workspace is opaque by
+// design (the workspace instantiates it, through machinery that is its own). So a suite that could
+// only reach this behaviour through the object would be reduced to asserting that a class was
+// returned. Everything worth getting wrong lives here instead, where it is ordinary code with
+// ordinary dependencies, and `resource.ts` is the shell that supplies `ctx.props` and holds one of
+// these for the object's lifetime.
+//
+// Holding ONE per object is what the action ledger needs: the workspace settles an action by
+// calling `applyAction` on the resource, so a core rebuilt per call would lose the pending action
+// the decision is about.
+import { Gatekeeper } from '../gatekeeper.js';
+import { actionKindOf } from './descriptions.js';
+import { loopbackExport } from './exports.js';
+import { ActionLedger, queueGovernance } from './queue.js';
+import { assertObserverMaySee, identifyObserver } from './sharing.js';
+import { renderTierSessionTypes, SESSION_INTERFACE_NAME } from './session-types.js';
+/** One bound resource: the session it opens, its types, and the action lifecycle behind it. */
+export class ResourceCore {
+    #env;
+    #policy;
+    #props;
+    #deps;
+    #ledger = new ActionLedger();
+    constructor(env, policy, props, deps) {
+        this.#env = env;
+        this.#policy = policy;
+        this.#props = props;
+        this.#deps = deps;
+    }
+    async describe() {
+        const tier = this.#tier();
+        return {
+            url: this.#gatekeeper().deployment,
+            title: 'cat-factory workspace',
+            snippet: `File work, start runs and answer what they park on, at policy tier '${tier.name}': ` +
+                `${tier.description}`,
+            suggestedBindingName: 'catFactory',
+            tsType: SESSION_INTERFACE_NAME,
+        };
+    }
+    /**
+     * The session's own types, rendered for the tier this account holds.
+     *
+     * Tier-specific rather than a copy of the vendor's, because this is the one the contract points a
+     * caller at: `ResourceDescription.tsType` must name an export of THIS method's output, and a
+     * session carries exactly its granted operations.
+     */
+    async getTypeScriptTypes() {
+        return renderTierSessionTypes(this.#tier());
+    }
+    /**
+     * Open a governed session.
+     *
+     * The queue is not optional and not a decoration: every operation the returned object carries
+     * funnels through the one `invoke` closure, which submits actions to this queue and authorizes
+     * observations against it. The tier policy underneath is the FLOOR, so an operation the policy
+     * never granted is absent from the object rather than something the queue has to refuse.
+     *
+     * The queue passed here is OWNED by the session that comes back: it is released, along with
+     * every action that session left undecided, when the session is disposed. A caller reaching this
+     * over RPC therefore hands in a reference of its own rather than the parameter it received (see
+     * `resource.ts`), because the parameter's lifetime ends when this call returns and the session's
+     * does not.
+     */
+    async startSession(approvalQueue) {
+        const gatekeeper = this.#gatekeeper();
+        const accountId = this.#props.accountId;
+        return gatekeeper.capabilityForAccount(accountId, queueGovernance({
+            queue: approvalQueue,
+            ledger: this.#ledger.openSession(),
+            subject: {
+                accountId,
+                tier: gatekeeper.tierForAccount(accountId).name,
+                deployment: gatekeeper.deployment,
+            },
+            // Resolved per bind rather than once per session: the refusal for a deployment missing
+            // the export belongs to the call that needed it, and a session that binds no hook is one
+            // this Gatekeeper has no reason to refuse at all.
+            controllerFor: (props) => loopbackExport(this.#deps.exports, 'hookController', props),
+        }));
+    }
+    /**
+     * How many submitted actions this object is still holding, across every live session.
+     *
+     * Exposed for the same reason the ledger counts them: the ONE unbounded thing about a long-lived
+     * resource object is this set, and a count that does not fall back to zero when the sessions are
+     * gone is the leak rather than a slow day.
+     */
+    get pendingActionCount() {
+        return this.#ledger.pendingCount;
+    }
+    /**
+     * The action kinds this Gatekeeper may auto-apply, if the user opted into the kind.
+     *
+     * Derived from the same table and the same consequence reading `describeAction` stamps onto each
+     * submission, so a pre-approval UI listing kinds before any action exists and the `autoApprovable`
+     * flag on an action that has been submitted cannot disagree.
+     *
+     * TODAY THIS IS EMPTY, and that is the honest answer rather than a gap. The public surface
+     * annotates a consequence only where the stakes are real money or a merged pull request, so every
+     * other mutation is unannotated, and the table's documented reading of an unannotated mutation is
+     * that it is destructive. Offering those for unattended auto-approval would mean inverting that
+     * default here, which is precisely the misreading `resolveConsequence` exists to stop. If the
+     * surface ever states that a write is safe, it appears here with no further decision.
+     */
+    async getAutoApprovableActions() {
+        return this.#tier()
+            .granted.filter((binding) => !binding.readOnly)
+            .filter((binding) => (binding.consequence?.destructive ?? true) === false)
+            .map(actionKindOf);
+    }
+    /** The workspace approved an action: perform it, and hand the result to the waiting call. */
+    async applyAction(action) {
+        await this.#ledger.apply(action);
+    }
+    /** The workspace rejected an action: the waiting call throws and nothing is performed. */
+    async rejectAction(action) {
+        this.#ledger.reject(action);
+    }
+    /**
+     * Reverting is not something this Gatekeeper can do, which every action it submits already states
+     * (`implementsRevert: false`).
+     *
+     * It answers rather than throwing because the caller is the workspace UI on behalf of a person who
+     * wants their change undone: a message naming what they have to do themselves is the useful
+     * answer, where an exception would surface as a failed revert they might retry.
+     */
+    async revertAction(_action) {
+        return {
+            message: 'This Gatekeeper cannot revert a cat-factory operation. A started run is stopped from the ' +
+                'board or with `tasks_stop`; a merged pull request is reverted in the repository, not here.',
+            canRetry: false,
+        };
+    }
+    /**
+     * Share this resource's observations onward, if the observer could have read them all directly.
+     *
+     * The contract's requirement, answered rather than declined: the observer names an account this
+     * deployment minted, its policy resolves that account's tier, and the share is admitted only
+     * when that tier reaches everything the tier THIS resource is bound at reaches. `sharing.ts`
+     * holds the tests and why each is the one the contract asks for, including why the account has
+     * to be recognised before its tier means anything.
+     *
+     * Nothing is recorded about an admitted observer, and that is a property of the rule rather than
+     * an omission: every accepted observer can read everything this resource could ever have
+     * observed, so there is never an observation to exclude from them afterwards.
+     */
+    async addObserver(id, user) {
+        const gatekeeper = this.#gatekeeper();
+        const observerAccount = await identifyObserver(user, {
+            recognize: (accountId) => gatekeeper.recognizesAccount(accountId),
+        });
+        assertObserverMaySee({
+            observerId: id,
+            observerAccount,
+            owner: this.#tier(),
+            observer: gatekeeper.tierForAccount(observerAccount),
+        });
+    }
+    /** Idempotent by contract: nothing is recorded about an observer, so nothing is forgotten. */
+    async removeObserver(_id) { }
+    #gatekeeper() {
+        return Gatekeeper.create(this.#env, this.#policy);
+    }
+    #tier() {
+        return this.#gatekeeper().tierForAccount(this.#props.accountId);
+    }
+}
+//# sourceMappingURL=resource-core.js.map

package/dist/os/resource-core.js.map

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

package/dist/os/resource.d.ts

@@ -0,0 +1,16 @@
+import type { GatekeeperEnv } from '../env.js';
+import type { GatekeeperPolicy } from '../policy/compile.js';
+import type { ResourceObject } from './protocol.js';
+import { type ResourceProps } from './resource-core.js';
+export type { ResourceProps } from './resource-core.js';
+/**
+ * Build the resource Durable Object class over a deployment's policy.
+ *
+ * A factory rather than a class, for the reason `createGatekeeperWorker` is one: the policy is the
+ * deployment's and arrives as an argument, so a class that imported one would own the file the
+ * operator is supposed to write.
+ */
+export declare function createGatekeeperResource(options: {
+    policy: GatekeeperPolicy;
+}): new (ctx: DurableObjectState<ResourceProps>, env: GatekeeperEnv) => ResourceObject;
+//# sourceMappingURL=resource.d.ts.map

package/dist/os/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/os/resource.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAkD,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnG,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAErE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,gBAAgB,CAAA;CACzB,GAAG,KAAK,GAAG,EAAE,kBAAkB,CAAC,aAAa,CAAC,EAAE,GAAG,EAAE,aAAa,KAAK,cAAc,CAqDrF"}

package/dist/os/resource.js

@@ -0,0 +1,70 @@
+// The per-resource object the workspace binds: a Durable Object serving one paired cat-factory
+// workspace to one account.
+//
+// WHAT A RESOURCE IS, decided here and recorded in the initiative tracker: the PAIRED cat-factory
+// WORKSPACE, named by a URLPattern over the deployment origin. It follows from the credential
+// rather than being a modelling preference. This Worker holds one provisioning key, a cat-factory
+// key is scoped to exactly one workspace, and `STATE` is already keyed on the deployment origin for
+// the same reason. So one Gatekeeper Worker serves one resource, and an OS deployment that wants
+// two workspaces runs two Gatekeepers with two bindings, which is also the only arrangement in
+// which the two workspaces' credentials sit in different secret stores.
+//
+// Everything below is a FACADE. The policy compilation, the key broker, the durable state and the
+// approval answerers are the same single implementation the `/rpc` door reaches; what differs is
+// the door, and the governance that door brings with it. This file is the SHELL: it supplies
+// `ctx.props` and holds one `ResourceCore`, which is where the behaviour lives.
+import { DurableObject } from 'cloudflare:workers';
+import { holdQueue } from './queue.js';
+import { ResourceCore } from './resource-core.js';
+/**
+ * Build the resource Durable Object class over a deployment's policy.
+ *
+ * A factory rather than a class, for the reason `createGatekeeperWorker` is one: the policy is the
+ * deployment's and arrives as an argument, so a class that imported one would own the file the
+ * operator is supposed to write.
+ */
+export function createGatekeeperResource(options) {
+    const { policy } = options;
+    return class CatFactoryResource extends DurableObject {
+        // ONE core for the object's lifetime, because the action ledger inside it is what a later
+        // `applyAction` settles: a core rebuilt per call would have forgotten the action the decision
+        // is about. Field initializers run after the base constructor, so `ctx` and `env` are set.
+        //
+        // The exports bag is handed down because this shell is the only thing that has one: a hook's
+        // controller is one of the Worker's own named exports, resolved against the DEPLOYMENT's entry
+        // module, and the core is deliberately drivable without a Durable Object at all.
+        #core = new ResourceCore(this.env, policy, this.ctx.props, {
+            exports: this.ctx.exports,
+        });
+        async describe() {
+            return this.#core.describe();
+        }
+        async getTypeScriptTypes() {
+            return this.#core.getTypeScriptTypes();
+        }
+        // The one method where being the SHELL is not delegation: this is where the RPC boundary is,
+        // so this is where the queue's lifetime is taken over from the call that carried it in.
+        async startSession(approvalQueue) {
+            return this.#core.startSession(holdQueue(approvalQueue));
+        }
+        async getAutoApprovableActions() {
+            return this.#core.getAutoApprovableActions();
+        }
+        async applyAction(action) {
+            return this.#core.applyAction(action);
+        }
+        async rejectAction(action) {
+            return this.#core.rejectAction(action);
+        }
+        async revertAction(action) {
+            return this.#core.revertAction(action);
+        }
+        async addObserver(id, user) {
+            return this.#core.addObserver(id, user);
+        }
+        async removeObserver(id) {
+            return this.#core.removeObserver(id);
+        }
+    };
+}
+//# sourceMappingURL=resource.js.map

package/dist/os/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/os/resource.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,4BAA4B;AAC5B,EAAE;AACF,kGAAkG;AAClG,8FAA8F;AAC9F,kGAAkG;AAClG,oGAAoG;AACpG,iGAAiG;AACjG,+FAA+F;AAC/F,wEAAwE;AACxE,EAAE;AACF,kGAAkG;AAClG,iGAAiG;AACjG,6FAA6F;AAC7F,gFAAgF;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAIlD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAA;AAIrE;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAExC;IACC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAE1B,OAAO,MAAM,kBAAmB,SAAQ,aAA2C;QACjF,0FAA0F;QAC1F,8FAA8F;QAC9F,2FAA2F;QAC3F,EAAE;QACF,6FAA6F;QAC7F,+FAA+F;QAC/F,iFAAiF;QACxE,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE;YAClE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO;SAC1B,CAAC,CAAA;QAEF,KAAK,CAAC,QAAQ;YACZ,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAA;QAC9B,CAAC;QAED,KAAK,CAAC,kBAAkB;YACtB,OAAO,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,CAAA;QACxC,CAAC;QAED,6FAA6F;QAC7F,wFAAwF;QACxF,KAAK,CAAC,YAAY,CAAC,aAA4B;YAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAA;QAC1D,CAAC;QAED,KAAK,CAAC,wBAAwB;YAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,wBAAwB,EAAE,CAAA;QAC9C,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,MAAc;YAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;QACvC,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,MAAc;YAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;QACxC,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,MAAc;YAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;QACxC,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,EAAU,EAAE,IAAa;YACzC,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;QACzC,CAAC;QAED,KAAK,CAAC,cAAc,CAAC,EAAU;YAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC,CAAA;QACtC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/os/resources.d.ts

@@ -0,0 +1,11 @@
+import type { SupportedResource } from './protocol.js';
+/**
+ * The single resource: the paired cat-factory workspace, named by a pattern over its origin.
+ *
+ * The pattern is anchored on the deployment's ORIGIN with a wildcard path, which is what makes a
+ * board URL a person pastes (`https://cat-factory.example.com/w/…`) bind to this Gatekeeper. It is
+ * not `grantable`: there is nothing to grant separately, because the account's access is the
+ * provisioning key this Worker already holds.
+ */
+export declare function supportedResourceFor(deployment: string): SupportedResource;
+//# sourceMappingURL=resources.d.ts.map

package/dist/os/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/os/resources.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEtD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAW1E"}

package/dist/os/resources.js

@@ -0,0 +1,26 @@
+// What this Gatekeeper serves, as the workspace's own resource vocabulary.
+//
+// One function, in a file of its own, because three callers need the SAME answer and a second
+// spelling of the URL pattern would be a resource an account advertises and a bind cannot match:
+// the vendor lists it, the account lists it and matches a URL against it, and the resource object
+// describes itself with it.
+/**
+ * The single resource: the paired cat-factory workspace, named by a pattern over its origin.
+ *
+ * The pattern is anchored on the deployment's ORIGIN with a wildcard path, which is what makes a
+ * board URL a person pastes (`https://cat-factory.example.com/w/…`) bind to this Gatekeeper. It is
+ * not `grantable`: there is nothing to grant separately, because the account's access is the
+ * provisioning key this Worker already holds.
+ */
+export function supportedResourceFor(deployment) {
+    const origin = new URL(deployment).origin;
+    return {
+        urlPattern: `${origin}/*`,
+        title: 'cat-factory workspace',
+        description: 'The cat-factory workspace this Gatekeeper is paired with: file tasks, start runs, watch ' +
+            'them, and answer the decisions they park on. One Gatekeeper serves one workspace, because ' +
+            'the provisioning key it holds is scoped to one.',
+        grantable: false,
+    };
+}
+//# sourceMappingURL=resources.js.map

package/dist/os/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../src/os/resources.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,8FAA8F;AAC9F,iGAAiG;AACjG,kGAAkG;AAClG,4BAA4B;AAI5B;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM,CAAA;IACzC,OAAO;QACL,UAAU,EAAE,GAAG,MAAM,IAAI;QACzB,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,0FAA0F;YAC1F,4FAA4F;YAC5F,iDAAiD;QACnD,SAAS,EAAE,KAAK;KACjB,CAAA;AACH,CAAC"}

package/dist/os/session-types.d.ts

@@ -0,0 +1,6 @@
+import type { CompiledTier } from '../policy/compile.js';
+/** The type name a resource declares as its `tsType`, and the interface the `.d.ts` exports. */
+export declare const SESSION_INTERFACE_NAME = "CatFactoryWorkspace";
+/** Render the session `.d.ts` for one compiled tier. */
+export declare function renderTierSessionTypes(tier: CompiledTier): string;
+//# sourceMappingURL=session-types.d.ts.map

package/dist/os/session-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.d.ts","sourceRoot":"","sources":["../../src/os/session-types.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,gGAAgG;AAChG,eAAO,MAAM,sBAAsB,wBAAwB,CAAA;AAuF3D,wDAAwD;AACxD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAUjE"}

package/dist/os/session-types.js

@@ -0,0 +1,110 @@
+// The `.d.ts` a session serves through `getTypeScriptTypes()`, composed for one tier.
+//
+// The per-operation signatures are GENERATED (`@cat-factory/gatekeeper-bindings`'s
+// `SESSION_METHOD_SIGNATURES`, rendered by `pnpm gen:sdk` from the same spec the bindings table
+// comes from), so the types an agent codes against cannot describe a surface the deployment does
+// not serve. What is composed here is the tier's own subset plus the reserved methods, because a
+// session carries exactly what its policy granted: a file naming the whole surface would promise
+// methods the object does not have.
+//
+// The reserved methods are written out here rather than generated because they are this package's,
+// not the deployment's: they exist at exactly the same version as this file.
+import { renderSessionTypes } from '@cat-factory/gatekeeper-bindings';
+/** The type name a resource declares as its `tsType`, and the interface the `.d.ts` exports. */
+export const SESSION_INTERFACE_NAME = 'CatFactoryWorkspace';
+/**
+ * The methods every session carries whatever its policy: who the caller is, what they hold, what
+ * they do not, and the approval inbox.
+ *
+ * `withheld()` is the one worth reading twice. An agent that cannot tell "your policy hides this"
+ * from "no policy could grant this" from "ask for it another way" reports the wrong one to whoever
+ * has to fix it, which is why it is on the object rather than in a document.
+ */
+const RESERVED_MEMBERS = [
+    `  /** Who this session acts as, and the policy tier that account resolved to. */
+  tier(): Promise<{ actorId: string; tier: string; description: string; keyScope: string }>
+`,
+    `  /**
+   * Every operation this session carries, with the scope floor and consequence of each.
+   */
+  bindings(): Promise<
+    {
+      name: string
+      summary: string
+      minScope: string
+      readOnly: boolean
+      destructive: boolean
+      idempotent: boolean
+      pathParams: readonly string[]
+      queryParams: readonly { name: string; required: boolean }[]
+      hasBody: boolean
+    }[]
+  >
+`,
+    `  /**
+   * Every operation this session does NOT carry, and why: \`not_in_policy\` and
+   * \`denied_by_policy\` are your operator's decision, \`above_key_scope\` needs a higher tier,
+   * and \`not_relayable\` cannot cross a session call at all (ask for it another way).
+   */
+  withheld(): Promise<{ name: string; reason: string; detail: string }[]>
+`,
+    `  /** The approval cards the paired deployment has raised and this Gatekeeper still holds open. */
+  approvals_list(): Promise<unknown[]>
+`,
+    `  /**
+   * What a card's run is ACTUALLY parked on now, with the verbs each park takes and whether this
+   * session holds the operation behind it. The card is a pointer; the run is the truth.
+   */
+  approvals_inspect(cardId: string): Promise<unknown>
+`,
+    `  /**
+   * Answer a park. Three outcomes are distinguishable and all three matter: \`answered\` (the run
+   * is unparked), \`recorded\` (your vote counted, the quorum is unmet, the run is still parked)
+   * and \`stale\` (the run moved on).
+   */
+  approvals_answer(cardId: string, input: unknown): Promise<unknown>
+`,
+    `  /** Every run this Gatekeeper has been pushed lifecycle events for. */
+  runs_watched(): Promise<unknown[]>
+`,
+    `  /**
+   * Be pushed each approval card as it is raised or settled, instead of polling
+   * \`approvals_list()\`. The callback needs one method:
+   * \`onApprovalCard(card): Promise<void>\`.
+   *
+   * The workspace holds the registration and may ask a person before enabling it, so binding is
+   * not receiving: nothing arrives until it is enabled, and \`hooks_bound()\` is where that shows.
+   */
+  approvals_subscribe(callback: unknown): Promise<void>
+`,
+    `  /**
+   * Be pushed each run lifecycle transition, instead of polling \`runs_watched()\`. The callback
+   * needs one method: \`onRunEvent(state): Promise<void>\`.
+   */
+  runs_subscribe(callback: unknown): Promise<void>
+`,
+    `  /**
+   * Every hook this account has enabled, with what each has been pushed (\`deliveries\`), what it
+   * could not be pushed (\`missed\`), what the workspace's own side refused (\`failures\`) and
+   * whether it is still \`live\`.
+   *
+   * A hook goes quiet when this Gatekeeper's durable object is evicted between deliveries, since
+   * the workspace's callback source cannot be stored. That reads as \`live: false\` with a rising
+   * \`missed\`, and the remedy is to bind again; what was missed is still in
+   * \`approvals_list()\` and \`runs_watched()\`, which is why they remain the truth.
+   */
+  hooks_bound(): Promise<unknown[]>
+`,
+];
+/** Render the session `.d.ts` for one compiled tier. */
+export function renderTierSessionTypes(tier) {
+    return renderSessionTypes({
+        interfaceName: SESSION_INTERFACE_NAME,
+        bindings: tier.granted.map((binding) => binding.name),
+        extraMembers: RESERVED_MEMBERS,
+        preamble: `// The session for policy tier \`${tier.name}\`: ${tier.description}\n` +
+            `// Calls are made with a per-account API key at scope \`${tier.keyScope}\`, and every one of\n` +
+            "// them passes through this workspace's approval queue.",
+    });
+}
+//# sourceMappingURL=session-types.js.map

package/dist/os/session-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.js","sourceRoot":"","sources":["../../src/os/session-types.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,EAAE;AACF,mFAAmF;AACnF,gGAAgG;AAChG,iGAAiG;AACjG,iGAAiG;AACjG,iGAAiG;AACjG,oCAAoC;AACpC,EAAE;AACF,mGAAmG;AACnG,6EAA6E;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AAGrE,gGAAgG;AAChG,MAAM,CAAC,MAAM,sBAAsB,GAAG,qBAAqB,CAAA;AAE3D;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAsB;IAC1C;;CAED;IACC;;;;;;;;;;;;;;;;CAgBD;IACC;;;;;;CAMD;IACC;;CAED;IACC;;;;;CAKD;IACC;;;;;;CAMD;IACC;;CAED;IACC;;;;;;;;;CASD;IACC;;;;;CAKD;IACC;;;;;;;;;;;CAWD;CACA,CAAA;AAED,wDAAwD;AACxD,MAAM,UAAU,sBAAsB,CAAC,IAAkB;IACvD,OAAO,kBAAkB,CAAC;QACxB,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;QACrD,YAAY,EAAE,gBAAgB;QAC9B,QAAQ,EACN,oCAAoC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,WAAW,IAAI;YACxE,2DAA2D,IAAI,CAAC,QAAQ,wBAAwB;YAChG,yDAAyD;KAC5D,CAAC,CAAA;AACJ,CAAC"}

package/dist/os/sharing.d.ts

@@ -0,0 +1,35 @@
+import type { CompiledTier } from '../policy/compile.js';
+/** What the caller supplies so a claimed account can be checked against the ones this Gatekeeper made. */
+export interface ObserverRecognition {
+    /** Whether this deployment minted the named account. Never a guess: an unknown id is refused. */
+    recognize: (accountId: string) => Promise<boolean>;
+}
+/**
+ * Resolve the account behind an observer's verifier, or refuse.
+ *
+ * The verifier is the contract's own identity token: another vendor's gatekeeper is handed one,
+ * and the only thing it carries is who its holder is. Ours answers `{ accountId }`, so a stub that
+ * answers anything else did not come from this vendor and cannot be resolved against this
+ * deployment's policy. Answering the right SHAPE is not the same as being one of ours, which is
+ * why the id is then checked against the accounts this deployment actually minted.
+ *
+ * What that does NOT establish is worth stating, because the rule above is only as strong as this:
+ * a verifier that names an account of ours is taken at its word. The stub is reached over RPC from
+ * whoever the workspace handed us, so proving the holder IS that account would take a challenge
+ * the published contract does not carry. What is closed here is the case that needs no
+ * impersonation at all, which was every honest viewer from every other vendor.
+ */
+export declare function identifyObserver(user: unknown, deps: ObserverRecognition): Promise<string>;
+/**
+ * Refuse the share unless the observer could have read all of it themselves.
+ *
+ * Takes the two COMPILED tiers rather than resolving them, so the rule is testable without a
+ * policy, a Worker or an account: what it decides is a comparison, and everything else is lookup.
+ */
+export declare function assertObserverMaySee(deps: {
+    observerId: string;
+    observerAccount: string;
+    owner: CompiledTier;
+    observer: CompiledTier;
+}): void;
+//# sourceMappingURL=sharing.d.ts.map

package/dist/os/sharing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing.d.ts","sourceRoot":"","sources":["../../src/os/sharing.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAUxD,0GAA0G;AAC1G,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsChG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,KAAK,EAAE,YAAY,CAAA;IACnB,QAAQ,EAAE,YAAY,CAAA;CACvB,GAAG,IAAI,CAqCP"}