openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Secure OTP Server",
    "version": "1.0.0"
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "put": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "delete": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "patch": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "head": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "options": {
        "summary": "Check health status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/otp/create": {
      "post": {
        "operationId": "createOtp",
        "summary": "Create or reuse an OTP token",
        "description": "Validates the credential payload, issues a new OTP if necessary, and sets a fresh session cookie.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "Credential payload to verify before generating an OTP. Customize `src/custom/credential.ts` to tighten this schema.",
                "oneOf": [
                  { "type": "object", "additionalProperties": true },
                  { "type": "array", "items": {} },
                  { "type": "string", "minLength": 1 },
                  { "type": "number" }
                ]
              },
              "examples": {
                "objectCredential": { "value": { "email": "user@example.com" } },
                "stringCredential": { "value": "internal-user-id-123" }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP session metadata.",
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OtpSessionState" }
              }
            }
          },
          "400": {
            "description": "Invalid credential payload or malformed/expired cookie.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "examples": {
                  "credentialInvalid": { "$ref": "#/components/examples/ErrCredentialInvalid" },
                  "otpInvalidCookie": { "$ref": "#/components/examples/ErrOtpInvalidCookie" }
                }
              }
            }
          },
          "413": { "$ref": "#/components/responses/ErrBodyTooLarge" },
          "429": { "$ref": "#/components/responses/ErrOtpTooManyRequests" },
          "500": { "$ref": "#/components/responses/ErrServer" }
        }
      }
    },
    "/api/otp/resend": {
      "post": {
        "operationId": "resendOtp",
        "summary": "Resend current OTP if allowed",
        "responses": {
          "200": {
            "description": "Updated session metadata after resending.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OtpSessionState" }
              }
            }
          },
          "400": {
            "description": "Resend not allowed (blocked or expired) or cookie invalid.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "examples": {
                  "otpResendNotAllowed": { "$ref": "#/components/examples/ErrOtpResendNotAllowed" },
                  "otpInvalidCookie": { "$ref": "#/components/examples/ErrOtpInvalidCookie" }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/ErrOtpTooManyRequests" },
          "500": { "$ref": "#/components/responses/ErrServer" }
        }
      }
    },
    "/api/otp/verify": {
      "post": {
        "operationId": "verifyOtp",
        "summary": "Verify an OTP value",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["otp"],
                "properties": {
                  "otp": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 8,
                    "pattern": "^\\w+$",
                    "description": "OTP value generated in the current session (default length: 8, regex: /\\w+/)."
                  }
                }
              },
              "examples": {
                "default": {
                  "value": {
                    "otp": "1ab34cd5"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP verified and final action executed."
          },
          "400": {
            "description": "OTP incorrect, blocked, or cookie invalid.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "examples": {
                  "otpIncorrect": { "$ref": "#/components/examples/ErrOtpIncorrect" },
                  "otpTooManyAttempts": { "$ref": "#/components/examples/ErrOtpTooManyAttempts" },
                  "otpInvalidFormat": { "$ref": "#/components/examples/ErrOtpInvalidFormat" },
                  "otpInvalidCookie": { "$ref": "#/components/examples/ErrOtpInvalidCookie" },
                  "otpExpired": { "$ref": "#/components/examples/ErrOtpExpired" }
                }
              }
            }
          },
          "413": { "$ref": "#/components/responses/ErrBodyTooLarge" },
          "429": { "$ref": "#/components/responses/ErrOtpTooManyRequests" },
          "500": { "$ref": "#/components/responses/ErrServer" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OtpSessionState": {
        "type": "object",
        "description": "Current OTP credential state associated with the encrypted cookie payload.",
        "properties": {
          "expires": {
            "type": "string",
            "format": "date-time",
            "description": "When the current OTP becomes invalid (time precision reduced server-side)."
          },
          "blocked": {
            "type": "boolean",
            "description": "True once attempts are exhausted; prevents further verification."
          },
          "resendBlock": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest time when another resend is allowed."
          },
          "otpBlock": {
            "type": "string",
            "format": "date-time",
            "description": "Temporary block applied after repeated invalid attempts."
          }
        },
        "required": ["expires"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        },
        "required": ["error"]
      }
    },
    "responses": {
      "ErrBodyTooLarge": {
        "description": "Request payload exceeded 100 KiB limit.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "default": { "$ref": "#/components/examples/ErrBodyTooLarge" }
            }
          }
        }
      },
      "ErrOtpTooManyRequests": {
        "description": "Too many OTP operations in a short time window.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "default": { "$ref": "#/components/examples/ErrOtpTooManyRequests" }
            }
          }
        }
      },
      "ErrServer": {
        "description": "Unhandled server error.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "default": { "$ref": "#/components/examples/ErrServer" }
            }
          }
        }
      }
    },
    "examples": {
      "ErrBodyTooLarge": {
        "value": { "error": "BODY:TOO_LARGE", "message": "The body of your request is too large." }
      },
      "ErrCredentialInvalid": {
        "value": { "error": "CREDENTIAL:INVALID", "message": "Invalid credential." }
      },
      "ErrOtpExpired": {
        "value": { "error": "OTP:EXPIRED", "message": "The current OTP is expired. Please request a new code." }
      },
      "ErrOtpIncorrect": {
        "value": { "error": "OTP:INCORRECT", "message": "Incorrect OTP value." }
      },
      "ErrOtpInvalidCookie": {
        "value": { "error": "OTP:INVALID_COOKIE", "message": "The OTP cookies are invalid." }
      },
      "ErrOtpInvalidFormat": {
        "value": { "error": "OTP:INVALID_FORMAT", "message": "Invalid OTP format." }
      },
      "ErrOtpResendNotAllowed": {
        "value": { "error": "OTP:RESENT_NOT_ALLOWED", "message": "Resend not allowed." }
      },
      "ErrOtpTooManyAttempts": {
        "value": {
          "error": "OTP:TOO_MANY_ATTEMPTS",
          "message": "Too many attempts. For security reasons, the OTP has been blocked. Please wait for it to expire and then try again."
        }
      },
      "ErrOtpTooManyRequests": {
        "value": { "error": "OTP:TOO_MANY_REQUESTS", "message": "Too many requests, slow down :)" }
      },
      "ErrServer": {
        "value": { "error": "SERVER", "message": "The server has some issues, it's not your fault." }
      }
    }
  }
}