@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/SECURITY.md

@@ -1,275 +1,297 @@
-# Security
-
-Project acceptance paths are portable, project-relative, and realpath-contained before use, including symlink/junction escape rejection. `current` alias replacement changes only catalog metadata and never deletes or overwrites canonical evidence. `check` adds no generic file-serving route, inferred binding, source mutation, persisted check artifact, or image bytes to JSON; configured references must be explicitly approved. JSON artifact paths are project-relative.
-
-## Current controls
-
-`my-frontend-observer` launches a real, sandboxed Chromium browser
-(`src/browser/chromiumAdapter.ts`) and enforces a conservative, local-first,
-credential-free, non-destructive browser/network boundary
-(`src/safety/policy.ts`) as actual product behavior, covered by real-Chromium
-tests:
-
-- allowed schemes are `http`/`https` only;
-- allowed hosts are loopback only (`localhost`, `127.0.0.1`, `::1`, and any
-  `127.x.x.x` form) - no DNS resolution, no arbitrary "local dev host";
-- credential-bearing URLs (`user:pass@host`) are rejected;
-- the initial target, every navigation redirect, and every subresource
-  request are independently classified against the same loopback policy and
-  blocked before being contacted if unsafe;
-- popups and downloads are never followed/saved (reported as non-fatal
-  diagnostics);
-- navigation and readiness are bounded by explicit, request-configured
-  timeouts - no unbounded wait;
-- the Chromium browser/context/page are reliably closed on every exit path
-  (success, safety rejection, navigation/readiness failure, or an
-  unexpected internal error);
-- the observed target's own content/source is never modified by observation.
-
-## Comparison (`compare`, shipped as part of the published `0.4.0` package)
-
-`my-frontend-observer compare` introduces no new network or browser
-surface: it never
-launches Chromium, never navigates, and never re-observes a target - it only
-reads two local, already-persisted observation-artifact `manifest.json`
-files (`src/artifacts/artifactReader.ts`) through the same structural
-validator the observation writer uses, computes a pure in-memory
-comparison, and writes one local comparison `manifest.json`
-(`src/artifacts/comparisonArtifactWriter.ts`). Manifest content is parsed
-as JSON only and is never executed (no `eval`, no dynamic code loading from
-a manifest).
-
-## Frontend contracts (`approve-baseline`/`save-change-contract`/`evaluate-contract`, shipped as part of the published `0.5.0` package)
-
-These three commands introduce no new browser or network surface:
-`src/application/frontendContractPersistenceService.ts` and
-`src/application/frontendContractEvaluationService.ts` import nothing from
-`src/browser/` and never launch Chromium. `approve-baseline` and
-`save-change-contract` validate and persist a local JSON contract file
-(parsed as JSON only, never executed); `evaluate-contract` reads
-already-persisted local observation/comparison/contract artifacts and runs
-the pure `evaluateFrontendContract` function. None of the three navigates,
-re-observes a target, or contacts a network resource.
-
-## Bounded agent context and correlation (v0.6, released as `0.6.0`)
-
-`src/domain/boundedAgentContextProjection.ts` and
-`src/domain/boundedAgentContextCorrelation.ts` introduce no new browser or
-network surface: neither imports anything from `src/browser/`, neither
-launches Chromium or navigates, and neither performs filesystem or network
-I/O of its own. Both are pure, in-memory functions over already-captured
-observation/comparison/contract evidence plus caller-supplied candidate
-static-evidence records - the correlation module never reads a file path or
-retrieves anything itself; the caller (outside this repository) is
-responsible for however it obtained the candidate evidence it passes in.
-Neither module embeds source code snippets, redacts anything, or invokes
-another ecosystem tool (`@dailephd/my-dev-kit` is not a dependency of either
-module). Bounded runtime projections may include existing screenshot *path
-references* (never embedded bytes), consistent with every other artifact
-family's existing reference-not-embed discipline.
-
-## External visual-reference security and privacy boundary (v0.7, released as `0.7.0`)
-
-External visual-reference support (`import-reference`/`approve-reference`/
-`evaluate-reference-fidelity`, plus the programmatic correction-workflow
-coordinator) is released as part of the published `0.7.0` package. Imported reference images remain
-local-first evidence: `import-reference` reads a local file path only,
-never a URL, and no code path in this repository uploads a reference image,
-a candidate screenshot, source code, or any derived evidence to an external
-service. Reference/candidate compatibility and fidelity evaluation are pure,
-in-process computations over already-loaded artifacts - neither launches a
-network request.
-
-Bounded local-file safety for reference images is a frozen, source-verified
-policy, not an open decision: `EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS`
-(`png`/`jpeg`/`webp`, detected from header/magic bytes only, never from a
-caller-declared file extension), `EXTERNAL_REFERENCE_MAX_IMAGE_BYTES`
-(20,000,000 bytes), and `[EXTERNAL_REFERENCE_MIN_DIMENSION_PX,
-EXTERNAL_REFERENCE_MAX_DIMENSION_PX]` (`[1, 8192]` pixels per side, parsed
-from the same bounded header bytes, never a full pixel decode) are all
-enforced before any artifact is persisted; an unsupported/undetectable
-format, an over-limit file, or invalid/out-of-bound dimensions is rejected
-outright (`unsupported-image-format`/`invalid-image-dimensions`/
-`image-too-large`), never silently clamped or accepted.
-
-Reference images are treated as untrusted data, not executable content: the
-format/dimension detector never evaluates embedded code, never dynamically
-loads a script, and never treats image metadata as an instruction source -
-only bounded header-byte inspection is performed, no general-purpose image
-or video codec is invoked. Explicit, caller-supplied state
-(`--state-file`/`--applicability-file`, `theme`/`applicationState`/
-`authenticatedState`) is a closed, bounded label vocabulary with no field
-capable of holding a credential, token, cookie, session id, or authorization
-header - `authenticatedState` accepts only the literal values
-`'authenticated'`/`'unauthenticated'`.
-
-Reference artifacts and the bounded correction handoff preserve path privacy
-and boundedness: every reference/observation/binding/fidelity/context
-identity function is a pure hash of semantic content only - an operational
-file path (the image path, a `--regions-file`/`--requirements-file`/
-`--applicability-file`/`--state-file`/`--bindings-file` path, or an artifact
-root directory) is never included in any logical identity, and importing
-the same semantic reference content from two different filesystem locations
-produces the same `referenceRequestId`. The bounded coding-agent handoff
-(`ReferenceCorrectionHandoff`) never embeds raw reference image bytes, a
-full `ObservationArtifact`, or a source excerpt - only stable identifiers,
-bounded fidelity mismatch records, and evidence path *references*.
-
-Import never silently promotes an image to an approved reference: only the
-explicit `approve-reference` command (or `approveExternalReference`
-programmatically) transitions a reference out of the `'imported'` lifecycle
-state, and the v0.7 correction workflow's `prepareReferenceCorrection`/
-`reviewReferenceCorrectionAttempt` both fail closed if the supplied
-reference is not already approved. Neither function - nor anything either
-calls - ever invokes `approveExternalReference` or
-`approveAndPersistBaseline` itself; a `'pass'` review result is reported as
-`approvalEligible: true`, a plain flag, never an automatic approval action.
-
-Reference/candidate comparison and fidelity evaluation do not broaden the
-existing browser/network boundary: candidate rendering continues through the
-existing loopback-only Chromium observation path unchanged, and reference
-evaluation itself never launches a browser at all (it consumes only
-already-captured `ObservationArtifact` evidence). The v0.7 correction
-workflow never edits target source: `src/domain/referenceCorrectionWorkflow.ts`
-and everything it imports contain no filesystem-write call, no
-`child_process` invocation, and no patch-application mechanism - the actual
-source edit between review attempts is always the responsibility of an
-external implementation actor (a human or a coding agent), never this
-package's own product code. No remote AI/model-provider dependency was
-introduced anywhere in v0.7.
-
-## Interactive local viewer (v0.8, released as `0.8.0`)
-
-`my-frontend-observer view` (`src/viewerServer/`, `viewer/`) is implemented,
-tested, and formally security-reviewed. The properties below were verified
-locally/manually during implementation (Batches 1-8) and then re-verified
-through the formal pre-release security audit - see
-`docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`,
-which also found and fixed one real finding: a media filename that is
-itself a symlink/junction pointing outside the evidence root could
-previously have had its linked-to file's content served. `checkExists()`
-(`src/viewerServer/evidence/mediaResolver.ts`) now uses `lstat()` and
-rejects any non-regular-file entry, closing that escape.
-
-- **Loopback-only, fixed local origin**: the Node viewer server binds only
-  to `127.0.0.1` (never `0.0.0.0`), never a configurable remote host.
-  `--port` selects the TCP port only (default `4319`); an explicit alternate
-  port fails startup if already in use rather than silently falling back.
-- **Explicit evidence root, path containment, traversal rejection**: `--root`
-  is the only filesystem root the server ever reads from. Every artifact/
-  media route resolves a caller-supplied handle against that root through
-  the existing canonical discovery/classification path and rejects any
-  handle that would resolve outside it - the server never exposes `--root`
-  as a generic static directory or arbitrary filesystem path, and never
-  interprets an `EvidenceReference` as a filesystem path to the browser.
-- **No arbitrary filesystem browsing, no static-candidate path
-  interpretation**: the viewer offers no directory-listing or free-path
-  endpoint; every route addresses one specific, already-discovered handle.
-- **Read-only API (v0.8)**: in v0.8 every `/api/*` route rejected
-  non-`GET`/`HEAD` methods with `405` at a single top-of-handler check
-  (`src/viewerServer/httpServer.ts`). v0.9 keeps that check for every
-  inspection route and adds exactly three project-aware authoring `POST`
-  routes, described in "v0.9 local annotation write boundary" below.
-- **No target-source or evidence mutation**: the viewer never edits target
-  source and never modifies an existing Observer evidence artifact. In v0.8
-  the viewer server had no filesystem-write path at all. In v0.9 a
-  project-aware session may create new immutable annotation, change-contract,
-  and imported external-reference artifacts through the canonical writers,
-  only on an explicit authoring request. A standalone `view --root` session
-  still never writes.
-- **Binding/context files are explicit local session input, not persisted
-  evidence**: `--bindings-file`/`--context-file` are read once at startup,
-  validated through the existing canonical validators, held only in server
-  memory, and never written into any Observer artifact or exposed as a
-  filesystem path to the browser. The viewer never runs
-  `@dailephd/my-dev-kit` and never rebuilds a bounded context or its
-  correlation from these files - it only displays what it was given.
-- **PWA shell cache scope**: the service worker precaches only the built
-  application shell (HTML/JS/CSS/icons/manifest); `navigateFallbackDenylist`
-  excludes every `/api/` route from the precache, verified both statically
-  (built `sw.js`) and live (real Chromium: zero Cache Storage entries under
-  any `/api/` pathname after normal use - see
-  `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`).
-- **Server-down stale-evidence protection**: proven in real Chromium - after
-  the server is stopped and the page reloaded, the app shell may still
-  render from the precache, but the evidence-dependent surface shows an
-  explicit unavailable state, never previously-fetched evidence presented
-  as current.
-
-## v0.9 local annotation write boundary (released in 0.9.0)
-
-v0.9 adds a narrow local write surface to the viewer. It is released in
-`0.9.0`. It is a same-machine capability boundary for
-one local viewer session. It is not remote account authentication and does not
-protect against other software already running as the same user.
-
-- **Loopback only**: the viewer still binds only to `127.0.0.1`.
-- **Project-aware authoring only**: authoring is enabled only when `view` runs
-  without `--root` inside an initialized project. The standalone arbitrary-root
-  viewer (`view --root <root>`) stays read-only. Its
-  `GET /api/authoring/session` reports `enabled: false`, and every authoring
-  `POST` returns `403`.
-- **Session capability**: each project-aware server creates a random 32-byte
-  token (64 hex characters) in memory. It is handed out by
-  `GET /api/authoring/session` only on the exact expected loopback `Host`, as a
-  defense against DNS rebinding. The viewer keeps it only in React memory. It
-  is never persisted, never written into evidence, and never cached.
-- **Request checks, in order**: exact `Host`, exact same-origin `Origin`, the
-  `x-frontend-observer-authoring-token` header compared in constant time,
-  `content-type: application/json`, identity `content-encoding` only, a
-  256 KiB (`262144` byte) body limit, valid JSON, and a closed request shape
-  with unknown fields rejected.
-- **Exactly three `POST` routes**: `POST /api/annotations`,
-  `POST /api/annotations/:handle/promote-contract`, and
-  `POST /api/annotations/:handle/materialize-reference`. `PUT`, `PATCH`, and
-  `DELETE` stay unsupported everywhere. Any other `POST` returns `405`.
-- **No permissive CORS**: no `Access-Control-Allow-*` headers are sent, so a
-  page from any other origin cannot read the capability or send a JSON
-  authoring request. A real-Chromium test proves this for all three routes.
-- **Server-side resolution only**: the browser sends evidence handles and item
-  ids, never output paths. The server resolves handles through canonical
-  discovery with path containment and writes only under the project's managed
-  evidence root (`annotations`, `contracts`, and `references`) through the
-  canonical writers.
-- **Serialized writes**: all three routes share one write queue per session.
-  Annotation revisions use stale-parent conflict detection instead of
-  last-write-wins.
-- **No automatic approval**: promotion never approves a baseline, and
-  materialization never approves a reference or changes project reference
-  acceptance. Contract activation for `check` happens only on explicit
-  request.
-- **No caching of authority**: authoring and evidence API responses use
-  `cache-control: no-store`, and the service worker never caches `/api/`
-  routes, including the new `POST` routes.
-- **Safe media**: annotation overlay media is served only after the stored
-  SVG is re-rendered from the canonical artifact and verified. It uses a
-  script-blocking `content-security-policy` with `sandbox` and `nosniff`.
-  Existing media containment and symlink checks apply unchanged.
-- **Temporary directories**: evidence discovery skips writer temporary
-  `.tmp-*` directories, so a partially written artifact is never presented as
-  evidence.
-
-## Not yet addressed
-
-Certificate-failure-specific handling, permission-prompt-specific handling
-(Chromium's default deny-all applies; no permission is ever explicitly
-granted), and any non-loopback/remote browsing mode remain unimplemented and
-out of scope. `@dailephd/my-frontend-observer@0.9.0` is published to npm, and a
-pre-release readiness CI workflow (Windows/Linux/macOS packed-candidate
-validation, now covering the v0.8 viewer alongside every earlier version's
-packed behavior) exists (see `docs/CI_CD.md`). The v0.7 external-reference/
-correction-workflow security properties above are released as part of
-`0.7.0`, following a completed cross-platform pre-release security
-validation stage (see `docs/reports/v0.7-pre-release-readiness.md`). The
-v0.8 interactive viewer's security boundary described above is released as
-part of `0.8.0`, following a completed formal pre-release cross-platform
-security validation stage (see
-`docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`).
-Symlink/junction filesystem-escape handling for the viewer's raw-evidence
-routes is now exercised by a dedicated regression test
-(`tests/unit/viewerEvidenceServer.test.ts`), which caught and led to the fix
-described above. The v0.9 annotation write boundary described above is
-implemented and covered by local security tests, but its formal
-cross-platform pre-release security validation has not run yet. None of this
-expands the security scope above: remote browsing, certificate handling, and
-permission-prompt handling remain separate, unimplemented concerns.
+# Security
+
+Project acceptance paths are portable, project-relative, and realpath-contained before use, including symlink/junction escape rejection. `current` alias replacement changes only catalog metadata and never deletes or overwrites canonical evidence. `check` adds no generic file-serving route, inferred binding, source mutation, persisted check artifact, or image bytes to JSON; configured references must be explicitly approved. JSON artifact paths are project-relative.
+
+## Current controls
+
+`my-frontend-observer` launches a real, sandboxed Chromium browser
+(`src/browser/chromiumAdapter.ts`) and enforces a conservative, local-first,
+credential-free, non-destructive browser/network boundary
+(`src/safety/policy.ts`) as actual product behavior, covered by real-Chromium
+tests:
+
+- allowed schemes are `http`/`https` only;
+- allowed hosts are loopback only (`localhost`, `127.0.0.1`, `::1`, and any
+  `127.x.x.x` form) - no DNS resolution, no arbitrary "local dev host";
+- credential-bearing URLs (`user:pass@host`) are rejected;
+- the initial target, every navigation redirect, and every subresource
+  request are independently classified against the same loopback policy and
+  blocked before being contacted if unsafe;
+- popups and downloads are never followed/saved (reported as non-fatal
+  diagnostics);
+- navigation and readiness are bounded by explicit, request-configured
+  timeouts - no unbounded wait;
+- the Chromium browser/context/page are reliably closed on every exit path
+  (success, safety rejection, navigation/readiness failure, or an
+  unexpected internal error);
+- the observed target's own content/source is never modified by observation.
+
+## Comparison (`compare`, shipped as part of the published `0.4.0` package)
+
+`my-frontend-observer compare` introduces no new network or browser
+surface: it never
+launches Chromium, never navigates, and never re-observes a target - it only
+reads two local, already-persisted observation-artifact `manifest.json`
+files (`src/artifacts/artifactReader.ts`) through the same structural
+validator the observation writer uses, computes a pure in-memory
+comparison, and writes one local comparison `manifest.json`
+(`src/artifacts/comparisonArtifactWriter.ts`). Manifest content is parsed
+as JSON only and is never executed (no `eval`, no dynamic code loading from
+a manifest).
+
+## Frontend contracts (`approve-baseline`/`save-change-contract`/`evaluate-contract`, shipped as part of the published `0.5.0` package)
+
+These three commands introduce no new browser or network surface:
+`src/application/frontendContractPersistenceService.ts` and
+`src/application/frontendContractEvaluationService.ts` import nothing from
+`src/browser/` and never launch Chromium. `approve-baseline` and
+`save-change-contract` validate and persist a local JSON contract file
+(parsed as JSON only, never executed); `evaluate-contract` reads
+already-persisted local observation/comparison/contract artifacts and runs
+the pure `evaluateFrontendContract` function. None of the three navigates,
+re-observes a target, or contacts a network resource.
+
+## Bounded agent context and correlation (v0.6, released as `0.6.0`)
+
+`src/domain/boundedAgentContextProjection.ts` and
+`src/domain/boundedAgentContextCorrelation.ts` introduce no new browser or
+network surface: neither imports anything from `src/browser/`, neither
+launches Chromium or navigates, and neither performs filesystem or network
+I/O of its own. Both are pure, in-memory functions over already-captured
+observation/comparison/contract evidence plus caller-supplied candidate
+static-evidence records - the correlation module never reads a file path or
+retrieves anything itself; the caller (outside this repository) is
+responsible for however it obtained the candidate evidence it passes in.
+Neither module embeds source code snippets, redacts anything, or invokes
+another ecosystem tool (`@dailephd/my-dev-kit` is not a dependency of either
+module). Bounded runtime projections may include existing screenshot *path
+references* (never embedded bytes), consistent with every other artifact
+family's existing reference-not-embed discipline.
+
+## External visual-reference security and privacy boundary (v0.7, released as `0.7.0`)
+
+External visual-reference support (`import-reference`/`approve-reference`/
+`evaluate-reference-fidelity`, plus the programmatic correction-workflow
+coordinator) is released as part of the published `0.7.0` package. Imported reference images remain
+local-first evidence: `import-reference` reads a local file path only,
+never a URL, and no code path in this repository uploads a reference image,
+a candidate screenshot, source code, or any derived evidence to an external
+service. Reference/candidate compatibility and fidelity evaluation are pure,
+in-process computations over already-loaded artifacts - neither launches a
+network request.
+
+Bounded local-file safety for reference images is a frozen, source-verified
+policy, not an open decision: `EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS`
+(`png`/`jpeg`/`webp`, detected from header/magic bytes only, never from a
+caller-declared file extension), `EXTERNAL_REFERENCE_MAX_IMAGE_BYTES`
+(20,000,000 bytes), and `[EXTERNAL_REFERENCE_MIN_DIMENSION_PX,
+EXTERNAL_REFERENCE_MAX_DIMENSION_PX]` (`[1, 8192]` pixels per side, parsed
+from the same bounded header bytes, never a full pixel decode) are all
+enforced before any artifact is persisted; an unsupported/undetectable
+format, an over-limit file, or invalid/out-of-bound dimensions is rejected
+outright (`unsupported-image-format`/`invalid-image-dimensions`/
+`image-too-large`), never silently clamped or accepted.
+
+Reference images are treated as untrusted data, not executable content: the
+format/dimension detector never evaluates embedded code, never dynamically
+loads a script, and never treats image metadata as an instruction source -
+only bounded header-byte inspection is performed, no general-purpose image
+or video codec is invoked. Explicit, caller-supplied state
+(`--state-file`/`--applicability-file`, `theme`/`applicationState`/
+`authenticatedState`) is a closed, bounded label vocabulary with no field
+capable of holding a credential, token, cookie, session id, or authorization
+header - `authenticatedState` accepts only the literal values
+`'authenticated'`/`'unauthenticated'`.
+
+Reference artifacts and the bounded correction handoff preserve path privacy
+and boundedness: every reference/observation/binding/fidelity/context
+identity function is a pure hash of semantic content only - an operational
+file path (the image path, a `--regions-file`/`--requirements-file`/
+`--applicability-file`/`--state-file`/`--bindings-file` path, or an artifact
+root directory) is never included in any logical identity, and importing
+the same semantic reference content from two different filesystem locations
+produces the same `referenceRequestId`. The bounded coding-agent handoff
+(`ReferenceCorrectionHandoff`) never embeds raw reference image bytes, a
+full `ObservationArtifact`, or a source excerpt - only stable identifiers,
+bounded fidelity mismatch records, and evidence path *references*.
+
+Import never silently promotes an image to an approved reference: only the
+explicit `approve-reference` command (or `approveExternalReference`
+programmatically) transitions a reference out of the `'imported'` lifecycle
+state, and the v0.7 correction workflow's `prepareReferenceCorrection`/
+`reviewReferenceCorrectionAttempt` both fail closed if the supplied
+reference is not already approved. Neither function - nor anything either
+calls - ever invokes `approveExternalReference` or
+`approveAndPersistBaseline` itself; a `'pass'` review result is reported as
+`approvalEligible: true`, a plain flag, never an automatic approval action.
+
+Reference/candidate comparison and fidelity evaluation do not broaden the
+existing browser/network boundary: candidate rendering continues through the
+existing loopback-only Chromium observation path unchanged, and reference
+evaluation itself never launches a browser at all (it consumes only
+already-captured `ObservationArtifact` evidence). The v0.7 correction
+workflow never edits target source: `src/domain/referenceCorrectionWorkflow.ts`
+and everything it imports contain no filesystem-write call, no
+`child_process` invocation, and no patch-application mechanism - the actual
+source edit between review attempts is always the responsibility of an
+external implementation actor (a human or a coding agent), never this
+package's own product code. No remote AI/model-provider dependency was
+introduced anywhere in v0.7.
+
+## Interactive local viewer (v0.8, released as `0.8.0`)
+
+`my-frontend-observer view` (`src/viewerServer/`, `viewer/`) is implemented,
+tested, and formally security-reviewed. The properties below were verified
+locally/manually during implementation (Batches 1-8) and then re-verified
+through the formal pre-release security audit - see
+`docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`,
+which also found and fixed one real finding: a media filename that is
+itself a symlink/junction pointing outside the evidence root could
+previously have had its linked-to file's content served. `checkExists()`
+(`src/viewerServer/evidence/mediaResolver.ts`) now uses `lstat()` and
+rejects any non-regular-file entry, closing that escape.
+
+- **Loopback-only, fixed local origin**: the Node viewer server binds only
+  to `127.0.0.1` (never `0.0.0.0`), never a configurable remote host.
+  `--port` selects the TCP port only (default `4319`); an explicit alternate
+  port fails startup if already in use rather than silently falling back.
+- **Explicit evidence root, path containment, traversal rejection**: `--root`
+  is the only filesystem root the server ever reads from. Every artifact/
+  media route resolves a caller-supplied handle against that root through
+  the existing canonical discovery/classification path and rejects any
+  handle that would resolve outside it - the server never exposes `--root`
+  as a generic static directory or arbitrary filesystem path, and never
+  interprets an `EvidenceReference` as a filesystem path to the browser.
+- **No arbitrary filesystem browsing, no static-candidate path
+  interpretation**: the viewer offers no directory-listing or free-path
+  endpoint; every route addresses one specific, already-discovered handle.
+- **Read-only API (v0.8)**: in v0.8 every `/api/*` route rejected
+  non-`GET`/`HEAD` methods with `405` at a single top-of-handler check
+  (`src/viewerServer/httpServer.ts`). v0.9 keeps that check for every
+  inspection route and adds exactly three project-aware authoring `POST`
+  routes, described in "v0.9 local annotation write boundary" below.
+- **No target-source or evidence mutation**: the viewer never edits target
+  source and never modifies an existing Observer evidence artifact. In v0.8
+  the viewer server had no filesystem-write path at all. In v0.9 a
+  project-aware session may create new immutable annotation, change-contract,
+  and imported external-reference artifacts through the canonical writers,
+  only on an explicit authoring request. A standalone `view --root` session
+  still never writes.
+- **Binding/context files are explicit local session input, not persisted
+  evidence**: `--bindings-file`/`--context-file` are read once at startup,
+  validated through the existing canonical validators, held only in server
+  memory, and never written into any Observer artifact or exposed as a
+  filesystem path to the browser. The viewer never runs
+  `@dailephd/my-dev-kit` and never rebuilds a bounded context or its
+  correlation from these files - it only displays what it was given.
+- **PWA shell cache scope**: the service worker precaches only the built
+  application shell (HTML/JS/CSS/icons/manifest); `navigateFallbackDenylist`
+  excludes every `/api/` route from the precache, verified both statically
+  (built `sw.js`) and live (real Chromium: zero Cache Storage entries under
+  any `/api/` pathname after normal use - see
+  `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`).
+- **Server-down stale-evidence protection**: proven in real Chromium - after
+  the server is stopped and the page reloaded, the app shell may still
+  render from the precache, but the evidence-dependent surface shows an
+  explicit unavailable state, never previously-fetched evidence presented
+  as current.
+
+## v0.9 local annotation write boundary (released in 0.9.0)
+
+v0.9 adds a narrow local write surface to the viewer. It is released in
+`0.9.0`. It is a same-machine capability boundary for
+one local viewer session. It is not remote account authentication and does not
+protect against other software already running as the same user.
+
+- **Loopback only**: the viewer still binds only to `127.0.0.1`.
+- **Project-aware authoring only**: authoring is enabled only when `view` runs
+  without `--root` inside an initialized project. The standalone arbitrary-root
+  viewer (`view --root <root>`) stays read-only. Its
+  `GET /api/authoring/session` reports `enabled: false`, and every authoring
+  `POST` returns `403`.
+- **Session capability**: each project-aware server creates a random 32-byte
+  token (64 hex characters) in memory. It is handed out by
+  `GET /api/authoring/session` only on the exact expected loopback `Host`, as a
+  defense against DNS rebinding. The viewer keeps it only in React memory. It
+  is never persisted, never written into evidence, and never cached.
+- **Request checks, in order**: exact `Host`, exact same-origin `Origin`, the
+  `x-frontend-observer-authoring-token` header compared in constant time,
+  `content-type: application/json`, identity `content-encoding` only, a
+  256 KiB (`262144` byte) body limit, valid JSON, and a closed request shape
+  with unknown fields rejected.
+- **Exactly three v0.9 `POST` routes**: v0.9 introduced
+  `POST /api/annotations`,
+  `POST /api/annotations/:handle/promote-contract`, and
+  `POST /api/annotations/:handle/materialize-reference`. `PUT`, `PATCH`, and
+  `DELETE` stay unsupported everywhere. The implemented and released v0.10
+  routes extend this same gate as described below.
+- **No permissive CORS**: no `Access-Control-Allow-*` headers are sent, so a
+  page from any other origin cannot read the capability or send a JSON
+  authoring request. A real-Chromium test proves this for all three routes.
+- **Server-side resolution only**: the browser sends evidence handles and item
+  ids, never output paths. The server resolves handles through canonical
+  discovery with path containment and writes only under the project's managed
+  evidence root (`annotations`, `contracts`, and `references`) through the
+  canonical writers.
+- **Serialized writes**: all three routes share one write queue per session.
+  Annotation revisions use stale-parent conflict detection instead of
+  last-write-wins.
+- **No automatic approval**: promotion never approves a baseline, and
+  materialization never approves a reference or changes project reference
+  acceptance. Contract activation for `check` happens only on explicit
+  request.
+- **No caching of authority**: authoring and evidence API responses use
+  `cache-control: no-store`, and the service worker never caches `/api/`
+  routes, including the new `POST` routes.
+- **Safe media**: annotation overlay media is served only after the stored
+  SVG is re-rendered from the canonical artifact and verified. It uses a
+  script-blocking `content-security-policy` with `sandbox` and `nosniff`.
+  Existing media containment and symlink checks apply unchanged.
+- **Temporary directories**: evidence discovery skips writer temporary
+  `.tmp-*` directories, so a partially written artifact is never presented as
+  evidence.
+
+## v0.10 Visual Change authoring boundary
+
+v0.10 extends only the project-aware guarded `POST` surface. It adds explicit
+reference approval and actual/reference workflow creation, plus workflow
+activation, canonical check, restore, handoff preparation, human review, and
+recording of already-existing governance results. Every route reuses the same
+exact Host, Origin, memory-only capability token, JSON content type,
+compression rejection, body limit, closed request-shape, serialized-write,
+path-containment, and `no-store` controls. Standalone `view --root` remains
+read-only, and the service worker continues to cache no `/api/` response.
+
+The additional surface does not grant source-edit or external-process
+authority. Observer never edits target source, executes a coding agent, invokes
+my-dev-kit, or contacts/controls an orchestrator. Optional orchestrator fields
+are bounded traceability metadata only. Handoffs are generated in memory and
+are not a persisted evidence family. Review acceptance requires the latest
+canonical Observer check to be PASS; it cannot approve a baseline/reference or
+restore project acceptance. Governance recording can reference only a
+separately persisted canonical approval and does not perform that approval.
+
+## Not yet addressed
+
+Certificate-failure-specific handling, permission-prompt-specific handling
+(Chromium's default deny-all applies; no permission is ever explicitly
+granted), and any non-loopback/remote browsing mode remain unimplemented and
+out of scope. `@dailephd/my-frontend-observer@0.10.1` is the current release. A
+pre-release readiness CI workflow (Windows/Linux/macOS packed-candidate
+validation, now covering the v0.8 viewer alongside every earlier version's
+packed behavior) exists (see `docs/CI_CD.md`). The v0.7 external-reference/
+correction-workflow security properties above are released as part of
+`0.7.0`, following a completed cross-platform pre-release security
+validation stage (see `docs/reports/v0.7-pre-release-readiness.md`). The
+v0.8 interactive viewer's security boundary described above is released as
+part of `0.8.0`, following a completed formal pre-release cross-platform
+security validation stage (see
+`docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`).
+Symlink/junction filesystem-escape handling for the viewer's raw-evidence
+routes is now exercised by a dedicated regression test
+(`tests/unit/viewerEvidenceServer.test.ts`), which caught and led to the fix
+described above. The v0.9 annotation write boundary described above is
+implemented and covered by local security tests; formal cross-platform
+pre-release validation was completed before release. None of this
+expands the security scope above: remote browsing, certificate handling, and
+permission-prompt handling remain separate, unimplemented concerns.