Skip to content

Commit b11deaf

Browse files
01rabbitclaude
01rabbit
and
claude
authored
docs: add coercion-safe delaying architecture threat model and security claims (#130)
Add COERCION_SAFE_DELAYING.md covering the three-component architecture (Silent Standby, dummy dataset, context profiles), security claims, non-claims, assumptions, and known limitations. Update THREAT_MODEL.md with a dedicated coercion-safe delaying section covering claims, non-claims, assumptions, known limitations, and allowed/disallowed behaviors. Update PHASMID_ARCHITECTURE.md with the three-component architecture description and recognition mode table. Update NON_CLAIMS.md with coercion-safe-specific non-claims. Update CLAIMS.md with CLM-36 through CLM-40 for the new features. Closes #124 Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 6fc278b commit b11deaf

5 files changed

Lines changed: 341 additions & 0 deletions

File tree

‎docs/CLAIMS.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,8 @@ A claim is listed with its source, verification method, and scope limitations.
3939
| CLM-33 | `PHASMID_MIN_PASSPHRASE_LENGTH` sets minimum passphrase length policy. | docs/SPECIFICATION.md §Passphrase policy | tests: `tests/test_passphrase_policy.py`, `tests/test_config.py` | Runtime configuration |
4040
| CLM-34 | No new network surfaces introduced for operator pages; routes are gated by web token and UI unlock checks. | docs/TUI_OPERATOR_CONSOLE.md §Security notes | tests: `tests/test_web_server.py` | Operator pages |
4141
| CLM-35 | Running `phasmid doctor` is diagnostic and does not certify the host as secure. | src/phasmid/models/doctor.py disclaimer | tests: `tests/test_tui.py`, `tests/test_doctor_m4.py` | Doctor output semantics |
42+
| CLM-36 | Context profiles guide dummy generation and plausibility validation; built-in profiles are `travel`, `field_engineer`, `researcher`, `maintenance`, `archive`. | docs/COERCION_SAFE_DELAYING.md §Context Profile Templates | tests: `tests/test_context_profile.py` | Context profile schema |
43+
| CLM-37 | Dummy dataset plausibility report generates local-only advisory output: container size, dummy size, occupancy ratio, file count, file type distribution, and warnings. | docs/COERCION_SAFE_DELAYING.md §Plausible Dummy Dataset | tests: `tests/test_dummy_generator.py` | Dummy plausibility report |
44+
| CLM-38 | Silent Standby clears sensitive UI state on hotkey trigger; recovery requires re-authentication. | docs/COERCION_SAFE_DELAYING.md §Silent Standby | tests: `tests/test_standby_state.py` | Standby state transitions |
45+
| CLM-39 | Coercion-safe recognition mode routes low-confidence recognition to dummy disclosure path, not to an obvious access-denied response. | docs/COERCION_SAFE_DELAYING.md §Coercion-Safe Recognition Fallback | tests: `tests/test_recognition_routing.py` | Recognition mode routing |
46+
| CLM-40 | Dummy generator does not forge forensic artifacts, fake kernel logs, or perform timestamp forgery. | docs/COERCION_SAFE_DELAYING.md §Disallowed Behaviors | tests: `tests/test_dummy_generator.py` | Dummy generation restrictions |

‎docs/COERCION_SAFE_DELAYING.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Coercion-Safe Delaying Architecture
2+
3+
## Overview
4+
5+
Phasmid implements a coercion-safe delaying architecture to increase uncertainty,
6+
delay confident conclusions, separate coerced disclosure from true disclosure, and
7+
improve operator survivability in hostile or coercive environments.
8+
9+
This architecture does not claim permanent secrecy against unlimited forensic
10+
analysis. Its purpose is to avoid immediate proof, increase investigation cost
11+
and time, and provide plausible controlled disclosure under stress, coercion, or
12+
opportunistic inspection.
13+
14+
---
15+
16+
## Design Principles
17+
18+
- Prioritize survivability over perfect secrecy.
19+
- Avoid obvious failure states under coercion.
20+
- Prefer plausible ambiguity over active deception.
21+
- Use pre-consistent disclosure profiles instead of emergency fake generation.
22+
- Avoid claims of forensic invisibility.
23+
- Avoid anti-forensic or malware-like behavior.
24+
- Treat delay and uncertainty as defensive mechanisms.
25+
26+
---
27+
28+
## Security Claims
29+
30+
| Claim | Description |
31+
|---|---|
32+
| Separation of coerced from true disclosure | Coerced disclosure path uses a pre-configured dummy profile that is operationally separate from the true disclosure path. |
33+
| Immediate proof avoidance | No single action or observation confirms or denies the existence of protected content. |
34+
| Increased analysis cost | An adversary must invest time to distinguish dummy content from protected content. |
35+
| Pre-consistent disclosure | Dummy profiles are configured and populated before any coercive event, not generated on demand. |
36+
| Local-only operation | All standby, dummy, and profile operations are local. No network calls are introduced. |
37+
| Natural coercion-safe flow | Standby and dummy disclosure transitions do not require suspicious rapid key sequences or visible "panic" indicators. |
38+
39+
---
40+
41+
## Non-Claims
42+
43+
- Phasmid does not guarantee permanent secrecy against a capable forensic examiner
44+
with unlimited time and resources.
45+
- Phasmid does not claim that dummy content is indistinguishable under forensic analysis.
46+
- Phasmid does not forge or tamper with filesystem metadata, kernel logs, or timestamps.
47+
- Phasmid does not conceal the existence of the software itself.
48+
- Phasmid does not provide coercion-proof operation; survivability is a probabilistic
49+
improvement, not an absolute guarantee.
50+
- Silent Standby does not erase data; it removes it from the visible UI surface only.
51+
- Recovery from standby requires re-authentication; no automatic re-entry is provided.
52+
53+
---
54+
55+
## Assumptions
56+
57+
- The operator has pre-populated a plausible dummy profile before any coercive event.
58+
- The dummy profile is internally consistent: file types, sizes, and directory structure
59+
match the declared context profile.
60+
- The operator activates standby before a coercive party reaches the active UI state.
61+
- The hardware form factor does not itself attract hostile inspection.
62+
- The host operating system is not compromised at the time of standby activation.
63+
64+
---
65+
66+
## Known Limitations
67+
68+
- Standby transition is a UI-layer operation. It does not erase key material from memory.
69+
- A live memory capture performed after standby activation but before process exit may
70+
still expose in-memory key material.
71+
- Dummy content plausibility depends entirely on operator preparation; a trivially empty
72+
or structurally inconsistent dummy profile reduces survivability.
73+
- Recognition confidence routing (coercion_safe mode) routes low-confidence recognition
74+
to dummy disclosure but does not verify physical coercion context.
75+
- The dummy plausibility report is a local advisory tool; it does not verify adversarial
76+
perception.
77+
78+
---
79+
80+
## Three-Component Architecture
81+
82+
### 1. Silent Standby
83+
84+
Silent Standby provides a coercion-safe transition from a sensitive UI state to a
85+
non-sensitive standby state.
86+
87+
States:
88+
89+
```text
90+
active - Normal operation; sensitive UI visible.
91+
standby - Sensitive UI cleared; non-sensitive screen displayed.
92+
sealed - Session sealed; re-authentication required to return to active.
93+
dummy_disclosure - Operator is presenting dummy content as the apparent data.
94+
```
95+
96+
Transition rules:
97+
98+
- `active → standby`: Triggered by configurable hotkey (default: Ctrl+S).
99+
- `standby → sealed`: Automatic; standby always seals the session.
100+
- `sealed → active`: Requires re-authentication; direct re-entry to prior state is disallowed.
101+
- `sealed → dummy_disclosure`: Coercion-safe mode routes naturally toward dummy path.
102+
103+
What standby clears:
104+
105+
- Visible sensitive content in the TUI.
106+
- True-profile UI references.
107+
- Temporary display buffers.
108+
109+
What standby does NOT do:
110+
111+
- Erase key material from process memory.
112+
- Prevent a live memory capture from recovering in-use key material.
113+
- Fabricate system events or fake log entries.
114+
- Hide the Phasmid process from the process list.
115+
116+
### 2. Plausible Dummy Dataset
117+
118+
Dummy datasets provide a disclosure-ready alternative content set that can plausibly
119+
stand alone without the true protected content being visible or required.
120+
121+
Dummy content rules:
122+
123+
- Generated or imported before any coercive event.
124+
- Context-consistent: file types and directory structure match the declared context profile.
125+
- Occupancy ratio must be plausible relative to the container size.
126+
- File count and size distribution must be realistic for the declared context.
127+
128+
Explicit restrictions:
129+
130+
- No forged forensic artifacts.
131+
- No fake kernel logs or system event fabrication.
132+
- No timestamp forgery or anti-forensic metadata tampering.
133+
- No intentional forensic-tool deception.
134+
- No malware-like behavior.
135+
136+
### 3. Context Profile Templates
137+
138+
Context profiles define the expected content structure for a given operational context.
139+
They guide dummy generation and provide plausibility validation.
140+
141+
Built-in profiles:
142+
143+
| Profile | Intended Use | Typical Content |
144+
|---|---|---|
145+
| `travel` | Travel data carrier | Images, itinerary, notes, receipts |
146+
| `field_engineer` | Engineering field work | Logs, configs, exported diagnostics, manuals |
147+
| `researcher` | Research material | PDFs, notes, references, exported datasets |
148+
| `maintenance` | Device maintenance | Diagnostic exports, system check results, update files |
149+
| `archive` | Long-term archive | Documents, media, backups |
150+
151+
---
152+
153+
## Coercion-Safe Recognition Fallback
154+
155+
Recognition mode controls how the system responds to low-confidence or failed recognition.
156+
157+
| Mode | Behavior |
158+
|---|---|
159+
| `strict` | Mismatch → failure |
160+
| `coercion_safe` | Low confidence → dummy disclosure path |
161+
| `demo` | Safe debug visibility |
162+
163+
In `coercion_safe` mode:
164+
165+
- Low recognition confidence routes to dummy disclosure rather than returning an obvious
166+
access-denied error.
167+
- Repeated recognition instability also routes to dummy disclosure.
168+
- The transition is natural and does not produce visible "access denied" loops.
169+
170+
Failure handling rules:
171+
172+
- Repeated obvious lockout messages are avoided.
173+
- Aggressive error messages are avoided.
174+
- Visible "access denied" cycling is avoided.
175+
176+
---
177+
178+
## Allowed and Disallowed Behaviors
179+
180+
### Allowed
181+
182+
- Plausible dummy disclosure using pre-configured content.
183+
- Privacy-preserving standby transitions that remove sensitive UI state.
184+
- Ambiguity-preserving workflows where no single observation confirms or denies.
185+
- Local-only operation with no network side effects.
186+
- Configurable hotkey-triggered standby.
187+
- Context-profile-guided dummy structure.
188+
- Local plausibility reports for operator self-assessment.
189+
190+
### Disallowed
191+
192+
- Rootkits or kernel-level hiding mechanisms.
193+
- Hidden process persistence.
194+
- Anti-forensic data destruction triggered by coercion detection.
195+
- Forensic tool bypass or interference.
196+
- Malware-like concealment behavior.
197+
- False system event fabrication.
198+
- Timestamp forgery.
199+
- Fake law enforcement or intrusion log generation.
200+
- Anti-forensic metadata tampering.
201+
202+
---
203+
204+
## Operational Guidance
205+
206+
Before deployment in any environment where coercion is a realistic risk:
207+
208+
1. Select a context profile appropriate to the operational context.
209+
2. Populate the dummy dataset with plausible, context-consistent content.
210+
3. Run the dummy plausibility report and resolve all warnings.
211+
4. Test the standby transition to confirm it clears the sensitive UI.
212+
5. Confirm that re-authentication is required to return from standby.
213+
6. Review the Seizure Review Checklist (`docs/SEIZURE_REVIEW_CHECKLIST.md`).
214+
215+
---
216+
217+
## References
218+
219+
- `docs/THREAT_MODEL.md` — threat model and adversary definitions
220+
- `docs/NON_CLAIMS.md` — explicit non-claims inventory
221+
- `docs/CLAIMS.md` — claims inventory
222+
- `docs/SEIZURE_REVIEW_CHECKLIST.md` — seizure-condition review checklist
223+
- `docs/FIELD_TEST_PROCEDURE.md` — field testing procedures
224+
- `docs/JANUS_EIDOLON_SYSTEM.md` — two-slot architecture specification

‎docs/NON_CLAIMS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,23 @@ Each item includes a brief rationale to keep review and deployment decisions exp
4646

4747
- Phasmid does not promise a single maintainer (bus factor 1) sustainability guarantee.
4848
Rationale: long-term response capacity and maintenance continuity can be constrained by single-maintainer limits.
49+
50+
## Coercion-Safe Delaying Non-Claims
51+
52+
- Phasmid does not guarantee permanent secrecy against unlimited forensic analysis.
53+
Rationale: the coercion-safe architecture increases uncertainty and investigation cost; it does not eliminate the adversary's eventual ability to distinguish dummy from protected content.
54+
55+
- Phasmid does not claim that dummy content is indistinguishable under expert forensic analysis.
56+
Rationale: an expert forensic examiner with sufficient time may identify structural differences between dummy and true content.
57+
58+
- Phasmid does not forge or tamper with filesystem metadata, kernel logs, or timestamps.
59+
Rationale: anti-forensic tampering is an explicitly disallowed behavior.
60+
61+
- Silent Standby does not erase key material from process memory.
62+
Rationale: standby is a UI-layer operation; live memory capture after standby may still expose in-memory key material.
63+
64+
- Phasmid does not detect or verify physical coercion context.
65+
Rationale: coercion-safe recognition mode routes based on recognition confidence, not on verified coercion state.
66+
67+
- Dummy plausibility is entirely dependent on operator preparation.
68+
Rationale: the plausibility report is advisory; a trivially empty or inconsistent dummy profile reduces survivability.

‎docs/PHASMID_ARCHITECTURE.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,33 @@ The architecture preserves these constraints:
3434
- restricted actions require server-side checks and explicit confirmation
3535
- Field Mode reduces exposure but is not a security boundary
3636

37+
## Coercion-Safe Delaying Architecture
38+
39+
Phasmid implements a three-component coercion-safe delaying architecture:
40+
41+
1. **Silent Standby** — Transitions from sensitive UI state to non-sensitive standby
42+
on a configurable hotkey. States: `active`, `standby`, `sealed`, `dummy_disclosure`.
43+
Recovery requires re-authentication. Standby does not erase key material from memory.
44+
45+
2. **Plausible Dummy Dataset** — Pre-configured context-consistent content for
46+
controlled disclosure. Generated before any coercive event. Guided by context
47+
profiles. Evaluated by the plausibility report.
48+
49+
3. **Context Profile Templates** — Schemas that define expected content for a given
50+
operational context (`travel`, `field_engineer`, `researcher`, `maintenance`,
51+
`archive`). Guide dummy generation and plausibility validation.
52+
53+
Recognition modes control response to low-confidence recognition:
54+
55+
- `strict` — mismatch is a failure
56+
- `coercion_safe` — low confidence routes to dummy disclosure path
57+
- `demo` — safe debug visibility
58+
59+
This architecture does not claim forensic invisibility. It increases uncertainty,
60+
delays confident conclusions, and avoids obvious failure states under coercion.
61+
62+
See `docs/COERCION_SAFE_DELAYING.md` for full design documentation.
63+
3764
## Current Documentation Map
3865

3966
- [docs/SPECIFICATION.md](docs/SPECIFICATION.md) defines implementation behavior and configuration.

‎docs/THREAT_MODEL.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -423,6 +423,71 @@ Phasmid explicitly does not aim to provide:
423423

424424
---
425425

426+
## Coercion-Safe Delaying Architecture
427+
428+
Phasmid implements a coercion-safe delaying architecture to increase uncertainty,
429+
delay confident conclusions, and provide plausible controlled disclosure.
430+
431+
### Security Claims
432+
433+
- Separates coerced disclosure path from true disclosure path using pre-configured
434+
controlled-disclosure datasets.
435+
- Avoids immediate proof by ensuring no single observation confirms or denies
436+
the existence of protected content.
437+
- Increases adversarial analysis cost through context-consistent pre-configured content.
438+
- Silent Standby removes sensitive UI state on a configurable hotkey trigger.
439+
- Coercion-safe recognition mode routes low-confidence recognition to the
440+
controlled-disclosure path rather than an obvious access-denied response.
441+
442+
### Non-Claims
443+
444+
- Phasmid does not guarantee permanent secrecy against unlimited forensic analysis.
445+
- Phasmid does not forge or tamper with filesystem metadata, kernel logs, or timestamps.
446+
- Phasmid does not conceal the existence of the software itself.
447+
- Silent Standby does not erase key material from process memory.
448+
- Pre-configured disclosure content is not guaranteed to be indistinguishable under
449+
expert forensic analysis.
450+
451+
### Assumptions
452+
453+
- The operator has pre-populated a plausible controlled-disclosure dataset before
454+
any coercive event.
455+
- The controlled-disclosure dataset is internally consistent with the declared
456+
operational context template.
457+
- The operator activates standby before a coercive party reaches the active UI state.
458+
- The host operating system is not compromised at the time of standby activation.
459+
460+
### Known Limitations
461+
462+
- Standby is a UI-layer operation; it does not erase in-memory key material.
463+
- Controlled-disclosure content plausibility depends entirely on operator preparation.
464+
- Recognition confidence routing does not verify physical coercion context.
465+
- Plausibility warnings are advisory; they do not verify adversarial perception.
466+
467+
### Allowed Behaviors
468+
469+
- Plausible controlled disclosure using pre-configured content.
470+
- Privacy-preserving standby transitions that remove sensitive UI state.
471+
- Ambiguity-preserving workflows.
472+
- Configurable hotkey-triggered standby.
473+
- Operational context template-guided content structure.
474+
- Local plausibility reports.
475+
476+
### Disallowed Behaviors
477+
478+
- Rootkits or kernel-level hiding.
479+
- Hidden process persistence.
480+
- Anti-forensic data destruction.
481+
- Forensic tool bypass or interference.
482+
- Malware-like concealment.
483+
- False system event fabrication.
484+
- Timestamp forgery.
485+
- Anti-forensic metadata tampering.
486+
487+
For full architectural documentation see `docs/COERCION_SAFE_DELAYING.md`.
488+
489+
---
490+
426491
## Operational Guidance
427492

428493
- Keep `PHASMID_HOST` at the default `127.0.0.1` unless the host is otherwise protected.

0 commit comments

Comments
 (0)