openapi: '3.0.3'

info:
  version: 1.0.0
  title: i3M Wallet API

paths:
  /did-jwt/verify:
    post:
      summary: |
        Use the wallet to verify a JWT. The Wallet only supports DID issuers and the 'ES256K1' algorithm. Useful to verify JWT created by another wallet instance.
      operationId: didJwtVerify
      x-eov-operation-handler: did-jwt
      tags:
        - utils
      requestBody:
        description: Verify a JWT resolving the public key from the signer DID and optionally check values for expected payload claims
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jwt:
                  type: string
                  pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                  example: eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJmaWVsZDEiOiJzYWRzYWQ3NSIsImZpZWxkMiI6ImFmZnNhczlmODdzIiwiaXNzIjoiZGlkOmV0aHI6aTNtOjB4MDNmOTcwNjRhMzUzZmFmNWRkNTQwYWE2N2I2OTE2YmY1NmMwOWM1MGNjODAzN2E0NTNlNzg1ODdmMjdmYjg4ZTk0IiwiaWF0IjoxNjY1NDAwMzYzfQ.IpQ7WprvDMk6QWcJXuPBazat-2657dWIK-iGvOOB5oAhAmMqDBm8OEtKordqeqcEWwhWw_C7_ziMMZkPz1JIkw
                expectedPayloadClaims:
                  type: object
                  additionalProperties: true
                  description: |
                    The expected values of the proof's payload claims. An expected value of '' can be used to just check that the claim is in the payload. An example could be:

                    ```json
                    {
                      iss: 'orig',
                      exchange: {
                        id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
                        orig: '{"kty":"EC","x":"rPMP39e-o8cU6m4WL8_qd2wxo-nBTjWXZtPGBiiGCTY","y":"0uvxGEebFDxKOHYUlHREzq4mRULuZvQ6LB2I11yE1E0","crv":"P-256"}', // Public key in JSON.stringify(JWK) of the block origin (sender)
                        dest: '{"kty":"EC","x":"qf_mNdy57ia1vAq5QLpTPxJUCRhS2003-gL0nLcbXoA","y":"H_8YwSCKJhDbZv17YEgDfAiKTaQ8x0jpLYCC2myxAeY","crv":"P-256"}', // Public key in JSON.stringify(JWK) of the block destination (receiver)
                        hash_alg: 'SHA-256',
                        cipherblock_dgst: 'IBUIstf98_afbiuh7UaifkasytNih7as-Jah61ls9UI', // hash of the cipherblock in base64url with no padding
                        block_commitment: '', // hash of the plaintext block in base64url with no padding
                        secret_commitment: '' // hash of the secret that can be used to decrypt the block in base64url with no padding
                      }
                    }
                    ```
              required:
               - jwt

      responses:
        "200":
          description: |
            A verification object. If `verification` equals `success` all checkings have passed; if it is `failed`, you can access the error message in `error`. Unless the JWT decoding fails (invalid format), the decoded JWT payload can be accessed in `payload`.
            
            Example of success:

            ```json
            {
              "verification": "success",
              "payload": {
                "iss": "did:ethr:i3m:0x02d846307c9fd53106eb20db5a774c4b71f25c59c7bc423990f942e3fdb02c5898",
                "iat": 1665138018,
                "action": "buy 1457adf6"
              }
            }
            ```

            Example of failure:

            ```json
            {
              "verification": "failed",
              "error": "invalid_jwt: JWT iss is required"
              "payload": {
                "iat": 1665138018,
                "action": "buy 1457adf6"
              }
            }
            ```
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerificationOutput"

        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "../schema/error.yaml#/components/schemas/ApiError"

components:
  schemas:
    DecodedJwt:
      title: JwtPayload
      type: object
      properties:
        header: 
          type: object
          properties:
            typ:
              type: string
              enum:
                - JWT
            alg: 
              type: string
              enum:
                - ES256K
          required:
            - typ
            - alg
          additionalProperties: true
        payload:
          type: object
          properties:
            iss:
              $ref: "../schema/identity.yaml#/components/schemas/did"
          required:
            - iss
          additionalProperties: true
        signature:
          type: string
          format: ^[A-Za-z0-9_-]+$
        data:
          type: string
          format: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
          description: <base64url(header)>.<base64url(payload)>
      required:
        - signature
        - data
    
    VerificationOutput: 
      title: VerificationOutput
      type: object
      properties:
        verification:
          type: string
          enum:
            - success
            - failed
          description: whether verification has been successful or has failed
        error:
          type: string
          description: error message if verification failed
        decodedJwt:
          $ref: "#/components/schemas/DecodedJwt"
          description: the decoded JWT
      required:
        - verification