# Private provider-binding ingress

Party Governance records one canonical provider binding from qualified ownership
evidence. The API relays the retained compatibility writer's request through
`request.party_governance.provider_binding.v1`. Only its enrolled broker principal
can publish this kind. Browser sessions cannot call this private operation.

The [wire contract](proto/pharos/party_governance/provider_binding/v1/provider_binding.proto)
and [private HTTP relay](../../authentication/legacy.openapi.yaml) preserve
`command_id`, `correlation_id`, `party_id`, `proof_ref` and the complete immutable
signed assertion. Transport request IDs may change. The proof reference is
`sha256:` plus the lowercase SHA-256 digest of the exact assertion bytes.
Unknown/duplicate fields, malformed UUIDs and unsupported versions are rejected.
Replies contain one closed typed outcome and its exact transport correlation.

The [signed ownership fact](../../authentication/provider_binding_assertion.schema.json)
has header `alg: EdDSA`, `typ: pharos-party-provider-binding-v1+jwt` and an enrolled
`kid`. Its issuer is `themelio-compat`; its audience is
`party_governance.provider_binding.v1`. The signed `jti`, `correlation_id` and
`party_id` match the request. It also binds the independently allocated canonical
`binding_id`, `expected_revision`, `auth_version`, exact provider/instance/external
identity, accepted API authentication evidence reference, exact AAI issuer/subject
and integer-second `verified_at`.

This is a durable ownership fact without an expiry claim. It establishes no
authentication or provider access grant. The writer first resolves accepted API
evidence and verifies the provider's exact federated account identity. Email,
username, display attributes and a caller-selected external ID cannot establish
association. It persists the complete command and signed fact before sending.
Lost acknowledgement is resolved by repeating those exact bytes.

Beto enrols the writer's public key with exact attester, provider, instance and AAI
issuer scope. Every intake, including receipt replay, checks current canonical
Party identity, eligibility and authentication generation against the fact.
`verified_at` may be at most thirty seconds in the future. An old fact cannot
acquire a later generation after disablement/re-enablement.
The existing binding transaction enforces expected revisions and retained external
identity uniqueness, committing its root, receipt, outcome and event intents
together. Retired bindings reject reuse and reassignment.

Successful recording returns the current established binding with its positive
JSON-safe revision. An unavailable outcome can follow a successful commit; it
does not permit a new command or another binding ID. The private read relay uses
the existing canonical owner query, verifies the requested Party and enrolled
provider scope, and preserves established/retired/missing semantics.
The compatibility account worker marks ready only after a committed established
binding. The legacy AUP policy read and credential issuance resolve that binding
through this owner query before provider effects.

The writer holds `THEMELIO_COMPAT_BINDING_SIGNING_KEY` (or `_FILE`) and
`THEMELIO_COMPAT_BINDING_SIGNING_KEY_ID`. Beto holds only its verification key.
HTTP `BindingWriter` and `BindingReader` credentials are separately scoped and
never admitted by public ingress.

`scripts/generate_party_provider_binding.py` reproduces API/Beto wire bindings.
Generated output and schemas declare the protocol; activation additionally needs
the explicitly enrolled owner worker, broker permissions and private API relay.