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.

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).