# Pack Specification Language (PSL)
# Payment Service v2.4.1

pack:
  name: payment-service
  version: 2.4.1
  type: code
  author: platform-team
  created: 2024-11-15T10:00:00Z
  updated: 2024-12-02T08:00:00Z

metadata:
  repository: github.com/company/payment-service
  environment: production
  compliance:
    - PCI-DSS
    - SOC2

  api:
    - path: /v1/payments
      method: POST
      auth: required
      timeout_ms: 5000
      rate_limit: 100/minute
      idempotent: true
      request:
        user_id: uuid
        amount: decimal(10,2)
        currency: enum[USD,EUR,GBP]
        payment_method: string(max:50)
      response:
        payment_id: uuid
        status: enum[pending,processing,completed,failed]
        created_at: timestamptz

    - path: /v1/payments/{payment_id}
      method: GET
      auth: required
      timeout_ms: 2000
      rate_limit: 500/minute
      response:
        payment_id: uuid
        user_id: uuid
        amount: decimal(10,2)
        currency: enum[USD,EUR,GBP]
        status: enum[pending,processing,completed,failed]
        created_at: timestamptz
        updated_at: timestamptz

  data:
    payments:
      fields:
        id: uuid
        user_id: uuid
        amount: decimal(10,2)
        currency: enum[USD,EUR,GBP]
        status: enum[pending,processing,completed,failed]
        payment_method: string(max:50)
        created_at: timestamptz
        updated_at: timestamptz
      indexes:
        - [user_id, created_at]
        - [status, created_at]
      constraints:
        - "amount > 0"
        - "currency IN ('USD', 'EUR', 'GBP')"
      retention: 7y

    payment_events:
      fields:
        id: uuid
        payment_id: uuid
        event_type: enum[created,authorized,captured,failed,refunded]
        timestamp: timestamptz
        metadata: json
      indexes:
        - [payment_id, timestamp]
      partitioned_by: timestamp
      retention: 2y

  state:
    payment_lifecycle:
      initial: pending
      terminal:
        - completed
        - failed
      transitions:
        - from: pending
          to: processing
          trigger: authorization_requested
          guard: "amount > 0 AND payment_method IS NOT NULL"
          max_retries: 3

        - from: processing
          to: completed
          trigger: authorization_succeeded
          side_effect: "send_confirmation_email"

        - from: processing
          to: failed
          trigger: authorization_failed
          side_effect: "log_failure_reason"

        - from: pending
          to: failed
          trigger: validation_failed
          side_effect: "notify_user"

  integrations:
    stripe_gateway:
      type: payment_gateway
      endpoint: https://api.stripe.com/v1
      auth_type: bearer_token
      timeout_ms: 10000
      required: true
      circuit_breaker:
        failure_threshold: 5
        timeout_duration: 30s
        half_open_requests: 1
      retry:
        max_attempts: 3
        backoff: exponential
        initial_delay_ms: 1000

    auth_service:
      type: identity_provider
      endpoint: https://auth.company.com
      auth_type: oauth2
      timeout_ms: 3000
      required: true

    redis_cache:
      type: cache
      endpoint: redis://redis.company.com:6379
      timeout_ms: 500
      required: false
      fallback: "use_database_query"

  errors:
    - code: PAY-001
      message: "Payment amount must be positive"
      http: 400
      retry: false
      alert: false
      severity: info

    - code: PAY-002
      message: "Invalid currency code"
      http: 400
      retry: false
      alert: false
      severity: info

    - code: PAY-003
      message: "Payment gateway timeout"
      http: 504
      retry: true
      alert: true
      severity: error

    - code: PAY-004
      message: "Insufficient funds"
      http: 402
      retry: false
      alert: false
      severity: info

    - code: PAY-005
      message: "Internal payment processing error"
      http: 500
      retry: true
      alert: true
      severity: critical

  stack:
    language: typescript
    language_version: "5.3"
    framework: express
    runtime: node_20
    database: postgresql
    cache: redis
    message_queue: rabbitmq

  security:
    authentication:
      method: jwt
      issuer: "https://auth.company.com"
      audience: "payment-service"
      token_ttl: 1h

    authorization:
      model: rbac
      roles:
        - name: user
          permissions:
            - "payments:create:own"
            - "payments:read:own"

        - name: admin
          permissions:
            - "payments:*:*"
          inherits:
            - user

    encryption:
      at_rest: true
      in_transit: true
      algorithm: AES-256-GCM

  observability:
    metrics:
      - name: payment_requests_total
        type: counter
        labels: [method, status, currency]
        description: "Total payment requests processed"

      - name: payment_processing_duration_ms
        type: histogram
        labels: [method, currency]
        buckets: [10, 50, 100, 200, 500, 1000, 2000, 5000]
        description: "Payment processing time in milliseconds"

      - name: active_payments
        type: gauge
        labels: [status]
        description: "Number of payments in each status"

    logs:
      level: info
      format: json
      sensitive_fields:
        - payment_method
        - card_number
      action: redact

    traces:
      enabled: true
      sample_rate: 0.1
      propagation: w3c

traits:
  - resilient
  - auditable
  - scalable
  - secure
  - observable
  - testable
  - documented
  - idempotent

constraints:
  - id: SEC-001
    name: TLS Version Enforcement
    law: 2
    expression: tls_version >= 1.3
    severity: critical
    rationale: "PCI-DSS requires TLS 1.3 for payment data transmission"
    remediation: "Update load balancer and ingress configurations to enforce TLS 1.3"
    relaxable: false

  - id: PERF-001
    name: P99 Latency Budget
    law: 2
    expression: p99_latency_ms < 200
    severity: high
    rationale: "User experience degrades beyond 200ms response time"
    remediation: "Optimize database queries, add caching, or scale horizontally"
    relaxable: true
    relaxation_contexts:
      - batch_processing

  - id: DATA-001
    name: User ID Format Validation
    law: 1
    expression: user_id matches UUID
    severity: medium
    rationale: "UUID format prevents enumeration attacks and ensures uniqueness"
    remediation: "Validate UUID format at API boundary"
    relaxable: false

  - id: DATA-002
    name: Payment Amount Constraints
    law: 2
    expression: amount > 0 AND currency in [USD, EUR, GBP]
    severity: high
    rationale: "Business rule: only process positive amounts in supported currencies"
    remediation: "Add validation before payment processing"
    relaxable: false

  - id: DATA-003
    name: Cache TTL Consistency
    law: 1
    expression: cache_ttl = 300s
    severity: medium
    rationale: "Consistent cache invalidation across environments"
    remediation: "Synchronize cache configuration in all deployment targets"
    relaxable: true
    relaxation_contexts:
      - development
      - testing

  - id: SEC-002
    name: Auth Token Expiry Limit
    law: 2
    expression: token_ttl <= 3600s
    severity: high
    rationale: "Security requirement: limit token lifetime to 1 hour"
    remediation: "Configure auth service with 1-hour maximum TTL"
    relaxable: false

  - id: BUS-001
    name: Payment Status State Machine
    law: 4
    expression: status in [pending, processing, completed, failed]
    severity: medium
    rationale: "Finite state machine constraint for payment lifecycle"
    remediation: "Ensure all status transitions follow defined FSM"
    relaxable: false

  - id: COMP-001
    name: PCI-DSS Data Retention
    law: 2
    expression: payment_data_retention <= 7y
    severity: critical
    rationale: "PCI-DSS requires secure deletion after 7 years"
    remediation: "Implement automated data purging after retention period"
    relaxable: false

algebra:
  composition:
    operator: ∘
    rules:
      - expression: "payment-service ∘ auth-service"
        verification: "auth_service.provides(jwt) AND payment-service.requires(jwt)"
    associative: true
    commutative: false

  projection:
    operator: π
    domains:
      - security
      - performance
      - compliance

  relaxation:
    operator: 𝓡
    conditions:
      - context: development
        relax:
          - PERF-001
          - DATA-003
        requires_approval: false

      - context: production
        relax: []
        requires_approval: true

history:
  - version: 2.4.1
    timestamp: 2024-12-02T08:00:00Z
    author: platform-team
    changes: "Added observability metrics and error catalog"

  - version: 2.4.0
    timestamp: 2024-11-20T10:00:00Z
    author: platform-team
    changes: "Implemented circuit breaker for payment gateway"

  - version: 2.3.7
    timestamp: 2024-11-01T10:00:00Z
    author: platform-team
    changes: "Updated TLS to version 1.3"

lineage:
  parent: payment-service-v2
  children: []
  composed_from:
    - auth-service
    - notification-service

system_bindings:
  target: k8s/payment-service
  namespace: production
  cluster: us-east-1
  resources:
    cpu: 500m
    memory: 1Gi
    replicas:
      min: 3
      max: 10