openapi.yaml

openapi: 3.0.3
info:
  title: Marreq API (partial contract)
  description: |
    Subset of the Marreq JSON API for interchangeable frontends.
    All application routes are under `/api`. Many more paths exist; see `marreq-core/src/api/mod.rs` and README.
  version: 0.1.0
servers:
  - url: /api
    description: Same-origin (nginx proxy or Vite dev proxy)
  - url: http://localhost:8000/api
    description: Direct Rocket (local)

paths:
  /auth/providers:
    get:
      summary: Discover enabled browser authentication methods
      operationId: authProviders
      responses:
        '200':
          description: Public provider names only; no credentials or protocol secrets
          content:
            application/json:
              schema:
                type: object
                required: [password_enabled, external]
                properties:
                  password_enabled:
                    type: boolean
                  external:
                    type: array
                    items:
                      type: object
                      required: [id, display_name]
                      properties:
                        id: { type: string }
                        display_name: { type: string }
  /auth/external/{provider}/start:
    get:
      summary: Begin an external Authorization Code + PKCE login
      operationId: authExternalStart
      parameters:
        - in: path
          name: provider
          required: true
          schema: { type: string }
        - in: query
          name: return_to
          schema: { type: string, example: /projects }
      responses:
        '303': { description: Redirect to the provider }
        '400': { $ref: '#/components/responses/ApiError' }
        '404': { $ref: '#/components/responses/ApiError' }
  /auth/external/{provider}/callback:
    get:
      summary: Consume a single-use external authentication callback
      operationId: authExternalCallback
      parameters:
        - in: path
          name: provider
          required: true
          schema: { type: string }
        - in: query
          name: code
          schema: { type: string }
        - in: query
          name: state
          schema: { type: string }
      responses:
        '303': { description: Login or link completed; redirect to the local return path }
        '400': { $ref: '#/components/responses/ApiError' }
  /auth/csrf:
    get:
      summary: Get or mint CSRF token
      operationId: authCsrf
      responses:
        '200':
          description: CSRF token for X-CSRF-Token header
          content:
            application/json:
              schema:
                type: object
                required: [csrf_token]
                properties:
                  csrf_token:
                    type: string
  /auth/login:
    post:
      summary: Session login (JSON)
      operationId: authLogin
      parameters:
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Logged in; Set-Cookie session + csrf
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  user:
                    type: object
        '400':
          $ref: '#/components/responses/ApiError'
  /auth/logout:
    post:
      summary: End session
      operationId: authLogout
      parameters:
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /auth/me:
    get:
      summary: Current user (session)
      operationId: authMe
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Current user
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/ApiError'
  /dashboard:
    get:
      summary: SPA dashboard payload (user + decorated projects + CSRF)
      operationId: dashboardJson
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Dashboard context for the home view
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/ApiError'
  /projects:
    get:
      summary: List projects for session user
      operationId: listProjectsSession
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Project list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/ApiError'

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
      description: |
        Rocket private session cookie: typically `session` on HTTP (localhost) or
        `__Host-session` when `MARREQ_SECURE_SESSION_COOKIE=1` over HTTPS.
        Use `fetch(..., { credentials: 'include' })`.
  responses:
    ApiError:
      description: Structured error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
              error:
                type: string
              message:
                type: string