Add Physical Security framework

[AllyPry]

Summary

This PR adds a new Physical Security framework focused on protecting crypto holders (individuals and organizations) against wrench attacks.

Placement as top-level category (not under Operational Security) after discussion with @scode2277 and @mattaereal in Discord.

Structure

10 pages covering:

• Checklist
• Defensive Design Principles
• Incident Response
• Overview
• Personal and Family OPSEC
• Recovery and Resilience
• Risk Factors
• Threat Model
• Transaction Flows
• Wallet Architecture

[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	446ec62

[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.

[ElliotFriedman]

Personally I think decoys are a bad plan because under duress your ability to lie likely decreases. Instead, holders are probably much better off having a plan where they can give something up (a small amount relative to holdings) and have documentation showing the difficulty and process involved in moving larger amounts of funds.

These smaller amounts can have tripwires that function as duress buttons, which can alert loved ones and law enforcement.

[mattaereal]

I agree! Time locks are a demotivational factor, too

[AllyPry]

Agree