transcription/docs/ver1/ver1-step5.md

# Step 5 Implementation Plan: Private-Network Safety Baseline

## Purpose

Implement **Ver1 Step 5** from `docs/ver1/ver1.md` by applying right-sized security controls for a single-user system running on a trusted private network.

Step 5 focuses on practical risk reduction without introducing unnecessary complexity, while preserving:

- personal-scale operational simplicity
- single-operator workflow
- explicit boundary ownership from `docs/architecture.md`
- safety and diagnostics behavior defined in `docs/error_handling.md`

Primary governing docs:

- `docs/ver1/ver1.md` (Step 5 objective and sequencing)
- `docs/architecture.md` (deployment model and module boundaries)
- `docs/error_handling.md` (safe user output and diagnostic boundaries)
- `docs/requirements.md` (REQ-1, REQ-2, REQ-5, REQ-7, REQ-8, REQ-9, REQ-10, REQ-11, REQ-12)
- `docs/intent.md` (domain integrity priorities)

---

## MCP Resources Reviewed and Applied

All currently available resources on `john-stream-mcp` were reviewed. Step 5 applies the following guidance directly:

1. `resource://skills/pydantic-settings/document`
   - typed security-related runtime settings
   - explicit env/source precedence
   - fail-fast handling for missing/invalid required values

2. `resource://skills/fastapi-uv-docker/document`
   - environment and deployment safety defaults
   - startup/health posture and container hygiene assumptions
   - local secret handling expectations

3. `resource://skills/pytesting/document`
   - deterministic security-behavior test lanes
   - marker discipline and behavior-first assertions

4. `resource://skills/python-logging-dictconfig/document`
   - centralized logging discipline
   - avoid leaking sensitive values in logs

5. `resource://skills/nicegui-ui-customization/document`
   - user-safe failure messaging in UI
   - resilient interaction behavior and clear error feedback

6. `resource://skills/ruff-linting-formating/document`
   - keep lint quality baseline stable during safety changes

Planning methodology input:

7. `resource://prompts/greenfield-architecture/document`
   - explicit tradeoff-oriented staging
   - scope discipline for minimally sufficient security controls

Reviewed but not directly Step 5 execution-critical:

- skills: `copilot-customization`, `fastapi-async-sqlalchemy-modernization`, `mcp-details`, `nicegui`, `python-typing`, `vscode-configuration`, `zensical-docs`
- prompts: `authoring`, `mcp-consumer-repo-shim`, `pytest-scaffold`, `pytest-fill-scaffold`

---

## Current-State Gap Summary (Step 5 Scope)

Based on current implementation and prior Step outputs:

1. **Private-network assumptions are implicit, not fully codified**
   - Need explicit, documented security posture and operator constraints.

2. **Access control for UI/API is minimal or absent**
   - Step 5 requires basic single-operator gating appropriate for private-network use.

3. **Input validation baseline exists but needs security-oriented audit closure**
   - Upload and API validation should be verified for abuse-resistant boundaries.

4. **Safe error output baseline exists (Step 2), but needs security confirmation pass**
   - Must ensure no sensitive internals leak through API/UI error payloads.

5. **Secret handling documentation needs formalization in Step 5 artifacts**
   - Local workflow should clearly prohibit secrets in repo-tracked files and logs.

6. **Dependency/security scanning is not yet formalized as a recurring gate**
   - Step 5 requires lightweight scanning and triage of high-risk findings.

---

## Scope for Step 5

### In scope

1. Codify private-network and single-operator security assumptions in docs and config.
2. Add basic access control for UI/API actions (right-sized for trusted network model).
3. Audit and harden input-validation boundaries (upload, API params/payloads, operational flags).
4. Verify safe error surface behavior (UI/API) and prevent sensitive leak paths.
5. Formalize local secret handling policy and usage examples.
6. Add lightweight dependency/security scan workflow and triage policy.
7. Add Step 5 verification tests and results artifact.

### Out of scope

- Internet-facing zero-trust security architecture
- Enterprise IAM/SSO/role systems
- Full cryptographic key-management infrastructure
- Major security product integrations beyond lightweight V1 needs

---

## Target Decisions for Step 5

1. **Threat model is explicitly private-network + single operator**
   - Security controls are right-sized to this posture and documented as assumptions.

2. **Access control is required, even in private network mode**
   - Basic gate (single shared operator credential/token) protects UI/API mutation paths.

3. **Validation and output safety are strict defaults**
   - Reject invalid inputs early; never expose sensitive internals in user-facing outputs.

4. **Secrets are runtime-only**
   - No secrets committed to source control; no plaintext secret logging.

5. **Security scanning is lightweight but mandatory**
   - Add recurring dependency/security checks with high-risk triage and closure workflow.

6. **No security control may violate Step 1–4 operational simplicity guardrails**
   - Preserve deployability and maintainability for personal-scale use.

---

## Detailed Work Breakdown

## Phase A — Security Posture Definition and Gap Lock

- [ ] **A1. Define Step 5 threat model**
  - trusted private network
  - single operator
  - local deployment assumptions
  - explicit out-of-scope threat classes

- [ ] **A2. Produce security baseline checklist**
  - access control
  - validation boundaries
  - safe error behavior
  - secret handling
  - dependency risk checks

- [ ] **A3. Map controls to architecture boundaries**
  - UI
  - API
  - service
  - config/runtime
  - operator runbooks

### Deliverables

- `docs/ver1/ver1-step5-security-assumptions.md` (recommended)
- Step 5 control matrix (control -> owner -> validation method)

### Exit Criteria

- private-network safety posture is explicit and approved
- each in-scope control has boundary ownership and verification path

---

## Phase B — Basic Single-Operator Access Control

- [ ] **B1. Select access mechanism**
  - minimal approach suitable for private-network model
  - explicitly document tradeoffs and operator ergonomics

- [ ] **B2. Protect mutating operations first**
  - upload/create/accept/export-trigger endpoints
  - UI actions that trigger persistence changes

- [ ] **B3. Protect read operations as policy requires**
  - determine read-path gating expectations and apply consistently

- [ ] **B4. Add clear unauthorized behavior contract**
  - stable API status and safe message
  - UI feedback with actionable operator guidance

### Deliverables

- access-control policy and implementation notes
- unauthorized behavior matrix (UI/API)

### Exit Criteria

- unauthorized actions are blocked consistently
- authorized operator flows remain usable and deterministic

---

## Phase C — Input Validation and Safe Output Hardening

- [ ] **C1. Validation audit for all entry points**
  - file uploads (type/size/content guards)
  - route/query/body constraints
  - service-layer invariants

- [ ] **C2. Normalize validation failures to canonical taxonomy**
  - `validation_error` vs `user_input_error` consistency

- [ ] **C3. Confirm safe error output policy under security lens**
  - no stack traces/secrets/internal paths in UI/API default outputs
  - preserve error reference IDs for traceability

- [ ] **C4. Add abuse-resistant guardrails where practical**
  - basic request-size and payload-shape constraints
  - anti-duplication interaction safeguards (where missing)

### Deliverables

- validation-path inventory and hardening checklist
- safe-output verification notes

### Exit Criteria

- input boundaries are deterministic and tested
- user-facing error outputs remain safe and actionable

---

## Phase D — Secrets Handling and Configuration Safety

- [ ] **D1. Define secret handling policy**
  - where secrets are allowed (runtime env only)
  - where secrets are prohibited (source files, docs examples beyond placeholders)

- [ ] **D2. Enforce settings expectations**
  - required secret fields fail fast
  - avoid fallback defaults that silently weaken safety

- [ ] **D3. Add operator documentation for local secret workflow**
  - how to set environment values safely
  - how to rotate/update credentials locally

- [ ] **D4. Validate logging does not leak secret values**
  - startup/config logs
  - error logs for provider/config failures

### Deliverables

- secret-handling section in runbook/README/docs
- settings and logging safety verification notes

### Exit Criteria

- no secret leakage paths remain in normal operations
- operator can configure secrets safely using docs only

---

## Phase E — Dependency and Security Scanning Baseline

- [ ] **E1. Select lightweight scanning commands for V1**
  - dependency vulnerability scan
  - optional static security scan if practical

- [ ] **E2. Define triage policy for findings**
  - severity classification
  - required closure criteria for Step 5 completion

- [ ] **E3. Run scans and capture evidence**
  - record command outputs/summaries
  - remediate or formally defer with risk notes

- [ ] **E4. Add recurring execution guidance**
  - local pre-release checklist integration
  - future CI gate handoff for Step 7/9

### Deliverables

- Step 5 scan report artifact (recommended)
- triage log of resolved/deferred findings

### Exit Criteria

- no unresolved critical vulnerabilities in Step 5 scope
- high-risk findings are resolved or explicitly risk-accepted with rationale

---

## Phase F — Verification and Test Expansion

Apply `pytesting` guidance (deterministic, behavior-first, strict markers).

- [ ] **F1. Access-control tests**
  - unauthorized requests are rejected as expected
  - authorized operator requests succeed

- [ ] **F2. Validation and abuse-boundary tests**
  - invalid payloads rejected with stable category/status
  - file-type/size constraints enforced

- [ ] **F3. Safe-output tests**
  - API/UI error responses avoid sensitive details
  - error IDs and suggestions remain present

- [ ] **F4. Config/secret safety tests**
  - required secrets fail fast when missing
  - no unsafe fallback behavior introduced

### Validation Commands

- `uv run pytest --collect-only -q`
- `uv run pytest -m unit -q`
- `uv run pytest -m "not external" -q`
- `uv run pytest -q`

### Exit Criteria

- Step 5 safety behavior is test-covered and passing
- no regression in core upload/transcribe/review workflows

---

## Phase G — Documentation and Risk Closure

- [ ] **G1. Create Step 5 results artifact**
  - `docs/ver1/ver1-step5-results.md`

- [ ] **G2. Update operator-facing docs**
  - security assumptions and local deployment cautions
  - credential handling and recovery basics

- [ ] **G3. Update traceability and carry-forward notes**
  - map Step 5 controls to REQ and evidence

### Deliverables

- `docs/ver1/ver1-step5-results.md`
- updated security assumptions checklist and risk summary

### Exit Criteria

- Step 5 controls and residual risks are fully documented
- handoff is ready for Step 6 observability and Step 7 quality gates

---

## Recommended Implementation Order

1. Phase A — posture definition and gap lock
2. Phase B — access control baseline
3. Phase C — validation/output hardening
4. Phase D — secrets and config safety
5. Phase E — dependency/security scan baseline
6. Phase F — test expansion and verification
7. Phase G — docs and risk closure

This order reduces risk by locking assumptions first, then applying controls at highest-impact boundaries before final verification and documentation.

---

## Step 5 Execution Checklist (Phase-by-Phase)

Use this checklist to execute Step 5 in implementation order and record progress/evidence.

### Phase A — Security Posture Definition and Gap Lock

- [ ] Publish `docs/ver1/ver1-step5-security-assumptions.md`.
- [ ] Record explicit in-scope and out-of-scope threat classes.
- [ ] Produce Step 5 control matrix (control, owner, validation method).
- [ ] Confirm boundary ownership for each control (UI/API/service/config/docs).

### Phase B — Basic Single-Operator Access Control

- [ ] Choose and document access mechanism (with rationale and tradeoffs).
- [ ] Implement enforcement for mutating API operations.
- [ ] Implement corresponding UI-side access behavior for protected actions.
- [ ] Decide and enforce read-path protection policy.
- [ ] Add unauthorized API/UI contract tests.

### Phase C — Input Validation and Safe Output Hardening

- [ ] Complete input-validation inventory for upload/API/service boundaries.
- [ ] Tighten payload/file constraints where gaps are found.
- [ ] Ensure validation failure categories match `docs/error_handling.md`.
- [ ] Verify user-facing errors remain safe, actionable, and traceable.
- [ ] Add regression tests for invalid/boundary inputs.

### Phase D — Secrets Handling and Configuration Safety

- [ ] Document secrets policy (runtime-only, no repo storage).
- [ ] Verify required secret settings fail fast when missing.
- [ ] Audit logs for accidental secret leakage risk paths.
- [ ] Update operator docs for local secret setup/rotation workflow.
- [ ] Add tests for config safety expectations where practical.

### Phase E — Dependency and Security Scanning Baseline

- [ ] Select scanning commands and record tool versions.
- [ ] Run baseline scans and capture outputs.
- [ ] Triage findings by severity and exploitability in private-network context.
- [ ] Resolve/mitigate critical findings; document accepted residual risk.
- [ ] Add recurring scan guidance for release workflow handoff.

### Phase F — Verification and Test Expansion

- [ ] Run `uv run pytest --collect-only -q`.
- [ ] Run `uv run pytest -m unit -q`.
- [ ] Run `uv run pytest -m "not external" -q`.
- [ ] Run `uv run pytest -q`.
- [ ] Confirm no regressions in upload/transcribe/review core flows.

### Phase G — Documentation and Risk Closure

- [ ] Complete `docs/ver1/ver1-step5-results.md` with evidence.
- [ ] Update docs/README/runbooks with final Step 5 security posture.
- [ ] Record REQ traceability updates and residual risks.
- [ ] Confirm Step 5 completion checklist items are all closed.

---

## Risks and Mitigations

1. **Risk:** Over-engineering beyond private-network needs
   - **Mitigation:** enforce Step 5 scope discipline and threat-model constraints.

2. **Risk:** Access controls disrupt operator usability
   - **Mitigation:** keep mechanism minimal and test primary workflows thoroughly.

3. **Risk:** Sensitive details leak through errors/logging
   - **Mitigation:** apply safe-output and log-sanitization checks with tests.

4. **Risk:** Unpatched dependency vulnerabilities remain invisible
   - **Mitigation:** formalize scan + triage + evidence capture workflow.

5. **Risk:** Secret handling remains ad hoc
   - **Mitigation:** fail-fast settings + explicit operator documentation + review checks.

---

## Step 5 Completion Checklist

- [ ] Private-network and single-operator security assumptions are documented.
- [ ] Basic single-operator access control is implemented and verified.
- [ ] Input-validation boundaries are audited, hardened, and test-covered.
- [ ] UI/API error output safety is confirmed under security tests.
- [ ] Secret handling policy and local workflow docs are complete.
- [ ] Dependency/security scans are run; critical findings are resolved.
- [ ] Step 5 tests pass across all validation lanes.
- [ ] `docs/ver1/ver1-step5-results.md` is completed with evidence and residual risks.

---

## Handoff to Step 6

Step 5 completion enables Step 6 (Minimal Observability & Operability) with:

- explicit security assumptions for operator context
- access and validation controls suitable for private-network operation
- safer runtime/configuration handling for ongoing operations
- dependency-risk visibility feeding release-readiness gates