openapi: 3.0.3
info:
  title: Galaxy Auth / Session Service Internal API
  version: v1
  description: |
    This specification documents the implemented `galaxy/authsession` v1
    trusted internal REST contract.

    Contract rules:
    - the internal surface lives under `/api/v1/internal`;
    - all request and response bodies are JSON only;
    - read operations return canonical session DTO wrappers;
    - mutating operations return explicit `200` JSON acknowledgements;
    - mutation requests carry audit metadata as `reason_code` and `actor`;
    - `BlockUser` accepts exactly one of `user_id` or `email`;
    - `ListUserSessions` is newest-first and unpaginated in v1.
tags:
  - name: InternalAuthSession
    description: Trusted internal session read, revoke, and block operations.
paths:
  /api/v1/internal/sessions/{device_session_id}:
    get:
      tags:
        - InternalAuthSession
      operationId: getSession
      summary: Read one device session
      parameters:
        - $ref: "#/components/parameters/DeviceSessionID"
      responses:
        "200":
          description: The requested device session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSessionResponse"
        "404":
          $ref: "#/components/responses/SessionNotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/users/{user_id}/sessions:
    get:
      tags:
        - InternalAuthSession
      operationId: listUserSessions
      summary: List all active and revoked sessions of one user
      description: |
        Returns the full v1 session list for one user. Results are ordered from
        newest to oldest and are intentionally unpaginated in v1.
      parameters:
        - $ref: "#/components/parameters/UserID"
      responses:
        "200":
          description: |
            Sessions belonging to the requested user. Returns an empty array
            when the user has no stored sessions, including unknown `user_id`
            values.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListUserSessionsResponse"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/sessions/{device_session_id}/revoke:
    post:
      tags:
        - InternalAuthSession
      operationId: revokeDeviceSession
      summary: Revoke one device session
      parameters:
        - $ref: "#/components/parameters/DeviceSessionID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevokeDeviceSessionRequest"
      responses:
        "200":
          description: Explicit idempotent acknowledgement of the revoke result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevokeDeviceSessionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/SessionNotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/users/{user_id}/sessions/revoke-all:
    post:
      tags:
        - InternalAuthSession
      operationId: revokeAllUserSessions
      summary: Revoke all sessions of one user
      parameters:
        - $ref: "#/components/parameters/UserID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevokeAllUserSessionsRequest"
      responses:
        "200":
          description: Explicit idempotent acknowledgement of the bulk revoke result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevokeAllUserSessionsResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/SubjectNotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/user-blocks:
    post:
      tags:
        - InternalAuthSession
      operationId: blockUser
      summary: Block future auth flow for one subject and revoke active sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BlockUserRequest"
      responses:
        "200":
          description: Explicit idempotent acknowledgement of the block result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockUserResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/SubjectNotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
components:
  parameters:
    DeviceSessionID:
      name: device_session_id
      in: path
      required: true
      description: Stable identifier of one device session.
      schema:
        type: string
    UserID:
      name: user_id
      in: path
      required: true
      description: Stable identifier of one user.
      schema:
        type: string
  schemas:
    Actor:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          description: Machine-readable actor type such as `system`, `service`, or `admin`.
        id:
          type: string
          description: Optional stable identifier of the initiating actor.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/ErrorBody"
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable internal API error code.
        message:
          type: string
          description: Human-readable error description safe for trusted internal callers.
    Session:
      type: object
      additionalProperties: false
      required:
        - device_session_id
        - user_id
        - client_public_key
        - status
        - created_at
      properties:
        device_session_id:
          type: string
        user_id:
          type: string
        client_public_key:
          type: string
          description: Standard base64-encoded raw 32-byte Ed25519 public key of the device session.
        status:
          type: string
          enum:
            - active
            - revoked
        created_at:
          type: string
          format: date-time
          description: RFC3339 UTC timestamp when the session was created.
        revoked_at:
          type: string
          format: date-time
          nullable: true
          description: RFC3339 UTC timestamp when the session was revoked.
        revoke_reason_code:
          type: string
          nullable: true
          description: Machine-readable revoke reason code when the session is revoked.
        revoke_actor_type:
          type: string
          nullable: true
          description: Actor type that initiated the revoke.
        revoke_actor_id:
          type: string
          nullable: true
          description: Optional stable actor identifier that initiated the revoke.
    GetSessionResponse:
      type: object
      additionalProperties: false
      required:
        - session
      properties:
        session:
          $ref: "#/components/schemas/Session"
    ListUserSessionsResponse:
      type: object
      additionalProperties: false
      required:
        - sessions
      properties:
        sessions:
          type: array
          description: Full newest-first session list for the requested user.
          items:
            $ref: "#/components/schemas/Session"
    RevokeDeviceSessionRequest:
      type: object
      additionalProperties: false
      required:
        - reason_code
        - actor
      properties:
        reason_code:
          type: string
          description: Machine-readable revoke reason code.
        actor:
          $ref: "#/components/schemas/Actor"
    RevokeDeviceSessionResponse:
      type: object
      additionalProperties: false
      required:
        - outcome
        - device_session_id
        - affected_session_count
      properties:
        outcome:
          type: string
          enum:
            - revoked
            - already_revoked
        device_session_id:
          type: string
        affected_session_count:
          type: integer
          format: int64
          minimum: 0
    RevokeAllUserSessionsRequest:
      type: object
      additionalProperties: false
      required:
        - reason_code
        - actor
      properties:
        reason_code:
          type: string
          description: Machine-readable bulk revoke reason code.
        actor:
          $ref: "#/components/schemas/Actor"
    RevokeAllUserSessionsResponse:
      type: object
      additionalProperties: false
      required:
        - outcome
        - user_id
        - affected_session_count
        - affected_device_session_ids
      properties:
        outcome:
          type: string
          enum:
            - revoked
            - no_active_sessions
        user_id:
          type: string
        affected_session_count:
          type: integer
          format: int64
          minimum: 0
        affected_device_session_ids:
          type: array
          items:
            type: string
    BlockUserRequest:
      oneOf:
        - $ref: "#/components/schemas/BlockUserByUserIDRequest"
        - $ref: "#/components/schemas/BlockUserByEmailRequest"
    BlockUserByUserIDRequest:
      type: object
      additionalProperties: false
      required:
        - user_id
        - reason_code
        - actor
      properties:
        user_id:
          type: string
        reason_code:
          type: string
          description: Machine-readable block reason code.
        actor:
          $ref: "#/components/schemas/Actor"
    BlockUserByEmailRequest:
      type: object
      additionalProperties: false
      required:
        - email
        - reason_code
        - actor
      properties:
        email:
          type: string
          format: email
        reason_code:
          type: string
          description: Machine-readable block reason code.
        actor:
          $ref: "#/components/schemas/Actor"
    BlockUserResponse:
      type: object
      additionalProperties: false
      required:
        - outcome
        - subject_kind
        - subject_value
        - affected_session_count
        - affected_device_session_ids
      properties:
        outcome:
          type: string
          enum:
            - blocked
            - already_blocked
        subject_kind:
          type: string
          enum:
            - user_id
            - email
        subject_value:
          type: string
        affected_session_count:
          type: integer
          format: int64
          minimum: 0
        affected_device_session_ids:
          type: array
          items:
            type: string
  responses:
    InvalidRequestError:
      description: Request path, parameters, or body fields are invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            invalidRequest:
              value:
                error:
                  code: invalid_request
                  message: reason_code must not be empty
    SessionNotFoundError:
      description: The referenced device session does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            sessionNotFound:
              value:
                error:
                  code: session_not_found
                  message: session not found
    SubjectNotFoundError:
      description: The referenced internal block or bulk-revoke subject does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            subjectNotFound:
              value:
                error:
                  code: subject_not_found
                  message: subject not found
    ServiceUnavailableError:
      description: A required dependency is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            unavailable:
              value:
                error:
                  code: service_unavailable
                  message: service is unavailable
    InternalError:
      description: Unexpected internal failure while processing the request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            internal:
              value:
                error:
                  code: internal_error
                  message: internal server error