app.supportos-api

SupportOS API

Ownership: AuthOS claim-to-grant projection is owned by @lssm-tech/lib.customer-support-spec/authos-claim-projection; this host keeps the OIDC/JWKS verifier, issuer binding and live session checks that call it.

Standalone managed or self-hosted SupportOS HTTP host. A custom production composition may be injected through SUPPORT_OS_COMPOSITION_MODULE. Without one, the included zero-argument managed composition requires DATABASE_URL, SUPPORT_OS_AUTHOS_ISSUER, SUPPORT_OS_AUTHOS_JWKS_URL, SUPPORT_OS_AUTHOS_SESSION_STATUS_URL, SUPPORT_OS_AUTHOS_SESSION_EXCHANGE_URL, SUPPORT_OS_AUTHOS_DOWNSTREAM_EXCHANGE_URL, SUPPORT_OS_AUTHOS_WORKLOAD_TOKEN, SUPPORT_OS_ALLOWED_ORIGINS, SUPPORT_OS_DATA_PROTECTION_KEY, COMMUNICATION_OS_API_ORIGIN, SUPPORT_OS_COMMUNICATION_SERVICE_TOKEN, SUPPORT_OS_CONNECT_DECISION_URL, and SUPPORT_OS_CONNECT_SERVICE_TOKEN; it fails closed when any authority dependency is absent. When support.opa-handoffs is enabled it additionally requires COMPANYOS_OPA_API_ORIGIN. Internal-note verification exchanges the workload credential for a grant lasting no more than five minutes and bound to the communicationos-support audience, tenant, workspace, actor, and verify capability; OPA destination resolution uses a separate short-lived companyos-opa-support grant bound to the exact tenant, workspace, case, handoff, and destination.

When support.service-profiles is enabled, managed composition additionally requires COMPANYOS_SUPPORT_API_ORIGIN. It exchanges the SupportOS workload credential for a grant lasting no more than five minutes and bound to the companyos-support audience, tenant, workspace, actor, exact profile, and verification capability. The CompanyOS verification request contains only party/context references, consent/source evidence, and the mutation digest; encrypted or plaintext field values are never forwarded. Startup and readiness fail closed until the dependency is configured and healthy. Readiness probes the dedicated CompanyOS service-profile readiness route, not a generic product root, so an origin without the evidence receiver stays out of rotation.

When support.company-actions is enabled, managed composition additionally requires COMPANYOS_SUPPORT_API_ORIGIN, CONNECT_OS_SUPPORT_API_ORIGIN, and WORKFLOW_OS_SUPPORT_API_ORIGIN. It exchanges the workload credential for separate grants bound to the exact action plan and digest in the companyos-support, connect-support, and workflow-support audiences. CompanyOS returns only a minimized case/profile/entitlement evidence projection; Connect decides; Workflow alone starts effects and verifies outcomes. All three dedicated readiness routes must advertise the exact capability set with fresh evidence before the API enters rotation. The API stores and returns opaque references only and exposes no amount, customer body, provider payload, grant, or credential.

When support.notifications is enabled, managed composition additionally requires SUPPORT_OS_NOTIFICATION_POLICY_URL, SUPPORT_OS_NOTIFICATION_POLICY_READY_URL, SUPPORT_OS_NOTIFICATION_DELIVERY_EVIDENCE_URL, SUPPORT_OS_NOTIFICATION_DELIVERY_EVIDENCE_READY_URL, SUPPORT_OS_NOTIFICATION_WORKER_READY_URL, and SUPPORT_OS_QUEUE_READY_URL. Policy and delivery responses must echo the exact authenticated scope, resource references, and request digest over bounded HTTPS calls. Readiness requires the SupportOS worker to advertise notification.deliver; a scoped workspace flag can never override the global kill switch.

When support.data-lifecycle is enabled, managed composition additionally requires SUPPORT_OS_ERASURE_PROTECTION_ORIGIN, SUPPORT_OS_ERASURE_PROTECTION_TOKEN, SUPPORT_OS_ERASURE_PROTECTION_READY_URL, SUPPORT_OS_ERASURE_WORKER_READY_URL, and SUPPORT_OS_QUEUE_READY_URL. Protection and Connect calls are bounded HTTPS requests and must echo their exact scope, resource, digest, decision, and idempotency bindings. Readiness requires durable-deletion protection capabilities and a SupportOS worker that advertises erasure.execute; scoped flags cannot override the global kill switch. The API never receives or returns the plaintext erasure subject.

createPostgresSupportOsApiInput remains the injectable self-hosted factory. The included managed composition verifies short-lived AuthOS OIDC grants against HTTPS JWKS, checks live AuthOS session status, intersects grant capabilities with current PostgreSQL membership, verifies every membership mutation against the configured Connect decision endpoint, uses scope-bound AES-GCM protected references, and connects to CommunicationOS through an authenticated bridge. In-memory authority and the deprecated HMAC compatibility resolver are never selected implicitly.

The managed composition also recognizes a dedicated AuthOS bootstrap grant for POST /api/support/v1/workspaces/onboard. It verifies issuer, audience, validity, revocation/session state, and the non-delegable support.workspace.onboard capability without performing the impossible pre-creation membership lookup. The PostgreSQL authority then requires an independent scoped flag and a state-bound Connect response before creating the workspace and founding administrator atomically.

The portable API is versioned at /api/support/v1. Browser hosts exchange an AuthOS session cookie through POST /api/support/v1/auth/session-exchange; the managed adapter permits only configured HTTPS origins, requires a CSRF token, forwards no caller authorization header, and authorizes the returned grant against live session and membership state before returning it. Tenant and workspace scope always comes from the authenticated composition, never from request bodies or query parameters. Protected POST /cases and POST /cases/{caseRef}/transitions operations require bounded idempotency headers; transitions also require an expected revision. Responses carry a correlation ID, and malformed, oversized, unauthorized, stale, conflicting, rate-limited, and degraded requests use stable error envelopes.

DecisionGraph lifecycle management is available under /api/support/v1/decisions only when both support.contracts and support.decisioning are enabled. Managed PostgreSQL composition supplies the typed lifecycle authority; authenticated scope is server-derived, mutations use bounded idempotency headers and draft revision fences, and list continuation is bound to a database-issued watermark.

When a host injects workspaceMigrationGovernance, the PostgreSQL composition also exposes protected workspace-migration preview, get, start, advance, and rollback operations. Managed deployment leaves this authority absent until a real Connect bridge is configured; there is no implicit allow-all decision path. The independent support.workspace-migration global/workspace flag is checked at both HTTP and PostgreSQL authority boundaries.

GET /healthz reports process liveness only. GET /readyz and the compatibility /api/support/v1/health projection fail closed unless the current PostgreSQL migration and every required worker, queue, feature-flag, and adapter probe are ready. The managed composition reads worker and queue probe URLs from SUPPORT_OS_WORKER_READY_URL and SUPPORT_OS_QUEUE_READY_URL. Enabling support.sla-clocks additionally requires SUPPORT_OS_SLA_WORKER_READY_URL; that endpoint must identify itself as the SupportOS worker, report ready, and advertise the registered sla.clock handler. Internal-note, SLA, and notification worker probes are conjunctive when their lanes are enabled.

Every non-liveness request has a bounded deadline (SUPPORT_OS_REQUEST_DEADLINE_MS, default 15 seconds). SIGINT and SIGTERM stop new work, abort in-flight request signals, wait up to SUPPORT_OS_SHUTDOWN_GRACE_MS (default 30 seconds), and force-close connections only after the grace period. Uncooperative timed-out work remains counted until it actually settles, so drain status cannot become falsely healthy.

Every configured authority origin (*_ORIGIN, SUPPORT_OS_ALLOWED_ORIGINS) and endpoint URL is checked by one validator (src/https-origin.ts) on the raw value: https:// (or wss:// for the realtime origin) written out, no whitespace, control characters, backslashes or userinfo (not even a bare @), no percent-encoded, numerically rewritten or trailing-dot host, and an explicit port only in 1-65535 (the default port is normalized away). IDN hosts are accepted and compared as punycode. An origin carries no path, query or fragment, not even an empty ? or #; endpoint URLs never carry a fragment. Values the URL parser would silently repair, such as a trailing newline, fail startup.

The API starts the shared OpenTelemetry SDK as supportos-api (or the bounded operator-supplied OTEL_SERVICE_NAME) and exports to OTEL_EXPORTER_OTLP_ENDPOINT when configured. A configured collector must be a credential-free HTTPS URL; malformed, plaintext, credential-bearing, query, or fragment endpoints fail startup. Non-liveness request metrics use only method, finite route family, status family, success/failure, and bounded duration. Raw paths, path identifiers, query strings, headers, cookies, grants, case data, messages, answers, contacts, prompts, errors, and secrets are never dimensions. Telemetry failure never changes request authority. Distributed tracing, worker/provider/ AI/SLA signals, dashboards, alerts, retention/residency enforcement, load cardinality, burn-rate gates, and production canaries remain open.

The explicitly armed load/soak harness and its privacy boundary are documented in docs/load-qualification.md. It creates a non-overwriting, digest-bound aggregate artifact for the current readiness, case-list, case-detail, and search surfaces. A one-hour or eight-hour local run is not a substitute for governed production evidence, backlog recovery, provider, outbox, export, AI, capacity, or canary qualification.