> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tuturuuu session auth Worker keys

> Slice 4 key publication for the first-party Tuturuuu session: the pinned key guard and its emergency list control record, the observer, the deployment provenance rules, the binding inventory, the Cloudflare API budget, the publication census and the observation cache.

**Status: design, pending independent security review.** This page completes
[Tuturuuu session auth Worker](https://docs.tuturuuu.com/platform/architecture/tuturuuu-session-auth-worker.md)
for slice 2a's key publication rules on
[Tuturuuu session token signer](https://docs.tuturuuu.com/platform/architecture/tuturuuu-session-token-signer.md).
Release-authority acceptances and APEX dependencies are collected on
[auth Worker controls](https://docs.tuturuuu.com/platform/architecture/tuturuuu-session-auth-worker-controls.md#rollout).

## Key guard

Slice 2a requires the emergency list to belong to a deploy identity other than
the one that writes `TTR_TOKEN_SIGNING_KEYS`. The guard runs in the platform
account, where Cloudflare's product-level Workers permissions cover every
script. The split therefore rests on script-scoped tokens, key-plane scripts
that take changes only from their own CI workflow, a trust anchor pinned in
reviewed source, and a control record written only through the security
operators' Access-gated Worker. An identity with Worker-wide rights in the
account, or a compromise of that workflow and its token, is the accepted
residual stated below.

* **Key-plane scripts.** Three dedicated scripts in the platform account,
  each with a separate staging script, built from `apps/auth-keyguard` with
  one Wrangler config per script. None has a `workers.dev` or preview URL,
  and the observer alerts if a live one does.
  * `tuturuuu-auth-keyguard`, the guard: serves the signed list on its pinned
    hostname and holds `GuardState`.
  * `tuturuuu-auth-keyguard-operator`, the keyguard operator Worker: the only
    path by which a security operator changes the emergency list or clears a
    halt.
  * `tuturuuu-auth-observer`, the observer below.
* **Script-scoped deploy tokens.** Cloudflare API tokens can be scoped to
  individual Worker scripts. The auth workflow's token is an editor on the
  `tuturuuu-auth` scripts only, and the gateway workflow's token is an editor
  on `tuturuuu-gateway` only. `keyguard-cloudflare.yaml` deploys the
  key-plane scripts, one job per script, with
  `CLOUDFLARE_KEYGUARD_DEPLOY_TOKEN`, `CLOUDFLARE_KEYGUARD_OPERATOR_DEPLOY_TOKEN`
  and `CLOUDFLARE_AUTH_OBSERVER_DEPLOY_TOKEN`, each an editor on its one
  script. Each script has its own GitHub environment per stage:
  `keyguard-guard-staging`, `keyguard-guard-production`,
  `keyguard-operator-staging`, `keyguard-operator-production`,
  `keyguard-observer-staging` and `keyguard-observer-production`. Each holds
  only its script's deploy token and the App key below, so a job never sees
  another script's token. Every keyguard environment allows deployments
  from the `main` branch only, requires a security operator as reviewer,
  refuses self-review, and has administrator bypass turned off.
  `keyguard-cloudflare.yaml` triggers on `push` to `main` only.
  No steady-state CI deploy identity spans `tuturuuu-auth` and the gateway,
  or `tuturuuu-auth` and a key-plane script.
* **CI-only key plane.** After its creation run, each key-plane script takes
  every change, code, variable, secret and rollback, only from its own job in
  `keyguard-cloudflare.yaml`, the rule `tuturuuu-auth` follows with
  `auth-cloudflare.yaml`. The job builds the script, uploads the build
  manifest (each module's name and SHA-256) as the run artifact
  `keyguard-<script>-manifest`, uploads a version without traffic, records
  the version id, script and commit in a GitHub deployment for that script's
  environment with an `in_progress` status, deploys the version to 100% of
  traffic in one step, and then sets the status to `success`. The deployment
  and both statuses are written as the keyguard deployer App below, and each
  status's `log_url` names the run and its attempt.
  * **API fields.** The App creates each deployment with `auto_merge: false`,
    `required_contexts: []`, the script's environment name and an explicit
    `production_environment` (`true` for production, `false` for staging),
    so GitHub neither merges a branch nor waits on status checks. It writes
    every status with `auto_inactive: false`, so a new `success` never makes
    GitHub mark the previous deployment `inactive`.
  * **Verification.** The observer's [key-plane check](#observer) verifies
    that record for every version with traffic. A retry or a rollback is a
    new commit on `main`, such as a revert, never a re-run, a dispatch or a
    redeploy of an earlier version.
* **Keyguard deployer App.** The GitHub App `tuturuuu-keyguard-deployer`,
  installed on this repository only with Deployments write and no other
  write permission, is the only identity that writes key-plane deployment
  records. Its private key `TTR_KEYGUARD_DEPLOYER_APP_PRIVATE_KEY` is an
  environment secret of the keyguard environments only, and each job mints
  an installation token from it after the environment's approval. No other
  workflow or person uses the App. `apps/auth-keyguard/deploy-identities.json`
  pins its App id and bot user id. A record created by
  `github-actions[bot]` through `GITHUB_TOKEN`, or by any other actor, never
  counts, whatever its payload says.
* **Qualifying run.** A run of `keyguard-cloudflare.yaml` qualifies for a
  key-plane script only when the GitHub Actions run API reports, for the run
  id and attempt read from the App's status `log_url`: workflow path
  `.github/workflows/keyguard-cloudflare.yaml`, `event` `push`,
  `head_branch` `main`, `head_sha` equal to the deployment's commit, and
  `run_attempt` 1, which is the attempt that uploaded the version; and the
  jobs API reports that attempt's job for that script with its deploy step
  completed. A `workflow_dispatch`, including one with ref `main`, a re-run,
  a run on another branch, and a run that never reached the deploy step do
  not qualify. The run id is never read from the deployment payload.
* **User tokens.** A member may deploy a script other than `tuturuuu-auth`
  and the key-plane scripts with a short-lived user API token minted with the
  cf CLI. It is scoped to the scripts the deploy changes where Cloudflare
  allows it, expires within 24 hours, and is entered in the credential ledger
  with its token id, owner, scripts, permission groups, expiry and purpose
  before its first use. After their creation runs, `tuturuuu-auth` and the
  key-plane scripts take changes only from their CI jobs, so no user token
  deploys them, and the audit alert treats any such use as positive. A user
  token that needs a Worker-wide grant is minted only under a creation waiver
  below, names that waiver in its ledger entry and expires no later than the
  waiver.
* **Credential ledger.** An append-only store in security-operator custody,
  outside the platform Cloudflare account and outside this public repository,
  because its entries name members. The store stamps each entry's
  `recordedAt` with its own clock, and no writer supplies it. Security
  operators append entries; the audit alert workflow has read-only access.
  The audit alert raises a positive alert when a ledgered token's event comes
  before its entry's `recordedAt` or after its expiry, and an entry whose
  expiry is more than 24 hours after its `recordedAt` never counts. The
  24-hour cap and the scopes are ledger fields: neither the observer nor the
  audit alert can list a user token, so neither can verify a token's real
  lifetime or scope.
* **Global API keys.** No deploy, CI job or Worker uses a Global API key.
  Each member's key is disabled where the account allows it, and otherwise
  rolled and left unused. The audit alert reads `actor.context` `api_key` as
  a Global API key and alerts on any watched change made with one.
* **Creating a script.** A per-Worker role cannot create a Worker or be
  granted on one that does not exist yet; creation needs product-level
  Workers Admin, which covers every Worker. Each script is created under a
  time-bounded release-authority waiver (id, scope, expiry) that grants that
  Admin to one creation run and is removed before any auth version receives
  traffic. The creation run for `tuturuuu-auth`, or for any later new Worker
  outside the key plane, may use the waiver's CI token or a ledgered user
  token that names the waiver. A key-plane script's creation run may use
  only its own `keyguard-cloudflare.yaml` job, in a qualifying run, with the
  waiver's CI token; no user token creates a key-plane script. Each waiver
  is published as a commit reachable from `main` with its id, scope and
  expiry; the
  observer ignores any other waiver.
* **No standing Worker-wide grant.** A grant is Worker-wide when it can
  upload, put a secret on or deploy any Worker beyond one script, that is,
  when its resource scope is the Workers product, the developer platform or
  the account, and its permission group is any Admin or Editor that covers
  Workers: Workers Admin, Workers Editor, Developer Platform Admin, Developer
  Platform Editor, legacy Workers Platform Admin, Workers Scripts Edit,
  Workers Scripts Write, Workers CI Edit, Workers Observability Edit or
  Workers Observability Telemetry Edit. The account role `Administrator`, on
  `roles[].name` or as an account-scoped policy permission group, is
  Worker-wide too, as is its legacy alias `Account Administrator` where a
  payload still emits it. Role and permission group names match as the full
  string, so `Administrator Read Only` and other read roles never count.
* **Effective access.** Each policy has one scope, and an identity's access is
  the union of its policies. For each member the observer unions its direct
  policies with the policies of every user group it belongs to, and for each
  account token it takes all of its policies, before classifying. If the
  union of an identity's resources for any permission that can upload, put a
  secret or deploy covers a `tuturuuu-auth` script together with
  `tuturuuu-gateway` or any key-plane script, the identity is Worker-wide,
  because it breaks the disjoint deploy split. Read-only permissions never
  count, so the observer's and the census's own read tokens are never
  Worker-wide.
* **Grant check.** Every 5 minutes the observer reads the account members
  (`roles[]`, and `policies[].permission_groups` with their
  `resource_groups`), the user groups' policies, and the account-owned API
  tokens' policies. Any Worker-wide grant outside an open waiver sets
  `identityBlocked`, so identity minting stops until it clears. A run counts
  as a successful read only when every page of members, user groups and
  account tokens was read. A cap fails the run only when a page remains
  unread; an unread page or an error is a failed read, which keeps the last
  `identityBlocked`, alerts and does not move the success time. When the last
  successful read is older than 15 minutes it sets `identityBlocked`. User
  API tokens and Global API keys cannot be listed through the account, so the
  observer cannot classify them: the ledger and Global API key rules above
  govern them, and the audit alert reports their use outside those rules.
  Only the `Super Administrator - All Privileges` role is exempt: it can edit
  every Worker and is never blocked, because that would stop minting
  permanently, and it is a standing residual the release authority accepts.
* **State.** One `GuardState` Durable Object per environment holds
  `{ listVersion, kids, mintHalt, gatewayVersions, identityBlocked }`.
  `gatewayVersions` is the set of gateway version ids the observer accepted
  below, kept as a sorted array, and `identityBlocked` marks the identity
  class unusable. Every change increments `listVersion` in the same
  transaction: a security operator arming or removing an emergency `kid` or
  clearing a halt, the observer setting the halt, accepting or dropping a
  gateway version, or changing `identityBlocked`. Only a security operator
  clears a halt.
* **Document.** `GET /<env>` returns `{ payload, keyId, sig }`. `payload` is
  the base64url of the canonical bytes (RFC 8785 JSON) of
  `{ env, kids, listVersion, mintHalt, gatewayVersions, identityBlocked, issuedAtMs }`, and `sig` is Ed25519
  over exactly those bytes with `TTR_TOKEN_EMERGENCY_LIST_KEY`. The guard
  stamps `issuedAtMs` at response time and signs every response afresh, so a
  successful fetch always yields a fresh document and a halt the guard is
  still serving never lapses. Every response carries
  `Cache-Control: no-store`. The guard serves no other public path.

### The emergency list control record

The emergency list and the halt live only in `GuardState`, never in KV, a
variable or a secret, which any editor of a binding script could attach or
change. The guard accepts writes only through two `WorkerEntrypoint` classes
with closed method sets:

| Entry point | Bound by | Caller key | Methods |
| - | - | - | - |
| `OperatorEntry` | `tuturuuu-auth-keyguard-operator` only | `TTR_KEYGUARD_ENTRY_OPERATOR_KEY` | `armKid`, `removeKid`, `clearHalt`, `readState` |
| `ObserverEntry` | `tuturuuu-auth-observer` only | `TTR_KEYGUARD_ENTRY_OBSERVER_KEY` | `setHalt`, `acceptGatewayVersion`, `dropGatewayVersion`, `setIdentityBlocked` |

* **Keys checked inside the object.** Any Worker in the account can bind a
  named entry point or another script's Durable Object class, so neither
  binding proves its caller. Each entry passes the presented key into
  `GuardState`, which compares it in constant time with the guard's own
  secret, current value and at most one previous, before reading any other
  argument. A foreign service or Durable Object binding without the key gets
  `unauthorized` and changes nothing. Each key is 32 random bytes per
  environment, rotated in the auth Worker's caller-key order. The observer's
  key reaches no method that touches `kids` or clears a halt.
* **Security operators.** Two layers gate the operator Worker. The first is
  Cloudflare Access: the operator Access application, whose policy admits
  only the security operators group, covers every hostname of the Worker,
  and Worker-level Access stays enabled so a `workers.dev` or preview URL
  would be gated too, though none may exist. The second is inside the Worker
  and the guard: the operator Worker verifies the Access JWT for that
  application's audience on every request, and `GuardState` accepts its
  calls only with `TTR_KEYGUARD_ENTRY_OPERATOR_KEY`, held by the guard and
  the operator Worker only, so another Worker's binding to `OperatorEntry`
  changes nothing. Each write records the operator's Access identity and a
  reason in an append-only log in `GuardState`.
* **Slice 2a split.** The signing-key writer is the auth workflow's token, an
  editor on `tuturuuu-auth` only. The emergency list writer is the
  security-operator role, through the Access-gated operator Worker and its
  caller key. The guard and the operator Worker change only through their
  `keyguard-cloudflare.yaml` jobs, whose environments need a security
  operator's approval and whose tokens have no role on `tuturuuu-auth`.
  Neither writer has a role on the other's scripts, and the grant check
  blocks identity minting while a listed identity spans both. Any other
  write to the list needs one of the residuals below.

### Accepted residual

Because the guard runs in the platform account, a key-plane write by any path
other than the operator Worker needs one of two things:

* an identity with Worker-wide edit rights there: a
  `Super Administrator - All Privileges` member, an identity under an open
  creation waiver, or a Worker-wide user token; or
* a compromise of `keyguard-cloudflare.yaml` and the deploy token of the
  script it targets, such as a rewritten workflow on `main`, an approved
  deployment of a malicious commit on `main`, or a stolen token.

Either could redeploy `tuturuuu-auth-keyguard` with code that signs any list
with the key it already holds, arming an emergency `kid`, clearing a halt,
accepting a gateway version or clearing `identityBlocked`, or redeploy or
silence the observer. A Worker-wide identity could also change
`tuturuuu-auth` directly. The pin does not stop this, because the redeployed
guard still holds the pinned key. The compensations that keep the guard in
this account:

* dedicated scripts for the guard, its operator Worker and the observer, each
  deployed only from its own `keyguard-cloudflare.yaml` job with its own
  script-scoped token, in its own per-stage keyguard environment limited to
  `main` that needs a security operator's approval;
* deployment records written only by the keyguard deployer App and tied to
  a qualifying run through GitHub's own run API, with only the version on
  the latest App `success` deployment accepted, so an earlier attested
  version restored later is reported;
* the emergency list in a control record written only through the
  Access-gated operator Worker;
* the observer's key-plane check, which alerts on any key-plane version with
  traffic that lacks a matching GitHub deployment, so a CI token used outside
  its workflow is reported;
* the [audit alert](#audit-alert), which runs outside the observer's code and
  outside Cloudflare and raises a positive alert on any change to a
  key-plane script by an actor other than its CI token inside a qualifying
  run of its job, which also covers a redeployed observer hiding its own
  miss;
* the credential ledger and the grant check, which leave the
  `Super Administrator - All Privileges` role and open waivers as the only
  standing Worker-wide grants the observer accepts.

Detection follows the change. The response to an alert is to rotate the
guard's signing key through a pin change; rotate
`TTR_KEYGUARD_DEPLOYER_APP_PRIVATE_KEY` and the three key-plane deploy tokens
`CLOUDFLARE_KEYGUARD_DEPLOY_TOKEN`,
`CLOUDFLARE_KEYGUARD_OPERATOR_DEPLOY_TOKEN` and
`CLOUDFLARE_AUTH_OBSERVER_DEPLOY_TOKEN`, revoking the old values; redeploy
every watched script from `main`; and deny affected keys at the verifiers.

### The pin

* **In reviewed source.** `apps/auth/src/keys/key-guard-pin.ts` exports, per
  environment, the guard URL and its Ed25519 public keys as
  `{ current, previous? }`, each with its `keyId`. The signer reads no guard
  URL or key from its environment, so changing the pin needs a reviewed commit
  on `main` and a CI deploy, which the observer checks.
* **Rotation.** A security operator puts key K2 on `tuturuuu-auth-keyguard`
  as its next signing key through `keyguard-cloudflare.yaml`. A reviewed auth change sets
  the pin to `{ current: K2, previous: K1 }`, and CI moves that auth version
  to 100% of traffic. Only then does the guard sign with K2. When the guard
  has signed with K2 for 300 seconds and no auth version without K2 carries
  traffic, a reviewed change drops `previous`. A URL change follows the same
  order: the new hostname serves before the pin names it, and the old one
  keeps serving until no auth version with traffic names it.

### Accepting a list

The census cron fetches the document once per tick with `cache: 'no-store'`, a
2-second timeout and no retry, and stores the response bytes in
`KeyObservations`. Every isolate verifies the bytes itself with the pinned
keys; `KeyObservations` only stores and forwards them, so a writer of that
object cannot forge a list.

A document is valid only when its `keyId` names the pin's `current` or
`previous` key, `sig` verifies over the exact `payload` bytes, `payload` is
canonical JSON with the closed member set above and no duplicate members,
`env` equals `TTR_SESSION_ENV`, and `issuedAtMs` is at most 5 seconds ahead of
the isolate clock. Against the held list, a valid document:

| `listVersion` | Content | Result |
| - | - | - |
| Greater | Any | Replaces the held list |
| Equal | Every signed member except `issuedAtMs` the same, `gatewayVersions` compared as a sorted array | Refreshes the held list's `issuedAtMs` |
| Equal | Different | Rejected and alerted as a conflict |
| Lower | Any | Rejected and alerted as a rollback |

`KeyObservations` keeps the highest accepted `listVersion` durably and refuses
to store a lower one, and the observation snapshot carries the held document,
so a restart or a cold isolate never accepts an older list. A fetch error, an
invalid document, a conflict or a rollback keeps the held list in force until
its `issuedAtMs` is 300 seconds old by the isolate clock. Past that, the
signer's read view gives `kids` as empty and `mintHalt` as false, while the
stored document stays the input to the comparison above, so the next valid
equal document refreshes it and restores both fields. `gatewayVersions` and
`identityBlocked` keep their last held values: a guard outage never fails the
identity class for a gateway version already accepted, and never clears a
block. A new gateway version with traffic that has not been accepted fails the
identity class until the guard is back and accepts it, so a gateway deploy
during a guard outage stops identity minting; that stall is stated in the
release-authority list.

### Effect on the signer

* **`kids`.** The held list's `kids` is the value the host passes to slice 2a
  as `TTR_TOKEN_EMERGENCY_KIDS`: at most one `kid` per class that may skip the
  7-day wait, with slice 2a's rules. No auth Worker secret or variable
  carries it. An empty list removes only that skip, so a guard outage fails safe.
* **`mintHalt`.** While the held list carries `mintHalt: true`, `mintToken`
  refuses every class, identity included, and resolution answers
  `unavailable`, which the gateway turns into its retry result (see
  [auth Worker controls](https://docs.tuturuuu.com/platform/architecture/tuturuuu-session-auth-worker-controls.md#g8-stop-fence-modes)).
  The halt lives only in the held list, so it lapses when the guard stays
  unreachable for 300 seconds. Guard availability is a minting dependency only
  for accepting a new gateway version, as described above. The halt contains configuration drift under honest auth code.
  A deployed version whose code differs from `main` can ignore it; the
  observer reports that version, and the containment is key denial at the
  verifiers.

## Observer

The observer is `tuturuuu-auth-observer`, a dedicated cron Worker in the
platform account with its own read tokens and its own script-scoped deploy
token. It writes `GuardState` only through `ObserverEntry`. An identity with
Worker-wide rights could change or silence it, so the
[audit alert](#audit-alert) runs outside its code path.

* **Credentials.** `TTR_AUTH_OBSERVER_CF_READ_TOKEN`, a Cloudflare API token
  with Workers Scripts Read, Account Settings Read, Account API Tokens Read
  and Access: Apps and Policies Read on the platform account only (never
  Account Settings Write or SCIM
  Provisioning), created for a dedicated service user;
  `TTR_AUTH_OBSERVER_GITHUB_TOKEN`, read-only access to repository
  contents, deployments, Actions runs and artifacts; and
  `TTR_KEYGUARD_ENTRY_OBSERVER_KEY`. All three are
  observer secrets, and no other Worker holds the read tokens.
* **CI-only production deploys.** `auth-cloudflare.yaml` is the only path that
  changes production or staging `tuturuuu-auth`. It uploads a version without
  traffic (`wrangler versions upload`, or `wrangler versions secret put` for a
  secret change), records the version id and commit in a GitHub deployment for
  that environment, and only then deploys the version. A rollback deploys a
  recorded version. No person or agent deploys, edits a variable or puts a
  secret on `tuturuuu-auth` outside that job.
* **Auth check, every 5 minutes.** For each environment's `tuturuuu-auth`,
  every version with traffic must appear in a GitHub deployment for that
  environment whose creator is the auth workflow's GitHub actor, whose payload
  names `auth-cloudflare.yaml` and that exact version id, and whose commit is
  reachable from `main` (any other deployment does not count); its variables, bindings and
  secret names must equal `apps/auth/wrangler.jsonc` at that commit; and the
  script must have no route, custom domain, `workers.dev` or preview URL. Any
  code, variable or secret change creates a new version, so a change made
  outside CI fails the first condition. A positive mismatch sets `mintHalt`
  for that environment and alerts. An unreachable GitHub or Cloudflare API, a
  `429`, or an incomplete check alerts and leaves `mintHalt` unchanged, so an
  expired read token cannot turn into a halt only a security operator can end.
  The check also compares the auth binding's target script id and full
  binding definition, not the binding name alone.
* **Gateway check, every 5 minutes.** For each environment's
  `tuturuuu-gateway`, the observer accepts a version with traffic only when a
  GitHub deployment for that environment has the gateway workflow's GitHub
  actor, names `gateway-cloudflare.yaml`, carries that exact version id, and
  is at a commit reachable from `main`; any other deployment does not count.
  It also compares that version's `AUTH` binding (target script id and full
  definition) with the committed gateway configuration. Accepted version ids
  go into `gatewayVersions`; an id is dropped once its version has no traffic,
  which bumps `listVersion`, so the array stays bounded. A positive miss
  leaves the version out, which
  fails the identity class at the next census tick, and a mismatched `AUTH`
  binding sets `mintHalt`. A GitHub or API error, or a run that reaches its
  cap with a page unread, alerts and accepts nothing new and removes nothing, and never fails the class
  for a version already accepted; only a positive miss fails it.
* **Key-plane check, every 5 minutes.** For each environment's
  `tuturuuu-auth-keyguard`, `tuturuuu-auth-keyguard-operator` and
  `tuturuuu-auth-observer`, every version with traffic must be the version
  on the latest App `success` deployment for that script's environment. A
  deployment is an App deployment when the deployment has the keyguard
  deployer App's bot user as `creator` and the pinned App id in
  `performed_via_github_app`; `github-actions[bot]` never counts. Its
  status is its latest status with that same creator and App id. It is a
  `success` deployment when that status is `success` and:

  * its payload names `keyguard-cloudflare.yaml` and that exact version id,
    and its commit is reachable from `main`;
  * the run id and attempt come from that status's `log_url` and name a
    [qualifying run](#key-guard);
  * the version's variables, bindings and secret names equal that script's
    committed Wrangler config at that commit; and
  * the SHA-256 of each module of the version's content, read from the
    Cloudflare API, equals the `keyguard-<script>-manifest` artifact of that
    run, with the same module set. The result is kept by version id in
    `ObserverCache`, since a version is immutable.

  The latest `success` deployment is the most recently created one; an
  earlier one stays latest until a newer deployment reaches `success`. So a
  version with its own earlier attested record, restored later, alerts.
  A status that GitHub generates, such as an `inactive` on a deployment
  whose version has no traffic, has no App creator and is ignored. The check
  reads only the App's latest status, never a deployment's full status
  history, because GitHub drops status records after 90 days; a verified
  `success` is kept by deployment id in `ObserverCache`, so a dropped record
  does not undo it. A version on an App deployment newer than the latest
  `success`, whose status is `in_progress` while its run attempt is still
  running, is pending, and alerts when it has not reached `success`
  15 minutes after its creation. No key-plane script may have a
  `workers.dev` or preview URL, the guard serves only its pinned hostname,
  and the operator Access application must cover every hostname of the
  operator Worker. A miss is a positive alert to the security on-call
  channel. A deploy made with a key-plane CI token outside a qualifying run
  leaves a version with no accepted record, so it alerts here although the
  audit alert may see an expected token. The check sets no halt,
  since a redeployed guard would not serve it; the response is the
  containment under the accepted residual. An API or GitHub error, or a run
  capped with a page unread, alerts as a failed read. All three provenance
  checks read GitHub with `TTR_AUTH_OBSERVER_GITHUB_TOKEN`.
* **Inventory check, every 15 minutes.** See the binding inventory below.
* **Bounded.** Each run stays inside its call cap below, writes only
  `GuardState` through `ObserverEntry`, its own `ObserverCache` Durable
  Object and alerts, and never retries within a run.

## Audit alert

The audit alert is the scheduled GitHub Actions workflow
`auth-audit-alert.yaml`, which reads Cloudflare Audit Logs v2 for the watched
scripts outside the observer's code and outside Cloudflare. Its source,
MACed cursor, expected actors and residual are on
[auth Worker audit alert](https://docs.tuturuuu.com/platform/architecture/tuturuuu-session-auth-worker-audit.md).

## Binding inventory

`apps/auth/binding-inventory.json` is a set of `(script, entrypoint)` pairs
allowed to bind `tuturuuu-auth`. `api-ops` is the only script listed twice,
for `WebEntry` and `AdminEntry`; no other script binds `AdminEntry`. A CI check fails when a
committed Wrangler config binds `tuturuuu-auth` outside it, or when it
disagrees with the entry point table. `apps/auth-keyguard/binding-inventory.json`
lists the pairs allowed to bind `tuturuuu-auth-keyguard`: only
`(tuturuuu-auth-keyguard-operator, OperatorEntry)` and
`(tuturuuu-auth-observer, ObserverEntry)`.

* **Live diff.** The observer's inventory check lists every script in the
  platform account, reads the bindings of each version with traffic, and diffs
  bindings to `tuturuuu-auth` and to `tuturuuu-auth-keyguard` against both
  inventory files on `main`. Any Durable Object binding to a `GuardState`
  class from another script is a finding. It keeps each version's bindings by
  version id in `ObserverCache`, since a version is immutable.
* **Incomplete runs.** When the call cap is reached while another API page
  exists or a script is unread, the run fails as `incomplete` and alerts. An
  incomplete run never counts as clean.
* **Finding.** An alert means rotate that entry's caller key now, by the
  rotation procedure on the auth Worker page; for the guard, its
  `TTR_KEYGUARD_ENTRY_*` key in the same order.
* **Prevention and detection.** The caller key is the preventive control: a
  binding without the key gets `unauthorized` and causes no downstream call.
  The inventory diff is detection only.
* **Acceptance.** Staging and production acceptance run the same diff once
  from CI against git and fail on any finding or an incomplete run. This is a
  G4 input, and the G4 owner owns the procedure.

## Cloudflare API budget

The census, the observer and the audit alert read the Cloudflare API, which
allows 1,200 requests per 5 minutes per user. Each read token belongs to its
own service user, and each caller has a hard cap:

| Caller | Cap | Worst case per 5 minutes |
| - | - | - |
| Census tick, once a minute | 40 calls per tick | 200 |
| Observer auth check, every 5 minutes | 20 calls per run | 20 |
| Observer inventory check, every 15 minutes | 300 calls per run | 300 |
| Observer gateway check, every 5 minutes | 20 calls per run | 20 |
| Observer key-plane check, every 5 minutes | 40 calls per run | 40 |
| Observer grant check (members, user groups, account tokens), every 5 minutes | 30 calls per run | 30 |
| Audit alert, every 5 minutes | 10 calls per run | 10 |

The sum, 620, stays under 1,200 even if every token shared one user. A census
tick that reaches its cap completes the classes it finished; the others keep
their last good census. On a `429` the caller stops API reads until
`Retry-After` has passed, alerts, and changes no stored result: every class
keeps its last good census, whose 300-second cap is measured from its own
store time and is never shortened by the error. Persistent `429` responses
still stop minting once that cap passes. Every call writes a `keys`
accounting point.

## Publication census

* **Identity membership.** The identity registry is the gateway's effective
  mount inventory (its mounted paths and mount bindings) merged with the live
  bindings, as slice 2a defines. The gateway release publishes it as the
  identity registry artifact, an APEX-owned dependency: the gateway exports a
  `MountInventory` entry point whose `list()` returns
  `{ env, gatewayVersionId, registryVersion, mounts: [{ mountId, script, base }] }`,
  the committed gateway configuration merged with the live bindings that
  gateway version was deployed with. The auth Worker binds it as
  `{ service: 'tuturuuu-gateway', entrypoint: 'MountInventory' }`. A service
  binding RPC is unreachable from any public route, so it needs no caller key
  or signature, and the gateway's deploy helper already asserts that the
  committed set is a subset of the live one. The gateway release can attach a
  signed snapshot of the same list as a CI artifact for offline evidence. The
  auth Worker and its deploy identity can only call `list()`, no file under
  `apps/auth` lists identity membership, and the signer is never the source of
  membership.
* **Other classes.** Realtime, s2s, access and step-up registries follow the
  same contract, each published by its verifier's release with that family's
  slice. A class with no published artifact has an empty registry and mints
  nothing, as slice 2a requires.
* **Published versus live.** The authority for identity membership is the
  Cloudflare API view of the script named `tuturuuu-gateway`, read with
  `TTR_SESSION_CENSUS_READ_TOKEN`: each tick reads its active deployment and,
  for each version with traffic, projects that version's mount map from its
  `GATEWAY_MOUNTED_PATHS` variable and its `MOUNT_<SEGMENT>` service bindings
  (for example `MOUNT_MAIL` to `tuturuuu-mail` for `/mail` and `/mail/*`) into
  entries of `mountId`, script and base. Every version with traffic must
  produce the same map, and each must be in the signed `gatewayVersions` list
  from the key guard, so the census needs no GitHub credential of its own.
  `list()` must equal that map. The class fails when the artifact's
  `gatewayVersionId` is not an accepted version with traffic, when its
  `registryVersion` is lower than the highest seen, or when `list()` and the
  API view differ in any entry, or when the key guard's list marks the
  identity class blocked. Because the gateway's deploy token cannot edit
  `tuturuuu-auth`, and the auth token cannot edit the gateway, the signer's
  deploy identity is never the source of membership.
* **Live versions.** Each tick reads every listed script's active deployment,
  its versions and their traffic shares. A version's configured key bundle is
  immutable, so the collector reads it once per new version id and keeps it in
  `KeyObservations`' version bundle cache.
* **Reports.** Each verifier serves `KeysReportEntry.report()`, which returns
  `{ versionId, keys }`: the `CF_VERSION_METADATA` id of the running version
  and the public key bundle it loaded. For identity, the collector calls
  `CensusEntry.report(mounts)` with the published mounts, and the gateway
  calls each listed mount's report with at most 8 in flight and a 2-second
  timeout, returning one result per listed mount, timeouts included.
* **Class result.** A class's census succeeds only when membership passes
  and every published entry has an active deployment and a report, the
  report's `versionId` is one of that deployment's versions, and its keys
  equal that version's configured bundle. A timeout, an error, a missing
  entry, a report for an unpublished entry, a duplicate, or a mismatch fails
  the class. A key holds only when every live version of every entry contains
  it, so an entry mid gradual deployment, with two live versions, passes only
  when both bundles contain the key.
* **Public JWKS.** The collector also fetches
  `https://tuturuuu.com/.well-known/jwks.json` with caching disabled. The
  fetch counts only when its response carries `x-gateway-cache: AUTH` and the
  serving auth deployment id, proving it crossed the public gateway path
  rather than a same-zone shortcut; otherwise every class's census fails.
* **Write.** A tick checks the fence first. A complete census for a class is
  written to `KeyObservations` in one transaction with the store's time, and
  the collector then writes the snapshot described below.
* **Use.** The signer hands `publicationHolds` the last census and its time.
  A failed refresh keeps the last success only until the 300-second cap, so a
  collector outage stops minting for that class after at most 5 minutes.
* **Rows.** The first time `publicationHolds` is true for a key, the isolate
  calls `KeyObservations.getOrCreate(class, kid, thumbprint)`. The object
  inserts the row stamped with its own clock in one transaction, marking the
  first row of a class as bootstrap. Rows are never updated or deleted, and
  no caller supplies a time.

## Observation cache across isolates

`publicationHolds` needs the committed rows and the last census, and the
signer needs the held guard document, so the persisted copy carries all three.

* **Warm isolates.** Each isolate loads every committed row, each class's last
  successful census with its store time, and the held guard document from
  `KeyObservations` at start and every 60 seconds. When a read fails it keeps
  its last good copy; the 300-second census cap and the guard list's
  300-second age still apply to it.
* **Snapshot.** After each complete census the collector writes one snapshot
  to `KEY_OBSERVATION_SNAPSHOT`: every committed row, each class's last
  successful census with its store time, the held guard document as fetched,
  `TTR_SESSION_ENV`, and the writing auth deployment id, under one HMAC with
  `TTR_TOKEN_OBSERVATION_MAC_KEY`. That is at most one KV write per minute per
  environment.
* **Cold isolates.** An isolate whose first `KeyObservations` read fails loads
  the snapshot and checks its MAC and that its environment equals
  `TTR_SESSION_ENV`. It uses only rows whose `(class, kid, thumbprint)`
  matches an entry in the current key set, and a class's census only while
  its store time is at most 300 seconds before the isolate clock; past that
  the class mints nothing. It verifies the guard document with the pin as any
  isolate does. A missing or invalid snapshot leaves the isolate with no rows,
  no census and an empty guard list, and it mints nothing, as slice 2a
  requires. A key with no persisted row stays blocked.
* **Writer version.** The deployment id records which auth version wrote the
  snapshot. A snapshot from the previous auth version stays usable during a
  deploy, because `publicationHolds` checks keys against the current key set,
  not the writer.
* **Staleness.** KV is eventually consistent. A stale snapshot can only lack
  the newest row, which keeps that key blocked, hold an older census, which
  the 300-second cap measures from the census's own store time, or hold an
  older guard document, which the `listVersion` rule and its 300-second age
  bound.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.