# Arena personal issuer collection verification

Status: implemented and tested; not deployed or activated. This is read-only
collection discovery and an ownership check during terms approval. It does not
create, mint, publish, sell, transfer, consume consent, or reserve studio rights.
No production grants, credentials or collection fixtures are provisioned.

## Authority and privacy

Hybrid-ID remains the authority for the signed-in native account and primary
vault. This first contract supports personal accounts only. Corporate/shared
issuers need their own explicit membership/delegation contract; they are not
inferred from a supplied workspace or vault. Collections must have BOTH the
native issuer profile and the current primary vault recorded in Core. Missing,
conflicting, archived or legacy unbound records are excluded, not adopted.

Private inventory is available only in the personal Hybrid-ID portal. Arena's
ordinary `openid` sign-in is not permission to disclose private collections.
The existing Arena terms request/read response is still not an issuance token.
A public or cached positive result must never be used as creation authority.

## Identity private native binding

`POST /identity/sso/assets/issuer` takes exactly `{}`. It uses the existing
body-bound SSO service HMAC and durable nonce middleware plus the owner's current
`hybrid-id-web` browser token. Other relying parties, developer credentials,
workloads and caller-selected identifiers are denied. The current native account,
Chain admission, asset module access and `contracts:read` ceiling are checked.
The two native account projections must agree on the primary vault.

Successful private response (inside the existing `success/response` envelope):

```json
{
  "schema": "hybrid.identity.personal-asset-issuer.v1",
  "subject": "32 lowercase hex native profile",
  "identity_uuid": "32 lowercase hex native identity",
  "issuer_vault_uuid": "32 lowercase hex current personal vault",
  "authority": "personal_primary_vault",
  "collection_read_only": true,
  "issuance_enabled": false,
  "value_movement": false
}
```

Identifiers above are explanatory placeholders. This response stays between
Identity and its provider; it is never an OIDC claim or Arena response. No-store.
Default gate: `HYBRID_SSO_ASSET_ISSUER_READ_ENABLED` absent/false returns 503.

## Canonical Core private collection read

`POST /asset-registry/issuer-collections`, exact JSON fields:
`issuer_profile_uuid`, `issuer_vault_uuid`, `after`, `collection_uuid`.
The first two MUST be derived from the fresh native binding. `after` is an empty
string or lower32hex keyset cursor; `collection_uuid` is empty for a page or an
exact lower32hex collection. Only one of those selectors may be nonempty.
No URL query, browser Origin, bearer fallback or arbitrary forwarded fields.
Maximum 1,024 request bytes; pages have at most 50 records, ordered by UUID.

This endpoint trusts only a separate provider-owned `ASSET_ISSUER_READ_SECRET`
(at least32 characters). Do NOT put that secret into general Core client keys
or give it to Arena. `ASSET_ISSUER_READ_ENABLED=true` is also required.
The additive `20261008_asset_issuer_read_nonces.sql` migration provides durable
nonce replay protection. Absence/failure is 503, never an empty successful page.

Headers: `X-Hybrid-Issuer-Timestamp` (10-digit UTC Unix seconds),
`X-Hybrid-Issuer-Nonce` (48 lowercase hex), `X-Hybrid-Issuer-Signature`
(HMAC-SHA256 lowercase hex). Sign the following newline-separated UTF-8 values
with no trailing newline:

```
hybrid.asset-issuer-collections.v1
{timestamp}
{nonce}
POST
/asset-registry/issuer-collections
{sha256-of-exact-request-bytes}
```

Clock tolerance is30seconds; accepted nonces survive61seconds in MySQL. Exact
HTTP replay returns409; a fresh read uses a new nonce. Core returns
`success:true,response:{schema:"hybrid.asset-issuer-collections.v1",collections,
next_cursor,collection_read_only:true,issuance_enabled:false,value_movement:false}`.
Each collection has only `collection_uuid`, `name`, `status`, `visibility`.
Native owner IDs, arbitrary metadata and credentials are excluded. Database
errors return503; the legacy helper that swallows query failures is not used.
Logs redact the private route/body. Responses are no-store.

## Provider and personal portal

Provider config is opt-in under existing `assetConsents`:
`issuerCollections:{enabled:true,origin:<fixed trusted Core origin>,secret:<private key>}`.
Use TLS except a private10.x or loopback transport. Redirects, URL credentials,
queries and path overrides are rejected. Configuration is never user input.
Requests time out after8seconds; responses are bounded to64KiB and validated.
Native vault/account authority is rechecked after the Core response.

Signed personal management action:
`{action:"asset-consent-collections",after:""}`.
Website BFF: `GET /api/identity/asset-consents?operation=collections&after=...`.
Only the authenticated personal owner gets the result. It adds the derived
`issuer_vault_uuid` for the owner's selection; native profile/identity never leave
the provider. Pagination is not a transaction or a saved authorization.

`asset-consent-approve` now checks the exact proposed collection against current
native ownership before recording approval. Wrong vault, inaccessible collection,
withdrawn account permission, unavailable service or revoked app connection fail
closed. Revocation/decline/history remain possible while discovery is unavailable.
The existing atomic revision check runs again after asynchronous reads, so a
concurrent decline/withdrawal cannot be overwritten. An approval still expires
in at most10minutes and still exposes `issuer_authorized:false` to Arena.

## Remaining delivery and rollout

1. Deploy Identity code with its gate off; deploy the Core handler and nonce
   migration with its dedicated gate off; deploy provider code before the site.
   Preserve existing runtime configuration and unrelated verification gates.
2. Provision the private read key between provider/Core, validate native issuer
   and collection ownership with a real eligible account, then enable only these
   read gates. No issued assets, source rights or paid features are enabled.
3. The personal Hybrid-ID picker now supports a v2 immutable intent with no
   caller-selected issuer IDs. One explicitly shared selection fixes the final
   terms; approval is a separate step. Connect Arena's request/read UI to that
   flow; no broad inventory scope is added. See arena-asset-consent.md.
4. Implement the canonical purpose-bound consent consumer and source-rights
   reservation/consumption with durable withdrawal, expiry and crash recovery.
   Recheck collection ownership at the actual issuance acceptance point.
5. Connect Core's original-request creation receipt, read back the real draft,
   and separately validate publisher/studio acceptance. Update public availability
   only with deployment evidence. Funding, Stripe and real-value execution stay
   paused.
