k_card/Workplan.md

# Workplan

Last updated: 2026-04-24

This is the execution plan for making ChromeCard FIDO2 development and validation reproducible on this machine.

## Constraints

- Treat `/home/user/chromecard/CR_SDK_CK-main` as read-only.
- Keep helper scripts such as `fido2_probe.py` and `webauthn_local_demo.py` at `/home/user/chromecard`.
- Target deployment model is Qubes OS with 3 AppVMs based on `debian-13-xfce`: `k_client`, `k_proxy`, `k_server`.
- Current authenticator link is card->`k_proxy` (USB), but architecture must allow migration to wireless phone-mediated validation.

## Goals

- Re-establish deterministic host-to-card FIDO2 communication over USB HID/CTAPHID.
- Restore a buildable/flashable firmware workspace for `CR_SDK_CK-main`.
- Turn ad-hoc demos into a repeatable verification flow.
- Stand up chained TLS communication in Qubes: `k_client -> k_proxy -> k_server`.
- Support both login flow (browser in `k_client`) and user enrollment flow (process in `k_client`).
- Minimize repeated card prompts by introducing secure session reuse after successful authentication.
- Implement a protected dummy resource on `k_server` (monotonic counter) for end-to-end validation.
- Ensure `k_proxy` and `k_server` are thread-safe and support concurrent access.
- Prepare `k_proxy` auth path for future transport shift: USB-direct -> wireless phone bridge.

## Phase 0: Qubes VM Baseline (Blocking)

1. Provision/verify AppVMs.
- Ensure `k_client`, `k_proxy`, `k_server` exist and are based on `debian-13-xfce`.

2. Assign functional responsibilities.
- `k_client`: browser client + enrollment process.
- `k_proxy`: USB card access + proxy/auth bridge.
- `k_server`: protected resource/service endpoint.

3. Define TLS endpoints and certificates.
- `k_proxy` presents TLS service to `k_client`.
- `k_server` presents TLS service to `k_proxy`.
- Trust roots and cert distribution model documented per VM.

Exit criteria:
- All 3 VMs exist, boot, and have clearly defined service ownership.

## Phase 1: Qubes Firewall Policy (Blocking)

1. Enforce allowed forward paths only.
- Allow `k_client` outbound TLS only to `k_proxy` service port(s).
- Allow `k_proxy` outbound TLS only to `k_server` service port(s).
- Deny direct `k_client` to `k_server` traffic.

2. Validate return path behavior.
- Confirm responses propagate back through established flows.

3. Verify with simple probes.
- TLS handshake and HTTP(S) checks from `k_client` to `k_proxy`.
- TLS handshake and HTTP(S) checks from `k_proxy` to `k_server`.

Exit criteria:
- Policy matches intended chain and is test-verified.

## Phase 2: TLS Certificates and Service Endpoints

1. Certificate model.
- Create or import CA and issue certs for `k_proxy` and `k_server`.
- Install trust roots in client VM(s) that need validation.

2. Service shape.
- `k_server`: HTTPS service exposing protected resource endpoint(s), including a monotonic counter endpoint.
- `k_proxy`: minimal HTTPS API gateway service (full web server framework not required).

3. Endpoint contract.
- Define request/response schema between `k_client` and `k_proxy`.
- Define upstream request contract from `k_proxy` to `k_server`.

Exit criteria:
- Mutual TLS trust decisions are documented and tested.
- HTTPS calls succeed on both links with expected cert validation.

## Phase 2.5: Define State Ownership and Concurrency Model

1. State ownership.
- Decide where user/session state is authoritative (`k_proxy`, `k_server`, or split model).
- Define token/session format and validation boundary.

2. Concurrency controls.
- Define thread-safe strategy for session store and shared counters.
- Define locking/atomic/update semantics for counter increments and session updates.

3. Runtime model.
- Choose service runtime/config that supports simultaneous requests safely.

Exit criteria:
- Architecture clearly documents state authority and race-free update rules.

## Phase 3: Recover Basic Device Visibility on `k_proxy` (Blocking)

1. Verify physical + USB enumeration path.
- Check cable/port and confirm device appears in USB listings.
- Confirm `/dev/hidraw*` nodes appear when card is connected.

2. Validate Linux permissions.
- Install/update udev rule for ChromeCard HID VID/PID.
- Reload udev and verify non-root read/write access to hidraw node.

3. Re-run host probe.
- Run `python3 /home/user/chromecard/fido2_probe.py --list`.
- Run `python3 /home/user/chromecard/fido2_probe.py --json`.
- Record VID/PID/path and CTAP2 `getInfo` output in `Setup.md`.

Exit criteria:
- At least one CTAP HID device is listed.
- `--json` returns valid `ctap2_info`.

## Phase 4: Re-validate Local WebAuthn Demo on `k_proxy`

1. Start local demo server.
- Run `python3 /home/user/chromecard/webauthn_local_demo.py`.
- Confirm URL is `http://localhost:8765`.

2. Exercise register/login.
- Register a test user.
- Authenticate with same user.
- Capture errors (if any) and update `Setup.md`.

3. Decide next demo hardening step.
- Keep bring-up-only mode, or
- add signature verification for attestation/assertion.

Exit criteria:
- Register and login both complete with card interaction prompts.

Status (2026-04-24):
- Completed in `k_proxy` using `http://localhost:8765`.
- Registration result: `ok=true`, `username=alice`, `credential_count=1`.
- Authentication result: `ok=true`, `username=alice`, `authenticated=true`.

## Phase 5: Implement Proxy Auth + Session Reuse

1. Authenticate via card once per session window.
- `k_proxy` handles initial auth using connected card.
- On success, create session state for `k_client`.

2. Session model.
- Prefer server-side session store or signed session token.
- Include TTL/expiry, rotation, and explicit invalidation/logout path.
- Do not expose card secrets or long-lived auth material to `k_client`.

3. Proxying behavior.
- With valid session: `k_proxy` forwards request to `k_server` and returns result.
- Without valid session: require fresh card-backed auth flow.

Exit criteria:
- Repeated authorized requests do not require card interaction until session expiry.
- Expired/invalid sessions are correctly rejected.

Status (2026-04-24):
- Started with a runnable prototype:
  - `/home/user/chromecard/k_proxy_app.py`
  - `/home/user/chromecard/k_server_app.py`
  - `/home/user/chromecard/PHASE5_RUNBOOK.md`
- Implemented in prototype:
  - session create/status/logout endpoints in `k_proxy`
  - TTL-based server-side session store with expiry garbage collection
  - protected monotonic counter endpoint in `k_server` with thread-safe increments
  - proxy forwarding from `k_proxy` to `k_server` using a shared upstream token
- Current auth gate for session creation is card-presence probe (`fido2_probe.py --json`), pending upgrade to full assertion verification path.

## Phase 5.5: Implement Dummy Resource + Access Policy on `k_server`

1. Protected dummy resource.
- Add endpoint returning increasing number.
- Require valid upstream auth/session context from `k_proxy`.

2. Optional user/session handling.
- Add minimal user/session checks if `k_server` is chosen as authority (or partial authority).

3. Correctness under concurrency.
- Ensure increments are monotonic and race-safe under parallel calls.

Exit criteria:
- Authorized requests obtain consistent increasing values.
- Unauthorized requests are rejected.

## Phase 6: Integrate Client Enrollment + Proxy Login Flow

1. Enrollment process in `k_client`.
- Start process from `k_client` that captures new-user enrollment intent/data.
- Route enrollment requests to `k_proxy` over TLS.

2. Card-mediated login in `k_proxy`.
- `k_proxy` uses connected card for FIDO2/WebAuthn operations.
- `k_proxy` authenticates toward `k_server` over TLS.

3. Browser flow in `k_client`.
- Browser traffic goes only to `k_proxy`.
- Validate end-to-end login to `k_server` resource through proxy chain.

Exit criteria:
- Enrollment and login both function end-to-end via `k_client -> k_proxy -> k_server`.

## Phase 6.5: Concurrency and Multi-Client Test Setup

1. Single-VM concurrency tests.
- Generate parallel request bursts from `k_client` to `k_proxy`.
- Verify response integrity, session reuse behavior, and error rates.

2. Multi-client tests.
- Run requests from multiple `k_client` instances (or equivalent parallel clients) concurrently.
- Verify isolation between users/sessions.

3. Acceptance checks.
- No race-related crashes/corruption in `k_proxy` or `k_server`.
- Counter/resource behavior remains correct under load.
- Session reuse reduces card prompts while preserving authorization checks.

Exit criteria:
- Test results demonstrate stable concurrent operation with documented limits.

## Phase 7: Restore Firmware Build/Flash Path

1. Validate SDK tree completeness.
- Confirm presence of `mvp`, `setup`, `components`, `samples` under `CR_SDK_CK-main`.
- If missing, obtain full repository/checkpoint and document source.

2. Install/enable build tools.
- Ensure `west` and `nrfjprog` are available in shell.
- Confirm target board/toolchain match (`nrf7002dk/nrf5340/cpuapp`, NCS `v2.9.2` baseline in docs).

3. Run baseline build+flash.
- From `CR_SDK_CK-main`, run `./scripts/build_flash_mvp.sh`.
- If flashing fails, run documented recovery and retry.

Exit criteria:
- Successful `west build` and `west flash`.

## Phase 8: Consolidate Documentation and Paths

1. Remove path drift between docs and actual files.
- Keep `fido2_probe.py` and `webauthn_local_demo.py` at workspace root.
- Ensure docs never instruct placing helper scripts under `CR_SDK_CK-main`.
- Update references consistently in all docs.

2. Keep `Setup.md` current.
- After each significant change, update status snapshot and outcomes.

3. Add minimal reproducibility checklist.
- One command list for probe + demo + build/flash prechecks.

4. Maintain Markdown execution records continuously.
- `Setup.md` and `Workplan.md` are the canonical living docs for this workspace.
- Re-scan relevant `.md` files before each new execution cycle and reconcile drift.
- Record date-stamped session notes when priorities or blockers change.

Exit criteria:
- New team member can follow docs end-to-end without path or tooling ambiguity.

## Phase 9: Migrate to Phone-Mediated Wireless Validation (Future)

1. Auth transport abstraction in `k_proxy`.
- Introduce/keep a transport interface for authenticator operations.
- Implement at least two backends:
- USB-direct backend (current).
- Phone-wireless backend (future).

2. Wireless phone integration.
- Define protocol between `k_proxy` and phone service.
- Define secure pairing/authentication and message integrity for wireless link.
- Add timeout/retry behavior and offline handling.

3. Functional equivalence tests.
- Verify login/enrollment behavior is unchanged at API level for `k_client`.
- Verify session reuse still works and card prompts are not increased unexpectedly.

Exit criteria:
- `k_proxy` can validate via wireless phone path with no client-facing API changes.

## Inputs Expected During This Session

- Exact observed behavior on reconnect attempts (USB/hidraw/probe).
- Whether we should pull server-side code now.
- Any board/firmware variants different from default documentation assumptions.
- Preferred TLS ports, certificate approach, and hostname scheme for `k_client`, `k_proxy`, `k_server`.
- Session TTL and invalidation requirements for cached authenticated access.
- Decision on where user/session authority lives (`k_proxy` vs `k_server` vs split).
- Target concurrency level for validation (parallel clients and parallel requests per client).
- Preferred wireless transport/protocol between `k_proxy` and phone (for future phase).