@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-batch2-viewer-annotation-authoring-boundary.md

@@ -0,0 +1,438 @@
+# v0.9 Batch 2 Report: Viewer Annotation Authoring Boundary
+
+## 1. VERDICT
+
+PASS_V0_9_BATCH2_VIEWER_ANNOTATION_AUTHORING_BOUNDARY
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Branch: `master`
+3. Starting HEAD: `3618c7b0d2a9cdec80004be4c9cc5bb823bb42f4`
+4. Ending HEAD before the final commit: `3618c7b0d2a9cdec80004be4c9cc5bb823bb42f4`
+5. Package version: `0.8.1` (unchanged in `package.json` and `package-lock.json`)
+6. Viewer protocol version: `1.1.0` (was `1.0.0`)
+
+## 3. Prompt 1 entry gate
+
+1. Prompt 1 verdict: `PASS_V0_9_BATCH1_VISUAL_ANNOTATION_FOUNDATION`
+2. Prompt 1 commit: `3618c7b0d2a9cdec80004be4c9cc5bb823bb42f4`
+3. Annotation artifact kind: `my-frontend-observer/visual-annotation`
+4. Annotation schema: `1.0.0`
+5. Preflight found a clean tracked worktree on `master` at the required HEAD.
+6. `git ls-files -v docs/reports/v0.9-architecture-retrieval.md` printed `S`
+   at entry and again before commit. The `skip-worktree` state was preserved.
+   The user's local copy of that report was not read into this commit or
+   changed. The preserved copies under
+   `.my-dev-kit-workflow/adhoc/preserved-local-docs/` were not touched.
+7. No pull, merge, rebase, reset, stash, or clean was run.
+
+## 4. Annotation evidence discovery
+
+1. `ArtifactFamily` in `src/viewerServer/evidence/classify.ts` gains exactly
+   `'visual-annotation'`, mapped to `VisualAnnotationArtifact`.
+2. Classification for `artifactKind === my-frontend-observer/visual-annotation`:
+   1. A schema version other than `1.0.0` gives `unsupported-version` with
+      family `visual-annotation`.
+   2. Otherwise the canonical `readVisualAnnotationArtifact` runs. If it
+      succeeds, the record is `supported`. If it fails, the record is
+      `invalid-structure` with family `visual-annotation`.
+3. The classifier copies no annotation validation. The reader stays the only
+   authority, including its owned-overlay SHA-256 check.
+4. `src/viewerServer/evidence/handles.ts` gains the `visual-annotation` handle
+   slug. This additional file was required because the slug table is typed as
+   a complete record over `ArtifactFamily`.
+
+## 5. Annotation metadata projection
+
+For a supported annotation, `buildMetadataRecord` returns:
+
+1. `logicalId`: `annotationId`
+2. `schemaVersion` and `producerVersion` from the artifact
+3. `annotationSourceKind`: `source.kind`
+4. `annotationItemCount`: `items.length`
+5. `annotationConfirmedItemCount`: the number of items whose interpretation
+   state is `confirmed`
+6. `media`: one `annotation-overlay` summary (a cheap availability check only)
+7. `relatedIds`: `sourceObservationId` or `sourceReferenceId`, plus
+   `supersedesAnnotationId` when present
+
+Items are never embedded in metadata. Observation alias metadata is applied
+only to observation records, so an annotation record never gets an alias.
+
+## 6. Annotation media resolution
+
+1. `MediaSummary.role` and `MediaRole` gain exactly `annotation-overlay`.
+2. `resolveMedia` accepts the role only for the `visual-annotation` family. It
+   resolves only `artifact.overlay.path` through `resolveContainedFile`. It
+   uses `lstat` and requires a regular file. The MIME type is `image/svg+xml`.
+3. It rejects a missing file, a directory, a symlink or other non-regular
+   entry, an unsafe path, the wrong family, an unknown handle, and an unknown
+   role. A browser-supplied filename is never used.
+4. Defense in depth (additional local decision): the served bytes must equal
+   `renderVisualAnnotationOverlaySvg(artifact.source, artifact.items)` exactly.
+   Otherwise the overlay is refused. A hand-edited SVG whose digest was copied
+   into the manifest therefore cannot be served from the viewer origin.
+5. Defense in depth (additional local decision): every `image/svg+xml` media
+   response also carries
+   `content-security-policy: default-src 'none'; style-src 'unsafe-inline'; sandbox`
+   and `x-content-type-options: nosniff`. Even direct navigation to the
+   overlay cannot run script in the viewer origin, where the authoring token
+   lives. Existing media types (PNG, JPEG, WebP) get no new headers.
+
+## 7. Annotation source-view projection
+
+1. `src/viewerServer/evidence/index.ts` adds `findObservationByIdentity(root,
+   observationId, requestId)` and `findExternalReferenceByIdentity(root,
+   referenceId, referenceRequestId)`. Both use `discoverManifests`,
+   `MAX_INDEX_RECORDS`, `classifyManifest`, and `encodeArtifactHandle`. Both
+   require the logical id and the request id to match.
+2. Local decision: when more than one exact match exists, both return
+   `undefined` instead of picking one. This follows the existing
+   `linkedEvidence.ts` rule of never choosing silently.
+3. New `src/viewerServer/evidence/annotationView.ts` provides
+   `getAnnotationView(root, annotationHandle)`. It loads the annotation through
+   `loadArtifactByHandle` and requires the `visual-annotation` family. It then
+   resolves the source:
+   1. A runtime source maps to the observation handle with media role
+      `screenshot`.
+   2. An imported reference maps to the imported handle with role `image`.
+   3. An approved reference maps to the approved handle with role `source-image`.
+4. A missing or ambiguous source returns `source.status: 'unavailable'` with a
+   reason. The annotation itself stays loadable.
+5. `GET` and `HEAD` `/api/annotations/:handle/view` answer with no-store JSON:
+   1. 400 for a malformed handle.
+   2. 404 for an unknown handle.
+   3. 409 when the handle is not an annotation or not currently loadable.
+   4. 200 otherwise, including when the source is unavailable.
+
+## 8. Project-aware authoring mode
+
+1. `StartViewerOptions` gains `authoringProjectRoot?: string`. When it is
+   absent, the viewer is read-only exactly as before.
+2. When it is supplied, `startViewer` calls the existing
+   `loadProjectViewerState`, which validates the project configuration and
+   alias catalog. It then requires the viewer root to be that project's
+   `projectEvidenceRoot`. The comparison uses resolved paths, with a
+   real-path fallback for drive-letter casing and symlinked parents.
+3. On any mismatch or invalid project, the viewer does not start. It returns
+   the existing `viewer-root-invalid` diagnostic. No new diagnostic code was
+   added.
+4. Authoring is never inferred from the root alone.
+5. `loadProjectViewerState` now also returns `projectRoot`, resolved once.
+   Alias behavior is unchanged.
+6. `src/projectWorkflow/projectPaths.ts` adds `projectAnnotationsRoot(projectRoot)`
+   and `annotationOutputLocation()`. The latter returns
+   `.frontend-observer/evidence/annotations`. Observation paths, project
+   config schema, and catalog schema are unchanged. No migration was added.
+7. In `src/cli.ts`, the normal `my-frontend-observer view` now also passes
+   `authoringProjectRoot` from `loadProjectViewerState`. `view --root <root>`
+   passes nothing new, so it stays read-only. No flag, command, or help text
+   was added or changed.
+
+## 9. Authoring session capability
+
+1. New `src/viewerServer/authoringSecurity.ts` defines:
+   1. `VIEWER_AUTHORING_TOKEN_BYTES = 32`
+   2. `VIEWER_AUTHORING_TOKEN_HEADER = 'x-frontend-observer-authoring-token'`
+   3. `MAX_ANNOTATION_AUTHORING_BODY_BYTES = 256 * 1024`
+2. One token is created per authoring server session with
+   `randomBytes(32).toString('hex')`, which gives 64 lowercase hex characters.
+   It lives only in the in-memory `ViewerAuthoringSession`
+   `{ projectRoot, token, expectedHost, expectedOrigin }`. It is never
+   persisted, never put in a cookie, storage, a URL, a cache, or an artifact,
+   and never logged.
+3. `expectedHost` and `expectedOrigin` are set after the listener binds to its
+   actual port. They are `127.0.0.1:<port>` and `http://127.0.0.1:<port>`.
+   Before that they are empty strings, and an empty expectation matches
+   nothing.
+4. `GET` and `HEAD` `/api/authoring/session` always send `cache-control: no-store`:
+   1. A read-only viewer returns `{ ok: true, enabled: false }`.
+   2. An authoring viewer returns `{ ok: true, enabled: true, token }` and
+      nothing else.
+5. Defense in depth (additional local decision): in authoring mode the session
+   route returns 403 unless the `Host` header equals `expectedHost`. This keeps
+   the token away from a DNS-rebinding page.
+
+## 10. POST security policy
+
+`POST /api/annotations` runs these checks in order:
+
+1. Authoring disabled gives 403.
+2. `Host` must equal `expectedHost`, else 403.
+3. `Origin` must equal `expectedOrigin` exactly, else 403. A missing Origin is
+   also 403.
+4. The token header must match exactly, else 403. The comparison uses
+   `timingSafeEqual` when lengths match, and the response does not say which
+   part differed.
+5. `Content-Type` must be `application/json`, optionally with a UTF-8 charset,
+   compared case-insensitively. Anything else gives 415.
+6. `Content-Encoding` present and not `identity` gives 415.
+7. A declared `Content-Length` above 262144 gives 413 before any body is read.
+   An undeclared chunked body stops being collected once it passes 262144
+   bytes and also gives 413. Rejections send `connection: close`, so the
+   server stops receiving further body bytes.
+8. Malformed JSON gives 400.
+9. Unknown top-level request fields give 400.
+
+Method policy:
+
+1. `POST` is accepted only for `/api/annotations`. `GET` or `HEAD` on that path
+   returns 405 with `Allow: POST`.
+2. `POST` on any other path returns 405 with `Allow: GET, HEAD`. This includes
+   the Prompt 5 and Prompt 6 route names, which do not exist.
+3. `PUT`, `PATCH`, and `DELETE` return 405 everywhere.
+4. No CORS headers are sent.
+
+## 11. Save request contract
+
+`SaveAnnotationRequest` is `{ sourceHandle, parentAnnotationHandle?, items }`,
+defined in the new `src/viewerServer/annotationAuthoring.ts`.
+
+1. Exactly those three top-level keys are allowed.
+2. `sourceHandle` must be a non-empty string.
+3. `parentAnnotationHandle`, when present, must be a non-empty string.
+4. `items` must be an array. Its content is validated by the canonical
+   annotation domain inside `persistVisualAnnotation`.
+5. The browser cannot supply a source path, output location, project root,
+   annotation id, request id, overlay path or SHA, `createdAt`, producer, or
+   alias.
+
+## 12. Server-owned source construction
+
+1. `sourceHandle` is resolved through `loadArtifactByHandle`.
+   1. Unknown gives 404.
+   2. Not loadable gives 409.
+   3. A family other than observation, imported reference, or approved
+      reference gives 409.
+2. Observation: the source is built exactly as the prompt specifies. The
+   screenshot must be `available` or `partial`, otherwise 409. The coordinate
+   space is `requestConfig.viewport` in CSS pixels. It never uses screenshot
+   device pixels or devicePixelRatio.
+3. Imported reference: built from `referenceId` and `image.sha256`, `width`,
+   `height`. The image owner is the reference itself.
+4. Approved reference: built from `sourceReference.referenceId` and
+   `sourceReference.image`.
+5. An alias is never used as source identity.
+
+## 13. Server-owned output location
+
+1. The service calls `persistVisualAnnotation` exactly once with
+   `outputLocation: annotationOutputLocation()` and
+   `cwd: session.projectRoot`. Artifacts land in
+   `.frontend-observer/evidence/annotations/<annotationId>/`.
+2. The server never calls the writer directly. It never builds identity or
+   overlays itself.
+3. A 201 response is exactly
+   `{ ok, annotationId, annotationRequestId, handle }`. The handle is
+   `encodeArtifactHandle('visual-annotation', 'annotations/<annotationId>')`.
+4. The response carries no absolute path, manifest or overlay path, project
+   root, or token.
+
+## 14. Revision and stale-edit behavior
+
+1. With no parent, `supersedesAnnotationId` is undefined.
+2. With a parent, the parent is resolved through `loadArtifactByHandle` and
+   must be `visual-annotation`.
+   1. Unknown gives 404.
+   2. Not an annotation, or not loadable, gives 409.
+3. `isSameVisualAnnotationSource` compares every canonical source field for
+   each source kind. A mismatch gives 409. It is a pure local helper and is
+   not exported from the package.
+4. Stale check: a bounded scan (`discoverManifests`, `MAX_INDEX_RECORDS`,
+   `classifyManifest`) looks for any supported annotation whose
+   `supersedesAnnotationId` equals the parent id.
+   1. Any such child gives 409, including when several children exist.
+   2. No child is ever selected by timestamp.
+5. Local decision: if discovery was truncated, the lineage cannot be proven
+   free of children. The save fails closed with 409 instead of silently
+   branching.
+6. Local decision: saves are serialized per authoring session with an
+   in-process promise queue. The stale check and the write cannot interleave.
+   A test sends three concurrent revisions of one parent and gets exactly one
+   201 and two 409s.
+7. The parent artifact is never modified.
+
+## 15. HTTP status behavior
+
+1. 201: a save succeeded.
+2. 400: malformed JSON, invalid request shape, an unknown top-level field, a
+   malformed view or media handle, or an invalid Content-Length.
+3. 403: authoring disabled, or a Host, Origin, or token failure. Also the
+   session route on an unexpected Host.
+4. 404: unknown source handle, unknown parent handle, unknown view or media
+   handle, or a rejected media role or file.
+5. 405: an unsupported method or route combination.
+6. 409: source not loadable or not annotatable, parent not an annotation,
+   parent source mismatch, parent already has a child, lineage unverifiable,
+   or a view handle that is not a loadable annotation.
+7. 413: body over 262144 bytes.
+8. 415: wrong content type or a compressed body.
+9. 422: canonical annotation validation failure, such as out-of-frame
+   geometry or a cross-domain item.
+10. 500: persistence failure, returned with a generic message and no stack
+    trace or path.
+
+## 16. Tests added/modified
+
+### 16.1 Added
+
+1. `tests/support/annotationAuthoringFixtures.ts` holds shared helpers. They
+   build real evidence through the canonical writers, create a real
+   initialized project, and send raw `node:http` requests with full Host and
+   Origin control.
+2. `tests/unit/viewerAnnotationEvidence.test.ts` (15 tests) covers:
+   1. Discovery A to E: supported metadata and counts, unsupported schema,
+      invalid structure, full artifact load, and no alias projection.
+   2. Media: exact SVG, headers, and HEAD.
+   3. Media rejections: wrong family, unknown role, malformed handle, unknown
+      handle, traversal handle, missing overlay, directory overlay, symlink
+      overlay, and a hand-edited overlay whose digest was updated.
+   4. Source view A to E: runtime, imported, approved, missing source, and
+      identity mismatch.
+   5. View status mapping and write-method rejection.
+3. `tests/unit/viewerAuthoringSecurity.test.ts` (14 tests) covers:
+   1. The constants and protocol version.
+   2. Token format and freshness, and content-type parsing.
+   3. The session route when disabled, enabled, and on a rebinding Host.
+   4. Security cases A to Q, including token lifetime across two servers.
+   5. The exact 262144-byte body and 413 for declared and chunked oversize.
+   6. The method matrix, and read-only routes still working in authoring mode.
+4. `tests/unit/viewerAnnotationAuthoring.test.ts` (15 tests) covers:
+   1. Project-aware cases A to D.
+   2. Save cases A to C, plus the 404, 409, and 422 mappings.
+   3. Revision cases A to D, plus concurrent revisions.
+   4. Request-shape and same-source helper unit tests.
+
+### 16.2 Modified
+
+1. `tests/unit/projectWorkflow.test.ts` gains 2 tests for the annotation path
+   helpers and for `loadProjectViewerState` returning `projectRoot`.
+2. `tests/unit/cliViewDispatch.test.ts` gains 1 test. Project-aware `view`
+   passes `authoringProjectRoot`, and `view --root` does not.
+3. `tests/browser/projectWorkflowViewer.test.ts` gains 1 real-Chromium test.
+   A same-origin page gets the token and saves an annotation (201) with the
+   Origin Chromium really sends. The same page gets 403 without the token, and
+   403 on a read-only viewer.
+4. `tests/browser/pwaHardening.test.ts`: the existing cache-boundary test now
+   fetches `/api/authoring/session`, `/api/annotations/:handle/view`,
+   `/api/media/:handle/annotation-overlay`, and `POST /api/annotations` from a
+   real page. It asserts `no-store` and still finds zero `/api/` cache entries.
+5. `package.json` (additional file): the `test:security` script now also runs
+   the three new unit suites. No version, dependency, or other script changed.
+
+No existing test was weakened, skipped, or removed.
+
+## 17. Regression validation
+
+Every command below was run on Windows in the repository root.
+
+1. `npm run typecheck`: PASS (exit 0)
+2. `npm run lint`: PASS (exit 0)
+3. `npm test`: PASS (76 files, 1286 tests)
+4. `npm run build`: PASS (exit 0)
+5. `npm run test:browser`: PASS (21 files, 187 tests, real Chromium)
+6. `npm run test:security`: PASS (unit: 13 files, 143 tests. Browser: 3 files,
+   77 tests)
+7. `npm run check:docs`: PASS ("Documentation check passed (17 required files).")
+8. `npm pack --dry-run`: PASS (343 files, 875.9 kB). It includes the new
+   `dist/viewerServer` modules. No agent-control files are included.
+
+The existing read-only coverage all still passes: status, index, artifacts,
+observation media, comparison, evaluation, reference, binding, fidelity,
+context, static assets, and GET/HEAD behavior. The packed viewer smoke
+script's check (`POST /api/status` returns 405) still holds by construction.
+
+## 18. Security validation
+
+1. Host enforcement: PASS (wrong and rebinding Host give 403 on save and on
+   the session route).
+2. Origin enforcement: PASS (missing, foreign, `localhost`, and `null` Origin
+   give 403. A real Chromium same-origin POST succeeds).
+3. Token enforcement: PASS (missing, wrong, short, and cross-session tokens
+   give 403).
+4. JSON media type and encoding: PASS (415).
+5. Body size: PASS (exactly 262144 bytes is accepted. Larger bodies give 413,
+   both declared and chunked).
+6. Path safety: PASS (a traversal handle gives 404, and no browser-chosen
+   path or identity is accepted).
+7. Symlink safety: PASS. File symlink creation was confirmed to work on this
+   Windows host, so the symlinked-overlay test really exercised the rejection
+   (404). On hosts that refuse to create file symlinks, that test returns
+   early by design, the same as the existing viewer symlink test. Directory
+   and missing overlay rejection ran unconditionally.
+8. Method surface: PASS (only `POST /api/annotations`. PUT, PATCH, and DELETE
+   are 405 everywhere).
+9. PWA: PASS (new API responses are `no-store` and never in cache storage).
+
+## 19. Scope audit
+
+1. viewer React UI changed: false
+2. annotation drawing UI implemented: false
+3. ContractPrimitive vocabulary changed: false
+4. contract evaluator changed: false
+5. external-reference schema changed: false
+6. reference promotion implemented: false
+7. contract promotion implemented: false
+8. project config schema changed: false
+9. alias catalog schema changed: false
+10. package version changed: false
+11. dependency changed: false
+
+Prompt 1 owners (`visualAnnotation.ts`, `visualAnnotationIdentity.ts`, the
+annotation reader and writer, and `visualAnnotationPersistenceService.ts`) were
+not modified. No broad documentation file was modified.
+
+## 20. Changed files
+
+### 20.1 Added
+
+1. `src/viewerServer/authoringSecurity.ts`
+2. `src/viewerServer/annotationAuthoring.ts`
+3. `src/viewerServer/evidence/annotationView.ts`
+4. `tests/support/annotationAuthoringFixtures.ts`
+5. `tests/unit/viewerAnnotationEvidence.test.ts`
+6. `tests/unit/viewerAuthoringSecurity.test.ts`
+7. `tests/unit/viewerAnnotationAuthoring.test.ts`
+8. `docs/reports/v0.9-batch2-viewer-annotation-authoring-boundary.md`
+
+### 20.2 Modified
+
+1. `src/viewerServer/evidence/classify.ts`
+2. `src/viewerServer/evidence/handles.ts` (additional, see section 4)
+3. `src/viewerServer/evidence/projection.ts`
+4. `src/viewerServer/evidence/index.ts`
+5. `src/viewerServer/evidence/mediaResolver.ts`
+6. `src/viewerServer/httpServer.ts`
+7. `src/viewerServer/viewerService.ts`
+8. `src/projectWorkflow/projectPaths.ts`
+9. `src/application/projectWorkflowService.ts`
+10. `src/cli.ts`
+11. `package.json` (additional, `test:security` script only, see section 16)
+12. `tests/unit/projectWorkflow.test.ts`
+13. `tests/unit/cliViewDispatch.test.ts`
+14. `tests/browser/projectWorkflowViewer.test.ts`
+15. `tests/browser/pwaHardening.test.ts`
+
+### 20.3 Generated paths
+
+1. `dist/` was rebuilt. It is ignored by Git.
+2. Tests create temporary directories under the OS temp directory, following
+   the existing convention, and remove them.
+3. The existing PWA test profile under `.my-dev-kit-workflow/v0.8/batch-08/`
+   was reused. It is ignored by Git.
+4. Validation logs were written to the session scratchpad, outside the
+   repository.
+
+### 20.4 Remaining risks
+
+1. `startViewer` now imports the project workflow service to reuse
+   `loadProjectViewerState`. That module graph was already loaded by the CLI
+   and the package entry point.
+2. `docs/CI_CD.md`, `docs/SECURITY.md`, and `docs/ARCHITECTURE.md` do not yet
+   describe the authoring boundary, protocol 1.1.0, or the extended security
+   script. Batch 7 owns that reconciliation.
+
+## 21. Remaining next step
+
+v0.9 Prompt 3 — Runtime screenshot annotation authoring