openapi: "3.0.3"
info:
  title: Nova Mobile App API
  version: "v1.0"
  description: |
    OpenAPI contract for the Nova Mobile App authentication flow.

    **Runtime routing**: AWS Lambda middleware routes by query params
    `ctrl`, `api`, and `ver`.

    **Controller**: `clientManagementCtl`

    **Conceptual mobile paths**:
    - `POST /mobile/auth/challenge` -> `api=getChallenge`
    - `POST /mobile/auth/login` -> `api=login`
    - `POST /mobile/auth/otp/send` -> `api=sendOTP`
    - `POST /mobile/auth/otp/verify` -> `api=verifyOTP`
    - `POST /mobile/auth/passcode/create` -> `api=createPasscode`
    - `POST /mobile/auth/passcode/verify` -> `api=verifyPasscode`
    - `POST /mobile/auth/biometric/enable` -> `api=enableBiometric`

    ### Success
    HTTP `200` returns the response DTO directly, without a wrapper envelope.

    ### Error
    Error responses use the shared API error envelope:
    ```json
    {
      "code": 180215,
      "message": "Invalid request body",
      "details": [{ "source": "phone_number", "issue": "required" }]
    }
    ```

    ### Current client-mobile Error Codes
    Error codes are generated by `sentools.NewSenErrorf(ctx, suffix, ...)`,
    which returns `ServiceErrorCodeFromContext(ctx) + suffix`.

    For `lambda/client-mobile/main.go`, the current controller base is:
    - `180200`
      (`MovilErrorCode(PkgErr_Staff, 0)`)

    Middleware/request codes used by this lambda:
    - `180203` -> Auth client JWT failed or forbidden
    - `180209` -> Infrastructure failure, such as nonce check failure
    - `180211` -> Invalid request, such as response body too large
    - `180212` -> Request not well formed: invalid `ctrl/api/ver`, wrong
      method, malformed JSON, validation failure, invalid body encoding,
      missing authorization header, or request body shield failure
    - `180213` -> Internal server error or panic
    - `180214` -> Origin not allowed

    Handler codes used by registered `clientManagementCtl` APIs
    (`getChallenge`, `login`, `sendOTP`, `verifyOTP`, `createPasscode`,
    `verifyPasscode`, and `enableBiometric`):
    - `180202` -> Database query error
    - `180203` -> Internal/config error, such as missing server JWT key,
      missing mobile attestation app ID, challenge generation failure,
      missing toolset, invalid user ID, missing email template, or OTP
      generation/email failure
    - `180206` -> Invalid phone/password, invalid authentication proof, or
      external service failure during login OTP delivery
    - `180208` -> Account locked by password retry policy
    - `180213` -> User/client not found
    - `180215` -> Validation failed, invalid request body, invalid challenge
      token, platform mismatch, device attestation failure, or device
      attestation required, invalid passcode format, or invalid
      passcode
    - `180221` -> User/client deactivated
    - `180234` -> Session not found
    - `180235` -> Session is not active
    - `180236` -> Max OTP resend/attempt limit reached
    - `180237` -> User temporarily blocked
    - `180238` -> OTP record not found
    - `180239` -> Invalid OTP

    Note: some full codes have multiple meanings because middleware, system,
    and business constants share numeric suffixes in the current codebase.

servers:
  - url: "{endpoint}"
    variables:
      endpoint:
        default: https://so13mwiko9.execute-api.mx-central-1.amazonaws.com/default/dev-omni-nova-mobile-app
        description: Base URL of the mobile Lambda / API Gateway endpoint

tags:
  - name: Mobile Auth
    description: Login, OTP, passcode, biometric, and trusted-device authentication flow.

paths:
  "/?ctrl=clientManagementCtl&api=getChallenge&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3DgetChallenge%26ver%3Dv1"

  "/?ctrl=clientManagementCtl&api=login&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3Dlogin%26ver%3Dv1"

  "/?ctrl=clientManagementCtl&api=sendOTP&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3DsendOTP%26ver%3Dv1"

  "/?ctrl=clientManagementCtl&api=verifyOTP&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3DverifyOTP%26ver%3Dv1"

  "/?ctrl=clientManagementCtl&api=createPasscode&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3DcreatePasscode%26ver%3Dv1"

  "/?ctrl=clientManagementCtl&api=verifyPasscode&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3DverifyPasscode%26ver%3Dv1"

  "/?ctrl=clientManagementCtl&api=enableBiometric&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DclientManagementCtl%26api%3DenableBiometric%26ver%3Dv1"

components:
  securitySchemes:
    mobileBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: EdDSA JWT
      description: |
        Short-lived client-signed JWT used for protected post-login mobile
        authentication steps. The JWT is signed with the registered Ed25519
        device key.

  responses:
    Failure:
      $ref: "./components.yaml#/components/responses/Failure"

  schemas:
    ApiError:
      $ref: "./components.yaml#/components/schemas/ApiError"
    GetLoginChallengeRequest:
      $ref: "./components.yaml#/components/schemas/GetLoginChallengeRequest"
    GetLoginChallengeResponse:
      $ref: "./components.yaml#/components/schemas/GetLoginChallengeResponse"
    LoginRequest:
      $ref: "./components.yaml#/components/schemas/LoginRequest"
    LoginResponse:
      $ref: "./components.yaml#/components/schemas/LoginResponse"
    SendOTPRequest:
      $ref: "./components.yaml#/components/schemas/SendOTPRequest"
    SendOTPResponse:
      $ref: "./components.yaml#/components/schemas/SendOTPResponse"
    VerifyOTPRequest:
      $ref: "./components.yaml#/components/schemas/VerifyOTPRequest"
    VerifyOTPResponse:
      $ref: "./components.yaml#/components/schemas/VerifyOTPResponse"
    CreatePasscodeRequest:
      $ref: "./components.yaml#/components/schemas/CreatePasscodeRequest"
    CreatePasscodeResponse:
      $ref: "./components.yaml#/components/schemas/CreatePasscodeResponse"
    VerifyPasscodeRequest:
      $ref: "./components.yaml#/components/schemas/VerifyPasscodeRequest"
    VerifyPasscodeResponse:
      $ref: "./components.yaml#/components/schemas/VerifyPasscodeResponse"
    EnableBiometricRequest:
      $ref: "./components.yaml#/components/schemas/EnableBiometricRequest"
    EnableBiometricResponse:
      $ref: "./components.yaml#/components/schemas/EnableBiometricResponse"