openapi.yaml

openapi: 3.1.0
info:
  title: OpenRisk API
  version: 1.0.0
  description: |
    Modern, intelligent risk management platform API.
    Part of the OpenDefender suite with AI-driven risk assessment, mitigation tracking, and security integration.
    
    **Authentication**: All protected endpoints require a Bearer JWT token in the `Authorization` header.
    
    **Base URL**: `/api/v1`
  contact:
    name: OpenDefender Team
  license:
    name: GNU Affero General Public License v3.0 only (AGPL-3.0-only)
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
  - url: /api/v1
    description: Production API

tags:
  - name: Health
    description: Health check and status
  - name: Authentication
    description: Login and user management
  - name: Risks
    description: Risk management - create, read, update, delete risks
  - name: Mitigations
    description: Mitigation planning and tracking
  - name: Compliance
    description: Compliance frameworks, controls, and evidence (M1)
  - name: Assets
    description: Asset management
  - name: Statistics
    description: Dashboard and analytics
  - name: Export
    description: Data export
  - name: Gamification
    description: Gamification and user profiles
  - name: Saved Views
    description: Named filter/sort/column views of a register (#580)

paths:
  /health:
    get:
      tags:
        - Health
      summary: Health check
      operationId: healthCheck
      description: Check API health status
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: UP
                  version:
                    type: string
                    example: 1.0.0
                  db:
                    type: string
                    example: CONNECTED
        '503':
          description: API is running but its database is unreachable
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: DOWN
                  version:
                    type: string
                    example: 1.0.0
                  db:
                    type: string
                    example: DISCONNECTED

  # ==================== AUTHENTICATION ====================
  /auth/login:
    post:
      tags:
        - Authentication
      summary: Login with email and password
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginInput'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # OR26-03 — deferrable MFA enrolment. The organization-wide grace window
  # after which a privileged account (admin/root, or the RSSI business role)
  # must hold a second factor. Reading is open to any authenticated member —
  # everyone subject to a deadline deserves to see what it is. Writing is
  # admin-only and lands in the governance audit trail.
  /security/mfa-policy:
    get:
      tags:
        - Authentication
      summary: Read the organization's MFA grace policy
      operationId: getMfaPolicy
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The tenant's policy, or the shipped default when unset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MFAPolicy'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Authentication
      summary: Set the organization's MFA grace policy
      operationId: updateMfaPolicy
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMFAPolicyInput'
      responses:
        '200':
          description: The saved policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MFAPolicy'
        '400':
          description: grace_days missing or out of the 0..90 range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Not an administrator of this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/me:
    get:
      tags:
        - Profile
      summary: Get the caller's own profile and effective preferences
      operationId: getMyProfile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Own profile. `effective` resolves each preference as own choice, else the organization default.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyProfile'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
        - Profile
      summary: Update the caller's own profile and preferences
      description: >
        Partial update of the session's own user; no field selects another
        account. An omitted field is unchanged, an empty string clears it
        (full_name cannot be cleared). Email, username, role and status are
        not writable here.
      operationId: updateMyProfile
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfilePatch'
      responses:
        '200':
          description: Updated profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyProfile'
        '400':
          description: Invalid field; the message names it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/me/avatar:
    put:
      tags:
        - Profile
      summary: Upload the caller's avatar
      description: PNG, JPEG or WebP, at most 1 MB, decided by the file's bytes. Replaces and deletes any previous avatar.
      operationId: uploadMyAvatar
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Updated profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyProfile'
        '400':
          description: Not an accepted image, or larger than 1 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Profile
      summary: Remove the caller's avatar
      operationId: deleteMyAvatar
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Updated profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyProfile'

  /users/{id}/avatar:
    get:
      tags:
        - Profile
      summary: Read a user's avatar
      description: Served only when the user is an active member of the caller's organization; otherwise 404, exactly as for a user that does not exist.
      operationId: getUserAvatar
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The image
          content:
            image/png: { schema: { type: string, format: binary } }
            image/jpeg: { schema: { type: string, format: binary } }
            image/webp: { schema: { type: string, format: binary } }
        '404':
          description: No avatar visible to the caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/password/change:
    post:
      tags:
        - Authentication
      summary: Change the signed-in user's own password
      description: >
        Requires the current password; the new one must pass the password policy.
        On success every session of the user ends and the calling device is
        given a fresh one (new session cookies, and the pair in the body), and a
        notice is emailed. If no new session can be minted, `reauthenticate` is
        true. Rate limited with the other authentication routes. No password is
        ever logged or echoed.
      operationId: changePassword
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [current_password, new_password]
              properties:
                current_password: { type: string, format: password }
                new_password: { type: string, format: password }
                locale: { type: string, enum: [fr, en] }
      responses:
        '200':
          description: Password changed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  reauthenticate: { type: boolean }
                  token_pair:
                    type: object
                    properties:
                      access_token: { type: string }
                      refresh_token: { type: string }
                      expires_in: { type: integer }
                  csrf_token: { type: string }
        '400':
          description: "`weak_password` (with `assessment`) or `same_password`"
        '401':
          description: No session
        '403':
          description: "`wrong_current_password`"
        '409':
          description: "`no_local_password`: the account signs in through an identity provider"
        '429':
          description: Rate limited

  /auth/me:
    get:
      tags:
        - Authentication
      summary: The signed-in user, their MFA state and how they can prove who they are
      description: >
        Re-read on every call, never taken from the token alone. `mfa` is
        omitted when the server cannot resolve it (read that as unknown, not as
        "fine"). `has_password` is false for an account that signs in through
        an identity provider; such an account confirms sensitive changes, like
        turning MFA off, with an authenticator code instead (#754, D-061). It is
        a boolean, never the hash.
      operationId: getMe
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The current session's user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
        '401':
          description: No session
        '404':
          description: The session's user no longer exists

  /auth/mfa/disable:
    post:
      tags:
        - Authentication
      summary: Turn off two-factor authentication for the signed-in user
      description: >
        An open session is not enough (#754). The body carries the current
        `password`, or, when `/auth/me` says `has_password: false`, a current
        six-digit `code` from the authenticator app; backup codes are not
        accepted, and a code never replaces the password of an account that has
        one. Refused for roles the deployment requires MFA for. Each attempt
        counts against a per-account budget of 5 per 15 minutes (on top of the
        per-IP limit). On success the TOTP secret and every backup code are
        deleted in one transaction, the attempt is audited, and the owner is
        notified by email and in-app. Neither the password nor the code is ever
        logged or echoed. Errors carry a stable `code` (see DisableMFAError).
      operationId: disableMfa
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisableMFAInput'
      responses:
        '200':
          description: MFA is off
          content:
            application/json:
              schema:
                type: object
                required: [message]
                properties:
                  message: { type: string }
        '400':
          description: The body is not JSON
        '401':
          description: "`wrong_password` or `wrong_code`. Not a session error: the session stays valid."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableMFAError'
        '403':
          description: "`mfa_required_by_role`"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableMFAError'
        '404':
          description: "`not_enrolled`"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableMFAError'
        '409':
          description: "`no_local_password`: no password and no way to check a code on this deployment"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableMFAError'
        '429':
          description: "`too_many_attempts`, or the per-IP limit"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableMFAError'

  # ==================== ORGANIZATION ====================
  /organization:
    get:
      tags:
        - Organization
      summary: Get the caller's organization profile
      description: Requires organization:read or organization:members:read. The organization is the session's tenant.
      operationId: getOrganization
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Organization profile with live membership counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationView'
        '403':
          description: Missing permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Organization
      summary: Update the caller's organization profile and regional settings
      description: >
        Requires organization:update. Partial update — an omitted field is left
        unchanged, an empty string clears an optional field. The organization is
        the session's tenant; there is no id to choose. Settings keys this
        endpoint does not own (such as the display currency) are preserved.
      operationId: updateOrganization
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationProfilePatch'
      responses:
        '200':
          description: Updated organization profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationView'
        '400':
          description: Invalid field; the message names it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing organization:update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /organization/logo:
    put:
      tags:
        - Organization
      summary: Upload the organization logo
      description: Requires organization:update. PNG, JPEG or WebP, at most 1 MB, decided by the file's bytes. Replaces and deletes any previous logo.
      operationId: uploadOrganizationLogo
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Updated organization profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationView'
        '400':
          description: Not an accepted image, or larger than 1 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing organization:update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Organization
      summary: Remove the organization logo
      description: Requires organization:update.
      operationId: deleteOrganizationLogo
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Updated organization profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationView'
        '403':
          description: Missing organization:update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Organization
      summary: Read the caller's organization logo
      description: Any member. There is no id; only the session's organization is readable.
      operationId: getOrganizationLogo
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The image
          content:
            image/png: { schema: { type: string, format: binary } }
            image/jpeg: { schema: { type: string, format: binary } }
            image/webp: { schema: { type: string, format: binary } }
        '404':
          description: No logo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /organization/branding:
    get:
      tags:
        - Organization
      summary: Read the caller's organization branding
      description: Any member — every member's interface wears the name, logo and accent.
      operationId: getOrganizationBranding
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Branding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationBranding'

  # ==================== RISKS ====================
  /risks:
    get:
      tags:
        - Risks
      summary: List all risks
      operationId: listRisks
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
        - name: sort_by
          in: query
          schema:
            type: string
            description: Field to sort by (e.g., score, title, impact)
      responses:
        '200':
          description: List of risks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Risk'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      tags:
        - Risks
      summary: Create a new risk
      operationId: createRisk
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRiskInput'
      responses:
        '201':
          description: Risk created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Risk'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /risks/{id}:
    get:
      tags:
        - Risks
      summary: Get risk details
      operationId: getRisk
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Risk UUID
      responses:
        '200':
          description: Risk details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Risk'
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

    patch:
      tags:
        - Risks
      summary: Update risk
      operationId: updateRisk
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRiskInput'
      responses:
        '200':
          description: Risk updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Risk'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

    delete:
      tags:
        - Risks
      summary: Delete risk
      operationId: deleteRisk
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Risk deleted
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

  # ==================== MITIGATIONS ====================
  /risks/{id}/mitigations:
    post:
      tags:
        - Mitigations
      summary: Add mitigation to risk
      operationId: addMitigation
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Risk UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMitigationInput'
      responses:
        '201':
          description: Mitigation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mitigation'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

  /risks/{id}/financial:
    get:
      tags:
        - Financial Quantification
      summary: Full financial assessment for one risk
      description: >
        Returns the complete Cyber Risk Quantification for a risk (spec §9):
        SLE (explicit/composed/reference), downtime cost, worst/average loss,
        ALE (XAF+USD), remediation cost, residual ALE and ROSI.
      operationId: getRiskFinancial
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Financial assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialAssessment'
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

  /risks/{id}/simulate:
    post:
      tags:
        - Financial Quantification
      summary: What-if investment simulation (non-persisting)
      description: >
        Recomputes the financial assessment with the supplied overrides layered
        on the risk's stored drivers, WITHOUT persisting anything. Powers the
        CISO/CFO investment-scenario simulator.
      operationId: simulateRiskFinancial
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateFinancialInput'
      responses:
        '200':
          description: Simulated financial assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialAssessment'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

  /analytics/financial:
    get:
      tags:
        - Financial Quantification
      summary: Tenant-wide financial posture (CFO/CISO dashboard)
      description: >
        Portfolio ALE (current, worst-case, residual), remediation budget,
        portfolio ROSI, breakdown by criticality and the top financial exposures.
      operationId: getFinancialSummary
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Financial summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialSummary'
        '401':
          description: Unauthorized

  /risks/{id}/transfer-owner:
    post:
      tags:
        - Ownership
      summary: Transfer the ownership of a risk to another member
      description: >
        Hands the owner slot to another active member of the caller's
        organisation, and changes nothing else. The previous owner is captured
        before the write, the audit trail records a `transfer` entry
        (previous owner → new owner, actor), and the new owner receives an
        in-app notification unless they performed the transfer themselves.
        Requires `risks:update`. A risk of another
        organisation reads as not found.
      operationId: transferRiskOwner
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferOwnerRequest'
      responses:
        '200':
          description: Ownership transferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferOwnershipResult'
        '400':
          description: >
            Malformed id or new_owner_id, or the new owner is not an active
            member of the organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Missing `risks:update`
        '404':
          description: Not found in the caller's organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The new owner already owns it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /mitigations/{id}/transfer-owner:
    post:
      tags:
        - Ownership
      summary: Transfer the ownership of a mitigation to another member
      description: >
        Hands the owner slot to another active member of the caller's
        organisation, and changes nothing else. The previous owner is captured
        before the write, the audit trail records a `transfer` entry
        (previous owner → new owner, actor), and the new owner receives an
        in-app notification unless they performed the transfer themselves.
        Requires `mitigations:update`. A mitigation of another
        organisation reads as not found.
      operationId: transferMitigationOwner
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferOwnerRequest'
      responses:
        '200':
          description: Ownership transferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferOwnershipResult'
        '400':
          description: >
            Malformed id or new_owner_id, or the new owner is not an active
            member of the organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Missing `mitigations:update`
        '404':
          description: Not found in the caller's organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The new owner already owns it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /incidents/{id}/transfer-owner:
    post:
      tags:
        - Ownership
      summary: Transfer the ownership of an incident to another member
      description: >
        Hands the owner slot to another active member of the caller's
        organisation, and changes nothing else. The previous owner is captured
        before the write, the audit trail records a `transfer` entry
        (previous owner → new owner, actor), and the new owner receives an
        in-app notification unless they performed the transfer themselves.
        Requires `incidents:update`. An incident of another
        organisation reads as not found.
      operationId: transferIncidentOwner
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferOwnerRequest'
      responses:
        '200':
          description: Ownership transferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferOwnershipResult'
        '400':
          description: >
            Malformed id or new_owner_id, or the new owner is not an active
            member of the organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Missing `incidents:update`
        '404':
          description: Not found in the caller's organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The new owner already owns it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /risks/{id}/smart-score:
    get:
      tags:
        - Smart Risk Calculation
      summary: Multifactor smart risk score + breakdown
      description: >
        Computes (and caches on the risk) the multifactor "smart" risk score
        (spec §8): a 0–100 score blending business criticality, internet
        exposure, vulnerabilities/CVSS, control maturity, incident history,
        exploitability, financial value and live threat intel (CTI), each
        weighted by the tenant's configurable weights. Returns the radar-ready
        per-factor breakdown. The classic Score Engine (P × I × AC) is untouched.
      operationId: getRiskSmartScore
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Smart score with per-factor breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartRiskScore'
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

  /risks/{id}/smart-score/simulate:
    post:
      tags:
        - Smart Risk Calculation
      summary: Preview the smart score with custom weights (non-persisting)
      description: >
        Recomputes the smart score for a risk with the supplied factor weights
        WITHOUT persisting — powers the "tune the weighting live" simulator.
      operationId: simulateRiskSmartScore
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FactorWeightsInput'
      responses:
        '200':
          description: Simulated smart score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartRiskScore'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Risk not found

  /risk-scoring/weights:
    get:
      tags:
        - Smart Risk Calculation
      summary: Tenant's smart-risk factor weights
      description: >
        Returns the tenant's effective factor weights (custom or the built-in
        defaults) for the eight-factor multifactor model.
      operationId: getRiskScoringWeights
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Factor weights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskScoringWeights'
        '401':
          description: Unauthorized
    put:
      tags:
        - Smart Risk Calculation
      summary: Update the tenant's factor weights (admin)
      description: >
        Persists the tenant's custom factor weights. Weights are relative (the
        engine normalises them); each must be in [0,1] and at least one > 0.
        Admin only.
      operationId: updateRiskScoringWeights
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FactorWeightsInput'
      responses:
        '200':
          description: Updated weights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskScoringWeights'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (admin only)

  /mitigations/{mitigationId}:
    patch:
      tags:
        - Mitigations
      summary: Update mitigation details
      operationId: updateMitigation
      security:
        - bearerAuth: []
      parameters:
        - name: mitigationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMitigationInput'
      responses:
        '200':
          description: Mitigation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mitigation'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Mitigation not found

  /mitigations/{mitigationId}/toggle:
    patch:
      tags:
        - Mitigations
      summary: Toggle mitigation status (PLANNED ↔ DONE)
      operationId: toggleMitigationStatus
      security:
        - bearerAuth: []
      parameters:
        - name: mitigationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Status toggled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mitigation'
        '401':
          description: Unauthorized
        '404':
          description: Mitigation not found

  # ==================== MITIGATION SUB-ACTIONS ====================
  /mitigations/{id}/subactions:
    post:
      tags:
        - Mitigations
      summary: Create mitigation sub-action (checklist item)
      operationId: createMitigationSubAction
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Mitigation UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubActionInput'
      responses:
        '201':
          description: Sub-action created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MitigationSubAction'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Mitigation not found

  /mitigations/{id}/subactions/{subactionId}/toggle:
    patch:
      tags:
        - Mitigations
      summary: Toggle sub-action completed status
      operationId: toggleSubAction
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Mitigation UUID
        - name: subactionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Sub-action UUID
      responses:
        '200':
          description: Sub-action toggled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MitigationSubAction'
        '401':
          description: Unauthorized
        '404':
          description: Sub-action not found

  /mitigations/{id}/subactions/{subactionId}:
    delete:
      tags:
        - Mitigations
      summary: Delete mitigation sub-action
      operationId: deleteSubAction
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Mitigation UUID
        - name: subactionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Sub-action UUID
      responses:
        '204':
          description: Sub-action deleted
        '401':
          description: Unauthorized
        '404':
          description: Sub-action not found

  /mitigations/recommended:
    get:
      tags:
        - Mitigations
      summary: Get recommended mitigations (sorted by SPP score)
      operationId: getRecommendedMitigations
      responses:
        '200':
          description: Recommended mitigations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Mitigation'

  # ==================== COMPLIANCE (M1) ====================
  /compliance/catalogs:
    get:
      tags: [Compliance]
      summary: List regulatory control catalogs available to import (M2)
      description: >
        Static reference data (e.g. ISO 27001:2022's 93 Annex A controls) that can be
        bulk-imported into a tenant's own framework via POST
        /compliance/frameworks/{frameworkId}/import-catalog. Includes catalogs that are
        registered but not yet available (control_count: 0, available: false) so clients can
        show them as "coming soon" — see ROADMAP.md M2 for why COBAC/BCEAO/ANSSI-CM aren't
        modeled yet.
      operationId: listComplianceCatalogs
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: List of catalogs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ComplianceCatalogSummary'

  /compliance/frameworks/{frameworkId}/import-catalog:
    post:
      tags: [Compliance]
      summary: Bulk-import a regulatory catalog's controls into a framework (admin only, M2)
      description: >
        Idempotent — controls already present (matched by reference_code) are skipped, so
        calling this again after a catalog is extended only creates what's new.
      operationId: importComplianceCatalog
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportCatalogInput'
      responses:
        '200':
          description: Import result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportCatalogResult'
        '400':
          description: Unknown catalog key, or the catalog is not yet available
        '403':
          description: Forbidden — only Admin can import a catalog (same tier as creating a framework)
        '404':
          description: Framework not found

  /compliance/frameworks:
    get:
      tags: [Compliance]
      summary: List global compliance frameworks
      operationId: listComplianceFrameworks
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: List of frameworks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ComplianceFramework'
    post:
      tags: [Compliance]
      summary: Create a global compliance framework (admin only)
      operationId: createComplianceFramework
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFrameworkInput'
      responses:
        '201':
          description: Framework created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceFramework'
        '400':
          description: Invalid input
        '403':
          description: Forbidden — only Admin can create a global framework
        '409':
          description: A framework with this name and version already exists

  /compliance/frameworks/{frameworkId}:
    get:
      tags: [Compliance]
      summary: Get a compliance framework
      operationId: getComplianceFramework
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Framework
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceFramework'
        '404':
          description: Framework not found
    delete:
      tags: [Compliance]
      summary: Delete a compliance framework
      description: >
        Removes the framework and the calling tenant's controls under it.
        Admin/root-only. Note the framework row is global — deleting it removes
        it for every tenant (a known multi-tenant limitation; in practice each
        tenant imports its own frameworks).
      operationId: deleteComplianceFramework
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Framework deleted
        '403':
          description: Insufficient permissions
        '404':
          description: Framework not found

  /compliance/frameworks/{frameworkId}/progress:
    get:
      tags: [Compliance]
      summary: Get a tenant's compliance progress for a framework
      operationId: getComplianceProgress
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Progress summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceProgress'

  /compliance/frameworks/{frameworkId}/report:
    get:
      tags: [Compliance]
      summary: Download an official compliance report (PDF) for a framework
      description: >
        Generates, in a single click, a print-ready PDF compliance report for the
        framework: cover identity (organization, framework, date, requester), an
        executive summary (compliance %, per-status breakdown) and a detailed,
        paginated controls table (reference, name, status, evidence count, source
        citation). All data is strictly tenant-scoped — the framework is global
        but only the requesting tenant's controls and evidence appear. Suitable
        for COBAC/BCEAO/ISO one-click statements.
      operationId: generateComplianceReport
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: locale
          in: query
          required: false
          description: Fixed-label language of the report. Defaults to French.
          schema: { type: string, enum: [fr, en], default: fr }
      responses:
        '200':
          description: The compliance report as a PDF attachment.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '404':
          description: Framework not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /compliance/frameworks/{frameworkId}/controls:
    get:
      tags: [Compliance]
      summary: List a tenant's controls for a framework
      operationId: listComplianceControls
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: List of controls
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ComplianceControl'
    post:
      tags: [Compliance]
      summary: Instantiate a control for a tenant under this framework
      operationId: createComplianceControl
      security: [{ bearerAuth: [] }]
      parameters:
        - name: frameworkId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateControlInput'
      responses:
        '201':
          description: Control created (status defaults to not_implemented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceControl'
        '400':
          description: Invalid input
        '404':
          description: Framework not found
        '409':
          description: A control with this reference_code already exists for this tenant+framework

  /compliance/controls/{controlId}:
    get:
      tags: [Compliance]
      summary: Get a control
      operationId: getComplianceControl
      security: [{ bearerAuth: [] }]
      parameters:
        - name: controlId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Control
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceControl'
        '404':
          description: Control not found
    patch:
      tags: [Compliance]
      summary: Update a control (notably its implementation status)
      operationId: updateComplianceControl
      security: [{ bearerAuth: [] }]
      parameters:
        - name: controlId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateControlInput'
      responses:
        '200':
          description: Control updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceControl'
        '400':
          description: Invalid status value
        '404':
          description: Control not found
    delete:
      tags: [Compliance]
      summary: Delete a control (admin only)
      operationId: deleteComplianceControl
      security: [{ bearerAuth: [] }]
      parameters:
        - name: controlId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Control deleted
        '403':
          description: Forbidden — Delete is admin-only
        '404':
          description: Control not found

  /compliance/controls/{controlId}/evidences:
    get:
      tags: [Compliance]
      summary: List evidence attached to a control
      operationId: listComplianceEvidences
      security: [{ bearerAuth: [] }]
      parameters:
        - name: controlId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: List of evidence
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ControlEvidence'
    post:
      tags: [Compliance]
      summary: Upload a file as evidence for a control
      operationId: createComplianceEvidence
      security: [{ bearerAuth: [] }]
      parameters:
        - name: controlId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                description:
                  type: string
      responses:
        '201':
          description: Evidence uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlEvidence'
        '400':
          description: Missing file
        '404':
          description: Control not found

  /compliance/evidences/{evidenceId}/download:
    get:
      tags: [Compliance]
      summary: Download an evidence file
      description: |
        The only path to evidence file content — there is no public/static
        URL. Tenant ownership is re-verified on every call.
      operationId: downloadComplianceEvidence
      security: [{ bearerAuth: [] }]
      parameters:
        - name: evidenceId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Evidence not found

  /compliance/evidences/{evidenceId}:
    delete:
      tags: [Compliance]
      summary: Delete an evidence record and its file (admin only)
      operationId: deleteComplianceEvidence
      security: [{ bearerAuth: [] }]
      parameters:
        - name: evidenceId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Evidence deleted
        '403':
          description: Forbidden — Delete is admin-only
        '404':
          description: Evidence not found

  # ==================== GAP ANALYSIS / AUDITS / REMEDIATION / MAPPINGS ====================
  /compliance/gap-analysis:
    get:
      tags: [Compliance]
      summary: Analyse d'écarts — every unsatisfied control across the tenant's frameworks
      operationId: getGapAnalysis
      security: [{ bearerAuth: [] }]
      parameters:
        - name: framework_id
          in: query
          required: false
          description: Scope the analysis to a single framework.
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Gap analysis (roll-ups + open gaps).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GapAnalysis' }

  /compliance/control-mappings:
    get:
      tags: [Compliance]
      summary: List cross-framework control mappings
      operationId: listControlMappings
      security: [{ bearerAuth: [] }]
      parameters:
        - name: control_id
          in: query
          required: false
          description: Scope to mappings touching this control (as source or target).
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: The tenant's control mappings.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ControlMapping' }
    post:
      tags: [Compliance]
      summary: Link two controls across frameworks
      operationId: createControlMapping
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateControlMappingInput' }
      responses:
        '201':
          description: Mapping created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ControlMapping' }
        '400':
          description: Validation error (self-link, unknown control, bad relation).
        '409':
          description: A mapping between these controls already exists.

  /compliance/control-mappings/{mappingId}:
    delete:
      tags: [Compliance]
      summary: Delete a control mapping
      operationId: deleteControlMapping
      security: [{ bearerAuth: [] }]
      parameters:
        - name: mappingId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204': { description: Mapping deleted }
        '404': { description: Mapping not found }

  /compliance/audits:
    get:
      tags: [Compliance]
      summary: List a tenant's compliance audits
      operationId: listComplianceAudits
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: The tenant's audits.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ComplianceAudit' }
    post:
      tags: [Compliance]
      summary: Plan a compliance audit
      operationId: createComplianceAudit
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateAuditInput' }
      responses:
        '201':
          description: Audit created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ComplianceAudit' }
        '400': { description: Validation error }

  /compliance/audits/{id}:
    get:
      tags: [Compliance]
      summary: Get a compliance audit
      operationId: getComplianceAudit
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: The audit.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ComplianceAudit' }
        '404': { description: Audit not found }
    patch:
      tags: [Compliance]
      summary: Update a compliance audit (status, dates, summary…)
      operationId: updateComplianceAudit
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateAuditInput' }
      responses:
        '200':
          description: The updated audit.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ComplianceAudit' }
        '404': { description: Audit not found }
    delete:
      tags: [Compliance]
      summary: Delete a compliance audit
      operationId: deleteComplianceAudit
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204': { description: Audit deleted }
        '404': { description: Audit not found }

  /compliance/audits/{id}/generate-remediations:
    post:
      tags: [Compliance]
      summary: Auto-generate remediation plans for the gaps under an audit's framework
      operationId: generateRemediationsFromAudit
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '201':
          description: Remediation plans created (idempotent — skips gaps already covered).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenerateRemediationsResult' }
        '400': { description: Audit is program-wide (no framework) }
        '404': { description: Audit not found }

  /compliance/remediations:
    get:
      tags: [Compliance]
      summary: List a tenant's remediation plans
      operationId: listRemediations
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: control_id, in: query, required: false, schema: { type: string, format: uuid } }
        - { name: framework_id, in: query, required: false, schema: { type: string, format: uuid } }
        - { name: audit_id, in: query, required: false, schema: { type: string, format: uuid } }
        - { name: status, in: query, required: false, schema: { type: string, enum: [open, in_progress, completed, cancelled] } }
      responses:
        '200':
          description: The tenant's remediation plans.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/RemediationPlan' }
    post:
      tags: [Compliance]
      summary: Create a remediation plan
      operationId: createRemediation
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateRemediationInput' }
      responses:
        '201':
          description: Remediation plan created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RemediationPlan' }
        '400': { description: Validation error }

  /compliance/remediations/{id}:
    patch:
      tags: [Compliance]
      summary: Update a remediation plan (status, assignee, due date…)
      operationId: updateRemediation
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateRemediationInput' }
      responses:
        '200':
          description: The updated remediation plan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RemediationPlan' }
        '404': { description: Remediation plan not found }
    delete:
      tags: [Compliance]
      summary: Delete a remediation plan
      operationId: deleteRemediation
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204': { description: Remediation plan deleted }
        '404': { description: Remediation plan not found }

  # ==================== BOARD REPORT (M4) ====================
  /reports/board:
    get:
      tags: [BoardReport]
      summary: List a tenant's board reports (most recent first)
      operationId: listBoardReports
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: The tenant's board reports.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/BoardReport' }
    post:
      tags: [BoardReport]
      summary: Generate a monthly board report (draft)
      description: >
        Aggregates the tenant's risk register (by criticality) and compliance
        posture (per framework), estimates the annual financial exposure in FCFA,
        and asks the configured AI advisor to write a non-technical narrative for
        the board of directors. When ANTHROPIC_API_KEY is set a Claude advisor
        (claude-opus-4-8) writes the prose; otherwise, or on any API error, a
        deterministic template writes it (GeneratedByModel records which). The
        report is created as an editable DRAFT (human-in-the-loop) and must be
        approved before diffusion.
      operationId: generateBoardReport
      security: [{ bearerAuth: [] }]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GenerateBoardReportInput' }
      responses:
        '201':
          description: The generated draft report.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardReport' }

  /reports/board/{reportId}:
    get:
      tags: [BoardReport]
      summary: Get a board report (JSON)
      operationId: getBoardReport
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reportId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: The board report.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardReport' }
        '404':
          description: Report not found.
    patch:
      tags: [BoardReport]
      summary: Edit a draft board report's narrative
      description: Only DRAFT reports are editable; an approved report is frozen (returns 400/validation).
      operationId: updateBoardReport
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reportId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateBoardReportInput' }
      responses:
        '200':
          description: The updated report.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardReport' }
        '404':
          description: Report not found.
    delete:
      tags: [BoardReport]
      summary: Delete a board report
      operationId: deleteBoardReport
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reportId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Report deleted.
        '404':
          description: Report not found.

  /reports/board/{reportId}/approve:
    post:
      tags: [BoardReport]
      summary: Approve a draft board report (human-in-the-loop)
      description: Marks the report approved, recording the approver and timestamp. Idempotent.
      operationId: approveBoardReport
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reportId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: The approved report.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardReport' }
        '404':
          description: Report not found.

  /reports/board/{reportId}/pdf:
    get:
      tags: [BoardReport]
      summary: Download a board report as a polished PDF
      operationId: downloadBoardReportPDF
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reportId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: The board report as a PDF attachment.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '404':
          description: Report not found.

  # ==================== ASSETS ====================
  /assets:
    get:
      tags:
        - Assets
      summary: List all assets
      operationId: listAssets
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of assets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
        '401':
          description: Unauthorized

    post:
      tags:
        - Assets
      summary: Create asset
      operationId: createAsset
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetInput'
      responses:
        '201':
          description: Asset created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized

  /assets/{id}:
    get:
      tags:
        - Assets
      summary: Get asset by ID
      operationId: getAsset
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Asset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '404':
          description: Asset not found

    patch:
      tags:
        - Assets
      summary: Update asset
      operationId: updateAsset
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssetInput'
      responses:
        '200':
          description: Asset updated. If criticality changed, every linked
            risk's score is recalculated asynchronously by the Score Engine
            worker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          description: Invalid input
        '404':
          description: Asset not found

    delete:
      tags:
        - Assets
      summary: Delete asset
      operationId: deleteAsset
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Asset deleted
        '404':
          description: Asset not found

  /assets/{id}/history:
    get:
      tags:
        - Assets
      summary: Get asset history (snapshots taken before each update/delete)
      operationId: getAssetHistory
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Asset history, newest first
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetSnapshot'
        '404':
          description: Asset not found

  # ==================== ASSET DEPENDENCIES ====================
  /attack-surface/topology:
    get:
      tags:
        - Attack Surface
      summary: The tenant's asset dependency graph
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Node cap (default and maximum 2000).
          schema:
            type: integer
      responses:
        '200':
          description: Topology
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTopology'

  /attack-surface/topology/edge-types:
    get:
      tags:
        - Attack Surface
      summary: The four-type edge vocabulary the topology renders
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Edge types
          content:
            application/json:
              schema:
                type: object
                properties:
                  edge_types:
                    type: array
                    items:
                      type: string

  /attack-surface/topology/{id}/compromise-chain:
    get:
      tags:
        - Attack Surface
      summary: Everything impacted by, and reachable from, a compromised asset
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompromiseChain'
        '404':
          description: Unknown asset (or owned by another tenant)

  /attack-surface/schemas:
    get:
      tags:
        - Attack Surface
      summary: List the tenant's typed attribute schemas (all 8 categories)
      description: >-
        Returns one schema per asset category, seeding the shipped default for
        any the tenant has never edited — so the response always covers every
        category and the form generator never has to handle a missing schema.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Schemas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTypeSchemaList'

  /attack-surface/schemas/{category}:
    parameters:
      - name: category
        in: path
        required: true
        schema:
          type: string
          enum: [server, workstation, application, database, network, cloud, vendor, data_processing]
    get:
      tags:
        - Attack Surface
      summary: Get one category's attribute schema
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTypeSchema'
        '400':
          description: Unknown category
    put:
      tags:
        - Attack Surface
      summary: Replace a category's attribute schema (admin)
      description: >-
        The schema is validated as a whole before anything is written: it is the
        contract every asset of that category is checked against, so a malformed
        one would make the category unwritable for everybody.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssetTypeSchemaInput'
      responses:
        '200':
          description: Updated schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTypeSchema'
        '400':
          description: Invalid schema
        '403':
          description: Admin only

  /attack-surface/schemas/{category}/reset:
    post:
      tags:
        - Attack Surface
      summary: Restore the shipped default schema for a category (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Default schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTypeSchema'

  /asset-dependencies:
    get:
      tags:
        - Assets
      summary: List the tenant's asset dependency graph (every directed edge)
      operationId: listAssetDependencies
      security:
        - bearerAuth: []
      responses:
        '200':
          description: All dependency edges for the tenant
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetDependency'
        '401':
          description: Unauthorized

    post:
      tags:
        - Assets
      summary: Add a directed dependency edge (source depends on target)
      operationId: createAssetDependency
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetDependencyInput'
      responses:
        '201':
          description: Dependency created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetDependency'
        '400':
          description: Invalid input (self-reference, unknown type, ...)
        '404':
          description: Source or target asset not found in this tenant
        '409':
          description: Identical edge already exists

  /asset-dependencies/{id}:
    delete:
      tags:
        - Assets
      summary: Delete a dependency edge
      operationId: deleteAssetDependency
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Dependency deleted
        '404':
          description: Dependency not found

  # ==================== VENDORS (TPRM v1, ADR 0004) ====================
  /vendors:
    get:
      tags:
        - Vendors
      summary: List the vendor register
      description: >-
        A vendor is an asset of category vendor (ADR 0004 D1). Requires
        vendors:read and the vendor_risk entitlement, which Business and
        Enterprise include; other plans answer 402. latest_assessment is null
        until the assessment module (#670) is wired.
      operationId: listVendors
      security:
        - bearerAuth: []
      parameters:
        - name: search
          in: query
          description: Case-insensitive match on the name or the legal_name attribute
          schema:
            type: string
        - name: service_criticality
          in: query
          description: Exact match on the service_criticality attribute
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: One page of the register
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPage'
        '401':
          description: Unauthorized
        '402':
          description: The plan does not include vendor risk
        '403':
          description: Missing vendors:read

  /vendors/{id}/chain:
    get:
      tags:
        - Vendors
      summary: Read the vendor→asset→risk chain, one hop deep
      operationId: getVendorChain
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorChain'
        '402':
          description: The plan does not include vendor risk
        '404':
          description: Vendor not found — unknown, malformed, another tenant's, or an asset that is not a vendor

  /vendors/{id}/assets:
    post:
      tags:
        - Vendors
      summary: Link an asset to the vendor
      description: >-
        Creates an asset dependency edge. managed_by, hosted_by and depends_on
        are stored asset → vendor; processes_data_of is stored vendor → asset.
      operationId: linkVendorAsset
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVendorLinkInput'
      responses:
        '201':
          description: Link created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetDependency'
        '400':
          description: Invalid verb, or the asset is itself a vendor
        '402':
          description: The plan does not include vendor risk
        '404':
          description: Vendor or asset not found in this tenant
        '409':
          description: Identical link already exists

  /vendors/{id}/assets/{linkId}:
    delete:
      tags:
        - Vendors
      summary: Remove a link of the vendor
      operationId: unlinkVendorAsset
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: linkId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Link removed
        '402':
          description: The plan does not include vendor risk
        '404':
          description: Not a vendor link of this vendor in this tenant

  # ==================== VENDOR QUESTIONNAIRES (TPRM v1, #670) ====================
  /vendor-questionnaire-templates:
    get:
      tags: [Vendors]
      summary: List questionnaire templates, without their questions
      operationId: listVendorQuestionnaireTemplates
      security:
        - bearerAuth: []
      parameters:
        - name: include_archived
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VendorQuestionnaireTemplate'
        '402':
          description: The plan does not include vendor risk
    post:
      tags: [Vendors]
      summary: Author a questionnaire template (version 1)
      operationId: createVendorQuestionnaireTemplate
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorQuestionnaireTemplateInput'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorQuestionnaireTemplate'
        '400':
          description: Invalid template or question
        '402':
          description: The plan does not include vendor risk

  /vendor-questionnaire-templates/{id}:
    get:
      tags: [Vendors]
      summary: Read a template with its questions
      operationId: getVendorQuestionnaireTemplate
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      responses:
        '200':
          description: The template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorQuestionnaireTemplate'
        '404':
          description: Not found in this tenant
    put:
      tags: [Vendors]
      summary: Replace a template's fields and questions as a new version
      description: Assessments already sent keep the questions they were sent with.
      operationId: updateVendorQuestionnaireTemplate
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorQuestionnaireTemplateInput'
      responses:
        '200':
          description: The new version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorQuestionnaireTemplate'
        '400':
          description: Invalid template or question
        '404':
          description: Not found in this tenant
        '409':
          description: The template is archived

  /vendor-questionnaire-templates/{id}/archive:
    post:
      tags: [Vendors]
      summary: Archive a template (idempotent); it can no longer be sent or edited
      operationId: archiveVendorQuestionnaireTemplate
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      responses:
        '200':
          description: The archived template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorQuestionnaireTemplate'
        '404':
          description: Not found in this tenant

  /vendors/{id}/assessments:
    get:
      tags: [Vendors]
      summary: List a vendor's assessments, newest first, with their effective status
      operationId: listVendorAssessments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      responses:
        '200':
          description: Assessments, without items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VendorAssessment'
        '404':
          description: Vendor not found in this tenant
    post:
      tags: [Vendors]
      summary: Send a questionnaire to the vendor
      description: >-
        Snapshots the template's questions, mints the public link and mails it.
        questionnaire_url is returned ONLY when the email could not go out.
      operationId: sendVendorAssessment
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendVendorAssessmentInput'
      responses:
        '201':
          description: Sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessmentDelivery'
        '400':
          description: Invalid input, archived template, or no contact email
        '404':
          description: Vendor or template not found in this tenant

  /vendor-assessments/{id}:
    get:
      tags: [Vendors]
      summary: Read an assessment with its items and answers (reviewer view)
      operationId: getVendorAssessment
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      responses:
        '200':
          description: The assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessment'
        '404':
          description: Not found in this tenant

  /vendor-assessments/{id}/revoke:
    post:
      tags: [Vendors]
      summary: Withdraw an open questionnaire; its link then answers 410
      operationId: revokeVendorAssessment
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessment'
        '404':
          description: Not found in this tenant
        '409':
          description: Already submitted or revoked

  /vendor-assessments/{id}/resend:
    post:
      tags: [Vendors]
      summary: Issue and mail a new link; the previous link answers 410
      operationId: resendVendorAssessment
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/VendorPathId'
      responses:
        '200':
          description: Resent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessmentDelivery'
        '404':
          description: Not found in this tenant
        '409':
          description: Not open (submitted, revoked or expired)

  /public/vendor-assessment:
    get:
      tags: [Vendors]
      summary: The questionnaire, as the vendor contact sees it (no account)
      description: >-
        Authenticated by the opaque token in X-Vendor-Assessment-Token only. The
        token must never be put in the URL. Weights, points and control
        references are not exposed.
      operationId: getPublicVendorAssessment
      security: []
      parameters:
        - $ref: '#/components/parameters/VendorAssessmentToken'
      responses:
        '200':
          description: The questionnaire
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessmentPublicView'
        '404':
          description: Missing, malformed or unknown link — identical in every case
        '410':
          description: Superseded by a newer link, revoked, expired, or no longer available
        '429':
          description: Rate limit

  /public/vendor-assessment/answers:
    put:
      tags: [Vendors]
      summary: Save draft answers
      operationId: savePublicVendorAssessmentAnswers
      security: []
      parameters:
        - $ref: '#/components/parameters/VendorAssessmentToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [answers]
              properties:
                answers:
                  type: array
                  maxItems: 200
                  items:
                    $ref: '#/components/schemas/VendorAnswerInput'
      responses:
        '200':
          description: Saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessmentPublicView'
        '400':
          description: Unknown question or invalid answer
        '404':
          description: Missing, malformed or unknown link
        '409':
          description: Already submitted
        '410':
          description: Superseded, revoked, expired, or no longer available
        '429':
          description: Rate limit

  /public/vendor-assessment/submit:
    post:
      tags: [Vendors]
      summary: Submit and lock the answers
      operationId: submitPublicVendorAssessment
      security: []
      parameters:
        - $ref: '#/components/parameters/VendorAssessmentToken'
      responses:
        '200':
          description: Submitted, now read-only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorAssessmentPublicView'
        '400':
          description: Required questions still need an answer
        '404':
          description: Missing, malformed or unknown link
        '409':
          description: Already submitted
        '410':
          description: Superseded, revoked, expired, or no longer available
        '429':
          description: Rate limit

  # ==================== STATISTICS ====================
  /stats:
    get:
      tags:
        - Statistics
      summary: Get dashboard statistics
      operationId: getDashboardStats
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dashboard statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardStats'
        '401':
          description: Unauthorized

  /stats/risk-matrix:
    get:
      tags:
        - Statistics
      summary: Get risk matrix data (impact vs probability)
      operationId: getRiskMatrix
      responses:
        '200':
          description: Risk matrix data
          content:
            application/json:
              schema:
                type: object
                properties:
                  matrix:
                    type: object

  /stats/trends:
    get:
      tags:
        - Statistics
      summary: Get global risk trend
      operationId: getRiskTrend
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Risk trend data
          content:
            application/json:
              schema:
                type: object

  # ==================== EXPORT ====================
  /export/pdf:
    get:
      tags:
        - Export
      summary: Export risks to PDF
      operationId: exportPDF
      security:
        - bearerAuth: []
      responses:
        '200':
          description: PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized

  # ==================== GAMIFICATION ====================
  /gamification/me:
    get:
      tags:
        - Gamification
      summary: Get current user's gamification profile
      operationId: getGamificationProfile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Gamification profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GamificationProfile'
        '401':
          description: Unauthorized

  /action-center:
    get:
      tags:
        - Action Center
      summary: Prioritised outstanding work for the caller
      description: >
        Returns the items the caller can personally act on right now, ordered by
        category rank then by that category's own secondary key. A live read over
        risks, mitigations, incidents, evidence, remediation plans and approvals —
        nothing is persisted and there is no dismiss: an item disappears when the
        underlying work is done.


        Which categories are returned depends on the caller's business role.
        Pending approvals are NOT role-gated: they are evaluated per request
        against the current step's approver, so a caller who is the named
        approver always sees them, and a caller who would be refused at the
        Approve button never does.
      operationId: getActionCenter
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Page size. Defaults to 20, clamped to 100.
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: offset
          in: query
          description: Rows to skip. A negative value is rejected with 400.
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: The caller's prioritised action items, possibly empty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCenterResponse'
        '400':
          description: Invalid offset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ==================== RISK BULK ACTIONS (#581) ====================
  /risks/bulk:
    post:
      tags:
        - Risks
      summary: Apply one action to many risks, all or none
      description: >-
        All-or-nothing (decision D-036). Either every named risk is modified or
        none is: the batch runs in a single transaction, and one stale, foreign
        or otherwise unresolvable id fails the whole request without writing
        anything. There is deliberately no per-item outcome to report.

        One audit entry is written per modified risk, carrying the acting user.

        A risk id belonging to another tenant answers 404 — identical to a
        fabricated id — because the tenant predicate is part of the row load.
      operationId: bulkRiskAction
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRiskActionInput'
      responses:
        '200':
          description: The batch was applied in full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkRiskActionResult'
        '400':
          description: >-
            Validation error — empty selection, more than 100 items, an unknown
            action type, or a missing action parameter.
        '401':
          description: Unauthorized
        '403':
          description: The caller lacks risks:update, or the session carries no tenant
        '404':
          description: >-
            At least one id could not be resolved — absent, or belonging to
            another tenant, deliberately indistinguishable. Nothing was modified.

  # ==================== GOVERNED BULK OPERATIONS (#582) ====================

  /vulnerabilities/bulk/capabilities:
    get:
      tags: [Vulnerabilities]
      summary: Which bulk actions this register supports
      description: >-
        A compiled-in vocabulary, identical for every tenant, so the bulk bar
        never offers an action the server would refuse. No table is read.
      operationId: vulnerabilitiesBulkCapabilities
      security: [{bearerAuth: []}]
      responses:
        '200':
          description: The supported actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCapabilities'
        '403': {description: The caller lacks read access to this register}

  /vulnerabilities/bulk/preview:
    post:
      tags: [Vulnerabilities]
      summary: What a bulk action would change — mutates nothing
      description: >-
        Returns the affected count and a bounded sample of exactly what would
        change, and writes nothing. Also returns a `fingerprint`: send it back
        with the apply and a selection that moved underneath the user is refused
        with 409 rather than silently applied to the new set.

        Behind the register's read permission — it discloses only the current
        state of rows the caller can already fetch individually.
      operationId: vulnerabilitiesBulkPreview
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPreviewInput'
      responses:
        '200':
          description: The impact statement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPreview'
        '400': {description: Validation error}
        '403': {description: The caller lacks read access, or the session carries no tenant}

  /vulnerabilities/bulk/change-status:
    post:
      tags: [Vulnerabilities]
      summary: Apply "change_status" to many rows, all or none
      description: >-
        All-or-nothing (decision D-036): either every named row is changed or
        none is. One audit entry is written per modified row, carrying the acting
        user. Rows from another tenant answer 404, identical to fabricated ids.

        The action is fixed by the route, not read from the body, so this
        endpoint's permission always matches what it performs. Requires
        `vulnerabilities:update`.
      operationId: vulnerabilitiesBulkChangeStatus
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkApplyInput'
      responses:
        '200':
          description: The batch was applied in full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResult'
        '400': {description: Validation error — empty selection, over 100 items, or an invalid status}
        '403': {description: The caller lacks vulnerabilities:update, or the session carries no tenant}
        '404': {description: An id did not resolve — absent, or another tenant's, deliberately indistinguishable. Nothing was modified.}
        '409': {description: The selection changed since it was previewed. Nothing was modified.}

  /vulnerabilities/bulk/delete:
    post:
      tags: [Vulnerabilities]
      summary: Apply "delete" to many rows, all or none
      description: >-
        All-or-nothing (decision D-036): either every named row is changed or
        none is. One audit entry is written per modified row, carrying the acting
        user. Rows from another tenant answer 404, identical to fabricated ids.

        The action is fixed by the route, not read from the body, so this
        endpoint's permission always matches what it performs. Requires
        `vulnerabilities:delete`.
      operationId: vulnerabilitiesBulkDelete
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkApplyInput'
      responses:
        '200':
          description: The batch was applied in full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResult'
        '400': {description: Validation error — empty selection, over 100 items, or an invalid status}
        '403': {description: The caller lacks vulnerabilities:delete, or the session carries no tenant}
        '404': {description: An id did not resolve — absent, or another tenant's, deliberately indistinguishable. Nothing was modified.}
        '409': {description: The selection changed since it was previewed. Nothing was modified.}

  /assets/bulk/capabilities:
    get:
      tags: [Assets]
      summary: Which bulk actions this register supports
      description: >-
        A compiled-in vocabulary, identical for every tenant, so the bulk bar
        never offers an action the server would refuse. No table is read.
      operationId: assetsBulkCapabilities
      security: [{bearerAuth: []}]
      responses:
        '200':
          description: The supported actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCapabilities'
        '403': {description: The caller lacks read access to this register}

  /assets/bulk/preview:
    post:
      tags: [Assets]
      summary: What a bulk action would change — mutates nothing
      description: >-
        Returns the affected count and a bounded sample of exactly what would
        change, and writes nothing. Also returns a `fingerprint`: send it back
        with the apply and a selection that moved underneath the user is refused
        with 409 rather than silently applied to the new set.

        Behind the register's read permission — it discloses only the current
        state of rows the caller can already fetch individually.
      operationId: assetsBulkPreview
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPreviewInput'
      responses:
        '200':
          description: The impact statement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPreview'
        '400': {description: Validation error}
        '403': {description: The caller lacks read access, or the session carries no tenant}

  /assets/bulk/delete:
    post:
      tags: [Assets]
      summary: Apply "delete" to many rows, all or none
      description: >-
        All-or-nothing (decision D-036): either every named row is changed or
        none is. One audit entry is written per modified row, carrying the acting
        user. Rows from another tenant answer 404, identical to fabricated ids.

        The action is fixed by the route, not read from the body, so this
        endpoint's permission always matches what it performs. Requires
        `assets:delete`.
      operationId: assetsBulkDelete
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkApplyInput'
      responses:
        '200':
          description: The batch was applied in full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResult'
        '400': {description: Validation error — empty selection, over 100 items, or an invalid status}
        '403': {description: The caller lacks assets:delete, or the session carries no tenant}
        '404': {description: An id did not resolve — absent, or another tenant's, deliberately indistinguishable. Nothing was modified.}
        '409': {description: The selection changed since it was previewed. Nothing was modified.}

  # ==================== SAVED VIEWS (#580) ====================
  # A saved view is a named filter/sort/column combination for one register.
  # It grants no access to data: applying one still runs the register's own
  # query under the caller's own permissions. Every route derives the tenant and
  # the user from the signed session — never from the body or the query string.
  /saved-views:
    get:
      tags:
        - Saved Views
      summary: List the saved views the caller may see
      operationId: listSavedViews
      description: >-
        The caller's own views for a register, plus every view their tenant has
        shared. A personal view belonging to another user is never returned, not
        even to a tenant admin. Omitting `table_id` returns the views of every
        register, which is what the one-time localStorage migration reads.
      security:
        - bearerAuth: []
      parameters:
        - name: table_id
          in: query
          required: false
          description: >-
            The register the views belong to — the same id the table is mounted
            with ("risks", "vulnerabilities", "assets", …). Omit for all of them.
          schema:
            type: string
            maxLength: 64
      responses:
        '200':
          description: The views this caller may see, most recent first
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SavedView'
        '401':
          description: Unauthorized
    post:
      tags:
        - Saved Views
      summary: Save a new view of a register
      operationId: createSavedView
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSavedViewInput'
      responses:
        '201':
          description: The view as stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedView'
        '400':
          description: >-
            Invalid body, or a value outside its bounds — name over 120
            characters, table_id over 64, more than 40 facets, more than 200
            values in one facet, or more than 200 columns.
        '401':
          description: Unauthorized
        '409':
          description: This user already has a view of that name on that register.

  /saved-views/{id}:
    patch:
      tags:
        - Saved Views
      summary: Rename, re-share or re-point a saved view
      operationId: updateSavedView
      description: >-
        A patch: an absent field is left alone, so renaming a view cannot
        silently reset its filters. Only the view's owner, or a tenant admin,
        may change it.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSavedViewInput'
      responses:
        '200':
          description: The view as stored after the patch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedView'
        '400':
          description: Invalid id, invalid body, or a value outside its bounds.
        '401':
          description: Unauthorized
        '403':
          description: The caller neither owns this view nor administers the tenant.
        '404':
          description: >-
            No such view for this tenant. An id belonging to another tenant
            answers identically, deliberately: a 403 would confirm it exists.
        '409':
          description: This user already has another view of that name on that register.
    delete:
      tags:
        - Saved Views
      summary: Delete a saved view
      operationId: deleteSavedView
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Deleted. Soft-deleted server-side; it does not come back.
        '400':
          description: Invalid id.
        '401':
          description: Unauthorized
        '403':
          description: The caller neither owns this view nor administers the tenant.
        '404':
          description: No such view for this tenant.

# ==================== COMPONENTS ====================
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token. Obtain via /auth/login

  parameters:
    VendorPathId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    VendorAssessmentToken:
      name: X-Vendor-Assessment-Token
      in: header
      required: true
      description: >-
        The opaque questionnaire token from the link's URL fragment (ADR 0004 D4).
        Never send it in the path or the query string.
      schema:
        type: string

  schemas:
    # ========== ACTION CENTER (#429) ==========
    ActionItem:
      type: object
      description: >
        One thing the caller needs to act on. Assembled on read from an existing
        record; it has no table of its own and no lifecycle.
      required:
        - id
        - type
        - title
        - subject_resource_type
        - subject_resource_id
        - deep_link
        - category_rank
        - tenant_id
      properties:
        id:
          type: string
          description: >
            Stable composite id, "<source>:<uuid>" (e.g. "mitigation:8f1e...").
            Namespaced because two categories can otherwise carry the same
            underlying uuid, and React would then see duplicate keys.
          example: mitigation:8f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0
        type:
          type: string
          enum:
            - overdue_mitigation
            - critical_risk
            - pending_approval
            - open_incident
            - expiring_evidence
            - overdue_remediation
        title:
          type: string
          description: The underlying record's own title, never a generated sentence.
        subject_resource_type:
          type: string
          enum: [mitigation, risk, approval_request, incident, evidence, remediation_plan]
        subject_resource_id:
          type: string
          description: The record's own id. A uuid for every type except incident, which is an integer rendered as a string.
        deep_link:
          type: string
          description: >
            Relative frontend path that resolves to a real route. Detail pages
            take the id in the path (/risks/mitigations/{id}); risks and evidence
            have no detail page and open the universal entity drawer instead
            (/risks?drawer=risk&entity={id}).
          example: /risks/mitigations/8f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0
        due_at:
          type: string
          format: date-time
          nullable: true
          description: Due date, expiry or approval deadline, depending on the type. Null when the category has no date.
        category_rank:
          type: integer
          minimum: 1
          maximum: 6
          description: >
            1 overdue_mitigation, 2 critical_risk, 3 pending_approval,
            4 open_incident, 5 expiring_evidence, 6 overdue_remediation.
            This is the primary sort key, exposed so a client can group without
            re-deriving the rule.
        tenant_id:
          type: string
          format: uuid
    ActionCenterResponse:
      type: object
      required: [data, generated_at, limit, offset, total]
      properties:
        data:
          type: array
          description: Always an array. Empty when nothing is outstanding.
          items:
            $ref: '#/components/schemas/ActionItem'
        generated_at:
          type: string
          format: date-time
          description: When the aggregation ran. The list is a live read, so this is its as-of instant.
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
          description: Total outstanding items for this caller, not the size of this page.

    # ========== FINANCIAL QUANTIFICATION (spec §9) ==========
    Money:
      type: object
      description: An amount in both currencies (XAF canonical, USD derived).
      required: [xaf, usd]
      properties:
        xaf:
          type: number
        usd:
          type: number
    FinancialAssessment:
      type: object
      description: Full monetary view of a single risk (pkg/crq).
      required:
        - sle
        - sle_average
        - sle_worst
        - downtime_cost
        - sle_basis
        - aro
        - ale
        - ale_average
        - ale_worst
        - ale_basis
        - remediation_cost
        - mitigation_effectiveness
        - ale_after
        - risk_reduction
        - rosi
        - rosi_computable
      properties:
        sle: { $ref: '#/components/schemas/Money' }
        sle_average: { $ref: '#/components/schemas/Money' }
        sle_worst: { $ref: '#/components/schemas/Money' }
        downtime_cost: { $ref: '#/components/schemas/Money' }
        sle_basis:
          type: string
          enum: [explicit, composed, reference]
        aro:
          type: number
        ale: { $ref: '#/components/schemas/Money' }
        ale_average: { $ref: '#/components/schemas/Money' }
        ale_worst: { $ref: '#/components/schemas/Money' }
        ale_basis:
          type: string
          enum: [explicit, reference]
        remediation_cost: { $ref: '#/components/schemas/Money' }
        mitigation_effectiveness:
          type: number
          description: "[0,1] share of ALE removed by the control"
        ale_after: { $ref: '#/components/schemas/Money' }
        risk_reduction: { $ref: '#/components/schemas/Money' }
        rosi:
          type: number
          description: "Return on Security Investment ratio (e.g. 1.5 = +150%)"
        rosi_computable:
          type: boolean
          description: false when remediation cost <= 0 (ratio undefined)
    SimulateFinancialInput:
      type: object
      description: Per-field overrides for a what-if scenario (all optional).
      properties:
        sle_xaf: { type: number, minimum: 0 }
        aro: { type: number, minimum: 0 }
        downtime_hours: { type: number, minimum: 0 }
        hourly_downtime_cost_xaf: { type: number, minimum: 0 }
        data_loss_cost_xaf: { type: number, minimum: 0 }
        fines_xaf: { type: number, minimum: 0 }
        other_direct_cost_xaf: { type: number, minimum: 0 }
        remediation_cost_xaf: { type: number, minimum: 0 }
        mitigation_effectiveness: { type: number, minimum: 0, maximum: 1 }
    SmartFactorScore:
      type: object
      description: One factor's contribution to the multifactor smart score (spec §8).
      required: [key, label, weight, value, contribution, detail]
      properties:
        key:
          type: string
          enum:
            - business_criticality
            - internet_exposure
            - vulnerabilities
            - control_maturity
            - incident_history
            - exploitability
            - financial_value
            - threat_intel
        label: { type: string, description: Human-readable factor name }
        weight: { type: number, description: "Normalised weight applied, 0 to 1" }
        value: { type: number, description: "Risk contribution of the factor, 0 to 1 (1 = worst)" }
        contribution: { type: number, description: "Points this factor adds (value x weight x 100)" }
        detail: { type: string, description: Short human explanation of the raw inputs }
    SmartRiskScore:
      type: object
      description: The multifactor smart risk score plus its radar-ready breakdown.
      required: [score, criticality, factors, explanation]
      properties:
        score: { type: number, description: 0–100 composite score }
        criticality:
          type: string
          enum: [low, medium, high, critical]
        factors:
          type: array
          items: { $ref: '#/components/schemas/SmartFactorScore' }
        explanation: { type: string, description: Sentence naming the top drivers }
    FactorWeightsInput:
      type: object
      description: >
        The eight configurable factor weights. Relative values (the engine
        normalises them); each in [0,1], at least one > 0.
      required:
        - business_criticality
        - internet_exposure
        - vulnerabilities
        - control_maturity
        - incident_history
        - exploitability
        - financial_value
        - threat_intel
      properties:
        business_criticality: { type: number, minimum: 0, maximum: 1 }
        internet_exposure: { type: number, minimum: 0, maximum: 1 }
        vulnerabilities: { type: number, minimum: 0, maximum: 1 }
        control_maturity: { type: number, minimum: 0, maximum: 1 }
        incident_history: { type: number, minimum: 0, maximum: 1 }
        exploitability: { type: number, minimum: 0, maximum: 1 }
        financial_value: { type: number, minimum: 0, maximum: 1 }
        threat_intel: { type: number, minimum: 0, maximum: 1 }
    RiskScoringWeights:
      type: object
      description: A tenant's persisted smart-risk factor weights.
      required:
        - business_criticality
        - internet_exposure
        - vulnerabilities
        - control_maturity
        - incident_history
        - exploitability
        - financial_value
        - threat_intel
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        business_criticality: { type: number }
        internet_exposure: { type: number }
        vulnerabilities: { type: number }
        control_maturity: { type: number }
        incident_history: { type: number }
        exploitability: { type: number }
        financial_value: { type: number }
        threat_intel: { type: number }
        updated_by: { type: string, format: uuid }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    CriticalityBucket:
      type: object
      required: [criticality, count, ale]
      properties:
        criticality: { type: string }
        count: { type: integer }
        ale: { $ref: '#/components/schemas/Money' }
    TopRiskFinancial:
      type: object
      required: [id, title, criticality, ale, ale_worst, rosi, rosi_computable]
      properties:
        id: { type: string, format: uuid }
        title: { type: string }
        criticality: { type: string }
        ale: { $ref: '#/components/schemas/Money' }
        ale_worst: { $ref: '#/components/schemas/Money' }
        rosi: { type: number }
        rosi_computable: { type: boolean }
    FinancialSummary:
      type: object
      description: Tenant-wide financial posture for the CFO/CISO dashboard.
      required:
        - currency
        - xaf_per_usd
        - total_risks
        - quantified_risks
        - total_ale
        - total_ale_worst
        - total_ale_after
        - total_risk_reduction
        - total_remediation
        - portfolio_rosi
        - portfolio_rosi_computable
        - by_criticality
        - top_risks
      properties:
        currency: { type: string }
        xaf_per_usd: { type: number }
        total_risks: { type: integer }
        quantified_risks: { type: integer }
        total_ale: { $ref: '#/components/schemas/Money' }
        total_ale_worst: { $ref: '#/components/schemas/Money' }
        total_ale_after: { $ref: '#/components/schemas/Money' }
        total_risk_reduction: { $ref: '#/components/schemas/Money' }
        total_remediation: { $ref: '#/components/schemas/Money' }
        portfolio_rosi: { type: number }
        portfolio_rosi_computable: { type: boolean }
        by_criticality:
          type: array
          items: { $ref: '#/components/schemas/CriticalityBucket' }
        top_risks:
          type: array
          items: { $ref: '#/components/schemas/TopRiskFinancial' }

    # ========== INPUT SCHEMAS ==========
    LoginInput:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: admin@example.com
        password:
          type: string
          format: password
          example: password123

    CreateRiskInput:
      type: object
      required:
        - title
        - impact
        - probability
      properties:
        title:
          type: string
          minLength: 3
          example: "Data breach risk"
        description:
          type: string
          example: "Unauthorized access to sensitive customer data"
        impact:
          type: integer
          minimum: 1
          maximum: 5
          description: Impact level (1-5)
          example: 5
        probability:
          type: integer
          minimum: 1
          maximum: 5
          description: Probability level (1-5)
          example: 3
        tags:
          type: array
          items:
            type: string
          example: ["security", "data-protection"]
        asset_ids:
          type: array
          items:
            type: string
            format: uuid
        framework:
          type: string
          enum: [ISO27001, CIS, NIST, OWASP]
          example: ISO27001

    UpdateRiskInput:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        impact:
          type: integer
          minimum: 1
          maximum: 5
        probability:
          type: integer
          minimum: 1
          maximum: 5
        tags:
          type: array
          items:
            type: string
        asset_ids:
          type: array
          items:
            type: string
            format: uuid

    CreateMitigationInput:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 3
          example: "Implement encryption"
        assignee:
          type: string
          example: "security-team@example.com"
        progress:
          type: integer
          minimum: 0
          maximum: 100
          example: 50
        cost:
          type: string
          example: "High"
        mitigation_time:
          type: string
          example: "2025-12-31"
        due_date:
          type: string
          format: date
          example: "2025-12-31"

    UpdateMitigationInput:
      type: object
      properties:
        title:
          type: string
        assignee:
          type: string
        progress:
          type: integer
          minimum: 0
          maximum: 100
        cost:
          type: string
        mitigation_time:
          type: string
        due_date:
          type: string
          format: date

    CreateSubActionInput:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          example: "Install security patches"

    CreateAssetInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          example: "Production Database Server"
        type:
          type: string
          enum: [Server, Application, Cloud, Database, SaaS, Storage, Network, Laptop, Data, User, Supplier]
          example: Database
        criticality:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
          example: CRITICAL
        owner:
          type: string
          example: "DBA Team"
        external_id:
          type: string
          example: "db-prod-001"
        category:
          type: string
          enum: [server, workstation, application, database, network, cloud, vendor, data_processing]
        attributes:
          type: object
          additionalProperties: true
          description: >-
            Typed attribute values. Requires a category — without one there is no
            schema to validate them against, and they are rejected.

    UpdateAssetInput:
      type: object
      description: Partial update — omitted fields are left unchanged.
      properties:
        name:
          type: string
          minLength: 1
        type:
          type: string
          enum: [Server, Application, Cloud, Database, SaaS, Storage, Network, Laptop, Data, User, Supplier]
        criticality:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
        owner:
          type: string
        category:
          type: string
          enum: [server, workstation, application, database, network, cloud, vendor, data_processing]
        attributes:
          type: object
          additionalProperties: true
          description: >-
            When present, REPLACES the whole attribute bag (it is validated as a
            whole, so a partial merge could drop a required attribute without the
            validator seeing its absence).

    # ========== RESPONSE SCHEMAS ==========
    AuthResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT Bearer token
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        user:
          $ref: '#/components/schemas/User'
        mfa:
          $ref: '#/components/schemas/MFAStatus'

    MFAStatus:
      type: object
      description: >-
        The resolved MFA requirement for the authenticated member (OR26-03).
        Carries no secret material: no TOTP seed, no QR payload, no backup codes.
      required: [state, configured, required, privileged, grace_period_active, grace_days]
      properties:
        state:
          type: string
          enum: [configured, recommended, grace_active, grace_expiring, required]
          description: >-
            configured — an authenticator is enrolled. recommended — not
            enrolled, not privileged; encouraged, never enforced. grace_active /
            grace_expiring — privileged and still able to defer, the second
            within 48h of the deadline. required — the server refuses protected
            access until an authenticator exists.
        configured:
          type: boolean
        required:
          type: boolean
          description: When true, protected routes answer 403 MFA_ENROLLMENT_REQUIRED.
        privileged:
          type: boolean
          description: Whether the mandate applies to this member at all.
        grace_period_active:
          type: boolean
        deadline:
          type: string
          format: date-time
          nullable: true
          description: Absent for a member the mandate does not apply to, and for an enrolled one.
        grace_days:
          type: integer
          description: The tenant's configured window, echoed so the UI needs no second call.

    MFAPolicy:
      type: object
      required: [grace_days, configured, min_days, max_days, default_days, privileged_org_roles, privileged_business_roles]
      properties:
        grace_days:
          type: integer
          minimum: 0
          maximum: 90
          description: Days a privileged member may defer enrolment. 0 = required immediately.
        configured:
          type: boolean
          description: >-
            False when the tenant has never saved the setting, so the screen can
            say "using the default" rather than imply somebody chose it.
        updated_by_id:
          type: string
          format: uuid
          nullable: true
        min_days:
          type: integer
        max_days:
          type: integer
        default_days:
          type: integer
        privileged_org_roles:
          type: array
          items:
            type: string
        privileged_business_roles:
          type: array
          items:
            type: string

    UpdateMFAPolicyInput:
      type: object
      required: [grace_days]
      properties:
        grace_days:
          type: integer
          minimum: 0
          maximum: 90

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        full_name:
          type: string
        role:
          type: string
          enum: [ADMIN, ANALYST, VIEWER]
        avatar_url:
          type: string
          format: uri
        last_login:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Risk:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        impact:
          type: integer
          minimum: 1
          maximum: 5
        probability:
          type: integer
          minimum: 1
          maximum: 5
        score:
          type: number
          format: float
          description: Calculated risk score
        status:
          type: string
          enum: [OPEN, MITIGATED, ACCEPTED, CLOSED]
        framework:
          type: string
          enum: [ISO27001, CIS, NIST, OWASP]
        tags:
          type: array
          items:
            type: string
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
        mitigations:
          type: array
          items:
            $ref: '#/components/schemas/Mitigation'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Mitigation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        risk_id:
          type: string
          format: uuid
        title:
          type: string
        status:
          type: string
          enum: [PLANNED, IN_PROGRESS, DONE]
        assignee:
          type: string
        progress:
          type: integer
          minimum: 0
          maximum: 100
        cost:
          type: string
        mitigation_time:
          type: string
        due_date:
          type: string
          format: date
        sub_actions:
          type: array
          items:
            $ref: '#/components/schemas/MitigationSubAction'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    MitigationSubAction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        mitigation_id:
          type: string
          format: uuid
        title:
          type: string
        completed:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ComplianceFramework:
      type: object
      description: Tenant-scoped framework a tenant tracks, e.g. ISO 27001, COBAC. Each tenant owns its own.
      required: [id, tenant_id, name, version, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        name:
          type: string
        version:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateFrameworkInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
        version:
          type: string
        description:
          type: string

    ComplianceControl:
      type: object
      description: Tenant-scoped control instantiated under a global framework.
      required: [id, tenant_id, framework_id, reference_code, name, status, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        framework_id:
          type: string
          format: uuid
        reference_code:
          type: string
          example: A.5.1.1
        name:
          type: string
        description:
          type: string
        source_reference:
          type: string
          description: >
            Citation for where this control comes from (standard section, circular article,
            law) — populated on catalog-imported controls, optional for ad-hoc ones.
          example: "ISO/IEC 27001:2022, Annexe A, A.5.1"
        status:
          type: string
          enum: [not_implemented, in_progress, implemented, not_applicable]
        evidence_count:
          type: integer
          description: >
            Computed count of the control's active evidences. Returned by the
            list/get endpoints so the UI can badge substantiated controls and
            enforce the "no implemented status without a proof" rule.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateControlInput:
      type: object
      required: [name]
      properties:
        reference_code:
          type: string
        name:
          type: string
        description:
          type: string
        source_reference:
          type: string

    UpdateControlInput:
      type: object
      description: Partial update — omitted fields are left unchanged.
      properties:
        reference_code:
          type: string
        name:
          type: string
        description:
          type: string
        source_reference:
          type: string
        status:
          type: string
          enum: [not_implemented, in_progress, implemented, not_applicable]

    ComplianceCatalogSummary:
      type: object
      description: A regulatory control catalog available (or not yet available) for import.
      required: [key, name, available, control_count]
      properties:
        key:
          type: string
          example: iso27001-2022
        name:
          type: string
          example: ISO/IEC 27001
        version:
          type: string
          example: "2022"
        description:
          type: string
        available:
          type: boolean
          description: False for placeholder catalogs with no reviewed control content yet.
        control_count:
          type: integer

    ImportCatalogInput:
      type: object
      required: [catalog_key]
      properties:
        catalog_key:
          type: string
          example: iso27001-2022

    ImportCatalogResult:
      type: object
      required: [imported, skipped, total]
      properties:
        imported:
          type: integer
          description: Controls newly created by this call.
        skipped:
          type: integer
          description: Controls that already existed (matched by reference_code) and were left untouched.
        total:
          type: integer
          description: Total controls in the catalog.

    ControlEvidence:
      type: object
      description: Tenant-scoped evidence file attached to a control.
      required: [id, tenant_id, control_id, filename, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        control_id:
          type: string
          format: uuid
        filename:
          type: string
        description:
          type: string
        uploaded_by:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ComplianceProgress:
      type: object
      description: Computed, not persisted — tallies a tenant's controls for a framework by status.
      required: [framework_id, total, by_status, applicable, percent_complete]
      properties:
        framework_id:
          type: string
          format: uuid
        total:
          type: integer
        by_status:
          type: object
          additionalProperties:
            type: integer
          example: { not_implemented: 2, in_progress: 2, implemented: 4, not_applicable: 2 }
        applicable:
          type: integer
          description: total minus not_applicable
        percent_complete:
          type: number
          format: float
          description: implemented / applicable * 100 (0 if applicable is 0)

    GapControl:
      type: object
      description: One unsatisfied control (neither implemented nor not_applicable).
      required: [control_id, framework_id, framework_name, reference_code, name, description, status, source_reference, evidence_count]
      properties:
        control_id: { type: string, format: uuid }
        framework_id: { type: string, format: uuid }
        framework_name: { type: string }
        reference_code: { type: string }
        name: { type: string }
        description: { type: string }
        status: { type: string, enum: [not_implemented, in_progress, implemented, not_applicable] }
        source_reference: { type: string }
        evidence_count: { type: integer }

    FrameworkGapSummary:
      type: object
      description: Per-framework gap roll-up.
      required: [framework_id, framework_name, version, total, implemented, in_progress, not_implemented, not_applicable, gaps, percent_complete]
      properties:
        framework_id: { type: string, format: uuid }
        framework_name: { type: string }
        version: { type: string }
        total: { type: integer }
        implemented: { type: integer }
        in_progress: { type: integer }
        not_implemented: { type: integer }
        not_applicable: { type: integer }
        gaps: { type: integer }
        percent_complete: { type: number, format: float }

    GapAnalysis:
      type: object
      description: >
        Computed, not persisted — every open compliance gap across a tenant's
        frameworks (or one framework), with per-framework and overall roll-ups.
      required: [total_controls, total_gaps, frameworks, gaps]
      properties:
        total_controls: { type: integer }
        total_gaps: { type: integer }
        frameworks:
          type: array
          items: { $ref: '#/components/schemas/FrameworkGapSummary' }
        gaps:
          type: array
          items: { $ref: '#/components/schemas/GapControl' }

    ComplianceAudit:
      type: object
      description: A tenant-scoped compliance audit (planning, execution, history).
      required: [id, tenant_id, framework_id, title, type, status, auditor, scope, summary, compliance_score, scheduled_start, scheduled_end, completed_at, created_by, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        framework_id: { type: string, format: uuid, nullable: true, description: null for a program-wide audit }
        title: { type: string }
        type: { type: string, enum: [internal, external, certification, surveillance] }
        status: { type: string, enum: [planned, in_progress, completed, cancelled] }
        auditor: { type: string }
        scope: { type: string }
        summary: { type: string }
        compliance_score: { type: number, format: float, description: compliance % snapshotted when the audit completes }
        scheduled_start: { type: string, format: date-time, nullable: true }
        scheduled_end: { type: string, format: date-time, nullable: true }
        completed_at: { type: string, format: date-time, nullable: true }
        created_by: { type: string, format: uuid, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CreateAuditInput:
      type: object
      required: [title, type]
      properties:
        title: { type: string }
        type: { type: string, enum: [internal, external, certification, surveillance] }
        framework_id: { type: string, format: uuid }
        auditor: { type: string }
        scope: { type: string }
        scheduled_start: { type: string, format: date-time }
        scheduled_end: { type: string, format: date-time }

    UpdateAuditInput:
      type: object
      properties:
        title: { type: string }
        type: { type: string, enum: [internal, external, certification, surveillance] }
        status: { type: string, enum: [planned, in_progress, completed, cancelled] }
        auditor: { type: string }
        scope: { type: string }
        summary: { type: string }
        compliance_score: { type: number, format: float }
        scheduled_start: { type: string, format: date-time }
        scheduled_end: { type: string, format: date-time }

    RemediationPlan:
      type: object
      description: A remediation action to close a compliance gap, linked to a control/audit.
      required: [id, tenant_id, title, description, control_id, framework_id, audit_id, priority, status, assigned_to, due_date, completed_at, created_by, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        title: { type: string }
        description: { type: string }
        control_id: { type: string, format: uuid, nullable: true }
        framework_id: { type: string, format: uuid, nullable: true }
        audit_id: { type: string, format: uuid, nullable: true }
        priority: { type: string, enum: [low, medium, high, critical] }
        status: { type: string, enum: [open, in_progress, completed, cancelled] }
        assigned_to: { type: string, format: uuid, nullable: true }
        due_date: { type: string, format: date-time, nullable: true }
        completed_at: { type: string, format: date-time, nullable: true }
        created_by: { type: string, format: uuid, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        control_code: { type: string }
        control_name: { type: string }

    CreateRemediationInput:
      type: object
      required: [title]
      properties:
        title: { type: string }
        description: { type: string }
        control_id: { type: string, format: uuid }
        audit_id: { type: string, format: uuid }
        priority: { type: string, enum: [low, medium, high, critical] }
        assigned_to: { type: string, format: uuid }
        due_date: { type: string, format: date-time }

    UpdateRemediationInput:
      type: object
      properties:
        title: { type: string }
        description: { type: string }
        priority: { type: string, enum: [low, medium, high, critical] }
        status: { type: string, enum: [open, in_progress, completed, cancelled] }
        assigned_to: { type: string, format: uuid }
        due_date: { type: string, format: date-time }

    GenerateRemediationsResult:
      type: object
      description: Result of auto-generating remediation plans from a completed audit.
      required: [created, skipped, plans]
      properties:
        created: { type: integer }
        skipped: { type: integer }
        plans:
          type: array
          items: { $ref: '#/components/schemas/RemediationPlan' }

    ControlMapping:
      type: object
      description: A tenant-scoped, undirected crosswalk between two controls across frameworks.
      required: [id, tenant_id, source_control_id, target_control_id, relation, note, created_by, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        source_control_id: { type: string, format: uuid }
        target_control_id: { type: string, format: uuid }
        relation: { type: string, enum: [equivalent, partial, related] }
        note: { type: string }
        created_by: { type: string, format: uuid, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        source_code: { type: string }
        source_name: { type: string }
        source_framework_id: { type: string }
        source_framework_name: { type: string }
        target_code: { type: string }
        target_name: { type: string }
        target_framework_id: { type: string }
        target_framework_name: { type: string }

    CreateControlMappingInput:
      type: object
      required: [source_control_id, target_control_id]
      properties:
        source_control_id: { type: string, format: uuid }
        target_control_id: { type: string, format: uuid }
        relation: { type: string, enum: [equivalent, partial, related] }
        note: { type: string }

    FrameworkSnapshot:
      type: object
      description: Per-framework advancement frozen into a board report at generation time.
      properties:
        name: { type: string }
        version: { type: string }
        total: { type: integer }
        applicable: { type: integer, description: total minus not_applicable }
        implemented: { type: integer }
        percent_complete: { type: number, format: float }

    BoardReport:
      type: object
      description: >
        A tenant-scoped monthly board-of-directors report. Snapshots the risk and
        compliance posture at generation time plus an editable, non-technical
        narrative. Lifecycle: draft -> approved (human-in-the-loop).
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        title: { type: string }
        organization_name: { type: string, description: Organization display name snapshotted at generation time }
        period_label: { type: string, example: "Juillet 2026" }
        locale: { type: string, enum: [fr, en] }
        status: { type: string, enum: [draft, approved] }
        risks_critical: { type: integer }
        risks_high: { type: integer }
        risks_medium: { type: integer }
        risks_low: { type: integer }
        risks_total: { type: integer }
        financial_exposure_fcfa: { type: integer, format: int64, description: Estimated annual exposure in FCFA (order-of-magnitude model) }
        overall_compliance_percent: { type: number, format: float }
        frameworks_snapshot:
          type: array
          nullable: true
          items: { $ref: '#/components/schemas/FrameworkSnapshot' }
        executive_summary: { type: string }
        risk_commentary: { type: string }
        compliance_commentary: { type: string }
        financial_commentary: { type: string }
        recommendations:
          type: array
          items: { type: string }
        generated_by_model: { type: string, description: '"claude-opus-4-8" or "template" (provenance)' }
        created_by: { type: string, format: uuid }
        approved_by: { type: string, format: uuid, nullable: true }
        approved_at: { type: string, format: date-time, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    GenerateBoardReportInput:
      type: object
      description: Both fields optional — empty period defaults to the current month, empty locale to French.
      properties:
        period_label: { type: string, example: "Juillet 2026" }
        locale: { type: string, enum: [fr, en], default: fr }

    UpdateBoardReportInput:
      type: object
      description: Partial narrative edits for a DRAFT report. Any omitted field is left unchanged.
      properties:
        title: { type: string }
        executive_summary: { type: string }
        risk_commentary: { type: string }
        compliance_commentary: { type: string }
        financial_commentary: { type: string }
        recommendations:
          type: array
          items: { type: string }

    Asset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum: [Server, Application, Cloud, Database, SaaS, Storage, Network, Laptop, Data, User, Supplier]
        criticality:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
        owner:
          type: string
        source:
          type: string
          enum: [MANUAL, OPENASSET]
        external_id:
          type: string
        category:
          type: string
          description: >-
            Typed category selecting which attribute schema governs this asset.
            Empty on assets registered before typed attributes existed.
          enum: [server, workstation, application, database, network, cloud, vendor, data_processing]
        attributes:
          type: object
          additionalProperties: true
          description: >-
            Typed attribute values, validated server-side against the tenant's
            schema for this asset's category.
        hostnames:
          type: array
          items:
            type: string
          description: Correlation fingerprint, denormalised from attributes.
        ip_addresses:
          type: array
          items:
            type: string
          description: Correlation fingerprint, denormalised from attributes.
        cloud_resource_id:
          type: string
          description: Correlation fingerprint, denormalised from attributes.
        cpes:
          type: array
          items:
            type: string
        risks:
          type: array
          items:
            $ref: '#/components/schemas/Risk'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AttributeDef:
      type: object
      description: >-
        One attribute of an asset category's schema. The set of these for a
        category IS the schema: the form generator renders it, the server
        validates against it, and the correlator reads its fingerprint role.
      required: [key, label, type]
      properties:
        key:
          type: string
          description: Stable snake_case machine key.
        label:
          type: string
        label_en:
          type: string
        type:
          type: string
          enum: [string, text, number, integer, boolean, enum, multi_enum, date, ip, ip_list, hostname, cidr, url, email, string_list]
        required:
          type: boolean
        enum:
          type: array
          items:
            type: string
        group:
          type: string
        help:
          type: string
        min:
          type: number
        max:
          type: number
        fingerprint:
          type: string
          description: >-
            Marks this attribute as an identity signal used to correlate external
            findings back to the asset.
          enum: ['', hostname, ip, cloud_id, cpe]

    AssetTypeSchema:
      type: object
      description: A tenant's attribute schema for one asset category.
      required: [category, attributes]
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        category:
          type: string
          enum: [server, workstation, application, database, network, cloud, vendor, data_processing]
        label:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/AttributeDef'
        customized:
          type: boolean
          description: Whether the tenant edited the shipped default.
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AssetTypeSchemaList:
      type: object
      required: [schemas, categories]
      properties:
        schemas:
          type: array
          items:
            $ref: '#/components/schemas/AssetTypeSchema'
        categories:
          type: array
          items:
            type: string

    UpdateAssetTypeSchemaInput:
      type: object
      required: [attributes]
      properties:
        label:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/AttributeDef'

    TopologyNode:
      type: object
      description: >-
        One asset as the topology view needs it — enough to place, colour and
        label it. The full asset is fetched only when its detail panel opens.
      required: [id, name, criticality, zone, internet_exposed, risk_count, max_risk_score, vuln_count, degree]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
        category:
          type: string
        criticality:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
        zone:
          type: string
          description: Cluster key — declared network zone, else cloud region, else category.
        internet_exposed:
          type: boolean
        risk_count:
          type: integer
        max_risk_score:
          type: number
        vuln_count:
          type: integer
        degree:
          type: integer
          description: Number of edges touching this node.

    TopologyEdge:
      type: object
      required: [id, source, target, type, raw_type]
      properties:
        id:
          type: string
          format: uuid
        source:
          type: string
          format: uuid
        target:
          type: string
          format: uuid
        type:
          type: string
          description: Folded onto the four-type topology vocabulary.
          enum: [depends_on, hosted_on, connects_to, processes_data_of]
        raw_type:
          type: string
          description: The stored relation before folding (e.g. runs_on).
        description:
          type: string

    TopologyZone:
      type: object
      required: [key, label, count]
      properties:
        key:
          type: string
        label:
          type: string
        count:
          type: integer

    AssetTopology:
      type: object
      required: [nodes, edges, zones, truncated]
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/TopologyNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/TopologyEdge'
        zones:
          type: array
          items:
            $ref: '#/components/schemas/TopologyZone'
        truncated:
          type: boolean
          description: >-
            True when the node cap bit. Reported rather than silently trimming —
            a topology missing nodes without saying so is worse than a slow one.
        node_limit:
          type: integer

    ChainHop:
      type: object
      required: [asset_id, depth]
      properties:
        asset_id:
          type: string
          format: uuid
        depth:
          type: integer

    CompromiseChain:
      type: object
      description: >-
        What follows from an asset being compromised. `impacted` are the assets
        that depend on it (what breaks); `reachable` are the assets it depends on
        or connects to (where an attacker moves next).
      required: [origin_id, impacted, reachable, edge_ids]
      properties:
        origin_id:
          type: string
          format: uuid
        impacted:
          type: array
          items:
            $ref: '#/components/schemas/ChainHop'
        reachable:
          type: array
          items:
            $ref: '#/components/schemas/ChainHop'
        edge_ids:
          type: array
          items:
            type: string
            format: uuid

    AssetSnapshot:
      type: object
      description: >-
        An asset's state captured immediately before an update or deletion.
        Answers "qui a modifié quoi, et quand": the prior field values (quoi),
        created_at (quand) and changed_by / changed_by_email (qui).
      properties:
        id:
          type: string
          format: uuid
        asset_id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
        criticality:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
        owner:
          type: string
        reason:
          type: string
          enum: [update, delete]
        changed_by:
          type: string
          format: uuid
          description: >-
            ID of the user who performed the change that superseded this state.
            All-zero UUID when the actor is unknown (legacy rows) or a
            non-interactive/system change.
        changed_by_email:
          type: string
          description: >-
            Computed display label for changed_by (resolved on read). Absent when
            the actor is unknown or could not be resolved.
        created_at:
          type: string
          format: date-time

    AssetDependency:
      type: object
      description: >-
        A directed edge in the tenant's asset dependency graph:
        source_asset depends on target_asset (read "source <type> target").
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        source_asset_id:
          type: string
          format: uuid
        target_asset_id:
          type: string
          format: uuid
        type:
          type: string
          enum: [depends_on, runs_on, connects_to, hosted_by, stores_data_in, authenticates_via, backs_up_to, managed_by]
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    VendorScoreContribution:
      type: object
      required: [item_id, weight, points, na, contribution]
      properties:
        item_id:
          type: string
          format: uuid
        weight:
          type: number
        points:
          type: number
          description: The chosen option's points; 0 when unanswered
        na:
          type: boolean
          description: Not applicable — excluded from both sums, contribution 0
        contribution:
          type: number
          description: 100 × weight × (1 − points) / Σ weight

    VendorQuestionOption:
      type: object
      required: [value, label, points]
      properties:
        value:
          type: string
        label:
          type: string
        points:
          type: number
          minimum: 0
          maximum: 1
          description: 1 is the fully favourable answer

    VendorQuestionnaireQuestionInput:
      type: object
      required: [text, answer_type]
      properties:
        text:
          type: string
          maxLength: 2000
        help:
          type: string
        answer_type:
          type: string
          enum: [choice, text]
        options:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/VendorQuestionOption'
        weight:
          type: number
          minimum: 0
          maximum: 10
          description: Forced to 0 for a text question
        required:
          type: boolean
        na_allowed:
          type: boolean
        control_ref:
          type: string
          description: Optional citation written by a person; never generated

    VendorQuestionnaireQuestion:
      allOf:
        - $ref: '#/components/schemas/VendorQuestionnaireQuestionInput'
        - type: object
          required: [id, template_id, position]
          properties:
            id:
              type: string
              format: uuid
            template_id:
              type: string
              format: uuid
            position:
              type: integer

    VendorQuestionnaireTemplateInput:
      type: object
      required: [name, language, questions]
      properties:
        name:
          type: string
          maxLength: 200
        description:
          type: string
        language:
          type: string
          enum: [fr, en]
        questions:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/VendorQuestionnaireQuestionInput'

    VendorQuestionnaireTemplate:
      type: object
      required: [id, name, language, version, archived_at, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        language:
          type: string
        version:
          type: integer
        archived_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        questions:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/VendorQuestionnaireQuestion'

    VendorAssessmentItem:
      type: object
      required: [id, position, text, answer_type, weight, required, na_allowed, answer_value, answer_na]
      properties:
        id:
          type: string
          format: uuid
        position:
          type: integer
        text:
          type: string
        help:
          type: string
        answer_type:
          type: string
          enum: [choice, text]
        options:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/VendorQuestionOption'
        weight:
          type: number
        required:
          type: boolean
        na_allowed:
          type: boolean
        control_ref:
          type: string
        answer_value:
          type: string
          nullable: true
        answer_na:
          type: boolean
        answer_comment:
          type: string
        answered_at:
          type: string
          format: date-time
          nullable: true

    VendorAssessment:
      type: object
      required: [id, vendor_asset_id, template_id, template_version, status, contact_email, contact_language, due_at, sent_at, score, tier, confidence, source]
      properties:
        id:
          type: string
          format: uuid
        vendor_asset_id:
          type: string
          format: uuid
        template_id:
          type: string
          format: uuid
        template_version:
          type: integer
        status:
          type: string
          enum: [sent, in_progress, submitted, revoked, expired]
        owner_user_id:
          type: string
          format: uuid
        contact_email:
          type: string
        contact_language:
          type: string
        due_at:
          type: string
          format: date-time
        sent_at:
          type: string
          format: date-time
        submitted_at:
          type: string
          format: date-time
          nullable: true
        revoked_at:
          type: string
          format: date-time
          nullable: true
        score:
          type: number
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Vendor score, 0–100, higher is riskier (ADR 0004 D5). Written on
            submission. Null until then, and null when nothing was scorable. Never an
            input to a risk's score.
        tier:
          type: string
          nullable: true
          enum: [critical, high, medium, low, null]
          description: critical ≥ 70 · high ≥ 40 · medium ≥ 20 · low < 20
        score_breakdown:
          type: array
          nullable: true
          description: The arithmetic of the score. Contributions sum to it.
          items:
            $ref: '#/components/schemas/VendorScoreContribution'
        scoring_version:
          type: string
          nullable: true
          description: The formula that produced the score, e.g. vendorscore/1
        source:
          type: string
        source_id:
          type: string
        source_version:
          type: string
        observed_at:
          type: string
          format: date-time
          nullable: true
        confidence:
          type: number
          description: 0.50 — self-attested (ADR 0004 D3a)
        provenance:
          type: object
          additionalProperties: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/VendorAssessmentItem'

    SendVendorAssessmentInput:
      type: object
      required: [template_id, due_at]
      properties:
        template_id:
          type: string
          format: uuid
        due_at:
          type: string
          format: date-time
        contact_email:
          type: string
          description: Defaults to the vendor's contact_email attribute
        contact_language:
          type: string
          enum: [fr, en]
          description: Defaults to the template's language

    VendorAssessmentDelivery:
      type: object
      required: [assessment, delivery]
      properties:
        assessment:
          $ref: '#/components/schemas/VendorAssessment'
        delivery:
          type: string
          enum: [sent, unavailable, failed]
        delivery_detail:
          type: string
        questionnaire_url:
          type: string
          description: Present ONLY when the email did not go out. It carries the one-time token in its fragment.

    VendorAnswerInput:
      type: object
      required: [item_id]
      properties:
        item_id:
          type: string
          format: uuid
        answer_value:
          type: string
          nullable: true
          description: An offered option's value, or free text. Empty clears a draft answer.
        answer_na:
          type: boolean
        answer_comment:
          type: string
          maxLength: 2000

    VendorPublicItem:
      type: object
      required: [id, position, text, answer_type, options, required, na_allowed, answer_value, answer_na]
      properties:
        id:
          type: string
          format: uuid
        position:
          type: integer
        text:
          type: string
        help:
          type: string
        answer_type:
          type: string
          enum: [choice, text]
        options:
          type: array
          items:
            type: object
            required: [value, label]
            properties:
              value:
                type: string
              label:
                type: string
        required:
          type: boolean
        na_allowed:
          type: boolean
        answer_value:
          type: string
          nullable: true
        answer_na:
          type: boolean
        answer_comment:
          type: string

    VendorAssessmentPublicView:
      type: object
      required: [organization_name, vendor_name, language, due_at, status, read_only, items]
      properties:
        organization_name:
          type: string
        vendor_name:
          type: string
        language:
          type: string
        due_at:
          type: string
          format: date-time
        status:
          type: string
          enum: [sent, in_progress, submitted]
        read_only:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/VendorPublicItem'

    VendorLatestAssessment:
      type: object
      required: [id, status, score, tier, due_at]
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        score:
          type: number
          nullable: true
        tier:
          type: string
          nullable: true
        due_at:
          type: string
          format: date-time

    VendorRegisterEntry:
      type: object
      required: [id, name, legal_name, country, service_provided, service_criticality, contract_end, criticality, owner, linked_assets, latest_assessment]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        legal_name:
          type: string
        country:
          type: string
        service_provided:
          type: string
        service_criticality:
          type: string
        contract_end:
          type: string
        criticality:
          type: string
        owner:
          type: string
        linked_assets:
          type: integer
          description: Distinct assets linked to the vendor
        latest_assessment:
          allOf:
            - $ref: '#/components/schemas/VendorLatestAssessment'
          nullable: true

    VendorPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/VendorRegisterEntry'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    VendorChainRisk:
      type: object
      required: [id, title, score, criticality, status]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        score:
          type: number
        criticality:
          type: string
        status:
          type: string

    VendorChainAsset:
      type: object
      required: [id, name, type, category, criticality]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
        category:
          type: string
        criticality:
          type: string

    VendorChainLink:
      type: object
      required: [link_id, verb, asset, risks]
      properties:
        link_id:
          type: string
          format: uuid
        verb:
          type: string
          enum: [managed_by, hosted_by, hosted_on, depends_on, processes_data_of, stores_data_in]
        asset:
          $ref: '#/components/schemas/VendorChainAsset'
        risks:
          type: array
          items:
            $ref: '#/components/schemas/VendorChainRisk'

    VendorChain:
      type: object
      required: [vendor_id, vendor_name, links]
      properties:
        vendor_id:
          type: string
          format: uuid
        vendor_name:
          type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/VendorChainLink'

    CreateVendorLinkInput:
      type: object
      required: [asset_id, verb]
      properties:
        asset_id:
          type: string
          format: uuid
        verb:
          type: string
          enum: [managed_by, hosted_by, processes_data_of, depends_on]
        description:
          type: string
          maxLength: 500

    CreateAssetDependencyInput:
      type: object
      required:
        - source_asset_id
        - target_asset_id
      properties:
        source_asset_id:
          type: string
          format: uuid
        target_asset_id:
          type: string
          format: uuid
        type:
          type: string
          enum: [depends_on, runs_on, connects_to, hosted_by, stores_data_in, authenticates_via, backs_up_to, managed_by]
          default: depends_on
        description:
          type: string

    DashboardStats:
      type: object
      properties:
        total_risks:
          type: integer
        open_risks:
          type: integer
        mitigated_risks:
          type: integer
        accepted_risks:
          type: integer
        closed_risks:
          type: integer
        average_risk_score:
          type: number
          format: float
        critical_assets:
          type: integer
        recent_risks:
          type: array
          items:
            $ref: '#/components/schemas/Risk'

    GamificationProfile:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        points:
          type: integer
        level:
          type: integer
        badges:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              earned_at:
                type: string
                format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    BulkRiskActionInput:
      type: object
      required:
        - type
        - risk_ids
      properties:
        type:
          type: string
          enum: [change_status, assign_to, add_tags, remove_tags, delete]
        risk_ids:
          type: array
          minItems: 1
          maxItems: 100
          description: Repeated ids are de-duplicated before the batch runs.
          items:
            type: string
            format: uuid
        status:
          type: string
          description: Required for change_status.
        assign_to_id:
          type: string
          format: uuid
          description: Required for assign_to.
        tags:
          type: array
          description: Required for add_tags and remove_tags. Removing an absent tag is a no-op.
          items:
            type: string
        justification:
          type: string
          description: Recorded on each audit entry.

    BulkRiskActionResult:
      type: object
      required:
        - total
        - applied
        - risk_ids
        - audited
      properties:
        total:
          type: integer
          description: How many distinct risks were named.
        applied:
          type: integer
          description: >-
            Equals total on success. A failure is an HTTP error, not a partial
            number, so this is never a shortfall.
        risk_ids:
          type: array
          items:
            type: string
            format: uuid
        audited:
          type: integer
          description: >-
            Audit entries written. Below applied only if the trail was
            unavailable; the mutation still happened, and the gap is reported
            rather than hidden.

    BulkCapabilities:
      type: object
      properties:
        entity_type:
          type: string
          example: vulnerability
        actions:
          type: array
          description: >-
            Only the actions this register can actually perform. Assets expose
            delete alone — domain.Asset has no Status, no Tags, and a free-text
            Owner, so nothing else from the frozen action set maps onto it.
          items:
            type: string
            enum: [change_status, delete]

    BulkPreviewInput:
      type: object
      required: [action, ids]
      properties:
        action:
          type: string
          enum: [change_status, delete]
        ids:
          type: array
          minItems: 1
          maxItems: 100
          items: {type: string, format: uuid}
        status:
          type: string
          description: The target value, for change_status.

    BulkApplyInput:
      type: object
      required: [ids]
      properties:
        ids:
          type: array
          minItems: 1
          maxItems: 100
          description: Repeated ids are de-duplicated before the batch runs.
          items: {type: string, format: uuid}
        status:
          type: string
          description: The target value, for the change-status route.
        justification:
          type: string
          maxLength: 1000
          description: Recorded on every audit entry the change produces.
        fingerprint:
          type: string
          description: >-
            The value returned by the preview. When present it must still match
            the selection's current state, or the request is refused with 409.
            Omit it to apply without previewing.

    BulkSampleChange:
      type: object
      properties:
        id: {type: string, format: uuid}
        label:
          type: string
          description: How the row reads to a human — a CVE id, an asset name — never a uuid.
        before: {type: object, additionalProperties: true}
        after: {type: object, additionalProperties: true}
        changed_fields:
          type: array
          items: {type: string}

    BulkPreview:
      type: object
      properties:
        requested:
          type: integer
          description: How many distinct ids the caller named.
        found:
          type: integer
          description: How many exist in this tenant. A shortfall is what would fail the apply.
        missing:
          type: array
          description: >-
            Ids that did not resolve — stale selections, or another tenant's,
            deliberately not distinguished.
          items: {type: string, format: uuid}
        affected:
          type: integer
          description: >-
            How many rows the change would actually alter. Lower than `found`
            when a row already holds the target value.
        unchanged:
          type: integer
        sample:
          type: array
          description: A bounded list (10) of exactly what would change.
          items:
            $ref: '#/components/schemas/BulkSampleChange'
        fingerprint:
          type: string
          description: Pass to the apply call to detect a selection that moved.
        action:
          type: string
          enum: [change_status, delete]

    BulkResult:
      type: object
      properties:
        total: {type: integer}
        applied:
          type: integer
          description: Equals total on success. A failure is an HTTP error, never a partial number.
        ids:
          type: array
          items: {type: string, format: uuid}
        audited:
          type: integer
          description: >-
            Audit entries written. Below `applied` only if the trail was
            unavailable; the mutation still happened and the gap is reported.

    # ========== SAVED VIEWS (#580) ==========
    SavedViewVisibility:
      type: string
      enum: [personal, shared]
      description: >-
        `personal` — only its owner sees it. `shared` — every member of the same
        tenant sees it. Sharing never crosses a tenant, and there is nothing in
        between on purpose: a view shared with a named subset of people is a
        permissions design, not a table feature.

    SavedViewSort:
      type: object
      required: [key, dir]
      properties:
        key:
          type: string
          description: The column the view sorts on.
        dir:
          type: string
          enum: [asc, desc]

    SavedViewState:
      type: object
      description: >-
        The part of the table state a view restores. Page and page size are
        deliberately absent — "page 3" is not part of what a view means.
      required: [q, filters, sort]
      properties:
        q:
          type: string
          description: The instant search term. Empty when the view carries none.
        filters:
          type: [object, 'null']
          description: >-
            Facet key → selected values. Null when the view carries no facet
            selection at all. At most 40 facets, each with at most 200 values.
          additionalProperties:
            type: array
            items:
              type: string
        sort:
          oneOf:
            - $ref: '#/components/schemas/SavedViewSort'
            - type: 'null'
          description: Null when the view does not pin a sort.

    SavedViewColumns:
      type: object
      description: >-
        The column layout the view restores. Keys the current build does not
        know are dropped on read rather than rejected, so a view saved before a
        column was removed still opens. At most 200 entries per list.
      required: [order, hidden]
      properties:
        order:
          type: [array, 'null']
          items:
            type: string
        hidden:
          type: [array, 'null']
          items:
            type: string

    SavedView:
      type: object
      description: >-
        One named view of one register, owned by one user inside one tenant.
        Server-side since #580, so it survives a browser and can be handed to a
        colleague. A usability capability, not a compliance control.
      required:
        - id
        - tenant_id
        - user_id
        - table_id
        - name
        - visibility
        - state
        - columns
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
          description: The owning tenant. Every read of this resource filters on it.
        user_id:
          type: string
          format: uuid
          description: The owner — the only person who may edit it, plus tenant admins.
        table_id:
          type: string
          maxLength: 64
          description: >-
            The register the view belongs to. A free string on purpose: the
            eighth register does not need a migration.
          example: risks
        name:
          type: string
          maxLength: 120
        visibility:
          $ref: '#/components/schemas/SavedViewVisibility'
        state:
          $ref: '#/components/schemas/SavedViewState'
        columns:
          $ref: '#/components/schemas/SavedViewColumns'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        owner_email:
          type: string
          description: >-
            Resolved on read for display ("shared by Amina"). Not a column, and
            absent when the server could not resolve a name.

    CreateSavedViewInput:
      type: object
      required: [table_id, name]
      properties:
        table_id:
          type: string
          maxLength: 64
          example: risks
        name:
          type: string
          maxLength: 120
        visibility:
          $ref: '#/components/schemas/SavedViewVisibility'
          description: >-
            Defaults to `personal` when omitted. Sharing is an explicit act: a
            default of shared would publish one user's working view to their
            whole institution.
        state:
          $ref: '#/components/schemas/SavedViewState'
        columns:
          $ref: '#/components/schemas/SavedViewColumns'

    UpdateSavedViewInput:
      type: object
      description: >-
        A patch. Every field is optional and an absent one is left untouched, so
        renaming a view cannot silently reset its filters. A present `state` or
        `columns` replaces the stored one whole.
      properties:
        name:
          type: string
          maxLength: 120
        visibility:
          $ref: '#/components/schemas/SavedViewVisibility'
        state:
          $ref: '#/components/schemas/SavedViewState'
        columns:
          $ref: '#/components/schemas/SavedViewColumns'

    OrganizationView:
      type: object
      required: [id, name, slug, plan, is_active, owner_id, created_at, updated_at, counts, can_edit]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        slug: { type: string }
        logo_url: { type: string }
        industry: { type: string }
        size: { type: string, enum: ['1-50', '51-200', '201-1000', '1000+'] }
        plan: { type: string }
        is_active: { type: boolean }
        owner_id: { type: string, format: uuid }
        owner_name: { type: string }
        timezone: { type: string, description: IANA time zone }
        website: { type: string, format: uri }
        description: { type: string }
        default_locale: { type: string, enum: [fr, en] }
        date_format: { type: string, enum: [DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD] }
        has_logo: { type: boolean }
        accent: { type: string, enum: [azure, iris] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        counts:
          type: object
          additionalProperties: { type: integer }
        can_edit: { type: boolean }
    OrganizationProfilePatch:
      type: object
      properties:
        name: { type: string, minLength: 2, maxLength: 120 }
        industry: { type: string, maxLength: 80 }
        size: { type: string, enum: ['', '1-50', '51-200', '201-1000', '1000+'] }
        website: { type: string, maxLength: 255, description: 'Absolute https:// URL, or empty to clear' }
        description: { type: string, maxLength: 500 }
        timezone: { type: string, description: 'IANA time zone, or empty to clear' }
        default_locale: { type: string, enum: ['', fr, en] }
        date_format: { type: string, enum: ['', DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD] }
        accent: { type: string, enum: ['', azure, iris], description: 'A design-system accent preset; free colours are refused' }
    OrganizationBranding:
      type: object
      required: [name, has_logo]
      properties:
        name: { type: string }
        has_logo: { type: boolean }
        accent: { type: string, enum: [azure, iris] }
    MyProfile:
      type: object
      required: [id, email, username, full_name, job_title, phone, bio, timezone, locale, date_format, theme_mode, has_avatar, effective, updated_at]
      properties:
        id: { type: string, format: uuid }
        email: { type: string }
        username: { type: string }
        full_name: { type: string }
        job_title: { type: string }
        phone: { type: string }
        bio: { type: string }
        timezone: { type: string }
        locale: { type: string }
        date_format: { type: string }
        theme_mode: { type: string }
        has_avatar: { type: boolean }
        avatar_url: { type: string }
        effective:
          type: object
          properties:
            timezone: { type: string }
            locale: { type: string }
            date_format: { type: string }
        updated_at: { type: string, format: date-time }
    UserProfilePatch:
      type: object
      properties:
        full_name: { type: string, minLength: 1, maxLength: 120 }
        job_title: { type: string, maxLength: 80 }
        phone: { type: string, maxLength: 32 }
        bio: { type: string, maxLength: 500 }
        timezone: { type: string, description: 'IANA time zone, or empty to follow the organization' }
        locale: { type: string, enum: ['', fr, en] }
        date_format: { type: string, enum: ['', DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD] }
        theme_mode: { type: string, enum: ['', light, dark, system] }
    TransferOwnerRequest:
      type: object
      required:
        - new_owner_id
      properties:
        new_owner_id:
          type: string
          format: uuid
          description: User id of the new owner. Must be an active member of the organisation.
    TransferOwnershipResult:
      type: object
      required:
        - entity_type
        - entity_id
        - previous_owner_id
        - owner_id
        - transferred_at
      properties:
        entity_type:
          type: string
          enum: [risk, mitigation, incident]
        entity_id:
          type: string
          description: The entity id as it appears in the path (a uuid, or an integer for incidents).
        previous_owner_id:
          type: string
          format: uuid
          nullable: true
          description: Null when the entity had no owner.
        owner_id:
          type: string
          format: uuid
        transferred_at:
          type: string
          format: date-time
    MeResponse:
      type: object
      required: [user, organization_id, has_password]
      properties:
        user:
          $ref: '#/components/schemas/User'
        organization_id:
          type: string
          format: uuid
        has_password:
          type: boolean
          description: False for an identity-provider account with no local password.
        mfa:
          $ref: '#/components/schemas/MFAStatus'
        business_role:
          type: string
          description: The caller's current business role in this organization, when they have one.
    DisableMFAInput:
      type: object
      properties:
        password:
          type: string
          format: password
          description: Required when the account has a password.
        code:
          type: string
          pattern: '^[0-9]{6}$'
          description: Current authenticator code. Required instead of `password` when `has_password` is false.
        locale:
          type: string
          enum: [fr, en]
    DisableMFAError:
      type: object
      required: [error, code]
      properties:
        error:
          type: string
          description: Localised message, safe to show as is.
        code:
          type: string
          enum: [wrong_password, wrong_code, mfa_required_by_role, no_local_password, not_enrolled, too_many_attempts, rejected, internal]
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: "Invalid input"
        code:
          type: integer
          example: 400
        details:
          type: object