Skip to content

phuryn/product-engineering / app-stack/skills/environments

environments

Verified

Adding a variable or secret, 'set up production', a domain or a provider token, 'which database is this', a leaked key: dev and production for an AI-built app, backups, incidents.

references/domain-and-provider-access.md

View on GitHub
# The domain, and the agent's access to providers

Taking a product to its domain and its production accounts: what the agent may hold while it does the setup, the order the domain comes up in, which hosts sit behind a proxy, and what to tighten before the first users. The mechanics belong to the vendors and change, so this file links to them and keeps the order and the boundaries. Every vendor fact here was read on the vendor's pages on 2026-10-28, and the managed `robots.txt` and Google's crawler list on 2026-10-29. For a typical product on Netlify, Clerk and Supabase, Cloudflare is the DNS provider and little else.

## Who holds what

- **The owner creates every provider credential the agent uses; the agent never mints its own.** (The app's own generated secrets are still the agent's to make: `variables.md`.) The owner also does what commits the account: the registrar and its nameservers, adding the zone, paid plans, creating or widening a token, and each vendor's dashboard-only settings (on Clerk: the production instance, legal consent at sign-up, the social sign-in credentials, connecting the payment account; `clerk-production`).
- **Ask for the smallest token the vendor offers, one per environment** (`SKILL.md`, separate key sets). On Cloudflare that is a custom API token on one zone, with *Zone · DNS · Edit* (*DNS Write* in the permissions list) and nothing else until a command needs more ([permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)). When a command is refused for a missing permission, the owner adds that one permission, and the record says so (a Cloudflare token is edited in place; a Supabase token can't be changed, so the owner issues a new one and revokes the old: [Supabase](https://supabase.com/changelog/scoped-personal-access-tokens-ga)). A token scopes to a zone, not to records, so on one zone shared by both environments a DNS token reaches production's records whichever environment it is for: it stays time-boxed and is revoked after the setup. An operator command that writes development's DNS after that needs development on a zone of its own (a second domain), so development's token reaches nothing of production's; until then, each such write waits for a time-boxed token from the owner.
- **Record each token when it is made**: its row in the variables doc (its permissions and what they reach, who made it and when it expires, in *Source*; what rotating it costs, in *Rotation*) and, in the copies table where there is one, where it sits while in use. Some tokens cannot read their own policy back, so the record is the only place the scope is known. (`2026-10-28`, a monitoring product's account of its setup: its DNS provider's token had been widened over several sessions until it reached every zone in the account, and its records did not say who had made or widened which token.)
- **Where the vendor has no scoped token, time-box it.** A Netlify personal access token reaches the whole account, so the owner issues it with an expiry and revokes it when the setup is done (`variables.md § Setting values on the host`).
- **An identity provider's CLI session reaches the whole account too.** Clerk's (`npx clerk auth login`) picks any application in the account with `--app` ([Clerk's CLI](https://clerk.com/docs/cli), read 2026-10-29) and production with `--instance prod` (`clerk-production`), so it is time-boxed the same way: the owner signs it in for an apply and its read-back, and it is signed out (`npx clerk auth logout`) once both are done. If it prints that it signed out locally only, the session could not be revoked with Clerk, and the owner revokes it in Clerk's dashboard, as that message says.
- **Supabase has scoped personal access tokens** ([Supabase](https://supabase.com/docs/guides/platform/personal-access-tokens); generally available `2026-10-06`): one can be limited to selected projects in one organization, read or read-write per capability, for the Management API, the MCP and the CLI. **Development setup uses the CLI and needs no management token.** Every database command uses its own connection string without linking. Issue a read-only, development-project-only token through `SUPABASE_ACCESS_TOKEN` only when the agent needs the MCP for logs or advisors (`supabase-production` § The choices). `supabase link` needed *API Key Secrets* (Read), which gives the secret key and access to all of the project's data. Tokens scope to projects. Unless the form lists a branch on its own, a token that reaches a development branch also reaches its parent, production. If the owner chooses a development branch of production, use its connection string without an MCP or parent-project grant for development. Never the CLI's browser login, which creates a token with the account's full access, every organization included (still so when scoped tokens shipped), and which the CLI falls back on whenever the variable is unset: if `supabase login` was ever run on this machine (in bash, `env -u SUPABASE_ACCESS_TOKEN npx supabase projects list >/dev/null 2>&1 && echo logged-in` prints `logged-in`), the owner runs `npx supabase logout`, or the agent does on the owner's go, with `npx supabase logout --yes` (without `--yes` it asks, and a shell with no terminal answers no): it deletes the saved token and every database password the CLI saved on this machine, for every project, and revokes nothing; then the owner deletes that token in the account's access tokens. The MCP server's browser sign-in reaches the whole organization too; it gets development's token in its `Authorization` header instead ([Supabase MCP](https://supabase.com/docs/guides/getting-started/mcp); apply `supabase-production` § The choices for the diagnostic setup). Production's management reads (backups, SSL enforcement, network restrictions) are the owner's, in the dashboard, or on a read-only production token issued time-boxed. Production's database is written only through its connection string (`supabase-production`): for the setup go-live step 1 lists, then on the owner's go.
- **The secret keys the agent uses during setup are its own, deleted once it is done.** Supabase's secret keys have no narrower form ([Supabase](https://supabase.com/docs/guides/api/api-keys)), and Clerk documents none for its secret key, but both allow more than one at a time (`variables.md § Rotating`). So the owner makes one for the setup, the agent uses production's to apply the setup's settings and read them back, before go-live step 3 (after it, a production setting waits for the owner's go), and the owner deletes it when the setup is done: no holder changes, and the setup session's transcripts hold a dead value. Where the agent used the app's own keys instead, the owner rotates them: every holder in the copies table gets the new value, operator files included, each is deployed and checked, and the old value is revoked last.
- **Payments and email get one key per environment.** With billing inside the identity provider (Clerk Billing), the app holds no payment key at all. With Stripe called directly, use [restricted keys](https://docs.stripe.com/keys), each allowed only what its code calls. For email, one provider server or key per environment, so a development key can't send as production; the development redirect is what keeps development from mailing a real person (`transactional-email`).

## The domain, in order

Each step waits until the one before it is verified, because each vendor checks DNS before it issues anything. Where one site still deploys the product branch, step 3 comes last, at go-live step 3, after step 4's keys.

1. **The owner adds the zone and checks the imported records against the current DNS** (the apex, every subdomain, mail and verification records), adding any the scan missed, and sets every imported A, AAAA and CNAME record to DNS-only unless the table below allows that host behind the proxy, since Cloudflare proxies them by default when a domain is added in the dashboard ([proxy status](https://developers.cloudflare.com/dns/proxy-status/)); **turns DNSSEC off at the registrar if it is on**, since changing nameservers with it active can make the domain unreachable; **then changes the nameservers and waits until the zone shows active.** DNSSEC goes back on from the new provider afterwards ([Cloudflare's setup](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/)). With the host's own DNS instead, the same order holds up to DNSSEC, which Netlify DNS does not support: it stays off, and keeping it means external DNS ([Netlify](https://docs.netlify.com/manage/domains/troubleshooting-tips/)).
2. **The email and identity-provider records**, exactly as each vendor lists them and DNS-only, until each vendor shows them verified (`transactional-email`, `clerk-production`).
3. **The host's custom domain, on the site that will serve production.** Repointing a record that already serves something (the apex, `www`, a host the owner's site or mail uses) waits for the owner's go. A production site of its own takes the domain now. Where one site still deploys the product branch on development values, attach it in go-live step 3, once the fresh production deploy is the one serving (`release-gate`, `references/go-live.md` and `references/netlify.md § The site`): attached earlier, strangers who find the domain sign up into development. Add the records the host lists, DNS-only where the table below says so ([Netlify with external DNS](https://docs.netlify.com/manage/domains/configure-domains/configure-external-dns/): when the domain is the apex or `www`, Netlify adds both, so both need records). The certificate follows once the records verify; Railway documents it within an hour. (`2026-10-28`, a monitoring product: Netlify's came within the hour.)
4. **Then production's keys on the host, at `release-gate`'s go-live step 3 and not before**: after the product branch is pinned to development values and the production branch exists, because until then a push to the product branch deploys to production (`release-gate`, `references/go-live.md`). Then a fresh deploy; the owner deletes the setup's own secret keys once the rest of go-live's done-when is checked (`release-gate`, `references/go-live.md` step 5), since reading the first account back in the identity instance needs a secret key. Production identity keys refuse sign-in on any host but the configured domain (`clerk-production`, `references/gotchas.md`), so sign-in is checked on the domain once its certificate is issued.

**A hostname minutes old fails for some third parties.** A webhook registration or a vendor's verification right after the record was made can fail to resolve for twenty minutes or so: retry it on a timer rather than debug it. A resolver that asked for the name before it existed keeps that "no such name" answer for the zone's negative TTL. (`2026-10-28`, a monitoring product: a chat platform's webhook registration failed for about twenty minutes after its hostname was created, and one customer's resolver held a negative answer for an hour.)

## Proxy or DNS-only, host by host

Keep one table in the environments doc: every hostname, whether it goes through the proxy, and why ([proxy status](https://developers.cloudflare.com/dns/proxy-status/)).

| Host | Through Cloudflare's proxy? | Why |
|---|---|---|
| Netlify | No, DNS-only | Netlify does not support it: no certificate provisioning behind it, and a cache that outlives a deploy. So the app gets no proxy WAF and no origin seal; flood limits are Netlify's rate limiting, and only Netlify's client-IP header is trusted (`release-gate`, `references/netlify.md`) |
| Railway | Either | Proxied, it needs the SSL/TLS mode **Full**: Railway says Full (strict) "will not work as intended". A nested subdomain must be DNS-only unless the zone has Cloudflare's Advanced Certificate Manager ([Railway's domains](https://docs.railway.com/networking/domains/working-with-domains)) |
| A server of your own, with a valid certificate | Either | Proxied, Full (strict) ([SSL modes](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/)). Moving it to a new server: the new one has its certificate and reads ready before the record moves (`release-gate`) |
| The email, identity-provider and verification records | No, DNS-only | the vendor's records, exactly as listed |

- **The SSL/TLS mode is one setting for the whole zone** unless a configuration rule sets it for a hostname, so a zone holding both a Railway service and a server of your own needs that rule.
- **A proxied host is what makes the origin seal possible** (`app-lifecycle`, `references/capabilities.md § Proxy WAF + origin seal`).
- **A proxied hostname can get the zone's own `robots.txt`** (a DNS-only host, Netlify included, serves the origin's file untouched, because its traffic never passes through the proxy). With Bot Preference Sync on and an AI crawler policy set to block, Cloudflare prepends its managed lines to the origin's file, or serves its own where the origin has none ([managed robots.txt](https://developers.cloudflare.com/bots/additional-configurations/managed-robots-txt/)). Its training disallow names `Google-Extended` among the AI crawlers, and that token also governs grounding in Gemini Apps, so the site drops out of those answers too ([Google's crawlers](https://developers.google.com/crawling/docs/crawlers-fetchers/google-common-crawlers)). After the nameservers change, read the served file on every proxied host (`curl -s https://<host>/robots.txt`), not the repository's, and keep the block only if the owner meant it; the owner turns it off in the dashboard. (`2026-10-29`, a developer-tool product: the served file opened with that block while the repository's said everything may be crawled.)

## Before the first users

- [ ] Every token belongs to one environment, is scoped as above and recorded; the time-boxed ones are revoked, and the identity provider's CLI is signed out (§ Who holds what).
- [ ] The secret keys made for the agent's setup are deleted; where it used the app's own, those are rotated, every holder updated (`variables.md § Rotating`).
- [ ] Every secret on the host is marked secret, above all the generated keys that can't be replaced (`variables.md`).
- [ ] The operator `.env` files have a copy in a password manager, not only on one machine: a holder like any other, never a place a command runs, listed in the copies table and updated at every rotation (`variables.md § Where every copy lives`).
- [ ] On every proxied hostname, the served `robots.txt` says what the owner meant (§ Proxy or DNS-only).
- [ ] An external monitor watches `/health` and the identity provider's sign-in host (`release-gate`, `references/go-live.md`; `clerk-production`, `references/gotchas.md`).
- [ ] What the defaults leave open is decided by the owner, not left, and each change below is applied on the owner's go: on proxied hostnames, a minimum TLS version of 1.2, HTTPS forced, and HSTS, with a short max-age first and no `includeSubDomains` or preload until every subdomain serves HTTPS, because a browser enforces it for the whole max-age (a DNS-only host sends its own: read the served header first); a CAA record only once it names every authority that issues for the domain (the host's, the proxy's, the identity provider's subdomains), since one left out stops that certificate renewing; DNSSEC, where the DNS provider signs the zone, whose DS record the owner adds at the registrar; DMARC past `p=none` once every sender is aligned and mail flows (`transactional-email`); TLS to the database enforced (`supabase-production`, `references/gotchas.md`). (`2026-10-28`, a monitoring product's account of its setup: minimum TLS 1.0, HTTPS not forced, no HSTS, no CAA record, DNSSEC off and DMARC at `p=none`, all left at their defaults.)

**From the first promotion on** (go-live step 3), production changes only on the owner's go: migrations, deploys, configuration (`release-gate`). Before it, the agent's production writes are the setup go-live step 1 lists. Development stays the agent's to change while nobody else depends on it (`supabase-production`, § Applying a migration). Before hosted CI or a second operator, the operator files get a copy in a password manager and each operator tokens of their own; CI gets development-only tokens, and production's operator secrets never reach CI (`variables.md § Setting values on the host`).
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall