# @lssm-tech/app.supportos-api

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.2.1`
- Package path: `packages/apps/supportos-api`
- Manifest path: `packages/apps/supportos-api/package.json`
- Manifest Git blob: `8a070ac68d101fd5a1515b6b22351ba3d9f407b7`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.supportos-api](https://lssm.co/docs/packages/app.supportos-api/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-api)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-api/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-api/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.supportos-api.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "company-and-work",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Company, work and service operations](https://lssm.co/docs/areas/company-and-work/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/supportos-api/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-api/README.md",
  "blobSha": "d8217c1d15ddeed7d78511015347110b8a5b1d6c",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# 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`](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-api/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.


## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

This workspace does not declare package export paths.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/integration.communication-os-client](https://lssm.co/docs/packages/integration.communication-os-client/): `workspace:*`
- [@lssm-tech/integration.customer-support-postgres](https://lssm.co/docs/packages/integration.customer-support-postgres/): `workspace:*`
- [@lssm-tech/integration.provider-database](https://lssm.co/docs/packages/integration.provider-database/): `workspace:^`
- [@lssm-tech/lib.communication-spec](https://lssm.co/docs/packages/lib.communication-spec/): `workspace:^`
- [@lssm-tech/lib.contracts-spec](https://lssm.co/docs/packages/lib.contracts-spec/): `workspace:^`
- [@lssm-tech/lib.customer-support-spec](https://lssm.co/docs/packages/lib.customer-support-spec/): `workspace:^`
- [@lssm-tech/lib.decision-runtime](https://lssm.co/docs/packages/lib.decision-runtime/): `workspace:^`
- [@lssm-tech/lib.observability](https://lssm.co/docs/packages/lib.observability/): `workspace:^`
- [@lssm-tech/module.customer-support](https://lssm.co/docs/packages/module.customer-support/): `workspace:*`
- `@opentelemetry/api`: `1.9.1`
- `jose`: `^6.2.12`
- `postgres`: `^3.4.9`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/lib.customer-support-runtime](https://lssm.co/docs/packages/lib.customer-support-runtime/): `workspace:*`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@types/bun`: `catalog:types`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "build": "bun build --target node --packages bundle --outfile dist/server.js src/server.ts",
  "capacity:assess": "bun run scripts/support-capacity.ts",
  "dev": "bun run --watch src/server.ts",
  "load": "bun run scripts/support-load.ts load",
  "soak": "bun run scripts/support-load.ts soak",
  "slo:assess": "bun run scripts/support-slo.ts",
  "start": "bun run src/server.ts",
  "supply-chain": "bun run scripts/support-supply-chain-sbom-cli.ts",
  "supply-chain:inventory": "bun run scripts/support-supply-chain.ts",
  "supply-chain:qualify": "bun run scripts/support-supply-chain-qualify.ts",
  "test": "bun test",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.supportos-api.txt",
  "route": "/llms/app.supportos-api",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.supportos-api.txt",
  "blobSha": "d8217c1d15ddeed7d78511015347110b8a5b1d6c",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```