Add Physical Security framework

[AllyPry]

Summary

This PR establishes Physical Security as a top-level framework and restructures it
from a wrench-attack-only framework into a proper domain, following @mattaereal's feedback
and the action plan discussed on this PR. (Top-level placement agreed with @scode2277 and
@mattaereal on Discord.)

What changed

Restructure into a domain

• physical-security/overview.mdx is now a domain-level overview (people, physical assets,
  counter-surveillance, supply-chain integrity) with a cross-reference to Operational Security.
• The original 10 wrench-attack pages moved into a Coercion & Duress sub-section
  (physical-security/coercion-and-duress/).
• Added stub sub-sections (dev: true) for the rest of the domain: Facility & Perimeter
  Security, Physical Counter-Surveillance, Supply Chain Physical Integrity.
• Renamed personal-and-family-opsec → personal-and-family-safety.
• Updated the vocs.config.tsx sidebar to the nested structure.

Review feedback addressed

• Reframed the decoy / "plausibility" guidance toward controlled surrender (a small,
  truthful payout + visible friction via time-locks and multi-party approval + duress
  tripwires), per @ElliotFriedman and @mattaereal.
• Fixed QA issues: contributor typo (Allypry → AllyPry), missing trailing newlines,
  and the Overview sidebar link missing its leading slash.

Branch

• Updated with develop — no longer conflicting.

Deferred to a follow-up PR

• De-overlapping Operational Security (Travel guide, Control Domains) with Coercion & Duress,
  plus cross-references in both directions.

Structure

overview.mdx domain overview
coercion-and-duress/ the original 10 pages
facility-and-perimeter/ stub (dev)
physical-counter-surveillance/ stub (dev)
supply-chain-physical-integrity/ stub (dev)

[github-actions]

Sidebar Configuration Reminder

This PR includes added, renamed, or removed documentation files:

• docs/pages/physical-security/checklist.mdx (added)
• docs/pages/physical-security/defensive-design-principles.mdx (added)
• docs/pages/physical-security/incident-response.mdx (added)
• docs/pages/physical-security/overview.mdx (added)
• docs/pages/physical-security/personal-and-family-opsec.mdx (added)
• docs/pages/physical-security/recovery-and-resilience.mdx (added)
• docs/pages/physical-security/risk-factors-and-early-signals.mdx (added)
• docs/pages/physical-security/threat-model.mdx (added)
• docs/pages/physical-security/transaction-flows-under-duress.mdx (added)
• docs/pages/physical-security/wallet-and-key-architecture.mdx (added)

Please ensure that:

• The sidebar in vocs.config.tsx has been updated to include these files
• New content has the dev: true parameter so it's marked as under development
• Sidebar links match the file paths - use the preview deployment to verify

See Contributing Guide – Sidebar & Navigation for more details.

---

_{This is an automated reminder. If this PR doesn't need sidebar changes, you can ignore this message.}

[frameworks-volunteer]

Model: z-ai/glm-5.1 Reasoning: medium Provider: openrouter

Security Review

No issues found. Content is static MDX with standard components. No secrets, injection vectors, or sensitive data exposure.

QA Review

Found 2 issues that should be fixed before merge, plus 2 minor suggestions.

Issues (should fix)

1. threat-model.mdx -- contributor typo: users: [Allypry] (lowercase 'p') while all other pages use users: [AllyPry] (uppercase 'P'). GitHub usernames are case-sensitive and the contributor lookup in contributors.json uses AllyPry as the key, so this will break attribution rendering on the threat model page.

2. Missing trailing newlines: 8 of 10 new MDX files lack a trailing newline (\ No newline at end of file in the diff). This can cause markdownlint failures or noisy diffs on future edits. Affected files: defensive-design-principles.mdx, incident-response.mdx, overview.mdx, recovery-and-resilience.mdx, risk-factors-and-early-signals.mdx, threat-model.mdx, transaction-flows-under-duress.mdx, wallet-and-key-architecture.mdx.

Suggestions (non-blocking)

3. vocs.config.tsx -- inconsistent link prefix: Overview entry uses 'physical-security/overview' (no leading slash) while all other Physical Security entries use '/physical-security/...' (with leading slash). Consider making this consistent to avoid potential navigation issues.

4. Missing dev: true: New sidebar items lack dev: true. If this content is considered WIP, add dev: true per AGENTS.md convention. If production-ready, this is fine as-is.

Looks Good

• Well-structured content following playbook template (Key Takeaway, practical guidance sections)
• Comprehensive coverage of the wrench attack threat landscape
• Internal links in overview match actual page paths
• contributors.json entry format is correct
• No hardcoded secrets or placeholder content
• Component imports and TagProvider usage consistent with existing pages

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
frameworks	✅ Ready (View Log)	Visit Preview	1ff1add

[mattaereal]

@shallem do you think we could include this somehow inside OpSec, or keep it as a separate framework? I think this is big enough to have it's own category and be cross-referenced, even add more stuff not directly related to wallets, like networking, and such, which was mentioned in the opsec while traveling, where there is a lot of overlap with this.

[mattaereal]

@AllyPry Thanks again for the contribution. It will probably take me a while to reply accordingly because of several reasons:

1. It overlaps with opsec's sub-categories
2. It is framed specifically about wrench attacks, and physical security is way more broad than that
3. We not only need to review this, but decide a potential structural change to re-adapt it to feature more different physical security suggestions, and not turning the entire framework into a specific threat model when there are clearly more, and also de-overlap the current contents so we can create a more robust Physical security framework, or pour this into a subcategory within Opsec

You're more than welcome to give an opinion and suggest a path forward

[AllyPry]

Maybe "Physical Security" can have its own category and the wrench attacks framework could be a subcategory?

[mattaereal]

@frameworks-volunteer, with all the context you have from frameworks, agent.md, skill.md, from the latest development, where would you place Physical security? As a sub-section in opsec, or in a separate framework? In any case you'd suggest, or even both, how would you restructure the contents to be a fit? Because right now it appears to be only a 'wrench attack framework' rather than an actual domain.

[frameworks-volunteer]

Model: z-ai/glm-5.1 Reasoning: medium Provider: openrouter

After reviewing the current frameworks structure and the PR content, here is my assessment.

Physical Security deserves its own top-level framework, but the current content is too narrow

The PR adds 10 pages all scoped to wrench attacks against crypto key-holders. Physical security is a legitimate domain with breadth beyond coercion -- perimeter security, access control, surveillance countermeasures, secure facility design, environmental hazards, supply-chain physical tampering, and more. As written, this is a "Wrench Attack Defense" framework, not a "Physical Security" framework. That is the core structural problem.

Recommended placement: separate top-level framework (not under OpSec)

Reasons:

1. OpSec is already overloaded -- it has 14 sidebar entries spanning core concepts, OS hardening, browser security, MFA, passwords, Google Workspace, control domains, travel, and appendices. Adding physical security as a sub-section would make it the dumping ground for anything "not purely technical."

2. OpSec and Physical Security have different primary threats -- OpSec mitigates information disclosure through procedural and digital controls. Physical Security mitigates bodily harm, forced access, and environmental threats. The defensive principles differ (information compartmentalization vs. physical barriers/deterrence/deception).

3. Cross-referencing is cleaner than nesting -- OpSec/Travel already touches on physical safety (device theft, border coercion, physical SIM swaps). These should reference a Physical Security framework rather than duplicate it. Similarly, the wrench-attack wallet architecture content overlaps with Wallet Security. Cross-links solve this without forcing one domain under another.

Proposed restructure of the PR content

Rename the framework scope from "Physical Security" to its actual domain, then expand:

Option A: Keep "Physical Security" as the top-level name, restructure internally

• overview.mdx -- Broaden to cover the full physical security domain (not just wrench attacks). Wrench attacks become one threat category among several.
• Sub-categories:
  • Coercion & Duress (current wrench-attack content goes here)
    • Threat Model, Risk Factors, Defensive Design Principles, Wallet Architecture under Duress, Transaction Flows under Duress, Incident Response, Recovery & Resilience, Personal & Family OPSEC, Checklist
  • Facility & Perimeter Security (stub -- access control, surveillance, environmental, secure rooms)
  • Physical Counter-Surveillance (stub -- detecting physical surveillance, countermeasures)
  • Supply Chain Physical Integrity (stub -- tamper evidence, hardware supply chain)

Cross-references:

• From OpSec/Travel: "For coercion-specific defenses, see Physical Security > Coercion & Duress"
• From Wallet Security: "For duress-resistant wallet designs, see Physical Security > Coercion & Duress > Wallet Architecture"

Option B: Rename to "Coercion & Duress Defense" as its own framework

If the contributor and maintainers prefer to keep the current scope tight rather than expand into a broader physical security domain, rename it to match what it actually covers. This avoids the "wrench attack framework masquerading as a domain" problem and leaves room for a future Physical Security framework with broader scope.

What to de-overlap from OpSec

The OpSec/Travel guide mentions: physical theft, coercion, duress codes, decoy wallets, border inspections. These are coercion/duress topics. If Option A is chosen, those references should be trimmed from the Travel guide and point to the Physical Security framework instead. The Travel guide should focus on: device hardening, network safety, border digital-inspection protocols, and post-trip audit -- not coercion defense.

Summary

• Separate top-level framework (not under OpSec)
• Restructure current content as a "Coercion & Duress" sub-section within Physical Security, not the entire framework
• Cross-reference from OpSec/Travel and Wallet Security
• If scope stays wrench-attacks-only, rename the framework accordingly (Option B)
• The overview.mdx must be rewritten to introduce physical security as a domain, not just wrench attacks

[mattaereal]

@frameworks-volunteer, generate a detailed action plan for option A of the plans you suggested above, in which we decouple the Opsec domain from Physical Security and transform it into a proper top-level domain.

[frameworks-volunteer]

Model: z-ai/glm-5.1 Reasoning: medium Provider: openrouter

Detailed Action Plan: Decouple OpSec from Physical Security (Option A)

This plan transforms Physical Security into a proper top-level domain and restructures the current PR #501 content from a narrow "wrench-attack framework" into a broader Physical Security domain with the coercion content as one sub-category.

---

Phase 1: Restructure the Physical Security Directory Layout

Current PR #501 layout (all flat, all coercion-focused):

docs/pages/physical-security/
  overview.mdx
  threat-model.mdx
  risk-factors-and-early-signals.mdx
  defensive-design-principles.mdx
  wallet-and-key-architecture.mdx
  personal-and-family-opsec.mdx
  transaction-flows-under-duress.mdx
  incident-response.mdx
  recovery-and-resilience.mdx
  checklist.mdx

Target layout (sub-categorized, coercion as one section, stubs for other sub-domains):

docs/pages/physical-security/
  overview.mdx                           (REWRITE - broaden scope)
  coercion-and-duress/                   (NEW sub-directory)
    overview.mdx                         (NEW - scope the sub-category)
    threat-model.mdx                     (MOVE from current threat-model.mdx)
    risk-factors-and-early-signals.mdx   (MOVE)
    defensive-design-principles.mdx      (MOVE)
    wallet-and-key-architecture.mdx      (MOVE)
    transaction-flows-under-duress.mdx   (MOVE)
    incident-response.mdx               (MOVE)
    recovery-and-resilience.mdx          (MOVE)
    personal-and-family-opsec.mdx        (MOVE)
    checklist.mdx                        (MOVE)
  facility-and-perimeter/                (NEW stub sub-directory)
    overview.mdx                         (NEW stub)
  physical-counter-surveillance/         (NEW stub sub-directory)
    overview.mdx                         (NEW stub)
  supply-chain-physical-integrity/       (NEW stub sub-directory)
    overview.mdx                         (NEW stub)

Steps:

1. Create the coercion-and-duress/ sub-directory
2. Move all 9 existing coercion-scoped MDX files into it
3. Add coercion-and-duress/overview.mdx as a sub-category landing page
4. Update all internal links within moved files (relative path changes from ../components to ../../../components, and any cross-page links)
5. Create stub overview pages for the 3 new sub-categories with > ⚠️ Stub/in progress, help contribute/expand notices
6. Rewrite physical-security/overview.mdx (see Phase 2)

---

Phase 2: Rewrite the Top-Level Overview

The current overview.mdx is scoped to wrench attacks only:

• Title: "Overview | Security Alliance"
• Description: "...wrench attacks are, why they matter now..."

Target: a proper domain-level overview covering:

1. What Physical Security encompasses as a domain (not just coercion):

   • Protection of people from bodily harm, forced access, and environmental threats
   • Protection of physical assets from theft, tampering, and destruction
   • Physical counter-surveillance and detection
   • Supply chain physical integrity (tamper evidence, hardware provenance)

2. Relationship to Operational Security: Distinct domains with cross-references

   • OpSec = procedural + digital controls to prevent information disclosure
   • Physical Security = barriers, deterrence, deception, and response against physical threats
   • Overlap areas (travel, device theft) handled via cross-links, not duplication

3. Sub-categories within this framework:

   • Coercion & Duress (current PR content, most mature)
   • Facility & Perimeter Security (stub)
   • Physical Counter-Surveillance (stub)
   • Supply Chain Physical Integrity (stub)

4. Who this framework serves: Individuals, organizations, and protocols with crypto holdings or high-value physical assets

5. Frontmatter updates:

   • title: "Physical Security | Security Alliance" (under 60 chars)
   • description: ~150 chars, action verbs, domain-broad keywords

---

Phase 3: Extract Physical Content from OpSec

Content in OpSec that belongs in Physical Security (to be de-overlapped):

3a. OpSec > Control Domains > Physical & Environmental Controls

• Path: docs/pages/opsec/control-domains/physical-environmental/
• Current files: secure-workspace-travel.mdx (stub), tamper-evidence.mdx (stub)
• Action:
  • Move tamper-evidence.mdx to physical-security/supply-chain-physical-integrity/tamper-evidence.mdx (or cross-reference if move is too disruptive)
  • Rewrite secure-workspace-travel.mdx to focus on the OpSec perspective (procedural controls for workspace/travel) and add cross-reference: "For physical security measures at travel destinations, see Physical Security > Coercion & Duress"
  • Update opsec/control-domains/overview.mdx Section Outline to link to the new Physical Security framework for the physical-environmental sub-items, rather than hosting them inline

3b. OpSec > Travel Guide

• Path: docs/pages/opsec/travel/guide.mdx
• Sections containing coercion/duress content (identified by grep):
  • Line ~80: coercion in threat model
  • Line ~152: disabling Touch ID/Face ID for forced-unlock scenarios
  • Line ~373-392: "Physical safety and common sense" section mentions tamper-evident seals, decoy containers
  • Line ~525-527: duress codes, decoy accounts, forced disclosure
• Action:
  • Trim the coercion-specific guidance from the Travel guide
  • Add cross-references to Physical Security for each trimmed section
  • Keep the Travel guide focused on: device hardening, network safety, border digital-inspection protocols, SIM/eSIM security, USB attack prevention, post-trip audit -- the digital/procedural side of travel OpSec

3c. OpSec Overview

• Path: docs/pages/opsec/overview.mdx
• Currently lists Travel as a sub-section
• Action: Add a "Related Frameworks" section linking to Physical Security

---

Phase 4: Update vocs.config.tsx Sidebar

Current PR sidebar (flat list under "Physical Security"):

text: 'Physical Security',
collapsed: true,
items: [
  { text: 'Overview', link: 'physical-security/overview' },
  { text: 'Threat Model', link: '/physical-security/threat-model' },
  ... (8 more flat entries)
]

Target sidebar (nested sub-categories):

text: 'Physical Security',
collapsed: true,
items: [
  { text: 'Overview', link: '/physical-security/overview' },
  {
    text: 'Coercion & Duress',
    collapsed: true,
    items: [
      { text: 'Overview', link: '/physical-security/coercion-and-duress/overview' },
      { text: 'Threat Model', link: '/physical-security/coercion-and-duress/threat-model' },
      { text: 'Risk Factors and Early Signals', link: '/physical-security/coercion-and-duress/risk-factors-and-early-signals' },
      { text: 'Defensive Design Principles', link: '/physical-security/coercion-and-duress/defensive-design-principles' },
      { text: 'Wallet and Key Architecture', link: '/physical-security/coercion-and-duress/wallet-and-key-architecture' },
      { text: 'Transaction Flows Under Duress', link: '/physical-security/coercion-and-duress/transaction-flows-under-duress' },
      { text: 'Incident Response', link: '/physical-security/coercion-and-duress/incident-response' },
      { text: 'Recovery and Resilience', link: '/physical-security/coercion-and-duress/recovery-and-resilience' },
      { text: 'Personal and Family OpSec', link: '/physical-security/coercion-and-duress/personal-and-family-opsec' },
      { text: 'Checklist', link: '/physical-security/coercion-and-duress/checklist' },
    ]
  },
  {
    text: 'Facility & Perimeter Security',
    collapsed: true,
    dev: true,
    items: [
      { text: 'Overview', link: '/physical-security/facility-and-perimeter/overview', dev: true },
    ]
  },
  {
    text: 'Physical Counter-Surveillance',
    collapsed: true,
    dev: true,
    items: [
      { text: 'Overview', link: '/physical-security/physical-counter-surveillance/overview', dev: true },
    ]
  },
  {
    text: 'Supply Chain Physical Integrity',
    collapsed: true,
    dev: true,
    items: [
      { text: 'Overview', link: '/physical-security/supply-chain-physical-integrity/overview', dev: true },
    ]
  },
]

Also update the OpSec sidebar section:

• Add a "Related Frameworks" note or link to Physical Security
• Consider adding dev: true to the Coercion & Duress items initially (since they are being restructured)

---

Phase 5: Update Frontmatter on Moved Files

Every moved MDX file needs:

1. Title remains the same (they are still accurate within the sub-category)
2. Description may need minor adjustment (replace "wrench-attack" framing with "coercion-and-duress" framing where it appears)
3. Import paths for components change from '../../../components' to '../../../../components' (one level deeper)
4. Contributors field: keep AllyPry as wrote, add reviewer per maintainer preference

---

Phase 6: Fix the Overview Link Bug in Current PR

The current PR has a sidebar bug:

{ text: 'Overview', link: 'physical-security/overview' },  // MISSING leading slash

All other entries have /physical-security/.... Fix this to /physical-security/overview.

---

Phase 7: Add Cross-References

After restructuring, add cross-reference links:

From OpSec to Physical Security:

• opsec/overview.mdx: Add "Related Frameworks" section linking to Physical Security
• opsec/travel/guide.mdx: Replace coercion-specific content with links to /physical-security/coercion-and-duress/...
• opsec/control-domains/overview.mdx: Update Physical & Environmental Controls section to reference the new framework

From Physical Security to OpSec:

• physical-security/coercion-and-duress/personal-and-family-opsec.mdx: Link to OpSec for the digital-hygiene side (the page title says "OpSec" and overlaps with OpSec's domain)

From Wallet Security to Physical Security:

• If a wallet-security framework exists, add: "For duress-resistant wallet designs, see Physical Security > Coercion & Duress > Wallet and Key Architecture"

---

Phase 8: Rename "Personal and Family OpSec" Page

The page personal-and-family-opsec.mdx lives in Physical Security but is named after OpSec. Within the Coercion & Duress sub-category, it covers reducing attack surface through digital hygiene, identity separation, and family training -- topics that bridge OpSec and Physical Security.

Options:

• A) Rename to personal-and-family-safety.mdx -- reflects the physical security framing
• B) Keep the name and add a prominent cross-reference to OpSec at the top
• Recommendation: Option A, since the content is about physical safety and coercion reduction, not information compartmentalization per se.

---

Phase 9: Update the PR Description

The PR description currently says:

"Placement as top-level category (not under Operational Security)"

Update to reflect the new structure:

• Physical Security as top-level domain
• Current content restructured as Coercion & Duress sub-category
• Stubs for 3 additional sub-categories
• De-overlapping from OpSec travel and control-domains

---

Implementation Order

1. Phase 6 -- fix the sidebar link bug (quick, no content deps)
2. Phase 1 -- restructure directory layout (moves + new stubs)
3. Phase 5 -- update frontmatter and import paths on moved files
4. Phase 2 -- rewrite the top-level overview
5. Phase 4 -- update vocs.config.tsx sidebar
6. Phase 3 -- de-overlap OpSec content (requires care to not break existing pages)
7. Phase 7 -- add cross-references
8. Phase 8 -- rename the OpSec-named page
9. Phase 9 -- update PR description

Phases 1-5 should be done in this PR. Phases 3, 7, 8 can be follow-up PRs to avoid scope creep and allow maintainer review of the OpSec changes separately.

[mattaereal]

@AllyPry are you still willing to take on this? I don't see conversation resolution nor the re-structuring we should do to be able to integrate it properly. Let me know if you need help

[AllyPry]

Sorry I was on other tasks and totally forgot about it. I'll get back to it this week.

[github-actions]

Sidebar Configuration Reminder

Documentation files update:

New in this push:

• docs/pages/physical-security/coercion-and-duress/checklist.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/defensive-design-principles.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/incident-response.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/overview.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/personal-and-family-safety.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/recovery-and-resilience.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/risk-factors-and-early-signals.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/threat-model.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/transaction-flows-under-duress.mdx (added) ← NEW
• docs/pages/physical-security/coercion-and-duress/wallet-and-key-architecture.mdx (added) ← NEW
• docs/pages/physical-security/facility-and-perimeter/overview.mdx (added) ← NEW
• docs/pages/physical-security/physical-counter-surveillance/overview.mdx (added) ← NEW
• docs/pages/physical-security/supply-chain-physical-integrity/overview.mdx (added) ← NEW

Previously seen:

• docs/pages/physical-security/overview.mdx (added)

Please ensure that:

• The sidebar in vocs.config.tsx has been updated to include these files
• New content has the dev: true parameter so it's marked as under development
• Sidebar links match the file paths - use the preview deployment to verify

See Contributing Guide – Sidebar & Navigation for more details.

---

_{This is an automated reminder. If this PR doesn't need sidebar changes, you can ignore this message.}

[github-actions]

Sidebar Configuration Reminder

Documentation files update:

New in this push:

• docs/pages/devsecops/isolation/developer-machine-sandboxing.mdx (added) ← NEW
• docs/pages/multisig-for-protocols/key-takeaways.mdx (added) ← NEW
• docs/pages/opsec/passwords/managers.mdx (added) ← NEW
• docs/pages/opsec/passwords/rootaccounts.mdx (added) ← NEW

Please ensure that:

• The sidebar in vocs.config.tsx has been updated to include these files
• New content has the dev: true parameter so it's marked as under development
• Sidebar links match the file paths - use the preview deployment to verify

See Contributing Guide – Sidebar & Navigation for more details.

---

_{This is an automated reminder. If this PR doesn't need sidebar changes, you can ignore this message.}

[AllyPry]

Thanks for the feedback guys, I've pushed an update:

• Restructured into a proper domain (per @mattaereal): the wrench-attack content now lives
  under a Coercion & Duress sub-section, with a domain-level overview and stub sub-sections
  for Facility & Perimeter, Physical Counter-Surveillance, and Supply Chain Physical Integrity.
• Decoy guidance reworked (per @ElliotFriedman): replaced the decoy / "plausibility" approach
  with controlled surrender (time-locks, multi-party approval) and duress tripwires.
• QA fixes: contributor typo, missing trailing newlines, and the Overview sidebar link.

Ready for another look

[mattaereal]

I'm taking a good look at this. So far so good! Please reply me in discord ^^