Walkthroughs
============

Operator click-paths for the PFC console and config SPA. Screenshots are
captured by ``scripts/capture_ui.py`` (Playwright) against a local admin
with ``PFC_REQUIRE_AUTH=1``.

This is **not** a HIPAA/SOC 2/ISO certificate.

Vocabulary: **passthrough** means destination in the clear, body ciphertext;
**lookup_id** is the sender handle; **NATS** is the untrusted broker;
inspect officers are **share names**, not Google accounts.

Console login (separate from Peergos Drive)
-------------------------------------------

**Capability.** Create a console session. Drive login cannot unwrap cubes.

**Steps.**

1. Open https://pfc.georgelambert.org — username, password, TOTP.
2. First account becomes **admin**. Sign up, then enroll TOTP (authenticator URL).
3. Confirm a 6-digit code. Session cookie ``pfc_sess``.

**Why.** ``PFC_REQUIRE_AUTH=1``. HIPAA APIs require ``totp_ok``.

**Outcome.** Nav: Cubes, Catalog, Users, Inspect, Audit.

**Storage.** ``PFC_DATA`` UserStore JSON. Not Peergos cryptree.

.. image:: _static/screens/01-login.png
   :alt: PFC console sign-in
   :width: 90%

.. image:: _static/screens/02-totp-enroll.png
   :alt: TOTP enroll
   :width: 90%

Cubes, catalog, copy+stamp
--------------------------

**Capability.** Workspace cube ``<user>-ws`` holds library cards (Client,
Author, Subject, Title). Identity-preserving copy keeps original timestamp
and SHA-256.

**Steps.**

1. Create cube (hipaa lab stub or internal). Author must not be an inspect officer.
2. Append text or drop a file. Catalog prompt: keep cube defaults or edit this item.
3. Copy object into dest cube; stamp scope hash/public/sealed/files.
4. Comments/memos/links append the **cube** chain; unregistered hashes flush to
   ``verae.ts.batch`` about every 15s.

**Why.** First registered SHA-256 wins. Known hashes are not restamped.

**Outcome.** Object chips; workspace catalog search.

**Storage.** ``cubes/<id>/`` chain JSONL, ``catalog/card.json``, hash registry.
Pin via ``verae.storage.pin``; replicate via ``verae.storage.replicate``.

.. image:: _static/screens/03-cubes.png
   :alt: DataCubes
   :width: 90%

.. image:: _static/screens/04-catalog.png
   :alt: Card catalog
   :width: 90%

Users
-----

**Capability.** Admin creates officer accounts for k-of-n inspect.

**Steps.** Add username/password/role. Officers enroll their own TOTP.

**Why.** Two-officer presence. Author is not an officer.

**Storage.** UserStore under ``PFC_DATA``.

.. image:: _static/screens/05-users.png
   :alt: Users
   :width: 90%

Inspect (k-of-n)
----------------

**Capability.** Viewer-only reveal after k officers present. Log-before-reveal.

**Steps.**

1. Officer A **Start inspect** → join code (no session yet).
2. Officer B **Join** with the code → ``session_id``.
3. **View** object by sha256. **Close** ends the session.

**Why.** Shamir shares; Google SSO does not decrypt cubes.

**Outcome.** Audit events. HIPAA file bytes stay gated without a session.

**Storage.** Pending inspect JSON + audit log on the cube.

.. image:: _static/screens/06-inspect.png
   :alt: Inspect
   :width: 90%

Audit
-----

**Capability.** List access events for a cube (no payload bodies).

**Steps.** Enter cube id, **Load**.

**Storage.** Audit JSONL on the cube.

.. image:: _static/screens/07-audit.png
   :alt: Audit
   :width: 90%

Config SPA (unsigned preview only)
----------------------------------

**Capability.** Build a ``pfc.json`` preview. **Load requires an Ed25519
signed wrapper.** Admin ``POST /v1/admin/config`` signs and appends
admin-history (prev + new + diff).

**Steps.** Fill host / leaf hub / NATS URL / profile / min_ok. Preview JSON.
Download. Sign via console or ``secure_messaging.signed_config.sign``.

**Why.** Unsigned files are rejected.

.. image:: _static/screens/08-config-spa.png
   :alt: Config SPA
   :width: 90%

Secure message success vs failure
---------------------------------

**Success.** ``verae.sm.send`` with ``to`` + ciphertext → ack
``accepted=true`` + ``lookup_id``. Sender cannot reopen ``ct``.

**Failure.** Missing ``to`` or empty ``ct`` → ``SM-MISSING-TO`` /
``SM-EMPTY-CT``. Publishes ``verae.sm.log.summary`` (codes only),
``verae.sm.error`` (Network Error Bundle), ``verae.sm.dead``.
``ct_sender`` is sender-only; ``ct_system`` is the ops bounce report.