Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
DSAR export contract (W3.1)

POST /api/v1/dsar with { requestType: "export", subjectId: "<customerId>" } enqueues an async export job. Polling GET /api/v1/dsar?status=completed returns the request with the export attached.

​
Default response shape

The exported data field is plain portable JSON (Article 20 compliant): 
{
  "customerId": "cust-123",
  "exportedAt": "2026-04-28T12:00:00.000Z",
  "encrypted": false,
  "data": {
    "interactions": [...],
    "summaries": [...],
    "variantAssignments": [...],
    "deliveries": [...],
    "auditLogs": [...],
    "consentRecords": [...],
    "dsarRequests": [...]
  },
  "counts": {
    "interactions": 1234,
    "summaries": 56,
    "variantAssignments": 12,
    "deliveries": 89,
    "auditLogs": 234,
    "consentRecords": 6,
    "dsarRequests": 1
  }
}
ConsentRecord rows are now part of the export (per Article 7 demonstrable-consent requirement). This is new in W3.1.

​
Encrypted at-rest envelope

For long-term archival, request encryption with ?encrypt=true (when calling exportSubjectData programmatically) or set the corresponding flag on the DSAR worker job. The encrypted shape: 
{
  "encrypted": true,
  "data": {
    "ciphertext": "<base64-encrypted-blob>",
    "format": "encrypted-aes-256-gcm"
  }
}
The encryption uses the platform’s AES-256-GCM key registry (versioned, rotatable). Decryption requires lib/encryption.decrypt() with the same key version.

​
Why the change

The third-party audit (2026-04-28) flagged that the previous DSAR export returned only an encrypted blob, failing GDPR Article 20’s right-to-portability. W3.1 makes plain JSON the default; encryption is opt-in for at-rest storage.

​
Resumable Flow runs (W3.2)

Long-running pipeline runs now persist a per-node checkpoint after each successful step. On retry of a failed run with the same runId, already-completed nodes are skipped and their cached output is reloaded from the checkpoint. Two backends:
StoreWhen
InMemoryCheckpointStoreTests, ephemeral local dev
PostgresCheckpointStoreProduction — persists to flow_run_checkpoint table
Migration: run prisma/manual-sql/07_flow_run_checkpoints.sql once per deployment (idempotent). The Helm chart’s existing manual-sql apply step picks it up automatically. API: import { runResumableDag, InMemoryCheckpointStore, PostgresCheckpointStore } from "@/lib/flow/runtime/checkpoint" — see platform/src/lib/flow/runtime/__tests__/checkpoint.test.ts for the four canonical scenarios (clean run, retry-after-failure, clear, hooks).

​
Release supply chain (W3.3)

Pushing a tag (git tag v0.5.0 && git push origin v0.5.0) triggers .github/workflows/release.yml:
  1. Checkout, install, generate Prisma client, run vitest.
  2. Generate CycloneDX 1.5 SBOM from package-lock.json via tools/scripts/generate-sbom.ts.
  3. Upload SBOM as a workflow artifact (365-day retention).
  4. If AWS_ROLE_ARN is configured as a repo variable:
    • Build + push Docker image to ECR.
    • Sign the image with Cosign (keyless via GitHub OIDC).
    • Generate SLSA v1 in-toto provenance via tools/scripts/generate-slsa-attestation.ts.
    • cosign attest --type slsaprovenance1 attaches the provenance.
  5. Create a GitHub Release with the SBOM file attached and auto-generated release notes.
If AWS_ROLE_ARN isn’t set (e.g. on forks), the workflow still builds the SBOM and creates the release — only the image-signing steps are skipped.

​
Verifying a signed release

After a release lands: 
cosign verify \
  --certificate-identity-regexp "https://github\.com/kaireonai/platform/\.github/workflows/release\.yml" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  422500312304.dkr.ecr.us-east-1.amazonaws.com/kaireon-api:v0.5.0
And to pull the SLSA provenance: 
cosign verify-attestation \
  --type slsaprovenance1 \
  --certificate-identity-regexp "https://github\.com/kaireonai/platform/\.github/workflows/release\.yml" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  422500312304.dkr.ecr.us-east-1.amazonaws.com/kaireon-api:v0.5.0 \
  | jq '.payload | @base64d | fromjson | .predicate'

​
Performance baseline (W3.4)

platform/perf/recommend.js is a k6 scenario file with three pre-baked RPS levels (1K / 5K / 10K). Running them is operator-driven (requires a load-test environment isolated from playground + credentialed API keys). The baseline procedure + run command is committed to platform/perf/baselines/2026-04-28-smoke.md.

​
Source files

  • platform/src/lib/dsar.ts — exportSubjectData(tenantId, customerId, { encrypt? })
  • platform/src/__tests__/lib/dsar-fire-drill.test.ts — 13 tests including 3 new for portable JSON / encrypt opt-in / consentRecords inclusion
  • platform/src/lib/flow/runtime/checkpoint.ts — InMemory + Postgres stores
  • platform/src/lib/flow/runtime/resumable-runner.ts — runResumableDag
  • platform/src/lib/flow/runtime/__tests__/checkpoint.test.ts — 4 tests
  • platform/prisma/manual-sql/07_flow_run_checkpoints.sql
  • tools/scripts/generate-sbom.ts
  • tools/scripts/generate-slsa-attestation.ts
  • .github/workflows/release.yml
  • platform/perf/baselines/2026-04-28-smoke.md