components:
  schemas:
    ApprovalResponse:
      properties:
        message:
          type: string
        request_id:
          format: uuid
          type: string
        status:
          enum:
          - pending_approval
          - pending_security_review
          type: string
      type: object
    CreateTenantResponse:
      properties:
        key:
          description: KMS key ID
          type: string
        tenant_created:
          type: string
      type: object
    ErrorResponse:
      properties:
        error:
          description: Error code
          type: string
        fix_version:
          description: Recommended fix version (policy_denied errors)
          type: string
        reason:
          description: Human-readable error reason
          type: string
        vuln_id:
          description: Vulnerability ID (policy_denied errors)
          type: string
      type: object
    GetImportParamsResponse:
      properties:
        import_token:
          format: base64
          type: string
        kms_key_id:
          type: string
        parameters_valid_to:
          description: Unix timestamp
          format: int64
          type: integer
        public_key:
          format: base64
          type: string
      type: object
    GetPublicKeyResponse:
      properties:
        key_id:
          type: string
        key_spec:
          type: string
        key_usage:
          type: string
        public_key_pem:
          description: PEM-formatted public key
          type: string
        tenant_id:
          type: string
      type: object
    ImportKeyResponse:
      properties:
        imported:
          description: KMS key ID
          type: string
      type: object
    Request:
      properties:
        action:
          description: The API action to perform
          enum:
          - sign
          - pkcs11_sign
          - approve_sign
          - create_tenant
          - rotate_key
          - get_import_params
          - import_key
          - get_public_key
          - create_exception
          - list_exceptions
          - revoke_exception
          type: string
        algorithm:
          default: RSASSA_PKCS1_V1_5_SHA_256
          description: Signing algorithm (sign action only)
          type: string
        artifact_type:
          description: Type of artifact being signed (for policy evaluation)
          type: string
        artifact_version:
          description: Version of artifact being signed (for policy evaluation)
          type: string
        encrypted_key_material:
          description: Encrypted key material
          format: base64
          type: string
        environment:
          description: Environment name (for policy evaluation)
          type: string
        expiration_model:
          description: Key expiration model
          enum:
          - KEY_MATERIAL_EXPIRES
          - KEY_MATERIAL_DOES_NOT_EXPIRE
          type: string
        hash:
          description: Base64-encoded pre-computed hash to sign (required for sign, pkcs11_sign)
          format: base64
          type: string
        identity_id:
          description: Identity performing the operation (for policy evaluation)
          type: string
        identity_status:
          description: Status of identity (for policy evaluation)
          enum:
          - active
          - inactive
          type: string
        import_token:
          description: Import token for key import
          format: base64
          type: string
        key_spec:
          description: Key specification for key management operations
          enum:
          - RSA_2048
          - RSA_3072
          - RSA_4096
          - ECC_NIST_P256
          - ECC_NIST_P384
          - ECC_NIST_P521
          - ML_DSA_44
          - ML_DSA_65
          - ML_DSA_87
          - SM2
          type: string
        kms_key_id:
          description: KMS key ID
          type: string
        project:
          description: Project name (for policy evaluation)
          type: string
        pss_padding:
          default: false
          description: Use PSS padding for RSA signatures (pkcs11_sign only)
          type: boolean
        request_id:
          description: Request ID for resuming approvals
          format: uuid
          type: string
        require_tee:
          description: Whether TEE is required (for policy evaluation)
          type: boolean
        sbom:
          description: SPDX or CycloneDX SBOM (for policy evaluation)
          type: string
        tenant_id:
          description: Tenant identifier
          type: string
        version:
          default: v1
          description: API version (defaults to v1 if omitted)
          enum:
          - v1
          type: string
        wrapping_algorithm:
          description: Key wrapping algorithm for import
          enum:
          - RSAES_OAEP_SHA_256
          - RSAES_OAEP_SHA_1
          - RSA_AES_KEY_WRAP_SHA_256
          - RSA_AES_KEY_WRAP_SHA_1
          type: string
        wrapping_key_spec:
          description: Wrapping key specification for import
          enum:
          - RSA_2048
          - RSA_3072
          - RSA_4096
          type: string
      required:
      - action
      - tenant_id
      type: object
    SignResponse:
      properties:
        signature:
          description: Base64-encoded signature
          format: base64
          type: string
      type: object
  securitySchemes:
    awsSigv4:
      description: AWS Signature Version 4 authentication
      in: header
      name: Authorization
      type: apiKey
info:
  contact:
    name: Left Coast Logics
    url: https://leftcoastlogics.com
  description: 'Lambda-based API for cryptographic signing operations with policy evaluation, key management, and approval workflows. Path-based versioning: /v1/*, /v2/* for future versions.'
  license:
    name: Proprietary
  title: SaaS Signer Web API
  version: 1.0.0
  x-api-versions:
    stable: v1
    supported:
    - v1
openapi: 3.0.0
paths:
  /v1/approve_sign:
    post:
      operationId: approve_sign
      requestBody:
        content:
          application/json:
            example:
              action: approve_sign
              request_id: 550e8400-e29b-41d4-a716-446655440000
              tenant_id: my-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Approval processed
      security:
      - awsSigv4: []
      summary: Approve a pending signature request
      tags:
      - Approvals
  /v1/create_exception:
    post:
      operationId: create_exception
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '201':
          description: Exception created
      security:
      - awsSigv4: []
      summary: Create a policy exception
      tags:
      - Policy Exceptions
  /v1/create_tenant:
    post:
      operationId: create_tenant
      requestBody:
        content:
          application/json:
            example:
              action: create_tenant
              key_spec: RSA_2048
              tenant_id: new-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTenantResponse'
          description: Tenant created
      security:
      - awsSigv4: []
      summary: Create a new tenant with KMS key
      tags:
      - Tenant Management
  /v1/get_import_params:
    post:
      operationId: get_import_params
      requestBody:
        content:
          application/json:
            example:
              action: get_import_params
              key_spec: RSA_2048
              tenant_id: my-tenant
              wrapping_algorithm: RSAES_OAEP_SHA_256
              wrapping_key_spec: RSA_2048
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetImportParamsResponse'
          description: Import parameters
      security:
      - awsSigv4: []
      summary: Get parameters for external key import
      tags:
      - Key Import
  /v1/get_public_key:
    post:
      operationId: get_public_key
      requestBody:
        content:
          application/json:
            example:
              action: get_public_key
              tenant_id: my-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPublicKeyResponse'
          description: Public key
      security:
      - awsSigv4: []
      summary: Retrieve tenant's public key
      tags:
      - Key Management
  /v1/import_key:
    post:
      operationId: import_key
      requestBody:
        content:
          application/json:
            example:
              action: import_key
              encrypted_key_material: base64-encoded-material
              expiration_model: KEY_MATERIAL_DOES_NOT_EXPIRE
              import_token: base64-encoded-token
              kms_key_id: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
              tenant_id: my-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportKeyResponse'
          description: Key imported
      security:
      - awsSigv4: []
      summary: Import externally-generated key material
      tags:
      - Key Import
  /v1/list_exceptions:
    post:
      operationId: list_exceptions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: List of exceptions
      security:
      - awsSigv4: []
      summary: List policy exceptions
      tags:
      - Policy Exceptions
  /v1/pkcs11_sign:
    post:
      description: Sign using dynamic algorithm selection based on key_spec, with optional PSS padding for RSA keys.
      operationId: pkcs11_sign
      requestBody:
        content:
          application/json:
            example:
              action: pkcs11_sign
              hash: LCa0a2j_xo_5m0U8HTBx40y-ztLk-fKv5s3P0H0P1C0=
              key_spec: RSA_2048
              pss_padding: false
              tenant_id: my-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignResponse'
          description: Signature successful
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalResponse'
          description: Pending approval
        '403':
          description: Policy denied
      security:
      - awsSigv4: []
      summary: Sign with PKCS#11-compatible algorithm selection
      tags:
      - Signing
  /v1/revoke_exception:
    post:
      operationId: revoke_exception
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Exception revoked
      security:
      - awsSigv4: []
      summary: Revoke a policy exception
      tags:
      - Policy Exceptions
  /v1/rotate_key:
    post:
      operationId: rotate_key
      requestBody:
        content:
          application/json:
            example:
              action: rotate_key
              key_spec: RSA_4096
              tenant_id: my-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Key rotated
      security:
      - awsSigv4: []
      summary: Rotate tenant's signing key
      tags:
      - Tenant Management
  /v1/sign:
    post:
      description: Sign a pre-computed hash using the tenant's KMS key. Includes policy evaluation to check for vulnerabilities and compliance.
      operationId: sign
      requestBody:
        content:
          application/json:
            example:
              action: sign
              algorithm: RSASSA_PKCS1_V1_5_SHA_256
              hash: LCa0a2j_xo_5m0U8HTBx40y-ztLk-fKv5s3P0H0P1C0=
              sbom: '...'
              tenant_id: my-tenant
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignResponse'
          description: Signature successful
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalResponse'
          description: Pending approval or security review
        '400':
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Policy denied
      security:
      - awsSigv4: []
      summary: Sign a hash with policy evaluation
      tags:
      - Signing
servers:
- description: Production signing service
  url: https://signing.api.example.com
  variables:
    region:
      default: us-east-1
      description: AWS region
- description: Local development server
  url: http://localhost:3001
tags:
- description: Cryptographic signing operations
  name: Signing
- description: Approval workflow operations
  name: Approvals
- description: Tenant lifecycle management
  name: Tenant Management
- description: External key import operations
  name: Key Import
- description: Key operations
  name: Key Management
- description: Policy exception management
  name: Policy Exceptions