[4.0.1 backport] CBG-4978 update the documentation for CORS (#7853)

Author: torcolvin

docs/api/components/responses.yaml

@@ -15,6 +15,12 @@ Not-found:
       example:
         error: not_found
         reason: no such database "invalid-db"
+Unauthorized:
+  description: User does not have access to resource, or resource does not exist
+  content:
+    application/json:
+      schema:
+        $ref: ./schemas.yaml#/HTTP-Error
 Conflict:
   description: Resource already exists under that name
   content:
@@ -33,12 +39,15 @@ Role:
     application/json:
       schema:
         $ref: ./schemas.yaml#/Role
-Invalid-CORS:
-  description: Origin is not in the approved list of allowed origins
+Invalid-CORS-LoginOrigin:
+  description: Value of `Origin` is not in the approved list of allowed origins in `LoginOrigin` of Sync Gateway bootstrap or database configuration.
   content:
     application/json:
       schema:
         $ref: ./schemas.yaml#/HTTP-Error
+      example:
+        error: "Bad Request"
+        reason: "No CORS"
 User-session-information:
   description: Properties associated with a user session
   content:

docs/api/components/schemas.yaml

@@ -390,25 +390,42 @@ User-session-information:
   type: object
   properties:
     authentication_handlers:
-      description: The ways authentication can be established to authenticate as the user.
+      description: The ways authentication can be established to authenticate as a user. Used for CouchDB compatibility. Always contains "default" and "cookie".
       type: array
-      items:
-        type: string
+      enum:
+        - ["default", "cookie"]
+      default: ["default", "cookie"]
     ok:
+      description: Used for CouchDB compatibility. Always true.
       type: boolean
+      enum:
+        - true
     userCtx:
       type: object
       properties:
         channels:
-          description: |
-            A map of the channels the user has access to and the sequence number each channel was created at.
-
-            The key is the channel name and the value is the sequence number.
+          description: A map of the channels in the default collection that the user is in along with the sequence number the user was granted access. This does not include inherited channels through roles.
           type: object
+          additionalProperties:
+            x-additionalPropertiesName: channelName
+            type: number
+            minimum: 1
+            description: The sequence number the user was granted access.
+            title: sequence number
+          example:
+            "!": 1
+            "channelA": 2
         name:
           description: The name of the user.
           type: string
-          nullable: true
+          minLength: 1
+      required:
+        - channels
+        - name
+  required:
+    - authentication_handlers
+    - ok
+    - userCtx
   title: User Session Information
 OIDC-callback:
   type: object
@@ -1162,24 +1179,10 @@ Database:
       type: number
       default: 1
     cors:
-      description: CORS configuration for this database; if present, overrides server's config.
-      type: object
-      properties:
-        headers:
-          description: List of allowed headers
-          type: array
-          items:
-            type: string
-        login_origin:
-          description: List of allowed login origins
-          type: array
-          items:
-            type: string
-        origin:
-          description: 'List of allowed origins, use [''*''] to allow access from everywhere'
-          type: array
-          items:
-            type: string
+      allOf:
+        - $ref: "#/CORS"
+        - type: object
+          description: CORS configuration for this database; if present, overrides server's config.
     delta_sync:
       description: |-
         Delta sync configuration settings.
@@ -2124,26 +2127,10 @@ Startup-config:
           type: boolean
           default: true
         cors:
-          type: object
-          properties:
-            headers:
-              description: List of allowed headers
-              type: array
-              items:
-                type: string
-            login_origin:
-              description: List of allowed login origins
-              type: array
-              items:
-                type: string
-            max_age:
-              description: Maximum age of the CORS Options request
-              type: integer
-            origin:
-              description: 'List of allowed origins, use [''*''] to allow access from everywhere'
-              type: array
-              items:
-                type: string
+          allOf:
+            - type: object
+              description: CORS configuration for all databases
+            - $ref: "#/CORS"
         enable_advanced_auth_dp:
           description: |-
             Whether to enable the DP permissions check feature of admin auth.
@@ -3183,3 +3170,42 @@ IndexInitStatus:
     - last_error
     - index_status
   title: IndexInitStatus
+CORS:
+  type: object
+  properties:
+    headers:
+      description: |-
+        List of allowed headers. These headers will be added the `Access-Control-Allow-Headers` response to a valid CORS request.
+
+        A recommended minimum set of values should be `["Accept-Encoding", "Authorization", "Content-Type", "If-Match"]`.
+      type: array
+      items:
+        type: string
+      example:
+        - Accept-Encoding
+        - Authorization
+        - Content-Type
+        - If-Match
+    login_origin:
+      description: |-
+        List of allowed origins to apply to public `/{db}/_session` API.
+
+        To use cors on `/{db}/_session`, the domain must be present in both `login_origin` and `origin`.
+
+        If configured, `Authorization` must be included in headers.
+      type: array
+      items:
+        type: string
+      example: ["https://example.com"]
+    max_age:
+      description: Value for `Access-Control-Maximum-Age`. Uses 0 by default.
+      type: integer
+      default: 0
+    origin:
+      description: |-
+        List of allowed origins for the public API. The request `Origin` header is checked against these values. If successful the `Origin` header is returned in the HTTP response header as `Access-Control-Allow-Origin`.
+      type: array
+      items:
+        type: string
+      example: ["https://example.com"]
+  title: Cors Configuration

docs/api/paths/admin/db-_facebook.yaml

@@ -12,7 +12,7 @@ post:
   description: |-
     Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.
 
-    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.
+    If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options.
   requestBody:
     content:
       application/json:
@@ -28,7 +28,7 @@ post:
     '200':
       description: Session created successfully
     '400':
-      $ref: ../../components/responses.yaml#/Invalid-CORS
+      $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin
     '401':
       description: Received error from Facebook verifier
       content:

docs/api/paths/admin/db-_google.yaml

@@ -12,7 +12,7 @@ post:
   description: |-
     Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.
 
-    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.
+    If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options.
   requestBody:
     content:
       application/json:
@@ -28,7 +28,7 @@ post:
     '200':
       description: Session created successfully
     '400':
-      $ref: ../../components/responses.yaml#/Invalid-CORS
+      $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin
     '401':
       description: Received error from Google token verifier or invalid application ID in the config
       content:

docs/api/paths/admin/db-_session.yaml

@@ -65,10 +65,17 @@ post:
                 session_id: c5af80a039db4ed9d2b6865576b6999935282689
                 expires: '2022-01-21T15:24:44Z'
                 cookie_name: SyncGatewaySession
-    '400':
-      $ref: ../../components/responses.yaml#/Invalid-CORS
+    "401":
+      $ref: ../../components/responses.yaml#/Unauthorized
     '404':
-      $ref: ../../components/responses.yaml#/Not-found
+      description: Return if database does not exist
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas.yaml#/HTTP-Error
+          example:
+            error: not_found
+            reason: no such database "invalid-db"
   tags:
     - Session
   operationId: post_db-_session

docs/api/paths/public/db-_facebook.yaml

@@ -12,7 +12,7 @@ post:
   description: |-
     Creates a new session based on a Facebook user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.
 
-    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.
+    If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options.
   requestBody:
     content:
       application/json:
@@ -28,7 +28,7 @@ post:
     '200':
       description: Session created successfully
     '400':
-      $ref: ../../components/responses.yaml#/Invalid-CORS
+      $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin
     '401':
       description: Received error from Facebook verifier
       content:

docs/api/paths/public/db-_google.yaml

@@ -12,7 +12,7 @@ post:
   description: |-
     Creates a new session based on a Google user. On a successful session creation, a session cookie is stored to keep the user authenticated for future API calls.
 
-    If CORS is enabled, the origin must match an allowed login origin otherwise an error will be returned.
+    If `Origin` header is passed to this endpoint, the `Origin` header must match both the `cors.login_origin` and `cors.origin` configuration options.
   requestBody:
     content:
       application/json:
@@ -28,7 +28,7 @@ post:
     '200':
       description: Session created successfully
     '400':
-      $ref: ../../components/responses.yaml#/Invalid-CORS
+      $ref: ../../components/responses.yaml#/Invalid-CORS-LoginOrigin
     '401':
       description: Received error from Google token verifier or invalid application ID in the config
       content: