Host ownership of connection management
Rendered from contracts/auth/management.md by connectors-docs; the source owns every rule on this page.
Proposed, not implemented. This is the shared ownership and admission boundary of auth.connection and auth.acquisition, not an additional advertised contract family. Owner: story:contracts-management-boundary (E04). Design §12 assigns coordination and persistence to the host, provider protocol construction/interpretation to the provider auth implementation, sensitive versions to custody, and protected interaction to a trusted UI/ingress. Design §16.1 permits admitted remote management while excluding private callback and registration authority from ordinary discovery.
1. Owner and admission
connections.* and the safe auth.begin/auth.status surface are host management operations. The owning service's host registers and dispatches them to its coordinator; they are not provider business operations and do not call Adapter::invoke. A provider declares its auth profile and supplies private begin/exchange/refresh/revoke/validation hooks. The generic coordinator does not acquire provider-specific branches or storage clients inside each adapter.
Only the specified managed acquisition flows may use auth.begin/status/completion. static_config activation/materialization belongs to the explicitly admitted configuration path in acquisition §4.0: auth.begin refuses unsupported before allocating state for that path or a reserved flow. Registration is required only for the selected OAuth flow, never invented for static entry or configured/no-child-credential access. Locally revoked configured bindings cannot be resurrected by reload/restart; any allowed replacement uses a new admitted connection.
The host may carry these operations through the selected extended operations envelope. Reusing that envelope does not assign orchestration to the adapter, grant management access through a business-operation permission, or select callback HTTP paths. Reserved management names must not collide with adapter operations; collision refuses configuration. There is no generic public auth.complete, auth.refresh, credential-read, secret-delete or provider-revoke invocation.
Admission uses authenticated current caller/tenant/optional realm/executor context and an explicit receiver-owned management policy. It separately admits create, repair, list, describe, status and revoke. Provider grants, a business invocation grant, possession of an opaque ref or gateway credentials do not imply any management grant. A local deployment may select an explicit local management policy; missing policy or unavailable authority refuses. Checked result access applies to each returned record, including after a wait or replay.
Management does not depend on the target's provider readiness or enabled state: an admitted caller can inspect or locally revoke pending, disabled, degraded and revoked records, and repair a permitted non-revoked binding. This exemption applies only to the management read/coordinator action. Any provider work still requires that action's separately admitted provider capability, credentials and bounded effect budget. Revoked records cannot be repaired or re-enabled; creating another connection is a new admitted action.
| Action | Target and owner | Provider work and observation |
|---|---|---|
connections.list | Host metadata query in the admitted instance/scope; no selected connection required. | No credential resolution or provider call. Filter every record under current disclosure; safe bounded pages only. |
connections.describe | Host metadata/evidence projection for one admitted connection. | No credential capture, validation or provider call. A stale observation is marked as such; it grants no invocation authority. |
auth.begin create | Host admits instance, profile, requested access and flow-applicable configured registration; coordinator allocates one expiring acquisition. No existing connection is required. | Private provider begin/exchange mechanics only where the selected acquisition flow requires them and their effect has been admitted. OAuth client credentials can exchange immediately; “safe payload” does not mean effect-free. |
auth.begin repair | The same coordinator, additionally bound to exactly one existing non-revoked connection and its expected revision/identity. | Candidate identity/scope checks and publication follow acquisition/evidence. A failed repair does not replace or globally poison a still-valid active generation. |
auth.status | Host queries its acquisition under current creator/tenant or explicitly admitted delegated management scope. The ref is an identifier, not a polling grant. | No exchange, provider probe, approval spend or resend. Return safe lifecycle/connection/next-action facts, never completion authority or raw callback/provider data. |
| trusted completion | Owning coordinator's separately bound protected-entry/OAuth ingress; host validates current permitted flow, correlation, expiry and one use before invoking private provider exchange. | Credential material and OAuth code/state stay in the protected boundary. Completion publishes durable custody then admitted metadata before success; it never invokes the previously failed business operation. |
connections.revoke | Host first serializes monotonic local revocation with publication and final dispatch admission, invalidating pending admissions. | Provider revocation is a separately admitted private action when supported. Its failure/unknown result cannot undo local revocation or be reported as provider revocation success. |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Creation/list are instance-scoped. Describe/revoke/repair use exactly one admitted connection. A management binding requires the existing nonempty string Invocation.connection selector for describe/revoke/repair; a duplicate body selector must agree exactly or the request is invalid_input. Create/list/status omit Invocation.connection entirely and reject any supplied selector, including explicit JSON null. Status resolves the persisted acquisition owner and its stored repair relation; protected completion has its own separately bound ingress and cannot use an arbitrary supplied connection. Nullable connection in F03 signed claims is a separate value and does not make the Invocation field nullable. No implicit configured business connection fills an instance-scoped request. Exact public payload schemas and operation curation must declare these target rules before advertisement; this ownership selection does not invent another envelope field.
2. Readiness, revocation and outcome boundaries
The connection readiness reduction governs new provider business dispatch. It does not hide management records or prevent an admitted repair/status read. Connection enablement and terminal revocation remain separate from per-operation enablement and caller permissions. A status read can report disabled or revoked without enabling anything.
Local revocation is acknowledged only after the host metadata authority definitely commits the cutoff. Provider revocation can occur afterward under the coordinator's selected binding; report local revocation and provider outcome as separate facts. Unsupported provider revocation is explicitly unsupported, not success. An ambiguous local acknowledgement supplies no new provider dispatch permission; current authoritative status may be observed, but absence or socket failure is not rollback. Repeated observation of an already revoked record does not repeat a possibly consumed provider action. A provider call authorized before the local cutoff may already have had an effect; revocation is not cancellation or erasure of that history.
Side-effecting management must retain the shared mutation classification, audit, dispatch-fence and conservative uncertainty rules for its declared effects. It cannot be marked read-only merely because it changes host metadata. The exact management idempotency/approval and result schemas are binding obligations: the F03 helper presently covers mutations with a resolved canonical connection target, and does not silently supply an instance-scoped creation subject. An operation requiring approval but lacking a specified/verifiable subject is unavailable, not implicitly approval-free. This document does not advertise such an incomplete binding or extend the F03 proof format.
3. Protected actions and federation
Begin records the admitted originating scope, profile and flow-applicable registration selection and optional repair binding/revision at its owner. Before exchange and again before publication the coordinator checks current permission for that stored scope and exact target, in addition to the one-use/expiry and publication fence. Withdrawn management authority refuses; possession of the callback capability cannot restore it. If current policy cannot be established, fail closed without an exchange or new publication. An acquisition has one stable logical owning coordinator. Safe metadata includes its owning service identity and opaque acquisition ref, not a caller-selectable destination. All replicas acting under that identity share the same one-use/publication authority. Gateway aliases are presentation. A route refresh cannot rebind an in-flight acquisition to another coordinator or recreate it after an unknown response.
For begin/status/list/describe/revoke through a gateway, both gateway and owning leaf admit management access. Forward only through an explicitly supported selected management profile and scoped one-hop authority; ordinary configured federation does not establish the original caller. The leaf reconstructs the persisted target and current authority rather than trusting body ownership claims. Shared F03 raw-request correlation/time/nonce constraints remain necessary where that delivery binding is used; they do not provide missing management approval subjects or protected completion capabilities.
The trusted UI receives a continuation only through an authenticated confidential channel bound to this admitted acquisition and owner. Ordinary model results, operation discovery, lists/status, logs and audit must not contain an actionable completion/entry URL, OAuth code/state, registration secret or credential value/reference. When a flow produces an interactive action, an ordinary auth.begin result returns a safe acquisition ref, expiry and action kind (browser or protected_entry), not the URL. The separately admitted UI channel delivers the one-use continuation; for a flow that requires an interactive continuation, if the host has no such channel, begin refuses before allocating a usable flow. Non-interactive client-credentials begin requires its admitted registration/provider/custody path and current authority, not a UI channel, and can return completed without an action. This corrects the earlier ambiguous “ordinary results carry the URL once” proposal. A one-use URL is still completion authority before it is used.
The protected completion request reaches the owning leaf's ingress directly, or through an explicitly admitted protected transport that terminates there without exposing/reissuing the capability. It is never generic gateway invoke(auth.complete, evidence). The ingress checks method/body bounds, authenticated UI/session binding where applicable, provider callback correlation/state, expiry, replay and expected owner/repair revision before any exchange or publication. Authentication context comes from the bound flow and trusted ingress, not query-supplied tenant/realm/profile data. A capability for one flow cannot complete another, be exchanged for a business grant or survive successful consumption/expiry. Provider redirects/destinations come only from reviewed profile and admitted host configuration.
Routing that cannot reach that owner safely refuses; it cannot copy acquisition state to a new coordinator, fall back to the gateway's identity or rerun begin/exchange automatically. The exact protected codec, UI delivery mechanism and ingress placement must be specified, reachable by the intended UI/provider parties and pass conformance before that acquisition profile is exposed remotely. No particular HTTP path is selected by this ownership document.
4. Reference trace and limits of this selection
- Caller describes the admitted management surface and begins create/repair against the owning instance/profile or exact existing connection.
- Gateway and leaf check current management authority and target consistency. The leaf coordinator records bounded one-purpose acquisition state; trusted UI delivery and any admitted provider work follow the selected acquisition flow.
- UI/provider completion returns to that same coordinator's protected ingress. The host validates one use/correlation, the provider implementation interprets exchange/identity/grants, custody stores the sensitive version, and host publication checks revision/non-revocation.
- Caller polls the same owner under current result access and receives a safe completed reference or safe failure. It explicitly initiates any later business operation.
- An admitted revoke serializes local cutoff at that owner; provider revocation outcomes are separately truthful. Subsequent status/list/describe remain governed metadata reads.
All control/provider work consumes the selected operation/flow's bounded budget; a gateway does not reset it. Existing acquisition expiry defaults are 600 s browser / 300 s entry. Concrete management payload sizes, paging, audit/result fields, effect/approval/idempotency bindings and protected transport bounds remain required profile specifications before advertisement. Reusing an envelope or ESS value cannot discharge them.
Connection admission ESS types the selected status/eligibility and management-target values. It introduces no fictitious persistent owner or executable authority checker. Concrete Connection/Acquisition/AuthProfile persistence models and unresolved authority/custody relations retain their named owners. Verification records the textual traces, value checks and independent review separately from future runtime conformance.
Persistence ownership is consolidated in design §31. AcquisitionCoordinatorPort and ConnectionAuthorityPort remain the logical owners across admitted gateway paths; protected completion and provider revocation are ordered handoffs. This inventory does not supply a backend or execute its atomicity predicates.