161 lines
10 KiB
Markdown
161 lines
10 KiB
Markdown
---
|
||
phase: 01-federation-mesh-hardening
|
||
plan: 10
|
||
type: execute
|
||
wave: 6
|
||
depends_on: ["01-09"]
|
||
files_modified: []
|
||
autonomous: false
|
||
requirements: [FED-01, FED-02, FED-05, FED-06]
|
||
|
||
must_haves:
|
||
truths:
|
||
- "An operator who removes a federated peer on a live node does not see it reappear after at least two subsequent sync cycles"
|
||
- "A peer whose sync is failing shows the operator-visible sync-error badge on the live node, and the badge clears once that peer syncs successfully"
|
||
- "The channel-open flow works against a real node on the dev preview: the own-node URI copies, a trusted federated node opens in one click, a meshed Lightning peer can be sent a request, and a manually pasted URI is accepted"
|
||
- "The paid tick renders the branded ring on both payment-success surfaces on the dev preview, at a narrow and a desktop viewport, without clipping"
|
||
- "The demo and a real node behave the same through the mesh chat surface — aliasing a peer, reacting, editing, deleting, and sending an attachment produce the same modals and the same outcome on both"
|
||
prohibitions:
|
||
- statement: "The phase MUST NOT be signed off on demo evidence alone — every criterion in this checkpoint that names a real node is exercised against a real node, because a demo-only pass is exactly the divergence class this phase exists to remove"
|
||
category: transparency
|
||
artifacts: []
|
||
key_links: []
|
||
---
|
||
|
||
<objective>
|
||
Consolidate every human-gated verification this phase owes into one sign-off, run against the dev
|
||
pair rather than the demo.
|
||
|
||
Purpose: `01-VALIDATION.md` lists three manual-only verifications (removal sticking across real sync
|
||
cycles, the channel-open flow end to end, and the paid-tick visual), and CONTEXT.md adds the user's
|
||
own requirement that FED-05 and FED-06 are verified on the dev preview against archi-dev **before any
|
||
deploy**. Rather than interrupting each implementation plan with its own checkpoint, they are gathered
|
||
here so the operator is asked once, after the code is on the dev pair.
|
||
Output: a recorded sign-off, or a list of issues that becomes the input to a gap-closure pass.
|
||
</objective>
|
||
|
||
<execution_context>
|
||
@$HOME/.claude/gsd-core/workflows/execute-plan.md
|
||
@$HOME/.claude/gsd-core/templates/summary.md
|
||
</execution_context>
|
||
|
||
<context>
|
||
@.planning/PROJECT.md
|
||
@.planning/STATE.md
|
||
@.planning/phases/01-federation-mesh-hardening/01-VALIDATION.md
|
||
@.planning/phases/01-federation-mesh-hardening/01-CONTEXT.md
|
||
@.planning/phases/01-federation-mesh-hardening/01-09-SUMMARY.md
|
||
</context>
|
||
|
||
## Artifacts this phase produces
|
||
|
||
This plan produces no new symbols. It verifies the artifacts produced by plans 01-01 through 01-09:
|
||
the serialized federation store, the sync-error badge, the mesh Lightning identity and request
|
||
messages, the federation Lightning URI field, the channel-open picker modal, the branded paid tick,
|
||
and the demo RPC parity harness.
|
||
|
||
<tasks>
|
||
|
||
<task type="checkpoint:human-verify" gate="blocking">
|
||
<name>Task 1: Phase 1 consolidated verification on the dev pair</name>
|
||
<what-built>
|
||
Phase 1 in full, deployed to archi-dev-box and x250-dev and sha256-verified by plan 01-09:
|
||
- Federation node-store writes are serialized behind one lock with an atomic node-list write, so
|
||
a removal issued during a sync pass can no longer be undone by that sync.
|
||
- One periodic federation sync loop instead of two; per-peer sync failures are persisted and
|
||
shown as a badge on the node row, clearing when the peer recovers; out-of-order snapshots can
|
||
no longer move a peer's state backwards.
|
||
- A new channel-open picker modal reached from the Lightning panel's existing Open Channel
|
||
button: your own node's Lightning URI with a copy button, trusted federated nodes listed by
|
||
hostname with a one-click open, meshed peers running Lightning listed separately with a
|
||
request flow, and a manual URI paste fallback.
|
||
- The payment-success tick now uses the screensaver ring with its EQ segments on both the send
|
||
modal and the scan modal.
|
||
- The demo backend answers every mesh and federation RPC the UI calls, and reactions, edits,
|
||
deletes, and peer aliasing change demo state instead of returning a bare acknowledgement.
|
||
</what-built>
|
||
<how-to-verify>
|
||
Run these against the dev pair, not the demo, except where a step says demo.
|
||
|
||
1. **Removal sticks (FED-01).** On archi-dev-box, open the Federation view and remove a federated
|
||
peer. Wait through at least two auto-sync cycles — the loop runs every 90 seconds, so give it
|
||
four minutes — then reload. Expected: the peer is gone and stays gone. Then try removing a peer
|
||
that no longer exists (repeat the removal): expected an error message, not a silent success.
|
||
|
||
2. **Sync errors are visible (FED-02).** Make one federated peer unreachable — take its node off
|
||
the network, or block it — and wait one sync cycle. Expected: that node's row shows a sync-error
|
||
badge, and hovering it shows the error text and when it happened. Bring the peer back and wait
|
||
one more cycle. Expected: the badge clears on its own.
|
||
|
||
3. **Channel opening (FED-05).** Open the dev preview pointed at archi-dev and go to the Lightning
|
||
channels panel, then click Open Channel. Expected: a full-screen modal (the backdrop covers the
|
||
whole window and clicking outside closes it), showing your node's Lightning URI at the top.
|
||
Click Copy Lightning URI: expected the label flips to Copied! for about two seconds, and pasting
|
||
elsewhere gives the complete URI even though the on-screen text is shortened. Check the trusted
|
||
list shows your federated nodes by hostname with their FIPS or Tor badge. Check the meshed
|
||
Lightning peers list below it. Click Request Channel on a meshed peer, add a short message, and
|
||
send: expected a "request sent" style confirmation that does NOT claim a channel is open or
|
||
connected. Click Paste URI Manually, enter something malformed such as text with no at-sign:
|
||
expected a format message and no attempt to open. Then paste a valid peer URI: expected the
|
||
normal open flow. Finally, double-click Open Channel on a trusted node: expected one open
|
||
attempt, with the button disabled while it runs.
|
||
|
||
4. **Paid tick (FED-06).** On the dev preview, trigger a payment success in the send modal and in
|
||
the scan modal. Expected: the checkmark now sits inside the screensaver-style ring with the
|
||
radiating segment lines, at both a narrow phone width and a desktop width, with nothing cut off
|
||
by the edge of the card. The amount and the SENT wording are unchanged.
|
||
|
||
5. **Demo and real node match (FED-04).** On the demo, rename a mesh peer, react to a message,
|
||
edit one, delete one, and send a small file attachment. Then do the same on archi-dev.
|
||
Expected: the same modals appear in the same situations, the changes are visible in both, and
|
||
the browser console shows no "Method not found" errors on either.
|
||
|
||
6. **Single-node gate stays green (CLAUDE.md mandate).** Phase 1 modified daemon internals
|
||
(`federation/storage.rs`, `server.rs` — a periodic loop was removed), which falls under the
|
||
"re-run the gate after orchestrator/lifecycle changes" rule. Run `tests/lifecycle/run-gate.sh`
|
||
ON a dev-pair node (gate runs on-node, never via RPC). Expected: green, 0 not-ok. A full 5×
|
||
run on .228 is NOT required here (that is Phase 3's multinode criterion) — one clean pass on
|
||
the dev pair is the insurance this checkpoint needs.
|
||
|
||
If anything fails, describe what you saw and which numbered step it was — that becomes the gap
|
||
list for a closure pass rather than a re-run of the whole phase.
|
||
</how-to-verify>
|
||
<resume-signal>Type "approved" to sign off Phase 1, or describe the issues by step number.</resume-signal>
|
||
</task>
|
||
|
||
</tasks>
|
||
|
||
<threat_model>
|
||
## Trust Boundaries
|
||
|
||
| Boundary | Description |
|
||
|----------|-------------|
|
||
| operator judgement → phase sign-off | A human verdict gates whether this phase is considered complete |
|
||
| live fleet node → operator observation | Verification runs against real nodes carrying real federation trust and real Lightning funds |
|
||
|
||
## STRIDE Threat Register
|
||
|
||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||
| T-01-42 | Repudiation | signing off on demo evidence while a real node still fails | high | mitigate | Each step names where it runs; the prohibition above forbids demo-only sign-off; step 5 explicitly compares the two |
|
||
| T-01-43 | Elevation of Privilege | a removed peer regaining federation membership unnoticed because the check was too short | high | mitigate | Step 1 requires waiting at least two sync cycles at the 90-second interval, stated as a wall-clock duration rather than "a while" |
|
||
| T-01-44 | Denial of Service | the verification itself taking a live node off the network and leaving it that way | medium | mitigate | Step 2 restores the peer as part of the step and requires observing the badge clear, so the node cannot be left isolated as a side effect |
|
||
| T-01-45 | Spoofing | a channel opened against a peer-advertised URI during verification sending funds to the wrong node | high | mitigate | Step 3's request path targets a meshed peer with a request, not an open; the one-click open is exercised only against a bilaterally-trusted federated node the operator already federated with |
|
||
</threat_model>
|
||
|
||
<verification>
|
||
The operator's response is the verification. An "approved" response completes the phase; any
|
||
described issue is captured verbatim in the SUMMARY as a gap for `/gsd-plan-phase 1 --gaps`.
|
||
</verification>
|
||
|
||
<success_criteria>
|
||
- All five numbered checks were exercised, each in the place it names.
|
||
- The operator either approved or produced a numbered issue list.
|
||
- The outcome is recorded in the SUMMARY, including which node each check ran against.
|
||
</success_criteria>
|
||
|
||
<output>
|
||
Create `.planning/phases/01-federation-mesh-hardening/01-10-SUMMARY.md` when done, recording the
|
||
verdict, the node each check ran against, and any issue text verbatim.
|
||
</output>
|