@cat-factory/gatekeeper-bindings 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @cat-factory/gatekeeper-bindings
+
+## What it is
+
+A policy-annotated table of every cat-factory **public API** (`/api/v1`) operation, plus the
+scope-ladder helpers a policy layer ranks keys and classifies calls with. Like
+[`sdk/mcp`](https://github.com/kibertoad/cat-factory/tree/main/sdk/mcp), this is **not a fifth
+client**: it is the same operations the four SDKs expose, projected as a table and generated from
+the same OpenAPI spec (`pnpm gen:sdk`), so it cannot drift from the surface it meters. The thunks
+call [`@cat-factory/sdk`](https://www.npmjs.com/package/@cat-factory/sdk) and re-implement none of
+its behaviour.
+
+It is the data half of the cat-factory **Gatekeeper** family, three pieces taken two different
+ways:
+
+| Piece                                                                                            | What it is                                                                                                  | How you take it                         |
+| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `@cat-factory/gatekeeper-bindings` (this package)                                                | the generated operation table and the scope helpers                                                         | install, to build your own policy layer |
+| [`@cat-factory/gatekeeper-worker`](https://www.npmjs.com/package/@cat-factory/gatekeeper-worker) | the full Gatekeeper Worker machinery: Cap'n Web capability surface, key broker, webhook receiver, approvals | install, and write only a policy        |
+| [`deploy/gatekeeper`](https://github.com/kibertoad/cat-factory/tree/main/deploy/gatekeeper)      | the deployment template: a policy file, wrangler bindings, three lines of wiring                            | copy, and edit `src/policy.config.ts`   |
+
+## Purpose and goal
+
+For building **credential-holding front-ends**: services that hold the cat-factory API key
+themselves and meter what their own callers may do. The motivating consumer is a
+[Cloudflare OS](https://github.com/cloudflare/cloudflare-os) Gatekeeper Worker (design record: the
+[initiative tracker](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/cloudflare-os-gatekeeper.md)),
+but nothing here is Cloudflare-specific: any proxy, bot or governance layer that fronts a
+cat-factory key can use it.
+
+The goal is that such a layer enforces policy against the operations the deployment actually
+serves, at the scope floors it actually enforces, never against a hand-curated list that drifts.
+The floors come from the spec's `x-min-scope`, which the server generates from the same contract
+field its controllers enforce, so the declared scope and the enforced scope are one value.
+
+## What each binding carries
+
+One `GatekeeperBinding` per `/api/v1` operation:
+
+- `name` (`tasks_create`): the policy spelling, identical to the MCP facade's tool name.
+- `minScope`: the key-scope floor the deployment enforces for the route (`read` / `write` /
+  `decide` / `admin`), read off the spec's `x-min-scope`. This is the STATIC floor: a run-starting
+  operation can still be refused `pipeline_requires_decide_scope` at request time when the named
+  pipeline can park on a human.
+- `readOnly`, `consequence`: what a front-end needs to decide which calls get waved through,
+  which get logged, and which need a human. `consequence` is present only where the stakes are
+  real money or a merged pull request, exactly as in the MCP tool table, so read it through
+  `resolveConsequence(binding)` rather than directly: an unannotated mutation is cautiously
+  destructive, and `binding.consequence?.destructive` would answer `false` for it.
+- `result`: how `invoke`'s answer comes back (`value`, SSE `stream`, or `binary` bytes), so a
+  JSON-relay front-end can route or withhold the non-value operations, stating which.
+- `pathParams` / `queryParams` / `hasBody` and `invoke(client, args)`: enough to expose the
+  whole surface dynamically without hand-writing a wrapper per operation. The argument
+  convention is the MCP facade's (path params and query keys at the top level, body under
+  `body`; unknown keys are dropped, never forwarded).
+
+## The helpers
+
+Hand-written beside the table (`src/index.ts`), because every consumer needs them and deriving
+them independently is how one gets them backwards:
+
+- `scopeSatisfies(have, need)`: whether a key of scope `have` clears a floor of `need`. The
+  ladder is inclusive: every rung can do everything below it.
+- `bindingsWithinScope(scope)`: every operation a key of that scope can call.
+- `bindingByName(name)`: one operation by its policy spelling; `undefined` for a name the surface
+  does not have, so a misspelled or retired name is a condition the caller reports rather than a
+  thrown surprise.
+- `resolveConsequence(binding)`: the consequence annotation with the cautious default applied (an
+  unannotated mutation counts as destructive and non-idempotent).
+- `PUBLIC_API_SCOPE_LADDER`: the scope ranking itself, emitted from the spec's
+  `x-public-api-scopes`.
+
+The ladder helpers **throw on a scope they do not carry** rather than ranking it below `read`:
+a deployment one release ahead of this package must read as version skew, never as a key with no
+permissions.
+
+## How to use it
+
+```ts
+import { CatFactoryClient } from '@cat-factory/sdk'
+import {
+  bindingByName,
+  bindingsWithinScope,
+  resolveConsequence,
+  scopeSatisfies,
+} from '@cat-factory/gatekeeper-bindings'
+
+const client = new CatFactoryClient({ baseUrl: process.env.BASE_URL!, apiKey: process.env.KEY! })
+
+// Expose to this caller only what a `write` key can do, minus anything destructive. Read the
+// consequence through the helper: most mutations carry no annotation, and the unannotated ones
+// are the cautious case, not the safe one.
+const exposed = bindingsWithinScope('write').filter((b) => !resolveConsequence(b).destructive)
+
+// Forward a metered call.
+const binding = bindingByName('tasks_create')!
+if (!scopeSatisfies('write', binding.minScope)) throw new Error('caller tier too low')
+const result = await binding.invoke(client, {
+  serviceId: 'svc_123',
+  body: { title: 'Fix the flaky login test', description: '...' },
+})
+```
+
+Two routes are deliberately absent from the table because they have no honest operation shape:
+`GET /api/v1/openapi.json` (spec discovery) and `ALL /api/v1/mcp` (the hosted MCP endpoint). Both
+gate at `read` on the server.
+
+## Configuration and customization
+
+Nothing in this package is configured or customized: it is generated data plus pure helpers, and
+the policy built on top of it belongs to the consumer (see `@cat-factory/gatekeeper-worker` for a
+ready-made one). `src/bindings.generated.ts` is GENERATED (`pnpm gen:sdk`); change the route
+contracts, never the file.
+
+## References
+
+- [`backend/docs/public-api.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/public-api.md):
+  the full API reference (keys, scopes, endpoint semantics).
+- [`sdk/README.md`](https://github.com/kibertoad/cat-factory/blob/main/sdk/README.md): the client
+  family and the generation chain this table rides.
+- [`@cat-factory/gatekeeper-worker`](https://www.npmjs.com/package/@cat-factory/gatekeeper-worker):
+  the Worker machinery that compiles deployment policy against this table.
+- [The initiative tracker](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/cloudflare-os-gatekeeper.md):
+  design record, decisions and gotchas.

package/dist/bindings.generated.d.ts

@@ -0,0 +1,68 @@
+import type { CatFactoryClient } from '@cat-factory/sdk';
+/**
+ * A public-API key scope. The ladder is INCLUSIVE and ordered
+ * (read < write < decide < admin): a key satisfies every floor at or below its own rung. See
+ * `backend/docs/public-api.md`, "Pick the right scope".
+ */
+export type PublicApiScope = 'read' | 'write' | 'decide' | 'admin';
+/**
+ * The scope ladder, least to greatest. The ARRAY ORDER is the ranking, and this is the
+ * deployment's own vocabulary: generated from the spec's `x-public-api-scopes`, which the
+ * server stamps from the same constant its admission check ranks with.
+ */
+export declare const PUBLIC_API_SCOPE_LADDER: readonly PublicApiScope[];
+/** One `/api/v1` operation, as a policy-annotated capability. */
+export interface GatekeeperBinding {
+    /** The name a policy file addresses, `<group>_<method>`: the MCP tool's own spelling. */
+    name: string;
+    /** The SDK resource group, spelled as the TypeScript client mounts it (`client.taskTypes`). */
+    group: string;
+    /** The method on that resource client. */
+    method: string;
+    /** The spec's `operationId`, for correlating a forwarded call with a deployment's logs. */
+    operationId: string;
+    httpMethod: string;
+    /** The route, with `{param}` placeholders. */
+    path: string;
+    /** One-line label from the spec's `summary`. */
+    summary: string;
+    /**
+     * The least key scope the route admits: the STATIC floor the deployment enforces, and only
+     * that: a run-starting operation can still be refused `pipeline_requires_decide_scope` at
+     * request time when the named pipeline can park on a human.
+     */
+    minScope: PublicApiScope;
+    /** Whether the call changes nothing (a GET). */
+    readOnly: boolean;
+    /**
+     * How `invoke`'s result comes back: a decoded `value`, an SSE `stream` reader, or raw
+     * `binary` bytes. A front-end that only relays JSON should route `stream`/`binary`
+     * bindings specially or withhold them, stating which.
+     */
+    result: 'value' | 'stream' | 'binary';
+    /**
+     * The annotations the HTTP method cannot supply, present only where the consequence is real
+     * money or a merged pull request (shared with the MCP table's hints). Absent means the cautious
+     * reading applies: treat an unannotated mutation as destructive and non-idempotent.
+     */
+    consequence?: {
+        destructive: boolean;
+        idempotent: boolean;
+    };
+    /** Path parameter names `invoke` reads from `args`, in path order. */
+    pathParams: readonly string[];
+    /** Query parameter names `invoke` forwards from `args`; anything else is dropped. */
+    queryParams: readonly string[];
+    /** Whether `invoke` reads `args.body` as the request body. */
+    hasBody: boolean;
+    /**
+     * Forward a call to the SDK: path params and query keys at the top level, body under `body`.
+     *
+     * Every failure is a REJECTION, the SDK's own and a missing-argument `TypeError` alike, so one
+     * `.catch()` (or one `try` around an `await`) covers a forwarded call.
+     */
+    invoke: (client: CatFactoryClient, args: Record<string, unknown>) => Promise<unknown>;
+}
+/** Every `/api/v1` operation as a policy-annotated binding, in resource-group order. */
+export declare const GATEKEEPER_BINDINGS: readonly GatekeeperBinding[];
+//# sourceMappingURL=bindings.generated.d.ts.map

package/dist/bindings.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.generated.d.ts","sourceRoot":"","sources":["../src/bindings.generated.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAA;AAElE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,cAAc,EAAyC,CAAA;AAEtG,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAA;IACZ,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,QAAQ,EAAE,cAAc,CAAA;IACxB,gDAAgD;IAChD,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACrC;;;;OAIG;IACH,WAAW,CAAC,EAAE;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAA;IAC3D,sEAAsE;IACtE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,qFAAqF;IACrF,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACtF;AAkCD,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,EAAE,SAAS,iBAAiB,EA0+C3D,CAAA"}