[BACK-2165] [BACK-2164] [BACK-2163] Add app attestation and assertion api documentation.

.gitignore

@@ -2,3 +2,4 @@
 dist
 build
 .idea/
+.DS_Store

reference/auth.v1.yaml

@@ -39,6 +39,10 @@ tags:
     description: >-
       List and manage users.
 
+  - name: Attestation
+    description: >-
+      Attest and assert an app is a valid instance of an iOS app.
+
 paths:
   '/auth/login':
     post:
@@ -719,6 +723,98 @@ paths:
       security:
         - serverToken: []
 
+  '/v1/attestations/challenges':
+    post:
+      operationId: CreateAttestationChallenge
+      summary: Create an attestation challenge.
+      description: >-
+        Starts the attestation flow by requesting an attestation challenge that the client will later use in an Apple API call and to verify an attestation.
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: './auth/models/newappchallenge.v1.yaml'
+      responses:
+        '201':
+          $ref: '#/components/responses/AppChallenge'
+        '400':
+          $ref: './common/responses/badrequest.v1.yaml'
+        '401':
+          $ref: './common/responses/unauthorized.v1.yaml'
+        '403':
+          $ref: './common/responses/forbidden.v1.yaml'
+      tags:
+        - Attestation
+
+  '/v1/attestations/verifications':
+    post:
+      operationId: VerifyAttestation
+      summary: Verify an attestation.
+      description: >-
+        This confirms the app is a valid instance of an iOS app. It must use the previously generated challenge.
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: './auth/models/attestationverify.v1.yaml'
+      responses:
+        '204':
+          description: The attestation was verified successfully.
+        '400':
+          $ref: './common/responses/badrequest.v1.yaml'
+        '401':
+          $ref: './common/responses/unauthorized.v1.yaml'
+        '403':
+          $ref: './common/responses/forbidden.v1.yaml'
+      tags:
+        - Attestation
+
+  '/v1/assertions/challenges':
+    post:
+      operationId: CreateAssertionChallenge
+      summary: Create an assertion challenge.
+      description: >-
+        Requests an assertion challenge be generated. This can only happen after attestation has been verified.
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: './auth/models/newappchallenge.v1.yaml'
+      responses:
+        '201':
+          $ref: '#/components/responses/AppChallenge'
+        '400':
+          $ref: './common/responses/badrequest.v1.yaml'
+        '401':
+          $ref: './common/responses/unauthorized.v1.yaml'
+        '403':
+          $ref: './common/responses/forbidden.v1.yaml'
+      tags:
+        - Attestation
+
+  '/v1/assertions/verifications':
+    post:
+      operationId: VerifyAssertion
+      summary: Verify an assertion.
+      description: >-
+        This verifies an assertion and returns X.509 certficates.
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: './auth/models/assertionverify.v1.yaml'
+      responses:
+        '200':
+          $ref: '#/components/responses/Assertion'
+        '400':
+          $ref: './common/responses/badrequest.v1.yaml'
+        '401':
+          $ref: './common/responses/unauthorized.v1.yaml'
+        '403':
+          $ref: './common/responses/forbidden.v1.yaml'
+      tags:
+        - Attestation
+
 components:
   securitySchemes:
     basicAuth:
@@ -998,3 +1094,21 @@ components:
                 required:
                   - code
                   - reason
+    AppChallenge:
+      description: 'Challenge generated by server and which client should use in later operations.'
+      headers:
+        'X-Tidepool-Session-Token':
+          $ref: './common/headers/tidepoolsessiontoken.v1.yaml'
+      content:
+        'application/json':
+          schema:
+            $ref: './auth/models/appchallenge.v1.yaml'
+    Assertion:
+      description: 'Certificates returned upon successful assertion.'
+      headers:
+        'X-Tidepool-Session-Token':
+          $ref: './common/headers/tidepoolsessiontoken.v1.yaml'
+      content:
+        'application/json':
+          schema:
+            $ref: './auth/models/assertionsecret.v1.yaml'

reference/auth/models/appchallenge.v1.yaml

@@ -0,0 +1,7 @@
+title: Challenge
+description: Challenge generated by server.
+type: object
+properties:
+  challenge:
+    type: string
+    minLength: 1

reference/auth/models/assertionsecret.v1.yaml

@@ -0,0 +1,8 @@
+title: Assertion Secret
+description: Data sent back upon successful app assertion.
+type: object
+properties:
+  data:
+    oneOf:
+      - $ref: './coastalresponse.v1.yaml'
+      - $ref: './palmtreeresponse.v1.yaml'

reference/auth/models/assertionverify.v1.yaml

@@ -0,0 +1,34 @@
+title: Assertion Verify
+description: Request body for verifying an assertion.
+type: object
+properties:
+  assertion:
+    type: string
+    pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
+    description: Base64 encoded data received from Apple App Attest API. User must base64 encode the binary data received from Apple.
+  clientData:
+    type: object
+    properties:
+      challenge:
+        description: The previously returned assertion challenge.
+        type: string
+        minLength: 1
+      partner:
+        description: Code name of partner to retrieve certificate from.
+        type: string
+        minLength: 1
+        enum:
+          - Coastal
+          - PalmTree
+      partnerData:
+        oneOf:
+          - $ref: './coastalrequest.v1.yaml'
+          - $ref: './palmtreerequest.v1.yaml'
+    description: Actual data requested by client. Must include the previously requested challenge.
+  keyId:
+    $ref: './keyid.v1.yaml'
+    description: Base64 encoded key Id received from Apple App Attest API.
+required:
+  - attestation
+  - clientData
+  - keyId

reference/auth/models/attestationverify.v1.yaml

@@ -0,0 +1,18 @@
+title: Attestation Verify
+description: Request body for verifying an attestation.
+type: object
+properties:
+  attestation:
+    type: string
+    pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
+    description: Base64 encoded data received from Apple App Attest API. User must base64 encode the binary data received from Apple.
+  challenge:
+    type: string
+    minLength: 1
+    description: The previously returned attestation challenge.
+  keyId:
+    $ref: './keyid.v1.yaml'
+required:
+  - attestation
+  - challenge
+  - keyId

reference/auth/models/coastalrequest.v1.yaml

@@ -0,0 +1,26 @@
+title: Coastal Request Data
+description: Data to send to Coastal's API.
+type: object
+properties:
+  rcInstanceId:
+    type: string
+    minLength: 1
+  rcHWVersions:
+    type: array
+    items:
+      type: string
+  rcSWVersions:
+    type: array
+    items:
+      type: string
+  phdTypeId:
+    type: string
+    minLength: 1
+  phdInstanceId:
+    type: string
+    minLength: 1
+  csr:
+    type: string
+    pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
+    description: Base64 encoded string of the PEM formatted certificate signing request to the partner API.
+    minLength: 1

reference/auth/models/coastalresponse.v1.yaml

@@ -0,0 +1,21 @@
+title: Coastal Response
+description: Data retrieved from Coastal's API.
+type: object
+properties:
+  certificates:
+    description: X.509 certificates to be used for client authentication.
+    type: array
+    items:
+      type: object
+      properties:
+        content:
+          type: string
+          pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
+          description: base64 encoded X.509 certificate in DER format.
+        ttlInDays:
+          type: integer
+        type:
+          type: string
+          enum:
+            - CONSTRAINED
+            - WILDCARD

reference/auth/models/keyid.v1.yaml

@@ -0,0 +1,4 @@
+title: Key Id
+description: Base64 encoded key identifier received from apple. The Key Id is some shortened data, usually a hash, used to identify the longer actual key.
+type: string
+pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'

reference/auth/models/newappchallenge.v1.yaml

@@ -0,0 +1,10 @@
+title: New App Challenge
+description: Information needed when generating an attestation or assertion challenge.
+type: object
+properties:
+  keyId:
+    type: string
+    pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
+    description: Base64 encoded key Id received from Apple App Attest API.
+required:
+  - keyId

reference/auth/models/palmtreerequest.v1.yaml

@@ -0,0 +1,8 @@
+title: Palm Tree Request Data
+description: Data to send to Palm Tree's API.
+type: object
+properties:
+  csr:
+    description: Base64 encoded certificate signing request.
+    type: string
+    pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'

reference/auth/models/palmtreeresponse.v1.yaml

@@ -0,0 +1,24 @@
+title: Palm Tree Response
+description: Data retrieved from Palm Tree's API.
+type: object
+properties:
+  type:
+    type: string
+  enrollment:
+    type: object
+    properties:
+      body:
+        type: string
+        description: PEM encoded certificate.
+      id:
+        type: string
+      issuerName:
+        type: string
+      serialNumber:
+        type: string
+      subjectName:
+        type: string
+      status:
+        type: string
+      validityPeriod:
+        type: string

reference/common/models/base64.v1.yaml

@@ -0,0 +1,4 @@
+title: Base64
+type: string
+description: Base64 encoded data.
+pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'