feat: Add CIBA (Client-Initiated Backchannel Authentication) support (RFC 9126)

[rsharath]

Summary

Add support for Client-Initiated Backchannel Authentication (CIBA) as defined in RFC 9126 and the OpenID Connect CIBA spec. CIBA enables headless AI agents to initiate authentication on behalf of a user without requiring a browser redirect — the user approves via an out-of-band channel (push notification, email, or voice call).

Motivation

CIBA is a critical flow for autonomous agent scenarios where:

• An agent needs user authorization but has no browser context (e.g., background orchestrators, CLI tools, MCP servers)
• A human-in-the-loop approval step is required before an agent acts on behalf of a user
• The agent operates in a headless environment (server-side, container, CI/CD pipeline)

This was identified as a gap compared to other agent identity platforms that support CIBA for headless agent approval flows.

Requirements

New Grant Type

• Register urn:openid:params:grant-type:ciba as a new grant type
• Implement backchannel authentication endpoint (POST /oauth2/bc-authorize)
• Implement polling mode: agent polls token endpoint with auth_req_id
• Implement ping mode: server notifies agent callback URL when user approves
• Support push mode (optional): server delivers token directly to agent callback

Authentication Request

• Accept login_hint (user identifier — email, phone, user ID)
• Accept scope and binding_message (human-readable context for approval prompt)
• Accept requested_expiry for auth request TTL (default configurable, bounded by credential policy)
• Return auth_req_id, expires_in, and interval (polling interval)

User Approval

• Define BackchannelNotifier interface for pluggable notification delivery:

  type BackchannelNotifier interface {
      Notify(ctx context.Context, req BackchannelAuthRequest) error
  }

• Ship with no built-in notifier — users bring their own (push, email, SMS, Twilio, etc.)
• Expose Server.SetBackchannelNotifier() hook for registration
• Approval endpoint for user to accept/deny (POST /oauth2/bc-authorize/{auth_req_id}/approve)

Token Issuance

• On approval, issue tokens via standard token endpoint with grant_type=urn:openid:params:grant-type:ciba
• Enforce credential policy constraints (TTL, scopes, trust level)
• Support delegation: issued token can carry act claim if agent is acting on behalf of user
• Pending requests expire after requested_expiry or server default

Storage

• New backchannel_auth_requests table: auth_req_id, account_id, project_id, client_id, login_hint, scope, binding_message, status (pending/approved/denied/expired), expires_at, created_at

Integration with Existing Features

• Credential policy enforcement on CIBA-issued tokens
• CAE signal support — revoke CIBA-issued tokens on risk signals
• Cascade revocation if CIBA token is used as subject_token in token exchange
• Introspection and revocation endpoints work with CIBA-issued tokens

Non-Goals (for initial implementation)

• Built-in push notification or SMS delivery (pluggable interface only)
• CIBA with signed authentication requests (JWT-secured authorization requests)

References

• RFC 9126 - OAuth 2.0 Pushed Authorization Requests
• OpenID Connect CIBA Core
• CIBA Flow Diagram

[safayavatsal]

Implementation plan — dependent PR sequence

After scoping the codebase, I'll deliver CIBA across three sequential, dependent PRs. They must be merged in order — each one builds on the previous PR's schema and service wiring.

PR 1 — Foundation (polling-mode CIBA) → #131

• Migration 014_backchannel_auth_requests (table includes notification_mode and client_notification_endpoint columns up-front so PR 2 is pure code, no follow-on migration)
• domain.BackchannelAuthRequest types + domain.GrantTypeCIBA constant
• BackchannelNotifier hook in hooks.go + Server.SetBackchannelNotifier() in server.go
• internal/store/postgres/backchannel_request.go repository
• internal/service/backchannel.go — request lifecycle (Create / Approve / Deny / Poll / Expire)
• Replace the existing POST /oauth2/bc-authorize 501 stub with real handler; add POST /oauth2/bc-authorize/{auth_req_id}/approve and /deny under tenant-scoped admin middleware
• Wire urn:openid:params:grant-type:ciba into the oauth.go grant switch; emits CIBA-standard errors (authorization_pending, slow_down, access_denied, expired_token)
• Extend internal/worker/cleanup.go to sweep expired requests
• Form-encoded compat: add /oauth2/bc-authorize to OAuthFormEndpoints
• Integration test (testcontainers) covering full polling lifecycle, act chain, credential-policy enforcement, and introspection

After PR 1, polling-mode CIBA is fully functional on its own.

PR 2 — Ping mode (depends on PR 1) → #132

• Migration 015_ciba_ping_columns adds oauth_clients.client_notification_endpoint (registered HTTPS allowlist) and backchannel_auth_requests.client_notification_token (per-request bearer the server echoes in the ping)
• bc-authorize accepts client_notification_token; non-empty switches the row to notification_mode='ping' only if the client has a registered HTTPS endpoint
• BackchannelService.dispatchPing fires on pending→approved and pending→denied: bounded retry with exponential backoff + jitter, 4xx terminal, 5xx retried, records last_notify_error
• Server.SetBackchannelPingTransport(http.RoundTripper) and SetBackchannelPingDispatchSync(bool) test hooks
• HTTPS enforced at both registration and request time (defence in depth)
• Integration test for the ping path: happy path, missing-endpoint rejection, http:// scheme rejection

PR 2 is currently stacked on top of PR 1 (it carries both commits). Once PR 1 merges, GitHub's diff for PR 2 will narrow to PR 2's commit only. Cannot merge before PR 1.

PR 3 — Push mode (depends on PR 2) → #133

• Migration 016_ciba_push_mode: oauth_clients.backchannel_token_delivery_mode enum (poll|ping|push) with CHECK constraint
• Client registration validates the enum; ping/push require a registered client_notification_endpoint
• CreateAuthRequest derives notification mode from the client's registered delivery mode (per CIBA §10 — mode is a client property, not per-request)
• dispatchResolution routes approved/denied resolution to dispatchPing or dispatchPushApproval/dispatchPushDenial based on notification_mode
• Push approval mints via shared issueTokenForApprovedRow (extracted from Redeem) and POSTs the full CIBA §10.3.1 token-response body (access_token, token_type, expires_in, auth_req_id, optional scope/refresh_token)
• Push denial POSTs the RFC 6749 §5.2 error body
• Redeem refuses push-mode rows with access_denied so polling cannot double-deliver a token already pushed
• Shared postCallback helper consolidates outbound HTTP machinery between ping and push (bounded retry, jitter, 4xx terminal, 5xx retried, last_notify_error)
• Integration tests: push happy path (token delivered + polling refused), push denial (error body, no token), registration-without-endpoint rejection

PR 3 is stacked on PR 1 + PR 2. Cannot merge before #131 and #132.

Why not three independent / parallel PRs

1. All three touch the same backchannel_auth_requests table — independent PRs would force overlapping migrations and merge-order coupling anyway.
2. BackchannelService is constructed once in server.go's dependency-ordered service block; ping and push hang fields off the same struct.
3. Ping and push both react to the same pending → approved transition that PR 1 introduces.

If parallel review is desired, PR 2 and PR 3 are stacked on each other — review can happen in parallel, but merge order is still PR 1 → PR 2 → PR 3.

Spec citation note

The issue title cites RFC 9126, but RFC 9126 is PAR (Pushed Authorization Requests). The flow described in the body is OpenID CIBA Core 1.0. PR docs and the OpenAPI description will cite OpenID CIBA Core 1.0; PAR is a separate spec that ZeroID may want to add later.

After all three PRs merge

Every checkbox on the issue's Requirements list is delivered, including ping and push (initially flagged optional). CAE signal revocation, cascade revocation, introspection, and credential-policy enforcement are inherited from credentialSvc.IssueCredential — no separate wiring needed.