> **True Witness Here** # POPCORN checkpoint workflow This package supplies the caller workflow and read-only evidence viewer for the POPCORN checkpoint service. It includes a caller-run CLI and guarded payment adapter. Local tests use fixture keys and mocked settlement; passing them does not establish that a paid live checkpoint has completed. The checkpoint action records a digest. Original checkpoint content stays with its caller. The caller supplies the exact canonical action bytes, a grant signed by the configured authority, and a presenter signer bound by that grant. A self-issued caller key alone is not authorization. ## Required order `canonical()` → `digest()` → `validate()` → `prepareCommitment()` → read-only `witness.js` display. `model.js` defines deterministic bytes, digest and explicit parameter validation. Every assignment refers to scope, clock, cost and evidence. `publication.js` prepares the immutable commitment. `executor.mjs` rechecks identity, authorization, exact input, trusted signature, freshness, scope, clock and cost at the transaction boundary. The executor is the only component that can commit the checkpoint. The viewer displays evidence and makes no decision. Missing parameters stop with `incomplete, need X`. There is no optimizer, scoring, inferred permission, or default policy. ## Controlled workflow API `workflow.mjs` exports `createCheckpointWorkflow(configuration)`. Its `run({authorization, action_bytes})` method returns the caller's evidence journal. `action_bytes` is unpadded base64url of the canonical action JSON's UTF-8 bytes, not of the original checkpoint content. The action's `checkpoint_digest` identifies that locally retained content. Configuration is explicit: - `authorityKeys` and `executorKeys`: maps from trusted HTTPS key URI to a public P-256 JWK. They are installed trust configuration, not keys accepted from an untrusted receipt. - `witnessKeys` and `verifyWitness`: the trusted POPCORN JWKS and the native cryptographic witness verifier. A successful HTTP response is not a verification result. - `clock` and `policy`: the same explicit grounded-time shape and scope, radius, freshness policy used by the resource executor. - `signPresenter(payload)`: returns the presenter's ES256 envelope. The workflow verifies it with the key named in the authority's signed grant before buying anything. - `registerAuthorization(authorization)`: sends the authority-signed envelope to the resource's authorization registry after the caller journal has claimed the ID, and before any paid attempt. It must return `{status:'active', authorization_id, authorization_digest}` matching this exact grant. A refusal, mismatch or ambiguous transport result stops the workflow without a purchase. Registration is not retried automatically and never clears a revocation. - `issueWitness(request, context)`: performs at most one explicitly authorized `/v2/receipt` purchase and returns only the original JSON response body. `live-adapters.mjs` pins the current x402 challenge's endpoint, exact scheme, amount, Base network, USDC asset and payee before signing. It never returns a payment-signature header or private key. It requires the separately installed, reviewed native-v2 POPCORN MCP package. - `execute(request)` and `finalize(request)`: adapters to the enforcing resource boundary. Neither is an arbitrary action callback supplied by the requesting agent. - `journal.create(authorization_id, state)`: durably and atomically claims an unused ID, returning `true`. It returns `false` if the ID is already claimed. `journal.save(authorization_id, state)` durably saves each snapshot before resolving. These are caller-owned storage adapters. The workflow does not generate authority grants, install keys, choose a payment source, or assume a missing setting. The test fixtures use separate ephemeral authority, presenter, executor and witness keys, plus mocked settlement. Those fixtures are not production credentials or evidence of a live call. ## Caller command and configuration The complete caller entry point is `live-client.mjs`. All file paths and payment approval are required: ```sh node live-client.mjs --action action.json --authorization authorization.json --config public-trust.json --presenter-key presenter-private.json --journal PRIVATE_DIRECTORY --approve-payment 0.002 ``` The caller supplies `EVM_PRIVATE_KEY` in their own process environment. The command never asks them to send it to another party. The presenter file has `{key_uri, private_jwk}` and must match the public key already bound by the signed authority grant. The private key stays local; only signed public envelopes leave the caller. Public trust configuration has these exact fields: `origin`, `authority_keys`, `executor_keys`, `witness_keys`, `policy`, `request_timeout_ms`, and `clock_max_round_trip_ms`. The origin is exactly `https://767-2676.com`. Authority and executor arrays contain `{key_uri, public_jwk}` entries; the executor URI is `https://767-2676.com/.well-known/checkpoint-executor-key.json`. `witness_keys` is the explicitly trusted native POPCORN JWKS. Do not populate any public trust field with a private key. Policies and timeouts have no defaults. The CLI dynamically imports `@violetclaire/popcorn-mcp/core`. Its exported witness URL and locked payment constants must match native `/v2/receipt`, 1,000 USDC atomic units per witness, Base, and the pinned payee. The older v1-only MCP package is rejected before a payment. This command does not install dependencies or silently substitute a version. Local tests replace the payment client and settlement transport with fixtures; they do not prove that an installed wallet or live package has been exercised. The result is full evidence JSON on stdout, with `journal_path` pointing at the latest durable snapshot. Exit code `0` means complete; `2` means stopped; `3` means an ambiguous outcome or committed action with pending post-witness evidence. Save and inspect the returned bundle. Re-running the same authorization cannot start another purchase. The file journal claims one directory per authorization with an exclusive create and retains numbered snapshots. Each file is fsynced before an atomic same-directory rename. POSIX directory entries are also fsynced; Node does not expose a portable directory-fsync operation on Windows. File modes are restrictive where supported; the caller's private directory ACL controls access on Windows. ## Bound evidence The pre-action record binds the authorization ID, digest of the signed authorization envelope, exclusive expiry, action ID, intended input digest and a fresh nonce. Its POPCORN witness commits to the SHA-256 of that record's exact canonical UTF-8 bytes. The presenter signs the same bindings for the execute audience. The executor's signed execution receipt binds the authorization and the committed result. The executor emits it in the same resource transaction, or binds it to an immutable transaction ID. A later requester-made statement is not substituted for this receipt. The post-commit witness commits to the exact canonical execution receipt, including the executor signature. It uses a new nonce and `previous_attestation_digest` equal to SHA-256 of the first witness's **exact decoded JWS payload bytes**. It is not a hash of the JWS string or of reserialized JSON. Both witnesses, their bound records and the executor result are retained together. Neither witness grants authorization. The resource executor enforces the grant. Historical POPCORN-WITNESS 1.0 and 2.0 receipts keep their original protocol labels. ## Active authorization and revocation An authentic signed grant must also be enrolled as active at the resource. The executor checks the persisted authorization record inside the execution transaction, not only the caller's earlier registration acknowledgement. The exact signed grant's digest must match, and the grant must remain unrevoked and unused. Swapping the action or its bytes after issuance does not carry the original grant's permission over to the replacement. The enrolled authority can sign a `checkpoint-revocation+jws` envelope whose payload is `{type:'checkpoint-revocation/v1', authorization_id, authorization_digest}`. The resource's `revokeAuthorization()` stores that revocation. Re-registering the old grant cannot undo it. A revocation before execution prevents the action even if the pre-action witness was already purchased; that purchase is evidence, not a reservation of permission. The viewer displays a saved registration acknowledgement as historical evidence. It is not a live authorization check or permission to execute. ## Clock scope POPCORN is not an RFC 3161 timestamp authority. Its time source is the platform wall clock. Its current 10,000 ms accuracy radius is issuer-asserted, not independently measured; no external atomic-clock alignment is claimed. For an exclusive expiry `E`, the entire verified interval must precede the expiry: `U < E`. Equality, overlap, a missing bound or a stale receipt closes the gate. A policy requiring measured accuracy is indeterminate and must stop. The executor rechecks time immediately before the action can take effect; a successful earlier check does not keep an expired grant open. The live caller obtains a fresh nonce-bound time record from `/checkpoint/clock`, signed with the configured executor key. The request requires the authority grant and its presenter's signature. This limited checkpoint time record is not a POPCORN witness receipt. The caller verifies that signature and binding, adds its measured monotonic round-trip and verification time to the upper bound, and uses no caller UTC clock. It never clips the enlarged interval to fit a policy. The grant and configured policy must explicitly allow the resulting radius; for example a 20,000 ms maximum can accommodate a source interval with a 10,000 ms asserted radius and bounded transit. The permitted cap of 60,000 ms is a policy ceiling, not a claim that the source clock was measured to that accuracy. ## Cost and failure behavior The explicit action and grant must allow two witnesses at 1,000 USDC atomic units each: total 2,000 units (0.002 USDC), on Base, with the pinned USDC asset and payee. Existing `/v2/receipt` payment semantics are unchanged. A witness purchase may succeed even when a later execution check rejects the action. The workflow requires a durable caller-side journal. It atomically claims an authorization ID before paid calls. Each 1,000-unit attempt is reserved and saved **before** invoking its payment adapter. An ambiguous paid result is retained and never retried automatically. Payment-signature headers, payment authorization payloads and wallet private keys must never enter the journal or returned bundle. The grant window is checked again after each durable reservation, including the post-commit purchase. Immediately before the paid HTTP transmission, the live adapter obtains another verified clock record and checks `U < E`. It also parses the signed EIP-3009 payment authorization and rejects a `validBefore` later than the grant's exclusive expiry, conservatively floored to whole seconds. An SDK-generated 60-second payment authorization that outlives the grant is rejected before transmission. A payment budget never extends the grant's lifetime. An ambiguous executor response is not retried. Replaying an authorization ID must be rejected at the executor. Recovery requires inspecting the actual resource record; creating a new authorization is not evidence that the prior attempt failed. If execution commits but post-witness purchase, verification, or finalization fails, the journal retains `committed_post_witness_pending` and the executor's signed result. The completed action is not undone or executed again. A complete bundle is returned only after both witnesses verify and the executor has retained them together. ## Read-only mirror Open the [checkpoint evidence viewer](https://767-2676.com/checkpoint/) to inspect a saved JSON evidence file, or serve this directory locally and open `index.html`. The browser reads the selected file locally. `witness.js` does not upload it, buy a witness, verify a signature, or call the executor. It displays the file's claims as claims. Signature checks belong to the controlled workflow and the resource executor. The byte-exact leTAIN SVG is outside this package and is not changed by it.