# `Attesto.Plug.ResourceAuthenticate`
[🔗](https://github.com/XukuLLC/attesto/blob/v2.28.0/lib/attesto/plug/resource_authenticate.ex#L2)

Authenticate one OAuth protected resource using `Attesto.Plug.Authenticate`.

Requires an explicit `:resource_audience` or `:trusted_audiences` policy.
With `resource_audience: :resource`, use `:resource_path` and a pinned
`:base_url` or `:origin`. Never derive an audience from an unchecked Host.
A DPoP mount requires a pin or an explicit `:htu` callback at initialization;
`:allow_dynamic_origin` also supports a non-empty `:allowed_hosts` allowlist.
HTTP pins require `allow_http: true` and loopback.

`:base_url` / `:origin` accepts a URL, one-arity callback or MFA tuple.
`:resource_audience` also accepts a literal identifier, callback or MFA.
`:resource_metadata_url` overrides the derived RFC 9728 challenge pointer;
`:www_authenticate` overrides challenge rendering entirely.
`:principal` receives verified claims and sender context and returns
`{:ok, principal}` or `{:error, reason}`. The exact error result
`{:error, {:temporarily_unavailable, reason}}` answers 503
`temporarily_unavailable`, without a challenge or `Retry-After`. The reason
is discarded. Every other result answers 401 `invalid_token`. An exception
the callback raises is not caught, as with the verifier: it reaches the
host's error handling, which typically answers 500. MFA extras follow call
arguments.

Assign keys are configurable with `:claims_key` (default `:attesto_claims`),
`:scopes_key` (`:attesto_scopes`), `:sender_key` (`:attesto_sender`),
`:principal_key` (`:attesto_principal`) and `:context_key` (`:attesto_context`).
The context contains subject, client_id, scope, claims, cnf and principal.
`:policy_rejection_send_error` optionally supplies a separate error renderer
for principal refusals; otherwise `:send_error` handles them too.
`:principal_unavailable_send_error` similarly overrides `:send_error` for
principal outages. Both hooks receive `(conn, status, body)`.

Outcome hooks distinguish `:policy_rejected` (401 principal refusal),
`:principal_unavailable` (503 principal outage), and `:verifier_unavailable`
(503 verifier outage through `:send_error`). A status/body alone cannot
distinguish the two outage outcomes.

All other `Attesto.Plug.Authenticate` options pass through, including
`:config`, `:verify`, `:replay_check`, `:nonce_check`, `:nonce_issue`,
`:cert_der`, `:htu`, `:credential_from_conn`, `:bearer_methods`, `:step_up`,
`:send_error`, `:www_authenticate`, `:no_store` and verification options.
With no explicit `:bearer_methods`, the base plug's defaults apply.
Use `Attesto.Plug.ProtectResource` to add per-route scope authorization.

# `dpop_target_uri`

```elixir
@spec dpop_target_uri(
  Plug.Conn.t(),
  keyword()
) :: String.t()
```

Returns the DPoP target URI (`htu`) a proof must sign for `conn` when the
plug is configured with `opts` and no `:htu`: the origin resolved by
`Attesto.ResourceMetadata.resolve_origin/2` followed by `conn.request_path`.

With a pinned `:base_url` or `:origin`, the request's scheme, `Host` header,
and port do not affect the result. A pinned value carrying a path prefix is
joined with `conn.request_path`, which matches a proxy that strips that
prefix before the request reaches the application. Without a pin, the
resolved origin is the request's own.

    iex> conn = Plug.Test.conn(:post, "http://10.0.0.5:4000/mcp")
    iex> Attesto.Plug.ResourceAuthenticate.dpop_target_uri(conn, base_url: "https://mcp.example.com")
    "https://mcp.example.com/mcp"

---

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