> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/hosted-services.md). # Hosted Services ## Current Boundary Hosted services are optional or planned. Core local FactionOS workflows must keep working without hosted auth, cloud persistence, hosted analytics, Cloudflare credentials, Anthropic keys, Discord, Telegram, or generic webhook credentials. ## Phase 07 Baseline Phase 07 Session 01 records the hosted-services requirements, routing, and payload privacy baseline in: * `.spec_system/archive/phases/phase_07/hosted_services_requirements_privacy_baseline.md` * `.spec_system/archive/phases/phase_07/phase07_requirement_routing_matrix.md` * `.spec_system/archive/phases/phase_07/hosted_payload_privacy_blocklist.md` These files are planning artifacts. They do not enable hosted auth, hosted storage, analytics capture, push delivery, public replay hosting, remote access, tunnels, hosted diagnostics, production-hosted validation, or trusted erasure. Later Phase 07 sessions own source changes and tests for those surfaces where scoped. ## Phase 07 Closeout Status Phase 07 is complete. Session 07 validated the hosted-services and analytics guardrails described below end to end (20 focused test files / 183 tests, full suite 2186 passed / 1 skipped, format/lint/typecheck/build/secret-scan all green) and confirmed requirement closure for P07-R001 through R025 (22 closed by validated sessions, 3 deferred to Phase 08). Shipped Phase 07 guardrails: hosted configuration exposure boundaries (S02), planned-state hosted identity contracts and diagnostics (S03), hosted persistence and public replay inactive states (S04), consent-gated analytics controls (S05), and push/remote-access/tunnel unavailable states with compact operator diagnostics (S06). Every hosted surface remains optional, planned, inactive, unavailable, or explicitly gated, and none is required for core local workflows. Routed to Phase 08 release hardening: trusted unified erasure, production-hosted (deployed app and Worker) validation, release hardening, mobile and WCAG certification, and legacy decommission. Phase 07 makes no active hosted-auth, hosted-storage, analytics-capture, push-delivery, public-replay-hosting, remote-access, or trusted-erasure claim. Phase 08 Session 01 adds the release claim baseline in `.spec_system/archive/phases/phase_08/release_requirements_risk_baseline.md` and the routing matrix in `.spec_system/archive/phases/phase_08/phase08_requirement_routing_matrix.md`. Those artifacts keep hosted identity, hosted storage, analytics capture, public replay, push, remote access, trusted erasure, production-hosted validation, and certification as no-claim or owner-gated surfaces unless the Phase 08 release-candidate record or a later scoped release record proves the specific claim. They do not activate hosted services. ## Hosted Configuration Boundary Phase 07 Session 02 adds source-backed hosted configuration contracts without enabling a hosted feature. The shared contract in `packages/protocol/src/hostedConfig.ts` defines active-local, public-client, server-only secret, deploy-only, reserved future, and blocked categories. The server consumes that vocabulary through `GET /diagnostics/hosted-config`, which returns status labels, counts, categories, exposure labels, and docs paths only. Browser-visible config remains limited to documented public-client values. The current accepted browser default is `VITE_FACTIONOS_WARROOM_WORKER_URL`, which must be a credential-free http(s) Worker URL with no query string or fragment. Reserved `VITE_SUPABASE_*` values stay local-only and reserved until a later hosted identity or persistence session adds source, consent, redaction, authorization, fallback, tests, and docs. Known or secret-like `VITE_` mirrors of server-only or deploy-only values are blocked. ## Hosted Identity Boundary Phase 07 Session 03 adds source-backed hosted identity guardrails without enabling hosted accounts. The baseline lives in `.spec_system/archive/phases/phase_07/hosted_identity_authorization_guardrails.md`, with shared vocabulary in `packages/protocol/src/hostedIdentity.ts`, local status diagnostics in `GET /diagnostics/hosted-identity`, and browser planned-state copy in `apps/web/src/lib/hostedIdentity.ts`. Hosted identity status is currently `planned` or `unavailable`, with local-only fallback required. Before account identity can become active, a later session must define and validate sign-in, PKCE or equivalent flow, token validation, session expiry, logout, revocation, consent, account export, deletion handoff, role mapping, organization membership source, authorization checks, audit events, abuse controls, and user-visible failure paths. The current War Room Worker authority remains one room-scoped bearer proof. It is not hosted account identity, SSO, organization membership, public collaboration safety, analytics consent, production audit proof, or trusted erasure. Participant names, ids, colors, roles, online flags, and approval state remain room metadata only. Hosted identity diagnostics are posture-only. They may expose status labels, requirement labels, unsupported claim labels, non-overclaim labels, counts, and docs paths. They must not expose raw account tokens, OAuth codes, refresh tokens, ID tokens, account ids, raw Worker authority tokens, request bodies, local paths, prompts, commands, replay buffers, exports, archives, diagnostics, logs, backups, or env values. ## Hosted Persistence And Public Replay Boundary Phase 07 Session 04 adds source-backed hosted persistence and public replay guardrails without enabling hosted storage. The baseline lives in `.spec_system/archive/phases/phase_07/hosted_persistence_public_replay_boundaries.md`, with shared vocabulary in `packages/protocol/src/hostedPersistence.ts`, local status diagnostics in `GET /diagnostics/hosted-persistence`, and browser planned-state copy in `apps/web/src/lib/hostedPersistence.ts`. Hosted persistence status is currently `planned` or `unavailable`, and public replay hosting is `disabled`. Current runtime has no Supabase client, database, bucket, storage migration, upload endpoint, browser direct storage write, account-backed persistence, public replay page, public replay index, takedown runtime, release-grade deletion, or trusted erasure workflow. Data eligibility is intentionally narrow: * Future eligible data may be considered later only after consent, authorization, retention, export, deletion, audit, and local fallback exist. * Account, organization, replay publish, and takedown data require server-mediated authorization by default before storage. * Replay fragments, logs, backups, and browser/local state remain local-only. * Diagnostics and replay summaries are redacted-only. * Local exports and archives are user-export-only local artifacts. * Prompts, transcripts, file contents, commands, terminal output, secrets, broad paths, replay buffers, export bodies, archives, backups, diagnostics, scan payloads, media drafts, War Room payloads, cloud account ids, and quarantined historical content are blocked from hosted persistence and public replay by default. Before hosted storage can become active, a later session must ship matching schema artifacts, migrations or bucket policies where applicable, RLS or authorization tests, server mediation, consent, retention, export, deletion, audit, abuse controls, duplicate-action guards, timeout/failure handling, and docs in the same scope as the runtime behavior. Current replay sharing remains redacted local URL-fragment sharing. Any hosted public replay surface needs explicit consent, replay event and byte caps, redaction, expiration, takedown, no-index posture, abuse controls, public-safe errors, and local-only fallback before activation. Trusted unified erasure, production-hosted validation, release hardening, certification, and release-grade deletion claims require matching release-record evidence. Session 04 defines requirements only and must not be used as erasure evidence. ## Hosted Analytics Boundary Phase 07 Session 05 adds source-backed analytics consent and payload controls. The baseline lives in `.spec_system/archive/phases/phase_07/analytics_consent_payload_controls.md`, with shared vocabulary in `packages/protocol/src/hostedAnalytics.ts` and browser readiness and payload helpers in `apps/web/src/lib/hostedAnalytics.ts`. Umami is the selected optional default provider from ADR 0003, and it may be self-hosted. Browser analytics is disabled by default and sends only approved minimized events through Umami `/api/send` when public config and consent are ready. `FACTIONOS_ANALYTICS_ENABLED=true`, `FACTIONOS_ANALYTICS_PROVIDER`, `UMAMI_HOST_URL`, `UMAMI_WEBSITE_ID`, and `UMAMI_API_KEY` are insufficient without browser-safe `VITE_` config, consent, and payload controls. Opt-out overrides config and prior consent. The current web helper can evaluate disabled, unavailable, consent-required, opted-out, or ready guardrail state from caller-provided config and consent input. The runtime sender posts approved event envelopes only when readiness is `ready`; otherwise it returns without fetching. It does not inject a tracking script, import an analytics SDK, store account-backed consent, or ship a dashboard. Settings shows passive analytics status copy only. Local Umami setup and browser verification steps live in `docs/runbooks/local-umami-analytics.md`. Approved analytics payloads are allowlisted to coarse product posture fields such as event id, surface, route id, status, feature, action, provider, consent state, bounded counts, duration buckets, category, reason codes, version labels, and docs paths. `localOnly` is kept in local helper results and stripped before network send. Payload helpers drop unknown keys and block prompts, provider prompts, transcripts, file/code content, command bodies, terminal output, secrets, credential values, full URLs, broad paths, exports, replay buffers, scans, diagnostics, logs, backups, media drafts, War Room payloads, account ids, zone ids, tunnel tokens, and quarantined historical content. This guardrail is replaceable by design. Future providers must use the shared protocol vocabulary, keep local-only fallback visible, preserve disabled defaults and opt-out dominance, and add tests and docs before runtime capture is activated. The optional Umami runtime sender has been verified locally against a loopback-only self-hosted Umami instance. Browser-originated `cockpit_view`, `settings_status_view`, `hosted_guardrail_status`, and `war_room_local_status` events were accepted by Umami and visible in Umami's own Events dashboard. That evidence does not create a production-hosted app claim, a FactionOS analytics dashboard claim, hosted identity, hosted storage, public replay hosting, trusted erasure, or a requirement for local users to run Umami. ## Push, Remote Access, Tunnel, And Operator Diagnostics Boundary Phase 07 Session 06 adds source-backed hosted operation guardrails without enabling push delivery, remote access, tunnels, or hosted diagnostic agents. The baseline lives in `.spec_system/archive/phases/phase_07/push_remote_access_operator_diagnostics_guardrails.md`, with shared vocabulary in `packages/protocol/src/hostedOperations.ts`, local status diagnostics in `GET /diagnostics/hosted-operations`, CLI loopback-only posture output, and browser local notification posture helpers. Browser notifications remain local OS notifications. The web app can request browser notification permission only through user action, show active-tab or service-worker local notifications, and fall back to in-app toasts. It does not create push subscriptions, call a push backend, route notifications through a server, read VAPID keys, or claim Web Push delivery. The service worker's future push handler is bounded and sanitizes title, body, tag, icon, and click target fields; it accepts only same-origin relative navigation targets. VAPID variables are reserved future placeholders. `VAPID_PUBLIC_KEY` may become browser-visible only after a reviewed Web Push session. `VAPID_PRIVATE_KEY` is server-only and must not appear in `VITE_` variables, browser bundles, diagnostics, logs, docs examples, replay buffers, exports, archives, or public demo code. `VAPID_SUBJECT` is sender metadata, not activation proof. Remote access and Cloudflare Tunnel remain unavailable. `CLOUDFLARE_TUNNEL_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_ZONE_ID`, and `CLOUDFLARE_API_TOKEN` are deploy-only or secret-bearing operational values. They must not appear in browser config, health responses, diagnostics, logs, replay, exports, archives, or docs examples. Any later remote access or tunnel feature needs explicit opt-in, token expiration and revocation, local auth, Origin/CORS, rate limits, audit, abuse controls, redaction, timeout handling, and tests. Hosted operation diagnostics are posture-only. They may expose status labels, surface labels, requirement labels, unsupported claim labels, blocked payload labels, booleans, bounded counts, and docs paths. They must not expose raw subscriptions, VAPID private keys, Cloudflare ids, zone ids, tunnel tokens, request bodies, local paths, prompts, commands, terminal output, room payloads, logs, backups, exports, archives, replay buffers, scan payloads, media drafts, or env values. ## Current Optional Integrations | Integration | Current role | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Anthropic | Optional LLM provider when `ANTHROPIC_API_KEY` is set. Fallbacks exist when unset. | | Cloudflare Workers and Durable Objects | Optional War Room backend in `apps/warroom`; the web client can use it for room lifecycle, health diagnostics, approval, presence, reconnect, bounded catch-up, and allowlisted redacted federation. | | Cloudflare Pages | Official static public demo deployment for `public-demo/`. | | Discord | Optional outbound adapter. | | Telegram | Optional outbound adapter. | | Generic webhook | Optional outbound adapter. | | GitHub Pages | Legacy/fallback static public demo deployment. | ## Current Cloudflare Deployments | Surface | Current deployment | | --------------------------------- | ------------------------------------------------------------------ | | Public demo Pages project | `factionos-public-demo` | | Public demo custom domain | `https://demo.faction-os.com/` | | War Room Worker | `factionos-warroom` | | War Room Worker custom domain | `https://warroom.faction-os.com/` | | War Room Worker `workers.dev` URL | `https://factionos-warroom.apex-web-services-llc-0d4.workers.dev/` | Cloudflare API checks on 2026-05-29 confirmed the Pages custom domain and Worker custom domain are active enough for health checks. Managed/OWASP WAF execution was not entitled on the current account/zone, and the zone's single available rate-limit rule slot is already used by `Leaked credential check`. The War Room Worker therefore relies on its app-level fixed-window limiter until Cloudflare plan capacity or security priorities change. ## Production-Hosted Validation Boundary Phase 08 Session 05 adds `npm run release:hosted-smoke` as a repeatable smoke gate for deployed surfaces. It checks the public demo Pages shell and service worker, the War Room Worker custom-domain `/health`, the War Room Worker workers.dev `/health`, and an optional app shell only when `FACTIONOS_PRODUCTION_APP_URL` or `FACTIONOS_HOSTED_APP_URL` is set. This command does not activate hosted auth, hosted storage, analytics capture, public replay hosting, push delivery, remote access, Cloudflare Tunnel, hosted diagnostic agents, production accounts, or trusted erasure. Missing credentials, absent app hosts, and `--no-network` runs are unavailable no-claim states. Sanitized output may record target ids, safe hostnames, statuses, booleans, timing buckets, docs paths, and issue codes only. It must not include raw URLs with query strings, Cloudflare account ids, zone ids, API tokens, request bodies, room payloads, prompts, local paths, exports, logs, backups, replay buffers, or raw dashboard output. Phase 08 Session 08 records final release-candidate hosted-smoke outcomes in `.spec_system/archive/phases/phase_08/release_candidate_validation_record.md`. No-network smoke passed as unavailable/no-claim evidence. Live hosted smoke did not authorize deployed-hosted claims: public demo reported `SENSITIVE_OUTPUT`, both Worker targets reported `WORKER_DEPLOYMENT` and `WORKER_HEALTH_RATE_LIMIT`, and the optional app shell reported `TARGET_UNAVAILABLE`. These are production-hosted claim blockers, not failures of the local-first app, and they must stay in release copy until a safe live hosted smoke passes. ## War Room Hosted Boundary The Worker and Durable Object surface is not hosted auth, hosted storage for core local data, analytics, public replay hosting, or a remote executor. It is an optional room relay for compact participant and allowlisted collaboration state. The local server remains the loopback runtime and `/warroom` compatibility/status stub. Current War Room federation blocks prompts, file contents, command bodies, terminal output, transcripts, secret values, broad paths, exports, replay buffers, media drafts, scan payloads, local diagnostics, and logs from Worker federation. Later hosted account, analytics, public replay, and unified erasure work remains deferred unless a future PRD changes scope. Phase 08 Session 04 adds a hosted identity release gate to protocol, server diagnostics, and browser helpers. The gate is explicit `no_claim`: no active hosted auth runtime, SSO, organization membership, account UI, analytics consent runtime, public collaboration safety claim, production audit proof, or trusted erasure claim exists. Room-local Worker authority remains bearer proof for one room only and is not hosted account identity. Phase 06 Session 01 keeps the Worker as optional collaboration transfer, not a hosted-service dependency. The baseline in `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md` also blocks diagnostics, PID files, spool entries, backups, archives, memory findings, settings snapshots, and quarantined historical content from shared collaboration payloads. Phase 06 does not ship hosted identity, hosted storage, analytics dashboards, public replay hosting, remote execution, Docker execution, production-hosted validation, or trusted erasure. ## Deferred Hosted Surfaces Supabase project bootstrapping exists only as parked local configuration for a future hosted phase. No current runtime package imports Supabase, no client is created, no tables or buckets are defined, and no hosted auth flow is active. | Surface | PRD guardrail | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Supabase auth and persistence | Requires local-only fallback, server-mediated access by default, PKCE/JWKS validation, minimal OAuth scopes, account lifecycle controls, consent, revocation, RLS or authorization tests, abuse controls, audit events, and account export/deletion docs. Publishable keys may become browser config; secret or service-role keys must remain server-only. | | Umami analytics | Selected optional default provider. Readiness requires browser-safe config plus consent, opt-out wins, payloads are allowlisted and scrubbed, and the optional runtime sender posts only approved minimized events. No dashboard, tracking script, SDK, recorder, heatmap, or session replay is active. | | Push notifications | Browser notifications are local OS notifications only. Web Push requires a reviewed backend, subscription consent, VAPID exposure rules, unsubscribe, retention, payload minimization, and visible local fallback before activation. | | Remote access | Unavailable. Requires explicit opt-in, token expiration and revocation, local auth, rate limits, Origin/CORS, audit, unsupported-state handling, abuse controls, and no remote executor claims before activation. | ## Variable And Payload Categories Phase 07 uses these categories before any hosted surface is described as active: * Active local: consumed by current local source or tooling. * Public-client: browser-visible and publishable only when documented, revocable, non-secret, and backed by local-only fallback. * Server-only secret: bearer tokens, provider keys, webhook secrets, service-role keys, VAPID private keys, and future hosted secrets. * Deploy-only: Cloudflare account, API, zone, Pages, Worker, and tunnel values used for deployment or operations only. * Reserved future: Supabase, Umami, VAPID, push, public replay, tunnel, and hosted-service placeholders that are not consumed by current runtime unless source proves otherwise. * Blocked: prompts, provider prompts, file contents, command bodies, terminal output, transcripts, tokens, broad paths, exports, replay buffers, scan payloads, media drafts, diagnostics, logs, backups, account ids, zone ids, tunnel tokens, and quarantined historical content. ## Documentation Rule Public client tokens and service-discovery findings can inform posture requirements, but raw tokens, OAuth client IDs, and probe response files should not be committed into runtime config or repeated in user-facing docs. Phase 08 Session 07 keeps historical service-discovery and hosted-service evidence in posture-only form. The Session 07 action record retains conclusions about planned, disabled, unavailable, deploy-only, server-only, and public-client boundaries without copying raw tokens, OAuth values, probe output, Cloudflare account ids, zone ids, service-role values, tunnel tokens, provider payloads, command output, sensitive local paths, or historical quarantined content into stable docs. Reserved Cloudflare, Supabase, Umami, VAPID, Worker, provider, analytics, public replay, and tunnel variables remain insufficient to claim hosted identity, hosted storage, analytics capture, push delivery, remote access, production-hosted validation, release-grade deletion, or trusted erasure. ## Release Gate Any hosted feature must document: * What data is sent. * Why hosted storage or processing is needed. * How local-only mode behaves. * How operators disable it. * What tests protect privacy and authorization. * How users export or delete account-backed data where applicable. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/docs/hosted-services.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.