Writing a Gatekeeper

A Gatekeeper is a Cloudflare Worker that mediates all access between a Gadget and an external service. It implements a three-tier hierarchy:

• Vendor (GatekeeperVendor, a WorkerEntrypoint) — top-level entry for the service. One per service.
• User (GatekeeperUser, a WorkerEntrypoint with ctx.props) — a human user's authenticated connection.
• Instance (Gatekeeper<Session>, a DO facet of the Overseer) — per-resource, per-Gadget binding that provides the Session API.

Read packages/workshop-shared/src/gatekeeper.ts for the canonical interfaces and detailed JSDoc.

Seven responsibilities

1. Auth management — Manage authorization to the external service via OAuth (or similar), on behalf of the human end user. This means managing "connected accounts" — token storage, refresh, and revocation in a UserAccount Durable Object.

2. API design — Provide a TypeScript API wrapper around the service's API, compatible with Cap'n Web RPC. The interface should be designed around capability-based security: object-oriented, with separate interfaces representing logical resources. For example, the Google Docs gatekeeper provides an interface to a specific document, rather than a coarse-grained interface where you pass the doc ID to every method. IMPORTANT: When writing a new gatekeeper, design a proposed API and then STOP to let the operator review and make changes before proceeding with the rest of the implementation. Getting the API right is the most important and delicate part of creating a new gatekeeper.

3. Fine-grained resource granting — Enable the end user to grant access to agents at fine granularities, in addition to coarse-grained access. For example, a user may want to give an agent access to a specific Google Doc or GitHub repo, rather than granting broad access to everything they can do. This should be straightforward given a capability-based API. That said, broad access should also be allowed when it makes sense. Consider carefully which granularities are meaningful — a Jira gatekeeper might support "whole service", "project", and "issue" granularities, but it would be silly to support granting access to a single field of an issue separately.

4. Logging & approvals — Every action the agent or gadget performs must be logged via the ApprovalQueue API. Every action with an externally-visible side effect must be submitted via submitAction(), and must not actually be performed until applyAction() has been called. Read-only observations must call authorizeObservation() before returning data to the caller.