Wipe Platform Admin Documentation on Wipe Platform Admin Docs

Local Stack

Mon, 01 Jan 0001 00:00:00 +0000

Local Stack

Run the full local stack from the repository root:

 docker compose up --build

The root compose file builds the backend and the SvelteKit portal, then starts PostgreSQL with PGMQ, Keycloak, MinIO, Mailpit, OpenTelemetry Collector, Prometheus, Loki, Tempo, Grafana, API, workers, and frontend.

Service URLs

Service	URL	Notes
API	`http://localhost:8080`	Backend API, `/healthz`, `/readyz`, Swagger.
Swagger UI	`http://localhost:8080/swagger/index.html`	Generated from backend annotations.
Frontend BFF	`http://localhost:5174`	The SvelteKit portal, and the only UI. `/` for tenants, `/admin` for platform administrators, `/verify` for public certificate checks. OIDC tokens stay server-side.
Admin docs	`http://localhost:5175`	Static Hugo/LotusDocs administrator handbook.
Keycloak	`http://localhost:8081`	`admin` / `admin`.
PostgreSQL	`localhost:5432`	`wipe` / `wipe`, database `wipe`.
MinIO console	`http://localhost:9001`	`minioadmin` / `minioadmin`.
Mailpit	`http://localhost:8025`	Captured SMTP messages.
Grafana	`http://localhost:3000`	`admin` / `admin`.
Prometheus	`http://localhost:9090`	Scrapes OTel Collector exporter.
Loki	`http://localhost:3100`	Logs.
Tempo	`http://localhost:3200`	Traces.
OTLP gRPC/HTTP	`localhost:4317`, `localhost:4318`	Telemetry ingest.

Seeded Accounts

Realm	Username	Password	Role
`master`	`platform-admin`	`admin`	`PLATFORM_ADMIN`
`master`	`billing-operator`	`admin`	`BILLING_OPERATOR`
`exawipe`	`client-admin`	`admin`	`CLIENT_ADMIN`
`exawipe`	`client-tech`	`admin`	`CLIENT_TECH`
`exawipe`	`auditor`	`admin`	`AUDITOR`

The seeded direct-access clients are wipe-admin-cli for the master realm and wipe-dev-cli for the exawipe realm. The newer frontend BFF requires standard-flow web clients with PKCE: wipe-portal-admin in master and wipe-portal in exawipe.

Tenants And Organizations

Mon, 01 Jan 0001 00:00:00 +0000

Tenants And Organizations

Use these routes with a PLATFORM_ADMIN token.

Tenant Lifecycle

Action	Route
List tenants	`GET /admin/api/v1/tenants`
Create tenant	`POST /admin/api/v1/tenants`
Read tenant	`GET /admin/api/v1/tenants/{tenant_id}`
Update tenant	`PATCH /admin/api/v1/tenants/{tenant_id}`
Delete tenant	`DELETE /admin/api/v1/tenants/{tenant_id}`

Create tenants with a stable slug, display name, optional instance_fingerprint, and optional branding.

 {
 "name": "Example Tenant",
 "slug": "example-tenant",
 "instance_fingerprint": "sha256:example"
}

Tenant deletion is a backend soft delete. Treat it as an operationally sensitive action and keep the audit record attached to the change.

Host Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Host Deployment

The repository includes host deployment notes for wipe.stack-plane.com. The same pattern applies to a single VM or bare-metal host that runs Docker Compose behind host Nginx.

Prepare Environment

Copy the host environment template and replace every placeholder:

 cp deploy/host/wipe.stack-plane.com.env.example .env

Review at minimum:

Group	Required values
Public URLs	API, frontend, Keycloak, verification, invitation, callback URLs.
Secrets	PostgreSQL, Keycloak, S3, SMTP, frontend session secret, OIDC client secrets.
Admin access	`ADMIN_API_ALLOWED_CIDRS`, `ADMIN_API_ALLOW_INTERNAL_NETWORKS`, MFA window.
Storage	S3 endpoint, bucket names, credentials, optional filesystem fallback.
Signer	`SIGNER_MODE`, endpoint, bearer or mTLS material, key IDs, TSA settings.
Observability	OTel endpoint, environment name, logs/metrics/traces routing.

Do not reuse local default passwords or seeded API keys outside local development.

Users And Invitations

Mon, 01 Jan 0001 00:00:00 +0000

Users And Invitations

Platform admins can create and maintain tenant users through the tenant API when the target tenant and organization are supplied. Client admins can perform the same workflow inside their own organization scope.

Routes

Action	Route	Roles
List users	`GET /api/v1/users`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`
Create user and invitation	`POST /api/v1/users`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`
Update user profile	`PUT /api/v1/users/{id}`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`
Delete user by body alias	`DELETE /api/v1/users`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`
Delete user by path	`DELETE /api/v1/users/{id}`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`
Accept invitation	`POST /api/v1/invitations/accept`	Public token route

Create User

Example request:

IdP Federation

Mon, 01 Jan 0001 00:00:00 +0000

IdP Federation

Identity provider federation is configured by a PLATFORM_ADMIN and must be approved by a second PLATFORM_ADMIN before it becomes public discovery metadata.

Routes

Action	Route
Read organization IdP metadata	`GET /admin/api/v1/organizations/{id}/idp`
Configure IdP metadata	`POST /admin/api/v1/organizations/{id}/idp`
Approve IdP metadata	`POST /admin/api/v1/organizations/{id}/idp/approve`
Home realm discovery	`POST /api/v1/auth/discover`

Configure IdP

Example request:

 {
 "tenant_id": "11111111-1111-4111-8111-111111111111",
 "provider": "saml",
 "metadata_url": "https://idp.example/metadata",
 "idp_url": "https://idp.example/login",
 "entity_id": "https://idp.example/entity",
 "display_name": "Example IdP"
}

The backend stores the metadata with status=PENDING_APPROVAL, requested_by, and requested_at. Pending metadata is not exposed by auth discovery.

Runtime Services

Mon, 01 Jan 0001 00:00:00 +0000

Runtime Services

The platform is a modular Go backend plus SvelteKit frontends. Runtime state is externalized to PostgreSQL and object storage.

Backend Binaries

Binary	Compose service	Command	Purpose
`api`	`api`	`/app/api`	Main HTTP API, admin API, public verification, embedded ingest in dev.
`ingest`	Optional standalone	`/app/ingest`	Agent-only `/ingest/v1` gateway with dedicated least-privilege DB role.
`worker-proof`	`proof-worker`	`/app/worker-proof`	Consumes `proofs.validated`; validates `.der`, decrypts, signs, creates certificates.
`worker`	`anchor-worker`	`/app/worker anchor`	Consumes `certificates.to_anchor`; submits/updates anchors and regenerates PDFs after anchoring.
`worker`	`notification-worker`	`/app/worker notifications`	Consumes `notifications.to_send`; sends SMTP/webhook deliveries and records retries/DLQ.
`worker`	`report-worker`	`/app/worker reports`	Schedules and creates monthly billing reports and billing export artifacts.
`worker`	`retry-worker`	`/app/worker retry`	Enqueues due proof retries and re-tests recoverable proof states.
`worker`	`maintenance-worker`	`/app/worker maintenance`	Applies retention/anonymization and verifies audit/receipt chains.
`migrator`	`db-migrate` profile	`/app/migrator`	Runs embedded SQL migrations.
`verifier`	CLI image target	`/app/verifier`	Offline verification CLI foundation.

The worker binary chooses its kind from the first argument or WORKER_KIND. WORKER_ONCE=true runs one claim pass and exits, which is useful for controlled maintenance or release validation.

Branding And Email Templates

Mon, 01 Jan 0001 00:00:00 +0000

Branding And Email Templates

Branding is organization-scoped JSON. It controls organization display metadata and the invitation email template used for new users.

Routes

Action	Route	Roles
Read branding	`GET /api/v1/organizations/{id}/branding`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`
Update branding	`PUT /api/v1/organizations/{id}/branding`	`CLIENT_ADMIN`, `PLATFORM_ADMIN`

Platform admins must pass the target organization ID and tenant scope because a master realm token is not naturally tenant-scoped.

Branding Payload

Example:

 {
 "branding": {
 "app_name": "Example Wipe",
 "logo_url": "https://static.example.com/logo.png",
 "email_templates": {
 "user_invited_subject": "Welcome to {{app_name}}",
 "user_invited_text": "You have been invited to {{organization_name}} as {{role}}. Accept: {{accept_url}}",
 "user_invited_html": "<html><body><img src=\"{{logo_url}}\" alt=\"{{app_name}} logo\"><p>You have been invited to {{organization_name}} as <strong>{{role}}</strong>.</p><p><a href=\"{{accept_url}}\">Accept invitation</a></p></body></html>"
 }
 }
}

The admin platform can edit logo_url, app_name, and the email_templates.* fields. The backend renders the email body from these templates rather than sending raw JSON.

Configuration Reference

Mon, 01 Jan 0001 00:00:00 +0000

Configuration Reference

The backend is configured from environment variables. The canonical local list is backend/.env.example; the root compose file supplies defaults for the reference stack.

Core HTTP And Public URLs

Variable	Use
`DEPLOYMENT_MODE`	`cloud`, `onprem`, or `airgapped`; do not rely on it alone for network policy.
`HTTP_ADDRESS`	API bind address, usually `:8080`.
`HTTP_SHUTDOWN_TIMEOUT`	Graceful shutdown window.
`HTTP_CORS_ALLOW_ORIGINS`	Browser origins allowed to call the API directly.
`HTTP_HSTS_ENABLED`	Enables HSTS when TLS terminates at the API or trusted proxy chain.
`PUBLIC_VERIFY_BASE_URL`	Base URL used in certificate QR and public verification links.
`PUBLIC_INVITATION_BASE_URL`	Base URL used in invitation acceptance links.

Security Controls

Variable	Use
`ADMIN_API_ALLOWED_CIDRS`	Explicit IP/CIDR allowlist for `/admin/api/v1`.
`ADMIN_API_ALLOW_INTERNAL_NETWORKS`	Allows loopback/private/link-local admin clients for internal deployments.
`SENSITIVE_ACTION_MFA_MAX_AGE`	Recent-MFA window for sensitive writes; `0` disables local-only checks.
`SECURITY_OUTBOUND_ALLOWED_HOSTS`	Host allowlist for IdP metadata, branding URLs, and webhooks.
`SECURITY_OUTBOUND_ALLOWED_CIDRS`	Explicit IP ranges allowed by outbound URL policy.
`SECURITY_OUTBOUND_ALLOW_PRIVATE_NETWORKS`	Only enable for controlled internal deployments.
`VERIFY_RATE_LIMIT_PER_MINUTE` / `VERIFY_RATE_LIMIT_PER_HOUR`	Public verification rate limits.
`VERIFY_CAPTCHA_SECRET` / `VERIFY_CAPTCHA_VERIFY_URL`	Optional Turnstile/hCaptcha-style siteverify integration.

Identity And Keycloak

Variable	Use
`KEYCLOAK_MASTER_ISSUER` / `KEYCLOAK_EXAWIPE_ISSUER`	Public issuer URLs that must match JWT `iss`.
`KEYCLOAK_MASTER_AUDIENCE` / `KEYCLOAK_EXAWIPE_AUDIENCE`	Expected JWT audiences.
`KEYCLOAK_MASTER_JWKS_URL` / `KEYCLOAK_EXAWIPE_JWKS_URL`	JWKS endpoints used by the API.
`KEYCLOAK_JWKS_CACHE_TTL`	JWKS cache duration.
`KEYCLOAK_ADMIN_*`	Optional Admin API service-account configuration for provisioning users and IdPs.

For the new frontend BFF, configure APP_BASE_URL, API_INTERNAL_URL, KEYCLOAK_ISSUER_MASTER, KEYCLOAK_ISSUER_EXAWIPE, KEYCLOAK_INTERNAL_URL, web client IDs/secrets, and a 32-byte or longer SESSION_SECRET.

API Keys And Agents

Mon, 01 Jan 0001 00:00:00 +0000

API Keys And Agents

API keys are organization-scoped automation credentials. They are managed by CLIENT_ADMIN today, not by PLATFORM_ADMIN admin routes.

API Key Routes

Action	Route	Role
List keys	`GET /api/v1/api-keys`	`CLIENT_ADMIN`
Create key	`POST /api/v1/api-keys`	`CLIENT_ADMIN`
Rotate key	`POST /api/v1/api-keys/{id}/rotate`	`CLIENT_ADMIN`
Revoke key	`POST /api/v1/api-keys/{id}/revoke` or `DELETE /api/v1/api-keys/{id}`	`CLIENT_ADMIN`

Create request:

 {
 "name": "CI proof uploader",
 "organization_id": "22222222-2222-4222-8222-222222222222",
 "scopes": ["proofs:write", "proofs:read"]
}

The generated secret is returned once. Store it immediately. Later list calls show metadata and prefix only.

Migrations And Release

Mon, 01 Jan 0001 00:00:00 +0000

Migrations And Release

Use migrations and generated-contract checks as release gates. Do not depend on runtime AutoMigrate outside local development.

Image Build Matrix

The backend Dockerfile ships one Go build stage and exposes several runtime targets. CI publishes each as a separate image; the default runtime target remains a combined image for local compatibility.

Image	Docker target	Entrypoint
`wipe-api`	`api-runtime`	`/app/api`
`wipe-proof-worker`	`proof-worker-runtime`	`/app/worker-proof`
`wipe-worker`	`worker-runtime`	`/app/worker`
`wipe-verifier-cli`	`verifier-cli-runtime`	`/app/verifier`
`wipe-migrator`	`migrator-runtime`	`/app/migrator`

Build an individual image locally from the repository root (requires EXAWIPE_PROOF_READ_TOKEN in the environment; see Repository Secrets):

Kubernetes With Helm And Argo CD

Mon, 01 Jan 0001 00:00:00 +0000

Kubernetes With Helm And Argo CD

The compose stack in Host deployment is a single-host reference shape. For a regulated environment the same services run on Kubernetes from the wipe Helm chart in deploy/helm/wipe, synced by Argo CD from deploy/argocd.

What The Chart Deploys

Workload	Image	Shape
API	`wipe-api`	Deployment plus Service on 8080. Serves `/ingest/v1` on the same port while `INGEST_EMBEDDED=true`.
Ingest gateway	`wipe-ingest`	Disabled by default. Enable only with `INGEST_EMBEDDED=false`.
Proof worker	`wipe-proof-worker`	Deployment, scaled horizontally.
Anchor worker	`wipe-worker-anchor`	Single replica with the `Recreate` strategy; anchoring submits ordered messages.
Notification, report, retry workers	`wipe-worker-notifications`, `wipe-worker-reports`, `wipe-worker-retry`	Deployments.
Maintenance worker	`wipe-worker-maintenance`	Single replica with the `Recreate` strategy.
Migrations	`wipe-migrator`	Hook Job, not a Deployment.
Portal	`wipe-frontend`	SvelteKit BFF on the main hostname, and the only UI: `/` for tenants, `/admin` for platform administrators, `/verify` for public certificate checks.
Operator docs	`wipe-admin-docs`	This site, static Hugo behind nginx.

Workers expose no HTTP surface, so they carry no probes. The Go images are distroless and have no shell, which rules out exec probes everywhere. The portal does have health routes: the SvelteKit frontend answers /healthz once its server loop runs and /readyz once the API dependency responds, which is what its probes use.

Licenses And Billing

Mon, 01 Jan 0001 00:00:00 +0000

Licenses And Billing

License grants are platform-admin managed. Tenant billing exports are available to tenant admins, and restricted tenant-selected billing views are available to platform admins and billing operators.

License Grants

Action	Route	Roles
List license grants	`GET /admin/api/v1/license-grants`	`PLATFORM_ADMIN`, `BILLING_OPERATOR`
Import license grant	`POST /admin/api/v1/license-grants`	`PLATFORM_ADMIN`
Import license grant alias	`POST /admin/api/v1/license-grants/import`	`PLATFORM_ADMIN`

Example import:

 {
 "tenant_id": "11111111-1111-4111-8111-111111111111",
 "grant_id": "55555555-5555-4555-8555-555555555555",
 "grant_type": "QUANTITY",
 "instance_fingerprint": "sha256:example",
 "license_type": "desktop",
 "quantity": 100,
 "valid_from": "2026-01-01",
 "valid_until": "2026-12-31",
 "commercial_chain": ["Exaion", "Example Operator"],
 "signature": "dev-signature"
}

Imports validate the signed instance fingerprint against the tenant, reject duplicate grants globally, validate addendum and revocation chains, and require the commercial chain to start with Exaion and end with the current operator. The final production Exaion keyring/rotation policy remains part of the signer readiness backlog.

Proofs And Certificates

Mon, 01 Jan 0001 00:00:00 +0000

Proofs And Certificates

Proofs are .der files produced by the wipe agent. The backend stores the raw proof object before processing and uses asynchronous workers to validate, decrypt, sign, certify, and optionally anchor the result.

Submission Routes

Route	Auth	Use
`POST /api/v1/proofs`	`CLIENT_ADMIN`, `CLIENT_TECH`, or generic `proofs:write` API key	Submit one multipart `.der` proof.
`POST /api/v1/proofs/bulk`	`CLIENT_ADMIN`, `CLIENT_TECH`, or generic `proofs:write` API key	Submit up to 100 files or a ZIP archive, max 500 MB.
`POST /ingest/v1/proofs`	Enrolled-agent API key with `proofs:write`	Submit one raw `.der` body from an enrolled agent.
`GET /ingest/v1/proofs/{id}`	Enrolled-agent API key with `proofs:read`	Poll the status of an agent-owned proof.

Protected writes require Idempotency-Key. The unit proof size limit is 5 MB. The local rate limits are per authenticated principal or agent key: 100 unit submissions per hour and 500 batch submissions per hour. Each quota is a separate counter, shared across all API and ingest replicas through the database (rate_limit_windows, migration 0025); a 429 carries Retry-After.

Webhooks And Notifications

Mon, 01 Jan 0001 00:00:00 +0000

Webhooks And Notifications

The backend has a notification worker that sends SMTP messages and signed webhook deliveries from the notifications.to_send queue. Invitations and billing export delivery metadata are currently the most visible email flows; certificate webhooks are emitted for certificate.issued.

Webhook Routes

Action	Route	Role
List subscriptions	`GET /api/v1/webhooks`	`CLIENT_ADMIN`
Create subscription	`POST /api/v1/webhooks`	`CLIENT_ADMIN`
Delete subscription	`DELETE /api/v1/webhooks/{id}`	`CLIENT_ADMIN`

Example:

 {
 "url": "https://hooks.example.com/wipe",
 "events": ["certificate.issued"]
}

The subscription secret is returned once on creation. Store it in the receiving system immediately.

Common Pitfalls

Mon, 01 Jan 0001 00:00:00 +0000

Common Pitfalls

A short list of mistakes that have either happened already or are easy to make on first contact with the platform. Read this before operating a non-local instance.

Dev Secrets Outside Local

Secret	Why it bites you
`wipe_dev_agent.0123456789abcdef0123456789abcdef`	Seeded proof-automation API key with `proofs:write` and `proofs:read`. If accepted by a non-local instance, anyone holding the seed can submit proofs.
`wipe_dev_enroll.0123456789abcdef0123456789abcdef`	Seeded one-time enrollment code. If enrollment is enabled in a shared environment, an attacker can enroll a rogue agent.
`KEYCLOAK_MASTER_SEED_USER_PASSWORD` / `admin`	Default passwords for seeded users. Never reuse outside `DATABASE_SEED_DEV=true` local stacks.
`TEST_SIGNER_SEED`	Test signer HMAC seed. Production must use a remote signer with real custody; the test signer is not a custody boundary.

Rule of thumb: if DATABASE_SEED_DEV=true, AGENT_DEV_ENROLLMENT_ENABLED=true, LICENSE_DEV_MODE=true, or SIGNER_MODE=test is set, the environment is not production-safe.

Workers And Queues

Mon, 01 Jan 0001 00:00:00 +0000

Workers And Queues

The backend uses a PostgreSQL table-backed queue. Jobs are claimed with locking semantics and dead-lettered after retry exhaustion. The operator source of truth is the database plus structured worker logs and OpenTelemetry metrics.

Queues

Queue	Producer	Consumer	Purpose
`proofs.validated`	Proof submit routes	`worker-proof`	Validate proof, decrypt payload, create certificate, consume license, sign PDF/receipt.
`certificates.to_anchor`	Certificate service	`worker anchor`	Submit or update blockchain anchor metadata and regenerate certificate PDF.
`notifications.to_send`	User, billing, webhook flows	`worker notifications`	Send SMTP/webhook notifications, retry failures, write delivery metadata.
`billing.exports`	Billing export routes	`worker reports`	Generate requested export artifacts.
`reports.monthly`	Report scheduler	`worker reports`	Generate monthly billing report artifacts.
`proofs.retry`	Retry routes/scheduler	`worker retry`	Re-enqueue due failed or awaiting-license proofs.

The local PostgreSQL/PGMQ setup also seeds underscore queue aliases that resolve to the same jobs table: proofs_validated, certificates_to_anchor, notifications_to_send, billing_exports, reports_monthly, and proofs_retry. The dot-notation form above is canonical; treat the underscore form as a Compose/PGMQ compatibility alias only.

Observability And Alerts

Mon, 01 Jan 0001 00:00:00 +0000

Observability And Alerts

The current implementation emits OpenTelemetry signals to the collector. The reference stack routes metrics to Prometheus, logs to Loki, traces to Tempo, and dashboards/alerts to Grafana.

The backend does not expose a Prometheus /metrics endpoint by default. Prometheus scrapes the OpenTelemetry Collector Prometheus exporter.

Local URLs

Component	URL
Grafana	`http://localhost:3000`
Prometheus	`http://localhost:9090`
Loki	`http://localhost:3100`
Tempo	`http://localhost:3200`
OTLP gRPC	`localhost:4317`
OTLP HTTP	`localhost:4318`

Signal Fields

HTTP logs include:

Audit, Verification, And Retention

Mon, 01 Jan 0001 00:00:00 +0000

Audit, Verification, And Retention

The backend records admin/sensitive actions in the audit log and public verification attempts in verification_log. The maintenance worker handles retention, verification metadata anonymization, and tamper-evident chain checks.

Audit Routes

Route	Role	Scope
`GET /admin/api/v1/audit`	`PLATFORM_ADMIN`, `BILLING_OPERATOR`	Recent audit rows across the instance.
`GET /api/v1/audit`	`CLIENT_ADMIN`, `AUDITOR`	Tenant-scoped audit rows.

Audit entries are append-oriented and include hash-chain fields. The maintenance worker verifies audit-chain continuity and records metrics/alerts on breaks.

Incident Response

Mon, 01 Jan 0001 00:00:00 +0000

Incident Response

Use this page for first response. Record the incident, capture request IDs, trace IDs, affected tenant/organization IDs where permitted, and the exact time window before replaying or deleting anything.

Keycloak Outage

Impact:

New login/token requests fail.
Existing API calls may continue briefly while tokens and JWKS cache remain valid.
User, invitation, IdP, and provisioning operations should pause.

Triage:

Check keycloak and keycloak-postgres container health.
Query the realm metadata endpoint from the API network (not the browser): curl -fsS <issuer>/realms/<realm>/.well-known/openid-configuration.
Check API logs for JWT/JWKS fetch errors and elevated 401 responses.
Confirm public issuer URLs still match the configured JWT iss.

Recovery:

Backup And Restore

Mon, 01 Jan 0001 00:00:00 +0000

Backup And Restore

Backups are an operations responsibility. The repository provides the data layout and runtime services, but the final backup tooling depends on the target host or Kubernetes platform.

What To Back Up

Asset	Why it matters
PostgreSQL application database	Tenants, organizations, users, proofs, certificates, jobs, DLQ, audit, receipts, licenses, idempotency, verification logs.
Keycloak database/config	Realms, clients, users, roles, federation, credentials metadata.
Object storage buckets	Raw `.der` proofs, PDFs, canonical JSON, binaries, exports, monthly reports.
Environment and secrets	Runtime config, DB/S3/SMTP/Keycloak credentials, signer mTLS material, frontend session secret.
Signer key custody records	Production signer owns cryptographic keys; back up according to signer/HSM policy, not application DB policy.
Nginx/TLS config	Public routing, certificates, redirects, callback behavior.
Generated release artifacts	Image tags/digests, SBOM/provenance, Swagger/client versions.

Do not place API key raw secrets, JWTs, signer private keys, or production license signing material in application backups.

API Contract And Release Checks

Mon, 01 Jan 0001 00:00:00 +0000

API Contract And Release Checks

The backend owns the API contract. Swagger is generated from Go annotations, and the route-contract tool compares generated Swagger paths with the cahier-derived route backlog.

Contract Files

File	Purpose
`backend/docs/api-routes.md`	Product route backlog extracted from the backend cahier.
`backend/docs/swagger/swagger.json`	Generated OpenAPI JSON.
`backend/docs/api-contract-status.md`	Human-readable implemented/missing route comparison.
`backend/docs/api-contract-status.json`	Machine-readable route comparison.
`frontend/src/lib/api/client`	Generated HeyAPI client for the portal.

Current status: all 54 expected cahier backlog operations are represented in Swagger. Additional implemented routes include tenant admin CRUD, API keys, webhooks, audit, public verification aliases, agent campaign revocation, and ingest proof polling.

Signer Boundary

Mon, 01 Jan 0001 00:00:00 +0000

Signer Boundary

The signer is the only component allowed to perform private-key operations: certificate PDF signatures, blockchain transaction signatures, defensive certificate HMACs, and decryption of agent proof envelopes. Everything else in the platform consumes the signer as a service.

Current State: In-Process Test Signer

Local and CI stacks use the in-process test signer. It is not a custody boundary.

Attribute	Value
Mode	`SIGNER_MODE=test`
Package	`internal/adapters/signer/testsigner`
Seed	`TEST_SIGNER_SEED` (shared by API and proof worker so HMAC verification is stable)
Capabilities	`proof-envelope:v1` decryption, deterministic HMACs, RSA-backed PAdES signing, placeholder blockchain transaction signing
Trust	None — no remote custody, no durable key store, no approval workflow, no hardware backing

Both SIGNER_MODE=test and AGENT_TRUST_MODE=dev are refused at startup when ENVIRONMENT, APP_ENV, or OBSERVABILITY_ENVIRONMENT is set to prod or production. Do not run production load against SIGNER_MODE=test. A dedicated signer service is the production boundary.

Wipe Platform Admin Documentation on Wipe Platform Admin Docs

Local Stack

Local Stack link

Service URLs link

Seeded Accounts link

Tenants And Organizations

Tenants And Organizations link

Tenant Lifecycle link

Host Deployment

Host Deployment link

Prepare Environment link

Users And Invitations

Users And Invitations link

Routes link

Create User link

IdP Federation

IdP Federation link

Routes link

Configure IdP link

Runtime Services

Runtime Services link

Backend Binaries link

Branding And Email Templates

Branding And Email Templates link

Routes link

Branding Payload link

Configuration Reference

Configuration Reference link

Core HTTP And Public URLs link

Security Controls link

Identity And Keycloak link

API Keys And Agents

API Keys And Agents link

API Key Routes link

Migrations And Release

Migrations And Release link

Image Build Matrix link

Kubernetes With Helm And Argo CD

Kubernetes With Helm And Argo CD link

What The Chart Deploys link

Licenses And Billing

Licenses And Billing link

License Grants link

Proofs And Certificates

Proofs And Certificates link

Submission Routes link

Webhooks And Notifications

Webhooks And Notifications link

Webhook Routes link

Common Pitfalls

Common Pitfalls link

Dev Secrets Outside Local link

Workers And Queues

Workers And Queues link

Queues link

Observability And Alerts

Observability And Alerts link

Local URLs link

Signal Fields link

Audit, Verification, And Retention

Audit, Verification, And Retention link

Audit Routes link

Incident Response

Incident Response link

Keycloak Outage link

Backup And Restore

Backup And Restore link

What To Back Up link

API Contract And Release Checks

API Contract And Release Checks link

Contract Files link

Signer Boundary

Signer Boundary link

Current State: In-Process Test Signer link

Local Stack

Service URLs

Seeded Accounts

Tenants And Organizations

Tenant Lifecycle

Host Deployment

Prepare Environment

Users And Invitations

Routes

Create User

IdP Federation

Routes

Configure IdP

Runtime Services

Backend Binaries

Branding And Email Templates

Routes

Branding Payload

Configuration Reference

Core HTTP And Public URLs

Security Controls

Identity And Keycloak

API Keys And Agents

API Key Routes

Migrations And Release

Image Build Matrix

Kubernetes With Helm And Argo CD

What The Chart Deploys

Licenses And Billing

License Grants

Proofs And Certificates

Submission Routes

Webhooks And Notifications

Webhook Routes

Common Pitfalls

Dev Secrets Outside Local

Workers And Queues

Queues

Observability And Alerts

Local URLs

Signal Fields

Audit, Verification, And Retention

Audit Routes

Incident Response

Keycloak Outage

Backup And Restore

What To Back Up

API Contract And Release Checks

Contract Files

Signer Boundary

Current State: In-Process Test Signer