# `Attesto.ResourceMetadata`
[🔗](https://github.com/XukuLLC/attesto/blob/v2.28.0/lib/attesto/resource_metadata.ex#L2)

Builders for OAuth metadata for individual protected resources.

Protected resources publish RFC 9728 documents pointing clients to their
RFC 8414 authorization servers. Supply each resource's `:scopes_supported`
and `:bearer_methods_supported` explicitly; no scope catalog is assumed.

## Origin pinning behind a proxy

The `resource` identifier identifies this server, while
`authorization_servers` identifies the issuer a client must use to obtain a
token. A resource identifier may be derived from the live connection when it
is used only for discovery. Any authentication policy that derives its token
audience from the resource identifier must pin the origin.

Behind a TLS-terminating reverse proxy that derivation is both fragile and a
spoofing vector: `conn.scheme` is often `http`, and `conn.host` reflects the
request `Host` or whatever `X-Forwarded-*` rewriting produced. An attacker
can therefore influence an unpinned `resource`. Pin the resource origin when
it drives authorization policy, and identify the authorization server from a
trusted configuration source:

  * The **`resource`** identifier and the well-known metadata URL use
    `resolve_origin/2` - the *resource server* origin, pinned via `:base_url`
    or `:origin` (a `String.t()`, a `(Plug.Conn.t() -> String.t())` callback,
    or a `{module, fun}` / `{module, fun, args}` tuple), falling back to the
    live request origin only when neither option is present. An explicitly
    configured pin that is invalid raises instead of falling back.
  * **`authorization_servers`** defaults to the `:config` issuer (or an
    explicit `:issuer` string) when one is supplied - the authorization server
    the host already trusts for token verification, advertised verbatim - and
    otherwise must be supplied explicitly with `:authorization_servers`.
    The issuer is deliberately NOT used as the `resource` origin: RFC 9728
    keeps the protected resource and its authorization server distinct, and
    in a FAPI deployment they are usually different hosts.

Either can still be overridden outright with an explicit `:resource` /
`:authorization_servers` opt. Use the same pin on discovery and authentication.

# `append_resource_metadata`

```elixir
@spec append_resource_metadata(String.t(), String.t()) :: String.t()
```

Shared protected-resource metadata helper.

# `authorization_server`

```elixir
@spec authorization_server(
  Attesto.Config.t(),
  keyword()
) :: %{required(String.t()) =&gt; term()}
```

Shared protected-resource metadata helper.

# `cache_control`

Cache only metadata whose resource is statically pinned.

# `metadata_options`

Translate the router's scopes alias to the RFC 9728 field.

# `mount_options`

Validate one metadata route declaration and separate its root ownership option.

# `normalize_resource_path!`

```elixir
@spec normalize_resource_path!(
  term(),
  keyword()
) :: String.t()
```

Shared protected-resource metadata helper.

# `protected_resource`

```elixir
@spec protected_resource(keyword()) :: %{required(String.t()) =&gt; term()}
```

Build an RFC 9728 protected-resource metadata document.

Required options:

  * `:resource` - an absolute HTTPS protected resource identifier with no
    fragment, usually the canonical resource URI such as
    `"https://mcp.example.com/mcp"`. Pass `allow_http: true` for a deliberate
    local development endpoint.
  * `:authorization_servers` - a non-empty, unique list of HTTPS issuer
    identifiers with no query or fragment.

Common options include `:scopes_supported`, `:bearer_methods_supported`,
`:dpop_signing_alg_values_supported`, and
`:tls_client_certificate_bound_access_tokens`.

`:dpop_signing_alg_values_supported` defaults to every DPoP algorithm
Attesto verifies. A resource that accepts only Bearer tokens passes `false`
(or `[]`) to leave the member out of the document; RFC 9728 §3.2 does not
allow publishing it as an empty array.

Pass `:authenticate` with the option list given to
`Attesto.Plug.ProtectResource` (or `Attesto.Plug.ResourceAuthenticate`) to have
that default follow the plug: when those options cannot accept a DPoP request
(`Attesto.Plug.Authenticate.accepts_dpop?/1`), the member is left out. An
explicit `:dpop_signing_alg_values_supported` takes precedence.

# `protected_resource`

```elixir
@spec protected_resource(Plug.Conn.t(), String.t(), keyword()) :: %{
  required(String.t()) =&gt; term()
}
```

Build protected-resource metadata from a Plug connection and resource path.

`resource_path` is the path of the protected endpoint, for example `"/mcp"` or
`"/mcp/admin"`. The `resource` identifier is `resolve_origin/2` (the resource
server origin, pinned via `:base_url`/`:origin`) joined with that path.
`:authorization_servers` defaults to the `:config` issuer (or an explicit
`:issuer` string) when one is given. One of those sources is required; the
authorization server is never inferred from the request authority.

An explicit `:resource` or `:authorization_servers` opt overrides the derived
value, and short-circuits its derivation: a pinned origin / issuer callback is
not invoked (and cannot fail) for a value the host supplied outright.

# `protected_resource_metadata_path`

```elixir
@spec protected_resource_metadata_path(String.t()) :: String.t()
```

Shared protected-resource metadata helper.

# `protected_resource_url`

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

Build the well-known metadata URL for an protected resource path.

    iex> Attesto.ResourceMetadata.protected_resource_url("https://mcp.example.com", "/mcp")
    "https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

A Plug connection can also be passed as the first argument. The legacy
two-argument connection form remains available; new code should pass an
options list as the third argument so origin pinning is explicit.

# `protected_resource_url`

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

Build the well-known metadata URL, resolving the origin via `resolve_origin/2`.

Pass `:base_url`/`:origin` in `opts` to pin the resource origin (so the
challenge URL matches a pinned `resource`); with no such opt the live request
origin is used.

# `require_pinned_origin!`

```elixir
@spec require_pinned_origin!(keyword()) :: :ok
```

Shared protected-resource metadata helper.

# `resolve_origin`

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

Resolve the *resource server* origin used to build the `resource` identifier
and the well-known metadata URL.

This is the protected resource's own origin (RFC 9728 `resource`), which is
distinct from the authorization server (`authorization_servers` / the
`Attesto.Config` issuer) - the two are often different hosts in a FAPI
deployment, so the issuer is NOT used here. Precedence:

  1. an explicit `:base_url` or `:origin` opt - a `String.t()`, a
     `(Plug.Conn.t() -> String.t())` callback, or a `{module, fun}` /
     `{module, fun, args}` tuple (the conn is prepended to `args`), resolved
     at request time;
  2. the live request origin (`conn.scheme`/`conn.host`/`conn.port`).

When neither pin is present, the request origin is used. Once either option is
present, it is configuration: invalid literal values and invalid callback
results raise instead of falling back to the request authority. A trailing
slash is trimmed so the result joins cleanly with a resource path.

# `resource_identifier`

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

The canonical RFC 8707 / RFC 9728 resource identifier for this protected
resource: the resolved origin joined with the resource path (for example
`"https://mcp.example.com/mcp"`).

This is the SINGLE source for the value that must agree across the chain — the
RFC 9728 metadata `resource` field, the RFC 8707 `resource` a client requests,
the `aud` the authorization server mints, and the audience the resource-server
plug validates. Driving the audience check and the advertised metadata from
this one function is what makes them consistent by construction (a host cannot
configure them into disagreement). Origin precedence is `resolve_origin/2`'s.

# `resource_metadata_param`

```elixir
@spec resource_metadata_param(String.t()) :: String.t()
```

Shared protected-resource metadata helper.

# `resource_url?`

Validate a resource URL, permitting HTTP only for loopback under explicit opt-in.

# `static_pin?`

```elixir
@spec static_pin?(keyword()) :: boolean()
```

Shared protected-resource metadata helper.

# `validate_metadata_options!`

```elixir
@spec validate_metadata_options!(keyword()) :: :ok
```

Shared protected-resource metadata helper.

# `validate_origin_options!`

```elixir
@spec validate_origin_options!(keyword()) :: :ok
```

Shared protected-resource metadata helper.

---

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