Skip to content

capability-protocol.md

Latest commit

 

History

History
140 lines (107 loc) · 2.56 KB

capability-protocol.md

File metadata and controls

140 lines (107 loc) · 2.56 KB
Raw

Capability Protocol

IdentityMapper capabilities are not tied to HTTP.

A host receives transport-shaped input and turns it into a capability request. The capability returns a capability response. The host then turns that response back into transport-shaped output.

Transport Request
        |
        v
Capability Request
        |
        v
Capability
        |
        v
Capability Response
        |
        v
Transport Response

Authenticate

AuthenticateRequest
  identification
  credential
  provider optional

AuthenticateResponse
  authenticated
  identity
  error

Rejected authentication is represented by the explicit protocol exception:

AuthenticationRejected

Host services should treat AuthenticationRejected as an authentication result, not as infrastructure failure.

The public capability response remains:

AuthenticateResponse(authenticated=False)

Unexpected provider failures should not be converted into authentication rejection.

provider is a host routing hint, not a domain concept. When it is provided, the host calls that provider explicitly. When it is omitted, the host may select a provider according to its registry or policy.

Resolve Identity

ResolveIdentityRequest
  identification
  provider optional

ResolveIdentityResponse
  candidate
  error

Verify Credential

VerifyCredentialRequest
  candidate
  credential
  provider optional

VerifyCredentialResponse
  verified
  error

Map Identity

MapIdentityRequest
  source_identification
  source_credential
  source_provider optional
  target

MapIdentityResponse
  mapped
  identity
  target_identity
  error

MapIdentity first verifies the source proof through the source provider. Only after a verified canonical Identity exists can a target mapper project it into the requested target world.

source proof -> Identity -> TargetIdentity

The target mapper receives the canonical Identity, not the original source credential. The target mapper therefore cannot bypass the invariant by talking directly to the source provider.

Rule

REST, CLI, gRPC, message bus, and other transports should all reduce to the same capability request and response contracts.

Transport is a host concern.

Capability protocol is an IdentityMapper contract.

Source

The primary module for these contracts is:

identity_mapper.capability_protocol

identity_mapper.requests and identity_mapper.responses remain available as compatibility import surfaces.