openapi.yaml

openapi: 3.0.0

info:
  title: MFA API
  description: >-
    Webauthn 2sv API implemented with Go and AWS Lambda. NOTE: this spec is in draft form and may not be complete or
    100% accurate.
  version: 0.1.0

servers:
- url: 'https://api.example.org'

security:
- mfaApiKey: []
  mfaApiSecret: []

components:
  headers:
#    Note: OpenAPI 3.0.0 does not officially support request headers in components, but it appears to
#    be supported by Redocly and Smartbear
    x-mfa-RPDisplayName:
      in: header
      name: x-mfa-RPDisplayName
      description: Relying Party Display Name
      required: true
      schema:
        type: string
      example: ACME Inc
    x-mfa-RPID:
      in: header
      name: x-mfa-RPID
      description: Relying Party ID, should only be the top level domain with no subdomain, protocol, or path
      required: true
      schema:
        type: string
      example: example.com
    x-mfa-RPOrigin:
      in: header
      name: x-mfa-RPOrigin
      description: >-
        Relying Party Origin, the browser origin for the request, include appropriate subdomain and protocol with
        no path or port
      schema:
        type: string
      example: https://sub.example.com
    x-mfa-RPIcon:
      in: header
      name: x-mfa-RPIcon
      description: Replying Party Icon
      schema:
        type: string
    x-mfa-UserUUID:
      in: header
      name: x-mfa-UserUUID
      description: >-
        The UUID for the user attempting to register or authenticate with WebAuthn. This has nothing to do with 
        WebAuthn, but is the primary key for finding the right record in the database.
      required: true
      schema:
        type: string
    x-mfa-Username:
      in: header
      name: x-mfa-Username
      description: The user's username
      required: true
      schema:
        type: string
    x-mfa-UserDisplayName:
      in: header
      name: x-mfa-UserDisplayName
      description: The user's display name
      required: true
      schema:
        type: string
    x-mfa-UserIcon:
      in: header
      name: x-mfa-UserIcon
      description: User Icon
      schema:
        type: string

  responses:
    UnauthorizedError:
      description: API key or secret is missing or invalid

  securitySchemes:
    mfaApiKey:
      description: Authentication key assigned to an API consumer
      type: apiKey
      in: header
      name: X-Mfa-Apikey
    mfaApiSecret:
      description: Authentication secret assigned to an API consumer
      type: apiKey
      in: header
      name: X-Mfa-Apisecret

  schemas:
    BeginRegistrationResponse:
      type: object
      properties:
        uuid:
          type: string
          description: The unique identifier for the user.
        publicKey:
          $ref: '#/components/schemas/PublicKeyCredentialCreationOptions'
      required:
      - uuid
      - publicKey

    PublicKeyCredentialCreationOptions:
      description: >-
        PublicKeyCredentialCreationOptions represents the IDL of the same name. In order to create a Credential via 
        create(), the caller specifies a few parameters in a PublicKeyCredentialCreationOptions object.
      type: object
      properties:
        rp:
          $ref: '#/components/schemas/RelyingPartyEntity'
        user:
          $ref: '#/components/schemas/UserEntity'
        challenge:
          type: string
          format: byte
          description: URL encoded base64
        pubKeyCredParams:
          description: Public key credential parameters
          type: array
          items:
            $ref: '#/components/schemas/CredentialParameter'
        timeout:
          type: integer
        excludeCredentials:
          $ref: '#/components/schemas/CredentialDescriptor'
        authenticatorSelection:
          $ref: '#/components/schemas/AuthenticatorSelection'
        hints:
          type: array
          items:
            type: string
        attestation:
          type: string
        attestationFormats:
          type: array
          items:
            type: string
        extensions:
          type: object
          properties:
            appidExclude:
              type: string
      required: [ "rp", "user", "challenge" ]

    RelyingPartyEntity:
      description: >-
        The RelyingPartyEntity represents the PublicKeyCredentialRpEntity IDL and is used to supply additional Relying
        Party attributes when creating a new credential.
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required: [ "id", "name" ]

    UserEntity:
      description: >-
        The UserEntity represents the PublicKeyCredentialUserEntity IDL and is used to supply additional user account
        attributes when creating a new credential.
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        name:
          type: string
      required: [ "id", "displayName", "name"]

    CredentialAssertion:
      description: The credential type and algorithm that the relying party wants the authenticator to create.
      type: object
      properties:
        publicKey:
          $ref: '#/components/schemas/PublicKeyCredentialRequestOptions'

    CredentialParameter:
      description: The credential type and algorithm that the relying party wants the authenticator to create.
      type: object
      properties:
        type:
          type: string
        alg:
          type: string
      required: [ "type", "alg" ]

    CredentialDescriptor:
      description: >-
        This dictionary contains the attributes that are specified by a caller when referring to a public key credential
        as an input parameter to the create() or get() methods. It mirrors the fields of the PublicKeyCredential object
        returned by the latter methods.
      type: object
      properties:
        type:
          description: The valid credential types
          type: string
        id:
          description: The ID of a credential to allow/disallow. (URL encoded Base64)
          type: string
          format: byte
        transports:
          description: The authenticator transports that can be used.
          type: array
          items:
            type: string
      required: [ "type", "id" ]

    AuthenticatorSelection:
      description: >-
        WebAuthn Relying Parties may use the AuthenticatorSelectionCriteria dictionary to specify their requirements 
        regarding authenticator attributes.
      type: object
      properties:
        authenticatorAttachment:
          description: >- 
            If this member is present, eligible authenticators are filtered to only authenticators attached with the
            specified AuthenticatorAttachment enum.
          type: string
        requireResidentKey:
          description: >-
            This member describes the Relying Party's requirements regarding resident credentials. If the parameter is
            set to true, the authenticator MUST create a client-side-resident public key credential source when creating
            a public key credential.
          type: boolean
        residentKey:
          description: >-
            This member describes the Relying Party's requirements regarding resident credentials per Webauthn Level 2.
          type: string
        userVerification:
          description: >-
            This member describes the Relying Party's requirements regarding user verification for the create()
            operation. Eligible authenticators are filtered to only those capable of satisfying this requirement.
          type: string

    PublicKeyCredentialRequestOptions:
      description: >-
        The PublicKeyCredentialRequestOptions dictionary supplies get() with the data it needs to generate an assertion.
        Its challenge member MUST be present, while its other members are OPTIONAL.
      type: object
      properties:
        challenge:
          type: string
          format: byte
        timeout:
          type: integer
        rpId:
          type: string
        allowCredentials:
          type: array
          items:
            $ref: '#/components/schemas/CredentialDescriptor'
        userVerification:
          type: string
        hints:
          type: array
          items:
            type: string
        extensions:
          type: object
          properties:
            appidExclude:
              type: boolean


    CredentialCreationResponse:
      type: object
      properties:
        id:
          type: string
        rawId:
          description: (URL encoded Base64)
          type: string
          format: byte
        response:
          $ref: '#/components/schemas/AuthenticatorAttestationResponse'
        type:
          type: string
        clientExtensionResults:
          type: object
          properties:
            appidExclude:
              type: boolean
        authenticatorAttachment:
          type: string
      required: [ 'id', 'type', 'rawId', 'response' ]

    AuthenticatorAttestationResponse:
      description: >-
        AuthenticatorAttestationResponse is the initial unpacked 'response' object received by the relying party.
        This contains the clientDataJSON object, which will be marshalled into CollectedClientData, and the
        'attestationObject', which contains information about the authenticator, and the newly minted public key
        credential. The information in both objects are used to verify the authenticity of the ceremony and new 
        credential.
      type: object
      properties:
        clientDataJSON:
          description: The byte slice of clientDataJSON, which becomes CollectedClientData (URL encoded Base64)
          type: string
          format: byte
        transports:
          type: array
          items:
            type: string
        authenticatorData:
          description: (URL encoded Base64)
          type: string
          format: byte
        publicKey:
          description: (URL encoded Base64)
          type: string
          format: byte
        publicKeyAlgorithm:
          type: integer
        attestationObject:
          description: >-
            AttestationObject is the byte slice version of attestationObject. This attribute contains an attestation
            object, which is opaque to, and cryptographically protected against tampering by, the client. The 
            attestation object contains both authenticator data and an attestation statement. The former contains the 
            AAGUID, a unique credential ID, and the credential public key. The contents of the attestation statement are
            determined by the attestation statement format used by the authenticator. It also contains any additional 
            information that the Relying Party's server requires to validate the attestation statement, as well as to 
            decode and validate the authenticator data along with the JSON-serialized client data. (URL encoded Base64)
          type: string
          format: byte
      required: [ 'clientDataJSON', 'authenticatorData', 'publicKey', 'publicKeyAlgorithm', 'attestationObject' ]

    SimpleError:
      type: object
      properties:
        error:
          type: string
          description: "Error message describing the error"
      required:
      - error
paths:
  /api-key:
    post:
      operationId: createApiKey
      summary: Create API Key
      description: >
        Create a new API key for access to other endpoints. All other endpoints use API keys to encrypt and decrypt
        data. Consequently, no existing data can be read by an API key created after the creation of that data. Keys
        are not usable until activated using the POST /api-key/activate endpoint
      requestBody:
        description: request body for CreateAPIKey request
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: email address of the requester
                  required: true
                  example: email@example.com
      responses:
        200:
          description: New API key created
          content:
            application/json:
              schema:
                properties:
                  email:
                    type: string
                    description: Email address of the requester
                    required: true
                    example: "admin@example.com"
                  apiKeyValue:
                    type: string
                    description: Unique ID for the new API Key
                    required: true
                    example: "0123456789abcdef0123456789abcdef01234567"
                  createdAt:
                    type: string
                    description: Time the key was created
                    required: true
                    example: "2006-01-02T15:04:05Z"
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleError"
              examples:
                invalid-input:
                  value:
                    error: "invalid request: invalid character ',' looking for beginning of value"
                email-required:
                  value:
                    error: "email is required"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
  /api-key/activate:
    post:
      operationId: activateApiKey
      summary: Activate API Key
      description: >
        Activate a new API key for access to other endpoints. Keys cannot be used before activation.
      requestBody:
        description: request body for ApiKeyActivate request
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKeyValue:
                  type: string
                  description: API key ID
                  required: true
                  example: 0123456789012345678901234567890123456789
                email:
                  type: string
                  description: email address of the requester
                  required: true
                  example: email@example.com
      responses:
        200:
          description: New API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  apiSecret:
                    type: string
                    description: >
                      a random string associated with the key, when paired with the key value can be used to
                      authenticate against API endpoints
                    required: false
                  email:
                    type: string
                    description: Email address of the requester
                    required: true
                    example: "admin@example.com"
                  apiKeyValue:
                    type: string
                    description: Unique ID for the new API Key
                    required: true
                    example: "0123456789abcdef0123456789abcdef01234567"
                  activatedAt:
                    type: string
                    description: Time the key was activated
                    required: true
                    example: "2006-01-02T15:04:05Z"
                  createdAt:
                    type: string
                    description: Time the key was created
                    required: true
                    example: "2006-01-02T15:04:05Z"
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleError"
              examples:
                invalid-input:
                  value:
                    error: "invalid request: invalid character ',' looking for beginning of value"
                email-required:
                  value:
                    error: "email is required"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleError"
              examples:
                not-found:
                  value:
                    error: "key not found: item does not exist: 0123456789012345678901234567890123456789"
  /api-key/rotate:
    post:
      operationId: rotateApiKey
      summary: Rotate API Key
      description: >
        All data in webauthn and totp tables that is encrypted by the old key (identified by the request headers 
        `x-mfa-apikey` and `x-mfa-apisecret`) will be re-encrypted using a new key identified in the request body.
        If the process does not run to completion, this endpoint can be called any number of times to continue the
        process. A status of 200 does not indicate that all keys were encrypted using the new key. Check the response
        data to determine if the rotation process is complete.
      requestBody:
        description: request body for ApiKeyRotate request
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newKeyId:
                  type: string
                  description: new API Key ID
                  required: true
                  example: 0123456789012345678901234567890123456789
                newKeySecret:
                  type: string
                  description: new API Key secret
                  required: true
                  example: 0123456789012345678901234567890123456789012=
      responses:
        200:
          description: New API secret created and data re-encrypted
          content:
            application/json:
              schema:
                type: object
                properties:
                  totp:
                    type: object
                    properties:
                      complete:
                        type: integer
                        description: the number of TOTP codes that were encrypted with the new key
                        required: true
                      incomplete:
                        type: integer
                        description: the number of TOTP codes that have not yet been encrypted with the new key
                        required: true
                  webauthn:
                    type: object
                    properties:
                      complete:
                        type: integer
                        description: the number of Webauthn passkeys that were encrypted with the new key
                        required: true
                      incomplete:
                        type: integer
                        description: the number of Webauthn passkeys that have not yet been encrypted with the new key
                        required: true
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleError"
              examples:
                invalid-input:
                  value:
                    error: "invalid request: invalid character ',' looking for beginning of value"
                api-key-required:
                  value:
                    error: "apiKeyValue is required"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleError"
              examples:
                not-found:
                  value:
                    error: "key not found: item does not exist: 0123456789012345678901234567890123456789"
  /webauthn/register:
    post:
      summary: Begin Registration
      description: Begin the registration of a new credential
      parameters:
      - $ref: '#/components/headers/x-mfa-RPDisplayName'
      - $ref: '#/components/headers/x-mfa-RPID'
      - $ref: '#/components/headers/x-mfa-RPOrigin'
      - $ref: '#/components/headers/x-mfa-RPIcon'
      - $ref: '#/components/headers/x-mfa-UserUUID'
      - $ref: '#/components/headers/x-mfa-Username'
      - $ref: '#/components/headers/x-mfa-UserDisplayName'
      - $ref: '#/components/headers/x-mfa-UserIcon'
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleError"
              examples:
                invalid-input:
                  value:
                    error: "unable to get user from request context"
                registration-error:
                  value:
                    error: "failed to begin registration"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        200:
          description: New response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BeginRegistrationResponse"
    put:
      summary: Finish Registration
      description: Finish the registration of a new credential
      parameters:
      - $ref: '#/components/headers/x-mfa-RPDisplayName'
      - $ref: '#/components/headers/x-mfa-RPID'
      - $ref: '#/components/headers/x-mfa-RPOrigin'
      - $ref: '#/components/headers/x-mfa-RPIcon'
      - $ref: '#/components/headers/x-mfa-UserUUID'
      - $ref: '#/components/headers/x-mfa-Username'
      - $ref: '#/components/headers/x-mfa-UserDisplayName'
      - $ref: '#/components/headers/x-mfa-UserIcon'
      requestBody:
        description: credential creation response
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialCreationResponse'
      responses:
        200:
          description: New response
          content:
            application/json:
              schema:
                type: object
                properties:
                  key_handle_hash:
                    type: string
                    description: hash of the key handle
              example:
                key_handle_hash: 0123456789abcdefghij
        401:
          $ref: "#/components/responses/UnauthorizedError"

  /webauthn/login:
    post:
      summary: Begin Login
      responses:
        200:
          description: New response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialAssertion'
        401:
          $ref: "#/components/responses/UnauthorizedError"

    put:
      summary: Finish Login
      responses:
        200:
          description: New response
          content:
            application/json:
              schema:
        401:
          $ref: "#/components/responses/UnauthorizedError"

  /webauthn/user:
    delete:
      summary: Delete User
      responses:
        204:
          description: Success
        401:
          $ref: "#/components/responses/UnauthorizedError"

  /webauthn/credential/{id}:
    delete:
      summary: Delete Credential
      description: >-
        DeleteCredential removes a single passkey identified by the id parameter, which is the `key_handle_hash`
        returned by the Finish Registration endpoint.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: >-
            The unique identifier for the credential. It is the `key_handle_hash` value returned by the 
            Finish Registration endpoint. If the id is the fixed string "u2f" the legacy U2F data is removed from the
            record.
      responses:
        204:
          description: Success
        401:
          $ref: "#/components/responses/UnauthorizedError"

  /totp:
    post:
      summary: Create a new TOTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                issuer:
                  type: string
                  description: >-
                    The name of the service/website for which the user is setting up this TOTP account.
                  required: true
                  example: "SIL IdP"
                label:
                  type: string
                  description: A name for the user's account (such as their username).
                  required: false
                  example: "john_smith@example.com"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    description: The unique identifier for the TOTP.
                    example: "aaaaaaaa-1111-aaaa-1111-aaaaaaaaaaaa"
                  totpKey:
                    type: string
                    description: The TOTP secret key.
                    example: "0123456789ABCDEF0123456789ABCDEF"
                  imageUrl:
                    type: string
                    description: >-
                      ImageURL is a base64-encoded image in data URL format like "data:image/png;base64,iVBORw0KGgo...". 
                      The image is a QR code that contains the OTPAuthURL, which the user scans to store the shared 
                      secret key and metadata in their authenticator app.
                    example: "data:image/png;base64,iVBORw0KGgo..."
                  otpAuthUrl:
                    type: string
                    description: >-
                      OTPAuthURL is an otpauth URI that contains the TOTP secret key. It may also contain metadata 
                      like issuer, algorithm, and number of digits.
                    example: "otpauth://totp/idp:john_smith?secret=0123456789ABCDEF0123456789ABCDEF&issuer=SIL%20IdP"
        401:
          $ref: "#/components/responses/UnauthorizedError"
  /totp/{uuid}:
    delete:
      summary: Delete a TOTP
      parameters:
        - in: path
          name: uuid
          schema:
            type: string
            format: uuid
          required: true
          description: The unique identifier for the TOTP.
      responses:
        "204":
          description: Success
        "404":
          description: Not found
        "401":
          $ref: "#/components/responses/UnauthorizedError"
  /totp/{uuid}/validate:
    post:
      summary: Validate a TOTP
      parameters:
        - in: path
          name: uuid
          schema:
            type: string
            format: uuid
          required: true
          description: The unique identifier for the TOTP.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  required: true
                  description: >-
                    The generated one-time password to validate against the shared secret identified by the UUID
                    parameter.
                  example: "123456"
      responses:
        "200":
          description: The code is valid.
        "400":
          description: Invalid request, e.g. missing code.
        "401":
          description: Key is not valid or one-time code is not valid.