openapi: 3.0.3
info:
  title: Retained authentication compatibility operations
  version: 1.0.0
  description: Explicitly enrolled private interface. Keeps existing provider writers and AUP authority during migration.
x-activation: explicit-enrolment
components:
  responses:
    Accepted:
      description: Desired work, command receipt and exact outcome committed durably; no-store. Exact retries return the recorded outcome.
      content:
        application/json:
          schema:
            $ref: 'compatibility.schemas.yaml#/schemas/WorkAccepted'
  securitySchemes:
    PolicyReader:
      type: http
      scheme: bearer
      description: Separately enrolled API and SSH Access policy readers, each with its own credential; distinct from every session and work credential.
    CompatibilityDispatcher:
      type: http
      scheme: bearer
      description: Enrolled API dispatcher for durable compatibility work; no arbitrary provider operations.
security:
  - CompatibilityDispatcher: []
paths:
  /internal/compat/v1/policy:
    get:
      operationId: readLegacyPolicyRequirement
      security:
        - PolicyReader: []
      description: Read the current legacy AUP requirement independently of member identity or provider binding. Never read acceptance or consult a browser session.
      responses:
        '200':
          description: Current policy requirement with fresh authority evidence; no-store.
          content:
            application/json:
              schema:
                $ref: 'compatibility.schemas.yaml#/schemas/PolicyRequirement'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
    post:
      operationId: readLegacyPolicy
      security:
        - PolicyReader: []
      description: Resolve current verified Party/GitLab association and read legacy AUP. Never consult or require a browser/API/NextAuth session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'compatibility.schemas.yaml#/schemas/PolicyLookup'
      responses:
        '200':
          description: Correlated current legacy policy evidence; no-store. Authority failure must never become required/current.
          content:
            application/json:
              schema:
                $ref: 'compatibility.schemas.yaml#/schemas/PolicyStatus'
        '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'
  /internal/compat/v1/accounts/ensure:
    post:
      operationId: ensureCompatibilityAccount
      description: Record one desired account/personal-setup revision under the unique Party/provider/instance/scope key. Effects follow asynchronously.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'compatibility.schemas.yaml#/schemas/EnsureAccount'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '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'
  /internal/compat/v1/accounts/lookup:
    post:
      operationId: findCompatibilityAccountWork
      description: Read-only lookup by stable account business identity, allowing later logins to resume existing work without its former session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'compatibility.schemas.yaml#/schemas/AccountLookup'
      responses:
        '200':
          description: Current complete account work status; no-store.
          content:
            application/json:
              schema:
                $ref: 'compatibility.schemas.yaml#/schemas/WorkStatus'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '403':
          $ref: 'common.schemas.yaml#/responses/Forbidden'
        '404':
          description: No work for this enrolled Party/provider scope.
          content:
            application/json:
              schema:
                $ref: 'common.schemas.yaml#/schemas/Error'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/compat/v1/credentials/ensure:
    post:
      operationId: ensureCompatibilityCredentials
      description: Schedule credentials under the unique session-ref/generation/GitLab-binding key. Scope is server-configured. Recheck the exact API fence before effects and exposing results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'compatibility.schemas.yaml#/schemas/EnsureCredentials'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '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'
  /internal/compat/v1/credentials/revoke:
    post:
      operationId: revokeCompatibilityCredentials
      description: Persist a terminal fence and cleanup, including unknown/late token issuance. Does not require live Party or AUP authority.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'compatibility.schemas.yaml#/schemas/RevokeCredentials'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '409':
          $ref: 'common.schemas.yaml#/responses/Conflict'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'
  /internal/compat/v1/work/{workId}:
    get:
      operationId: getCompatibilityWork
      description: Read current progress without scheduling effects; server recovery owns retries. No browser polling.
      parameters:
        - name: workId
          in: path
          required: true
          schema:
            $ref: 'common.schemas.yaml#/schemas/UUID'
      responses:
        '200':
          description: Complete singular progress view, with its own revision and redacted reason; no-store.
          content:
            application/json:
              schema:
                $ref: 'compatibility.schemas.yaml#/schemas/WorkStatus'
        '400':
          $ref: 'common.schemas.yaml#/responses/Invalid'
        '401':
          $ref: 'common.schemas.yaml#/responses/Unauthenticated'
        '404':
          description: Unknown work ID; no-store.
          content:
            application/json:
              schema:
                $ref: 'common.schemas.yaml#/schemas/Error'
        '503':
          $ref: 'common.schemas.yaml#/responses/Unavailable'