api-authorization-oauth-metadata.yaml

# @api-common/spectral-api-authorization-ruleset — OAuth AS Metadata target
#
# Lints an OAuth 2.0 Authorization Server Metadata document (RFC 8414,
# `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration`)
# against the API Authorization Profile (https://apicommons.org/api-authorization).
#
# This is where the FAPI-specific truth actually lives and is assertable:
# client-authentication methods, DPoP / sender-constraining, Pushed Authorization
# Requests, PKCE S256, response types, the mix-up `iss` parameter, and signing
# algorithms. The OpenAPI half of the profile is in the companion
# `api-authorization-openapi.yaml`. Run this ruleset against the METADATA JSON:
#
#   spectral lint as-metadata.json -r api-authorization-oauth-metadata.yaml
#
# These rules carry NO `formats` so they run on the metadata JSON (which is not
# an OpenAPI document). Do not point this file at an OpenAPI spec; point the
# OpenAPI file at that.
#
# Tiers: `normal` (RFC 9700 / OAuth 2.1) and `high` (FAPI 2.0). `high` rules are
# the sender-constraining / PAR / strong-client-auth / code-only requirements.
# Built-in Spectral functions only.
#
# THE FLOOR: this checks what the AS ADVERTISES in its metadata, not its runtime
# behavior. Advertising `require_pushed_authorization_requests: true` is not
# proof the server enforces it — it is proof the server claims to. Design-time
# conformance is necessary, not sufficient.
#
# Provenance: RFC 8414 (AS Metadata), RFC 9700 (OAuth Security BCP), FAPI 2.0
# Security Profile, RFC 9449 (DPoP), RFC 8705 (mTLS), RFC 9126 (PAR),
# RFC 7636 (PKCE), RFC 9207 (iss), RFC 8725 (JWT BCP).
#
# License: Apache-2.0 — Copyright 2026 API Commons (Kin Lane).

extends: []

rules:

  # =========================================================================
  # Discoverability & transport — AZ-META-1 / TLS-1 (normal)
  # =========================================================================
  authz-meta-issuer-https:
    description: >-
      AZ-META-1 / TLS-1 (normal). The metadata must declare an `issuer`, and it
      must be an https:// URL. The issuer anchors every other value in the
      document.
    message: "API Authorization (AZ-META-1, normal): `issuer` must be present and use https://."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#az-meta-1
    given: $
    then:
      - field: issuer
        function: defined
      - field: issuer
        function: pattern
        functionOptions:
          match: "^https://"

  authz-meta-endpoints-present:
    description: >-
      AZ-META-2 (normal). The AS should advertise `revocation_endpoint`
      (RFC 7009) and `introspection_endpoint` (RFC 7662) so permissions can be
      dynamically revoked and validated.
    message: "API Authorization (AZ-META-2, normal): advertise `revocation_endpoint` and `introspection_endpoint`."
    severity: warn
    documentationUrl: https://apicommons.org/api-authorization#az-meta-2
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [revocation_endpoint, introspection_endpoint]

  # =========================================================================
  # Response / grant types — GRANT-1/2 (normal), RESP-1 (high)
  # =========================================================================
  authz-meta-no-implicit-response-type:
    description: >-
      GRANT-1 (normal). `response_types_supported` must not include the
      `token` response type (implicit). Front-channel token delivery leaks
      tokens through history and logs.
    message: "API Authorization (GRANT-1, normal): `response_types_supported` must not include a `token` (implicit) response type."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#grant-1
    given: $.response_types_supported
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          items:
            type: string
            not:
              pattern: "\\btoken\\b"

  authz-meta-grant-no-password:
    description: >-
      GRANT-2 (normal). `grant_types_supported` must not include the `password`
      grant, which is removed in OAuth 2.1.
    message: "API Authorization (GRANT-2, normal): `grant_types_supported` must not include `password`."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#grant-2
    given: $.grant_types_supported
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          items:
            not:
              const: password

  authz-meta-response-types-code-only:
    description: >-
      RESP-1 (high). At the high tier `response_types_supported` must be exactly
      `["code"]` — the authorization code flow only, no hybrid or implicit
      responses.
    message: "API Authorization (RESP-1, high): `response_types_supported` must be `code` only."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#resp-1
    given: $.response_types_supported
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          items:
            const: code

  authz-meta-iss-parameter:
    description: >-
      ISS-1 (high). The AS must support the authorization-response `iss`
      parameter (RFC 9207) to defend against authorization-server mix-up
      attacks.
    message: "API Authorization (ISS-1, high): `authorization_response_iss_parameter_supported` must be true."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#iss-1
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [authorization_response_iss_parameter_supported]
          properties:
            authorization_response_iss_parameter_supported:
              const: true

  # =========================================================================
  # PKCE — PKCE-2 (high)
  # =========================================================================
  authz-meta-pkce-s256:
    description: >-
      PKCE-2 (high). `code_challenge_methods_supported` must include `S256`.
      PKCE with S256 protects the authorization code against interception.
    message: "API Authorization (PKCE-2, high): `code_challenge_methods_supported` must include `S256`."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#pkce-2
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [code_challenge_methods_supported]
          properties:
            code_challenge_methods_supported:
              type: array
              contains:
                const: S256

  # =========================================================================
  # Client authentication — CAUTH-1 / CAUTH-2 (high)
  # =========================================================================
  authz-meta-client-auth-no-secret:
    description: >-
      CAUTH-2 (high). Shared-secret client authentication
      (`client_secret_basic` / `client_secret_post`) must not be offered at the
      token endpoint. Secrets are weak and leak.
    message: "API Authorization (CAUTH-2, high): `token_endpoint_auth_methods_supported` must not include `client_secret_*`."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#cauth-2
    given: $.token_endpoint_auth_methods_supported
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          items:
            not:
              pattern: "^client_secret_"

  authz-meta-client-auth-strong:
    description: >-
      CAUTH-1 (high). The token endpoint must offer strong client
      authentication — `private_key_jwt` (RFC 7523) or mTLS
      (`tls_client_auth` / `self_signed_tls_client_auth`, RFC 8705).
    message: "API Authorization (CAUTH-1, high): offer `private_key_jwt` or `tls_client_auth`/`self_signed_tls_client_auth`."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#cauth-1
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [token_endpoint_auth_methods_supported]
          properties:
            token_endpoint_auth_methods_supported:
              type: array
              contains:
                enum: [private_key_jwt, tls_client_auth, self_signed_tls_client_auth]

  # =========================================================================
  # Sender-constraining — SC-1 (high)
  # =========================================================================
  authz-meta-sender-constraining:
    description: >-
      SC-1 (high). Access tokens must be sender-constrained. The AS must
      advertise DPoP (`dpop_signing_alg_values_supported`, RFC 9449) or mTLS
      certificate-bound tokens (`tls_client_certificate_bound_access_tokens:
      true`, RFC 8705). Bearer-only is not acceptable at the high tier.
    message: "API Authorization (SC-1, high): advertise DPoP (`dpop_signing_alg_values_supported`) or mTLS-bound tokens."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#sc-1
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: [dpop_signing_alg_values_supported]
            - required: [tls_client_certificate_bound_access_tokens]
              properties:
                tls_client_certificate_bound_access_tokens:
                  const: true

  # =========================================================================
  # Pushed Authorization Requests — PAR-1 (high)
  # =========================================================================
  authz-meta-par-required:
    description: >-
      PAR-1 (high). The AS must require Pushed Authorization Requests
      (`require_pushed_authorization_requests: true`) and advertise the
      `pushed_authorization_request_endpoint` (RFC 9126). PAR moves the
      authorization request off the front channel.
    message: "API Authorization (PAR-1, high): require PAR (`require_pushed_authorization_requests: true`) and advertise its endpoint."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#par-1
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [pushed_authorization_request_endpoint, require_pushed_authorization_requests]
          properties:
            require_pushed_authorization_requests:
              const: true

  # =========================================================================
  # Signing algorithms — ALG-1 (normal), ALG-2 (high)
  # =========================================================================
  authz-meta-no-none-alg:
    description: >-
      ALG-1 (normal). No advertised signing-algorithm list may include `none`.
      The `none` algorithm disables signature verification entirely.
    message: "API Authorization (ALG-1, normal): signing-algorithm lists must not include `none`."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#alg-1
    given:
      - $.id_token_signing_alg_values_supported
      - $.token_endpoint_auth_signing_alg_values_supported
      - $.request_object_signing_alg_values_supported
      - $.introspection_signing_alg_values_supported
      - $.userinfo_signing_alg_values_supported
      - $.dpop_signing_alg_values_supported
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          items:
            not:
              const: none

  authz-meta-asym-signing:
    description: >-
      ALG-2 (high). Advertised signing algorithms must be asymmetric; symmetric
      HMAC (`HS*`) algorithms are not permitted at the high tier because they
      rely on a shared secret.
    message: "API Authorization (ALG-2, high): symmetric `HS*` signing algorithms are not permitted; use asymmetric (e.g. PS256/ES256)."
    severity: error
    documentationUrl: https://apicommons.org/api-authorization#alg-2
    given:
      - $.id_token_signing_alg_values_supported
      - $.token_endpoint_auth_signing_alg_values_supported
      - $.request_object_signing_alg_values_supported
      - $.introspection_signing_alg_values_supported
      - $.userinfo_signing_alg_values_supported
      - $.dpop_signing_alg_values_supported
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          items:
            not:
              pattern: "^HS"