openapi: 3.0.3
info:
  title: API-owned browser authentication
  version: 1.0.0
  description: Explicitly enrolled technical protocol. Activation requires the coordinated authentication cutover.
x-activation: explicit-enrolment
components:
  securitySchemes:
    PartySession:
      type: apiKey
      in: cookie
      name: pharos_session
security:
  - PartySession: []
paths:
  /auth/oidc/start:
    post:
      operationId: startOIDCLogin
      tags: [session]
      security: []
      description: Enforce configured Origin/CSRF rules and persist a browser-bound login attempt before redirecting.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: 'session.schemas.yaml#/schemas/LoginStart'
      responses:
        '303':
          description: Configured AAI authorisation URL; transient callback cookie and Cache-Control no-store.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /auth/oidc/callback:
    get:
      operationId: completeOIDCLogin
      tags: [session]
      security: []
      description: Require browser-bound state and exactly one of code/error; reject duplicate parameters and enforce the normative OIDC checks.
      parameters:
        - {name: state, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 512}}
        - {name: code, in: query, schema: {type: string, minLength: 1, maxLength: 8192}}
        - {name: error, in: query, schema: {type: string, minLength: 1, maxLength: 256}}
        - {name: error_description, in: query, schema: {type: string, maxLength: 2048}}
        - {name: iss, in: query, schema: {type: string, maxLength: 2048}}
        - {name: session_state, in: query, schema: {type: string, maxLength: 512}}
      responses:
        '303':
          description: Validated same-origin destination; rotate session, clear callback cookie, no-store and no-referrer. On rejection redirect only to the configured error page without a session.
          headers:
            Location:
              schema:
                type: string
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /auth/complete:
    get:
      operationId: completeSameOriginNavigation
      tags: [session]
      description: Token-free same-origin landing document after the OIDC redirect; starts a fresh navigation so Strict cookies accompany the application request.
      parameters:
        - name: return_to
          in: query
          required: true
          schema:
            $ref: 'session.schemas.yaml#/schemas/LoginStart/properties/return_to'
      responses:
        '200':
          description: No-store HTML document with a same-origin navigation to the configured allowlisted return path. No credential or identity appears in the URL or document.
          content:
            text/html:
              schema:
                type: string
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
  /auth/error:
    get:
      operationId: showAuthenticationFailure
      tags: [session]
      description: Fixed same-origin retry page; it conveys no authentication authority.
      responses:
        '401':
          description: No-store sign-in retry document with no provider error text or credential material.
          content:
            text/html:
              schema:
                type: string
  /auth/v1/session:
    get:
      operationId: getBrowserSession
      tags: [session]
      description: Read valid limited or business-session status. Do not poll; this read never schedules provider work.
      responses:
        '200':
          description: Current eligible Party and explicit policy/provider readiness; no-store.
          content:
            application/json:
              schema:
                $ref: 'session.schemas.yaml#/schemas/SessionStatus'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /auth/v1/onboarding/resume:
    post:
      operationId: resumeBrowserOnboarding
      tags: [session]
      description: Limited-session operation with Origin/CSRF protection. Derive Party, provider scope and desired work from current server authority.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'session.schemas.yaml#/schemas/ResumeRequest'
      responses:
        '202':
          description: Intent and recorded outcome are durable, or required work is already ready; no-store.
          content:
            application/json:
              schema:
                $ref: 'session.schemas.yaml#/schemas/ResumeAccepted'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '409':
          $ref: 'common.schemas.yaml#/responses/Conflict'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /auth/v1/logout:
    post:
      operationId: revokeBrowserSession
      tags: [session]
      description: Origin/CSRF protected. Fence local authority and record cleanup durably without Party/provider/AUP availability; clear the cookie.
      responses:
        '204':
          description: Revoked or already absent/expired; no-store. External cleanup may remain pending.
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /auth/oidc/logout:
    post:
      operationId: endOIDCSession
      tags: [session]
      description: Origin/CSRF protected RP-initiated logout. Revoke local authority durably, clear browser cookies and redirect through the enrolled provider end-session endpoint to the exact registered browser origin.
      responses:
        '303':
          description: On success, the validated provider end-session URL after durable local revocation and cookie clearing. On operational failure, the fixed /auth/logout-error retry page; cookies remain available for retry. No-store and no-referrer.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
  /auth/logout-error:
    get:
      operationId: showLogoutFailure
      tags: [session]
      security: []
      description: Fixed same-origin logout retry page. It conveys no authentication authority and never clears session or callback cookies.
      responses:
        '503':
          description: No-store HTML with a same-origin referrer policy, explaining that the session may remain active and preserving Origin for the protected retry form.
          content:
            text/html:
              schema:
                type: string