The HubSecrets & Vaults

Secrets

Keep every secret the hub holds in one vault that only the hub can read:

factory.infra.ts
import * as claude from "@notation/factory-claude";
import * as cloudflare from "@notation/factory-cloudflare";
import * as github from "@notation/factory-github";
import { sources } from "@notation/std/resources";

const vault = new cloudflare.Vault("vault"); // <-- 1. where the hub's secrets live

const router = new cloudflare.Router("router", { vault });

const gh = new github.Connection("gh", { org: "acme", router });
new github.CodeHost("github", { connection: gh, allow: [{ owner: "acme" }] });

new github.OperatorAuth("operators", { connection: gh, users: ["djgrant", "alice"] }); // <-- 2. who may run the CLI against the hub

const claudeToken = new sources.Env("claude-oauth-token", {
  config: { key: "CLAUDE_CODE_OAUTH_TOKEN", track: "scrypt" }, // <-- 3. read from your environment at deploy
});

const claudeAccount = new claude.Account("claude", {
  auth: vault.secret({ id: "claude-oauth-token", value: claudeToken.credentials.value }),
});

new cloudflare.Deployer("deployer", { router, vault, accounts: [claudeAccount] });

A Notation Factory instance has secrets in three places: your machine, the hub (Router and Deployer), and each outpost container. This page explains what each place holds, how each secret gets there, and who can read it.

Where secrets live

PlaceHoldsWho reads it
LocalYour container provider sign-in, your gh login, account secrets such as CLAUDE_CODE_OAUTH_TOKENfactory on your machine
Hub vaultFACTORY_ROOT_KEY, each connection's credentials (GitHub App private keys and client secrets, Slack bot tokens and signing secrets), account secretsThe Router, the Deployer, or both, depending on the secret. See Who binds each secret
OutpostIts FACTORY_CONTAINER_KEY, the secrets of the accounts whose runtimes it lists, the outpost secrets that allow its repo, short-lived code host tokens the router mintsThat container; agents get the minted tokens, account secrets and outpost secrets

The hub vault is write-only from outside the hub. factory infra up writes a secret's value to the vault's store, and never reads one back. Holding the container provider's credentials lets you replace the hub's secrets, not read them.

The root key

FACTORY_ROOT_KEY is a random key. The router declares it as a RandomKey resource from @notation/factory, so factory infra up generates it when it creates the key, writes it to the vault, and then forgets it. Every other secret Notation Factory makes is derived from it with HMAC, so the hub stores one key instead of many:

FACTORY_ROOT_KEY
 ├─ container key   HMAC(root, repo + container)               container ⇄ router, both directions
 ├─ webhook secret  HMAC(root, "github:webhook:" + App id)     GitHub ─▶ router
 ├─ admin key       HMAC(root, "admin")                        router ⇄ deployer
 ├─ session key     HMAC(root, "operator:session")             signs operators' admin sessions
 └─ internal key    HMAC(root, "cloudflare:…")                 Cloudflare Workers' private routing (*.factory.internal)

Neither the router nor the deployer stores a derived key. Each derives the key where the root key is bound, when it needs it. For example, the router derives gh's webhook secret to verify a webhook, and derives a container's key to verify that container's request for credentials.

The deployer gives each container its own FACTORY_CONTAINER_KEY when it deploys the container. A container can only sign as itself, so it can't impersonate another container.

Platforms that issue their own signing secret, such as Slack, keep it in the vault as part of the connection's credentials instead of deriving one.

The sync key

At the end of every factory infra up, deploy asks the router to sync: the router points each connection's platform at itself, such as the GitHub App's webhook, and then deploys every repo again. Deploy signs this request with the sync key, so that factory infra up doesn't need an operator to sign in.

The sync key is a random key, apart from the root key. The router declares it as a RecordedKey resource from @notation/factory. Unlike the root key, its value is recorded in Notation state, so every deploy can sign with it. Deploy never records the root key's value, and would have to rotate the root key to get it again. The router keeps the sync key in the vault's store, and binds it as FACTORY_SYNC_KEY.

The request carries the time it was made and an HMAC, with the sync key, of that time and the router's origin. A captured request works only for that router. The router refuses a request whose signature doesn't match, or whose time is more than 5 minutes from its own clock. Anyone who can read the hub's Notation state can sign a sync. A sync only does what factory infra up does anyway, and reveals no secrets.

The hub vault

The vault is a Vault from the hub's provider plugin. vault.secret(...) declares a secret in it, and gives the secret its value. Declaring a secret doesn't give anything access to it. The router or the deployer binds the secret to its own Worker or service, under a name it chooses.

Credentials

A secret's value is a Notation credential: an output of another resource that deploy holds in memory, and that state records only as a marker. vault.secret(...) takes these fields:

FieldMeaning
idKeys the secret in Notation's state
valueA credential, such as claudeToken.credentials.value or token.credentials.Value

A credential comes from one of two kinds of resource:

KindExampleWhere the value comes from
A sourcesources.Env, sources.Dotenv from @notation/std/resources, InfisicalSecret from @notation/infisical/resourcesA place outside Notation, such as the environment variable CLAUDE_CODE_OAUTH_TOKEN
A resource that issues itThe router's RandomKey, a GitHub App, a Slack app, the deployer's API tokenThe provider returns it when it creates the resource

For example, github.Connection passes its App's private key to the vault, and binds the secret to the router:

const privateKey = router.bind(          // <-- returns the binding name, here GH_PRIVATE_KEY
  router.vault.secret({
    id: "gh-private-key",
    value: app.credentials.privateKey,   // <-- GitHub returns it when it creates the App
  }),
);

The key goes from the App to the vault in the deploy's memory. No one copies it by hand.

router.bind(secret, name?) binds the secret to the router's Worker or service, and returns the binding name. Without name, the binding name is made from the secret's id with bindingName(id) from @notation/factory. bindingName makes the id upper case, and replaces each character other than a letter, a digit or _ with _. If the result starts with a digit, it adds _ in front. For example, gh-private-key becomes GH_PRIVATE_KEY. A connection records the binding names in its entry in the router's config.

The factory doesn't choose the secret's name in the store. The vault's provider makes a name scoped to the Notation app and stage, so two stages of one hub keep separate secrets:

ProviderVaultEach secret isName in the store
Cloudflarecloudflare.VaultA secret in the account's Secrets Store. Values can't be read back through the API. Workers read it through a secrets_store_secret binding<app>--<stage>--secret-<id>-<instance>, where Notation generates the 8 hex characters of the instance
Railwayrailway.VaultA sealed shared variable in the router's project. Values are never shown in the dashboard or returned by the API. A service reads it through a variable named after the binding name, whose value is ${{shared.<name>}}<app>__<stage>__<id>, with characters other than letters, digits and _ replaced by _

The vault and the hub are always on the same provider. cloudflare.Router and cloudflare.Deployer take only a cloudflare.Vault. A vault elsewhere would need its own access credential, and that credential would have to live in the hub provider's store anyway.

When a value is written

Deploy writes a secret when it creates it, and again when the credential has a new version:

Credentialfactory infra up writes the secret
sources.Env or sources.Dotenv without trackOn every deploy. The variable must be set on every machine that deploys
sources.Env or sources.Dotenv with track: "scrypt"When the value changes. State holds a salted hash of the value
The router's RandomKeyOnce, when it creates the key
A GitHub App's private key and client secret, a Slack app's tokensOnce, when it creates the App
The deployer's API tokenOnce, when it creates the token

The example at the top of this page sets track: "scrypt" on the Claude token, because the token is generated and can't be guessed from its hash. For a value that a person chose, use track: "hmac" with NOTATION_TRACK_KEY. See Notation's Secrets page.

A credential that deploy can't get again

Deploy holds a value only in the process that received it. When a secret needs a value that an earlier deploy received, deploy has to get it again. For example, the Secrets Store secret was deleted in the dashboard, or a deploy failed after it created the App and before it wrote the secret. What deploy does depends on the credential:

CredentialDeploy
A sourceReads the value from the source again
The router's RandomKeyRotates it: makes a new value, and writes every secret that holds it
A GitHub App's private key or client secret, a Slack app's tokens, the Railway deployer's tokenFails, because the provider has no API that issues another value

For the last row, plan and deploy fail and print two commands. One command passes a value that you issue at the provider, such as a private key that you generate on the GitHub App's settings page:

notation deploy --stage prod --credential gh-app.privateKey@<version>=GH_PRIVATE_KEY

The other command replaces the resource, which creates a new App. See notation deploy. factory infra up passes --credential on to Notation, so you can run factory infra up --credential … instead.

The secrets in the vault

For the example at the top of this page, the vault holds these secrets:

Secret idBinding nameDeclared byBound byValue from
router-root-keyFACTORY_ROOT_KEYRouter, as router.rootKeyRouter and deployerThe router's RandomKey
router-sync-keyFACTORY_SYNC_KEYcloudflare.Router, as router.syncKeyRouterThe router's RecordedKey
gh-private-keyPRIVATE_KEYgithub.ConnectionThe connection's channelThe App, app.credentials.privateKey
gh-client-secretCLIENT_SECRETgithub.ConnectionThe connection's channelThe App, app.credentials.clientSecret
slack-bot-token, slack-signing-secretSLACK_BOT_TOKEN, SLACK_SIGNING_SECRETslack.Connection, if the hub has oneRouterThe Slack app, botToken and signingSecret
deployer-builds-tokenCLOUDFLARE_BUILDS_TOKENDeployerDeployerThe builds token, which you paste on a local page during the first factory infra up
claude-oauth-tokenCLAUDE_CODE_OAUTH_TOKENYou, in the account's authDeployersources.Env

A connection's secret ids start with the connection's id, and the router makes each binding name from the id. So several connections of one provider each get their own bindings. For example, connections with the ids gh and personal bind GH_PRIVATE_KEY and PERSONAL_PRIVATE_KEY.

The deployer binds an account's secrets under the env var names that the account gives them, such as CLAUDE_CODE_OAUTH_TOKEN. The secret's id is yours to choose.

Who binds each secret

Each Worker or service binds only the secrets it uses:

SecretRouterDeployer
FACTORY_ROOT_KEYBound by the routerBound by the deployer
FACTORY_SYNC_KEYBound by the routerNot bound
Connection credentialsBound by each connection, with router.bind(...)Not bound
The deployer's provider tokenNot boundBound by the deployer
Account secretsNot boundBound by the deployer, for each of its accounts
Outpost secretsNot boundBound by the deployer, for each of its secrets

The router never binds an account's secrets, and the deployer never binds a connection's credentials. A leak of one Worker or service therefore exposes only the secrets it binds, plus the root key.

On Cloudflare, a binding is a secrets_store_secret entry in the Worker's Bindings. On Railway, it is a variable on the service.

The deployer's provider token

The deployer has a provider token of its own, which it owns as a resource and keeps in the vault:

ProviderTokenThe deployer reads it as
CloudflareThe builds token, a user API token with the seven permissions that factory infra up fills in on Cloudflare's create-token pageCLOUDFLARE_BUILDS_TOKEN
RailwayA project tokenRAILWAY_TOKEN

Losing the vault

The vault's secrets belong to the hub's Notation stage, so factory infra down deletes them along with the router and deployer. On Cloudflare, every hub on the account shares the account's one Secrets Store. The first hub creates the store, and each later hub uses it. factory infra down deletes only the hub's own secrets, by their <app>--<stage>-- names, and leaves the store and the other hubs' secrets. When you bring the hub up again, or move it to another provider:

  • factory infra up generates a new root key, and the router re-derives every webhook secret and container key.
  • The GitHub Apps survive, but deploy doesn't hold their private keys or client secrets. Generate a new private key and a new client secret on each App's page, and pass them with --credential.
  • For a Slack app, pass its bot token and signing secret with --credential.
  • Account secrets are written again from their sources.

Local credentials

factory infra up and factory infra down create, update and delete the hub, so they authenticate with your own credentials:

StepCredential
Create and deploy the hub on Cloudflarenpx wrangler login, or CLOUDFLARE_API_TOKEN (e.g. in CI). See Providers for the permissions that CLOUDFLARE_API_TOKEN needs
Choose the deployer's Cloudflare accountCLOUDFLARE_ACCOUNT_ID, or accountId on cloudflare.Deployer
Create and deploy the hub on RailwayRAILWAY_API_TOKEN
Create a GitHub App or Slack appYour browser, through the platform's manifest flow
Calls to GitHub as you, e.g. factory repo installYour gh login
Write account secrets to the vaultThe account's source, e.g. CLAUDE_CODE_OAUTH_TOKEN in your environment for sources.Env

The infra commands check each one before they start, and their messages name the credential that's missing or refused.

You can load them at startup with loadEnv in factory.config.ts, beside factory.infra.ts:

factory.config.ts
export default {
  loadEnv: "./with-env.sh", // <-- every factory command adopts the environment this sets
};

loadEnv is a command prefix: ./with-env.sh stands for any command that sets variables and then runs the command after it, such as your secret manager's CLI. factory runs it once when it starts and takes on the environment it sets, so your terminal stays attached.

Operator auth

Commands that talk to a running hub sign you in as an operator instead of using the root key: factory infra status and factory infra replay. factory infra up doesn't sign you in. It uses the sync key. The router checks who you are and returns an admin session, signed with a key derived from the root key, that lasts 4 hours. The router also checks that the session's operator is still in the operator auth on each request, so removing an operator ends their session. factory infra status and factory infra replay need no provider credentials at all. See Operator sign-in.

The router keeps no list of sessions, so it can't revoke one session. If an admin session leaks, whoever holds it can use it until it expires, for up to 4 hours. To end it sooner, remove its operator from the operator auth and deploy, which ends all of that operator's sessions, or rotate the root key, which ends every session.

Operators are not the code host's allow list. allow on CodeHost decides whose repos get outposts. Operators are the people allowed to run the CLI against the hub.

Each OperatorAuth decides who you are differently:

OperatorAuthYou sign in withWho decides access
github.OperatorAuthGitHub, through the connection's App, in your browserThe router, against users, which lists GitHub logins or account IDs
cloudflare.OperatorAuthCloudflare Access, in your browserCloudflare Access, against emails; the router verifies Access's token. The router can't sign operators in this way yet

Signing in with GitHub

github.OperatorAuth uses GitHub's web flow for the connection's App:

  1. The CLI asks the router for GitHub's sign-in page, and opens it in your browser.
  2. You authorize the App. GitHub sends your browser to http://127.0.0.1:47219/callback with a code, where the CLI listens.
  3. The CLI sends the code to the router. The connection's channel exchanges it for a user token with the App's client secret, reads your login and account ID with the token, and revokes the token.
  4. The router checks your login and ID against users, and returns the admin session. A login entry matches without case. An ID entry, a number, matches your account ID.

List operators by account ID where you can. A GitHub user can rename their account, and someone else can then register the old login. A login entry would let that person in. An ID entry keeps matching the same account after a rename. https://api.github.com/users/<login> shows a user's id.

The App needs two things for this, which Factory sets up when it creates the App:

  • The client secret, in the vault as <connection>-client-secret, which only the connection's channel binds.
  • The callback URL http://127.0.0.1:47219/callback. GitHub only sends the browser to an App's callback URLs, port included.

To use Cloudflare Access instead of GitHub:

factory.infra.ts
// …
new cloudflare.OperatorAuth("operators", { router, emails: ["dj@acme.dev", "alice@acme.dev"] });

Platform operations that need a connection's credentials run in the router, which has them: for GitHub, reading the App's settings, and reading and setting its webhook. factory infra up asks the router to do them, with the sync key.

Short-lived tokens

The router turns the code host's App private key into short-lived GitHub installation tokens, so nothing outside the hub holds a long-lived GitHub credential:

Token forAsked for byUsed to
A container's policiesThe container, signing with FACTORY_CONTAINER_KEYPush branches, open PRs, and whatever else its Policy grants. The container installs them in files only its own user can read, and agents use them
The deployerThe deployer, signing with the admin keyRead .factory/ from a repo, and write FACTORY_STATUS

A container refreshes its tokens when fewer than 30 minutes remain. A code host that can't mint tokens limited to one repo and short-lived fails the deploy of any repo whose policies need them.

Containers get no channel credential. They read and reply on a conversation through the router's channel relay, signing with FACTORY_CONTAINER_KEY.

Outposts

Outposts declare no secrets of their own. The deployer gives each container its FACTORY_CONTAINER_KEY when it deploys it, stored as the provider's own secret (a Worker secret on Cloudflare, a sealed variable on Railway). When a run starts, the deployer reads these through its own bindings and passes them to the container as env vars:

  • the secrets of every account whose runtime the container lists
  • the outpost secrets that allow the container's repo

A container that lists only claude.runtime, in a repo that no outpost secret allows, gets the Claude account's token and nothing else.

Agents never see FACTORY_CONTAINER_KEY or any provider's private variables. They see the minted tokens, the account secrets and the outpost secrets.

Outpost secrets

An OutpostSecret from @notation/factory is a secret that the hub holds for the containers of some repos, such as a database URL that an agent needs. Declare it in factory.infra.ts, and pass it to the deployer:

factory.infra.ts
import { OutpostSecret } from "@notation/factory";
// …
const databaseUrl = new sources.Env("web-database-url", {
  config: { key: "WEB_DATABASE_URL", track: "hmac" },
});

const webDatabase = new OutpostSecret("web-database-url", {
  name: "DATABASE_URL",                       // <-- 1. the env var name containers read it as
  value: databaseUrl.credentials.value,       // <-- 2. a credential, as for vault.secret
  allowedRepos: [{ owner: "acme", repo: "web" }], // <-- 3. the repos whose containers get it
});

new cloudflare.Deployer("deployer", { router, vault, accounts: [claudeAccount], secrets: [webDatabase] });

allowedRepos has the form of the code host's allow: a pattern without repo allows every repo of its owner. The deployer writes the value to the vault as the secret outpost-<id>, and binds it as OUTPOST_<id>, made with bindingName. Every container of an allowed repo gets it, whatever its runtimes.

factory infra up fails if a container could get two values for one env var: two outpost secrets with the same name whose allowedRepos overlap, or an outpost secret with the name of an account's secret.

The agents in those containers can read the value, so give an outpost secret no more access than you would give the agents. For a database, that's a role with only the privileges the agents need.

Topology

Taken together, secrets flow one way, from your machine into the vault and from the vault out to services and containers:

 LOCAL                               HUB                                        OUTPOST
 ─────                               ───                                        ───────
 provider sign-in ──infra up──▶ creates and deploys Router, Deployer, Vault
 browser ───────────infra up──▶ creates GitHub App, Slack app
 CLAUDE_CODE_OAUTH_TOKEN ──── from its source ──┐
 App keys, tokens ──── from their resources ────┤ written, never read back
                                                ▼
                               ┌─────────────────────────────┐
                               │ Vault                       │
                               │   FACTORY_ROOT_KEY          │
                               │   connection credentials    │
                               │   account secrets           │
                               └──────┬───────────────┬──────┘
                        root key and  │               │ root key and
                        connections   ▼               ▼ accounts
 GitHub, Slack ──events────────▶ Router ◀─admin key─▶ Deployer ──deploys──▶ Container
        (signed)                  ▲   │                                       FACTORY_CONTAINER_KEY
                                  │   │                                       account secrets
 operator sign-in ──session───────┘   ├──minted tokens, on a request ───────▶ token files
                                      │  signed with the container key
                                      └──channel relay ◀──────────────────── replies