# `AttestoPhoenix.Router`
[🔗](https://github.com/XukuLLC/attesto_phoenix/blob/v0.19.0/lib/attesto_phoenix/router.ex#L1)

Router macro that mounts the authorization-server endpoints.

`use AttestoPhoenix.Router` makes the `attesto_routes/1` macro available
inside a `Phoenix.Router`. Calling it inside (or alongside) a `scope`
declares the OAuth 2.0 / OpenID Connect server surface:

  * `GET /.well-known/oauth-authorization-server` - authorization-server
    metadata (RFC 8414 §3).
  * `GET /.well-known/openid-configuration` - OpenID Provider configuration
    (OpenID Connect Discovery 1.0 §4).
  * `GET /.well-known/jwks.json` - the JSON Web Key Set of the verification
    keys (RFC 7517 §5; the discovery document's `jwks_uri` per RFC 8414 §2).
  * `GET /.well-known/oauth-protected-resource` - protected-resource metadata
    (RFC 9728 §3), the discovery target of the §5.1 `WWW-Authenticate`
    challenge the resource-server plugs emit.
  * `GET /oauth/authorize` - the authorization endpoint (RFC 6749 §3.1;
    OpenID Connect Core 1.0 §3.1.2).
  * `POST /oauth/token` - the token endpoint (RFC 6749 §3.2).
  * `POST /oauth/par` - pushed authorization requests (RFC 9126).
  * `POST /oauth/revoke` - the token revocation endpoint (RFC 7009 §2).
  * `POST /oauth/introspect` - the token introspection endpoint (RFC 7662 §2),
    with the RFC 9701 signed-JWT response negotiated by the `Accept` header.
  * `POST /oauth/register` - dynamic client registration (RFC 7591 §3.1),
    mounted only when registration is enabled (see `:registration` below).
  * `DELETE /oauth/register/:client_id` - dynamic client registration
    management cleanup (RFC 7592 §2), mounted with registration.
  * `GET` and `POST /oauth/userinfo` - the UserInfo endpoint (OpenID Connect
    Core 1.0 §5.3); a bearer-authenticated protected resource (RFC 6750 §2.1).

The macro emits nothing but `Phoenix.Router` route entries pointing at this
library's controllers; it holds no policy of its own. Every behavioral
decision (which clients exist, which scopes are granted, whether DPoP / mTLS
binding is offered, whether registration is open) is owned by the host
through `AttestoPhoenix.Config`, which the controllers read at request time.

## Placement and pipelines

The discovery, OpenID configuration, and JWKS documents are unauthenticated
public metadata (RFC 8414 §5; OpenID Connect Discovery 1.0 §4; RFC 8615).
The authorization endpoint does not authenticate the client (RFC 6749 §3.1):
the resource owner authenticates through the host's login/consent callbacks,
so it carries no client-authentication pipeline. The token, revocation, and
registration endpoints authenticate the client from the request itself
(RFC 6749 §2.3, RFC 7009 §2, RFC 7591 §3), and the UserInfo endpoint is
bearer-authenticated from the `Authorization` header (RFC 6750 §2.1) by its
controller, rather than from a caller session, so they too take no
session-bearing pipeline. Supply a `:pipeline` only to attach
transport-level concerns the host wants in front of every endpoint (for
example a parser that accepts `application/x-www-form-urlencoded` at the
token endpoint per RFC 6749 §4.4.2, or an HTTPS-enforcing plug).

    scope "/" do
      attesto_routes()
    end

    # or with a host pipeline and a mount prefix:
    scope "/" do
      attesto_routes(pipeline: :oauth_server, prefix: "/auth")
    end

## Options

  * `:prefix` - path segment prepended to the `/oauth/*` endpoints (the
    well-known documents always live at the host root per RFC 8615, so the
    prefix does not apply to them). Defaults to `""`.
  * `:pipeline` - a pipeline name (atom) or list of pipeline names to
    `pipe_through` for the mounted routes. Defaults to `[]` (no extra
    pipeline; the surrounding `scope`'s `pipe_through`, if any, still
    applies).
  * `:registration` - when `true`, mounts `POST /oauth/register`
    (RFC 7591) and `DELETE /oauth/register/:client_id` (RFC 7592). Defaults
    to `false`. The endpoints still fail closed at request time unless the
    host has wired the registration callbacks in `AttestoPhoenix.Config`;
    this option only controls whether the routes exist, so a deployment that
    never offers registration presents no registration surface at all.

The library never inspects `:registration` to make a policy decision: it is
a route-existence toggle. Authorization-server metadata advertised at the
discovery endpoint is derived from `AttestoPhoenix.Config` by the discovery
controller, not from these macro options.

# `attesto_routes`
*macro* 

Mounts the authorization-server endpoints. See the module documentation for
the route table and the accepted options.

---

*Consult [api-reference.md](api-reference.md) for complete listing*