mirror_worker

Transparency Log Mirror Worker

A configurable Cloudflare Worker implementing c2sp.org/tlog-witness, c2sp.org/tlog-mirror, or both protocols with one per-origin MirrorState Durable Object.

Configuration

The presence of the witness and mirror identity sections enables each role. Combined deployments use a shared submission prefix and distinct monitoring prefixes per identity. logs is keyed by exact checkpoint origin and supports structured Ed25519 and subtree/v1 checkpoint signers.

When enable_chrome_cosigners is true, an hourly scheduled event synchronizes the public MTC cosigner registry into the singleton CosignerRegistry SQLite Durable Object. Synchronized issuer logs are merged with logs; static configuration takes precedence for an origin. The option defaults to true. Registry versions are opaque identifiers because the upstream schema does not require semantic-version syntax. Replacement rejects changed content under the same version and parseable timestamp regressions.

A read that finds no snapshot synchronizes once before falling back to an empty registry, so a fresh deployment serves dynamic origins before the first hourly event. A failure there is logged and leaves the static logs servable.

chrome_cosigner_realms lists the Chrome realm values accepted from the registry. An issuer whose realm is absent from the list is not trusted, so omitting the list trusts no dynamic cosigner. The registry currently publishes UNTRUSTED_VALIDATION_ONLY test CAs. Realms are stored in the snapshot and applied on read, so changing the list takes effect without a re-synchronization.

Witness and mirror monitoring prefixes are backed by separate public R2 buckets. The Worker only serves submission and metadata APIs.

Role keys remain separate secrets:

• WITNESS_SIGNING_KEY signs successful add-checkpoint responses and witness subtree responses.
• MIRROR_SIGNING_KEY signs completed mirror checkpoints and mirror subtree responses.
• MIRROR_TICKET_KEY seals mirror upload tickets.

Disabled-role secrets and R2 bindings are not loaded. Ticket and cleaner access is confined to mirror operations.

Mirror State

For each origin, MirrorState maintains committed.size <= next_entry.size <= pending.size. Checkpoint publication is serialized and durably ordered as publishing -> R2 -> committed -> clear. Every commit reconciles an existing publishing record first, so interrupted publication is retried before an older or newer request is evaluated.

Development

The dev configuration enables both roles. Run from this directory:

./reset-dev.sh
npx wrangler -e=dev dev --test-scheduled \
  --var COSIGNERS_JSON_URL:http://127.0.0.1:8790/cosigners.json \
  --var COSIGNERS_PEM_URL:http://127.0.0.1:8790/cosigners.pem

Run the integration suites from the workspace root against the same worker:

cargo test -p integration_tests --test tlog_witness
cargo test -p integration_tests --test tlog_mirror

The mirror integration test starts the registry fixture server on port 8790. The URL overrides are only honored by the dev build and are needed for that suite. Other builds use the public gstatic registry.

Operations

The mirror Durable Objects and hourly registry job send invocation counts, latencies, errors, and buffered logs through the optional WSHIM_SOCKET / WSHIM_TOKEN bindings. The MirrorState DO reports mirror_last_publication_timestamp_seconds{origin,role} on successful checkpoint publication. The cleaner alarm reports mirror_cleaner_backlog_leaves{origin}; registry reads and syncs report mirror_registry_last_sync_timestamp_seconds. origin is the SHA-256 origin hash used in the monitoring URL. Publication and registry-sync timestamps are absent until the first successful operation.

Publication timestamps are emitted only after the existing checkpoint writes succeed; the Worker does not persist monitoring timestamps. Registry-sync time is emitted when synchronization succeeds. Frontier and gap gauges are deferred: sampling state on /get-state alone would leave stale values when no read occurs. Without a separate progress source, there are no missing-origin or stalled-progress alerts. The cleaner backlog is emitted on successful cleaner alarm wakes (one hour by default). Publication timestamps are events: use the metrics backend's retained history to obtain the last value, and do not interpret a missing recent sample as no publication. Missing cleaner samples do not imply zero backlog. The cleaner reserves two of its 1,000 subrequests for the logs and metrics Wshim flushes; Wshim delivery remains best-effort. The metrics backend can alert on missing samples using an independent inventory of expected cleaner origins. Enroll a cleaner origin only after its first persisted upload, since checkpoint acceptance alone does not start the cleaner. The hourly registry job can likewise be monitored against expected deployments where enable_chrome_cosigners is true. Failed witness invocations emit per-origin event gauges. Incoming metrics need an env label matching the deployment's Wrangler environment for per-environment monitoring.