> 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-session04-hosted-persistence-and-public-replay-boundaries/spec.md). # Session Specification **Session ID**: `phase07-session04-hosted-persistence-and-public-replay-boundaries` **Phase**: 07 - Hosted Services and Analytics Guardrails **Status**: Not Started **Created**: 2026-05-30 **Package**: Cross-cutting (`apps/server`, `apps/web`, `packages/protocol`; docs) **Package Stack**: TypeScript, Express, React 18, Vite, Vitest, npm workspaces, Markdown docs *** ## 1. Session Overview This session defines the hosted persistence and public replay boundaries that must exist before FactionOS can claim hosted storage, account-backed replay, or public replay hosting. It turns the Phase 07 baseline, payload blocklist, hosted config guardrails, and hosted identity guardrails into a source-backed storage and replay posture: persistence is planned or unavailable, public replay hosting is disabled by default, and current replay/export/archive paths stay local-first. The work is cross-package but intentionally does not ship a database, storage bucket, migration, upload flow, public replay host, or trusted erasure workflow. `packages/protocol` should own shared data eligibility categories, future storage requirements, public replay requirements, blocklist labels, docs paths, and summary helpers. `apps/server` should expose only compact planned-state diagnostics behind existing local auth. `apps/web` should expose helper state that distinguishes local URL-fragment replay sharing from hosted or public replay hosting. The session also updates stable docs so future analytics, push, diagnostics, release hardening, and Phase 08 erasure work can reference one clear hosted persistence baseline. It must preserve core local workflows without Supabase, hosted auth, hosted storage, public replay hosting, analytics, Cloudflare credentials, remote tunnels, provider credentials, or production-hosted validation. *** ## 2. Objectives 1. Define hosted persistence eligibility, blocked categories, local-only categories, redacted-only categories, user-export-only categories, and future server-mediated storage requirements. 2. Define public replay hosting requirements for consent, payload caps, redaction, expiration, takedown, no-index posture, abuse controls, and local-only fallback. 3. Add protocol, server, and web scaffolding that reports hosted persistence and public replay as planned, unavailable, or disabled without enabling storage, upload, database, bucket, or public host behavior. 4. Update API, architecture, privacy, hosted-service, environment, deployment, release, protocol, server, and web docs so local replay, export, archive, scan, media draft, backup, and War Room data are not described as hosted-safe or public-safe by default. *** ## 3. Prerequisites ### Required Sessions * [x] `phase07-session01-hosted-services-requirements-and-privacy-baseline` - provides hosted storage routing, payload blocklist, local-first fallback checks, and Phase 08 deferrals. * [x] `phase07-session02-hosted-configuration-and-client-exposure-boundaries` - provides hosted config categories, diagnostics patterns, browser/server exposure boundaries, and disabled-default tests. * [x] `phase07-session03-hosted-identity-and-authorization-guardrails` - provides account lifecycle, authorization surfaces, audit requirements, diagnostics patterns, and non-overclaim wording. * [x] `phase06-session07-collaboration-isolation-and-mobile-validation-closeout` - provides current security posture, local browser evidence, War Room residual risks, and trusted erasure deferral. * [x] `phase01-session05-websocket-hydration-and-archive-export-privacy` - provides current archive/export redaction posture. * [x] `phase02-session06-settings-replay-notifications-and-scan-ux` - provides current local replay sharing, local export, notification, and scan UX boundaries. ### Required Tools/Knowledge * Node 20+, npm workspaces, TypeScript 5.9, Vitest, Express routing, Vite browser helpers, Zustand replay state, and Biome formatting/linting. * Existing hosted config and identity patterns in `packages/protocol`, `apps/server/src/lib/hostedConfig.ts`, `apps/server/src/lib/hostedIdentity.ts`, `apps/web/src/lib/hostedConfig.ts`, and `apps/web/src/lib/hostedIdentity.ts`. * Current replay, export, archive, scan, backup, media draft, and War Room redaction behavior in `apps/web/src/lib/replayLink.ts`, `apps/server/src/lib/exportSession.ts`, `apps/server/src/lib/sessionPrivacy.ts`, and related tests. ### Environment Requirements * Local checkout of the FactionOS monorepo with dependencies available through existing npm workspace scripts. * No Supabase project, hosted database, storage bucket, public replay host, account provider, production app host, or real credential is required. * Do not read, copy, print, or commit raw values from `.env.local`, hosted consoles, replay buffers, exports, archives, logs, backups, or local filesystem paths. Use synthetic test records and documented examples only. *** ## 4. Scope ### In Scope (MVP) * Maintainers can reference a hosted persistence and public replay boundary spec - add eligibility, local-only, blocked, redacted-only, user-export-only, retention, export, deletion, audit, abuse-control, and Phase 08 erasure handoff requirements. * Protocol consumers can share one storage and replay posture contract - add planned, unavailable, disabled, eligibility, public replay requirement, blocked payload, docs path, and summary vocabulary in `packages/protocol`. * Operators can inspect local hosted persistence posture safely - add server diagnostics that expose compact status, docs paths, required controls, and unsupported/planned reason codes without raw env values, payloads, replay data, exports, paths, logs, or credentials. * Browser code can render honest disabled-state copy - add web helpers for hosted persistence unavailability, public replay hosting disablement, local URL-fragment fallback, replay caps, and no upload endpoint behavior. * Tests can prevent sensitive hosted-payload drift - assert blocked categories stay local, redacted, or user-export-only and that planned-state diagnostics never serialize synthetic secrets, prompts, paths, exports, replay events, logs, backups, or account identifiers. * Stable docs and package README files align with current source behavior and keep Phase 08 ownership of trusted unified erasure and release-grade deletion claims. ### Out of Scope (Deferred) * Creating production database schemas, Supabase projects, RLS policies, storage buckets, storage migrations, hosted replay uploads, or account-backed persistence - *Reason: this session defines guardrails and planned states only.* * Uploading prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, scan payloads, media drafts, logs, backups, War Room payloads, or quarantined historical content - *Reason: blocked by the Phase 07 hosted payload privacy blocklist.* * Shipping public replay hosting, public replay pages, replay URLs outside the current local fragment format, search indexing, public embeds, or takedown workflows - *Reason: future hosted replay work must first satisfy consent, minimization, redaction, expiration, no-index, abuse, and takedown requirements.* * Closing trusted unified erasure, production-hosted validation, release hardening, mobile certification, WCAG certification, or legacy decommission - *Reason: Phase 08 owns those release gates.* * Implementing analytics capture, push delivery, remote access, tunnels, hosted diagnostics upload, or real file/git/terminal/Docker/remote executors - *Reason: Sessions 05 and 06 or later phases own those surfaces.* *** ## 5. Technical Approach ### Architecture Use `packages/protocol` as the shared contract owner for hosted persistence and public replay posture. Add a focused `hostedPersistence` module that exports status values, data categories, storage eligibility decisions, public replay requirement values, unsupported claim labels, blocked payload labels, docs paths, diagnostic shapes, and pure helpers for building a compact guardrail summary. Keep these helpers deterministic and side-effect free so server and web packages can consume them without duplicating strings. In `apps/server`, add a local hosted persistence diagnostics builder and route. The route should be read-only, inherit the same local auth, CORS, rate-limit, and body-size boundary as other diagnostics, and return status-only JSON: planned or unavailable states, docs paths, required controls, and explicit non-overclaim labels. It must never return raw env values, storage keys, service-role keys, account ids, request bodies, local paths, replay buffers, exports, archives, logs, backups, prompts, commands, transcripts, file contents, scan payloads, media drafts, or War Room payloads. In `apps/web`, add pure helper functions that describe hosted persistence and public replay hosting as unavailable or disabled while distinguishing current local replay URL fragments from hosted replay storage. The helper can refer to existing replay caps and share-link behavior, but must not add upload endpoints, hosted clients, account state, public replay routes, storage clients, service workers, or persistent hosted identifiers. Documentation updates should make the storage lifecycle explicit: future hosted persistence needs server mediation, authorization/RLS tests, migrations or schema artifacts, retention, export, deletion, takedown, abuse controls, and audit evidence before activation. Deletion wording must remain narrow: local browser cleanup, export removal, or Worker leave/reset are not trusted unified erasure. ### Design Patterns * Protocol-first contracts: shared persistence, replay, eligibility, and unsupported-state vocabulary starts in `packages/protocol`. * Planned-state scaffolding: source can expose unsupported or planned states without creating half-wired hosted storage or public replay behavior. * Redacted diagnostics: diagnostics report status labels, docs paths, booleans, counts, and requirement names only. * Local-first fallback: absent hosted storage keeps server, web, hooks, CLI, adapters, Worker fallback, public demo, local replay, export, archive, backup, and diagnostics workflows usable. * Boundary-nearest authorization: future authorization-sensitive storage, replay, export, deletion, and takedown operations should be server-mediated by default and must not rely on UI copy alone. * Negative claim tests: tests should assert that local replay fragments, exports, archives, backups, Worker data, and browser reset controls are not public replay hosting, hosted-safe storage, release-grade deletion, or trusted erasure. ### Technology Stack * TypeScript contracts and Vitest tests in `packages/protocol`. * Express diagnostics routing and Vitest route tests in `apps/server`. * Vite/browser helper logic and Vitest tests in `apps/web`. * Markdown docs under `.spec_system/PRD/phase_07/`, `docs/`, and package README files. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_07/hosted_persistence_public_replay_boundaries.md` | Source-backed hosted persistence and public replay eligibility, blocked payload, consent, retention, export, deletion, takedown, abuse, and Phase 08 handoff baseline | \~260 | | `packages/protocol/src/hostedPersistence.ts` | Shared hosted persistence and public replay posture contracts, requirement vocabulary, docs paths, diagnostics shapes, and pure helpers | \~260 | | `packages/protocol/tests/hostedPersistence.test.ts` | Protocol tests for data eligibility, public replay requirements, blocked payload labels, bounded summary builders, and negative claims | \~180 | | `apps/server/src/lib/hostedPersistence.ts` | Local hosted persistence diagnostics builder with redacted planned-state output | \~130 | | `apps/server/tests/hostedPersistenceDiagnostics.test.ts` | Server route tests for auth inheritance, planned/unavailable status, local-only fallback, and no raw payload leakage | \~160 | | `apps/web/src/lib/hostedPersistence.ts` | Browser helper for hosted persistence unavailable state, public replay disabled state, and local replay fragment fallback | \~150 | | `apps/web/tests/hostedPersistence.test.ts` | Web helper tests for local URL-fragment replay, disabled public replay hosting, caps, and no account/storage UI implication | \~140 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/index.ts` | Export hosted persistence contracts from the package barrel | \~2 | | `apps/server/src/routes/diagnostics.ts` | Add `GET /diagnostics/hosted-persistence` using the local diagnostics pattern | \~20 | | `apps/web/tests/replayLink.test.ts` | Add regression assertions that current share links remain redacted local URL fragments and not public replay hosting | \~30 | | `docs/api/README_api.md` | Document hosted persistence diagnostics as local planned-state posture, not hosted storage or public replay runtime behavior | \~30 | | `docs/hosted-services.md` | Add Session 04 storage eligibility, public replay, local-only fallback, and Phase 08 erasure guardrails | \~45 | | `docs/privacy-and-security.md` | Add blocked hosted-storage/public-replay payload rules, export/deletion limits, retention, takedown, and no raw-value diagnostics guarantees | \~45 | | `docs/ARCHITECTURE.md` | Add protocol-first planned-state architecture for hosted persistence and public replay while preserving local server/browser/Worker separation | \~30 | | `docs/environments.md` | Clarify Supabase, public replay, and storage variables remain reserved and do not enable hosted persistence | \~25 | | `docs/deployment.md` | Clarify deployment and Worker health are not storage, public replay, retention, deletion, takedown, or erasure proof | \~25 | | `docs/release.md` | Add hosted persistence and public replay release guardrails, negative-claim checks, and Phase 08 deferrals | \~35 | | `packages/protocol/README_protocol.md` | Document protocol ownership of persistence/public replay guardrail contracts | \~30 | | `apps/server/README_server.md` | Document server hosted persistence diagnostics, unavailable state, auth inheritance, and redaction boundaries | \~30 | | `apps/web/README_web.md` | Document browser hosted persistence helper, local replay fragment fallback, and no hosted/public replay UI | \~35 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Hosted persistence requirements classify data as future eligible, server-mediated required, local-only, redacted-only, user-export-only, blocked, or Phase 08 erasure-dependent. * [ ] Public replay hosting requirements cover consent, payload caps, replay redaction, expiration, takedown, no-index posture, abuse controls, local-only fallback, and disabled-default behavior. * [ ] Protocol hosted persistence contracts expose planned/unavailable states, data eligibility decisions, public replay requirements, blocked payload labels, docs paths, unsupported claims, and bounded summary helpers. * [ ] Server hosted persistence diagnostics return status-only planned posture and inherit local bearer auth when `FACTIONOS_AUTH_TOKEN` is configured. * [ ] Server diagnostics never include raw env values, tokens, account ids, request bodies, local paths, prompts, command output, replay buffers, exports, archives, logs, backups, scan payloads, media drafts, or War Room payloads. * [ ] Browser helpers keep hosted persistence and public replay hosting unavailable or disabled without adding storage clients, upload endpoints, public routes, account UI, or persisted hosted state. * [ ] Existing local replay share links remain URL-fragment based, redacted, bounded, and non-uploading. * [ ] No source, UI, docs, diagnostics, or tests imply hosted storage, public replay hosting, release-grade deletion, or trusted erasure is shipped. ### Testing Requirements * [ ] Protocol hosted persistence tests written and passing. * [ ] Server hosted persistence diagnostics route tests written and passing. * [ ] Web hosted persistence helper tests written and passing. * [ ] Existing replay-link regression tests updated or reviewed for local-only URL-fragment behavior. * [ ] Focused package typechecks run for changed TypeScript packages where feasible. * [ ] Manual docs review completed for hosted persistence, public replay, export, deletion, takedown, and Phase 08 erasure wording. ### Non-Functional Requirements * [ ] Core local workflows remain usable without hosted accounts, Supabase, storage buckets, RLS policies, migrations, Cloudflare credentials, public replay hosting, analytics, push, remote access, tunnels, or production hosts. * [ ] Public/browser surfaces never store or display raw account tokens, storage tokens, service-role keys, exports, replay buffers, logs, backups, paths, prompts, commands, transcripts, file contents, scan payloads, media drafts, or raw Worker authority tokens. * [ ] Future hosted persistence authorization-sensitive operations are documented as server-mediated by default unless a later session proves another boundary is safer. * [ ] Phase 08 trusted erasure, production-hosted validation, release hardening, certification, and legacy decommission remain explicitly deferred. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Do not add a database client, Supabase client, storage bucket, migration, public replay upload endpoint, public replay route, service worker upload path, account state, or hosted session cookie. * Do not read or copy `.env.local`; tests should use synthetic token-like, path-like, prompt-like, export-like, and replay-like strings and assert they are absent from serialized diagnostics. * Keep local replay language narrow: URL-fragment sharing with bounded, redacted event payloads and no upload. * Keep local exports, archives, logs, backups, scans, memory findings, media drafts, and War Room room data classified as sensitive local data unless a later session adds explicit consent, authorization, redaction, retention, deletion, and audit tests. * Account deletion, storage deletion, replay expiration, and takedown can be specified as future lifecycle requirements, but trusted unified erasure remains Phase 08. ### Potential Challenges * Hosted storage overclaim: mitigate with planned/unavailable states, unsupported-claim vocabulary, docs checks, and tests that prove no storage client, schema, bucket, upload route, or hosted write path is active. * Public replay confusion: mitigate by naming current share links as local URL-fragment replay only and testing that helper copy never calls them hosted or public replay. * Diagnostic leakage: mitigate by returning requirement names, status labels, docs paths, booleans, and counts only, with tests against synthetic sensitive values. * Deletion wording drift: mitigate by separating narrow future deletion and takedown requirements from Phase 08 trusted unified erasure. * Future authorization ambiguity: mitigate by documenting server mediation, authorization/RLS tests, audit events, retention, export, deletion, and abuse controls before any hosted storage or replay hosting can become active. ### Relevant Considerations * \[P06] **Unified erasure still missing**: do not claim trusted deletion for Worker storage, browser hints, archives, memory, settings, replay, exports, diagnostics, logs, backups, hosted storage, or future account data. * \[P00] **Hosted services are optional**: Supabase, 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-packages/protocol] **Protocol leads cross-package work**: shared storage, replay, unsupported-state, and diagnostic vocabulary should start in `packages/protocol`. * \[P03] **Local-first boundary is architectural**: server, web, hooks, CLI, adapters, LLM, analytics, backups, logs, and Worker integrations should degrade cleanly when remote services are absent. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Worker rooms are optional transfer, not hosted storage, public replay hosting, release-grade deletion, or trusted erasure proof. * \[P03] **Local backups are sensitive state**: backup tarballs preserve local FactionOS state and must not be uploaded or hosted without encryption, retention, consent, and erasure design. * \[P06] **Phase complete is not release complete**: this session does not close production-hosted validation, trusted erasure, mobile certification, WCAG certification, or release decommission gates. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Planned hosted persistence or public replay states could be mistaken for shipped storage or public hosting if disabled/unavailable language is vague. * Diagnostics or tests could accidentally serialize synthetic or real sensitive values from prompts, commands, paths, exports, replay buffers, logs, backups, account ids, service-role keys, or Worker payloads. * Existing local share/export/archive behaviors could be described as hosted-safe, public-safe, release-grade deletion, or trusted erasure even though they remain local-first artifacts. *** ## 9. Testing Strategy ### Unit Tests * Test protocol status, storage eligibility, public replay requirement, blocked payload, unsupported claim, and docs path vocabulary for uniqueness and expected values. * Test protocol summary builders return bounded status-only output and never require hosted services for local workflows. * Test web helpers return unavailable hosted persistence state, disabled public replay hosting state, local URL-fragment replay copy, replay caps, and no upload/account/storage UI implications. ### Integration Tests * Test `GET /diagnostics/hosted-persistence` returns planned/unavailable posture, docs paths, requirement names, local-only status, and no raw payload fields. * Test the diagnostics route inherits local bearer auth when configured. * Test synthetic storage keys, service-role keys, account ids, replay payloads, prompts, command bodies, local paths, export snippets, log snippets, backup names, and Worker payload strings do not appear in serialized diagnostics. ### Manual Testing * Review `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/ARCHITECTURE.md`, `docs/api/README_api.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, and package README files for consistent shipped/planned/disabled/deferred wording. * Confirm no doc describes local replay fragments, exports, archives, backups, scans, media drafts, logs, or Worker data as hosted-safe, public-safe, release-grade deletion, or trusted erasure evidence. ### Edge Cases * Supabase, storage, or public replay config values present in env examples must not enable hosted persistence, database clients, public replay hosting, or diagnostics beyond planned/unavailable posture. * Browser refresh, malformed replay hash, oversized replay events, empty replay buffers, clipboard failure, settings reset, Worker leave/reset, and local export should remain local-only behaviors. * Future retention, deletion, expiration, and takedown wording must be requirements only and must not close Phase 08 trusted unified erasure. * Docs and tests must avoid raw OAuth values, service-role values, account ids, authority tokens, request bodies, local paths, replay buffers, exports, logs, backups, media drafts, and probe dumps. *** ## 10. Dependencies ### External Libraries * No new external runtime libraries are planned. * Existing Express, TypeScript, Vite, React 18, Zustand, and Vitest dependencies are sufficient. ### Other Sessions * **Depends on**: `phase07-session01-hosted-services-requirements-and-privacy-baseline`, `phase07-session02-hosted-configuration-and-client-exposure-boundaries`, `phase07-session03-hosted-identity-and-authorization-guardrails` * **Enables**: `phase07-session05-analytics-consent-and-payload-controls`, `phase07-session06-push-remote-access-and-operator-diagnostics-guardrails`, `phase07-session07-hosted-guardrails-validation-and-documentation-closeout`, Phase 08 trusted-erasure and release-hardening planning *** ## 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-session04-hosted-persistence-and-public-replay-boundaries/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.