# Exact collectible consent consumption — canonical service contract

Status: implemented and tested, **not deployed or activated**. This is one
prerequisite for canonical creation, not an Arena mint endpoint or a distributed
rights transaction. The studio-rights participant and canonical coordinator still
need implementation and joint acceptance. No funding or value movement is added.

## Authority and acceptance point

An app's ordinary sign-in or cached approval response cannot authorize creation.
Only the intended canonical service may call this private, separately signed
channel. A first consumption requires the exact currently approved request,
proposal digest, canonical-body digest, approved revision, logical audience
`hybrid-chain.assets.v1` and purpose `create_one_draft`.

The provider rechecks the approving personal Hybrid-ID session and selected
collection through the existing native Identity/Core path. The approving portal
session is retained only in the encrypted, expiring `AssetConsentApprovalSession`
record, capped to the approval's lifetime, and removed on withdrawal or successful
consumption. Existing approval records without that binding cannot be consumed.
No native session token leaves the provider. A failed or changed session/issuer/
collection, expired approval, revoked app connection, disabled app or service,
changed metadata or storage error fails closed.

After all asynchronous checks, a single SQLite transaction reloads the approval,
rechecks its revision, current app connection and ephemeral session, writes one
immutable encrypted consumption receipt, changes status to `consumed`, increments
the revision and removes the temporary session. This transaction is the **consent
acceptance point**. A concurrent withdrawal either commits first and blocks
consumption, or consumption commits first and withdrawal returns409. There is no
interval where both can win. The personal review UI states this boundary.

Consumed means the permission was accepted for the one original draft request.
It does not confirm that an asset exists. The original approval cannot be reused
or withdrawn afterward. Future requests require a new explicit user decision;
failures never silently recreate or reactivate the consumed approval.

## Transport

`POST http://127.0.0.1:3152/hybrid/assets/consumption` is loopback only. The Core and
gateway Nginx templates deny this path. The handler independently rejects remote
peers, proxy-forwarding headers, Origin, Cookie and Authorization. Arena browser
cookies, OAuth access tokens, developer credentials and general admin keys are
not accepted. Maximum body2KiB; exact path without query, JSON content type.

The independently configured `assetConsents.consumer.secret` must be at least32
characters and must differ from the collection-read key. Use a dedicated random
operator-managed key, never a fixture or an app/client key. Requests sign the
exact UTF-8 bytes, not reserialized JSON. Headers:

- `X-Hybrid-Consumption-Timestamp`: current10-digit UTC Unix seconds.
- `X-Hybrid-Consumption-Nonce`: fresh48 lowercase hex characters.
- `X-Hybrid-Consumption-Signature`:64 lowercase hex HMAC-SHA256.

Signing input, newline separated with no trailing newline:

```text
HYBRID-ASSET-CONSUMPTION-V1
{timestamp}
{nonce}
POST
/hybrid/assets/consumption
{sha256_of_exact_body_bytes}
```

Clock tolerance is30seconds. Nonces survive process restart in a dedicated
SQLite table and expire after61seconds. Replay returns409. The durable consumption
clock also records the greatest observed server time; backward time fails503
until it catches up, including across restart. An observed expiration cannot
become valid again because the clock was moved backward. Key changes during
upstream checks stop new consumption. Never log headers, body, native authority
or portal tokens. All responses are private/no-store.

Body has exactly these fields:

```json
{
  "operation": "consume",
  "app_id": "the originating registered application",
  "request_id": "the original lowercase UUID v4",
  "proposal_digest": "the final selected proposal SHA-256",
  "canonical_request_sha256": "the exact canonical creation-body SHA-256",
  "revision": 2,
  "audience": "hybrid-chain.assets.v1",
  "purpose": "create_one_draft"
}
```

`revision` is the actual approved revision, not a fixed2. Legacy exact proposals
may approve at1; private collection selection usually approves at2. The caller
must not supply profile, vault, metadata or a replacement request ID.

## Response and recovery

`hybrid.asset-consent-consumption.v1` contains an immutable `receipt`, `replayed`,
`consent_consumed:true`, `receipt_only:true`, `ownership_current:false`, and false
rights_verified, asset_created, issuance_enabled, mint_enabled, publish_enabled
and value_movement fields. Native issuer profile/vault and exact canonical request
are returned **only over this private canonical-service channel**. They are absent
from ordinary Arena app responses, which keep all authority flags false.

The receipt binds the original request UUID, purpose/audience, approved revision,
proposal/canonical hashes, acceptance timestamp and revision, intended app,
recording/metadata/brief commitments and complete canonical creation body. The
canonical body contains the same original UUID as `creation_request_id`. Its hash
must be verified by the consumer before use. It is not a transferable bearer token
or proof of current collection ownership, studio rights, publication or finality.

After an uncertain reply, send the exact same intent with a new timestamp/nonce.
`operation:"read"` is read-only recovery:404 means no receipt exists and does not
consume an approval. Exact consume retries return the same receipt, even if the
approval later expires or the creation gate is paused. Changed terms under the
same ID return409. Historical receipt recovery is not a new authorization decision.
Never create a replacement UUID after a timeout,404, restart or changed response.

## Gating, backup and coordinated rollout

Configuration is absent by default. `assetConsents.consumer` has only the separate
secret plus `enabled`; with no secret the entire channel returns503. With a valid
secret and `enabled:false`, existing exact receipts can be recovered, but no new
consumption is accepted. New consumption additionally requires the existing
assetConsents.enabled gate and current personal approval. Do not provision a key
or enable either flag as part of source deployment.

Back up consent requests, consumption receipts, clock, nonces and provider key
consistently. Consumption UUIDs and receipts are permanent, not OIDC-token data;
Store.prune does not remove them. Restoring an older approval without its matching
consumption receipt could reopen authority: prohibit split or rollback restores.
Ephemeral portal bindings expire with the normal provider record cleanup.

Before activation, the canonical coordinator must:

1. Persist the original issuance intent and exact terms before external calls.
2. Obtain and recover an exact studio-rights reservation/consumption decision,
   including source revocation rules, using the same original UUID and metadata.
3. Consume this exact personal approval and durably retain/recover the result.
   A studio read or approval read is never a substitute for a decision record.
4. Recheck actual canonical issuer/collection controls at asset creation; consume
   only the exact returned canonical body through Core's original-request receipt
   primitive. Never widen purpose to mint, publish, purchase or transfer.
5. Recover crashes between participants and creation; distinguish pending,
   accepted-without-asset, failed and actually-created states. Define cleanup of
   unused source reservations only with authoritative no-creation evidence.
6. Read back the actual canonical asset/receipt before announcing creation.
   Complete real issuer/studio and concurrent revocation/expiry acceptance.

This change does not supply steps1–6 or claim atomic coordination across services.
It closes the provider's exact personal-consent decision and recovery boundary.

## Tests

`node --test sso/test/asset-consumption.test.mjs` covers SQLite concurrency,
withdrawal races, rollback, encrypted restart recovery, wrong terms/purpose,
changed issuer/session/collection/app connection, expiry and durable clock rollback,
key rotation, native signed HTTP, proxy/browser denial and durable nonce replay.
The actual provider HTTP test exercises v2 request, private selection, separate
approval, native Identity/Core lookup, consumption, private recovery and public
redaction using synthetic local OIDC models and signatures. No production user
permission or source grant is created by those tests.

Validation in this source change:740 provider tests passed,2 existing optional
skips;81 website tests, TypeScript and the production website build passed.
Compiled local Chromium checks at390/1440px in both themes passed explicit
approval, withdrawal and consumed-history presentation without overflow or page
errors. These are isolated synthetic checks; deployment and human acceptance
remain unverified.

## Originating application binding — contract2026-10-08.2

Every private consume/read intent must include `app_id`. Before any irreversible
acceptance or private issuer lookup, the provider requires that exact application
on the stored approval. It rechecks the binding inside the accepting transaction.
Historical receipt lookup also binds the app. The canonical coordinator derives
this value from its authenticated service-caller configuration, never a browser
choice. Missing app IDs fail400; a wrong app cannot consume another app's approval.
This source update precedes the first production consumption rollout; no deployed
consumer or live receipt migration is implied. Never drop a receipt's app binding
to work around an incompatible historical request.
