supported-surface.md

Supported Surface

Lockspire 1.0.0 is a GA release of an embedded OAuth/OIDC authorization server library for Phoenix and Elixir. It is meant for Phoenix teams that want to become an OAuth/OIDC provider inside an existing app while keeping accounts, login UX, layouts, branding, and product policy in the host application.

This page is the canonical support contract for what Lockspire currently supports, what it does not support, and what repo-owned proof backs those claims.

Supported in scope

Lockspire 1.0.0 GA currently supports this repo-proven surface:

• Embedded Phoenix install flow through mix lockspire.install
• Authorization code flow with PKCE S256
• The Phase 37 OIDC strictness slice proven in-repo: exact redirect_uri matching, prompt=none returning redirect-safe login_required instead of host login redirects, durable max_age / auth_time handling, and integer auth_time emission in ID tokens when max_age or explicit auth_time demand requires it
• Pushed authorization requests only as Lockspire-issued request_uri references that extend the existing authorization code + PKCE flow
• global and client-specific PAR requirement policies (can be configured as required or optional)
• OIDC discovery and JWKS
• Resource Indicators on the authorization and token surface, with truthful discovery metadata via resource_indicators_supported only when the mounted authorization-code surface is actually usable
• authorization_details_types_supported in discovery only when the mounted authorization-code surface is usable and the host has configured at least one RAR validator type
• Userinfo
• Dynamic client registration and registration management for self-service clients within the repo-proven RFC 7591/RFC 7592 slice
• Revocation
• Introspection
• Refresh token rotation
• DPoP on token requests, the Lockspire-owned userinfo endpoint, and truthful introspection visibility for active bound tokens, with bearer clients remaining unchanged by default unless they explicitly opt into DPoP mode
• Device authorization flow for embedded Phoenix hosts: POST /device/code, device polling through POST /token, single-use token redemption, and token issuance backed by the host-owned /verify seam
• A generated, host-owned device verification seam for /verify, including LockspireVerificationController, lockspire_verification_html, and the security contract in docs/device-flow-host-guide.md
• A generated, host-owned custom RAR consent seam through lockspire_consent_live.ex, with an illustrative payment_initiation walkthrough in docs/rar-consent-host-guide.md
• RP-initiated logout plus logout propagation from the protocol-owned /end_session/complete seam: durable back-channel enqueueing with Oban and Req, plus front-channel iframe cleanup as best effort browser choreography only
• Host-owned login redirects and consent handoff seams
• LiveView and admin workflows for clients, consents, tokens, keys, PAR/DPoP/DCR policies, and operator-managed logout propagation settings
• Phoenix-first onboarding docs and generated host integration files
• FAPI 2.0 Security Profile enforcement when security_profile: :fapi_2_0_security is set globally or per-client: PAR-required at /authorize, DPoP sender-constrained access tokens, ES256/PS256 signing only, exact-match redirect URIs with zero tolerance for trailing slashes or query drift
• RFC 9207 iss parameter emitted on every authorization-response redirect (success, denial, and error) for all clients regardless of profile
• Truthful FAPI 2.0 keys in .well-known/openid-configuration: authorization_response_iss_parameter_supported always true; require_pushed_authorization_requests true only when the global server policy is :fapi_2_0_security

Explicitly out of scope

Lockspire does not currently support:

• Implicit flow
• Request-object-by-value support
• Generic external request_uri handling outside Lockspire's own PAR endpoint
• Generic host protected-resource middleware remains out of scope
• DPoP nonce support or broader resource-server integration beyond Lockspire-owned endpoints
• Lockspire-owned device verification browser UI or hosted approval pages
• Lockspire-owned semantic RAR consent rendering, renderer registries, or payment-product UI
• Dynamic Client Registration support for backchannel_logout_uri, backchannel_logout_session_required, frontchannel_logout_uri, or frontchannel_logout_session_required remains unsupported in this slice
• Hosted auth as a separate required service
• SAML
• LDAP or Active Directory federation
• Full CIAM or workforce identity platform scope
• Lockspire-owned account database, passwords, or login UX
• Broad compatibility claims beyond the Phoenix/Elixir embedded-library path documented in this repo
• External OIDF FAPI 2.0 conformance suite certification — Lockspire pins the canonical OIDF FAPI 2.0 plan (fapi2-security-profile-final-test-plan) and variant axes in scripts/conformance/fapi2-plan.json and docs/maintainer-conformance.md, but the live Docker run remains a documented manual maintainer step and is not a CI pass-gate
• mTLS client authentication and mTLS-bound access tokens (DPoP is the supported sender-constraining mechanism for FAPI 2.0; mTLS is permanently out of scope per the v1.10 milestone)

Trust posture

Lockspire maintains its 1.0 GA posture because public claims are backed by what this repo can prove today. Repo-owned proof for this posture lives in:

• docs/install-and-onboard.md as the canonical Phoenix host onboarding path
• docs/rar-consent-host-guide.md for custom RAR consent on the generated host seam
• docs/device-flow-host-guide.md for the Phase 31 verification security contract
• docs/maintainer-conformance.md, scripts/conformance/phase37-plan.json, and mix conformance.phase37 for the repo-native Phase 37 conformance lane and its .artifacts/conformance/phase37 proof bundle
• test/integration/install_generator_test.exs for generator-backed install proof
• test/integration/phase6_onboarding_e2e_test.exs for the canonical auth-code + PKCE onboarding flow
• test/integration/phase37_protocol_strictness_e2e_test.exs for the generated-host strictness proof covering prompt=none, max_age, auth_time, and exact redirect behavior
• test/lockspire/release_readiness_contract_test.exs for narrow release and docs posture checks
• .github/workflows/ci.yml and .github/workflows/release.yml for maintained contributor and protected release lanes
• docs/maintainer-release.md and SECURITY.md for versioned release and disclosure guidance

Lockspire does not use a demo app, certification language, or external folklore as its primary public proof story.

GA bar

A 1.0 GA claim honestly says:

• there is one canonical Phoenix onboarding path
• secure OAuth/OIDC defaults are enforced inside the supported surface
• executable install and onboarding proof is checked into the repo
• the shipped device flow is an embedded-library path: device authorization endpoint, device polling, token redemption, and a narrow host-owned device verification seam, not a Lockspire-owned browser UI
• the shipped DPoP proof surface is narrow: /token issuance plus the Lockspire-owned userinfo endpoint, not generic host protected resources
• the shipped logout propagation surface is asymmetric by design: back-channel delivery is durable and front-channel logout is best effort only
• contributor and release workflows are versioned in the repo
• a private disclosure path exists for supported security issues

A 1.0 GA claim should not say:

• Lockspire is production-ready for unsupported host shapes
• Lockspire supports broader request-object modes, generic external request_uri handling, generic host protected-resource middleware, SAML, or LDAP
• Lockspire accepts DCR logout metadata or proves front-channel logout success remotely
• Lockspire is a hosted auth service or full CIAM product
• Lockspire has broad certification or conformance coverage

GA Criteria

A 1.0 GA claim requires everything in the GA bar plus:

• repeated green release gates in the trusted publish lane
• maintainer runbooks that match real release operations
• stable support expectations for the documented embedded-library surface
• evidence that public docs, workflows, and shipped behavior still agree over time