openapi: 3.0.3
info:
  title: TrustNet RP machine plane
  version: 1.0.0
  description: |
    The RP-facing machine plane (ADR-0010): `rp.trustnet.app/api/*`. Relying
    parties call these endpoints server-to-server on behalf of a consented
    user, authenticated by the OAuth2 access token Hydra issued at consent.

    This is a long-lived external commitment — a breaking change here breaks
    every RP. Subjects in payloads are PPIDs, always (G18); no response on this
    plane may ever contain an account_id or persona_id.
security:
  - bearerAuth: []
paths:
  /api/rp/v1/healthz:
    get:
      operationId: rpHealthz
      summary: Liveness probe
      description: |
        Static liveness only — unlike the first-party /api/healthz this carries
        no build/pid detail, which would be fingerprinting material to an RP.
      responses:
        "200":
          description: The plane is up.
          content:
            application/json:
              schema:
                type: object
                required: [status]
                additionalProperties: false
                properties:
                  status:
                    type: string
                    enum: [ok]
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/rp/v1/userinfo:
    get:
      operationId: rpUserinfo
      summary: Consented claims for the token's persona
      description: |
        Returns the claims the user approved at consent for the persona named
        by the presented access token, with their current values. The `sub` is
        the pairwise subject (PPID) — never an account_id or persona_id. Every
        read is recorded as a disclosure event (claim names only).
      responses:
        "200":
          description: The consented claims for the token's persona.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The token's scope does not cover this request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RPError"
        "502":
          description: Upstream verification failed; retry is safe.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RPError"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  responses:
    Unauthorized:
      description: Missing, expired, revoked or otherwise invalid token.
      headers:
        WWW-Authenticate:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RPError"

  schemas:
    RPError:
      type: object
      required: [error]
      additionalProperties: false
      properties:
        error:
          type: string
          enum: [invalid_token, insufficient_scope, temporarily_unavailable]

    # The consented claims, sub first. additionalProperties is false so an
    # unexpected field — the account_id/persona_id leak the machine plane
    # exists to prevent (G18) — fails the contract, not just the egress
    # harness. The claim set is the closed pool catalog (SP-12).
    UserInfo:
      type: object
      required: [sub]
      additionalProperties: false
      properties:
        sub:
          type: string
          description: The pairwise subject id (PPID).
        name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        middle_name:
          type: string
        nickname:
          type: string
        preferred_username:
          type: string
        profile:
          type: string
        picture:
          type: string
        website:
          type: string
        email:
          type: string
        gender:
          type: string
        birthdate:
          type: string
        zoneinfo:
          type: string
        locale:
          type: string
        phone_number:
          type: string