feat: add TOTP

supertokens · Mar 11, 2024 · a2afb77 · a2afb77
1 parent d12fc6c
commit a2afb77
Showing 1 changed file with 351 additions and 1 deletion.
diff --git a/api_spec.yaml b/api_spec.yaml
@@ -17,11 +17,11 @@ tags:
   - name: ThirdPartyPasswordless Recipe
   - name: EmailVerification Recipe
   - name: MultiFactorAuth Recipe
+  - name: TOTP Recipe
   - name: JWT Recipe
   - name: OpenId Recipe
 paths:
 
-
   /{apiBasePath}/mfa/info:
     put:
       tags:
@@ -119,6 +119,349 @@ paths:
         '500':
           $ref: '#/components/responses/500'
 
+  /{apiBasePath}/totp/device/list:
+    get:
+      tags:
+        - TOTP Recipe
+      operationId: listTOTPdevices
+      description: |
+        List the TOTP devices of the current user
+      parameters:
+        - $ref: '#/components/parameters/apiBasePath'
+        - $ref: '#/components/parameters/totpRid'
+        - $ref: '#/components/parameters/anti-csrf'
+      security:
+        - AccessTokenBearer: []
+        - AccessTokenCookie: []
+      responses:
+        '200':
+          description: The list of the TOTP devices of the session user
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/statusOK'
+                      devices:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            name:
+                              type: string
+                              example: "asdf123"
+                            period:
+                              type: number
+                              example: 30
+                            skew:
+                              type: number
+                              example: 30
+                            verified:
+                              type: boolean
+                              example: false
+                  - $ref: '#/components/schemas/generalErrorResponse'
+
+        '404':
+          $ref: '#/components/responses/404'
+
+        '500':
+          $ref: '#/components/responses/500' 
+
+  /{apiBasePath}/totp/device:
+    post:
+      tags:
+        - TOTP Recipe
+      operationId: createTOTPDevice
+      description: |
+        Creates an unverified totp device
+      parameters:
+        - $ref: '#/components/parameters/apiBasePath'
+        - $ref: '#/components/parameters/totpRid'
+        - $ref: '#/components/parameters/anti-csrf'
+      security:
+        - AccessTokenBearer: []
+        - AccessTokenCookie: []
+
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                deviceName: 
+                  type: string
+                  example: "asdf123"
+      responses:
+        '200':
+          description: |
+            Information about the created (unverified) device. Based on the this,
+            the user can add the device to their TOTP app and verify it.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/statusOK'
+                      deviceName:
+                        type: string
+                        example: "asfd123"
+                      qrCodeString:
+                        type: string
+                        example: "asfd123"
+                      secret:
+                        type: string
+                        example: "asfd123"
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['DEVICE_ALREADY_EXISTS_ERROR']
+                  - $ref: '#/components/schemas/generalErrorResponse'
+
+        '403':
+          $ref: '#/components/responses/403-factor-setup'
+
+        '404':
+          $ref: '#/components/responses/404'
+
+        '500':
+          $ref: '#/components/responses/500'
+
+  /{apiBasePath}/totp/device/remove:
+    post:
+      tags:
+        - TOTP Recipe
+      operationId: removeTOTPDevice
+      description: |
+        Removes a totp device
+      parameters:
+        - $ref: '#/components/parameters/apiBasePath'
+        - $ref: '#/components/parameters/totpRid'
+        - $ref: '#/components/parameters/anti-csrf'
+      security:
+        - AccessTokenBearer: []
+        - AccessTokenCookie: []
+
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                deviceName: 
+                  type: string
+                  example: "asdf123"
+      responses:
+        '200':
+          description: Success report
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/statusOK'
+                      didDeviceExist:
+                        type: boolean
+                        example: true
+                  - $ref: '#/components/schemas/generalErrorResponse'
+
+        '404':
+          $ref: '#/components/responses/404'
+
+        '500':
+          $ref: '#/components/responses/500'
+
+  /{apiBasePath}/totp/device/verify:
+    post:
+      tags:
+        - TOTP Recipe
+      operationId: verifyTOTPDevice
+      description: |
+        Checks that the TOTP sent in the body belongs to the totp device (specified by deviceName, belonging to the session user)
+      parameters:
+        - $ref: '#/components/parameters/apiBasePath'
+        - $ref: '#/components/parameters/totpRid'
+        - $ref: '#/components/parameters/anti-csrf'
+      security:
+        - AccessTokenBearer: []
+        - AccessTokenCookie: []
+
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                totp: 
+                  type: string
+                  example: "123456"
+                deviceName:
+                  type: string
+                  example: "asdf123asdf"
+
+      responses:
+        '200':
+          description: Verification result and optionally the session with a refreshed MFA claim
+          headers:
+            Set-Cookie:
+              description: Sent in cookie-based sessions if the access token payload is updated
+              schema:
+                type: string
+                example: 'sAccessToken=eyJhb...%3D%3D; Path=/; Expires=Tue, 22 Jun 2021 07:43:07 GMT; HttpOnly; SameSite=Lax'
+            st-access-token:
+              description: Sent in cookie-based sessions if the access token payload is updated
+              schema:
+                $ref: '#/components/schemas/token'
+            anti-csrf:
+              description: Sent if enabled by the user
+              schema:
+                $ref: '#/components/schemas/token'
+            front-token:
+              description: Sent if the access token payload is updated
+              schema:
+                $ref: '#/components/schemas/token'
+            Access-Control-Expose-Headers:
+              schema:
+                type: string
+                example: 'anti-csrf, front-token, st-access-token'
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/statusOK'
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['UNKNOWN_DEVICE_ERROR']
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['INVALID_TOTP_ERROR']
+                      currentNumberOfFailedAttempts:
+                        type: number
+                        example: 2
+                      maxNumberOfFailedAttempts:
+                        type: number
+                        example: 5
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['LIMIT_REACHED_ERROR']
+                      retryAfterMs:
+                        type: number
+                        example: 30000
+                  - $ref: '#/components/schemas/generalErrorResponse'
+
+        '403':
+          $ref: '#/components/responses/403-factor-setup'
+
+        '404':
+          $ref: '#/components/responses/404'
+
+        '500':
+          $ref: '#/components/responses/500'
+
+  /{apiBasePath}/totp/verify:
+    post:
+      tags:
+        - TOTP Recipe
+      operationId: verifyTOTP
+      description: |
+        Checks that the TOTP sent in the body belongs to a verified totp device of the session user
+      parameters:
+        - $ref: '#/components/parameters/apiBasePath'
+        - $ref: '#/components/parameters/totpRid'
+        - $ref: '#/components/parameters/anti-csrf'
+      security:
+        - AccessTokenBearer: []
+        - AccessTokenCookie: []
+
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                totp: 
+                  type: string
+                  example: "123456"
+      responses:
+        '200':
+          description: Verification result and optionally the session with a refreshed MFA claim
+          headers:
+            Set-Cookie:
+              description: Sent in cookie-based sessions if the access token payload is updated
+              schema:
+                type: string
+                example: 'sAccessToken=eyJhb...%3D%3D; Path=/; Expires=Tue, 22 Jun 2021 07:43:07 GMT; HttpOnly; SameSite=Lax'
+            st-access-token:
+              description: Sent in cookie-based sessions if the access token payload is updated
+              schema:
+                $ref: '#/components/schemas/token'
+            anti-csrf:
+              description: Sent if enabled by the user
+              schema:
+                $ref: '#/components/schemas/token'
+            front-token:
+              description: Sent if the access token payload is updated
+              schema:
+                $ref: '#/components/schemas/token'
+            Access-Control-Expose-Headers:
+              schema:
+                type: string
+                example: 'anti-csrf, front-token, st-access-token'
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/statusOK'
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['UNKNOWN_USER_ID_ERROR']
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['INVALID_TOTP_ERROR']
+                      currentNumberOfFailedAttempts:
+                        type: number
+                        example: 2
+                      maxNumberOfFailedAttempts:
+                        type: number
+                        example: 5
+                  - type: object
+                    properties:
+                      status:
+                        type: string
+                        enum: ['LIMIT_REACHED_ERROR']
+                      retryAfterMs:
+                        type: number
+                        example: 30000
+                  - $ref: '#/components/schemas/generalErrorResponse'
+
+        '404':
+          $ref: '#/components/responses/404'
+
+        '500':
+          $ref: '#/components/responses/500'
+
   /{apiBasePath}/<tenantId>/signinup/code⠀:
     post:
       tags:
@@ -2275,6 +2618,13 @@ components:
       schema:
         type: string
 
+    totpRid:
+      name: rid
+      in: header
+      example: totp
+      schema:
+        type: string
+
     anti-csrf:
       name: anti-csrf
       in: header