packages/custom-gatekeeper/README.md

1# Custom Gatekeeper
2
3> **Retired sample:** Fork Horse's deploy no longer ships this package; it remains a source example to copy and wire yourself.
4
5This is a credential-free, read-only example for deployment-owned Cloudflare OS integrations. It exposes deployment information through a typed singleton and records every read as an observation.
6
7## Adapt it
8
9Change only the pieces your integration needs:
10
11- `src/types.d.ts`: replace `CustomSession` with the API agents and Gadgets may call.
12- `src/types-code.ts`: keep the agent-facing declaration synchronized with `types.d.ts`.
13- `src/custom.ts`: replace `getDeploymentInfo()` and its observation description with the real read operation.
14- `src/custom.ts`: update vendor, account, resource, and binding metadata.
15- `wrangler.jsonc`: add non-secret bindings/variables and a migration when adding Durable Object classes.
16- `deployment.jsonc`: provide deployment values. This sample is retired: `scripts/deploy.ts` no longer deploys it or generates a `GATEKEEPER_CUSTOM` binding, so wire a copy yourself the way the deploy wires Fork Horse's gatekeeper (`GATEKEEPER_FORKHORSE`).
17
18Put API tokens and OAuth credentials in Wrangler secrets, never `wrangler.jsonc` or `deployment.jsonc`.
19
20## Observer policy
21
22`CustomVerifier.verify()` accepts every observer because the example returns the same low-stakes deployment text to every authenticated user. That is not a safe default for account-specific, tenant-specific, or confidential data.
23
24A real integration must decide which observers may retain data and implement verification at that data boundary. Use upstream's [`write-gatekeeper` skill](https://github.com/cloudflare/cloudflare-os/blob/main/.agents/skills/write-gatekeeper/SKILL.md) for observer design, OAuth, URL-scoped resources, writes and simulation, hooks, and configurator UI.
25
26## Check
27
28```sh
29pnpm run test:run
30pnpm run types:check
31pnpm exec wrangler deploy --dry-run
32```
33