Merge pull request #119 from PermanentOrg/per-9737_add_auth_api_desig…

…n_docs

Per 9737 add auth api design docs

package.json

@@ -23,9 +23,11 @@
     "node": ">=18.0"
   },
   "devDependencies": {
+    "@redocly/cli": "^1.22.1",
     "@tsconfig/node18-strictest": "^1.0.0",
     "@types/cors": "^2.8.13",
     "@types/express": "^4.17.8",
+    "@types/http-errors": "^2.0.1",
     "@types/jest": "26.0.23",
     "@types/mailchimp__mailchimp_transactional": "^1.0.5",
     "@types/node": "^12.20.7",
@@ -34,7 +36,6 @@
     "@types/supertest": "^2.0.10",
     "@typescript-eslint/eslint-plugin": "^5.42.1",
     "@typescript-eslint/parser": "^5.42.1",
-    "@types/http-errors": "^2.0.1",
     "eslint": "^8.27.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^17.0.0",
@@ -46,8 +47,8 @@
     "prettier": "^2.7.1",
     "ts-jest": "27.0.2",
     "tsc-watch": "^6.0.4",
-    "typescript-cp": "^0.1.9",
     "tslint-tinypg": "^2.0.2",
-    "typescript": "^4.9.5"
+    "typescript": "^4.9.5",
+    "typescript-cp": "^0.1.9"
   }
 }

packages/api/docs/future/api.yaml

@@ -0,0 +1,30 @@
+openapi: 3.0.0
+info:
+  title: Permanent Core API
+  version: 1.0.0
+  license:
+    name: AGPL-3.0
+    url: https://www.gnu.org/licenses/agpl-3.0.html
+servers:
+  - url: https://api.permanent.org/v2
+components:
+  securitySchemes:
+    bearerHttpAuthentication:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+paths:
+  /login:
+    $ref: "./paths/authentication.yaml#/login"
+  /start-mfa:
+    $ref: "./paths/authentication.yaml#/start-mfa"
+  /complete-mfa:
+    $ref: "./paths/authentication.yaml#/complete-mfa"
+  /logout:
+    $ref: "./paths/authentication.yaml#/logout"
+  /mfa-method:
+    $ref: "./paths/mfa_management.yaml#/mfa-method"
+  /mfa-method/{methodId}:
+    $ref: "./paths/mfa_management.yaml#/mfa-method-with-id"
+  /account:
+    $ref: "./paths/account.yaml#/account"

packages/api/docs/future/errors.yaml

@@ -0,0 +1,30 @@
+errorResponse:
+  description: An object representing an error response
+  type: object
+  properties:
+    errors:
+      type: array
+      items:
+        type: object
+        required: [name, message]
+        properties:
+          name:
+            type: string
+          message:
+            type: string
+          source:
+            description: < 
+              The name of the input field that caused the error. 
+            type: string
+'400':
+  description: Invalid Request
+  content:
+    application/json:
+      schema: 
+        $ref: "#/errorResponse"
+'500':
+  description: Internal Server Error
+  content:
+    application/json:
+      schema:
+        $ref: "./errors.yaml#/errorResponse"

packages/api/docs/future/models/account.yaml

@@ -0,0 +1,98 @@
+notificationTypesEnabled:
+  description: An object containing boolean toggles to represent whether each category of notifications is enabled
+  type: object
+  properties:
+    apps:
+      type: object
+      properties:
+        confirmations:
+          type: boolean
+    share:
+      type: object
+      properties:
+        requests:
+          type: boolean
+        activities:
+          type: boolean
+        confirmations:
+          type: boolean
+    account:
+      type: object
+      properties:
+        confirmations:
+          type: boolean
+        recommendations:
+          type: boolean
+    archive:
+      type: object
+      properties:
+        requests:
+          type: boolean
+        confirmations:
+          type: boolean
+    relationships:
+      type: object
+      properties:
+        requests:
+          type: boolean
+        confirmations:
+          type: boolean
+account:
+  description: An object representing a user account on permanent.org
+  type: object
+  required: [id, primaryEmail, fullName, address, settings]
+  properties:
+    id:
+      type: string
+    primaryEmail:
+      type: object
+      required: [address, verified]
+      properties:
+        address:
+          type: string
+        verified:
+          type: boolean
+    primaryPhone:
+      type: object
+      required: [number, verified]
+      properties:
+        number:
+          type: string
+        verified:
+          type: boolean
+    fullName:
+      type: string
+    defaultArchiveId:
+      type: string
+    address:
+      type: object
+      properties:
+        lineOne:
+          type: string
+        lineTwo:
+          type: string
+        city:
+          type: string
+        state:
+          type: string
+        zip:
+          type: string
+        country:
+          type: string
+    settings:
+      type: object
+      required: [hideChecklist, allowSftpDeletion, notificationsEnabled]
+      properties:
+        hideChecklist:
+          type: boolean
+        allowSftpDeletion:
+          type: boolean
+        notificationsEnabled:
+          type: object
+          properties:
+            sms: 
+              $ref: "#/notificationTypesEnabled"
+            email: 
+              $ref: "#/notificationTypesEnabled"
+            inApp:
+              $ref: "#/notificationTypesEnabled"

packages/api/docs/future/models/mfa.yaml

@@ -0,0 +1,17 @@
+mfaDestination:
+  description: > 
+    The "address" to which the two-factor code will be sent. This could be an email address
+    or a phone number.
+  type: string
+mfaMethod:
+  type: object
+  properties:
+    id:
+      type: string
+    type:
+      type: string
+      enum:
+        - sms
+        - email
+    destination:
+      $ref: "#/mfaDestination"

packages/api/docs/future/paths/account.yaml

@@ -0,0 +1,42 @@
+account:
+  post:
+    summary: Create a new account
+    operationId: createAccount
+    security: []
+    tags:
+      - account
+    requestBody:
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [email, password, name]
+            properties:
+              email:
+                type: string
+              password:
+                type: string
+              name:
+                type: string
+    responses:
+      '201':
+        description: > 
+          The account has been created.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data:
+                  type: object
+                  properties:
+                    authenticationToken:
+                      type: string
+                    refreshToken:
+                      type: string
+                    account:
+                      $ref: "../models/account.yaml#/account"
+      '400':
+        $ref: "../errors.yaml#/400"
+      '500':
+        $ref: "../errors.yaml#/500"