app.personalos-api

PersonalOS API

Thin Elysia host for subject-bound PersonalOS commands, minimized experience projections, event cursors, and online rights operations. The host fails closed until an AuthOS-compatible token verifier and runtime ports are injected. Session subject/actor identity, full delegation scopes, command names, and idempotency are checked before domain execution. Delegation identifiers alone never confer authority.

@lssm-tech/integration.personal-os-authos is the canonical production identity adapter. Its Better Auth bearer verifier rechecks the provider session for every request and emits the strict pseudonymous PersonalOS session shape consumed by tokenVerifier. Executable qualification issues a real magic-link session in a SQLite-backed Better Auth instance, calls GET /v1/projection with the issued bearer, revokes the provider session, and proves the same bearer receives 401. The projection contains neither the bearer, email address, raw provider user ID, nor raw provider session ID.

/v1/health is a public readiness endpoint, not a liveness fiction: it returns 503 not_ready when its injected readiness probe fails or reports unavailable, and every response is marked no-store.

The API accepts command envelopes with payload digests only. Sensitive command material belongs in an encrypted host channel and raw provider payloads are not part of the public contract.

Authenticated life administration is additive under GET /v1/life-admin, POST /v1/life-admin/commands, and POST /v1/life-admin/search. Reads return only the shared bounded projection with private, no-store; commands require the exact session actor, subject, idempotency key, canonical payload digest, revision, and server authority. The projection may include an exact-actor assigned-care window. Owner reads are subject-bound; delegated reads require a current explicit personal.life.care.read capability and fail closed on actor/version drift, expiry, or revocation. Concrete composition is opt-in through lifeAdminForSubject, which supplies the encrypted transaction, two-phase authority, verifier, audit, crypto, and identifier ports. Encrypted content references, provider credentials/payloads, receipts, and evidence never enter the response contract. Search requires a fresh exact session-bound query, online connectivity, active consent IDs, and a separately injected expiring authority issuer/verifier. Production composition reads only metadata from the encrypted aggregate; stale, unsupported, malformed, or unavailable rows never enter results.

Subject-owned support incidents use POST /v1/support/incidents/commands and GET /v1/support/incidents/:incidentId. The command route accepts only the strict support command wrapper; a client-supplied receipt or undeclared field is rejected. The authenticated session must exactly match the subject, actor, and idempotency header. The server runtime prepares the exact before/proposed state digests, obtains and independently verifies authority, atomically commits an allowed transition, or records a no-effect denial/confirmation audit. Reads return only the minimized incident cursor and are always no-store.

PersonalOS domain activation (RT-008) is fail-closed. Private finance, health and life-admin aggregates stay dormant until the composition injects domainActivation (activation store, consent facts, key-recovery probe and outbox-processor probe) and the subject has an active, consented activation record. GET /v1/activation/:domain returns the exact decision; blocked decisions carry only a stable reason such as host_binding_missing, activation_missing or consent_missing. Finance requires the activation boundary at composition time; there is no plaintext or parallel runtime path.

Activation-gated finance routes reuse the durable encrypted finance runtime: POST /v1/finance/commands executes typed finance commands (committed or replayed return 202), and POST /v1/finance/tax-recovery/dossiers returns a tax-recovery-v1 proposal whose items cite original encrypted documents. The dossier is never filed, submitted, paid or externally confirmed; submission is an explicit human action outside PersonalOS.

Activation lifecycle: POST /v1/activation/:domain lets the subject (never a delegate) activate a domain on named, currently granted consents, and POST /v1/activation/:domain/revocations revokes it. Health authorization, domain: 'health' workspace commands, life-admin and finance routes are all gated. Existing subjects are migrated by the idempotent PostgreSQL carry-forward backfill before the gate is enabled; the loopback E2E server activates its consented subject through the same carry-forward path.

health-routine-v1: POST /v1/health/routine/commands records typed signals, withdraws one, sets context or erases the routine into the encrypted subject aggregate; GET /v1/health/routine/proposal returns the subject-only view; GET /v1/health/routine/export returns the subject export. Export and erase_routine remain available after consent withdrawal.

Remote health authorization uses these locked routes:

• POST /v1/health/connection-authorizations accepts only provider kind, categories, an allowlisted relative return path, request/idempotency IDs, and request time. Subject, actor, and session assurance come from authentication; browser-supplied PKCE, OAuth state, credentials, and authority are rejected.
• GET /v1/health/connection-authorizations/:ticketId returns a subject-bound, secret-free status.
• GET|POST /v1/health/connection-authorizations/callback/:providerKind passes raw provider code/state directly to the injected host broker without persistence. The broker consumes stored PKCE/state once, deletes both, atomically persists a bound secret-free connect dispatch before deletion. The API may then return 303 to a trusted configured PersonalOS web origin plus the ticket's allowlisted relative path; a separate worker can recover delivery if the callback process stops.

Begin and status use { data }; errors use { error: { code } }. No route returns a credential reference, authorization code, PKCE verifier, or raw provider payload. createPersonalOsProductionApiInput() accepts the concrete healthAuthorizationBrokerFactory, active consent resolution, subject state, encryption, two-phase authority, receipt verification, and decision-audit ports. The factory injects the workspace-backed command issuer into the broker; hard-coded consent/revision/receipt fixtures are not a production seam. Provider OAuth clients, secrets, redirect registration, and production canaries remain deployer-owned and unqualified locally.

GET /v1/projection validates the host projection at the wire boundary and rejects any subject or exact-actor mismatch before returning it. Loader and schema failures return only the stable no-detail projection_unavailable response; internal RoleMorph diagnostics never cross the HTTP boundary.

POST /v1/domain-commands accepts the typed PersonalOS workspace or health command wrapper and checks the authenticated subject/actor, delegation, idempotency header, payload digest, revision, and final receipt binding before returning 202. GET /v1/workspace returns only the minimized subject-owned workspace cursor with bounded, count-preserving planning, delegation, goal-scoped support, connection-status, and coach-adaptation summaries. When the deployer binds the wellbeing-goal query port, the same read composes an exact-subject bounded goal window before RoleMorph filtering. Invalid counts, subject-version drift, and adapter failures fail closed; raw measurements, evidence, target values, and provider fields never cross the endpoint. Every workspace read revalidates the current exact RoleMorph presentation. A missing, stale, invalid, differently bound, denied-area, or denied-component projection returns cursor metadata only and strips every sensitive domain summary through the shared fail-closed DataView adapter. Its planning summary includes current outcome value, confidence, collection mode, minimized evidence IDs, and correction/removal counts without reasons or prior values. The executable outcome journey records, corrects, and removes a self-reported observation, rejects payload substitution without revision drift, and proves the current projection changes without losing immutable history. The same endpoint accepts the high-risk consent workspace domain. Its loopback qualification proves digest substitution denial, exact grant, missing-revocation no-data-loss recovery, durable revocation receipts, replay, and denial of a goal write after its adopted consent is revoked. Workspace reads expose only active/revoked/expired counts and affected-consumer IDs. The same authenticated route accepts online-only guardrail and goal-conflict commands. Loopback qualification proves payload substitution denial, immediate goal pause, pre-authority progress denial with unchanged revision, minimized guardrail counts, evidence-bound resolution, and resumed progress. Support commands remain high-risk, human-required, and online-only; the runtime rejects stale goal evidence, inactive or substituted members, missing consent, and foreign actors before authority or persistence. Coach proposal and activation are online-only, presentation-only, expiry/consent bound, and default to human authority; any policy-governed mode requires exact feature or task scope. Inspect, undo, and reset remain human-required and online-only. Stale coach or adaptation revisions are denied before authority. The directly usable createPersonalOsProductionApiInput() factory wires those routes to subject-bound state, encryption, authority, and ID factories; it does not require the dynamic composition-module environment seam. The legacy V1 routes and deployer-owned loader remain compatible.

The executable HTTP qualification submits the shared household constructor through invitation, activation, delegation, digest-substitution denial with an unchanged revision, recovery, and revocation before reading the minimized experience projection. A second loopback qualification executes household bootstrap, mission, goal, Today plan, habit, check-in, missed-day recovery, and weekly review through the production composition. It substitutes the Today payload without rebinding its digest, proves the revision and prior state stay unchanged, then resumes the same journey to its minimized projection.

Production startup requires PERSONAL_OS_API_COMPOSITION_MODULE, whose module must export createPersonalOsApiInput(). Startup fails before binding a port if the composition is missing or malformed. This keeps AuthOS, PostgreSQL, rights, and command execution wiring explicit and deployer-owned.

Migrations

bun run --cwd packages/apps/personalos-api migrate is the packaged PersonalOS install step (founder-ops install-sequence step 5). Run it with the migrator credential in PERSONAL_OS_MIGRATOR_DATABASE_URL before enabling the activation gate. It applies the ledgered store migration and then the activation carry-forward for every AuthOS subject supplied by PERSONAL_OS_MIGRATION_COMPOSITION_MODULE, a deployer-owned module exporting createPersonalOsMigrationInput() (subjects plus consent facts from the host key service). PERSONAL_OS_MIGRATION_STORE_ONLY=true replaces the module only when no AuthOS subject exists yet; exactly one of the two is required. PERSONAL_OS_DATABASE_SSL_MODE (require by default, prefer or allow) and PERSONAL_OS_STORE_SCHEMA (default public) are optional. Re-runs are idempotent. The JSON report holds ledger ids and outcome counts only; exit code 2 means a usage or execution error. Afterwards founder-ops qualify-migrations reads the public.personal_os_schema_migrations ledger and forced RLS on every subject table.

bun run --cwd packages/apps/personalos-api migrate:rehearse rehearses the same step against PERSONAL_OS_TEST_DATABASE_URL, which must be a loopback database whose name contains test, disposable or rehearsal. It works in a throwaway schema with synthetic subjects, replays the run, checks forced RLS and the exact ledger, drops the schema and exits 0 only when rehearsed.

Local E2E qualification host

start:e2e runs an explicitly non-production, loopback-only host with the real production route composition, workspace reducers/projections, two-phase authority, AES-GCM encrypted in-memory state, and a durable in-process health authorization queue:

Its experience projection also injects explicit allow decisions for the six PersonalOS *.manage action boundaries and non-default presentation preferences so surface tests can exercise the complete journey. Those decisions exist only in the E2E composition; production composition remains fail-closed until its verified host supplies RoleMorph decisions and personalization inputs. The executable projection suite also replaces those decisions with missing and lookalike tuples over real HTTP and proves that display-only views remain available while every governed action stays blocked and decision reasons remain absent from the wire projection. A forbidden generated-UI marker forces the entire invalid presentation to be suppressed behind the same generic projection_unavailable response. The local host additionally emits an opaque test-only tenant/consent binding so surface session-boundary tests can exercise exact Personalization retirement without exposing a raw tenant label or consent artifact. It also runs the real support-incident runtime with an in-memory exact-subject transaction adapter. Qualification covers confirmation recovery, distinct person/support-agent transitions, bounded information exchange, resolution, appeal, closure, minimized reads, and pre-authority identity/idempotency denial. This does not qualify managed durable case custody, support staffing, notification delivery, accessibility operations, manual acceptance, or a production canary.

PERSONAL_OS_E2E_PORT=3199 \
PERSONAL_OS_E2E_WEB_ORIGIN=http://127.0.0.1:3000 \
PERSONAL_OS_E2E_NATIVE_AUTH_NONCE=<run-specific-32+-character-nonce> \
bun run --cwd packages/apps/personalos-api start:e2e

Utiliser Authorization: Bearer valid. The selected web origin is the only browser origin accepted by CORS. GET /v1/projection hydrates the real encrypted workspace and returns the current subject/actor, revision, journey progress, area readiness, and privacy counts. E2E rights completion is explicit and idempotent rather than inferred from pending work. Health begin returns a provider-shaped HTTPS URL with server-generated opaque OAuth state and an S256 challenge; it never returns the PKCE verifier, callback code, credential reference, receipt, or dispatch.

Before the first persisted command, GET /v1/workspace returns a minimized revision-zero projection with absent domain revisions; it does not persist or authorize state, and create-household remains the only runtime bootstrap mutation. When the optional native nonce is configured, the loopback host also accepts one exact no-store POST /__e2e/native-authos/session exchange using the x-personalos-e2e-native-auth-nonce header. The route is disabled when the nonce is absent, is never registered by production startup, and exists only so a development client can exercise the real authenticated mobile boundary without embedding a bearer token.

For deterministic provider simulation, copy state from that URL into the normal callback route:

• authorize: GET /v1/health/connection-authorizations/callback/:provider?state=…&code=authorization_code_e2e_success
• deny: GET /v1/health/connection-authorizations/callback/:provider?state=…&error=access_denied

To qualify durable retry, add x-personalos-e2e-fail-domain-commit-once: true to one callback. The E2E host strips this header before invoking the production API, fails exactly one state commit, retains the secret-free dispatch, and retries it through the normal ticket status route. This control does not exist in any production request schema or production startup path.

bun run --cwd packages/apps/personalos-api test:operations-rehearsal runs a bounded loopback performance and capacity rehearsal through the same executable host. It evaluates a 750 ms local-loopback API p95 ceiling and zero-error budget plus steady, burst, injected dependency-failure, and recovery scenarios with the governed personal-operations qualifier. This is local E2E evidence only: it does not replace representative devices, production RUM, soak or retry-storm tests, managed dependency failure, cost validation, or production canaries.

Life-admin channel effects

createPersonalCalendarEffectExecutor and createPersonalNotificationEffectExecutor execute leased life-admin outbox effects for the worker. Both check the subject's life_admin activation before the encrypted aggregate is loaded (loadGatedLifeAdminEffectState; createLifeAdminEffectStateLoader binds the encrypted store). Calendar calendar_reconciliation effects write back to the subject's own active, read-write provider connection resolved by the deployment host, pass the effect idempotency key as the provider request id, and report a provider error as indeterminate for reconciliation before any retry; declines are refused. Mail and in-app notification_delivery effects are routed through the CommunicationOS product producer: email only with PersonalOS email consent, otherwise the in-app terminal, and push is refused. A notification whose scheduledAt is still in the future returns { status: 'deferred', availableAt } without admitting anything; the worker must release the lease with that availableAt rather than acknowledge it. Without a calendar host or CommunicationOS host every effect fails closed.