diff --git a/AGENTS.md b/AGENTS.md index 2e577d8..af0d9ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,8 @@ - This repository is `open-proofline/web-client`. - This is the Proofline web client only. The current backend source of truth is `open-proofline/server`. +- The project-level public governance, political alignment, public voice, and + reusable README baseline source of truth is `open-proofline/website`. - Do not implement backend features here. - Do not add browser decryption unless explicitly scoped and threat-modeled. - Do not add recording or capture behavior here. @@ -38,6 +40,17 @@ ## Commands +For documentation or reusable-prompt-only changes: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +For frontend source, route, browser-flow, auth, API-client, or behavior changes: + ```bash npm run typecheck npm run lint @@ -56,3 +69,10 @@ Check that changes remain frontend-only, do not overpromise production status, do not introduce browser decryption or key unwrapping, keep token persistence explicit and reviewable, preserve accessible loading/error/empty states, and keep server facts tied back to `open-proofline/server`. + +When changes touch README structure, public voice, governance, +cooperative/public-good framing, political alignment, funding posture, or +source-of-truth mapping, check the current `open-proofline/website` README, +`docs/governance-and-political-alignment.md`, and +`docs/repository-readme-baseline.md` instead of rewriting those project-level +claims here. diff --git a/CHANGELOG.md b/CHANGELOG.md index 80db715..d9682d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ## Unreleased +- Refreshed README, documentation, and reusable Codex workflow guidance to + consume the website repository's governance, public voice, source-of-truth + map, and README baseline while preserving web-client-specific boundaries. +- Clarified that server-supported account second-factor routes remain outside + the current web-client UI and API-client method surface. - Documented end-user web-client product design direction for user-facing language, trusted-contact invite/accept flows, viewer-link UX, future viewer map/location behavior, future browser capture framing, and product-design diff --git a/README.md b/README.md index 85bd164..4482fc6 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,131 @@ # Proofline Web Client -> This is an experimental Proofline web client prototype. It does not implement recording, browser decryption, trusted-contact decryption, key escrow, playable media export, emergency dispatch, or production safety workflows. -> -> Users or trusted contacts remain responsible for contacting emergency services. +

+ CI + License: AGPL-3.0-only + Status: Experimental + Security policy + Support Proofline +

-Proofline Web Client is the experimental React account and incident-review client -for the planned `open-proofline/web-client` repository. It is a frontend-only -prototype for authenticated account/session state, owned incident metadata, -incident detail review, stream/chunk metadata, contact public-key metadata, -sharing-grant metadata, and wrapped-key metadata. +Proofline is experimental public-interest open-source privacy and evidence +infrastructure. This repository contains the React web client and account portal +prototype for authenticated account flows, incident metadata review, contact and +sharing metadata, wrapped-key metadata review, and conservative browser session +handling. -The current backend source of truth remains -[`open-proofline/server`](https://github.com/open-proofline/server). This repo -must not make independent claims about backend behavior when the server docs -disagree or have moved. +Proofline is not an emergency service, emergency dispatch system, +emergency-services integration, staffed response center, or guaranteed +real-time response system. Users and trusted contacts remain responsible for +contacting emergency services. -End-user product language and interaction direction are documented in -[End-User Web Client Design](docs/end-user-web-client-design.md). That document -defines how the prototype should evolve from technical metadata review toward a -normal user-facing account, incident review, trusted-contact, viewer-link, and -future fallback capture experience without changing current runtime behavior. +## Current Status -## Stack +This repository is experimental and maintainer-led. It is not production-ready +emergency infrastructure, a production account portal, or production public API +deployment approval. + +Current web-client status: - Vite, React, and TypeScript -- TanStack Router -- TanStack Query -- Zod -- Tailwind CSS with the Vite Tailwind plugin -- Tailwind Catalyst component sources used inside this app -- Vitest, Testing Library, MSW, and Playwright +- TanStack Router route definitions under `src/routes/` +- TanStack Query for server state +- Zod schemas near the API client under `src/api/` +- auth/session code under `src/auth/` +- app-specific components under `src/components/proofline/` +- Tailwind CSS with Catalyst component source used inside this app +- prototype mock mode by default +- live mode for reviewed local backend testing +- explicit bearer-token and browser-cookie auth client modes +- frontend CI for dependency audit, typecheck, lint, unit tests, build, and + Playwright smoke tests -## Setup +## What This Repository Is -```bash -npm install -cp .env.example .env -``` +`open-proofline/web-client` is the frontend account and incident-review +prototype for Proofline. + +It currently includes: + +- login/logout prototype flow +- public registration form flow against the current server registration + contract +- browser email-verification route that reads a URL fragment token and clears it + from the address bar +- authenticated app shell +- account profile and password-change UI +- memory-first bearer session state, with optional local-storage persistence + for local development only +- explicit browser-cookie auth mode with in-memory CSRF token handling +- incident list UI backed by prototype mock data in mock mode and authenticated + owner-scoped `GET /v1/incidents` responses in live mode +- incident detail, stream, chunk, contact public-key, sharing-grant, and + wrapped-key metadata review +- owner incident deletion status and request UI +- wrapped-key delivery revocation UI for account-owned records +- safe loading, empty, and error states +- visible experimental and emergency-reliance warnings + +Current screens still expose some technical metadata. Future user-facing work +should follow [End-User Web Client Design](docs/end-user-web-client-design.md): +lead with human status, next actions, access state, and safety boundaries, and +move technical details behind advanced or developer-focused disclosure. + +## What This Repository Is Not + +This repository is not: + +- the Go backend +- the static public website +- an iOS or Android app +- a protocol implementation +- a production recording client +- an emergency service, emergency dispatch system, or staffed response center +- a notification delivery system +- a decryption service +- key escrow +- a hosted-account billing system +- a public admin/operator surface +- production public `/v1` deployment approval +- a standalone Catalyst, Tailwind, or UI component kit + +Do not add backend behavior, API behavior changes, recording/capture, +notification delivery, hosted-account billing, payment-gated access, browser or +backend decryption, trusted-contact decryption, raw key storage, key escrow, +playable export, public admin/operator surfaces, mobile-client behavior, or +protocol behavior here unless the maintainer explicitly changes the repository +strategy. + +## Source-Of-Truth Map + +Use the right source for the claim: + +| Topic | Read | +| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Web-client behavior, prototype limits, local development, and validation | This repository: `README.md`, `AGENTS.md`, `SECURITY.md`, and [docs/](docs/README.md) | +| End-user web-client product direction | [docs/end-user-web-client-design.md](docs/end-user-web-client-design.md) | +| API client behavior and route assumptions | [docs/api-client.md](docs/api-client.md), then verify backend facts against `open-proofline/server` | +| Backend behavior, deployment, API, auth, registration, billing placeholders, and security facts | [`open-proofline/server`](https://github.com/open-proofline/server) | +| Public web-client deployment boundary | [`open-proofline/server/docs/public-web-client-deployment-boundary.md`](https://github.com/open-proofline/server/blob/develop/docs/public-web-client-deployment-boundary.md) | +| Project public website and public framing | [`open-proofline/website`](https://github.com/open-proofline/website) | +| Governance, political alignment, and public-good posture | [`open-proofline/website/docs/governance-and-political-alignment.md`](https://github.com/open-proofline/website/blob/main/docs/governance-and-political-alignment.md) | +| Reusable Proofline README structure and public voice | [`open-proofline/website/docs/repository-readme-baseline.md`](https://github.com/open-proofline/website/blob/main/docs/repository-readme-baseline.md) | +| Organization-level overview | [`open-proofline/.github`](https://github.com/open-proofline/.github) | + +Keep repository-specific facts in the repository that owns them. Keep +project-wide governance posture in the website repository. + +## Current, Prototype, Planned, And Not Implemented + +| Category | Web-client boundary | +| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Current in this repo | Login/logout, registration form, email verification route, account overview, account password change, incident list/detail metadata review, contact public-key metadata management, sharing-grant metadata management, wrapped-key metadata review and revocation, owner deletion request UI, mock mode, bearer and cookie auth client modes. | +| Prototype/mock only | Sample account and incident records for local testing. Mock mode does not create accounts, send email, verify real tokens, model billing, prove server behavior, or approve public deployment. | +| Server-supported facts to verify | Current `open-proofline/server` docs cover local account sessions, configurable registration, email verification, browser-cookie auth and CSRF when enabled, account second-factor setup and per-session verification routes, owner-scoped incident list/detail routes, contact public-key metadata, owner-scoped sharing grants, wrapped-key metadata, viewer-token create/revoke routes, encrypted bundle downloads, and public deployment review boundaries. | +| Planned or design-only | End-user language cleanup, account second-factor setup UX, invite/accept trusted-contact flows, automatic client-managed contact key creation, durable viewer-link management, web-client no-account viewer, browser capture fallback, payment-backed hosted account lifecycle, notification delivery, and trusted-contact account access. | +| Not implemented and not implied | Production readiness, emergency dispatch, emergency-services integration, guaranteed response, staffed response center, production browser recording, production mobile capture, trusted-contact notifications, live context sharing, backend decryption, browser decryption, trusted-contact decryption, raw server-held media keys, key escrow, hosted-account billing as live behavior, public production admin/operator surfaces, legal admissibility, or legal reliability. | + +## API And Session Boundary By default the app runs in prototype mock mode: @@ -58,286 +147,122 @@ For reviewed local browser-cookie auth testing, also set: VITE_PROOFLINE_AUTH_MODE=cookie ``` -## Development +Bearer session tokens are kept in memory by default. The optional +`VITE_PROOFLINE_SESSION_STORAGE=localStorage` adapter is for local development +only and must not be treated as production browser credential storage. -```bash -npm run dev -npm run typecheck -npm run lint -npm run test -npm run build -npm run test:e2e -``` +Cookie-mode sessions do not store bearer tokens in the web client; the browser +session cookie is HttpOnly and managed by the server. Cookie mode sends +`credentials: "include"` only for cookie-authenticated requests and attaches the +server-provided CSRF header to unsafe requests. Bearer and cookie credentials +must not be mixed. -Formatting: +Public registration is controlled by `open-proofline/server`, not this +frontend. `disabled` and `admin_only` reject public registration, `open` creates +a pending email-verification account, and `paid` remains a fail-closed +placeholder that does not create checkout sessions, subscriptions, active +accounts, or billing webhooks. -```bash -npm run format -npm run format:check -``` +Email verification links carry a raw verification token in the URL fragment. +The web client submits that token in the verification request body and clears +the fragment. Raw verification tokens must not be logged, persisted, +screenshotted, copied into issue drafts, or sent to analytics. -## Product Scope +## Public Deployment Boundary -Proofline Web Client is the experimental React account portal and incident-review client for Proofline. +A static web client is not production-ready just because it can be hosted. +Public deployment requires reviewed backend and infrastructure work, including +route exposure, credentialed CORS, CSRF, cookie settings, cache policy, TLS, +edge abuse controls, logging redaction, and private-admin route exclusion. -The intended product model is a publicly hosted Proofline service where users -can create paid accounts once the backend, deployment, billing, abuse controls, -and operational hardening are ready. The server now documents public -self-registration modes, but registration is backend-configured and disabled by -default. Open self-registration requires reviewed server configuration and email -verification before login; paid registration remains a fail-closed placeholder, -not billing. +The current public web-client deployment boundary is documented in +[`open-proofline/server/docs/public-web-client-deployment-boundary.md`](https://github.com/open-proofline/server/blob/develop/docs/public-web-client-deployment-boundary.md). +Static-host browser header guidance in +[Browser Security Headers](docs/browser-security-headers.md) is a +deployment-review starting point, not production approval or broad public `/v1` +approval. -The web client is responsible for the user-facing account portal, -authenticated incident review, future trusted-contact access flows, future -viewer-link owner controls, and the future no-account viewer experience. It is -not the admin dashboard, recording client, mobile app, backend, or protocol -repository. +## Catalyst And Tailwind -Current prototype screens still expose technical metadata concepts such as -streams, chunks, contact public keys, sharing grants, and wrapped-key records. -Future user-facing work should follow the end-user design document: lead with -plain product language, show human status and next actions first, and move -technical details behind advanced or developer-focused disclosure. +Catalyst-derived component source files are used as part of this application. +They must not be extracted, packaged, published, or redistributed as a +standalone UI kit, template, starter, package, or design asset set. -## Current Scope +The copied Catalyst files remain governed by the Tailwind Plus License preserved +in `src/components/catalyst/LICENSE.md`. -The current bootstrap includes: +## Security Reporting -- login/logout prototype flow -- public registration form flow against the server registration contract -- browser email-verification route that clears verification URL fragments -- authenticated app shell -- conservative session state with memory-first token storage -- optional local-storage session persistence for local development only -- explicit bearer-token and browser-cookie auth client modes -- incident list UI backed by mock data in prototype mode and authenticated - owner-scoped `GET /v1/incidents` responses in live mode -- incident detail metadata UI -- stream and chunk metadata review -- contact public-key metadata views and account-level management -- sharing-grant metadata views and incident-scoped management -- wrapped-key metadata views and delivery revocation -- owner incident deletion status and request UI -- safe loading, empty, and error states -- visible prototype and emergency-reliance warnings -- frontend CI for typecheck, lint, unit tests, build, and Playwright smoke tests +Do not report security vulnerabilities through public GitHub issues. Use GitHub +private vulnerability reporting where available, and follow +[SECURITY.md](SECURITY.md). -## Planned Account Portal Scope - -Planned account portal work includes: - -- public landing and pricing/account-entry pages -- payment-gated account creation -- login/logout -- session status and session revocation flows -- account billing status display -- subscription/payment status handling -- clear account-disabled, payment-required, expired-session, unauthorized, and forbidden states -- browser-safe API error handling -- browser token-storage review and hardening -- deployment review for browser-cookie auth, credentialed CORS, and exact - reviewed origins +Do not publish real secrets, raw session tokens, browser session cookies, CSRF +tokens, raw viewer tokens, token-bearing viewer links, Authorization headers, +request bodies, uploaded bytes, plaintext, raw keys, raw media keys, contact +private keys, wrapped-key ciphertext, verification credentials, stored paths, +object keys, private deployment details, exploit details, or user safety data. -Payment-gated registration must be implemented as a backend-supported account -lifecycle, not just a frontend form. The current server paid-registration mode -returns a fail-closed placeholder error and does not create checkout sessions, -subscriptions, active accounts, or billing webhooks. The web client may present -billing UI only after the backend provides reviewed routes and state transitions -for payment confirmation, subscription status, and disabled/unpaid account -behavior. - -## Planned Incident Review Scope - -Planned authenticated incident-review work includes: - -- live owned-incident listing in the client against the current server route -- incident detail review -- end-user incident review language that foregrounds status, latest update, - upload state, shared access state, evidence protection, and next actions -- stream and chunk metadata review behind advanced or technical details -- viewer-token creation and revocation UI -- encrypted bundle download affordances with clear warnings -- mode, capture-profile, escalation-policy, sharing-state, deletion-state, and retention metadata display -- safe empty/error/loading states for all incident views - -The web client must not expose private admin/operator behavior or route `/v1/admin/...` functionality from a public edge. - -## Planned Sharing And Contact Scope - -Planned sharing/contact work includes: - -- trusted-contact access design, once separately scoped and threat-modeled -- invite/accept trusted-contact flows that avoid manual public-key handling as - the primary user experience -- automatic client-managed key creation and public-key publication after the - backend, client, and key-custody design support it - -Sharing metadata support does not imply browser decryption, trusted-contact decryption, raw key access, key escrow, or playable export. Wrapped-key revocation stops future delivery only and cannot claw back material an authorized actor may already have received. - -## Future Trusted-Contact Scope - -Future trusted-contact work may include: - -- trusted-contact account access -- trusted-contact incident access views -- grant-aware incident metadata review -- wrapped-key metadata delivery to authorized trusted contacts -- careful UX for emergency and non-emergency access states - -Trusted-contact flows must be designed and reviewed before implementation. They must not imply emergency-services integration or guaranteed emergency response. - -## Future Browser Recording Scope - -This repository does not currently implement recording or capture behavior. - -A future browser-based recording prototype may be added as a separately scoped -fallback and secondary capture method for desktop/browser use cases. Possible -capture modes may include: - -- microphone-only recording -- camera and microphone recording -- screen, window, or tab recording -- screen capture with microphone audio - -Browser recording must be treated as experimental. It must not be presented as -a replacement for native iOS or Android recording clients, and it must not be -described as reliable emergency capture or guaranteed background recording. - -Before implementation, browser recording must be separately designed, documented, threat-modeled, and tested. The design must cover: - -- browser permission prompts and explicit user consent -- browser and operating-system compatibility limits -- screen, camera, microphone, and system-audio support differences -- tab close, browser crash, sleep, permission loss, and background reliability limits -- local encrypted staging before upload -- chunking behavior -- upload retry and idempotency behavior -- user-visible recording state -- safe failure states -- privacy and safety wording -- browser token-storage and XSS implications - -If implemented, browser recording must preserve these boundaries: - -- no backend decryption -- no browser decryption unless separately scoped -- no raw server-held media keys -- no key escrow -- no break-glass access -- no playable media export unless separately scoped -- no emergency-services integration -- no claim of production readiness or emergency reliability - -Browser recording is intended for possible desktop/browser interaction records, meetings, calls, evidence notes, or other non-mobile capture contexts. Native platform clients remain the intended direction for safety-critical mobile recording and stronger lifecycle reliability. - -## Explicit Non-Goals - -This repository must not implement: +Backend security issues may belong in +[`open-proofline/server`](https://github.com/open-proofline/server). Public +website framing or governance issues may belong in +[`open-proofline/website`](https://github.com/open-proofline/website). -- production mobile-client behavior -- browser decryption -- backend decryption -- trusted-contact decryption -- raw media-key handling -- raw server-held keys -- key escrow -- break-glass key access -- playable media export -- emergency dispatch -- push, SMS, or Messenger notifications -- OAuth or JWT unless explicitly scoped later -- public admin dashboards -- backend implementation -- protocol repository behavior -- production safety workflows - -Users and trusted contacts remain responsible for contacting emergency services. +## Local Development -## Public Deployment Boundary +Install dependencies: + +```bash +npm install +``` -The web client may be designed for a future public Proofline service, but this repository must not claim production readiness. - -Public deployment requires separate backend and infrastructure work, including: - -- TLS and edge hardening -- public API exposure review -- admin/operator route exclusion from public edges -- payment-gated account creation -- abuse controls and rate limiting -- browser credential-storage review -- credentialed CORS and CSRF review for any browser-cookie auth mode -- CSP/XSS and browser security-header review -- logging and error-redaction review -- backup/restore and deletion/retention operational review -- monitoring and incident response planning - -Until those requirements are implemented and reviewed, the web client remains an experimental prototype. - -Static hosting header guidance is documented in -[Browser Security Headers](docs/browser-security-headers.md), but those headers -do not imply production readiness or public `/v1` API readiness. - -## API Boundary - -The server currently confirms bearer session auth, browser-cookie auth routes, -`POST /v1/auth/register`, `POST /v1/auth/email/verify`, `GET /v1/account`, -`POST /v1/account/password`, owner-scoped incident list/detail routes, -viewer-token create/revoke routes, contact public-key routes, sharing-grant -routes, and wrapped-key routes. Current `open-proofline/server` documents -authenticated `GET /v1/incidents`, and this client parses that response shape -in live mode. Mock mode uses prototype incident records only and must not be -treated as backend truth. - -Authenticated users can open the account profile route to review safe account -metadata and change their password through `POST /v1/account/password`. The -server keeps the active session usable after a successful password change and -revokes other sessions for the account. - -Public registration is controlled by the server's -`SAFE_ACCOUNT_REGISTRATION_MODE`. `disabled` and `admin_only` reject public -registration with `registration_disabled`; `open` creates a -`pending_email_verification` account and sends a verification link before login -is allowed; `paid` returns `registration_payment_unavailable` and does not -perform billing or create an active account. Registration and email verification -do not create browser sessions. +Start the Vite development server: -Email verification links carry a raw verification token in the URL fragment. -The web client reads that secret-bearing fragment, submits the token in the -verification request body, and clears the fragment from the address bar. Raw -verification tokens must not be logged, persisted, screenshotted, copied into -issue drafts, or sent to analytics. - -Viewer-token create/revoke UI is documented as a design boundary in -[Viewer Token UI Design](docs/viewer-token-ui-design.md). The intended -web-client viewer will replace the current server-rendered incident viewer -while preserving the same viewer-token system for no-account, read-only access -to unencrypted incident data. That path is separate from future notification -delivery and trusted-contact account/key flows. - -The client must not log session tokens, Authorization headers, request bodies, -uploaded bytes, plaintext, raw keys, raw media keys, contact private keys, -wrapped-key ciphertext, verification credentials, object keys, stored paths, -private deployment details, or user safety data. - -## Session Storage - -Bearer session tokens are kept in memory by default. A local-storage adapter -exists for developer convenience only behind -`VITE_PROOFLINE_SESSION_STORAGE=localStorage`. Browser token persistence must -be reviewed before any production use. Cookie-mode sessions do not store bearer -tokens; the browser session cookie is HttpOnly and managed by the server. +```bash +npm run dev +``` -## Catalyst And Tailwind +Run the full frontend validation stack: + +```bash +npm run typecheck +npm run lint +npm run test +npm run build +npm run test:e2e +git diff --check +``` + +For documentation and reusable-prompt-only changes, use the lighter validation +from the Codex docs workflows: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +Run Playwright when route, browser flow, auth, UI behavior, or visible page +copy changes. Do not claim validation passed unless the command actually ran. + +## Governance And Public-Good Posture + +Proofline is intended to grow as public-good open-source infrastructure. The +planned long-term direction is a non-distributing cooperative or similar +mission-locked structure aligned with cooperative and libertarian socialist +principles. Pay should be for defined labour, not ownership extraction. + +Read the canonical project posture in +[`open-proofline/website/docs/governance-and-political-alignment.md`](https://github.com/open-proofline/website/blob/main/docs/governance-and-political-alignment.md). + +The reusable Proofline README baseline and public voice guidance live in +[`open-proofline/website/docs/repository-readme-baseline.md`](https://github.com/open-proofline/website/blob/main/docs/repository-readme-baseline.md). -Catalyst-derived component source files are used as part of this application, -not redistributed as a standalone UI kit, template, starter, package, or design -asset set. The copied Catalyst files remain governed by the Tailwind Plus -License preserved in `src/components/catalyst/LICENSE.md`. +Donations and contributions do not create accounts, unlock features, provide +support priority, or provide emergency assistance. -## Security Status +## License -This repo is not production-ready. It has no production account portal, no -public API hardening, no browser decryption design, no recording client, and no -emergency-services integration. Treat the server docs and security model as the -source of truth for current backend behavior. +Proofline Web Client is licensed under the +[GNU Affero General Public License v3.0 only](LICENSE). diff --git a/SECURITY.md b/SECURITY.md index c91cd5b..dc52ef8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,10 +2,16 @@ Proofline Web Client is experimental and not production-ready. +Do not report security vulnerabilities through public GitHub issues. Use GitHub +private vulnerability reporting where available, and keep sensitive details out +of public issues, PRs, docs, prompts, screenshots, logs, and examples. + Do not report real secrets, raw session tokens, browser session cookies, CSRF tokens, raw viewer tokens, token-bearing viewer links, Authorization headers, -request bodies, plaintext, raw keys, wrapped-key ciphertext, verification -credentials, private deployment details, or user safety data in public issues. +request bodies, uploaded bytes, plaintext, raw keys, raw media keys, contact +private keys, wrapped-key ciphertext, verification credentials, stored paths, +object keys, private deployment details, exploit details, or user safety data in +public issues. Backend security issues may belong in [`open-proofline/server`](https://github.com/open-proofline/server). Web-client @@ -13,6 +19,10 @@ issues involving XSS, dependency risk, browser token handling, local storage, browser-cookie auth, CSRF handling, credentialed CORS, or UI disclosure should be handled carefully and without public sensitive details. +Project-wide governance, public-good posture, and public voice belong in +[`open-proofline/website`](https://github.com/open-proofline/website). They are +not a substitute for component-specific security review. + This repo does not implement recording, browser decryption, backend decryption, trusted-contact decryption, key escrow, playable media export, emergency dispatch, or production safety workflows. diff --git a/codex/README.md b/codex/README.md index e9e38f0..d9b3c4f 100644 --- a/codex/README.md +++ b/codex/README.md @@ -6,6 +6,16 @@ The web-client repository is frontend-only. `open-proofline/server` remains the source of truth for current backend behavior, routes, security model, and deployment constraints. +`open-proofline/website` is the project-level source for Proofline public +governance posture, political alignment, cooperative/public-good framing, +public voice, reusable README structure, and source-of-truth mapping. When a +task touches those areas, inspect the current website README, +`docs/governance-and-political-alignment.md`, and +`docs/repository-readme-baseline.md` before editing this repo. + +Codex output is maintainer-reviewed work. It is not an audit, certification, +security review, legal review, or endorsement by OpenAI. + ## Prompts - `00-project-context-check.md`: read repo context before changes @@ -29,6 +39,17 @@ deployment constraints. ## Standard Validation +For documentation or reusable-prompt-only changes: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +For frontend source, route, browser-flow, auth, API-client, or behavior changes: + ```bash npm run typecheck npm run lint diff --git a/codex/prompts/00-project-context-check.md b/codex/prompts/00-project-context-check.md index ec5cd28..e099219 100644 --- a/codex/prompts/00-project-context-check.md +++ b/codex/prompts/00-project-context-check.md @@ -14,19 +14,29 @@ Read relevant local files first: - `CHANGELOG.md` - `docs/README.md` - relevant `docs/` files +- `codex/README.md` +- relevant `codex/prompts/` files +- `package.json` - relevant source, route, API, auth, and test files - relevant issue or PR For backend facts, treat `open-proofline/server` as the external source of truth. Do not turn server planning docs into web-client implementation claims. +For governance, political alignment, public-good framing, public voice, +repository README structure, and source-of-truth mapping, treat +`open-proofline/website` as the external source of truth. Inspect its current +README, `docs/governance-and-political-alignment.md`, and +`docs/repository-readme-baseline.md` when those topics are involved. + ## Output Return: 1. current web-client scope 2. current frontend surfaces -3. backend assumptions that need server-doc confirmation +3. source-of-truth inputs checked, including backend or website docs when + relevant 4. security boundaries and non-goals 5. likely affected files 6. files or areas that must not change diff --git a/codex/prompts/05-codex-change-control.md b/codex/prompts/05-codex-change-control.md index b7113d9..6c54e28 100644 --- a/codex/prompts/05-codex-change-control.md +++ b/codex/prompts/05-codex-change-control.md @@ -14,16 +14,31 @@ Do **not** change code or docs unless explicitly asked. OAuth, JWT, push/SMS/Messenger notifications, public admin dashboards, mobile client code, or protocol repository behavior unless explicitly scoped. - Do not log raw tokens, Authorization headers, request bodies, plaintext, raw - keys, raw media keys, wrapped-key ciphertext, private deployment details, or - user safety data. + keys, raw media keys, wrapped-key ciphertext, verification credentials, + stored paths, object keys, private deployment details, or user safety data. - Preserve Tailwind Catalyst licensing boundaries. - Treat `open-proofline/server` as backend source of truth. +- Treat `open-proofline/website` as source of truth for public governance, + political alignment, cooperative/public-good posture, public voice, reusable + README structure, and source-of-truth mapping. ## Check Assess whether the task has a clear goal, affected files, validation commands, out-of-scope items, and a clean enough working tree. +For documentation or reusable-prompt-only tasks, prefer: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +For frontend behavior, route, auth, API-client, or browser-flow changes, use +the full web-client validation stack. + Return one of: - `Ready` diff --git a/codex/prompts/10-frontend-readability-maintenance.md b/codex/prompts/10-frontend-readability-maintenance.md index 47b6475..4f3f2f3 100644 --- a/codex/prompts/10-frontend-readability-maintenance.md +++ b/codex/prompts/10-frontend-readability-maintenance.md @@ -12,7 +12,10 @@ Improve frontend readability without changing product scope. - accessible form labels, validation, and disabled states - explicit loading, error, and empty states - no clever abstractions before they are needed -- no secret logging +- no secret logging, including raw tokens, browser session cookies, CSRF tokens, + Authorization headers, request bodies, verification credentials, paths, + object keys, plaintext, raw keys, wrapped-key ciphertext, private deployment + details, or user safety data - no browser decryption, key unwrapping, or key-handling changes - no production-readiness claims @@ -33,6 +36,7 @@ npm run typecheck npm run lint npm run test npm run build +git diff --check ``` Run Playwright only when route/browser flows change: diff --git a/codex/prompts/20-code-review.md b/codex/prompts/20-code-review.md index b3799f5..43ae56d 100644 --- a/codex/prompts/20-code-review.md +++ b/codex/prompts/20-code-review.md @@ -13,8 +13,10 @@ Do **not** add features unless needed to fix a bug. - auth/session token handling - local-storage use and warnings - accessible forms and states -- no raw token, Authorization header, request body, plaintext, key, wrapped-key - ciphertext, private deployment detail, or user safety data logging +- no raw token, browser session cookie, CSRF token, Authorization header, + request body, uploaded byte, plaintext, raw key, raw media key, contact + private key, wrapped-key ciphertext, verification credential, stored path, + object key, private deployment detail, or user safety data logging - no browser decryption or key unwrapping - no recording/capture behavior - no production-readiness claims @@ -34,4 +36,5 @@ npm run lint npm run test npm run build npm run test:e2e +git diff --check ``` diff --git a/codex/prompts/30-security-review.md b/codex/prompts/30-security-review.md index 79d0adf..2f9e0bc 100644 --- a/codex/prompts/30-security-review.md +++ b/codex/prompts/30-security-review.md @@ -15,9 +15,11 @@ public docs or issue drafts. - CSP and security-header deployment expectations - route assumptions that might expose private `/v1` or admin routes - public UI wording around emergency reliance -- no logging of raw tokens, Authorization headers, request bodies, plaintext, - raw keys, wrapped-key ciphertext, private deployment details, or user safety - data +- no logging of raw tokens, browser session cookies, CSRF tokens, + Authorization headers, request bodies, uploaded bytes, plaintext, raw keys, + raw media keys, contact private keys, wrapped-key ciphertext, verification + credentials, stored paths, object keys, private deployment details, or user + safety data - no browser decryption, key unwrapping, key escrow, recording, playable export, or emergency dispatch added incidentally - Catalyst licensing and redistribution boundaries @@ -34,6 +36,7 @@ npm run typecheck npm run lint npm run test npm run build +git diff --check ``` Run `npm run test:e2e` when browser flows changed. diff --git a/codex/prompts/40-documentation-update.md b/codex/prompts/40-documentation-update.md index 4f2493f..9687009 100644 --- a/codex/prompts/40-documentation-update.md +++ b/codex/prompts/40-documentation-update.md @@ -12,6 +12,9 @@ production readiness. - `SECURITY.md` - `CHANGELOG.md` - `docs/README.md` +- `docs/end-user-web-client-design.md` +- `docs/browser-security-headers.md` +- `docs/viewer-token-ui-design.md` - `docs/architecture.md` - `docs/api-client.md` - `docs/security-model.md` @@ -19,10 +22,15 @@ production readiness. - `docs/development.md` - `codex/README.md` - `codex/prompts/*.md` +- current `open-proofline/website` README and source docs when public voice, + governance, source-of-truth mapping, or README baseline is involved ## Constraints - Keep `open-proofline/server` as backend source of truth. +- Keep `open-proofline/website` as the source for public governance, + political alignment, cooperative/public-good posture, public voice, reusable + README structure, and source-of-truth mapping. - Do not describe unimplemented backend routes as confirmed. - Do not imply recording, browser decryption, trusted-contact decryption, key escrow, playable export, emergency dispatch, OAuth, JWT, or production safety @@ -36,8 +44,11 @@ production readiness. If only Markdown changed: ```bash -git diff --stat -git diff -- README.md AGENTS.md SECURITY.md CHANGELOG.md docs codex +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check ``` -Run frontend validation only if code changed. +Run frontend validation only if source, route, browser-flow, auth, API-client, +or behavior changed. diff --git a/codex/prompts/45-documentation-and-prompt-review.md b/codex/prompts/45-documentation-and-prompt-review.md index 1c51ae8..4031ea8 100644 --- a/codex/prompts/45-documentation-and-prompt-review.md +++ b/codex/prompts/45-documentation-and-prompt-review.md @@ -40,6 +40,14 @@ Start with current source-of-truth files: - Catalyst/Tailwind Plus license and provenance files: - `src/components/catalyst/README.md` - `src/components/catalyst/LICENSE.md` +- current project-level source documents from `open-proofline/website`, when + governance, political alignment, public-good framing, public voice, funding + posture, source mapping, or README structure is involved: + - `README.md` + - `docs/governance-and-political-alignment.md` + - `docs/repository-readme-baseline.md` + - `codex/README.md` + - relevant `codex/prompts/` Use source and test files to verify UI, API-client, route, auth/session, and documentation claims: @@ -59,6 +67,11 @@ For backend behavior, routes, deployment, and server security claims, inspect the current `open-proofline/server` source documents instead of relying on web-client assumptions. +For governance, political alignment, public-good framing, public voice, +repository README structure, and source-of-truth mapping, inspect the current +`open-proofline/website` source documents instead of duplicating project-level +claims here. + Do not rely on stale assumptions from this prompt when current docs or source code disagree. @@ -72,6 +85,7 @@ Review: - all reusable Codex prompt files - all public-facing project claims - source-of-truth alignment +- public voice and reusable README baseline alignment - technical accuracy - linguistic coherence - readability and approachability @@ -109,6 +123,8 @@ Check source-of-truth consistency: - Do docs agree with current `README.md`, `AGENTS.md`, `SECURITY.md`, and source docs? - Do backend claims match the current `open-proofline/server` docs? +- Do public-governance, political-alignment, public-good, public-voice, and + README-baseline claims match the current `open-proofline/website` docs? - Do Codex prompts agree with current repo rules? - Are public claims supported by implementation or source docs? @@ -146,6 +162,9 @@ Check readability and approachability: - Are public-facing docs understandable without internal context? - Are technical docs precise without being needlessly dense? - Is wording direct, humane, and clear? +- Does public-facing wording follow the website public voice without putting + jokes in emergency, security, implementation-status, encryption, decryption, + key-custody, or vulnerability-reporting sections? - Are acronyms and project-specific terms explained where needed? - Are there sections that sound like internal notes, legal fog, or startup hype? @@ -227,11 +246,16 @@ In edit mode: For docs-only edits, run: ```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md git diff --check -npm run format:check ``` -Run `npm run format:check` only if it is available and applicable. +Use the docs/prompt Prettier command above for docs-only review work so +unrelated source formatting drift does not block the docs report. Run +`npm run format:check` only when a repo-wide formatting check is explicitly +requested or applicable. If code changed because the maintainer explicitly scoped that work, run: diff --git a/codex/prompts/50-web-security-header-review.md b/codex/prompts/50-web-security-header-review.md index e6d603e..3d3fd3d 100644 --- a/codex/prompts/50-web-security-header-review.md +++ b/codex/prompts/50-web-security-header-review.md @@ -27,6 +27,15 @@ Document deployment expectations rather than claiming production hardening. ## Validation +For documentation-only header guidance changes: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + Run frontend validation if config or browser behavior changes: ```bash diff --git a/codex/prompts/70-work-on-github-issue.md b/codex/prompts/70-work-on-github-issue.md index 98b9306..7210376 100644 --- a/codex/prompts/70-work-on-github-issue.md +++ b/codex/prompts/70-work-on-github-issue.md @@ -14,6 +14,9 @@ Target base branch: `` - Do not create a PR unless explicitly requested. - Keep the change scoped to the issue. - Treat `open-proofline/server` as backend source of truth. +- Treat `open-proofline/website` as source of truth for public governance, + political alignment, cooperative/public-good posture, public voice, reusable + README structure, and source-of-truth mapping. - If security-sensitive, stop and say whether public issue handling is appropriate. - Do not add unrelated features or production-readiness claims. @@ -28,18 +31,32 @@ git fetch origin "" gh issue view --repo open-proofline/web-client ``` -Read `README.md`, `AGENTS.md`, `SECURITY.md`, relevant docs, source, and tests. +Read `README.md`, `AGENTS.md`, `SECURITY.md`, relevant docs, reusable prompts, +source, and tests. When the issue touches public voice, README structure, or +source-of-truth mapping, also inspect the current website source documents. Before editing, summarize issue goal, acceptance criteria, likely files, validation commands, out-of-scope items, and security sensitivity. ## Validation +For documentation or reusable-prompt-only changes: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +For frontend source, route, browser-flow, auth, API-client, or behavior changes: + ```bash npm run typecheck npm run lint npm run test npm run build +git diff --check ``` Run `npm run test:e2e` when route/browser flows change. diff --git a/codex/prompts/75-create-draft-pr-from-current-branch.md b/codex/prompts/75-create-draft-pr-from-current-branch.md index 7ab680e..6ee7a48 100644 --- a/codex/prompts/75-create-draft-pr-from-current-branch.md +++ b/codex/prompts/75-create-draft-pr-from-current-branch.md @@ -27,6 +27,18 @@ exist, the diff has unrelated changes, or the base was inferred ambiguously. ## Validation Before PR +For documentation or reusable-prompt-only branches whose issue or prompt +explicitly scopes docs-only validation: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +For frontend source, route, browser-flow, auth, API-client, or behavior changes: + ```bash npm run typecheck npm run lint diff --git a/codex/prompts/76-request-codex-pr-review.md b/codex/prompts/76-request-codex-pr-review.md index c8748fc..61dd631 100644 --- a/codex/prompts/76-request-codex-pr-review.md +++ b/codex/prompts/76-request-codex-pr-review.md @@ -29,7 +29,8 @@ consistency with README.md, AGENTS.md, SECURITY.md, and relevant docs. Focus on frontend route behavior, API client assumptions against open-proofline/server, token handling, no secret logging, no browser decryption -or key unwrapping, Catalyst licensing boundaries, and validation results. +or key unwrapping, Catalyst licensing boundaries, website-source alignment for +public voice/governance/README baseline claims, and validation results. ``` Do not merge, approve, or mark ready for review. diff --git a/codex/prompts/80-backlog-scan-issue-drafts.md b/codex/prompts/80-backlog-scan-issue-drafts.md index e6b60cf..8a2ff09 100644 --- a/codex/prompts/80-backlog-scan-issue-drafts.md +++ b/codex/prompts/80-backlog-scan-issue-drafts.md @@ -14,6 +14,8 @@ Do **not** change application code. Do **not** create GitHub issues directly. - `README.md`, `AGENTS.md`, `SECURITY.md`, `CHANGELOG.md` - `docs/` +- current `open-proofline/website` README and source docs when public voice, + governance, source-of-truth mapping, or README baseline gaps are candidates - `src/api`, `src/auth`, `src/routes`, `src/components` - `tests/` - `.github/workflows` @@ -23,9 +25,10 @@ Do **not** change application code. Do **not** create GitHub issues directly. ## Candidate Areas Correctness, security hardening, accessibility, frontend testing gaps, -documentation gaps, deployment/header guidance, dependency review, API route -confirmation against `open-proofline/server`, Catalyst licensing hygiene, and -Codex workflow improvements. +documentation gaps, public voice or README-baseline drift, deployment/header +guidance, dependency review, API route confirmation against +`open-proofline/server`, website source alignment for project-level claims, +Catalyst licensing hygiene, and Codex workflow improvements. Never include raw tokens, secrets, exploit details, private deployment details, or user safety data in public issue drafts. diff --git a/codex/prompts/81-backlog-drafts-structure-and-hygiene.md b/codex/prompts/81-backlog-drafts-structure-and-hygiene.md index 0a20b3f..e20d02b 100644 --- a/codex/prompts/81-backlog-drafts-structure-and-hygiene.md +++ b/codex/prompts/81-backlog-drafts-structure-and-hygiene.md @@ -26,6 +26,9 @@ Do **not** change application code. Do **not** create or close GitHub issues. Every public draft should include the `backlog` label and at least one topic label. Private notes must not be used for public issue creation. +Public drafts must not include raw tokens, secrets, exploit details, private +deployment details, request bodies, plaintext, raw keys, wrapped-key +ciphertext, stored paths, object keys, or user safety data. Validate with: diff --git a/codex/prompts/82-review-open-issues-for-stale-or-fixed.md b/codex/prompts/82-review-open-issues-for-stale-or-fixed.md index 4538e11..b43f264 100644 --- a/codex/prompts/82-review-open-issues-for-stale-or-fixed.md +++ b/codex/prompts/82-review-open-issues-for-stale-or-fixed.md @@ -24,6 +24,9 @@ requested. - `sensitive-do-not-publicly-discuss` Distinguish current-branch fixes from merged target-branch fixes. +For issues involving public voice, governance, README baseline, or +source-of-truth mapping, verify against current `open-proofline/website` +documents before marking them stale or fixed. Validation: diff --git a/codex/prompts/90-release-check.md b/codex/prompts/90-release-check.md index 0025712..05af94a 100644 --- a/codex/prompts/90-release-check.md +++ b/codex/prompts/90-release-check.md @@ -16,6 +16,8 @@ Target final base branch: `` - README, AGENTS, SECURITY, CHANGELOG, LICENSE - docs accuracy and links - API route assumptions against `open-proofline/server` +- public voice, governance, README baseline, and source-of-truth mapping + assumptions against `open-proofline/website` - no production-readiness claims - no recording, browser decryption, key escrow, playable export, emergency dispatch, OAuth, JWT, public admin dashboard, mobile code, or protocol @@ -29,6 +31,7 @@ Target final base branch: `` ```bash npm ci +npm run format:check npm run typecheck npm run lint npm run test diff --git a/codex/prompts/95-validate-deep-research-report.md b/codex/prompts/95-validate-deep-research-report.md index d9c0ebd..a7229de 100644 --- a/codex/prompts/95-validate-deep-research-report.md +++ b/codex/prompts/95-validate-deep-research-report.md @@ -25,6 +25,9 @@ Issue handling mode: `drafts_only`, `create_issues`, or `none` - Pin citations and report metadata to the reviewed commit. - Treat `open-proofline/server` as backend source of truth. +- Treat `open-proofline/website` as source of truth for public governance, + political alignment, public voice, reusable README structure, and + source-of-truth mapping. - Separate current implementation from future design. - Keep public wording safe under `SECURITY.md`. - Do not include raw tokens, secrets, exploit details, private deployment @@ -37,8 +40,10 @@ Issue handling mode: `drafts_only`, `create_issues`, or `none` If docs only: ```bash -git diff --stat -git diff -- docs .backlog-drafts +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check ``` If code changed unexpectedly, stop and explain why. diff --git a/docs/README.md b/docs/README.md index 35fb7d3..4beb13e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,17 @@ # Proofline Web Client Docs These docs describe the current experimental web-client prototype. The backend -source of truth remains `open-proofline/server`. +source of truth remains `open-proofline/server`. Project-wide public +governance, political alignment, public voice, and reusable README baseline +guidance live in `open-proofline/website`. + +Use the right source for the claim: + +- web-client behavior and prototype limits: this repository and these docs +- backend API, auth, deployment, billing-placeholder, and security facts: + `open-proofline/server` +- public governance, cooperative/public-good posture, public voice, and README + structure: `open-proofline/website` - [Architecture](architecture.md) - [End-user web-client design](end-user-web-client-design.md): product @@ -23,4 +33,5 @@ source of truth remains `open-proofline/server`. - [Development](development.md) The prototype does not implement recording, browser decryption, key escrow, -playable media export, emergency dispatch, or production safety workflows. +playable media export, emergency dispatch, hosted billing, notification +delivery, public admin/operator surfaces, or production safety workflows. diff --git a/docs/api-client.md b/docs/api-client.md index 3676a84..dbcdf88 100644 --- a/docs/api-client.md +++ b/docs/api-client.md @@ -37,6 +37,15 @@ From current `open-proofline/server` docs and route registration: - `GET /v1/auth/web/csrf` - `GET /v1/account` - `POST /v1/account/password` +- `POST /v1/account/second-factor/email/challenge` +- `POST /v1/account/second-factor/email/verify` +- `POST /v1/account/second-factor/totp/enroll` +- `POST /v1/account/second-factor/totp/confirm` +- `POST /v1/account/second-factor/totp/verify` +- `POST /v1/account/second-factor/webauthn/register/start` +- `POST /v1/account/second-factor/webauthn/register/finish` +- `POST /v1/account/second-factor/webauthn/verify/start` +- `POST /v1/account/second-factor/webauthn/verify/finish` - `POST /v1/incidents` - `GET /v1/incidents` - `GET /v1/incidents/{incident_id}` @@ -79,6 +88,13 @@ The UI maps password-change failures to fixed safe messages and does not log or persist passwords, request bodies, session tokens, Authorization headers, browser session cookies, or CSRF token values. +Current server docs also describe account second-factor setup and per-session +verification routes for email challenge, TOTP, and WebAuthn. This web client +does not yet implement second-factor setup, challenge, verification, or recovery +UI, and the current account schema does not retain server second-factor setup +metadata. Add those flows only through a dedicated account-security design and +full frontend validation. + ## Viewer Token UI Boundary Current `open-proofline/server` documents authenticated owner-scoped diff --git a/docs/architecture.md b/docs/architecture.md index 3de181c..e8d9d66 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -15,6 +15,9 @@ flowchart LR - The app handles account login, public registration, email verification, account profile/password management, and incident metadata review. +- The app does not implement account second-factor setup, challenge, + verification, or recovery UI yet; current second-factor route support remains + a server-side fact to verify against `open-proofline/server`. - The live API client supports explicit bearer-token and browser-cookie auth modes. Cookie mode uses server-managed HttpOnly cookies, in-memory CSRF tokens, and `credentials: "include"` only for cookie-authenticated requests. @@ -26,6 +29,11 @@ flowchart LR `open-proofline/server` remains the source of truth for backend routes, authorization, encrypted bundle behavior, and security headers. +`open-proofline/website` remains the source of truth for Proofline public +governance, cooperative/public-good posture, public voice, and reusable README +structure. Keep those project-level claims linked instead of duplicating them +in architecture docs. + ## Product Design Boundary [End-user web-client design](end-user-web-client-design.md) defines the product diff --git a/docs/development.md b/docs/development.md index ef121a1..fc2b106 100644 --- a/docs/development.md +++ b/docs/development.md @@ -12,7 +12,17 @@ Run locally: npm run dev ``` -Validation: +Validation for documentation or reusable-prompt-only changes: + +```bash +npx prettier --check \ + README.md AGENTS.md SECURITY.md CHANGELOG.md \ + docs/*.md codex/*.md codex/prompts/*.md +git diff --check +``` + +Validation for frontend source, route, browser-flow, auth, API-client, or +behavior changes: ```bash npm run typecheck diff --git a/docs/end-user-web-client-design.md b/docs/end-user-web-client-design.md index 31b5ac1..8dbff0d 100644 --- a/docs/end-user-web-client-design.md +++ b/docs/end-user-web-client-design.md @@ -66,13 +66,13 @@ testing path, or secondary capture method. The product design must keep current, prototype, backend-supported, planned, and not-implemented behavior separate. -| Category | Current design truth | -| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Implemented in this web client today | Login/logout, registration form, email verification route, account overview, account profile/password change, incident list/detail metadata review, contact public-key metadata management, sharing-grant metadata management, wrapped-key metadata review and revocation, deletion request UI, mock mode, bearer and cookie auth client modes. | -| Implemented in prototype/mock mode | Sample account and incident records for local testing. Mock mode does not create accounts, send email, verify real tokens, model billing, or prove backend behavior. | -| Live backend supported by current server docs | Local account sessions, configurable registration, email verification, browser-cookie auth and CSRF when enabled, owner-scoped incident list/detail routes, contact public-key metadata, owner-scoped sharing grants, wrapped-key metadata, viewer-token create/revoke routes, token-scoped server-rendered viewer routes, encrypted bundle downloads. | -| Planned or design-only | End-user language overhaul, invite/accept trusted-contact flows, automatic client-managed contact key creation, web-client no-account viewer, map/location presentation, browser capture fallback, durable viewer-link management, payment-backed account lifecycle, notification delivery, trusted-contact account access. | -| Not implemented and not implied | Emergency dispatch, guaranteed emergency response, production safety infrastructure, backend decryption, browser decryption, trusted-contact decryption, key escrow, raw server-held media keys, break-glass access, playable export, public admin dashboard, OAuth, JWT, push/SMS/Messenger notifications, production billing. | +| Category | Current design truth | +| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Implemented in this web client today | Login/logout, registration form, email verification route, account overview, account profile/password change, incident list/detail metadata review, contact public-key metadata management, sharing-grant metadata management, wrapped-key metadata review and revocation, deletion request UI, mock mode, bearer and cookie auth client modes. | +| Implemented in prototype/mock mode | Sample account and incident records for local testing. Mock mode does not create accounts, send email, verify real tokens, model billing, or prove backend behavior. | +| Live backend supported by current server docs | Local account sessions, configurable registration, email verification, browser-cookie auth and CSRF when enabled, account second-factor setup and per-session verification routes, owner-scoped incident list/detail routes, contact public-key metadata, owner-scoped sharing grants, wrapped-key metadata, viewer-token create/revoke routes, token-scoped server-rendered viewer routes, encrypted bundle downloads. | +| Planned or design-only | End-user language overhaul, account second-factor setup UX, invite/accept trusted-contact flows, automatic client-managed contact key creation, web-client no-account viewer, map/location presentation, browser capture fallback, durable viewer-link management, payment-backed account lifecycle, notification delivery, trusted-contact account access. | +| Not implemented and not implied | Emergency dispatch, guaranteed emergency response, production safety infrastructure, backend decryption, browser decryption, trusted-contact decryption, key escrow, raw server-held media keys, break-glass access, playable export, public admin dashboard, OAuth, JWT, push/SMS/Messenger notifications, production billing. | ## Audiences diff --git a/docs/security-model.md b/docs/security-model.md index f67ce0c..6d685a2 100644 --- a/docs/security-model.md +++ b/docs/security-model.md @@ -48,6 +48,20 @@ persisted in browser storage, screenshotted, copied into public issue drafts, included in analytics, or exposed in UI beyond the transient browser URL fragment needed to complete verification. +## Account Second-Factor Boundary + +Current `open-proofline/server` docs describe account second-factor setup and +per-session verification routes for email challenge, TOTP, and WebAuthn. This +web client does not yet implement second-factor setup, challenge, verification, +or recovery UI, and it does not retain server second-factor setup metadata in +frontend account state. + +Future second-factor UI needs its own account-security design before exposing +challenge codes, TOTP seeds, WebAuthn ceremony material, or recovery states in +the browser. Those values must not be logged, persisted outside the intended +browser ceremony, copied into public issues, sent to analytics, or mixed with +unrelated account metadata displays. + ## Viewer Token Boundary Viewer tokens are bearer secrets for no-account, read-only incident access. diff --git a/package-lock.json b/package-lock.json index fadc8bc..109a494 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4764,9 +4764,9 @@ } }, "node_modules/undici": { - "version": "7.26.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.26.0.tgz", - "integrity": "sha512-3O9Tf67pGhgOv9jM35AbhkXAKi13f3oy3aE4CSgr+TckGeY+/iu97ZXN+J7DpHPzLbVApFd1IFhcnBjREYXYcg==", + "version": "7.28.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.28.0.tgz", + "integrity": "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==", "dev": true, "license": "MIT", "engines": { @@ -4841,9 +4841,9 @@ } }, "node_modules/vite": { - "version": "8.0.15", - "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.15.tgz", - "integrity": "sha512-qpgllRxrLqwsMAGRdLhsEr9bepaOQk1rxH1xT2coBXLaEB/bfkqQj1j7RMxwMfnYrvO1ZnFMiwX+wBVgnsyn0g==", + "version": "8.0.16", + "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.16.tgz", + "integrity": "sha512-h9bXPmJichP5fLmVQo3PyaGSDE2n3aPuomeAlVRm0JLmt4rY6zmPKd59HYI4LNW8oTK7tlTsuC7l/m7awx9Jcw==", "license": "MIT", "dependencies": { "lightningcss": "^1.32.0",