3.8 KiB

Raw Blame History

Phase 5 Runbook (Session Reuse Prototype)

This runbook starts a minimal k_server + k_proxy prototype for session reuse testing.

Last updated: 2026-04-25

What This Prototype Covers

k_proxy creates short-lived sessions.
Session creation uses a card-presence check (fido2_probe.py --json) as the current auth gate.
Valid sessions can repeatedly access a protected k_server counter endpoint without re-running card auth each request.
Session status and logout/invalidation paths are implemented.

Modes

There are two useful ways to run this prototype:

Same-VM quickstart: k_proxy and k_server run on one VM for app-local testing.
Split-VM chain: k_proxy runs in k_proxy, k_server runs in k_server, and the Qubes forwarding layer must permit the chain.

Start Services

Same-VM quickstart

This matches the code defaults and is useful for basic app behavior only.

In the chosen VM:

python3 /home/user/chromecard/k_server_app.py --host 127.0.0.1 --port 8780 --proxy-token dev-proxy-token

In the same VM:

python3 /home/user/chromecard/k_proxy_app.py \
  --host 127.0.0.1 \
  --port 8770 \
  --session-ttl 300 \
  --server-base-url http://127.0.0.1:8780 \
  --proxy-token dev-proxy-token

Split-VM chain

This is the current Qubes target shape.

In k_server VM:

python3 /home/user/chromecard/k_server_app.py \
  --host 127.0.0.1 \
  --port 8780 \
  --proxy-token dev-proxy-token \
  --tls-certfile /home/user/chromecard/tls/phase2/k_server.crt \
  --tls-keyfile /home/user/chromecard/tls/phase2/k_server.key

In k_proxy VM:

qvm-connect-tcp 9780:k_server:8780

Notes:

python3 /home/user/chromecard/k_proxy_app.py \
  --host 127.0.0.1 \
  --port 8771 \
  --session-ttl 300 \
  --server-base-url https://127.0.0.1:9780 \
  --server-ca-file /home/user/chromecard/tls/phase2/ca.crt \
  --proxy-token dev-proxy-token \
  --tls-certfile /home/user/chromecard/tls/phase2/k_proxy.crt \
  --tls-keyfile /home/user/chromecard/tls/phase2/k_proxy.key

In k_client VM:

qvm-connect-tcp 9771:k_proxy:8771

Notes:

Current validated split-VM path is k_client localhost:9771 -> k_proxy localhost:8771 -> k_proxy localhost:9780 forward -> k_server localhost:8780.
Use --cacert /home/user/chromecard/tls/phase2/ca.crt for TLS verification in curl-based checks.
Raw VM-IP routing is not the validated path for the current prototype.

Test Flow

Use the proxy port that matches the mode you started:

Same-VM quickstart: 8770
Split-VM chain: 9771 from k_client, 8771 inside k_proxy

Create a session (runs auth gate once):

curl -sS -X POST http://127.0.0.1:<proxy-port>/session/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice"}'

Copy session_token from response, then:

TOKEN='<paste-token>'

Check session:

curl -sS -X POST http://127.0.0.1:<proxy-port>/session/status \
  -H "Authorization: Bearer $TOKEN"

Call protected resource multiple times (should not require new login):

curl -sS -X POST http://127.0.0.1:<proxy-port>/resource/counter \
  -H "Authorization: Bearer $TOKEN"
curl -sS -X POST http://127.0.0.1:<proxy-port>/resource/counter \
  -H "Authorization: Bearer $TOKEN"

Logout/invalidate:

curl -sS -X POST http://127.0.0.1:<proxy-port>/session/logout \
  -H "Authorization: Bearer $TOKEN"

Re-check after logout (should fail with 401):

curl -i -X POST http://127.0.0.1:<proxy-port>/resource/counter \
  -H "Authorization: Bearer $TOKEN"

Current Limitation

This uses card-presence probing, not a full WebAuthn assertion verification path.
Intended as a Phase 5 starter for session semantics and proxy/server behavior.
For the split-VM chain, the current blocker is not the Python prototype logic; it is refused qubes.ConnectTCP forwarding for the chain ports.

3.8 KiB Raw Blame History