Signal API Rules

extends: spectral:oas
rules:
  # Signal Server uses Basic auth (username:password where username=number, password=signaling key)
  signal-basic-auth-required:
    description: Signal Server API uses Basic authentication with phone number credentials
    message: Signal Server API should use http basic auth scheme
    severity: warn
    given: "$.components.securitySchemes[*]"
    then:
      field: scheme
      function: enumeration
      functionOptions:
        values:
          - basic
          - bearer

  # Signal uses phone number or UUID as primary identifier in paths
  signal-path-param-naming:
    description: Signal Server path parameters should follow consistent naming
    message: Path parameters should use consistent Signal Server naming conventions
    severity: warn
    given: "$.paths[*][*].parameters[?(@.in == 'path')]"
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^(deviceId|sourceDeviceId|destinationServiceId|usernameHash|recipientUUID|attachmentId|packId|stickerNum|messageGuid|keyId)$"

  # All Signal API operations must have operationId
  signal-operation-id-required:
    description: All operations must have an operationId
    message: Operation is missing an operationId
    severity: error
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: operationId
      function: truthy

  # All operations must have a summary in Title Case
  signal-operation-summary-required:
    description: All operations must have a summary
    message: Operation is missing a summary
    severity: error
    given: "$.paths[*][*]"
    then:
      field: summary
      function: truthy

  # Signal Server returns 204 for message sending (no content)
  signal-delete-returns-204:
    description: DELETE operations should return 204
    message: DELETE operations should define a 204 No Content response
    severity: warn
    given: "$.paths[*].delete.responses"
    then:
      field: "204"
      function: truthy

  # Pre-key upload operations should use PUT method
  signal-prekey-operations-use-put:
    description: Pre-key upload operations should use PUT method
    message: Pre-key upload should use PUT (idempotent key upload)
    severity: hint
    given: "$.paths[?(@property =~ /keys/)][put]"
    then:
      function: truthy

  # All responses must define at minimum a 401 error
  signal-auth-error-response:
    description: Operations should define 401 unauthorized response
    message: Operation should define a 401 Unauthorized response
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch].responses"
    then:
      field: "401"
      function: truthy

  # API key base64 parameters should document encoding
  signal-base64-key-format:
    description: Cryptographic key fields should document Base64 encoding
    message: Cryptographic key properties should specify Base64 pattern
    severity: hint
    given: "$.components.schemas[*].properties[?(@.description =~ /base64/i)]"
    then:
      field: pattern
      function: truthy