> 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/.spec_system/archive/phases/phase_07/prd_phase_07.md). # PRD Phase 07: Hosted Services and Analytics Guardrails **Status**: Complete **Sessions**: 7 **Estimated Duration**: 7-14 days **Progress**: 7/7 sessions validated (100%); Session 07 validation and documentation closeout complete Session 01 through Session 06 validations are complete. Session 07 ran the focused Phase 07 command set (20 test files / 183 tests passed), the full repo gate stack (format, lint, typecheck, full suite 2186 passed / 1 skipped, build, secret scan over 886 tracked files), confirmed requirement closure for P07-R001 through P07-R025 (22 closed by validated sessions, 3 deferred to Phase 08), synchronized the stable docs and PRDs, and recorded the cumulative security posture and Phase 08 handoff. The implementation artifacts are: * `hosted_services_requirements_privacy_baseline.md` * `phase07_requirement_routing_matrix.md` * `hosted_payload_privacy_blocklist.md` * `hosted_identity_authorization_guardrails.md` * `hosted_persistence_public_replay_boundaries.md` * `analytics_consent_payload_controls.md` * `push_remote_access_operator_diagnostics_guardrails.md` *** ## Overview Phase 07 turns the deferred hosted-service and analytics surfaces into source-backed guardrails before FactionOS can make any account-backed, analytics-backed, hosted-storage, push, remote-access, or public-sharing claim. This phase owns requirements reconciliation, hosted configuration and token exposure boundaries, hosted identity and authorization guardrails, hosted persistence and public replay boundaries, analytics consent and payload controls, push and remote-access guardrails, operator diagnostics, and validation closeout. Phase 07 must preserve the local-first posture from Phases 01-06. Core local workflows must keep working without hosted auth, hosted storage, analytics, Cloudflare credentials, public replay hosting, push infrastructure, remote tunnels, or provider credentials. Any hosted surface must have explicit disablement, consent, minimization, redaction, authorization, abuse-control, fallback, test, and documentation evidence before it is described as active. Trusted unified erasure, production-hosted validation, release hardening, mobile certification, WCAG certification, legacy decommission, and release candidate gating remain Phase 08 work unless a later PRD changes ownership. The Session 01 baseline artifacts define variable categories, public versus secret versus deploy-only boundaries, disabled defaults, local-first fallback, blocked hosted-payload categories, Session 04-07 ownership, and Phase 08 deferrals. They are documentation and planning artifacts only. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ------------------------------------------------------- | ---------------------- | ---------- | ---------- | | 01 | Hosted Services Requirements and Privacy Baseline | Complete and validated | \~14-20 | 2026-05-30 | | 02 | Hosted Configuration and Client Exposure Boundaries | Complete and validated | \~16-24 | 2026-05-30 | | 03 | Hosted Identity and Authorization Guardrails | Complete and validated | \~16-24 | 2026-05-30 | | 04 | Hosted Persistence and Public Replay Boundaries | Complete and validated | \~16-24 | 2026-05-30 | | 05 | Analytics Consent and Payload Controls | Complete and validated | 25 | 2026-05-30 | | 06 | Push Remote Access and Operator Diagnostics Guardrails | Complete and validated | 25 | 2026-05-30 | | 07 | Hosted Guardrails Validation and Documentation Closeout | Complete and validated | 20 | 2026-05-30 | *** ## Completed Sessions * Session 01: Hosted Services Requirements and Privacy Baseline * Session 02: Hosted Configuration and Client Exposure Boundaries * Session 03: Hosted Identity and Authorization Guardrails * Session 04: Hosted Persistence and Public Replay Boundaries * Session 05: Analytics Consent and Payload Controls * Session 06: Push Remote Access and Operator Diagnostics Guardrails * Session 07: Hosted Guardrails Validation and Documentation Closeout *** ## Implemented Sessions Awaiting Validation (none) ## Upcoming Sessions (none - Phase 07 complete; Phase 08 is next) ## Session 02 Outputs | Artifact | Purpose | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `packages/protocol/src/hostedConfig.ts` | Shared hosted config categories, exposure vocabulary, docs paths, variable metadata, and helper functions | | `packages/protocol/tests/hostedConfig.test.ts` | Protocol contract coverage for hosted config metadata, summaries, and blocked exposure | | `apps/server/src/lib/hostedConfig.ts` | Redacted hosted config posture builder for safe diagnostics | | `apps/server/tests/hostedConfig.test.ts` | Server posture coverage for absent, blank, public-client, server-only, deploy-only, reserved, and unsafe values | | `apps/server/tests/hostedConfigDiagnostics.test.ts` | Diagnostics route coverage for auth inheritance, redaction, and bounded JSON shape | | `apps/web/src/lib/hostedConfig.ts` | Browser helper for public `VITE_` config with local-only fallback | | `apps/web/tests/hostedConfig.test.ts` | Browser helper coverage for valid public config, blank fallback, malformed URLs, URL credentials, reserved placeholders, and unsafe mirrors | ## Session 03 Outputs | Artifact | Purpose | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `.spec_system/PRD/phase_07/hosted_identity_authorization_guardrails.md` | Source-backed hosted identity and authorization guardrail baseline | | `packages/protocol/src/hostedIdentity.ts` | Shared planned-state identity contracts, requirement vocabulary, and summary helpers | | `apps/server/src/lib/hostedIdentity.ts` | Local hosted identity diagnostics builder with redacted status-only posture | | `apps/server/src/routes/diagnostics.ts` | `GET /diagnostics/hosted-identity` route wired into the local auth and diagnostics stack | | `apps/web/src/lib/hostedIdentity.ts` | Browser helper copy for planned or unavailable hosted identity and War Room authority non-overclaim | | `docs/api/README_api.md`, `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/ARCHITECTURE.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, `packages/protocol/README_protocol.md`, `apps/server/README_server.md`, `apps/web/README_web.md`, `apps/warroom/README_warroom.md` | Stable docs and package README alignment for the hosted identity guardrail baseline | ## Session 04 Outputs | Artifact | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `.spec_system/PRD/phase_07/hosted_persistence_public_replay_boundaries.md` | Source-backed hosted persistence and public replay boundary baseline | | `packages/protocol/src/hostedPersistence.ts` | Shared hosted persistence and public replay posture contracts | | `packages/protocol/tests/hostedPersistence.test.ts` | Protocol contract coverage for eligibility, requirements, and bounded summaries | | `apps/server/src/lib/hostedPersistence.ts` | Local hosted persistence diagnostics builder | | `apps/server/tests/hostedPersistenceDiagnostics.test.ts` | Server diagnostics route coverage for planned and unavailable states | | `apps/server/src/routes/diagnostics.ts` | `GET /diagnostics/hosted-persistence` route wiring | | `apps/web/src/lib/hostedPersistence.ts` | Browser helper for hosted persistence unavailable state and local replay fallback | | `apps/web/tests/hostedPersistence.test.ts` | Browser helper coverage for disabled public replay hosting and local fallback | | `apps/web/tests/replayLink.test.ts` | Regression coverage for redacted fragment-based replay links | | `docs/api/README_api.md`, `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/ARCHITECTURE.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, `packages/protocol/README_protocol.md`, `apps/server/README_server.md`, `apps/web/README_web.md` | Stable docs and README alignment for the hosted persistence baseline | ## Session 05 Outputs | Artifact | Purpose | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `.spec_system/PRD/phase_07/analytics_consent_payload_controls.md` | Source-backed analytics provider, consent, opt-out, payload minimization, blocklist, local fallback, and Phase 08 handoff baseline | | `packages/protocol/src/hostedAnalytics.ts` | Shared hosted analytics provider, status, consent, event taxonomy, payload field, blocked label, unsupported claim, docs path, and summary contracts | | `packages/protocol/tests/hostedAnalytics.test.ts` | Protocol contract coverage for analytics vocabulary, consent gates, taxonomy, blocked labels, unsupported claims, and bounded summaries | | `packages/protocol/src/hostedConfig.ts`, `packages/protocol/tests/hostedConfig.test.ts` | Reserved analytics variable metadata and blocked browser mirror coverage | | `apps/web/src/lib/hostedAnalytics.ts` | Browser helper for disabled analytics readiness, consent and opt-out evaluation, local-only fallback, settings copy, and payload scrubbing | | `apps/web/tests/hostedAnalytics.test.ts` | Browser helper coverage for config plus consent gating, malformed URLs, opt-out, payload scrubbing, blocked nested keys, and no network side effects | | `apps/web/src/components/SettingsDrawer.tsx`, `apps/web/tests/SettingsHostedAnalytics.test.tsx` | Passive settings status copy and coverage for disabled, unavailable, consent-required, and revalidated analytics states | | `.env.local.example`, `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/environments.md`, `docs/release.md`, `packages/protocol/README_protocol.md`, `apps/web/README_web.md` | Stable docs and README alignment for the hosted analytics guardrail baseline | ## Session 06 Outputs | Artifact | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `.spec_system/PRD/phase_07/push_remote_access_operator_diagnostics_guardrails.md` | Source-backed push, VAPID, remote access, tunnel, operator diagnostic, redaction, local fallback, and Phase 08 handoff baseline | | `packages/protocol/src/hostedOperations.ts` | Shared hosted operation status, surface, requirement, blocked payload, unsupported claim, docs path, and bounded summary contracts | | `packages/protocol/tests/hostedOperations.test.ts` | Protocol contract coverage for push/remote/tunnel/diagnostics vocabulary, blocked labels, unsupported claims, and bounded summaries | | `packages/protocol/src/hostedConfig.ts`, `packages/protocol/tests/hostedConfig.test.ts` | Refined reserved VAPID and Cloudflare/tunnel metadata with browser-blocked mirror coverage | | `apps/server/src/lib/hostedOperations.ts` | Local hosted operation diagnostics builder with planned/unavailable posture and no raw value exposure | | `apps/server/tests/hostedOperationsDiagnostics.test.ts` | Server diagnostics route coverage for auth, CORS, planned/unavailable state, unsupported methods, and synthetic leak prevention | | `apps/server/src/routes/diagnostics.ts`, `apps/server/src/server.ts` | `GET /diagnostics/hosted-operations` route wiring and optional status passthrough | | `apps/cli/src/lib/orchestrationDiagnostics.js`, `apps/cli/src/commands/status.js`, `apps/cli/src/commands/doctor.js` | Loopback-only hosted operation diagnostics fetch, compaction, redaction, and compact status/doctor posture output | | `apps/cli/tests/orchestrationDiagnostics.test.js`, `apps/cli/tests/cliRuntime.test.js` | CLI coverage for compaction, non-loopback rejection, malformed/auth/timeout handling, and synthetic value redaction | | `apps/web/src/lib/hostedOperations.ts`, `apps/web/tests/hostedOperations.test.ts` | Browser hosted operation posture helper and coverage for local notification posture and unavailable push/remote/tunnel states | | `apps/web/src/lib/notifications.ts`, `apps/web/public/sw.js`, `apps/web/tests/notifications.test.ts` | Local notification copy, bounded service worker push payload and click-target sanitization, and regression coverage | | `.env.local.example`, `docs/api/README_api.md`, `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/ARCHITECTURE.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, `packages/protocol/README_protocol.md`, `apps/server/README_server.md`, `apps/cli/README_cli.md`, `apps/web/README_web.md` | Stable docs and README alignment for the push, remote access, tunnel, and operator diagnostics guardrail baseline | *** ## Objectives 1. Reconcile hosted auth, hosted storage, analytics, push, remote access, public replay, and operator diagnostic requirements into a Phase 07 routing baseline. 2. Define server, web, Worker, CLI, environment, and documentation boundaries for public client config, secret config, disabled defaults, and local-only fallback. 3. Specify hosted identity, consent, authorization, revocation, role, audit, and abuse-control guardrails without treating room-local Worker authority as hosted account proof. 4. Define hosted persistence and public replay guardrails for data minimization, row-level authorization, export, deletion, retention, and sensitive payload rejection before storage becomes active. 5. Define and validate analytics consent, event taxonomy, payload scrubbing, disabled-default behavior, self-hosting posture, and replaceability requirements. 6. Define push notification, remote access, tunnel, and operator diagnostic guardrails without making hosted services required for local development. 7. Validate Phase 07 guardrails, update stable docs and security posture, and hand off trusted erasure, production-hosted validation, release hardening, and decommission gates to Phase 08. ## Session 01 Outputs | Artifact | Purpose | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `hosted_services_requirements_privacy_baseline.md` | Source-backed hosted services, privacy, variable inventory, local-first fallback, surface baseline, and Phase 08 deferral record. | | `phase07_requirement_routing_matrix.md` | Requirement ownership for Sessions 02-07 and Phase 08, plus cross-session rules. | | `hosted_payload_privacy_blocklist.md` | Sensitive payload blocklist and local-first fallback checklist for hosted storage, analytics, public replay, push, diagnostics, remote access, Worker, adapters, exports, archives, logs, and backups. | Session 01 does not implement hosted auth, hosted config parsing, hosted storage, public replay hosting, analytics capture, push delivery, remote access, tunnels, hosted diagnostics, production-hosted validation, trusted erasure, certification, release hardening, or decommission work. *** ## Prerequisites * Phase 06 completed. * Phase 06 closeout artifacts and security posture are available. * `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, package README files, and current tests are reviewed before scoped changes. * Supabase, Umami, VAPID, Cloudflare, tunnel, provider, and adapter credentials remain optional for core local workflows. * Phase 08 retains ownership of trusted unified erasure, production-hosted validation, release hardening, mobile certification, WCAG certification, and legacy decommission. *** ## Technical Considerations ### Architecture Phase 07 should keep hosted services additive and reversible. The current core runtime has no production database requirement, and the web cockpit must not require hosted accounts, hosted storage, analytics, public replay hosting, push, or remote tunnels to start, hydrate, render, export local data, or run local War Room fallback states. Shared data-shape, route-family, unsupported-status, redaction, and diagnostic contracts should start in `packages/protocol` when more than one package consumes them. Server-mediated hosted access is preferred by default for secret-bearing or authorization-sensitive operations. Browser-exposed configuration must be limited to publishable, documented, revocable values. The optional Cloudflare Worker remains a room relay, not hosted account proof or trusted erasure. Supabase and Umami remain planned surfaces until Phase 07 adds source, tests, docs, and disabled-default controls. Push notification and remote-access variables remain reserved unless a scoped session wires consent, authorization, revocation, redaction, fallback, and abuse controls. ### Technologies * TypeScript contracts in `packages/protocol` * Express, route-family handling, config parsing, diagnostics, and redaction in `apps/server` * React 18, Vite, TypeScript, Tailwind, Zustand, browser storage, notification, and fetch APIs in `apps/web` * Cloudflare Worker, Durable Objects, WebSocket, Wrangler, and Worker tests in `apps/warroom` * Node CLI diagnostics and environment handling in `apps/cli` * Supabase configuration and PKCE/JWKS/RLS design notes where scoped * Umami analytics configuration and event taxonomy where scoped * Vitest, Testing Library, Playwright, Biome, npm workspace scripts, secret scan, ASCII/LF checks, and documentation gates ### Risks * Hosted identity overclaim: room-local Worker authority is not account identity, SSO, organization membership, consent, revocation, or production audit proof. * Secret exposure: public client config, deploy credentials, service-role keys, API tokens, OAuth ids, tunnel tokens, and provider secrets need explicit browser/server boundaries. * Sensitive payload leakage: analytics, hosted storage, public replay, push, diagnostics, and remote access must not receive prompts, file contents, command bodies, terminal output, transcripts, tokens, broad paths, exports, replay buffers, scan payloads, media drafts, logs, backups, or quarantined historical content. * Local-first regression: hosted surfaces could accidentally become startup, hydration, test, or deploy requirements for core local workflows. * Analytics consent drift: event capture could become enabled by default or collect more than the documented taxonomy allows. * Erasure confusion: Phase 07 guardrails cannot claim trusted deletion for existing local, Worker, browser, backup, log, archive, export, replay, hosted, or future account data. ### Relevant Considerations * \[P06] **Unified erasure still missing**: Phase 07 must not claim trusted deletion for Worker storage, browser hints, archives, memory, settings, replay, exports, diagnostics, logs, backups, hosted storage, or future account data. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Worker rooms are optional transfer, not hosted identity or broad hosted collaboration proof. * \[P00] **Hosted services are optional**: Supabase, Umami analytics, hosted storage, public replay hosting, and hosted validation remain optional or planned; core local workflows must work without hosted accounts or public client tokens. * \[P05] **Redaction is boundary-specific**: analytics, hosted storage, public replay, push, diagnostics, Worker, export, archive, adapter, backup, and log payloads need explicit minimization at each boundary. * \[P03] **Local-first boundary is architectural**: server, web, hooks, CLI, adapters, LLM, analytics, backups, logs, and Worker integrations must degrade cleanly when remote services are absent. * \[P06] **Phase complete is not release complete**: Phase 07 guardrails do not replace production-hosted validation, trusted erasure, mobile certification, WCAG certification, or release decommission gates. ### Security Carryforward * `P06-S07-HOSTED-IDENTITY`: Phase 07 must define hosted account lifecycle, consent, authorization, revocation, audit, and end-to-end validation before any hosted identity claim. * `P06-S07-HOSTED-VALIDATION`: Phase 07 may prepare hosted validation guardrails, but Phase 08 owns production-hosted release validation unless ownership is changed. * `P06-S07-ERASURE`: Phase 08 owns the trusted unified erasure workflow; Phase 07 must keep deletion wording narrow and honest. *** ## Success Criteria Phase complete when: * [x] All 7 sessions completed. * [x] Hosted-service, identity, storage, analytics, push, remote-access, and public replay requirements are routed to source-backed sessions or explicitly deferred. * [x] Public browser config, server-only secrets, deploy credentials, and optional service variables have documented boundaries and tests or validation notes. * [x] Hosted identity and authorization guardrails distinguish account proof from room-local authority and preserve local-only fallback. * [x] Hosted persistence and public replay guardrails define minimization, authorization, retention, export, deletion, and sensitive-payload rejection requirements. * [x] Analytics remains disabled by default unless explicit consent, scrubbed event taxonomy, payload tests, and opt-out controls are in place. * [x] Push, remote-access, tunnel, and operator diagnostic surfaces remain optional, bounded, and documented. * [x] Security, privacy, API, architecture, environments, deployment, release, package README, and phase PRD docs describe shipped Phase 07 guardrails and remaining Phase 08 risks. *** ## Dependencies ### Depends On * Phase 06: Collaboration, Isolation, and Mobile ### Enables * Phase 08: Release Hardening and Legacy Decommission --- # 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/.spec_system/archive/phases/phase_07/prd_phase_07.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.