Pack Approvals Notification Contract

Status: Implemented (NOTIFY-SVC-37-001) Last Updated: 2025-11-27 OpenAPI Spec: src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/openapi/pack-approvals.yaml

Overview

This document defines the canonical contract for pack approval notifications between Task Runner and the Notifier service. It covers event payloads, resume token mechanics, error handling, and security requirements.

Event Kinds

Canonical Event Schema

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "issuedAt": "2025-11-27T10:30:00Z",
  "kind": "pack.approval.requested",
  "packId": "pkg:oci/stellaops/scanner@v2.1.0",
  "policy": {
    "id": "policy-prod-deploy",
    "version": "1.2.3"
  },
  "decision": "pending",
  "actor": "ci-pipeline@stellaops.example.com",
  "resumeToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "summary": "Deployment approval required for production scanner update",
  "labels": {
    "environment": "production",
    "team": "security"
  }
}

Required Fields

Optional Fields

Resume Token Mechanics

Token Flow

┌─────────────┐     POST /pack-approvals      ┌──────────────┐
│ Task Runner │ ──────────────────────────────►│   Notifier   │
│             │   { resumeToken: "abc123" }   │              │
│             │◄──────────────────────────────│              │
│             │   X-Resume-After: "abc123"    │              │
└─────────────┘                               └──────────────┘
       │                                              │
       │                                              │
       │  User acknowledges approval                  │
       │                                              ▼
       │                              ┌──────────────────────────────┐
       │                              │  POST /pack-approvals/{id}/ack
       │                              │  { ackToken: "..." }         │
       │                              └──────────────────────────────┘
       │                                              │
       │◄─────────────────────────────────────────────┤
       │  Resume callback (webhook or message bus)    │

Token Properties

• Format: Opaque string; clients must not parse or modify
• TTL: 24 hours from issuedAt
• Uniqueness: Scoped to tenant + packId + eventId
• Expiry Handling: Expired tokens return 410 Gone

X-Resume-After Header

When resumeToken is present in the request, the server echoes it in the X-Resume-After response header. This enables cursor-based processing for Task Runner polling.

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "eventId, packId, kind, decision, actor are required.",
    "traceId": "00-abc123-def456-00"
  }
}

Retry Strategy

• Transient errors (5xx, 429): Exponential backoff starting at 1s, max 60s, max 5 retries
• Validation errors (4xx except 429): Do not retry; fix request
• Idempotency: Safe to retry any request with the same Idempotency-Key

Security Requirements

Authentication

All endpoints require a valid OAuth2 bearer token with one of these scopes:

• packs.approve — Full approval flow access
• Notifier.Events:Write — Event ingestion only

Tenant Isolation

• X-StellaOps-TenantId header is required on all requests
• Server validates token tenant claim matches header
• Cross-tenant access returns 403 Forbidden

Idempotency

• Idempotency-Key header is required for POST endpoints
• Keys are scoped to tenant and expire after 15 minutes
• Duplicate requests within the window return 200 OK

HMAC Signature (Webhooks)

For webhook callbacks from Notifier to Task Runner:

X-StellaOps-Signature: sha256=<hex-encoded-signature>
X-StellaOps-Timestamp: <unix-timestamp>

Signature computed as:

HMAC-SHA256(secret, timestamp + "." + body)

Verification requirements:

• Reject if timestamp is >5 minutes old
• Reject if signature does not match
• Reject if body has been modified

IP Allowlist

Configurable per environment in notifier:security:ipAllowlist:

notifier:
  security:
    ipAllowlist:
      - "10.0.0.0/8"
      - "192.168.1.100"

Sensitive Data Handling

• Resume tokens: Encrypted at rest; never logged in full
• Ack tokens: Signed with KMS; validated on acknowledgement
• Labels: Redacted if keys match secret, password, token, key patterns

Audit Trail

All operations emit structured audit events:

Observability

Metrics

Structured Logs

All operations include:

• traceId — Distributed trace correlation
• tenantId — Tenant identifier
• packId — Package identifier
• eventId — Event identifier

Integration Examples

Task Runner → Notifier (Ingestion)

curl -X POST https://notifier.stellaops.example.com/api/v1/notify/pack-approvals \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-TenantId: tenant-acme-corp" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "issuedAt": "2025-11-27T10:30:00Z",
    "kind": "pack.approval.requested",
    "packId": "pkg:oci/stellaops/scanner@v2.1.0",
    "decision": "pending",
    "actor": "ci-pipeline@stellaops.example.com",
    "resumeToken": "abc123",
    "summary": "Approval required for production deployment"
  }'

Console → Notifier (Acknowledgement)

curl -X POST https://notifier.stellaops.example.com/api/v1/notify/pack-approvals/pkg%3Aoci%2Fstellaops%2Fscanner%40v2.1.0/ack \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-TenantId: tenant-acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "ackToken": "ack-token-xyz789",
    "decision": "approved",
    "comment": "Reviewed and approved"
  }'

Related Documents

• Pack Approvals Integration Requirements
• Notifications Architecture
• Notifications API Reference
• Notification Templates