asyncapi: 2.6.0
info:
  title: residency-svc Async API
  version: 1.0.0
  description: |
    Kafka event channels for the EventZR Data Residency & Sovereignty Compliance Policy Engine.
    All events follow CloudEvents 1.0 specification. Partition key is tenant_id.
  contact:
    name: EventZR Platform Team
    email: platform@eventzr.com
  license:
    name: Proprietary

defaultContentType: application/cloudevents+json

servers:
  staging:
    url: boot-gpm4u49z.c2.kafka-serverless.us-east-1.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (Staging)
    security:
      - saslIam: []

channels:
  # ──────────────────────────────────────────────────────
  # PRODUCED EVENTS (16)
  # ──────────────────────────────────────────────────────

  eventzr.residency.policy.created.v1:
    description: Emitted when a new residency policy is created.
    publish:
      operationId: publishPolicyCreated
      message:
        $ref: '#/components/messages/PolicyEvent'

  eventzr.residency.policy.updated.v1:
    description: Emitted when a residency policy is updated.
    publish:
      operationId: publishPolicyUpdated
      message:
        $ref: '#/components/messages/PolicyEvent'

  eventzr.residency.policy.archived.v1:
    description: Emitted when a residency policy is archived.
    publish:
      operationId: publishPolicyArchived
      message:
        $ref: '#/components/messages/PolicyEvent'

  eventzr.residency.classification.updated.v1:
    description: Emitted when a data classification is created, updated, or deleted.
    publish:
      operationId: publishClassificationUpdated
      message:
        $ref: '#/components/messages/ClassificationEvent'

  eventzr.residency.consent.granted.v1:
    description: Emitted when a consent record is granted.
    publish:
      operationId: publishConsentGranted
      message:
        $ref: '#/components/messages/ConsentEvent'

  eventzr.residency.consent.revoked.v1:
    description: Emitted when a consent record is revoked.
    publish:
      operationId: publishConsentRevoked
      message:
        $ref: '#/components/messages/ConsentEvent'

  eventzr.residency.dsar.received.v1:
    description: Emitted when a new Data Subject Access Request is submitted.
    publish:
      operationId: publishDsarReceived
      message:
        $ref: '#/components/messages/DsarEvent'

  eventzr.residency.dsar.completed.v1:
    description: Emitted when a DSAR is fully completed.
    publish:
      operationId: publishDsarCompleted
      message:
        $ref: '#/components/messages/DsarEvent'

  eventzr.residency.dsar.deadline-approaching.v1:
    description: Emitted when a DSAR deadline is approaching (within 7 days).
    publish:
      operationId: publishDsarDeadlineApproaching
      message:
        $ref: '#/components/messages/DsarEvent'

  eventzr.residency.violation.detected.v1:
    description: Emitted when a compliance violation is detected during a check.
    publish:
      operationId: publishViolationDetected
      message:
        $ref: '#/components/messages/ViolationEvent'

  eventzr.residency.violation.resolved.v1:
    description: Emitted when a compliance violation is resolved or remediated.
    publish:
      operationId: publishViolationResolved
      message:
        $ref: '#/components/messages/ViolationEvent'

  eventzr.residency.compliance-check.completed.v1:
    description: Emitted when a compliance check finishes running.
    publish:
      operationId: publishComplianceCheckCompleted
      message:
        $ref: '#/components/messages/ComplianceCheckEvent'

  eventzr.residency.dpa.expiring.v1:
    description: Emitted when a Data Processing Agreement is about to expire.
    publish:
      operationId: publishDpaExpiring
      message:
        $ref: '#/components/messages/DpaEvent'

  eventzr.residency.retention.executed.v1:
    description: Emitted when a data retention policy execution completes.
    publish:
      operationId: publishRetentionExecuted
      message:
        $ref: '#/components/messages/RetentionEvent'

  eventzr.residency.breach.detected.v1:
    description: Emitted when a data breach is reported.
    publish:
      operationId: publishBreachDetected
      message:
        $ref: '#/components/messages/BreachEvent'

  eventzr.residency.breach.notified.v1:
    description: Emitted when a breach notification is sent to an authority or data subject.
    publish:
      operationId: publishBreachNotified
      message:
        $ref: '#/components/messages/BreachNotificationEvent'

  # ──────────────────────────────────────────────────────
  # CONSUMED EVENTS (10)
  # ──────────────────────────────────────────────────────

  eventzr.user.created.v1:
    description: Consumed to create default consent purposes for new user tenants.
    subscribe:
      operationId: onUserCreated
      message:
        $ref: '#/components/messages/UserCreatedEvent'

  eventzr.user.deleted.v1:
    description: Consumed to trigger RTBF (Right to Be Forgotten) verification and archive consent records.
    subscribe:
      operationId: onUserDeleted
      message:
        $ref: '#/components/messages/UserDeletedEvent'

  eventzr.backup.job.completed.v1:
    description: Consumed to update data location records with backup storage locations.
    subscribe:
      operationId: onBackupJobCompleted
      message:
        $ref: '#/components/messages/BackupJobCompletedEvent'

  eventzr.auth.consent.updated.v1:
    description: Consumed to sync consent changes from auth-svc.
    subscribe:
      operationId: onAuthConsentUpdated
      message:
        $ref: '#/components/messages/AuthConsentUpdatedEvent'

  eventzr.subscriptions.plan.changed.v1:
    description: Consumed to adjust available regulatory frameworks based on subscription tier.
    subscribe:
      operationId: onPlanChanged
      message:
        $ref: '#/components/messages/PlanChangedEvent'

  eventzr.notify.delivery.completed.v1:
    description: Consumed to track notification delivery status for breach notifications.
    subscribe:
      operationId: onNotifyDeliveryCompleted
      message:
        $ref: '#/components/messages/NotifyDeliveryCompletedEvent'

  eventzr.event.created.v1:
    description: Consumed to check cross-border data flows for newly created events.
    subscribe:
      operationId: onEventCreated
      message:
        $ref: '#/components/messages/EventCreatedEvent'

  eventzr.integration-hub.webhook.received.v1:
    description: Consumed to analyze webhooks for potential breach indicators.
    subscribe:
      operationId: onWebhookReceived
      message:
        $ref: '#/components/messages/WebhookReceivedEvent'

  eventzr.search.index.updated.v1:
    description: Consumed to update data location records when search indexes change.
    subscribe:
      operationId: onSearchIndexUpdated
      message:
        $ref: '#/components/messages/SearchIndexUpdatedEvent'

  eventzr.wallet.credit.deducted.v1:
    description: Consumed to log AI credit usage for compliance auditing.
    subscribe:
      operationId: onCreditDeducted
      message:
        $ref: '#/components/messages/CreditDeductedEvent'

components:
  securitySchemes:
    saslIam:
      type: scramSha512
      description: AWS MSK IAM authentication (SASL_SSL)

  messages:
    # ── Produced Messages ──────────────────────────────

    PolicyEvent:
      name: PolicyEvent
      title: Policy Lifecycle Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'
      headers:
        type: object
        properties:
          ce_type:
            type: string
            enum:
              - residency.policy.created
              - residency.policy.updated
              - residency.policy.archived

    ClassificationEvent:
      name: ClassificationEvent
      title: Classification Updated Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    ConsentEvent:
      name: ConsentEvent
      title: Consent Lifecycle Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    DsarEvent:
      name: DsarEvent
      title: DSAR Lifecycle Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    ViolationEvent:
      name: ViolationEvent
      title: Compliance Violation Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    ComplianceCheckEvent:
      name: ComplianceCheckEvent
      title: Compliance Check Completed Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    DpaEvent:
      name: DpaEvent
      title: DPA Expiring Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    RetentionEvent:
      name: RetentionEvent
      title: Retention Executed Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    BreachEvent:
      name: BreachEvent
      title: Breach Detected Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    BreachNotificationEvent:
      name: BreachNotificationEvent
      title: Breach Notified Event
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    # ── Consumed Messages ──────────────────────────────

    UserCreatedEvent:
      name: UserCreatedEvent
      title: User Created
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          userId:
            type: string
            format: uuid
          email:
            type: string

    UserDeletedEvent:
      name: UserDeletedEvent
      title: User Deleted
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          userId:
            type: string
            format: uuid

    BackupJobCompletedEvent:
      name: BackupJobCompletedEvent
      title: Backup Job Completed
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          jobId:
            type: string
            format: uuid
          storageLocation:
            type: string
          region:
            type: string

    AuthConsentUpdatedEvent:
      name: AuthConsentUpdatedEvent
      title: Auth Consent Updated
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          userId:
            type: string
            format: uuid
          consentType:
            type: string
          granted:
            type: boolean

    PlanChangedEvent:
      name: PlanChangedEvent
      title: Subscription Plan Changed
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          plan:
            type: string
          previousPlan:
            type: string

    NotifyDeliveryCompletedEvent:
      name: NotifyDeliveryCompletedEvent
      title: Notification Delivery Completed
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          notificationId:
            type: string
            format: uuid
          status:
            type: string
            enum: [delivered, failed, bounced]

    EventCreatedEvent:
      name: EventCreatedEvent
      title: Event Created
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          eventId:
            type: string
            format: uuid
          region:
            type: string

    WebhookReceivedEvent:
      name: WebhookReceivedEvent
      title: Integration Hub Webhook Received
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          webhookType:
            type: string
          source:
            type: string

    SearchIndexUpdatedEvent:
      name: SearchIndexUpdatedEvent
      title: Search Index Updated
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          indexName:
            type: string
          region:
            type: string

    CreditDeductedEvent:
      name: CreditDeductedEvent
      title: Wallet Credit Deducted
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          userId:
            type: string
            format: uuid
          amount:
            type: number
          reason:
            type: string

  schemas:
    CloudEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          description: CloudEvents event type
        source:
          type: string
          const: /residency-svc
        id:
          type: string
          format: uuid
          description: Unique event identifier
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          description: Event payload (varies by event type)
