Index of every page on this site: llms.txt
All skills
cloudflare avatar

/write-gatekeeper

@b84d584
by cloudflarecloudflare/cloudflare-os12k stars
1,469
Run it yourself

Guides implementation of Gatekeeper Workers that bridge Gadgets to external services. Covers auth, capability-based API design, approval queue integration, action kinds and auto-approval verdicts, caching, and action simulation. Load when creating, modifying, or reviewing the implementation of a gatekeeper.

Use this Skill: https://skilld.dev/gh/cloudflare/cloudflare-os/write-gatekeeper

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKELETON.md

≈8.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Gatekeeper Implementation Skeleton

Replace all My/my/MY prefixes with the service name.

Observer safety: new gatekeepers versus migrations

This template is for a new gatekeeper with no historical observations. Explicitly report all access dependencies on every observation and authorize observers only in verifyObserverAccess(). The shared subresources field is currently optional, so the local typed helper below makes it required for reads and hook deliveries. Implement getHistoricalSubresources() returning []: it is required even though the current Gatekeeper interface does not declare it, so type-checking will not catch its absence. Implement addObserver(id, verifier) / removeObserver(id), which the current interface requires, as compatibility-only no-ops.

Do not copy the empty history export or no-op admission methods into an existing gatekeeper. An existing migration must export its actual historical access requirements through getHistoricalSubresources(), not a blind [], and preserve its old checks until all affected reads report complete requirements and a shipped kernel importer has committed the history to the observer ledger. The current kernel does not consume the export yet. This template needs no observer roster, observed-set log, excludeObservers, or legacy tracker.

subresources: [] means no observer-access restriction, never "the binding already checked". Private-only reads must still report a real resource ID and deny collaborators in verifyObserverAccess(). If tenant/workspace membership is required in addition to resource ACLs, report that membership resource on every affected observation and verify it explicitly too.

The fictitious provider below has one atomic resource per https://example.com/resources/:resourceId, with nonempty ASCII alphanumeric, _, or - IDs. Its authenticated GET /api/resources/:resourceId returns the resource's complete data on success; this same ACL covers its hook events. A 403 or 404 definitively means the account cannot read the resource; 401, network failures, and other errors are indeterminate and must propagate. Adapt these assumptions to the real provider: a public metadata probe is not proof of access to private data or hooks. The OAuth, action, and event-source scaffolding remains service-specific.

This is the B — One access-controlled unit example, not a requirement that a binding have one resource kind or one permission level. Account discovery can be private while item reads are shareable; a broad binding can report several independently checked resources, and one provider object can expose different audiences for metadata, content, or availability. Choose the strategy for each disclosure before adapting this template; see Choosing a strategy and the kit's worked Google patterns.

Main implementation (src/<name>.ts)

import { WorkerEntrypoint, DurableObject, RpcTarget, RpcStub } from "cloudflare:workers";
import {
  GatekeeperUser,
  GatekeeperUserVerifier,
  GatekeeperVendor as GatekeeperVendorIface,
  Gatekeeper,
  HookController,        // Remove if no hooks
  HookInitiator,         // Remove if no hooks
  HookTargetMetadata,    // Remove if no hooks
  ResourceDescription,
  ApprovalQueue,
  ActionKind,
  ObservationDescription,
  VendorDescription,
  GatekeeperConnectCallback,
  GatekeeperConnectOptions,
  AccountDescription,
  SupportedResource,
  ResourceConfiguratorFrame,
  resourceTypeUrlPattern,
} from '@gadgets/workshop-shared/gatekeeper';
import { observerAccessVerifier } from "@gadgets/gatekeeper-kit/observers";
import { formatSubresourceId } from "@gadgets/gatekeeper-kit/subresource-ids";
import { MySession, MyHook as MyHookIface } from "./types";  // Remove MyHook if no hooks
import TYPES_CODE from "./types.txt";
import MY_CONFIGURATOR_HTML from "./generated/my-configurator-ui.txt";

const NONCE_BYTES = 32;
const NONCE_LIFETIME_MS = 10 * 60 * 1000;  // 10 minutes

function hexEncode(bytes: Uint8Array): string {
  return [...bytes].map(b => b.toString(16).padStart(2, "0")).join("");
}

function generateNonce(): string {
  return hexEncode(crypto.getRandomValues(new Uint8Array(NONCE_BYTES)));
}

function constantTimeEqual(a: string, b: string): boolean {
  let encoder = new TextEncoder();
  let bufA = encoder.encode(a);
  let bufB = encoder.encode(b);
  if (bufA.byteLength !== bufB.byteLength) return false;
  return crypto.subtle.timingSafeEqual(bufA, bufB);
}

type Env = Cloudflare.Env & {
  BASE_URL?: string,
};

function getBaseUrl(env: Env) {
  return (env.BASE_URL || "http://localhost:8787/gatekeeper/<name>").replace(/\/+$/, "");
}

function getBasePath(env: Env) {
  const path = new URL(getBaseUrl(env)).pathname;
  return path === "/" ? "" : path;
}

const SELF_CLOSING_HTML = `<!DOCTYPE html>
<html lang="en">
  <body>
    <script type="text/javascript">window.close();</script>
    <p>Authorization complete. You may close this tab and return to the Gadgets Workshop.
  </body>
</html>`;

const MY_RESOURCE: SupportedResource = {
  id: "resource",
  urlPattern: "https://example.com/resources/:resourceId",
  title: "My Resource",
  description: "Access a specific resource.",
};

// One product: omit the optional product namespace. Use this exact ID on every read and hook.
function resourceSubresourceId(resourceId: string): string {
  return formatSubresourceId({ fragments: [{ name: "resource", id: resourceId }] });
}

function resourceApiUrl(resourceId: string): string {
  return `https://example.com/api/resources/${encodeURIComponent(resourceId)}`;
}

// The shared type still makes subresources optional; new observation paths must not omit them.
function authorizeResourceObservation(
    queue: Pick<RpcStub<ApprovalQueue>, "authorizeObservation">,
    description: ObservationDescription & { subresources: string[] }): Promise<void> {
  return queue.authorizeObservation(description);
}

// Every action declares an auto-approval verdict, and a kind when it can be true (SKILL.md
// "Action kinds and auto-approval"). The user's "always approve" rule is stored under the tag, so never rename it
// once shipped; the label is what the user sees.
const MY_EDIT_KIND: ActionKind = { tag: "edit-data", label: "Edit data" };

// ---------------------------------------------------------------------------
// HTTP handler — serves the browser-based auth flow.
// For a complete OAuth example, see gatekeeper-google/src/google.ts.

export default {
  async fetch(req: Request, env: Env, ctx: ExecutionContext) {
    let url = new URL(req.url);
    let basePath = getBasePath(env);
    if (!url.pathname.startsWith(basePath + "/") && url.pathname !== basePath) {
      throw new Error(`Request path ${url.pathname} does not match BASE_URL path ${basePath}`);
    }
    let relPath = url.pathname.slice(basePath.length);
    let path = relPath.slice(1).split("/");

    if (path.length === 2 && path[0].length === 64 && path[1].length === NONCE_BYTES * 2) {
      // Auth initiation: the user has visited the connect URL.
      let doId = path[0];
      let nonce = path[1];
      let stub = ctx.exports.UserAccount.get(ctx.exports.UserAccount.idFromString(doId));
      if (!await stub.verifyNonce(nonce)) {
        // Show a friendly error page for expired/replayed links.
        return new Response("TODO: error HTML", {
          headers: { "Content-Type": "text/html; charset=utf-8" }
        });
      }

      // TODO: Redirect to external auth provider, or present an auth form.
      // For OAuth, generate a second nonce for the `state` parameter here —
      // see gatekeeper-google for the full pattern.
      throw new Error("TODO: implement auth initiation");
    } else {
      return new Response("Not Found", {status: 404});
    }
  }
};

// ---------------------------------------------------------------------------
// Vendor — top-level API exposed to the Workshop

export class GatekeeperVendor extends WorkerEntrypoint<Env> implements GatekeeperVendorIface {
  async describe(): Promise<VendorDescription> {
    return {
      displayName: "My Service",
      url: "https://example.com",
      logo: { url: "TODO: data URL or hosted image URL" },
      color: "#f0f4ff",
      tagline: "Short summary of what this connector enables",
      description:
          "Explain what Gadgets can do with this connector in plain language.",
    };
  }

  // This skeleton has no independently grantable resources, so it ignores
  // `options.resourceTypeIds` and stores an empty requested-resource list. Gatekeepers with
  // grantable resources should follow gatekeeper-google.
  async connectAccount(
      callback: Fetcher<GatekeeperConnectCallback>,
      _options?: GatekeeperConnectOptions): Promise<{url: string}> {
    let userObjectId = this.ctx.exports.UserAccount.newUniqueId();
    let nonce = generateNonce();
    await this.ctx.exports.UserAccount.get(userObjectId).setCallback(callback, nonce, []);
    return { url: `${getBaseUrl(this.env)}/${userObjectId.toString()}/${nonce}` };
  }

  async getSupportedResources(): Promise<SupportedResource[]> {
    return [MY_RESOURCE];
  }

  async getTypeScriptTypes(): Promise<string> {
    return TYPES_CODE;
  }
}

// ---------------------------------------------------------------------------
// UserAccount DO — stores per-user credentials (tokens, API keys, etc.).
// For a full OAuth implementation with two-phase nonces and reconnect support,
// see gatekeeper-google.
export class UserAccount extends DurableObject<Env> {
  async setCallback(
      callback: Fetcher<GatekeeperConnectCallback>,
      nonce: string,
      requestedResourceUrlPatterns: string[]) {
    // Self-destruct if the connect flow is never completed.
    if (!this.ctx.storage.kv.get<string>("credentials")) {
      this.ctx.storage.setAlarm(Date.now() + 3600 * 1000);
    }
    this.ctx.storage.kv.put("callback", callback);
    this.ctx.storage.kv.put("nonce", { value: nonce, expiresAt: Date.now() + NONCE_LIFETIME_MS });
    this.ctx.storage.kv.put("requestedResourceUrlPatterns", requestedResourceUrlPatterns);
  }

  // Verify and consume the nonce from the initiation URL. Prevents replay.
  // Returns false if the nonce is invalid or expired.
  async verifyNonce(nonce: string): Promise<boolean> {
    let stored = this.ctx.storage.kv.get<{value: string, expiresAt: number}>("nonce");
    if (!stored || Date.now() >= stored.expiresAt || !constantTimeEqual(stored.value, nonce)) {
      return false;
    }
    this.ctx.storage.kv.delete("nonce");
    return true;
  }

  // Called when the user completes authorization. Store credentials and notify the workshop.
  async completeConnection(/* auth result params */) {
    let callback = this.ctx.storage.kv.get<Fetcher<GatekeeperConnectCallback>>("callback");
    if (!callback) {
      throw new Error("Authorization timed out. Please try again.");
    }

    // TODO: Store credentials obtained from the auth flow
    this.ctx.storage.kv.put<string>("credentials", "TODO");

    let props: MyUserImplProps = { userObjectId: this.ctx.id.toString() };
    try {
      await callback.complete(this.ctx.exports.MyUserImpl({ props }));
    } catch (err) {
      this.ctx.storage.kv.delete("credentials");
      throw err;
    }
  }

  async getAccessToken(): Promise<string> {
    // TODO: Return a cached short-lived token, refreshing credentials if needed.
    let token = this.ctx.storage.kv.get<string>("credentials");
    if (!token) throw new Error("No credentials set.");
    return token;
  }

  async alarm() {
    if (!this.ctx.storage.kv.get<string>("credentials")) {
      this.ctx.storage.deleteAll();
    }
  }

  async revoke() {
    // TODO: Revoke credentials with the external service
    this.ctx.storage.deleteAlarm();
    this.ctx.storage.deleteAll();
  }
}

// ---------------------------------------------------------------------------
// UserImpl — maps resource URLs to gatekeeper DO classes

type MyUserImplProps = {
  userObjectId: string;
};

export class MyUserImpl extends WorkerEntrypoint<Env, MyUserImplProps>
                         implements GatekeeperUser {
  async describe(): Promise<AccountDescription> {
    // TODO: Fetch account info from external service using stored credentials
    return {
      displayName: "TODO",
      avatar: { url: "" },
    };
  }

  async getSupportedResources(): Promise<SupportedResource[]> {
    return [MY_RESOURCE];
  }

  async startResourceConfigurator(resourceTypeId: string): Promise<ResourceConfiguratorFrame> {
    resourceTypeUrlPattern([MY_RESOURCE], resourceTypeId);
    let id = this.ctx.exports.UserAccount.idFromString(this.ctx.props.userObjectId);
    let userAccount = this.ctx.exports.UserAccount.get(id);
    let ui = new MyConfiguratorUI(async () => {
      // TODO: Return a short-lived token or construct a read-only API client.
      // Keep this helper private; do not expose it as an RPC method.
      return await userAccount.getAccessToken();
    });
    return {
      iframeHtml: MY_CONFIGURATOR_HTML,
      ui: new RpcStub(ui),
    };
  }

  async getGatekeeperClassFor(url: string): Promise<{
    class: DurableObjectClass<Gatekeeper<any>>;
    resource: SupportedResource;
  }> {
    let parsed = new URL(url);
    let match = /^\/resources\/([A-Za-z0-9_-]+)\/?$/.exec(parsed.pathname);
    if (parsed.origin !== "https://example.com" || !match || parsed.search || parsed.hash) {
      throw new Error("Unsupported resource URL");
    }
    // The Overseer instantiates this class as a facet, with the resource pinned in props.
    let props: MyGatekeeperImplProps = {
      userObjectId: this.ctx.props.userObjectId,
      resourceId: match[1],
    };
    return {
      class: this.ctx.exports.MyGatekeeperImpl({ props }),
      resource: MY_RESOURCE,
    };
  }

  async revoke(): Promise<void> {
    let id = this.ctx.exports.UserAccount.idFromString(this.ctx.props.userObjectId);
    await this.ctx.exports.UserAccount.get(id).revoke();
  }

  async ensureResources(_resourceTypeIds: string[]): Promise<{url?: string}> {
    return {};
  }

  // The overseer only hands this account verifier back to this vendor, so
  // MyGatekeeperImpl.verifyObserverAccess may call its vendor-specific ACL probe.
  async getVerifier(): Promise<Fetcher<GatekeeperUserVerifier>> {
    let props: MyVerifierProps = { userObjectId: this.ctx.props.userObjectId };
    return this.ctx.exports.MyVerifier({ props });
  }
}

// ---------------------------------------------------------------------------
// Verifier — answers "can this observer access X?" against the OBSERVER's own credentials.
// Probe the same data endpoint/ACL used by getData(), not public metadata or the owner's account.

type MyVerifierProps = {
  userObjectId: string;
};

// Vendor-specific methods on the otherwise opaque verifier. The overseer's same-vendor guarantee
// lets verifyObserverAccess cast it back to this interface for this call only.
export interface MyVerifierApi extends GatekeeperUserVerifier {
  hasResourceAccess(resourceId: string): Promise<boolean>;
}

export class MyVerifier extends WorkerEntrypoint<Env, MyVerifierProps>
    implements MyVerifierApi {
  async hasResourceAccess(resourceId: string): Promise<boolean> {
    let account = this.ctx.exports.UserAccount.get(
        this.ctx.exports.UserAccount.idFromString(this.ctx.props.userObjectId));
    let token = await account.getAccessToken();
    let response = await fetch(resourceApiUrl(resourceId), {
      headers: { Authorization: `Bearer ${token}` },
      redirect: "manual",  // Workers has no "error"; a 3xx is not ok, so it throws below.
    });
    // Discard data: this probe answers an ACL question, it does not reveal data to a caller.
    await response.body?.cancel();
    if (response.status === 403 || response.status === 404) return false;
    if (!response.ok) {
      // Includes 401 (expired/invalid credentials), throttling, and provider outages.
      throw new Error(`Could not determine resource access: HTTP ${response.status}`);
    }
    return true;
  }
}

// ---------------------------------------------------------------------------
// Resource configurator — narrow iframe helper API

const configuratorTokenGetters = new WeakMap<object, () => Promise<string>>();

class MyConfiguratorUI extends RpcTarget {
  constructor(getToken: () => Promise<string>) {
    super();
    configuratorTokenGetters.set(this, getToken);
  }

  async listResources(query: string): Promise<{ value: string; title: string }[]> {
    let getToken = configuratorTokenGetters.get(this);
    if (!getToken) throw new Error("Configurator is not initialized.");
    let token = await getToken();
    void token;
    // TODO: Call read-only external APIs and return bounded search results.
    return [{ value: query || "example", title: query || "Example" }];
  }

}

// ---------------------------------------------------------------------------
// Hook type — remove this section (and the HookController/HookInitiator/HookTargetMetadata
// imports, the `subscribe` method, the `hookTsType` field, and MyHookControllerImpl) if the
// gatekeeper doesn't push events.
//
// The hook interface from types.d.ts is implemented by the Gadget as an RpcTarget. Intersect it
// with RpcTarget so it satisfies the HookController/HookInitiator generic constraints (Hook
// extends RpcTarget).
//
// Note that you can also use a plain function as a hook type, e.g. `RpcStub<() => Promise<void>>`.
// In that case you would not need to merge the type with `RpcTarget`.

type MyHook = RpcTarget & MyHookIface;

// ---------------------------------------------------------------------------
// GatekeeperImpl DO — per-resource instance, runs as a facet of the Overseer

type MyGatekeeperImplProps = {
  userObjectId: string;
  resourceId: string;
};

export class MyGatekeeperImpl extends DurableObject<Env, MyGatekeeperImplProps>
    implements Gatekeeper<MySession> {

  async describe(): Promise<ResourceDescription> {
    return {
      url: `https://example.com/resources/${encodeURIComponent(this.ctx.props.resourceId)}`,
      title: "TODO",
      snippet: "TODO",
      suggestedBindingName: "MY_RESOURCE",  // Based on type, not instance
      tsType: "MySession",
      hookTsType: "MyHook",  // Remove if hooks are not supported
    };
  }

  async getTypeScriptTypes(): Promise<string> {
    return TYPES_CODE;
  }

  // The kinds this binding can submit with `autoApprovable: true`, offered to the user to enable.
  // Approves nothing by itself. With gatekeeper-kit, return `autoApprovableKinds()` filtered to
  // this binding; return [] if every action opts out.
  async getAutoApprovableActions(): Promise<ActionKind[]> {
    return [MY_EDIT_KIND];
  }

  async startSession(approvalQueue: RpcStub<ApprovalQueue>): Promise<MySession> {
    return new MySessionImpl(
      approvalQueue.dup(),  // Always dup() before storing
      this.ctx,
      // ... API client, props, etc.
    );
  }

  async applyAction(actionId: number): Promise<void> {
    // Look up the action by ID from this gatekeeper's own storage, then perform it
    // against the external service.
    // TODO: Implement action lookup and execution.
    throw new Error(`Unknown action: ${actionId}`);
  }

  async rejectAction(actionId: number): Promise<void | { restart?: boolean }> {
    // Clean up simulation state for this action.
    // Return { restart: true } if the session can't recover from rejection.
  }

  revertAction(actionId: number):
      Promise<void | { message?: string; canRetry?: boolean; restart?: boolean }> {
    // TODO: Undo the action (look up what was done from own storage)
    throw new Error("Revert not implemented");
  }

  // Judges each observer by the verifier this call brings, against every reported ID, and stores
  // nothing. If the oracle throws, the whole call fails and the Workshop denies everyone in it.
  readonly #verifyObserverAccess = observerAccessVerifier({
    hasCollectionAccess: async (verifier: Fetcher<MyVerifierApi>, subresources) => {
      // Every ID this binding reports names its one atomic resource, so one live ACL probe
      // covers them all.
      let allowed = await verifier.hasResourceAccess(this.ctx.props.resourceId);
      return subresources.map(() => allowed);
    },
  });

  // Required, though the current Gatekeeper interface does not declare it. A new gatekeeper
  // observed nothing under the legacy observer protocol, so the export is empty and reads no state.
  async getHistoricalSubresources(): Promise<string[]> {
    return [];
  }

  async verifyObserverAccess(
      observers: { id: string; verifier: Fetcher<GatekeeperUserVerifier> }[],
      subresources: string[]): Promise<{ allowedObserverIds: string[] }> {
    let expected = resourceSubresourceId(this.ctx.props.resourceId);
    // Refuse an ID this binding never reports rather than guessing what it names.
    if (subresources.some(id => id !== expected)) {
      throw new Error("This connection was asked about a resource it never reported.");
    }
    return this.#verifyObserverAccess(observers, subresources);
  }

  // Compatibility only: the current interface requires these. All access dependencies are
  // explicit on observations; observer authorization is above, never here.
  async addObserver(_id: string, _verifier: Fetcher<GatekeeperUserVerifier>): Promise<void> {}

  // Compatibility only; there is no observer state to remove.
  async removeObserver(_id: string): Promise<void> {}
}

// ---------------------------------------------------------------------------
// HookController — remove if the gatekeeper doesn't push events.
//
// A WorkerEntrypoint the overseer uses to enable/disable the hook after the user approves it.
// It is constructed with `props` carrying the specifics of that particular registration, so it
// needs no other state. If your gatekeeper offers several kinds of hooks, give each its own
// controller class.

// Bind-time details for a single hook registration, baked into the controller's props.
type MyHookProps = {
  // TODO: e.g. an event kind, a filter, a sub-resource id, etc. — whatever the registration
  // method received and the controller/event source will need later.
  filter?: string;
};

type MyHookControllerImplProps = MyGatekeeperImplProps & MyHookProps;

export class MyHookControllerImpl extends WorkerEntrypoint<Env, MyHookControllerImplProps>
    implements HookController<MyHook> {
  // Called when the user enables the hook. Store `initiator` somewhere it can be reached when an
  // event arrives — typically an event-source DO. Don't store other state until now; everything
  // else is already in `this.ctx.props`. If already enabled, replace the previous initiator.
  //
  // `target` identifies where the hook delivers (workspace, and gadget when pinned to one). Store
  // it too if you display or link to the target; otherwise ignore it, but keep the parameter
  // declared — RPC argument validation rejects arguments the receiver doesn't declare.
  async enable(initiator: Fetcher<HookInitiator<MyHook>>, target: HookTargetMetadata): Promise<void> {
    // TODO: persist `initiator` (e.g. forward it to an event-source DO keyed by props).
  }

  // Called when the hook is disabled or deleted. Forget the stored initiator and clean up all
  // related state. May never be called again, though the overseer may later call enable() afresh.
  async disable(): Promise<void> {
    // TODO: forget the stored initiator.
  }
}

// Event delivery (sketch). When the external event arrives — e.g. in the event-source DO that
// holds the `initiator` — invoke the hook like so. The resource ID comes from the enabled
// registration's props, never an untrusted event field; events reveal only that resource:
//
//   async onEvent(initiator: Fetcher<HookInitiator<MyHook>>, resourceId: string, event: MyEvent) {
//     // startHook() begins a fresh session and returns the callback (re-bound to it) plus an
//     // ApprovalQueue. Await the disposable result so `using` releases its stubs even on denial.
//     using result = await initiator.startHook();
//
//     // A hook event is almost always an observation. (Register actions too if invoking the
//     // callback can cause side effects.) Authorize before delivering any event data.
//     await authorizeResourceObservation(result.approvalQueue, {
//       title: "Resource event",
//       description: "Delivered an event from the bound resource.",
//       subresources: [resourceSubresourceId(resourceId)],
//     });
//
//     // Deliver the event to the Gadget's callback.
//     await result.callback.onMyEvent(event);
//   }

// ---------------------------------------------------------------------------
// SessionImpl — the RPC interface exposed to the Gadget

class MySessionImpl extends RpcTarget implements MySession {
  #approvalQueue: RpcStub<ApprovalQueue>;
  #ctx: DurableObjectState<MyGatekeeperImplProps>;

  constructor(
      approvalQueue: RpcStub<ApprovalQueue>,
      ctx: DurableObjectState<MyGatekeeperImplProps>) {
    super();
    this.#approvalQueue = approvalQueue;
    this.#ctx = ctx;
  }

  [Symbol.dispose]() {
    this.#approvalQueue[Symbol.dispose]();
  }

  // Example: observation (read). Fetch data, then authorize before returning.
  async getData(): Promise<string> {
    let account = this.#ctx.exports.UserAccount.get(
        this.#ctx.exports.UserAccount.idFromString(this.#ctx.props.userObjectId));
    let token = await account.getAccessToken();
    let response = await fetch(resourceApiUrl(this.#ctx.props.resourceId), {
      headers: { Authorization: `Bearer ${token}` },
      redirect: "manual",  // Workers has no "error"; a 3xx is not ok, so it throws below.
    });
    if (!response.ok) throw new Error(`Resource read failed: HTTP ${response.status}`);
    let result = await response.text();

    await authorizeResourceObservation(this.#approvalQueue, {
      title: "Read data",
      description: "Fetched data from the bound resource.",
      subresources: [resourceSubresourceId(this.#ctx.props.resourceId)],
    });

    return result;
  }

  // Example: action (side effect). Submit for approval; do NOT perform here.
  // Assign a sequential action ID, store the action details in the gatekeeper's
  // own storage, then submit the ID to the approval queue. If you read current state to build
  // the description or capture revert info, do NOT log it as an observation: nothing is
  // returned to the caller.
  async updateData(newValue: string): Promise<void> {
    let actionId = /* assign next sequential ID and store action details */ 0;

    await this.#approvalQueue.submitAction(actionId, {
      title: "Update data",
      description: `Update value to: ${newValue}`,
      implementsRevert: true,
      actionKind: MY_EDIT_KIND,
      // `true` unless the action falls under the opt-out policy in SKILL.md. Where it depends on
      // the payload, compute it, with a comment naming the rule:
      //   autoApprovable: !removesContent(newValue),  // rule 1: deletes or removes content
      autoApprovable: true,
    });

    // TODO: Update cache/simulation state so subsequent reads reflect this
  }

  // Example: hook registration — remove if the gatekeeper doesn't push events.
  // `callback` is a persistent stub the Gadget created with ctx.restore(). Construct a controller
  // whose props capture the specifics of THIS registration (e.g. `filter`), then hand it, the
  // callback, and a user-facing description to the overseer via bindHook(). For multiple hook
  // kinds, pick the appropriate controller class here. Do NOT store the callback yourself — it is
  // bound to this session and would be revoked when the session ends.
  async subscribe(callback: RpcStub<MyHook>, filter?: string): Promise<void> {
    let controller = this.#ctx.exports.MyHookControllerImpl({
      props: { ...this.#ctx.props, filter },
    });
    await this.#approvalQueue.bindHook(controller, callback, {
      title: "TODO: short hook title",
      description: `TODO: what events this hook delivers${filter ? ` (filter: ${filter})` : ""}`,
    });
  }
}

cloudflare.config.ts

import {
  DEFAULT_GATEKEEPER_WRANGLER, OBSERVABILITY, defineGadgetsWorker, type DurableObjectMigration,
} from "@gadgets/scripts/worker-config";

export default defineGadgetsWorker({
  name: "gatekeeper-<name>",
  entrypoint: ".wrangler/validate/src/<name>.ts",
  compatibilityFlags: ["allow_irrevocable_stub_storage"],
  observability: OBSERVABILITY,
});

export const wrangler = DEFAULT_GATEKEEPER_WRANGLER;

export const migrations: DurableObjectMigration[] = [
  { tag: "v0", new_sqlite_classes: ["UserAccount", "MyGatekeeperImpl"] },
];

Run pnpm configs:generate; the generated wrangler.jsonc is committed and never edited by hand.

Only Durable Object classes go in new_sqlite_classes. MyVerifier and MyHookControllerImpl are WorkerEntrypoints, so they need no migrations entry — but, like all entrypoints, they must be exported from the worker's main module (so ctx.exports.MyVerifier(...) resolves). If your hook uses a dedicated event-source DO to hold the initiator, add that DO here too.

Creating the types.txt symlink

cd packages/gatekeeper-<name>/src
ln -s types.d.ts types.txt

Resource configurator files

Add per-resource configurator types and UI modules:

src/configurator/my-configurator-types.d.ts
src/configurator/my-configurator-types.txt -> my-configurator-types.d.ts
src/configurator/my-configurator-ui.tsx

my-configurator-types.d.ts should describe the iframe helper API. The UI module's own resourceUrl() hook returns the resource URL to Workshop.

export interface MyConfiguratorUI {
  listResources(query: string): Promise<{ value: string; title: string }[]>;
}

Add package scripts:

{
  "scripts": {
    "deploy": "vp run --no-cache build:configurator && wrangler deploy"
  },
  "dependencies": {
    "@gadgets/configurator-ui": "workspace:*",
    "@gadgets/gatekeeper-kit": "workspace:*"
  },
  "devDependencies": {
    "@gadgets/scripts": "workspace:*"
  }
}

@gadgets/scripts has to be declared, not just imported. The shared task configs and the gadgets-* bins that run them belong to that package, and the workspace root depends on it too — so its bins are already on PATH and a vite.config.ts importing it resolves even with no declaration here. That is a phantom dependency: it works until this package is built somewhere that does not happen to hoist it.

No build script: build is one of the shared Vite+ tasks below, and vp forbids a task and a script sharing a name. Build this one package with pnpm exec vp run -F <package-name> build — pnpm --filter cannot see a task, so pnpm --filter <package-name> build reports nothing to run; the workspace-wide pnpm build picks it up as usual. deploy goes through the task rather than calling build-gatekeeper-configurator.ts itself, so the codegen command lives in one place and cannot drift from the task that declares its env — wrangler deploy stays outside vp, since it has side effects and needs real credentials.

Also add a vite.config.ts re-exporting the shared build and build:configurator Vite+ tasks — the latter is what the pnpm dev-server pre-flight builds (vp run -r --cache build:configurator --dev). Both are tasks rather than package.json scripts so VITE_FRONTEND_ERROR_REPORTING is passed through and cache-fingerprinted; a build script running the builder with && would bypass that and silently bake the wrong value into the shipped HTML (do not add either script back):

// Vite+ per-package settings. The build:configurator task definition is shared by all gatekeepers
// with a configurator UI and ships as an export of `@gadgets/scripts`, alongside the builder it
// runs.
export { default } from '@gadgets/scripts/gatekeeper-configurator'

// ...or, if the gatekeeper has tests, `withTests` instead: the same settings plus the shared vitest
// `test` task. Add a `"test:run": "vitest run"` script too, for iterating without the cache.
export { withTests as default } from '@gadgets/scripts/gatekeeper-configurator'

Keep tokens and broad API clients out of public RpcTarget properties; use closures, #private, or WeakMap state and expose only narrow read-only helper methods.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning11d3 checks · Risk SAFE
  • Gen Agent Trust Hub11d

    This skill provides a comprehensive framework and template for implementing 'Gatekeeper' Cloudflare Workers. It establishes security-centric design patterns, including capability-based authorization, mandatory observation logging, and fine-grained resource granting. The guidelines promote best practices for authentication management and auditability. No security concerns were identified.

  • Socket11d

    No alerts

  • Snyk11d

    Risk: MEDIUM · 1 issue

Signed by skilld at b84d584. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 7 hours ago.

Activeupdated yesterday

README badge

README badge for cloudflare/cloudflare-os/write-gatekeeper