> 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/phase15-session02-security-and-privacy-vault/spec.md). # Session Specification **Session ID**: `phase15-session02-security-and-privacy-vault` **Phase**: 15 - Trust, Content, And Conversion Pages **Status**: Not Started **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session builds the `/security` route for the static FactionOS public website. The page makes the local-first trust boundary a primary product feature by explaining what stays on the developer machine, when optional integrations can transfer data, how redaction and consent guardrails work, and why first-release analytics are absent by default. The work follows the Phase 15 security stub and the current cumulative security posture. It must be precise rather than broad: FactionOS can claim a local-first default and no hosted account requirement for the core workflow, but it must not claim hosted identity, full trusted erasure, production-hosted validation, formal certification, broad media readiness, remote execution, or active analytics capture. Implementation stays inside `public-website` as static Astro output. The page should use typed package-local data, existing layout and CTA primitives, accessible section markup, conservative copy, external demo/docs link treatment, and package-local validation commands. *** ## 2. Objectives 1. Create `/security` with complete local-first security and privacy content covering lifecycle, data residency, optional boundaries, redaction, consent, telemetry, analytics, and FAQ. 2. Centralize security page copy, metadata, FAQ rows, lifecycle steps, boundary lists, and CTA links in typed website data. 3. Compose reusable Astro security sections that are accessible, responsive, and explicit about static website versus local product behavior. 4. Validate the route with package typecheck, build output review, responsive/accessibility smoke checks, ASCII/LF scans, and no-claim copy review. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session02-design-tokens-and-layout-shell` - shared shell, navigation, layout primitives, tokens, and responsive baseline exist. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - metadata, canonical URL, sitemap, robots, RSS, and structured data helpers exist. * [x] `phase14-session01-hero-cockpit-and-primary-ctas` - demo/docs CTA patterns and static website boundary copy exist. * [x] `phase14-session03-homepage-narrative-sections` - local-first lifecycle and homepage security boundary patterns exist. * [x] `phase14-session04-product-overview-page` - product surface map, internal security links, and optional capability guardrails exist. * [x] `phase14-session05-features-and-how-it-works-pages` - hook-to-cockpit flow, passive security handoffs, and docs/security route links exist. * [x] `phase15-session01-use-cases-hub-and-role-pages` - Phase 15 route/data patterns, conversion links, and public-site depth conventions exist. ### Required Tools/Knowledge * Astro 6 static routes, scoped component CSS, and package-local layouts. * TypeScript literal unions and `satisfies` for typed static data. * Existing `BaseLayout`, `Shell`, `Section`, `Badge`, `ButtonLink`, `Panel`, and marketing component patterns. * Current security posture in `.spec_system/SECURITY-COMPLIANCE.md`, `.spec_system/CONSIDERATIONS.md`, and `docs/privacy-and-security.md`. * Public website boundaries: no server adapter, no analytics by default, no hosted forms, no auth, no CMS, and no runtime personalization. ### Environment Requirements * Node.js 26.2.0 or newer. * npm workspace commands available from the repository root. * No new production dependencies unless a separate review justifies them. *** ## 4. Scope ### In Scope (MVP) * Visitors can open `/security` and understand the first-release trust posture: static website, local-first product baseline, no hosted account required for core workflow, and no analytics by default. * Visitors can read a trust manifesto that states local-first defaults without implying perfect security or certification. * Visitors can follow the local-only data lifecycle from hook event, local ingest, local cockpit display, optional outbound transfer, and manual cleanup boundaries. * Visitors can see what stays on the machine by default: prompts, file paths, terminal output, local event snapshots, and credentials. * Visitors can distinguish optional War Room, optional outbound adapters, and future hosted services from default local behavior. * Visitors can understand redaction and consent guardrails, including blocked payload categories and explicit opt-in requirements for external transfer. * Visitors can read passive Settings/telemetry posture: status copy may exist, but recorder, heatmap, dashboard, ingestion, and session replay analytics are not active. * Visitors can read analytics posture: absent by default, future Umami usage must follow existing guardrails, and sensitive payload categories must never be collected. * Visitors can use a security FAQ and links to product, how-it-works, demo, and docs without adding tracking, forms, or runtime fetches. * Maintainers can update security route copy, FAQ, lifecycle rows, boundary lists, CTA targets, and no-claim wording from a typed data module. ### Out of Scope (Deferred) * Legal privacy policy page - *Reason: Phase 15 Session 05 owns legal and policy routes with owner/legal review markers.* * Security certification claims - *Reason: formal certification evidence does not exist in the current security posture.* * Full threat model documentation - *Reason: this session creates public website copy, not a complete engineering threat model.* * Trusted unified erasure claim - *Reason: cumulative posture keeps full trusted erasure open/no-claim across hosted, backup, log, archive, workspace, and future boundaries.* * Hosted identity, SSO, org membership, or public collaboration safety claim - *Reason: Worker room authority is not hosted account identity.* * Production-hosted validation claim - *Reason: live hosted validation remains no-claim until separately proven.* * Real file, git, terminal, Docker, remote, or inbound command executor claim - *Reason: real executors and inbound commands remain deferred pending threat model, authorization, audit, tests, and docs.* * Runtime analytics, trackers, hosted forms, auth, CMS, server rendering, or runtime personalization - *Reason: first-release website remains static Astro output.* *** ## 5. Technical Approach ### Architecture Create `public-website/src/data/security.ts` as the typed source of truth for security route metadata, hero copy, trust manifesto content, lifecycle rows, default-local data categories, optional boundary cards, redaction and consent guardrails, telemetry/analytics posture, FAQ entries, and CTA links. Keep long copy reviewable as structured objects instead of scattering literal strings across route markup. Create focused Astro components for the dense trust sections and FAQ. The page route should compose data through `BaseLayout`, `Shell`, `Section`, `Badge`, `ButtonLink`, and `Panel`, with scoped styles that preserve responsive wrapping and avoid nested card shells. If FAQ structured data is added, extend the existing `StructuredDataPayload` type in `site.ts` rather than bypassing the metadata helper. The page must remain fully static. It must not add browser scripts, analytics SDK imports, network fetches, form handlers, cookies, localStorage writes, auth flows, or third-party embeds. External demo/docs links should use the existing explicit external link semantics. ### Design Patterns * Typed security data module: Keeps claim boundaries, FAQ rows, CTA targets, and no-claim copy centralized for review. * Static route composition: Uses Astro pages and scoped CSS with no server adapter, runtime fetch, or personalization. * Boundary cards: Pairs every capability claim with a default posture and a no-overclaim guardrail. * Accessible FAQ: Uses semantic headings or disclosure-free static sections unless an implementation has a concrete need for client interactivity. * External link discipline: Uses existing `ButtonLink` and link helpers so demo and docs are explicit external destinations. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3. * Scoped Astro component styles plus `public-website/src/styles/global.css` tokens. * Existing npm workspace scripts for typecheck and build. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/security.ts` | Typed security route metadata, trust manifesto, lifecycle rows, local data categories, optional boundaries, redaction/consent/analytics posture, FAQ entries, and CTA links | \~380 | | `public-website/src/components/marketing/SecurityVault.astro` | Main security page sections for manifesto, lifecycle, data-stays-local list, optional boundaries, redaction, consent, telemetry, analytics, and CTAs | \~360 | | `public-website/src/components/marketing/SecurityFaq.astro` | Accessible security FAQ section with static answers and supporting links | \~220 | | `public-website/src/pages/security.astro` | Security route with metadata, structured data if appropriate, shell composition, and section wiring | \~180 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/site.ts` | Add FAQ structured data support if used and verify existing security route constants/canonical URL are reused | \~35 | | `public-website/src/data/navigation.ts` | Confirm Security remains reachable in primary/mobile/footer navigation and refine descriptions only if needed | \~10 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `/security` renders with title, description, canonical metadata, trust manifesto, local lifecycle, data-stays-local list, optional boundary cards, redaction/consent guardrails, telemetry/analytics posture, FAQ, and CTAs. * [ ] Copy says prompts, file paths, terminal output, local event snapshots, credentials, replay data, demo payloads, and user-provided code are not collected by the public website and are not sent by default product behavior. * [ ] Optional War Room, outbound adapters, and future hosted services are described as optional and boundary-aware, not default hosted product behavior. * [ ] Analytics posture is explicit: absent by default, future Umami work must follow repo guardrails, and sensitive payload categories are blocked. * [ ] Page links to product, how-it-works, demo, and docs with existing internal/external link semantics. * [ ] Security FAQ answers likely trust questions without introducing legal privacy policy, certification, trusted erasure, hosted identity, or production-hosted validation claims. * [ ] No tracker, analytics SDK, hosted form, auth, CMS, runtime fetch, cookie, or localStorage code is introduced. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Built `/security` output includes expected metadata, route links, external demo/docs links, FAQ content, and boundary copy. * [ ] Manual responsive smoke checks cover desktop, tablet, and 360px mobile widths for lifecycle rows, data cards, boundary lists, FAQ, CTA rows, and navigation. * [ ] Manual keyboard/focus review confirms links and CTAs expose clear names and focus treatment. ### Non-Functional Requirements * [ ] Static website boundary is preserved: no analytics, trackers, forms, auth, CMS, server adapter, hosted persistence, runtime personalization, or command execution. * [ ] Copy avoids hosted identity, SSO, org membership, public collaboration safety, production auditability, formal certification, full trusted erasure, production-hosted validation, broad media readiness, real executor, remote execution, inbound command, and hidden telemetry claims. * [ ] Dense security cards and FAQ rows expose text equivalents and do not depend on color alone. * [ ] Text wraps without overlapping controls, cards, headings, or CTA rows at common mobile widths. * [ ] No new production dependency is added. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Security copy reviewed against `.spec_system/SECURITY-COMPLIANCE.md` and `.spec_system/CONSIDERATIONS.md`. *** ## 8. Implementation Notes ### Key Considerations * Reuse `sitePaths.security`, `siteUrls.security`, `siteExternalDestinations`, `siteStructuredData`, `ButtonLink`, `Badge`, `Panel`, and existing route metadata conventions. * The existing `SecurityBoundary.astro` is homepage-specific and can be used as a visual/reference pattern, but the `/security` page needs fuller sections and typed security route data. * Keep the distinction clear between this static public website, the separate synthetic demo, public GitBook docs, and the local product runtime. * Copy can claim "local-first by default" and "no hosted account required for the core workflow"; it cannot claim broad security outcomes or certifications without evidence. * Do not add accordions or client scripts for FAQ unless there is a concrete accessibility and maintenance reason. Static FAQ sections are sufficient for MVP. * If structured data is used for FAQ, type it in `site.ts` and ensure build output remains valid static JSON-LD. ### Potential Challenges * Security copy can overpromise. Mitigation: pair each claim with a boundary, an optional/future qualifier, or an explicit no-claim note. * Dense trust content can become hard to scan. Mitigation: group it into lifecycle, data-stays-local, optional boundaries, guardrails, analytics, FAQ, and CTA sections with concise headings. * Mobile cards can overlap or become too tall. Mitigation: use stable grid tracks, `min-width: 0`, wrapping, and straightforward one-column breakpoints. * FAQ wording can drift into legal policy. Mitigation: state product posture and route legal/privacy policy detail to the later Session 05 scope. ### Relevant Considerations * \[P14-public-website] **Public site page depth is still upcoming**: This session continues Phase 15 by making trust/security a first-class page. * \[P13-public-website] **Static Astro boundary is intentional**: The page must remain static Astro output with no server adapter, analytics, hosted forms, CMS, auth, or runtime personalization. * \[P13-public-website] **Public website external links are explicit**: Demo and docs CTAs may link out, but no third-party tracking or hosted form behavior should be introduced. * \[P14-public-website] **Typed marketing data modules**: Use a typed `security.ts` data module so route copy, metadata, CTA targets, and boundary language stay centralized. * \[P06-S07-HOSTED-IDENTITY] **Hosted identity remains no-claim**: Do not imply hosted accounts, organization membership, SSO, public collaboration safety, or production auditability. * \[P06-S07-ERASURE] **Trusted unified erasure remains no-claim**: Do not claim full trusted deletion across local, hosted, backup, log, archive, or future surfaces. * \[P06-S07-HOSTED-VALIDATION] **Production-hosted validation remains no-claim**: Do not imply deployed app-shell validation beyond proven static website and demo/docs destinations. * \[P07] **Analytics capture remains disabled by default**: Mention future Umami guardrails only as future/optional posture, not active website or app tracking. * \[P03] **Real executors remain unimplemented by design**: Do not imply file, git, terminal, Docker, remote, or inbound command execution exists. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * FAQ links and CTAs without clear accessible names, focus states, or external destination treatment. * Dense responsive sections causing local-data cards, boundary lists, FAQ rows, or CTA labels to overlap on mobile. * Security, analytics, consent, erasure, hosted identity, or integration copy implying stronger guarantees than current evidence supports. *** ## 9. Testing Strategy ### Unit Tests * Use TypeScript typecheck to validate `security.ts` route link keys, section ids, FAQ ids, tone unions, and component props. * Use Astro build output as static route coverage for `/security`. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck`. * Run `npm --workspace @factionos/public-website run build`. * Inspect generated HTML for `/security`, canonical metadata, FAQ content, internal product/how-it-works links, external demo/docs links, and no-claim boundary copy. ### Manual Testing * Smoke the security page at desktop, tablet, and 360px mobile widths. * Verify keyboard focus reaches primary CTAs, supporting links, FAQ links, header links, footer links, and external demo/docs links in a sensible order. * Check that long security terms, payload category names, and FAQ answers wrap without overlap. * Confirm no network, analytics, tracker, form, cookie, localStorage, or runtime personalization code was introduced. ### Edge Cases * Missing or mistyped security link key should fail typecheck rather than producing a broken route. * External links must include external destination affordance through existing `ButtonLink` or navigation patterns. * FAQ answers must stay product-posture oriented and not become legal policy or certification language. * Optional integrations must not be presented as default data transfer or hidden analytics. * Static examples must not look like live telemetry or imply the public website is connected to a local workspace. *** ## 10. Dependencies ### External Libraries * Astro: 6.4.2 * TypeScript: 5.9.3 * `@astrojs/mdx`: 6.0.1 * `@astrojs/rss`: 4.0.18 * `@astrojs/sitemap`: 3.7.3 * `sharp`: 0.34.5 ### Other Sessions * **Depends on**: `phase13-session02-design-tokens-and-layout-shell`, `phase13-session03-seo-metadata-and-static-site-plumbing`, `phase14-session01-hero-cockpit-and-primary-ctas`, `phase14-session03-homepage-narrative-sections`, `phase14-session04-product-overview-page`, `phase14-session05-features-and-how-it-works-pages`, `phase15-session01-use-cases-hub-and-role-pages` * **Depended by**: `phase15-session05-roadmap-faq-and-legal-pages`, `phase15-session06-cross-linking-and-copy-consistency-pass` *** ## 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/phase15-session02-security-and-privacy-vault/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.