> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase01-session04-server-routes-and-authorization-boundaries` **Package**: Cross-package (`apps/server`, `packages/protocol`) **Started**: 2026-05-29 04:34 **Last Updated**: 2026-05-29 04:50

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 21 / 21 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

### Task T021 - Run Verification Checks

**Started**: 2026-05-29 04:50 **Completed**: 2026-05-29 04:50 **Duration**: 1 minute

**Notes**:

* Ran focused protocol/server tests after updating one stale `/event` malformed-body expectation.
* Ran protocol and server package typechecks.
* Ran Biome format and lint checks on touched source and test files.
* Ran `git diff --check`, ASCII validation on touched files, and LF validation on touched files.
* Added `IMPLEMENTATION_SUMMARY.md` for session closure.

**Files Changed**:

* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T021 and completion checklist complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded verification results.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/IMPLEMENTATION_SUMMARY.md` - added session summary.
* `apps/server/tests/eventIngest.test.ts` - updated stale malformed body expectation after verification found it.
* `packages/protocol/tests/ingest.test.ts` - updated rejected ingest contract expectation.

**Verification Results**:

* `npx vitest run packages/protocol/tests/rest.test.ts packages/protocol/tests/ingest.test.ts apps/server/tests/routes.test.ts apps/server/tests/permission.test.ts apps/server/tests/authBoundaries.test.ts apps/server/tests/unsupportedRoutes.test.ts apps/server/tests/eventIngest.test.ts` - PASS, 7 files, 42 tests.
* `npm --workspace @factionos/protocol run typecheck` - PASS.
* `npm --workspace @factionos/server run typecheck` - PASS.
* `npx biome format ...` - PASS.
* `npx biome lint ...` - PASS.
* `git diff --check` - PASS.
* ASCII validation on touched files - PASS.
* LF validation on touched files - PASS.

**BQC Fixes**:

* Error information boundaries: ASCII validation found two non-ASCII comment dashes in touched `apps/server/src/server.ts`; normalized them to ASCII.
* Contract alignment: stale tests were updated to match the new `invalid_request` malformed-body contract.

***

### Task T020 - Extend Permission Tests

**Started**: 2026-05-29 04:49 **Completed**: 2026-05-29 04:50 **Duration**: 3 minutes

**Notes**:

* Added tests for missing and empty IDs, invalid boolean values, omitted approvals, explicit denies, and duplicate-safe repeated responses.

**Files Changed**:

* `apps/server/tests/permission.test.ts` - extended permission and plan approval validation coverage.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T020 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: tests now cover malformed approval payloads.
* Duplicate action prevention: tests verify repeat approval responses remain stable and do not fail.

***

### Task T019 - Extend Route Tests

**Started**: 2026-05-29 04:48 **Completed**: 2026-05-29 04:49 **Duration**: 4 minutes

**Notes**:

* Added route tests for invalid notice severity and targets, valid notice severity/targets, mission pagination limits, scroll collect body validation, War Room capability metadata, and updated catch-all payload shape.

**Files Changed**:

* `apps/server/tests/routes.test.ts` - extended route hardening coverage.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T019 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: route tests now cover invalid body/query shapes before state mutation.
* Contract alignment: route tests now expect the new War Room and catch-all response contracts.

***

### Task T018 - Update Detailed Contract Docs

**Started**: 2026-05-29 04:47 **Completed**: 2026-05-29 04:48 **Duration**: 4 minutes

**Notes**:

* Updated the detailed API contract for hardened POST validation, mission pagination, approval responses, War Room stub metadata, unsupported route-family classification, and remaining Phase 01 gaps.
* Kept historical route examples summarized as route families rather than copying the recovered inventory into product docs.

**Files Changed**:

* `docs/api/event-api-hook-contracts.md` - updated route statuses, error model, War Room separation, and route-family classification.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T018 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Contract alignment: detailed docs now match source behavior and tests for validation, unsupported routes, and War Room separation.

***

### Task T017 - Update Concise API Docs

**Started**: 2026-05-29 04:46 **Completed**: 2026-05-29 04:47 **Duration**: 2 minutes

**Notes**:

* Updated concise API docs for auth coverage over read, write, and unsupported routes.
* Documented strict mission limits, War Room stub capability metadata, approval response shape, validation envelope, and deterministic unsupported-route response shape.

**Files Changed**:

* `docs/api/README_api.md` - updated route validation, auth, unsupported-route, and War Room separation notes.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T017 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Contract alignment: docs now reflect the new validation and unsupported-route envelopes.

***

### Task T016 - Add Unsupported Historical Route Tests

**Started**: 2026-05-29 04:45 **Completed**: 2026-05-29 04:46 **Duration**: 2 minutes

**Notes**:

* Replaced the unsupported-route scaffold todo with route-family assertions for historical file, git, terminal/internal-hero, local War Room, and unknown paths.
* Added checks that request bodies, tokens, prompts, query strings, and private path fragments are not echoed in 501 responses.

**Files Changed**:

* `apps/server/tests/unsupportedRoutes.test.ts` - added unsupported route family tests.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T016 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Error information boundaries: tests prove unsupported responses omit body and query-sensitive values.
* Contract alignment: tests lock method, path, family, status, and docs pointer in 501 envelopes.

***

### Task T015 - Add Auth Boundary Coverage

**Started**: 2026-05-29 04:44 **Completed**: 2026-05-29 04:45 **Duration**: 2 minutes

**Notes**:

* Added coverage proving configured bearer auth protects read, write, and unsupported catch-all route families.
* Confirmed unsupported route classification happens only after authorization succeeds.

**Files Changed**:

* `apps/server/tests/authBoundaries.test.ts` - added read/write/catch-all auth boundary tests.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T015 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: tests lock auth middleware coverage over catch-all routes.
* Error information boundaries: unauthenticated unsupported probes receive only the existing 401 envelope.

***

### Task T014 - Align Event Invalid-Body Responses

**Started**: 2026-05-29 04:43 **Completed**: 2026-05-29 04:44 **Duration**: 2 minutes

**Notes**:

* Changed malformed `/event` body responses to use `invalid_request` plus field details while preserving `accepted: false`.
* Kept missing dispatch keys and unknown type-only payloads tolerant and accepted as before.
* Added a small route-level sender helper so invalid ingest responses stay centralized at the route boundary.

**Files Changed**:

* `apps/server/src/routes/event.ts` - added route-level invalid ingest response helper.
* `apps/server/src/lib/eventIngest.ts` - aligned invalid-body response code and details.
* `packages/protocol/src/ingest.ts` - updated rejected ingest response contract.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T014 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Contract alignment: `/event` malformed-body responses now match the session validation envelope convention.
* Failure path completeness: malformed non-object bodies still return a caller-visible 400 without affecting tolerant ingest flows.

***

### Task T013 - Harden Permission and Plan Approval Routes

**Started**: 2026-05-29 04:42 **Completed**: 2026-05-29 04:43 **Duration**: 3 minutes

**Notes**:

* Added JSON body validation, non-empty bounded ID validation, and optional boolean validation for `/permission-response` and `/plan/approve`.
* Changed pending-map cleanup to delete by validated ID before returning, making duplicate responses safe and observable through a `resolved` flag.

**Files Changed**:

* `apps/server/src/routes/permission.ts` - added approval request validation and idempotent pending-map cleanup.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T013 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: approval routes validate IDs and booleans before emitting events.
* Duplicate action prevention: duplicate HTTP responses cannot resolve the same pending map entry twice.

***

### Task T012 - Harden Scroll Collection and War Room Stub

**Started**: 2026-05-29 04:41 **Completed**: 2026-05-29 04:42 **Duration**: 3 minutes

**Notes**:

* Added schema validation for scroll collection request bodies and optional `heroId`.
* Kept scroll collection tolerant of an omitted body by treating it as an empty object.
* Added `/warroom` capability metadata and explicit Worker separate-surface metadata, while leaving the local response a stub.

**Files Changed**:

* `apps/server/src/routes/heroes.ts` - added scroll body validation and War Room capability metadata.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T012 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: scroll collect bodies are validated before state changes.
* Contract alignment: `/warroom` now carries explicit `stubbed` and `separate-surface` status metadata.

***

### Task T011 - Harden Mission List Reads

**Started**: 2026-05-29 04:40 **Completed**: 2026-05-29 04:41 **Duration**: 2 minutes

**Notes**:

* Added strict `limit` validation for `/missions`, defaulting to 50 and allowing 1 through 200.
* Invalid limits now return `invalid_request` instead of silent coercion.
* Added route-level deterministic sorting by `startedAt` descending with `id` tie-breaker.

**Files Changed**:

* `apps/server/src/routes/heroes.ts` - added mission pagination validation and deterministic response ordering.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T011 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: query input is validated before manager reads.
* Contract alignment: invalid pagination now uses the shared validation envelope.

***

### Task T010 - Harden Notice Creation

**Started**: 2026-05-29 04:39 **Completed**: 2026-05-29 04:40 **Duration**: 2 minutes

**Notes**:

* Added route-boundary validation for `/notice` JSON bodies.
* Notice text must be non-empty and bounded, severity must match the protocol enum, and target IDs must be bounded non-empty strings.
* The route copies validated target arrays before mutating notice state.

**Files Changed**:

* `apps/server/src/routes/heroes.ts` - added notice request validation and sanitized state mutation inputs.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T010 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: `/notice` validates `unknown` request bodies before manager calls.
* Error information boundaries: validation errors do not include submitted notice text or target values.

***

### Task T009 - Wire Unsupported Route Helper

**Started**: 2026-05-29 04:47 **Completed**: 2026-05-29 04:48 **Duration**: 1 minute

**Notes**:

* Replaced the inline catch-all response with `buildUnsupportedRouteResponse`.
* Confirmed middleware ordering remains CORS, rate limit, local auth, JSON parser, routes, then catch-all, so auth is enforced before unsupported response generation when configured.

**Files Changed**:

* `apps/server/src/server.ts` - wired unsupported-route helper into the catch-all.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T009 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Error information boundaries: catch-all no longer includes historical inventory paths in the response hint and delegates to compact route-family payloads.

***

### Task T008 - Create Unsupported Route Classifier

**Started**: 2026-05-29 04:44 **Completed**: 2026-05-29 04:47 **Duration**: 3 minutes

**Notes**:

* Added deterministic route-family classification for historical file, git, terminal, remote, settings, task queue, webhook, push, collaboration, War Room Worker, and unknown paths.
* Added a local War Room capability helper for the compatibility stub.
* Unsupported responses include method, normalized path, route family, status, docs pointer, and a stable message only.

**Files Changed**:

* `apps/server/src/lib/unsupportedRoutes.ts` - added route classifier and 501 response builder.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T008 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Error information boundaries: 501 payloads omit request bodies and query strings.
* Contract alignment: unsupported payloads use the protocol `UnsupportedRouteResponse` shape.

***

### Task T007 - Create Request Validation Helper

**Started**: 2026-05-29 04:41 **Completed**: 2026-05-29 04:44 **Duration**: 3 minutes

**Notes**:

* Added a lightweight validation helper for JSON object bodies, non-empty strings, optional strings, optional booleans, optional enums, bounded string arrays, and bounded integer query values.
* Validation failures return compact `invalid_request` envelopes with field-level reasons and no request-body echoing.

**Files Changed**:

* `apps/server/src/lib/requestValidation.ts` - added boundary validation utilities and explicit error mapping.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T007 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Trust boundary enforcement: route helpers now parse `unknown` JSON/query inputs before manager calls.
* Error information boundaries: invalid request responses describe fields and reasons only.

***

### Task T006 - Export REST Route Contracts

**Started**: 2026-05-29 04:40 **Completed**: 2026-05-29 04:41 **Duration**: 1 minute

**Notes**:

* Re-exported the protocol REST module from the package root.

**Files Changed**:

* `packages/protocol/src/index.ts` - added `rest.ts` export.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T006 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Contract alignment: consumers can import REST route contracts through `@factionos/protocol`.

***

### Task T005 - Add Protocol REST Tests

**Started**: 2026-05-29 04:39 **Completed**: 2026-05-29 04:40 **Duration**: 1 minute

**Notes**:

* Added protocol tests for route status values, route family values, helper guards, compact unsupported-route envelopes, and high-risk request/validation contract shapes.

**Files Changed**:

* `packages/protocol/tests/rest.test.ts` - added REST contract tests.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T005 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Contract alignment: tests now lock the status/family vocabulary used by server and docs.

***

### Task T004 - Define Shared REST Route Contracts

**Started**: 2026-05-29 04:37 **Completed**: 2026-05-29 04:39 **Duration**: 2 minutes

**Notes**:

* Added protocol-owned REST route status values, route family values, error codes, capability envelopes, unsupported-route response shape, and high-risk request body interfaces.
* Kept the module framework-independent with no Express imports or runtime dependencies.

**Files Changed**:

* `packages/protocol/src/rest.ts` - added REST route vocabulary and request/response contracts.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T004 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded implementation details.

**BQC Fixes**:

* Contract alignment: centralized route status and response shapes before server helpers and tests use them.

***

### Task T003 - Create Route-Hardening Test Scaffold

**Started**: 2026-05-29 04:36 **Completed**: 2026-05-29 04:37 **Duration**: 1 minute

**Notes**:

* Added an ephemeral server test scaffold for unsupported historical route behavior.
* Kept assertions as a todo until the unsupported route classifier contract exists.

**Files Changed**:

* `apps/server/tests/unsupportedRoutes.test.ts` - added server lifecycle helper and unsupported-route test scaffold.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T003 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded scaffold details.

**BQC Fixes**:

* N/A - test scaffold only.

***

### Task T002 - Verify Current Route Test Coverage

**Started**: 2026-05-29 04:35 **Completed**: 2026-05-29 04:36 **Duration**: 1 minute

**Notes**:

* Reviewed `apps/server/tests/routes.test.ts`, `apps/server/tests/permission.test.ts`, and `apps/server/tests/security.test.ts`.
* Confirmed existing coverage for core read paths, lifecycle event ingest, notice body presence, scroll collection, permission/plan happy paths, and generic HTTP/WebSocket auth.
* Identified missing session coverage for validation error envelopes, strict severity/boolean/target/body validation, mission pagination boundaries, unsupported route-family payloads, and auth enforcement over read, write, and catch-all routes.

**Files Changed**:

* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T002 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded coverage gaps.

**BQC Fixes**:

* N/A - verification-only task.

***

### Task T001 - Verify Current Server Route Map

**Started**: 2026-05-29 04:34 **Completed**: 2026-05-29 04:35 **Duration**: 1 minute

**Notes**:

* Reviewed current Express route registration in `apps/server/src/server.ts` and route handlers under `apps/server/src/routes`.
* Compared the current focused local route surface with the recovered historical inventory in `EXAMPLES/findings/api-routes.txt`, `EXAMPLES/findings/architecture.md`, `EXAMPLES/findings/BUILD_LINKS.md`, and `EXAMPLES/findings/websocket-events.txt`.
* Confirmed status gaps to preserve in docs: current local routes are shipped or stubbed, War Room Worker routes are a separate surface, and historical file, git, terminal, remote access, push, webhook, settings, worktree, task queue, and internal hero command families remain unsupported or planned.

**Files Changed**:

* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/tasks.md` - marked T001 complete.
* `.spec_system/specs/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md` - recorded verification findings.

**BQC Fixes**:

* N/A - verification-only task.

***

## Task Log

### 2026-05-29 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase01-session04-server-routes-and-authorization-boundaries/implementation-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.