> 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/sessions/phase07-session01-hosted-services-requirements-and-privacy-baseline/spec.md). # Session Specification **Session ID**: `phase07-session01-hosted-services-requirements-and-privacy-baseline` **Phase**: 07 - Hosted Services and Analytics Guardrails **Status**: Not Started **Created**: 2026-05-30 **Package**: Cross-cutting **Package Stack**: Markdown PRD/docs, environment examples, and source review across apps/server, apps/web, apps/warroom, apps/cli, apps/hooks, apps/adapters, and packages/protocol *** ## 1. Session Overview This session creates the source-backed Phase 07 hosted-services and privacy baseline before implementation begins. Phase 06 closed collaboration, isolation, mobile, and accessibility work while keeping hosted identity, trusted erasure, production-hosted validation, hosted storage, analytics, public replay hosting, push, remote access, and release hardening as later work. Phase 07 now needs a routing and privacy baseline so later implementation sessions can add guardrails without turning hosted services into required local dependencies. The work is documentation-first and cross-cutting. It audits Phase 06 closeout artifacts, PRD sources, UX requirements, hosted-service docs, privacy/security docs, environment docs, deployment and release docs, API docs, package README files, current environment examples, and existing tests or source boundaries. It then records hosted-service ownership, planned variable categories, local-first fallback expectations, blocked payload categories, and residual Phase 08 risks. The session must preserve FactionOS' local-first posture. Core local workflows must continue to work without Supabase, Umami, VAPID, Cloudflare credentials, public replay hosting, push infrastructure, remote tunnels, provider credentials, hosted accounts, or hosted storage. Session 01 does not implement hosted auth, hosted persistence, analytics, push, remote access, tunnels, public replay hosting, production-hosted validation, or trusted erasure. *** ## 2. Objectives 1. Create a source-backed hosted services requirements and privacy baseline for Phase 07 from PRD, UX PRD, Phase 06 closeout, security posture, stable docs, README files, environment examples, tests, and source evidence. 2. Inventory Supabase, Umami, VAPID, Cloudflare, tunnel, public replay, push, remote-access, diagnostic, and operator variables into public-client, server-only, deploy-only, active, reserved, and blocked categories. 3. Create a requirement-to-session routing matrix that assigns hosted identity, hosted config, hosted storage, analytics, push, remote access, diagnostics, documentation, and validation requirements to Sessions 02 through 07 or explicit Phase 08 deferrals. 4. Define sensitive hosted-payload blocklists and local-first fallback checks that later sessions must use before any hosted transfer, analytics capture, storage write, push payload, diagnostic report, remote access, or public replay path is described as active. *** ## 3. Prerequisites ### Required Sessions * [x] `phase06-session07-collaboration-isolation-and-mobile-validation-closeout` - provides Phase 06 local browser evidence, docs closeout, security posture, and hosted identity, trusted erasure, and hosted validation carryforward. * [x] `phase06-session03-shared-collaboration-event-contracts` - provides current allowlisted collaboration frame and blocked-field expectations. * [x] `phase05-session07-war-room-validation-and-documentation-closeout` - provides optional Worker deployment, health, rate-limit, and non-hosted identity boundaries. * [x] `phase04-session08-media-validation-and-documentation-closeout` - provides media transfer, provider draft, and release blocker lessons for future hosted and analytics surfaces. ### Required Tools/Knowledge * Node 20+, npm workspaces, Biome, Vitest, Playwright, TypeScript, React 18, Vite, Express, Cloudflare Workers, Durable Objects, Wrangler, Supabase auth/storage concepts, Umami analytics concepts, Web Push/VAPID concepts, and local-first privacy review. * Current source and docs: `.spec_system/PRD/PRD.md`, `.spec_system/PRD/PRD_UX.md`, `.spec_system/PRD/phase_07/PRD_phase_07.md`, `.spec_system/SECURITY-COMPLIANCE.md`, `.spec_system/CONSIDERATIONS.md`, `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, `docs/ARCHITECTURE.md`, `docs/api/README_api.md`, package README files, `.env.local.example`, package `.env.example` files, and relevant tests. * Current package boundaries: `packages/protocol` owns shared contracts, `apps/server` owns loopback runtime, validation, diagnostics, exports, archives, and server-mediated hosted-sensitive routes when introduced, `apps/web` owns browser config, consent UX, replay, notifications, analytics helpers, and localStorage, `apps/warroom` owns the optional Worker room relay, `apps/cli` and `apps/hooks` own local diagnostics, and `apps/adapters` owns outbound-only external payloads. ### Environment Requirements * Local checkout of the FactionOS monorepo with Phase 07 session stubs available. * No hosted account, Supabase project, Umami site, VAPID keypair, Cloudflare credential, tunnel token, provider key, push backend, remote access endpoint, production app host, or public replay host is required. * Stable docs and README files are treated as the current contract; archived PRDs, `docs/PROGRESS.md`, ignored `EXAMPLES/`, probe output, and local `.env.local` secrets remain evidence only and must not be copied into tracked docs. *** ## 4. Scope ### In Scope (MVP) * Maintainers can identify each Phase 07 hosted-service requirement owner - create a routing matrix for configuration, identity, storage, public replay, analytics, push, remote access, diagnostics, docs, and validation. * Operators can distinguish public, secret, deploy-only, active, reserved, and blocked variables - inventory Supabase, Umami, VAPID, Cloudflare, tunnel, Worker, provider, adapter, auth, analytics, and local runtime variables from docs and examples. * Security reviewers can identify blocked hosted payload categories - define sensitive data categories that must not enter hosted storage, analytics, public replay, push, diagnostics, remote access, Worker payloads, external adapters, logs, archives, or backups by default. * Implementers can preserve local-first fallback - define disablement, consent, minimization, redaction, authorization, error, unsupported-state, and documentation checks for later hosted surfaces. * Product and docs readers can distinguish Phase 07 guardrails from Phase 08 release work - keep trusted erasure, production-hosted validation, certification, release hardening, and legacy decommission explicitly deferred. * Stable docs can use current vocabulary - update hosted-service, privacy, environment, deployment, release, architecture, API, PRD, UX PRD, phase PRD, and package README wording where current hosted-service, analytics, or local-first language is stale or vague. ### Out of Scope (Deferred) * Implementing hosted configuration parsing or source behavior - *Reason: Session 02 owns source-backed config validation, diagnostics, tests, and docs.* * Shipping hosted auth, OAuth, Supabase clients, PKCE, JWKS, RLS, account UI, SSO, organization management, or hosted audit logs - *Reason: Session 03 owns identity guardrail scaffolding and Phase 08 owns release-grade hosted validation unless scope changes.* * Creating hosted database tables, storage buckets, migrations, public replay hosting, retention workers, or account-backed persistence - *Reason: Session 04 owns persistence and public replay boundaries, not production storage.* * Enabling analytics capture, event beacons, hosted dashboards, or user tracking - *Reason: Session 05 owns disabled-default analytics, consent, taxonomy, and payload controls.* * Shipping push delivery, remote tunnel workflows, remote execution, operator diagnostic agents, or access gateways - *Reason: Session 06 owns push, remote-access, and diagnostic guardrails only.* * Claiming trusted unified erasure, production-hosted validation, mobile certification, WCAG certification, release readiness, or legacy decommission completion - *Reason: Phase 08 owns those release gates.* *** ## 5. Technical Approach ### Architecture This session uses documentation-as-contract. The created Phase 07 baseline artifacts become the source handoff for Sessions 02 through 07, while stable docs and README updates keep shipped behavior honest for operators and maintainers. Hosted services must stay additive and reversible. Browser-exposed configuration is limited to publishable, documented, revocable values. Secret-bearing and authorization-sensitive operations should be server-mediated by default when later sessions introduce source changes. The optional Cloudflare Worker remains a room relay, not hosted account proof, hosted storage, public replay hosting, analytics, or trusted erasure. Shared data shapes, route-family vocabulary, unsupported-state envelopes, redaction categories, diagnostics posture, and payload safety checks should start in `packages/protocol` when more than one package consumes them. Stable docs must continue to distinguish current local runtime behavior from planned hosted surfaces and from Phase 08 release gates. ### Design Patterns * Requirements-first routing: every Phase 07 requirement should name the smallest owning session or a later-phase deferral. * Local-first optional services: core server, web, hooks, CLI, adapters, Worker tests, and public demo workflows must degrade cleanly when hosted services and credentials are absent. * Public/secret/deploy/reserved config separation: browser-safe values must be clearly separated from service-role keys, API tokens, zone ids, account ids, tunnel tokens, provider secrets, and deploy credentials. * Boundary-specific redaction: analytics-safe, storage-safe, public-replay-safe, push-safe, diagnostic-safe, Worker-safe, export-safe, adapter-safe, archive-safe, backup-safe, and log-safe are separate claims. * Honest capability wording: docs and future UI copy must distinguish shipped behavior, disabled or unavailable states, planned guardrails, and Phase 08 release work. ### Technology Stack * Markdown PRD, docs, README, routing matrix, privacy baseline, and hosted-payload blocklist artifacts. * Environment examples in `.env.local.example`, `apps/server/.env.example`, `apps/adapters/.env.example`, and Worker configuration notes in `apps/warroom/wrangler.toml`. * TypeScript shared contracts in `packages/protocol`. * Express, route-family handling, configuration validation, diagnostics, redaction, archive/export, and Vitest in `apps/server`. * React 18, Vite, TypeScript, Tailwind, Zustand, browser localStorage, Notification, fetch APIs, analytics helpers, replay helpers, and Playwright in `apps/web`. * Cloudflare Worker, Durable Objects, WebSocket, Wrangler, and Worker tests in `apps/warroom`. * Node CLI and dependency-light hook diagnostics in `apps/cli` and `apps/hooks`. * Validation tools: `rg`, `npm run format:check` where needed, `git diff --check`, ASCII/LF scans, docs link/path review, and focused package tests only if implementation changes code. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_07/hosted_services_requirements_privacy_baseline.md` | Source-backed hosted services, privacy, local-first, variable, and deferral baseline | \~190 | | `.spec_system/PRD/phase_07/phase07_requirement_routing_matrix.md` | Requirement-to-session routing matrix for Sessions 02-07 and Phase 08 deferrals | \~150 | | `.spec_system/PRD/phase_07/hosted_payload_privacy_blocklist.md` | Sensitive hosted-payload blocklist and local-first fallback checklist for storage, analytics, replay, push, diagnostics, remote access, Worker, adapters, logs, archives, exports, and backups | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/PRD.md` | Link Phase 07 baseline artifacts and clarify hosted services, analytics, local-first, erasure, and release deferrals | \~35 | | `.spec_system/PRD/PRD_UX.md` | Clarify UX boundaries for hosted identity, analytics consent, public replay, push, remote access, diagnostics, local-only fallback, and unavailable states | \~30 | | `.spec_system/PRD/phase_07/PRD_phase_07.md` | Link Session 01 outputs and align Sessions 02-07 with routing matrix ownership | \~35 | | `docs/hosted-services.md` | Add Phase 07 routing, variable category, blocked payload, local-first, and Phase 08 deferral baseline | \~40 | | `docs/privacy-and-security.md` | Record hosted-service transfer boundaries, sensitive blocklist, consent/minimization requirements, and trusted erasure deferral | \~35 | | `docs/environments.md` | Clarify active, public-client, server-only, deploy-only, reserved, blocked, and local-only fallback variables | \~35 | | `docs/deployment.md` | Clarify hosted-service deployment boundaries, Cloudflare/Worker separation, public demo, production-hosted validation, and deploy-only secret handling | \~25 | | `docs/release.md` | Preserve Phase 08 release gates and add Phase 07 guardrail validation expectations | \~25 | | `docs/ARCHITECTURE.md` | Clarify hosted-service additivity, server-mediated secret operations, protocol-led contracts, and local-first fallback | \~25 | | `docs/api/README_api.md` | Clarify current local API versus planned hosted route families, unsupported states, and payload redaction boundaries | \~25 | | `.env.local.example` | Align comments for reserved Supabase, Umami, VAPID, Cloudflare, tunnel, provider, and browser-safe values if stale | \~30 | | `apps/server/.env.example` | Add or clarify server-only hosted variable posture if needed | \~15 | | `apps/adapters/.env.example` | Clarify outbound payload sensitivity and hosted analytics/adapter separation if needed | \~10 | | `apps/warroom/wrangler.toml` | Clarify Worker vars remain room-relay config, not hosted identity/storage/analytics config if needed | \~10 | | `apps/server/README_server.md` | Clarify server-mediated hosted boundaries, local-only fallback, diagnostics, and no hosted storage/auth claims | \~20 | | `apps/web/README_web.md` | Clarify public browser config, analytics consent, replay/public sharing, push, notifications, localStorage, and local-only fallback | \~25 | | `apps/warroom/README_warroom.md` | Clarify Worker relay boundaries, room-local authority limits, compact diagnostics, and no hosted account/storage/analytics claims | \~20 | | `apps/cli/README_cli.md` | Clarify hosted diagnostic posture, local recovery, and no trusted erasure or remote access claims | \~15 | | `apps/hooks/README_hooks.md` | Clarify hook diagnostics, local transfer boundaries, provider keys, and no hosted payload forwarding by default | \~15 | | `apps/adapters/README_adapters.md` | Clarify outbound-only adapter transfer, raw full webhook risk, analytics separation, and hosted payload blocklist relevance | \~15 | | `packages/protocol/README_protocol.md` | Clarify protocol ownership for hosted route-family vocabulary, redaction categories, unsupported states, diagnostics, analytics, and future storage/identity contracts | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Phase 07 hosted services requirements and privacy baseline exists and cites current PRD, UX PRD, Phase 06 closeout, security posture, docs, README, environment example, test, and source evidence. * [ ] Routing matrix assigns hosted config, identity, storage, public replay, analytics, push, remote access, diagnostics, documentation, and validation requirements to Sessions 02 through 07 or explicit Phase 08 deferrals. * [ ] Planned variables are inventoried by category: active local, public-client, server-only secret, deploy-only secret, reserved future, and blocked from browser or logs. * [ ] Sensitive hosted-payload blocklist covers prompts, provider prompts, file contents, command bodies, terminal output, transcripts, tokens, URLs, broad paths, exports, replay buffers, scan payloads, media drafts, diagnostics, logs, backups, account ids, zone ids, tunnel tokens, and quarantined historical content. * [ ] Local-first fallback checklist defines disablement, consent, minimization, redaction, authorization, error, unsupported-state, documentation, and validation evidence needed before hosted transfer is described as active. * [ ] Stable docs and package README files distinguish Phase 07 guardrails from hosted identity proof, production-hosted validation, trusted erasure, certification, release hardening, and decommission work. ### Testing Requirements * [ ] Documentation path and link references reviewed for changed files. * [ ] Consistency scan completed for hosted-service names, variable categories, blocked payload terms, local-first wording, public/secret/deploy boundaries, disabled-default language, and Phase 08 deferrals. * [ ] No app tests are required unless implementation changes code; if source or config behavior changes are needed, focused package tests are run. * [ ] ASCII/LF checks completed for all session outputs and touched docs. * [ ] `git diff --check` completed. ### Non-Functional Requirements * [ ] Core FactionOS operation remains local-first and does not require Supabase, Umami, hosted auth, hosted storage, public replay hosting, push, VAPID, Cloudflare credentials, tunnel tokens, provider credentials, remote access, or production app hosting. * [ ] Public browser config remains limited to documented publishable values and never includes service-role keys, API tokens, zone ids, account ids, tunnel tokens, provider secrets, raw OAuth secrets, or deploy credentials. * [ ] Analytics remains disabled by default until later sessions add explicit consent, taxonomy, payload tests, opt-out, and documentation evidence. * [ ] Trusted unified erasure, production-hosted validation, mobile certification, WCAG certification, release readiness, and legacy decommission remain Phase 08 work. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. *** ## 8. Implementation Notes ### Key Considerations * Session 01 is a requirements and documentation baseline, not a hosted-service implementation session. * The baseline should route every requirement to the smallest later session that can implement and validate it. * Existing `.env.local.example` reserves future hosted variables, but reserved examples are not proof that runtime consumes or validates those variables. * Browser-safe does not mean public-safe. Publishable config can still identify projects or sites and must be documented, revocable, and non-secret. * Room-local Worker authority remains optional room relay proof only. It must not be described as hosted account identity, SSO, organization membership, public collaboration safety, or production audit proof. * Redaction must be described per boundary. Local export redaction, Worker safe-frame redaction, analytics scrubbing, hosted storage minimization, push payload minimization, diagnostics compaction, adapter formatting, archive redaction, backup retention, and log redaction are separate controls. * Stable docs are the current contract; archived PRDs, `docs/PROGRESS.md`, ignored `EXAMPLES/`, local probe output, raw service-discovery output, and local `.env.local` secrets remain evidence only. ### Potential Challenges * Scope bleed into source changes: inventory and route requirements here, but leave config parsing, hosted identity scaffolding, storage guards, analytics controls, push, remote access, and diagnostic source changes to Sessions 02 through 06. * Variable ambiguity: categorize current variables by consumption and exposure, and explicitly mark reserved values as not consumed unless source evidence proves otherwise. * Hosted identity overclaim: keep Worker room authority and hosted account identity separate in baseline docs and README updates. * Erasure ambiguity: export, browser reset, room leave/reset, local recovery, retention notes, and delete wording must not become trusted unified erasure claims. * Analytics drift: do not let Umami reserved settings imply active tracking; analytics must remain disabled until consent, taxonomy, scrubbing, tests, and opt-out are implemented. * Secret exposure in examples: comments may mention placeholder categories, but tracked docs must not include real tokens, account ids, zone ids, OAuth client secrets, tunnel tokens, provider keys, or service-role values. ### 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, valid spool state, workspace files, or future hosted surfaces. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Worker rooms remain 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. * \[P03-packages/protocol] **Protocol leads cross-package work**: shared route-family, unsupported-state, diagnostic, hosted payload, and redaction contracts should start in `packages/protocol` when multiple packages consume them. * \[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. * \[P06-S07-HOSTED-IDENTITY] **Hosted identity remains open**: Phase 07 must define account lifecycle, consent, authorization, revocation, audit, and validation before any hosted identity claim. * \[P06-S07-HOSTED-VALIDATION] **Hosted validation remains open**: local, mocked, and deployed Worker evidence is not production-hosted app validation. * \[P06-S07-ERASURE] **Trusted erasure remains open**: Phase 08 owns unified erase/reset workflow and audit tests. *** ## 9. Testing Strategy ### Unit Tests * No application unit tests are expected because this session produces planning and documentation artifacts only. * If implementation reveals a narrow source, config, or diagnostic wording fix, run the focused package test for that package before completing the task. ### Integration Tests * Run `npm run format:check` and `npm run lint` only if formatted workspace code or config behavior is changed. * Run `git diff --check` for whitespace validation. ### Manual Testing * Review changed docs and README files for consistent hosted-service names, variable categories, local-first wording, disabled-default analytics wording, public/secret/deploy separation, and Phase 08 deferrals. * Verify links to baseline artifacts and existing docs resolve from the repository root. * Confirm docs do not imply hosted accounts, hosted storage, analytics, public replay hosting, push backend, remote tunnel, remote execution, production-hosted validation, certification, release readiness, or trusted erasure are shipped by this session. ### Edge Cases * Missing Supabase config, missing Umami config, missing VAPID keys, missing Cloudflare credentials, blank Worker URL, invalid Worker URL, Worker down, tunnel token absent, hosted account absent, analytics disabled, push unavailable, public replay unavailable, remote access unavailable, and local server offline. * Prompt, provider prompt, file content, command body, terminal output, transcript, secret, URL, broad path, export, replay, scan, media draft, diagnostic, log, backup, account id, zone id, tunnel token, and quarantined historical payloads must remain non-transferable by default. * Publishable keys, website ids, Worker URLs, custom domains, and public origins must be treated as browser-visible identifiers, not secrets, and still require documentation and revocation posture. * Local docs, examples, diagnostics, and validation notes must not preserve raw service-discovery output, real credentials, raw OAuth secrets, raw provider keys, raw webhook URLs, raw tunnel tokens, or local `.env.local` values. *** ## 10. Dependencies ### External Libraries * None expected for this documentation-first session. ### Other Sessions * **Depends on**: `phase06-session07-collaboration-isolation-and-mobile-validation-closeout`, `phase06-session03-shared-collaboration-event-contracts`, `phase05-session07-war-room-validation-and-documentation-closeout`, `phase04-session08-media-validation-and-documentation-closeout` * **Depended by**: `phase07-session02-hosted-configuration-and-client-exposure-boundaries`, `phase07-session03-hosted-identity-and-authorization-guardrails`, `phase07-session04-hosted-persistence-and-public-replay-boundaries`, `phase07-session05-analytics-consent-and-payload-controls`, `phase07-session06-push-remote-access-and-operator-diagnostics-guardrails`, `phase07-session07-hosted-guardrails-validation-and-documentation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/sessions/phase07-session01-hosted-services-requirements-and-privacy-baseline/spec.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.