install-gatekeepers-in-os-fork

Files (3)

• SKILL.md
• credentials-and-bindings.md
• package-adaptations.md

SKILL.md (first lines)

# Install Gatekeepers In A Cloudflare OS Fork

Port the wrapper-owned Asana, AWS, and simulated QuickBooks Gatekeepers into a **fork of Cloudflare OS**, not into `cloudflare-os/` as a submodule patch and not via this wrapper's `deployment.jsonc` / `scripts/deploy.mjs`.

If the destination has `deployment.jsonc`, `scripts/deploy.mjs`, and `packages/custom-gatekeeper/`, it is a Deployment Starter wrapper. Stop and use [cloudflare-os-operator](../cloudflare-os-operator/SKILL.md) plus extra `GATEKEEPER_*` bindings in that wrapper. This skill is for an OS-shaped tree.

Do not enable the copied vendors in `/admin` until provenance, credentials, and observer policy are reviewed. Do not copy secrets.

## Locate Source And Destination

**Source** (this wrapper) must contain:

- `packages/gatekeeper-asana/`
- `packages/gatekeeper-aws/`
- `packages/gatekeeper-quickbooks/`
- `scripts/sync-gatekeeper-types.mjs`

**Destination** (OS fork) must contain:

- `packages/workshop-backend/`
- `packages/workshop-shared/`
- `run-dev-server.js`
- existing `packages/gatekeeper-*`

Do not assume the current working directory is either root. Organization context (`packages/custom-gatekeeper`) is out of scope unless the operator explicitly includes it.

## Hard Stops

- Never copy `.env`, `.dev.vars`, `.data/secrets/`, Worker secrets, tokens, or this deployment's Worker names.
- Never put secrets in `wrangler.jsonc`, `deploy-inputs.json` values, tracked files, or chat.
- Never enable auto-provisioned vendors for everyone as a smoke test.
- Stop if `packages/workshop-shared/src/gatekeeper.ts` is incompatible with the copied packages; record both commits and get operator approval before adapting APIs.
- Asana is **MCP OAuth**, not a REST personal access token.

## Workflow

Copy this checklist and track it:

```text
- [ ] 1. Classify destination as OS fork (not starter wrapper)
- [ ] 2. Diff workshop-shared Gatekeeper contract; get API/policy approval
- [ ] 3. Copy packages + sync-gatekeeper-types.mjs (code only)
- [ ] 4. Adapt package.json, tsconfig, wrangler.jsonc to the OS tree
- [ ] 5. Declare destination credential inputs; write gitignored .dev.vars
- [ ] 6. pnpm install, typecheck, test
- [ ] 7. Prove local GATEKEEPER_* discovery
- [ ] 8. Wire production (release manifest or direct wrangler)
- [ ] 9. Install destination secrets interactively
- [ ] 10. Keep /admin disabled or optional; rewrite and introduce skills
- [ ] 11. Verify observations; no credential leakage; QuickBooks labeled synthetic
```

### 1. Review contract and policy

Diff the destination `packages/workshop-shared/src/gatekeeper.ts` against this repo's pinned `cloudflare-os` gitlink. The copied Workers use Cap'n Web `GatekeeperVendor` / `CustomSession` / `authorizeObservation()`.

All three set `autoProvisionsAccount: true` and no-op observer verification (`addObserver` / `removeObserver` / `verify()`). **Enabled** in `/admin` makes them ambient for every user. That is unsafe if Gadgets are shared across identities that must not see Asana or AWS data.

Rewrite DEPARTURE-facing display names, observation text, and companion skills before treating the destination as a different tenant. QuickBooks is a **fixed synthetic dataset**, not Intuit.

Load the destination's `write-gatekeeper` skill before changing session APIs. These three have no resource configurator (`getSupportedResources()` is empty); skip configurator UI unless adding URL-scoped resources.

### 2. Copy code

From this repo into the **fork** root, keeping directory names:

```text
packages/gatekeeper-asana/        → packages/gatekeeper-asana/
packages/gatekeeper-aws/          → packages/gatekeeper-aws/
packages/gatekeeper-quickbooks/   → packages/gatekeeper-quickbooks/
scripts/sync-gatekeeper-types.mjs → scripts/sync-gatekeeper-types.mjs
```

Directory names must match each `wrangler.jsonc` `name`. Local Miniflare binds by directory; production bindings are `GATEKEEPER_ASANA`, `GATEKEEPER_AWS`, `GATEKEEPER_QUICKBOOKS`.

`packages/*` is already in the OS `pnpm-workspace.yaml`.

Apply file adaptations from [package-adaptations.md](package-adaptations.md).

### 3. Credentials (reinstall, never copy)

Declare inputs and local files using [credentials-and-bindings.md](credentials-and-bindings.md).

Non-secret destination vars belong in each package's `wrangler.jsonc` `vars`:

| Package | Vars | Secrets |
| --- | --- | --- |
| Asana | `ASANA_CLIENT_ID`, `ASANA_WORKSPACE_GID` | `ASANA_CLIENT_SECRET`, `ASANA_REFRESH_TOKEN` |
| AWS | `AWS_REGIONS` (comma-separated) | `AWS_ACCESS_KEY`, `AWS_ACCESS_KEY_SECRET` |
| QuickBooks | none | none |

Use the destination tenant's MCP OAuth app, workspace GID, and least-privilege AWS principal. Optional `ASANA_ACCESS_TOKEN` is a bootstrap only; MCP rejects REST PATs.

### 4. Validate locally

From the fork root, using **pnpm** only:

```sh
pnpm install
pnpm --filter @gadgets/gatekeeper-asana types:check
pnpm --filter @gadgets/gatekeeper-aws types:check
pnpm --filter @gadgets/gatekeeper-quickbooks types:check
pnpm --filter @gadgets/gatekeeper-asana test
pnpm --filter @gadgets/gatekeeper-aws test
pnpm --filter @gadgets/gatekeeper-quickbooks test
pnpm types:check
pnpm test
pnpm run-local
```

`run-dev-server.js` discovers `packages/gatekeeper-*` that have `wrangler.jsonc` and injects `GATEKEEPER_*` Workshop bindings with entrypoint `GatekeeperVendor`. Confirm those three bindings exist in the generated workshop `wrangler.dev.jsonc`.

This wrapper's `scripts/run-local.mjs` symlinks and Asana token helper do **not** exist in upstream. Per-package gitignored `.dev.vars` is the local secret path.

### 5. Production

Workshop and router committed `wrangler.jsonc` files do not list extra gatekeepers. Bindings are injected.

Choose the fork's deploy path and follow [credentials-and-bindings.md](credentials-and-bindings.md):

From departure/ontix-iq, Apache-2.0.

More from departure/ontix-iq