From 3c5bb27f5904a49ae24fcddd11181346127c9f08 Mon Sep 17 00:00:00 2001 From: Ellie Melton Date: Fri, 19 Jun 2026 20:51:04 +1000 Subject: [PATCH] Refresh README docs and Codex workflows --- AGENTS.md | 15 +- README.md | 292 ++++++++++++++---- SECURITY.md | 4 +- codex/README.md | 24 +- codex/prompts/00-project-context-check.md | 5 + codex/prompts/05-codex-change-control.md | 5 + ...-codex-structure-and-naming-maintenance.md | 8 + codex/prompts/40-documentation-update.md | 9 + .../45-documentation-and-prompt-review.md | 12 + codex/prompts/70-work-on-github-issue.md | 5 + .../75-create-draft-pr-from-current-branch.md | 3 + codex/prompts/76-request-codex-pr-review.md | 8 +- codex/prompts/80-backlog-scan-issue-drafts.md | 8 + codex/prompts/90-release-check.md | 7 + .../95-validate-deep-research-report.md | 13 +- docs/README.md | 25 +- docs/api.md | 15 +- docs/architecture.md | 35 ++- docs/browser-decryption.md | 4 +- docs/code-map.md | 10 +- docs/codex-change-control.md | 4 + docs/configuration.md | 2 +- docs/deployment.md | 7 +- docs/development.md | 5 + docs/incident-modes.md | 6 +- docs/public-web-client-deployment-boundary.md | 8 +- .../phase-0-deep-research-preflight.md | 28 +- .../phase-1-deep-research-technical-review.md | 48 ++- docs/security-model.md | 4 +- docs/stripe-subscription-billing.md | 3 +- docs/threat-model.md | 3 +- docs/v1-access-control.md | 7 +- docs/v1-preview-direction.md | 2 +- docs/web-client-viewer-routing.md | 2 +- 34 files changed, 513 insertions(+), 123 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cb0a417..f5684d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,11 @@ - Preserve the current deployment model: main `/v1` behind the reviewed localhost/LAN/WireGuard/firewall boundary, private `/admin` behind its own private listener, and only read-only incident viewer paths behind HTTPS/reverse proxy when exposed. - Separate bind addresses are a deployment boundary, not a complete security model. - Treat Codex prompts as scoped change requests, not open-ended permission to expand the project. +- Treat the website repository as the project-level source of truth for public + governance posture, political alignment, public-good framing, public voice, + README baseline style, and source-of-truth mapping. Server docs should link + to those website source documents instead of re-declaring project-wide + posture differently. - Do not implement newly discovered future work during an unrelated task; document it as an issue/backlog item instead. - For larger changes, start from a clean working tree or an explicit checkpoint commit. - Backlog scanning should create draft Markdown files first, not GitHub issues directly. @@ -38,7 +43,12 @@ - This repository is the Go server backend component only. - Current organisation: `open-proofline`. - Current server repository: `open-proofline/server`. -- Planned future companion repositories: `open-proofline/web-client`, `open-proofline/ios-client`, `open-proofline/android-client`, and `open-proofline/protocol`. +- Current companion repositories include `open-proofline/website` and + `open-proofline/web-client`. +- Planned future companion repositories include `open-proofline/ios-client`, + `open-proofline/android-client`, and `open-proofline/protocol`. +- Project-wide public governance posture and reusable README baseline guidance + live in `open-proofline/website`. - The Go module path is `github.com/open-proofline/server` at the repository root, release binaries use `proofline-server-*` names, and the published GHCR image is `ghcr.io/open-proofline/server`. - Current runtime protocol and default data-layout identifiers use Proofline names. Historical reports and archived prompts may still mention earlier `safety-recorder` identifiers. - SQLite metadata by default. @@ -91,6 +101,9 @@ Before accepting Codex changes, check: - wrapped-key ciphertext, private deployment details, stored paths, object keys, and user safety data are not logged - ZIP downloads use safe headers and controlled paths - documentation still matches `README.md` +- public-facing docs still link to the website governance/README-baseline + source documents when making project-wide public posture or public voice + claims - future web, iOS, Android, or protocol work was not accidentally added to this server repository - key custody/decryption changes are explicit and security-reviewed - no public-production readiness is implied unless deployment hardening has actually been implemented diff --git a/README.md b/README.md index 73cb215..645f265 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,74 @@ # Proofline Server -[![CI](https://github.com/open-proofline/server/actions/workflows/ci.yml/badge.svg)](https://github.com/open-proofline/server/actions/workflows/ci.yml) -[![Latest Tag](https://img.shields.io/github/v/tag/open-proofline/server?sort=semver)](https://github.com/open-proofline/server/tags) -[![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](LICENSE) -[![Go Version](https://img.shields.io/badge/go-1.26.4-00ADD8?logo=go&logoColor=white)](go.mod) -[![Status: Experimental](https://img.shields.io/badge/status-experimental-orange.svg)](#security-warning) -[![Security Policy](https://img.shields.io/badge/security-policy-blue.svg)](SECURITY.md) -[![GHCR](https://img.shields.io/static/v1?label=GHCR&message=ghcr.io%2Fopen-proofline%2Fserver&color=blue&logo=github)](https://github.com/orgs/open-proofline/packages/container/package/server) -[![Relay GHCR](https://img.shields.io/static/v1?label=Relay%20GHCR&message=ghcr.io%2Fopen-proofline%2Fstream-ingress&color=blue&logo=github)](https://github.com/orgs/open-proofline/packages/container/package/stream-ingress) - -Proofline Server is the experimental Go server backend for encrypted incident capture. It receives already-encrypted recording chunks through authenticated main `/v1` routes, stores metadata in SQLite by default or optional PostgreSQL, keeps encrypted blobs on local disk by default or in optional S3-compatible object storage, enforces default local staging and account-scoped committed blob quotas, serves a private admin dashboard under `/admin`, uses optional Valkey/Redis-compatible coordination for startup checks, route-class counters, and short-lived complete-upload leases when explicitly configured, supports optional browser cookie sessions for a future web client, supports disabled-by-default configurable account registration with SMTP-backed email verification for open self-hosted registration, supports email challenge, TOTP, and disabled-by-default WebAuthn/FIDO2 passkey or roaming security-key second-factor setup for account gating, supports private-admin assisted second-factor reset for lost-factor recovery, and exposes a token-scoped read-only viewer for incident review. - -> Repository role: this repository is the server/backend component only. In the multi-repo layout it is `open-proofline/server`, not the full Proofline product suite. -> -> Artifact note: the Go module path is `github.com/open-proofline/server`, the main server GHCR image is `ghcr.io/open-proofline/server`, the stream-ingress relay GHCR image is `ghcr.io/open-proofline/stream-ingress`, and release binaries use `proofline-server-*` names. Current runtime protocol and default data-layout identifiers use Proofline names. Historical reports and archived prompts may still mention earlier `safety-recorder` identifiers. - -## Security Warning - -> This project is not production-ready public infrastructure. The main `/v1` API now requires local account sessions for product routes and uses app-level route-class rate limits, so it is no longer an unauthenticated control plane. Broad public exposure still needs route-by-route deployment review, TLS, edge abuse controls, browser credential review, logging review, proxy hardening, and operational testing. Configurable public self-registration is disabled by default; enabling open registration adds only email-verified account creation and does not by itself approve broad public `/v1` exposure. Optional browser cookie sessions add CSRF checks and configured credentialed CORS for future web-client use, but they also need reviewed deployment rules. Existing `/admin/api/...` JSON routes are mounted only on the private-admin listener and require authenticated admin sessions with completed admin second-factor setup and active-factor verification when email challenge, TOTP, or WebAuthn is active. The private-admin listener also serves the `/admin` dashboard surface and must stay behind localhost, LAN, WireGuard, a firewall, or a strict reverse proxy. Separate bind addresses are a deployment boundary, not a complete security model. -> -> Public web-client deployments must follow the reviewed route, CORS, CSRF, -> cookie, cache, edge, and logging boundary in -> [docs/public-web-client-deployment-boundary.md](docs/public-web-client-deployment-boundary.md). - -## What It Is - -This repository currently contains the Go server backend only. It does not -contain the web client, iOS client, Android client, protocol repository, -account portal, production recording client, or mobile app code. The simulator -may capture or encode local test segments for backend reference flows only. - -The intended long-term Proofline product is broader than emergency-only recording: it should support private encrypted incident capture for emergencies, non-emergency interaction records, timed safety checks, and evidence notes. - -Future client repositories are expected to record audio/video and supporting metadata in short chunks, encrypt them locally, and upload them continuously so already-uploaded evidence is retained if a phone is lost, damaged, powered off, or taken. - -Evidence bundles are ZIP files containing encrypted chunks and JSON manifests. They are not decrypted, playable, or merged media exports. +

+ CI + Go 1.26.4 + License: AGPL-3.0-only + Status: Experimental + Security policy + Support Proofline + Latest tag + GHCR server image + GHCR stream-ingress image +

+ +Proofline is experimental public-interest open-source privacy and evidence +infrastructure. This repository contains the Go server backend for encrypted +incident capture: authenticated `/v1` routes, private admin surfaces, metadata +and encrypted blob storage, encrypted bundle generation, deployment docs, and +server release workflow. + +Proofline is not an emergency service, emergency dispatch system, +emergency-services integration, staffed response center, or guaranteed +real-time response system. + +## Current Status + +This repository is experimental and maintainer-led. It is not production-ready +public infrastructure or production-ready emergency infrastructure. + +Current server status: + +- Go module: `github.com/open-proofline/server` +- Main server image: `ghcr.io/open-proofline/server` +- Stream-ingress relay image: `ghcr.io/open-proofline/stream-ingress` +- Release binaries: `proofline-server-*` +- Default metadata backend: SQLite +- Optional metadata backend: PostgreSQL +- Default blob backend: local disk +- Optional committed-blob backend: S3-compatible object storage +- Optional coordination backend: Valkey/Redis-compatible coordination +- Main listener: authenticated `/v1` routes, read-only incident viewer, and + token-neutral viewer assets +- Private-admin listener: `/admin`, `/admin/...`, `/admin/api/...`, and + token-neutral admin assets + +Current runtime protocol and default data-layout identifiers use Proofline +names. Historical reports and archived prompts may still mention earlier +`safety-recorder` identifiers. + +## What This Repository Is + +`open-proofline/server` is the server/backend component of Proofline. It is +responsible for: + +- receiving already-encrypted recording chunks through authenticated main + `/v1` routes +- storing metadata in SQLite by default or optional PostgreSQL +- storing encrypted blobs on local disk by default or optional S3-compatible + object storage +- enforcing local temp-staging and account-scoped committed blob quotas +- serving the private admin web surface under `/admin` +- serving admin JSON routes only under the private-admin listener at + `/admin/api/...` +- exposing a token-scoped read-only incident viewer for current local/prototype + review +- generating encrypted ZIP evidence bundles with server-controlled entry names +- publishing the main server and stream-ingress relay images +- documenting server deployment, security, and release workflow + +Evidence bundles are ZIP files containing encrypted chunks and JSON manifests. +They are not decrypted, playable, or merged media exports. The simulator encrypts generated chunks by default with the accepted post-quantum envelope (`ML-KEM-768 + HKDF-SHA384 + AES-256-GCM`), can stage @@ -44,24 +78,128 @@ Keys remain client-side and are not uploaded to the backend. Future production key custody is expected to use a hybrid trusted-contact model; see [docs/key-custody.md](docs/key-custody.md). -Planned production-cluster work is additive. SQLite metadata and local filesystem blob storage remain supported. Optional PostgreSQL metadata, S3-compatible object storage, and Valkey/Redis-compatible coordination are available only when explicitly configured. Complete-upload idempotency is implemented through metadata-backed upload-operation state, and Valkey can hold short-lived complete-upload leases and retry hints when configured. Resumable or partial-upload protocols remain future work. See [docs/production-cluster-scope.md](docs/production-cluster-scope.md). +Planned production-cluster work is additive. SQLite metadata and local +filesystem blob storage remain supported. Optional PostgreSQL metadata, +S3-compatible object storage, and Valkey/Redis-compatible coordination are +available only when explicitly configured. Complete-upload idempotency is +implemented through metadata-backed upload-operation state, and Valkey can hold +short-lived complete-upload leases and retry hints when configured. Resumable or +partial-upload protocols remain future work. See +[docs/production-cluster-scope.md](docs/production-cluster-scope.md). + +## What This Repository Is Not + +This repository is not: + +- the static public website +- the React web client or account portal +- an iOS app +- an Android app +- a protocol implementation or shared conformance test suite +- 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 + +Do not add web-client, iOS-client, Android-client, protocol, recording/capture, +notification, hosted-account billing, payment-gated access, decryption, key +escrow, playable export, or public admin/operator behavior here unless the +maintainer explicitly changes the repository strategy. + +## Source-Of-Truth Map + +Use the right source for the claim: + +| Topic | Read | +|---|---| +| Server behavior, API, deployment, and security facts | This repository: `README.md`, `SECURITY.md`, and [docs/](docs/README.md) | +| Server v1 preview direction and current/future boundaries | [docs/v1-preview-direction.md](docs/v1-preview-direction.md), [docs/v1-preview-readiness-checklist.md](docs/v1-preview-readiness-checklist.md) | +| Server Codex workflows | [codex/README.md](codex/README.md), [codex/prompts/](codex/prompts/) | +| 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) | +| Web-client behavior and prototype limits | [`open-proofline/web-client`](https://github.com/open-proofline/web-client) | -## Open Proofline Repository Roles +Keep repository-specific facts in the repository that owns them. Keep +project-wide governance posture in the website repository. -The current organisation is `open-proofline`, with current and planned -responsibilities split across repositories: +## Project Map -| Repository | Responsibility | -|---|---| -| `open-proofline/server` | Go backend, main API, private admin web surface, read-only incident viewer, storage, migrations, deployment docs, and server release workflow. | -| `open-proofline/web-client` | Account portal, authorised incident review, trusted-contact access, and eventual replacement for the current token-only viewer. | -| `open-proofline/ios-client` | iOS incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | -| `open-proofline/android-client` | Android incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | -| `open-proofline/protocol` | Shared API specs, encryption envelope specs, bundle manifests, compatibility matrix, and conformance tests. | - -This repository should remain scoped to the server/backend role. Product-level -or client-specific work should be documented here only as planning context until -the relevant separate repository scope is ready. +| Repository | Status | Role | +|---|---|---| +| [`open-proofline/website`](https://github.com/open-proofline/website) | Current, experimental | Static public website, public framing, governance posture, README baseline, and website Codex workflows. | +| [`open-proofline/server`](https://github.com/open-proofline/server) | Current, experimental | Go backend, authenticated main API, private admin web surface, read-only incident viewer, storage, migrations, deployment docs, and server release workflow. | +| [`open-proofline/web-client`](https://github.com/open-proofline/web-client) | Current, experimental | React account portal and incident-review prototype for account flows and metadata review. It is not a recorder, emergency workflow, production decryption client, or production account portal. | +| `open-proofline/ios-client` | Planned | Future native iOS incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | +| `open-proofline/android-client` | Planned | Future native Android incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | +| `open-proofline/protocol` | Planned | Future shared API specs, encryption envelope specs, bundle manifests, compatibility matrix, and conformance tests. | + +Planned repositories should not be described as implemented until they exist and +their scope is documented. + +## Safety And Deployment Boundaries + +This project is not production-ready public infrastructure. The main `/v1` API +requires local account sessions for product routes and uses app-level route +class rate limits, but broad public exposure still needs route-by-route +deployment review, TLS, edge abuse controls, browser credential review, logging +review, proxy hardening, and operational testing. + +Configurable public self-registration is disabled by default. Enabling open +registration adds only email-verified account creation and does not by itself +approve broad public `/v1` exposure. Optional browser cookie sessions add CSRF +checks and configured credentialed CORS for future production web-client use, +but they also need reviewed deployment rules. + +Existing `/admin/api/...` JSON routes are mounted only on the private-admin +listener and require authenticated admin sessions with completed admin +second-factor setup and active-factor verification when email challenge, TOTP, +or WebAuthn is active. The private-admin listener also serves the `/admin` +dashboard surface and must stay behind localhost, LAN, WireGuard, a firewall, +or a strict reverse proxy. Separate bind addresses are a deployment boundary, +not a complete security model. + +Public web-client deployments must follow the reviewed route, CORS, CSRF, +cookie, cache, edge, and logging boundary in +[docs/public-web-client-deployment-boundary.md](docs/public-web-client-deployment-boundary.md). + +## Public Claim Boundaries + +Do not imply that this repository currently provides: + +- production readiness +- emergency dispatch or emergency-services integration +- guaranteed response +- a staffed response center +- production mobile capture +- trusted-contact notifications +- live context sharing +- backend, browser, or trusted-contact decryption +- raw server-held media keys +- key escrow +- hosted-account billing, subscriptions, or payment-gated access as live + behavior +- public production admin/operator surfaces +- legal admissibility or legal reliability + +## 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). + +Donations and contributions do not create accounts, unlock features, provide +support priority, or provide emergency assistance. ## Planned Incident Modes @@ -194,11 +332,11 @@ escrow. - Docker image builds and GitHub Actions / GHCR publishing for the main server image and the stream-ingress relay image -## What It Is Not Yet +## What Is Not Implemented Here - No iOS app - No Android app -- No implemented web client or account portal +- No web client or account portal in this repository - No protocol repository or shared conformance test suite - No production recording client implementation - No mode-driven incident access, notification, retention, key-custody, or @@ -358,6 +496,29 @@ inside the container; local Compose relay smoke remains loopback-bound and does not make the relay or the main `/v1` API production-ready public infrastructure. +## Validation + +For docs-only changes: + +```bash +scripts/check-markdown-links.py +git diff --check +``` + +For Go code changes: + +```bash +gofmt -w ./cmd ./internal ./migrations +go test ./... +go vet ./... +git diff --check +``` + +Go tests are not required for docs-only changes unless code changed. Do not use +`v1 preview`, `v1.0.0`, or real-user evidence-upload readiness language unless +[docs/v1-preview-readiness-checklist.md](docs/v1-preview-readiness-checklist.md) +has been run and every applicable blocker is satisfied. + ## Documentation - [Docs index](docs/README.md) @@ -426,15 +587,38 @@ Only after review, use `85-create-github-issues-from-drafts.md` to generate `scr Do not let Codex create GitHub issues directly during the initial scan. +## Security Reporting + +Do not report security vulnerabilities through public GitHub issues. Use +GitHub private vulnerability reporting for this repository, and see +[SECURITY.md](SECURITY.md) for supported versions, scope, and handling +expectations. + ## Security Viewer links, `/v1` bearer session tokens, and browser session cookies are credentials and should be treated as secrets. Browser cookie mode should use HttpOnly Secure cookies, explicit allowed origins, `credentials: "include"`, and CSRF headers for unsafe requests; browser token persistence should not use localStorage in production. Public deployment still needs TLS, rate limiting, log review, proxy hardening, operational testing, and deployment-specific retention, backup, and deletion enforcement. Do not route `/v1` as an unreviewed public catch-all; expose only explicitly reviewed route groups, and keep `/admin/api/...` and `/admin` off public edges. -Please see [SECURITY.md](SECURITY.md) for supported versions and vulnerability reporting guidance. Do not report security vulnerabilities through public GitHub issues. +Do not publish raw viewer tokens, incident tokens, idempotency keys, request +bodies, uploaded bytes, plaintext, raw keys, wrapped-key ciphertext, stored +paths, object keys, private deployment details, exploit details, or user safety +data in public docs, prompts, issue bodies, logs, screenshots, or examples. + +## Release And Deployment Notes + +GitHub Actions build and publish the main server image and stream-ingress relay +image for trusted branches and version tags. Release binaries use +`proofline-server-*` names. See [CHANGELOG.md](CHANGELOG.md) for release notes +and [docs/deployment.md](docs/deployment.md) for deployment guidance. + +Release or deployment tooling does not make Proofline production-ready public +infrastructure. Treat any broad public `/v1`, public web-client, or hosted +service deployment as a separate reviewed deployment task. ## Roadmap -- Create future `open-proofline/web-client`, `open-proofline/ios-client`, `open-proofline/android-client`, and `open-proofline/protocol` repositories when their scopes are ready +- Keep web-client work in `open-proofline/web-client`, and create future + `open-proofline/ios-client`, `open-proofline/android-client`, and + `open-proofline/protocol` repositories when their scopes are ready - Plan any future protocol or data-layout compatibility migrations separately from the completed repository/module/artifact rename - Continue hardening optional PostgreSQL metadata support while preserving SQLite local/default support - Complete the remaining cluster-safe upload operation semantics before multi-node production deployment diff --git a/SECURITY.md b/SECURITY.md index 992b2bb..e250503 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ # Security Policy -Proofline is a private encrypted incident-capture backend. It is not production-ready public infrastructure. The main `/v1` API uses local account sessions, optional browser cookie sessions for future web-client calls, email challenge, TOTP, disabled-by-default WebAuthn/FIDO2 second-factor setup for new account gating, private-admin assisted second-factor reset for lost-factor recovery, and app-level route-class rate limits. Broad public `/v1` exposure still needs route-by-route deployment review, TLS, edge abuse controls, browser credential review, logging review, proxy hardening, and operational testing. Private-admin `/admin/api/...` JSON routes and the private `/admin` web surface require admin authentication, completed admin second-factor setup, active-factor session verification when email challenge, TOTP, or WebAuthn is active, and must stay behind localhost, WireGuard, a firewall, or an equivalent private boundary. The private admin web display and validation boundary is documented in [docs/private-admin-web-scope.md](docs/private-admin-web-scope.md). +Proofline is a private encrypted incident-capture backend. It is not production-ready public infrastructure. The main `/v1` API uses local account sessions, optional browser cookie sessions for future production web-client calls, email challenge, TOTP, disabled-by-default WebAuthn/FIDO2 second-factor setup for new account gating, private-admin assisted second-factor reset for lost-factor recovery, and app-level route-class rate limits. Broad public `/v1` exposure still needs route-by-route deployment review, TLS, edge abuse controls, browser credential review, logging review, proxy hardening, and operational testing. Private-admin `/admin/api/...` JSON routes and the private `/admin` web surface require admin authentication, completed admin second-factor setup, active-factor session verification when email challenge, TOTP, or WebAuthn is active, and must stay behind localhost, WireGuard, a firewall, or an equivalent private boundary. The private admin web display and validation boundary is documented in [docs/private-admin-web-scope.md](docs/private-admin-web-scope.md). The current implementation supports generic incident capture, optional incident-mode metadata fields, and token-scoped read-only incident review. @@ -75,7 +75,7 @@ Reports are in scope when they affect the current backend, documentation, or dep The following are generally out of scope unless they demonstrate a concrete vulnerability in this repository: -- missing features already documented as absent, such as public account workflows, OAuth, JWT, SMS, push notifications, trusted-contact accounts, Android/iOS clients, a web client, mode-driven escalation behavior, or a public admin dashboard +- missing features already documented as absent, such as public account workflows, OAuth, JWT, SMS, push notifications, trusted-contact accounts, Android/iOS clients, web-client implementation in this server repository, mode-driven escalation behavior, or a public admin dashboard - lack of production hardening already documented as a known limitation, without a new exploit path - reports requiring unreviewed broad public exposure of main `/v1` route groups contrary to documented deployment guidance - denial-of-service reports based only on unrealistic local access or unbounded physical access diff --git a/codex/README.md b/codex/README.md index ed7f61c..0033ebb 100644 --- a/codex/README.md +++ b/codex/README.md @@ -1,9 +1,23 @@ # Codex Prompts -This directory records the Codex prompt workflow used for AI-assisted development. +This directory records the Codex prompt workflow used for AI-assisted +development in `open-proofline/server`. Codex output is treated as maintainer-reviewed work, not as endorsement, audit, certification, security review, or maintenance by OpenAI. +The server repository owns server behavior, API, deployment, security, and +release workflow facts. The website repository owns project-wide public +governance posture, political alignment, public-good framing, public voice, +reusable README baseline guidance, and source-of-truth mapping: + +- [`open-proofline/website/docs/governance-and-political-alignment.md`](https://github.com/open-proofline/website/blob/main/docs/governance-and-political-alignment.md) +- [`open-proofline/website/docs/repository-readme-baseline.md`](https://github.com/open-proofline/website/blob/main/docs/repository-readme-baseline.md) + +Reusable server prompts that touch README structure, public-facing wording, +project-wide governance, public-good framing, or source-of-truth mapping should +inspect those website documents and link to them instead of re-declaring the +project posture inside server docs. + ## Directory Structure Keep the Codex workflow in this structure: @@ -122,13 +136,18 @@ For any `v1 preview`, `v1.0.0`, or real-user evidence-upload readiness claim, run [docs/v1-preview-readiness-checklist.md](../docs/v1-preview-readiness-checklist.md) as part of the release workflow before using preview-ready language. -## Current project constraints +## Current Project Constraints Treat `README.md`, `AGENTS.md`, `SECURITY.md`, and the `docs/` directory as the current source of truth. For v1 preview terminology, repository roles, and current-versus-future product direction, read `docs/v1-preview-direction.md` before turning prototype gaps into backlog or implementation assumptions. For v1 preview release claims, also read `docs/v1-preview-readiness-checklist.md` and preserve its hard-blocker, non-goal, optional hosted-service, and issue-hygiene boundaries. +For public governance posture, political alignment, public-good framing, +public voice, README baseline style, and source-of-truth mapping, read the two +website source documents above. Keep server-specific facts in this repository; +link project-wide posture to the website source of truth. + Product documentation now uses the name Proofline. The repository URL is `open-proofline/server`, the root Go module path is `github.com/open-proofline/server`, release binaries use `proofline-server-*` names, and the published GHCR image is `ghcr.io/open-proofline/server`. Current runtime protocol and default data-layout identifiers use Proofline names. Historical reports and archived prompts may still mention earlier `safety-recorder` identifiers. Core constraints: @@ -166,6 +185,7 @@ When project scope, architecture, security posture, or workflow changes, update | Project change | Prompt/doc action | |---|---| +| README baseline, public voice, governance posture, public-good framing, or source-of-truth mapping changes | Read the website governance and README baseline docs, update `README.md`, `AGENTS.md`, `docs/`, `codex/README.md`, and reusable prompts only where they consume that project-wide source of truth. | | Product rename or repository/artifact namespace migration | Update `README.md`, `AGENTS.md`, `SECURITY.md`, relevant `docs/`, `codex/README.md`, and reusable prompts that mention product or artifact names. Keep docs-only renames separate from repository/module/Docker/GHCR migrations. | | First-class incident modes, capture profiles, escalation policies, sharing state, safety checks, interaction records, or evidence notes | Update `docs/incident-modes.md`, `README.md`, API docs, security/threat docs, client prototype docs, and relevant review prompts. | | New API routes or listener exposure | Review `AGENTS.md`, `docs/api.md`, security/threat docs, and relevant review prompts. | diff --git a/codex/prompts/00-project-context-check.md b/codex/prompts/00-project-context-check.md index 6144c05..c4463bd 100644 --- a/codex/prompts/00-project-context-check.md +++ b/codex/prompts/00-project-context-check.md @@ -20,6 +20,11 @@ Before making changes, read current source-of-truth files as relevant: - `docs/README.md` - `docs/v1-preview-direction.md` - `docs/key-custody.md`, if present +- `open-proofline/website/docs/governance-and-political-alignment.md`, when + public governance posture, political alignment, or public-good framing is in + scope +- `open-proofline/website/docs/repository-readme-baseline.md`, when README + structure, public voice, or source-of-truth mapping is in scope - relevant files in `docs/` - relevant source files - relevant tests diff --git a/codex/prompts/05-codex-change-control.md b/codex/prompts/05-codex-change-control.md index c9a42f0..a65fdd5 100644 --- a/codex/prompts/05-codex-change-control.md +++ b/codex/prompts/05-codex-change-control.md @@ -20,6 +20,11 @@ Before making changes, read current source-of-truth files as relevant: - `SECURITY.md` - `docs/README.md` - `docs/v1-preview-direction.md` +- `open-proofline/website/docs/governance-and-political-alignment.md`, when + public governance posture, political alignment, or public-good framing is in + scope +- `open-proofline/website/docs/repository-readme-baseline.md`, when README + structure, public voice, or source-of-truth mapping is in scope - relevant files in `docs/` - relevant source files - relevant tests diff --git a/codex/prompts/15-codex-structure-and-naming-maintenance.md b/codex/prompts/15-codex-structure-and-naming-maintenance.md index 37c14e3..59f9f97 100644 --- a/codex/prompts/15-codex-structure-and-naming-maintenance.md +++ b/codex/prompts/15-codex-structure-and-naming-maintenance.md @@ -32,6 +32,11 @@ Read: - all files under `codex/` - `docs/codex-change-control.md`, if present - `docs/development.md`, if relevant +- `open-proofline/website/docs/governance-and-political-alignment.md`, if + prompt workflow wording touches public governance or public-good framing +- `open-proofline/website/docs/repository-readme-baseline.md`, if prompt + workflow wording touches README structure, public voice, or source-of-truth + mapping ## Standard directory structure @@ -130,6 +135,9 @@ Check for: - historical prompts missing date prefixes - spaces, uppercase words, or inconsistent filenames - prompt files that reference stale project state +- prompt files that miss the website source documents when their workflow + covers README structure, public voice, governance posture, or source-of-truth + mapping - prompt files that contradict `AGENTS.md` - prompt files that still say server-side key storage/decryption is permanently impossible - prompt files that do not distinguish current implementation from future key custody design diff --git a/codex/prompts/40-documentation-update.md b/codex/prompts/40-documentation-update.md index e4500f2..0b5a20a 100644 --- a/codex/prompts/40-documentation-update.md +++ b/codex/prompts/40-documentation-update.md @@ -15,6 +15,11 @@ Before making changes, read current source-of-truth files as relevant: - `SECURITY.md` - `docs/README.md` - `docs/v1-preview-direction.md` +- `open-proofline/website/docs/governance-and-political-alignment.md`, when + public governance posture, political alignment, or public-good framing is in + scope +- `open-proofline/website/docs/repository-readme-baseline.md`, when README + structure, public voice, or source-of-truth mapping is in scope - relevant files in `docs/` - relevant source files - relevant tests @@ -94,6 +99,8 @@ Update only relevant files: - Codex change-control workflow - AI-assisted development disclosure - next steps / roadmap +- links to website source documents for project-wide governance, public voice, + and reusable README baseline claims ## Constraints @@ -102,6 +109,8 @@ Update only relevant files: - Do not claim the iOS client exists. - Do not claim production-readiness. - Do not describe future key custody/decryption as implemented unless it is implemented. +- Do not duplicate project-wide governance or public-voice posture in server + docs when a link to the website source of truth is clearer. - Keep wording clear and concise. ## Validation diff --git a/codex/prompts/45-documentation-and-prompt-review.md b/codex/prompts/45-documentation-and-prompt-review.md index 06953e5..3e17288 100644 --- a/codex/prompts/45-documentation-and-prompt-review.md +++ b/codex/prompts/45-documentation-and-prompt-review.md @@ -24,6 +24,8 @@ Start with current source-of-truth files: - `docs/README.md` - `docs/v1-preview-direction.md` - `docs/v1-preview-readiness-checklist.md` +- `open-proofline/website/docs/governance-and-political-alignment.md` +- `open-proofline/website/docs/repository-readme-baseline.md` - every current source-of-truth file under `docs/` - `codex/README.md` - every reusable prompt under `codex/prompts/`, including this prompt @@ -51,6 +53,8 @@ Review: - all reusable Codex prompt files - all public-facing project claims - source-of-truth alignment +- website governance, public-good framing, public voice, README baseline, and + source-of-truth mapping alignment - technical accuracy - linguistic coherence - readability and approachability @@ -77,6 +81,9 @@ Preserve these server-specific boundaries: media exports. - Do not imply the backend is production-ready public emergency infrastructure. +- Link project-wide governance posture and README baseline guidance to + `open-proofline/website` instead of rewriting that posture differently in + server docs. ## Review Checks @@ -84,6 +91,8 @@ Check source-of-truth consistency: - Do docs agree with current `README.md`, `AGENTS.md`, `SECURITY.md`, and `docs/`? +- Do README, docs, and prompts point to the website governance and README + baseline docs where project-wide public posture or public voice is in scope? - Do Codex prompts agree with current repo rules? - Are public claims supported by implementation or source docs? @@ -121,6 +130,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 current Proofline voice: serious + public-interest infrastructure, clear and humane, with dry humour only where + it clarifies values and never inside safety/security/key-custody claims? - Are acronyms and project-specific terms explained where needed? - Are there sections that sound like internal notes, legal fog, or startup hype? diff --git a/codex/prompts/70-work-on-github-issue.md b/codex/prompts/70-work-on-github-issue.md index 5b43b34..0394e14 100644 --- a/codex/prompts/70-work-on-github-issue.md +++ b/codex/prompts/70-work-on-github-issue.md @@ -86,6 +86,11 @@ Then read: - `CHANGELOG.md` - `SECURITY.md` - `docs/v1-preview-direction.md` +- `open-proofline/website/docs/governance-and-political-alignment.md`, when + public governance posture, political alignment, or public-good framing is in + scope +- `open-proofline/website/docs/repository-readme-baseline.md`, when README + structure, public voice, or source-of-truth mapping is in scope - relevant files in `docs/` - relevant source files - relevant tests 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 33050f0..cd01259 100644 --- a/codex/prompts/75-create-draft-pr-from-current-branch.md +++ b/codex/prompts/75-create-draft-pr-from-current-branch.md @@ -192,6 +192,9 @@ The PR body should include: - concise summary - validation commands run - docs updated, if any +- website governance/README-baseline source documents inspected, when + README structure, public voice, public governance, or source-of-truth mapping + changed - follow-up work, if any - tests skipped and why, if any - whether the issue was generated from a different reviewed branch/ref and whether it was revalidated against this PR base diff --git a/codex/prompts/76-request-codex-pr-review.md b/codex/prompts/76-request-codex-pr-review.md index 0b27f3f..71ad9b6 100644 --- a/codex/prompts/76-request-codex-pr-review.md +++ b/codex/prompts/76-request-codex-pr-review.md @@ -56,6 +56,7 @@ Post this PR comment only after confirming the base branch is correct: @codex review Please review this PR for correctness, security, scope control, and consistency with README.md, AGENTS.md, SECURITY.md, docs/v1-preview-direction.md where product direction is relevant, and relevant docs. +If the PR changes README structure, public voice, governance posture, or source-of-truth mapping, also check the website governance and README baseline source documents. Base branch: `` Head branch: `` @@ -104,9 +105,10 @@ Then review for: 5. documentation accuracy 6. consistency with README.md, AGENTS.md, and docs/v1-preview-direction.md where product direction is relevant 7. whether it satisfies the linked issue acceptance criteria -8. whether it should remain draft -9. whether it changes key custody/decryption assumptions, and whether those changes are explicitly designed and documented -10. whether branch-scoped issue/report findings were revalidated against the PR base branch +8. consistency with the website governance and README baseline source documents if README structure, public voice, governance posture, or source-of-truth mapping changed +9. whether it should remain draft +10. whether it changes key custody/decryption assumptions, and whether those changes are explicitly designed and documented +11. whether branch-scoped issue/report findings were revalidated against the PR base branch Do not modify files unless explicitly requested. diff --git a/codex/prompts/80-backlog-scan-issue-drafts.md b/codex/prompts/80-backlog-scan-issue-drafts.md index c4eddeb..a68a0b3 100644 --- a/codex/prompts/80-backlog-scan-issue-drafts.md +++ b/codex/prompts/80-backlog-scan-issue-drafts.md @@ -60,6 +60,11 @@ Read current repository files where present: - `LICENSE` - `docs/README.md` - `docs/v1-preview-direction.md` +- `open-proofline/website/docs/governance-and-political-alignment.md`, when + public governance posture, political alignment, or public-good framing is in + scope +- `open-proofline/website/docs/repository-readme-baseline.md`, when README + structure, public voice, or source-of-truth mapping is in scope - `docs/api.md` - `docs/architecture.md` - `docs/configuration.md` @@ -125,6 +130,7 @@ Look for future work in these categories: 12. Codex workflow/process improvements 13. Key custody / emergency access design 14. Branch/release-candidate follow-up work +15. README baseline, public voice, and source-of-truth mapping drift ## Candidate discovery guidance @@ -151,6 +157,8 @@ Bad candidate signals: - vague “improve code” - duplicate of existing issue - feature that contradicts README/AGENTS scope +- stale project-map wording that should be fixed in docs instead of becoming a + broad product issue - production claims beyond current maturity - public issue containing sensitive vulnerability details - anything requiring secrets, raw tokens, or private deployment details diff --git a/codex/prompts/90-release-check.md b/codex/prompts/90-release-check.md index 90fbcc5..3ccab01 100644 --- a/codex/prompts/90-release-check.md +++ b/codex/prompts/90-release-check.md @@ -52,6 +52,11 @@ Before making changes, read current source-of-truth files as relevant: - `docs/v1-preview-direction.md` - `docs/v1-preview-readiness-checklist.md`, for `v1 preview`, `v1.0.0`, or real-user evidence-upload readiness claims +- `open-proofline/website/docs/governance-and-political-alignment.md`, when + public governance posture, political alignment, or public-good framing is in + scope +- `open-proofline/website/docs/repository-readme-baseline.md`, when README + structure, public voice, or source-of-truth mapping is in scope - relevant files in `docs/` - relevant source files - relevant tests @@ -103,6 +108,8 @@ Check: - `gofmt` has been run - `go vet` passes, if practical - README version/scope is accurate +- README structure, public voice, and source-of-truth mapping still follow the + website README baseline when those sections changed - `CHANGELOG.md` includes the release - `LICENSE` exists and matches the documented SPDX identifier - `SECURITY.md` exists and does not promise production readiness diff --git a/codex/prompts/95-validate-deep-research-report.md b/codex/prompts/95-validate-deep-research-report.md index 0c71f26..34481ee 100644 --- a/codex/prompts/95-validate-deep-research-report.md +++ b/codex/prompts/95-validate-deep-research-report.md @@ -58,6 +58,12 @@ Allowed values: Product documentation now uses the name Proofline. Repository paths, the Go module path, Docker image names, GHCR package names, release binary names, runtime protocol identifiers, and default data-layout identifiers use the `open-proofline/server` repository namespace and Proofline names. Historical reports, archived prompts, legacy `/e/{token}` aliases, and historical migration names may still mention `safety-recorder` or `emergency`. +The website repository is the project-level source of truth for public +governance posture, political alignment, public-good framing, public voice, +reusable README baseline guidance, and source-of-truth mapping. Report wording +that summarizes project-wide public posture should use those website source +documents rather than inventing a server-local governance claim. + Proofline's planned product scope includes emergency incidents, non-emergency interaction records, timed safety checks, and evidence notes. The current backend stores generic incidents by default; optional incident-mode, capture-profile, escalation-policy, and sharing-state metadata are labels only unless the reviewed tree explicitly implements first-class behavior for them. The post-quantum envelope is a v1 preview requirement, but it is not current runtime behavior unless implementation files prove it. Any report claim that Proofline is ready for `v1 preview`, `v1.0.0`, or real-user evidence upload must be checked against `docs/v1-preview-readiness-checklist.md`. ## Rules @@ -91,6 +97,8 @@ sed -n '1,240p' README.md sed -n '1,220p' SECURITY.md sed -n '1,260p' AGENTS.md sed -n '1,280p' docs/README.md +sed -n '1,260p' ../website/docs/governance-and-political-alignment.md +sed -n '1,260p' ../website/docs/repository-readme-baseline.md cat docs/v1-preview-direction.md test -f docs/v1-preview-readiness-checklist.md && sed -n '1,260p' docs/v1-preview-readiness-checklist.md sed -n '1,260p' docs/incident-modes.md @@ -185,7 +193,10 @@ Check and fix, if needed: - Missing public product API authentication when docs state `/v1` is private and protected by local account sessions. -- Missing web/iOS/Android clients when docs mark them as future work. +- Missing iOS/Android/protocol clients when docs mark them as planned future + repositories. +- Missing production web-client behavior when docs mark `open-proofline/web-client` + as a separate current experimental prototype rather than a production client. - Missing first-class incident-mode behavior, capture-profile behavior, escalation policies, sharing-state behavior, or dead-man switch when docs mark them as future work. diff --git a/docs/README.md b/docs/README.md index 7505118..e26ceb7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,16 @@ # Documentation -This directory contains the detailed documentation for Proofline Server, the Go backend component of the planned Proofline project. The top-level [README](../README.md) is a concise server overview; these docs keep operational, API, deployment, incident-capture, and development details in one place. +This directory contains the detailed documentation for Proofline Server, the Go +backend component of the Proofline project. The top-level +[README](../README.md) is the server overview; these docs keep operational, +API, deployment, incident-capture, and development details in one place. + +Project-wide public governance posture, political alignment, public-good +framing, public voice, and reusable README baseline guidance live in the +[`open-proofline/website`](https://github.com/open-proofline/website) +repository. Server docs should link to those source documents for project-wide +public posture and keep this repository focused on server behavior, deployment, +and backend security facts. ## Contents @@ -69,19 +79,22 @@ Companion repositories are separate current or future projects outside this server repository: ```text +open-proofline/website open-proofline/web-client open-proofline/ios-client open-proofline/android-client open-proofline/protocol ``` -Those repositories do not exist in this repository and should not be implemented -here by accident. This server repository may keep planning notes for client and -protocol work only as repository-boundary context. +The website and web-client repositories currently exist as separate +experimental repositories. The iOS, Android, and protocol repositories remain +planned until they exist and document their own scope. None of those components +should be implemented here by accident. This server repository may keep +planning notes for client and protocol work only as repository-boundary context. ## Current Backend Scope -Proofline Server receives already-encrypted chunks, stores metadata in SQLite by default or optional PostgreSQL, stores encrypted blobs on local disk by default or in optional S3-compatible object storage, loads TOML config with `SAFE_*` environment and secret-file overrides, performs a startup check against optional Valkey/Redis-compatible coordination when explicitly configured, groups chunks into media streams, can issue configured short-lived regional relay upload and fanout capabilities for authorized open streams, exposes service-authenticated core relay preflight/commit/fanout authorization endpoints when relay-to-core auth is configured, includes a separate regional stream-ingress relay route for complete encrypted chunk upload/staging/forwarding, optimistic encrypted unconfirmed fanout, and bounded fanout state when configured, serves private admin JSON routes under `/admin/api/...` and a private admin web surface under `/admin`, applies app-level route-class rate limiting to main API routes, can use Valkey for short-lived complete-upload leases, supports optional browser cookie sessions with CSRF and credentialed CORS for future web-client calls, supports disabled-by-default configurable account registration with SMTP-backed email verification for open self-hosted registration, supports email challenge, TOTP, and disabled-by-default WebAuthn/FIDO2 passkey or roaming security-key second-factor setup for account gating, supports private-admin assisted second-factor reset for lost-factor recovery, and exposes a token-scoped read-only incident viewer with app-level route-class rate limiting. New chunk uploads must use the accepted post-quantum payload envelope by default, and the Go simulator now produces that PQ envelope unless an explicit v1 compatibility flag is used. +Proofline Server receives already-encrypted chunks, stores metadata in SQLite by default or optional PostgreSQL, stores encrypted blobs on local disk by default or in optional S3-compatible object storage, loads TOML config with `SAFE_*` environment and secret-file overrides, performs a startup check against optional Valkey/Redis-compatible coordination when explicitly configured, groups chunks into media streams, can issue configured short-lived regional relay upload and fanout capabilities for authorized open streams, exposes service-authenticated core relay preflight/commit/fanout authorization endpoints when relay-to-core auth is configured, includes a separate regional stream-ingress relay route for complete encrypted chunk upload/staging/forwarding, optimistic encrypted unconfirmed fanout, and bounded fanout state when configured, serves private admin JSON routes under `/admin/api/...` and a private admin web surface under `/admin`, applies app-level route-class rate limiting to main API routes, can use Valkey for short-lived complete-upload leases, supports optional browser cookie sessions with CSRF and credentialed CORS for future production web-client calls, supports disabled-by-default configurable account registration with SMTP-backed email verification for open self-hosted registration, supports email challenge, TOTP, and disabled-by-default WebAuthn/FIDO2 passkey or roaming security-key second-factor setup for account gating, supports private-admin assisted second-factor reset for lost-factor recovery, and exposes a token-scoped read-only incident viewer with app-level route-class rate limiting. New chunk uploads must use the accepted post-quantum payload envelope by default, and the Go simulator now produces that PQ envelope unless an explicit v1 compatibility flag is used. The regional stream-ingress relay currently has a separate health/readiness route with safe aggregate readiness categories, backend-issued upload and @@ -140,7 +153,7 @@ capture, escalation, sharing, and legal/export actions separate. The current main incident create/read routes support optional incident-mode, capture-profile, escalation-policy, and sharing-state metadata, and the account incident list/detail routes return only owner-scoped public-safe metadata for -future web-client reads. Those mode fields do not drive access, notification, +future production web-client reads. Those mode fields do not drive access, notification, retention, sharing, viewer, or key-custody behavior. Mode-driven behavior and migration boundaries are documented in [incident-modes.md](incident-modes.md). Current local account/session behavior diff --git a/docs/api.md b/docs/api.md index 405d8a4..27b2dd2 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,6 +1,6 @@ # API -This is the current backend-only HTTP surface for Proofline. The API binary starts a main API/viewer listener and a private-admin listener on one or more configured bind addresses. Main `/v1` routes require local account authentication except for login and the disabled-by-default registration/email-verification routes, and they use app-level route-class rate limits. Existing `/admin/api/...` JSON routes require an admin account with completed admin second-factor setup and are mounted only on the private-admin listener. The private-admin listener also serves the `/admin` dashboard route tree, which applies the same admin setup and active-factor session-verification gate before operator actions. Incident viewer routes are token-gated, read-only, and mounted on the main listener. The future canonical no-account viewer link belongs to the web-client origin as documented in [web-client-viewer-routing.md](web-client-viewer-routing.md); planned web, iOS, and Android clients are not part of this repository yet. +This is the current backend-only HTTP surface for Proofline. The API binary starts a main API/viewer listener and a private-admin listener on one or more configured bind addresses. Main `/v1` routes require local account authentication except for login and the disabled-by-default registration/email-verification routes, and they use app-level route-class rate limits. Existing `/admin/api/...` JSON routes require an admin account with completed admin second-factor setup and are mounted only on the private-admin listener. The private-admin listener also serves the `/admin` dashboard route tree, which applies the same admin setup and active-factor session-verification gate before operator actions. Incident viewer routes are token-gated, read-only, and mounted on the main listener. The future canonical no-account viewer link belongs to the web-client origin as documented in [web-client-viewer-routing.md](web-client-viewer-routing.md); web-client implementation lives in `open-proofline/web-client`, while planned iOS and Android clients are not part of this repository yet. Media bundle downloads are encrypted chunk bundles. The backend does not decrypt, merge, or produce playable media. Current encrypted uploads use the @@ -31,8 +31,8 @@ or backend decryption, notifications, raw key storage, and key escrow do not exist yet. Future trusted-contact alerts, missed-check-in messages, and viewer-link delivery are planned separately in [notification-boundary.md](notification-boundary.md). The main API does include -a narrow public-safe owner incident list/detail read surface for the future web -client, but this does not make every `/v1` route group public-ready without +a narrow public-safe owner incident list/detail read surface for future +production web-client use, but this does not make every `/v1` route group public-ready without route-level deployment review. The public web-client route, CORS, CSRF, cookie, cache, edge, and logging boundary is documented in @@ -112,8 +112,8 @@ Session tokens are opaque server-side credentials. The raw token is returned onl When `SAFE_WEB_AUTH_ENABLED=true`, the main API also accepts a dedicated browser session cookie for `/v1` routes when no bearer token is present. Browser -cookie mode is intended for the future `open-proofline/web-client`: web clients -should call with `credentials: "include"` and should not store raw bearer +cookie mode is intended for future production use by `open-proofline/web-client`: +web clients should call with `credentials: "include"` and should not store raw bearer tokens in localStorage in production. If a request sends both `Authorization: Bearer ...` and the browser session cookie, the server rejects it with `400 ambiguous_credentials`. @@ -148,7 +148,8 @@ Verification links use: {SAFE_PUBLIC_WEB_ORIGIN}/verify-email#token= ``` -The token is placed in the URL fragment so a future web client can submit it in +The token is placed in the URL fragment so a future production web-client +viewer can submit it in the JSON request body without sending it to the web server as a path or query value. The backend stores only token hashes, not raw verification tokens. @@ -2716,7 +2717,7 @@ The Go app does not set `Strict-Transport-Security` in local/dev HTTP mode. Set ### `GET /i/{token}/viewer-payload` Returns the stable, token-scoped no-account viewer payload intended for the -future web-client viewer. It is narrower than `/i/{token}/data`: it provides +future production web-client viewer. It is narrower than `/i/{token}/data`: it provides incident status, latest check-in time, safe device state when present, and a single latest shared or last reported location context when a check-in contains both latitude and longitude. It does not expose chunk summaries, stream diff --git a/docs/architecture.md b/docs/architecture.md index 45f554e..e30540b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -20,8 +20,9 @@ rotation, and deployment automation remain planned in [regional-stream-ingress-relay.md](regional-stream-ingress-relay.md). This repository is the server/backend component only. In the current -`open-proofline` organisation it is `open-proofline/server`. Web, iOS, Android, -and shared protocol work should live in separate repositories. +`open-proofline` organisation it is `open-proofline/server`. Public website and +web-client work live in their own current repositories; iOS, Android, and shared +protocol work should live in separate repositories when those scopes are ready. The long-term product direction is broader than emergency-only recording. Future clients may support emergency incidents, non-emergency interaction records, @@ -29,14 +30,14 @@ timed safety checks, and evidence notes. The current backend stores generic incidents by default, can store optional incident-mode, capture-profile, escalation-policy, and sharing-state metadata on main incident create/read routes, exposes owner-only public-safe incident list/detail metadata for future -web-client reads, and has local username/password accounts with opaque +production web-client reads, and has local username/password accounts with opaque server-side sessions for the main `/v1` API, private-admin JSON routes under `/admin/api/...`, plus a private admin web surface under `/admin`. Sharing metadata, owner wrapped-key records, and signed-in trusted-contact wrapped-key reads are implemented behind authenticated `/v1` routes. Mode-driven access, escalation, retention, key custody, trusted-contact -incident delivery, notification delivery, and mobile/web clients are not -implemented yet. Planned mode behavior, escalation, migration, and +incident delivery, notification delivery, production web-client behavior, and +mobile clients are not implemented yet. Planned mode behavior, escalation, migration, and viewer-wording boundaries are documented in [incident-modes.md](incident-modes.md), and current local session behavior plus future public product API, separately bound private admin API, role, and grant boundaries are documented in @@ -44,8 +45,8 @@ bound private admin API, role, and grant boundaries are documented in viewer-link, retry, suppression, opt-out, rate-limit, and audit boundaries are documented in [notification-boundary.md](notification-boundary.md). -The repository does not contain an iOS app, Android app, web client, protocol -package, production recording client, production client key storage, key +The repository does not contain an iOS app, Android app, web-client +implementation, protocol package, production recording client, production client key storage, key sharing, browser/client-side decryption, server-assisted break-glass key access, notification system, trusted-contact delivery model, future public product API, future separately bound private admin API, OAuth/JWT identity integration, or @@ -85,6 +86,7 @@ The current organisation is `open-proofline`. Current and planned repositories: ```text +open-proofline/website open-proofline/server open-proofline/web-client open-proofline/ios-client @@ -94,13 +96,14 @@ open-proofline/protocol Responsibilities: -| Repository | Responsibility | -|---|---| -| `open-proofline/server` | Go backend, authenticated main API, private admin web surface, public incident viewer, SQLite migrations, encrypted blob storage, deployment docs, and server release workflow. | -| `open-proofline/web-client` | Account portal, authorised incident review, trusted-contact access, and eventual replacement for the current token-only viewer. | -| `open-proofline/ios-client` | iOS incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | -| `open-proofline/android-client` | Android incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | -| `open-proofline/protocol` | Shared API specs, encryption envelope specs, bundle manifests, compatibility matrix, and conformance tests. | +| Repository | Status | Responsibility | +|---|---|---| +| `open-proofline/website` | Current, experimental | Static public website, public framing, governance posture, reusable README baseline, and website Codex workflows. | +| `open-proofline/server` | Current, experimental | Go backend, authenticated main API, private admin web surface, public incident viewer, SQLite migrations, encrypted blob storage, deployment docs, and server release workflow. | +| `open-proofline/web-client` | Current, experimental | React account portal and incident-review prototype for account flows and metadata review. It is not a recorder, emergency workflow, production decryption client, or production account portal. | +| `open-proofline/ios-client` | Planned | Future iOS incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | +| `open-proofline/android-client` | Planned | Future Android incident capture, encrypted staging, upload, local account flows, and platform-specific recording behavior. | +| `open-proofline/protocol` | Planned | Future shared API specs, encryption envelope specs, bundle manifests, compatibility matrix, and conformance tests. | The Go module path is `github.com/open-proofline/server`, release binaries use `proofline-server-*` names, and the published GHCR image is `ghcr.io/open-proofline/server`. Current runtime protocol and default data-layout identifiers use Proofline names. Historical reports and archived prompts may still mention earlier `safety-recorder` identifiers. @@ -116,7 +119,9 @@ This repository should remain scoped to backend server responsibilities: - simulator/reference backend flow - backend security, retention, and threat-model docs -Do not add future web-client, iOS-client, Android-client, or protocol implementation here unless the maintainer explicitly changes the repository strategy. +Do not add website, web-client, iOS-client, Android-client, or protocol +implementation here unless the maintainer explicitly changes the repository +strategy. ## Example Network Topology diff --git a/docs/browser-decryption.md b/docs/browser-decryption.md index f1ed043..414411e 100644 --- a/docs/browser-decryption.md +++ b/docs/browser-decryption.md @@ -197,7 +197,9 @@ Browser decryption UX should reflect why the incident was captured: | Safety check | Missed check-ins may trigger trusted-contact access, but false positives need careful wording and cancellation/audit policy. | | Evidence note | Often a controlled export/review workflow rather than live emergency access. | -Do not hard-code emergency language into all decrypting viewer flows. A future web client should distinguish urgent safety review from ordinary authorised incident review. +Do not hard-code emergency language into all decrypting viewer flows. Future +production web-client decryption UX should distinguish urgent safety review +from ordinary authorised incident review. ## URL Fragment Model diff --git a/docs/code-map.md b/docs/code-map.md index e2125e4..4f9e303 100644 --- a/docs/code-map.md +++ b/docs/code-map.md @@ -12,14 +12,14 @@ metadata, trusted-contact public-key metadata, incident/stream sharing-grant metadata, and grant-bound wrapped-key records without adding decryption. This repository is the server/backend component only. In the current -`open-proofline` organisation it is `open-proofline/server`. Web-client, -iOS-client, Android-client, and protocol implementation should live in separate -repositories. +`open-proofline` organisation it is `open-proofline/server`. Web-client work +lives in `open-proofline/web-client`; iOS-client, Android-client, and protocol +implementation should live in separate repositories when those scopes exist. The current backend stores generic incidents by default and can store optional incident-mode, capture-profile, escalation-policy, and sharing-state metadata on main incident create/read routes. The account incident list/detail routes return -owner-only public-safe metadata for future web-client reads. Those mode fields +owner-only public-safe metadata for future production web-client reads. Those mode fields do not drive access, notification, retention, sharing, viewer, or key-custody behavior. Account/device recipient-key, trusted-contact relationship, contact public-key, sharing-grant, and wrapped-key metadata is implemented separately behind @@ -380,7 +380,7 @@ Viewer tokens are created on the authenticated main API listener by `POST /v1/incidents/{incident_id}/incident-tokens`. The raw token is returned once, while the configured metadata repository stores only a SHA-256 hash. -`GET /i/{token}` is mounted on the main API/viewer listener. It renders `internal/httpapi/web/templates/incident_viewer.html` with `html/template`. CSS and JavaScript are embedded from `internal/httpapi/web/static`. `GET /i/{token}/data` returns the same read-only summary as JSON for polling. `GET /i/{token}/viewer-payload` returns the narrower token-scoped payload intended for the future web-client viewer. Pre-rename `/e/{token}` viewer, data, and download paths remain read-only aliases only while explicit local/test compatibility needs them; future canonical no-account viewer links should point at the web-client origin as documented in `docs/web-client-viewer-routing.md`. +`GET /i/{token}` is mounted on the main API/viewer listener. It renders `internal/httpapi/web/templates/incident_viewer.html` with `html/template`. CSS and JavaScript are embedded from `internal/httpapi/web/static`. `GET /i/{token}/data` returns the same read-only summary as JSON for polling. `GET /i/{token}/viewer-payload` returns the narrower token-scoped payload intended for the future production web-client viewer. Pre-rename `/e/{token}` viewer, data, and download paths remain read-only aliases only while explicit local/test compatibility needs them; future canonical no-account viewer links should point at the web-client origin as documented in `docs/web-client-viewer-routing.md`. Token lookup checks the hash, expiry, and revocation state before incident metadata is loaded. Invalid, expired, and revoked tokens all return the same public error. The public viewer limiter groups requests by safe route class and a hash of the socket peer identity before token lookup; limiter keys do not include raw viewer tokens or token-bearing paths. Viewer responses use `Referrer-Policy: no-referrer`, `X-Content-Type-Options: nosniff`, a strict `Content-Security-Policy`, restrictive `Permissions-Policy`, and `Cache-Control: no-store` for token-protected responses. diff --git a/docs/codex-change-control.md b/docs/codex-change-control.md index 467a198..e9b1919 100644 --- a/docs/codex-change-control.md +++ b/docs/codex-change-control.md @@ -29,6 +29,10 @@ Codex can draft changes, but the maintainer remains responsible for reviewing, t - `AGENTS.md` - relevant files in `docs/` - relevant prompt in `codex/prompts/` + - `open-proofline/website/docs/governance-and-political-alignment.md` and + `open-proofline/website/docs/repository-readme-baseline.md` when public + governance posture, public voice, README structure, or source-of-truth + mapping is in scope For prompt-maintenance triggers, see [Codex prompt maintenance](../codex/README.md#when-to-update-prompts). diff --git a/docs/configuration.md b/docs/configuration.md index ff36543..96e16be 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -233,7 +233,7 @@ values for the same field. Within TOML, set either the direct secret key or the | `SAFE_SMTP_TIMEOUT` | `10s` | SMTP dial timeout. Must be positive. | | `SAFE_AUTH_BOOTSTRAP_SECRET` | unset | One-time bootstrap secret required to create the first admin account when no admin exists. Remove after bootstrap. | | `SAFE_AUTH_BOOTSTRAP_SECRET_FILE` | unset | File containing the one-time bootstrap secret. Overrides `SAFE_AUTH_BOOTSTRAP_SECRET` when set. | -| `SAFE_WEB_AUTH_ENABLED` | `false` | Enables main `/v1` browser cookie-session routes for the future web client. Existing bearer-token routes continue to work. | +| `SAFE_WEB_AUTH_ENABLED` | `false` | Enables main `/v1` browser cookie-session routes for future production web-client use. Existing bearer-token routes continue to work. | | `SAFE_WEB_ALLOWED_ORIGINS` | unset | Comma-separated exact web origins that may receive credentialed CORS responses. Wildcards are rejected. | | `SAFE_WEB_SESSION_COOKIE_NAME` | `__Host-proofline_session` | Browser session cookie name. The default production name requires `SAFE_WEB_SESSION_COOKIE_SECURE=true`; local plain-HTTP development should use a non-`__Host-` name. | | `SAFE_WEB_SESSION_COOKIE_SECURE` | `true` | Sets the browser session cookie `Secure` attribute. `false` is accepted only with local loopback web origins. | diff --git a/docs/deployment.md b/docs/deployment.md index 553194a..503ae63 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -103,7 +103,7 @@ the secret mount and restart. The bootstrap form is disabled after an admin account exists. Treat the bootstrap secret, account passwords, raw session tokens, raw idempotency keys, and Authorization headers as secrets. -Browser cookie sessions for the future web client are disabled by default. For +Browser cookie sessions for future production web-client use are disabled by default. For local plain-HTTP web-client development, enable them explicitly with a local allowed origin and a non-`__Host-` non-`Secure` cookie name: @@ -878,8 +878,9 @@ https://developer.mozilla.org/en-US/observatory The reverse proxy should route only reviewed current-viewer paths to the main listener. Private dashboard routes should stay on localhost, WireGuard, LAN, or another private boundary, and public edges must block `/admin/api/...`. For a -future web-client viewer, point shared viewer links at the web-client origin -instead of making this built-in viewer route the canonical public entry point. +future production web-client viewer, point shared viewer links at the +web-client origin instead of making this built-in viewer route the canonical +public entry point. One same-host shape is: diff --git a/docs/development.md b/docs/development.md index 582fd93..b15bace 100644 --- a/docs/development.md +++ b/docs/development.md @@ -216,6 +216,11 @@ Codex output should summarize: When editing docs, keep these claims aligned: - current name, version, and scope in [../README.md](../README.md) +- project-wide public governance posture, political alignment, public-good + framing, public voice, reusable README baseline, and source-of-truth mapping + in `open-proofline/website`, especially + `docs/governance-and-political-alignment.md` and + `docs/repository-readme-baseline.md` - planned incident modes in [incident-modes.md](incident-modes.md) - route details in [api.md](api.md) - security assumptions in [security-model.md](security-model.md) and [threat-model.md](threat-model.md) diff --git a/docs/incident-modes.md b/docs/incident-modes.md index 7f99987..e23ba7e 100644 --- a/docs/incident-modes.md +++ b/docs/incident-modes.md @@ -184,9 +184,9 @@ Future account-enabled clients should distinguish: Incident labels must not silently grant access. Emergency incidents, interaction records, safety checks, and evidence notes need explicit sharing, escalation, and grant policy before implementation. The current token-scoped incident viewer is a temporary read-only access model. -A future web client may replace it after public account workflows, -authorization, key custody, and trusted-contact access are designed. The future -`/v1` role, grant, and route-exposure direction is documented in +A future production web-client viewer may replace it after public account +workflows, authorization, key custody, and trusted-contact access are designed. +The future `/v1` role, grant, and route-exposure direction is documented in [v1-access-control.md](v1-access-control.md). ## Migration From Generic Incidents diff --git a/docs/public-web-client-deployment-boundary.md b/docs/public-web-client-deployment-boundary.md index 382e0b2..e29a4db 100644 --- a/docs/public-web-client-deployment-boundary.md +++ b/docs/public-web-client-deployment-boundary.md @@ -11,10 +11,10 @@ origin can be treated as a reviewed v1 preview deployment path. ## Summary -The future `open-proofline/web-client` is v1-critical, but a public static web -client is not safe merely because it is a static site. A public web client -creates a browser credential boundary, a cross-origin API boundary, and a route -exposure boundary for the server. +The current experimental `open-proofline/web-client` repository is v1-critical, +but a public static web client is not safe merely because it is a static site. A +public web client creates a browser credential boundary, a cross-origin API +boundary, and a route exposure boundary for the server. The deployment model should be: diff --git a/docs/reports/prompts/phase-0-deep-research-preflight.md b/docs/reports/prompts/phase-0-deep-research-preflight.md index 5a89bc9..c5f7a40 100644 --- a/docs/reports/prompts/phase-0-deep-research-preflight.md +++ b/docs/reports/prompts/phase-0-deep-research-preflight.md @@ -14,6 +14,15 @@ open-proofline/server Product documentation currently uses the name Proofline. Repository URLs, the Go module path, Docker image names, GHCR package names, release binary names, runtime protocol identifiers, and default data-layout identifiers use the `open-proofline/server` repository namespace and Proofline names. Historical reports, archived prompts, legacy `/e/{token}` aliases, and historical migration names may still mention `safety-recorder` or `emergency`. +Project-wide public governance posture, political alignment, public-good framing, +public voice, reusable README baseline guidance, and source-of-truth mapping +live in `open-proofline/website`, especially: + +```text +docs/governance-and-political-alignment.md +docs/repository-readme-baseline.md +``` + ## Inputs Reviewed branch or ref: @@ -127,7 +136,10 @@ Phase 0 should make sure the actual Phase 1 report run will follow: - Valkey/Redis-compatible short-lived coordination backend support - exact Go client package documentation on `pkg.go.dev` when package behavior is discussed -7. Identify Apple/iOS/Swift, Android, web-client, protocol, legal-adjacent, or App Store/Play Store claims that would need primary sources if the report discusses them. +7. Identify public governance posture, public voice, README baseline, + Apple/iOS/Swift, Android, web-client, protocol, legal-adjacent, or App + Store/Play Store claims that would need primary sources if the report + discusses them. 8. Identify the required Source Registry sections and what each section must contain. @@ -169,6 +181,11 @@ Do **not** claim formal security audit, penetration test, compliance certificati Do **not** describe future incident modes, account access, key custody, browser decryption, break-glass access, mobile clients, web clients, or the post-quantum envelope as implemented features unless the reviewed tree contains implementation code. The post-quantum envelope is a v1 preview requirement, not current runtime behavior unless implementation has landed. +Do **not** describe `open-proofline/web-client` as absent if the current +project map identifies it as an existing experimental companion repository. +Distinguish current companion repositories from future production behavior and +from future iOS, Android, and protocol repositories. + ## Expected Source Plan The research plan should identify sources in these groups. @@ -202,6 +219,15 @@ docs/break-glass-key-access.md docs/ios-local-recorder-prototype.md ``` +When public governance posture, political alignment, public-good framing, +public voice, reusable README baseline guidance, or source-of-truth mapping is +in scope, also plan to inspect the website source documents: + +```text +open-proofline/website/docs/governance-and-political-alignment.md +open-proofline/website/docs/repository-readme-baseline.md +``` + For the v0.8.0 optional backend-support review, also plan repository inspection for: - PostgreSQL metadata backend implementation and documentation, including configuration, connection setup, migrations, schema behavior, transaction and constraint behavior, fallback/default behavior, tests or workflows, dependency declarations, and package usage diff --git a/docs/reports/prompts/phase-1-deep-research-technical-review.md b/docs/reports/prompts/phase-1-deep-research-technical-review.md index a4bff54..00801f4 100644 --- a/docs/reports/prompts/phase-1-deep-research-technical-review.md +++ b/docs/reports/prompts/phase-1-deep-research-technical-review.md @@ -59,6 +59,17 @@ read-only incident viewer. The product documentation now uses the name Proofline. Repository URLs, the Go module path, Docker image names, GHCR package names, release binary names, runtime protocol identifiers, and default data-layout identifiers use the `open-proofline/server` repository namespace and Proofline names. Historical reports, archived prompts, legacy `/e/{token}` aliases, and historical migration names may still mention `safety-recorder` or `emergency`. +Project-wide public governance posture, political alignment, public-good +framing, public voice, reusable README baseline guidance, and source-of-truth +mapping live in `open-proofline/website`. When the report summarizes those +project-wide claims, use the website source documents rather than inventing a +server-local governance claim: + +```text +open-proofline/website/docs/governance-and-political-alignment.md +open-proofline/website/docs/repository-readme-baseline.md +``` + The long-term product direction is broader than emergency-only recording. Planned modes include emergency incidents, non-emergency interaction records, timed safety checks, and evidence notes. These are planning direction unless the reviewed tree contains first-class implementation. Core project boundaries: @@ -71,9 +82,9 @@ Core project boundaries: only unless the reviewed tree implements first-class behavior for them. - Backend decryption, browser decryption, production key custody, break-glass access, trusted-contact accounts, public account portals, OAuth/JWT, push - notifications, SMS, Messenger, web/iOS/Android clients, and first-class - escalation policies are future or out-of-scope items unless explicitly - implemented in the reviewed tree. + notifications, SMS, Messenger, production web/iOS/Android client behavior, + and first-class escalation policies are future or out-of-scope items unless + explicitly implemented in the reviewed tree. - The post-quantum envelope is documented as a v1 preview requirement, but it is not shipped runtime behavior unless implementation files prove it. - V1 preview, v1.0.0, or real-user evidence-upload readiness claims must be @@ -84,6 +95,10 @@ Core project boundaries: direction, post-quantum envelope, and client prototype documents are design/planning guardrails or future preview requirements, not shipped implementation. +- `open-proofline/web-client` may exist as a current experimental companion + repository. Do not treat that repository as absent when the project map + identifies it, and do not treat its existence as implemented server behavior + or production web-client readiness. - Do not treat documented future work as a current defect merely because it is not implemented. ## Validation Evidence Policy @@ -139,6 +154,10 @@ Prioritize repository evidence first: Required external-source families when applicable: +- Project-wide public governance posture, political alignment, public-good + framing, public voice, README baseline, or source-of-truth mapping claims: + `open-proofline/website/docs/governance-and-political-alignment.md` and + `open-proofline/website/docs/repository-readme-baseline.md` - Go/toolchain/standard-library/module claims: `go.dev` or `pkg.go.dev` - AES-GCM, nonce, randomness, authenticated encryption, or cryptographic-strength claims: NIST, Go official docs, or another primary standards/source document - SQLite WAL, foreign keys, migration, transaction, locking, backup, or restore claims: `sqlite.org` @@ -192,6 +211,9 @@ Every registry entry must include: Minimum requirements: - List every repository file materially relied on, pinned to ``. +- List every companion-project source materially relied on, including website + governance/README-baseline docs or web-client docs, with commit/ref/date and + limitations. - List every authoritative external source materially relied on. - List required authoritative external source categories that were not consulted and explain why. - List validation commands that were actually supported by supplied evidence. @@ -246,9 +268,17 @@ Pay special attention to future-design and planning documents when present: - `docs/browser-decryption.md` - `docs/break-glass-key-access.md` - `docs/ios-local-recorder-prototype.md` -- any future web, iOS, Android, account, protocol, Apple-platform, or client-planning documents +- any current or future web-client, iOS, Android, account, protocol, + Apple-platform, or client-planning documents - any future client code, Swift/Kotlin/TypeScript package files, Xcode/Android project files, entitlement files, or App Store/Play Store metadata files if they exist in the reviewed tree +When public governance posture, political alignment, public-good framing, +public voice, reusable README baseline guidance, or source-of-truth mapping is +in scope, inspect the website source documents listed in Repository Context. +When the report discusses web-client behavior or prototype limits, inspect the +current `open-proofline/web-client` source documents if accessible, and clearly +separate companion-repository behavior from server behavior. + Technical focus areas: 1. Documentation consistency, Proofline naming, compatibility-name notes, and public-readiness wording @@ -264,7 +294,8 @@ Technical focus areas: 11. ZIP bundle generation, manifest completeness, fail-closed behavior, and path traversal handling 12. Crypto-adjacent simulator envelope, ciphertext-only backend boundary, and naming-compatibility claims 13. Future key custody, browser/client-side decryption, break-glass, trusted-contact access, and server escrow boundaries -14. Future web/iOS/Android/protocol/client planning and platform assumptions +14. Current web-client companion scope, future iOS/Android/protocol/client + planning, and platform assumptions 15. Deployment guidance, Traefik examples, WireGuard/private boundary, rate limiting, and no `/v1` public exposure 16. Docker/GHCR/GitHub Actions/supply-chain hygiene 17. Public issue/report safety @@ -294,7 +325,12 @@ Do not recommend public GitHub issues for private vulnerabilities, raw tokens, s ## Common False Positives To Avoid - Do not say `/v1` lacks public auth as a vulnerability unless the docs claim it is safe to expose publicly. -- Do not say missing iOS, Android, web-client, accounts, incident modes, capture profiles, escalation policies, sharing state, browser decryption, production key custody, or break-glass behavior is a defect when docs mark those as future work. +- Do not say missing iOS, Android, production web-client behavior, accounts, + incident modes, capture profiles, escalation policies, sharing state, browser + decryption, production key custody, or break-glass behavior is a defect when + docs mark those as future work. +- Do not say `open-proofline/web-client` is missing when current project docs + mark it as an existing experimental companion repository. - Do not describe the post-quantum envelope as implemented unless code proves it. If reviewing a v1 preview readiness claim, verify that the post-quantum envelope is implemented, documented, tested, and default. diff --git a/docs/security-model.md b/docs/security-model.md index a0bcb54..fb48155 100644 --- a/docs/security-model.md +++ b/docs/security-model.md @@ -22,7 +22,7 @@ account/device wrapped-key delivery, trusted-contact incident reads, dead-man-switch notifications, provider-backed trusted-contact alerts, mode-driven sharing, browser decryption, backend decryption, or public account-based product access beyond the narrow owner incident metadata -list/detail read surface for the future web client. Future notification +list/detail read surface for future production web-client use. Future notification delivery boundaries are documented in [notification-boundary.md](notification-boundary.md). @@ -125,7 +125,7 @@ by another already verified admin; there is no public recovery route or factor-bypass mode. When enabled, main `/v1` browser cookie auth uses a dedicated session cookie -for future web-client calls. Bearer auth remains supported for CLI, simulator, +for future production web-client calls. Bearer auth remains supported for CLI, simulator, and API clients. If bearer and browser-cookie credentials are sent together, the request is rejected as ambiguous. Cookie-authenticated unsafe requests require a session-bound HMAC CSRF token in the configured header; bearer diff --git a/docs/stripe-subscription-billing.md b/docs/stripe-subscription-billing.md index d4fec64..6c51ed3 100644 --- a/docs/stripe-subscription-billing.md +++ b/docs/stripe-subscription-billing.md @@ -12,7 +12,8 @@ Customer Portal boundary for the official hosted Proofline server. Official Proofline hosted accounts are intended as **cost-recovery subscription access** for the shared main server, not as a for-profit product strategy. Proofline remains an open source project maintained by one person across the -planned server, web-client, iOS-client, Android-client, and protocol surfaces. +current server and web-client surfaces plus planned iOS-client, Android-client, +and protocol surfaces. The subscription requirement for the official hosted service exists because the server, object storage, database, email delivery, monitoring, backups, diff --git a/docs/threat-model.md b/docs/threat-model.md index 216fa73..25eb91e 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -385,7 +385,8 @@ The current backend does not implement incident-mode-specific controls yet, so f they are not a complete security model. - `/v1` must not be routed as an unreviewed public catch-all; public deployment should be reviewed route group by route group. -- No iOS app, Android app, web client, production local recording client, +- No iOS app, Android app, web-client implementation in this server repository, + production local recording client, production client key storage, push notifications, SMS, Messenger integration, or public admin dashboard. The private `/admin` surface is not a complete operator UI, and the local desktop-recorder behavior in diff --git a/docs/v1-access-control.md b/docs/v1-access-control.md index 433c3e8..8e99067 100644 --- a/docs/v1-access-control.md +++ b/docs/v1-access-control.md @@ -67,7 +67,10 @@ Related source-of-truth docs: - No broad unreviewed public exposure of the current main `/v1` API. - No OAuth, JWT, public account portal, or identity-provider implementation. -- No web-client, iOS-client, Android-client, or protocol implementation. +- No web-client, iOS-client, Android-client, or protocol implementation in + this server repository. Current web-client work belongs in + `open-proofline/web-client`; iOS, Android, and protocol work remain future + companion-repository scope. - No push notification, SMS, Messenger, email notification beyond registration verification, password recovery email, or emergency-services integration. - No backend decryption, browser decryption, key escrow, trusted-contact @@ -209,7 +212,7 @@ be explicitly configured with SMTP email verification and activates accounts only after a single-use verification token is consumed. Paid registration fails closed until a future billing system exists. Bearer login returns the raw session token once for CLI/simulator/API clients. Optional browser login sets a -dedicated HttpOnly cookie for future web-client calls and does not return the +dedicated HttpOnly cookie for future production web-client calls and does not return the raw token in JSON. Stored session material is hashed. Sessions expire and can be revoked. New admin-created, `/admin` bootstrap, and open-registration accounts start as setup-incomplete for required second-factor setup; primary diff --git a/docs/v1-preview-direction.md b/docs/v1-preview-direction.md index 373fa25..4d2c507 100644 --- a/docs/v1-preview-direction.md +++ b/docs/v1-preview-direction.md @@ -69,7 +69,7 @@ backend source of truth. The current server is experimental, local-first, and ciphertext-only by default. It implements local username/password accounts, opaque server-side sessions, -optional browser cookie sessions for future web-client calls, disabled-by-default +optional browser cookie sessions for future production web-client calls, disabled-by-default public registration with SMTP-backed email verification when open mode is explicitly configured, owner-scoped incident metadata, contact public-key metadata, owner-scoped sharing grants, owner-scoped wrapped-key metadata, private diff --git a/docs/web-client-viewer-routing.md b/docs/web-client-viewer-routing.md index 1271ba0..ece163b 100644 --- a/docs/web-client-viewer-routing.md +++ b/docs/web-client-viewer-routing.md @@ -48,7 +48,7 @@ or redirect issue changes runtime behavior. They are not the long-term canonical viewer surface. `GET /i/{token}/viewer-payload` is the backend primitive intended for the -future web-client no-account viewer. Completed encrypted ZIP download routes +future production web-client no-account viewer. Completed encrypted ZIP download routes may remain backend primitives for a web-client viewer, subject to reviewed edge routing, no-store headers, rate limits, and token-redaction controls.