Skip to content

feat: one-way trust + require hardware-backed key storage - #5

Merged
YairEtzion merged 2 commits into
mainfrom
fix/hardware-only-docs
Mar 31, 2026
Merged

feat: one-way trust + require hardware-backed key storage#5
YairEtzion merged 2 commits into
mainfrom
fix/hardware-only-docs

Conversation

@YairEtzion

@YairEtzion YairEtzion commented Mar 31, 2026

Copy link
Copy Markdown
Contributor

Summary

One-way trust directionality (new)

  • Enforce asymmetric trust — after pairing, controllers can authenticate to targets but targets cannot authenticate back. Limits blast radius of a compromised server.
  • Role field added to AllowListDevice (controller | target), enforced in verification middleware (Step 3b)
  • Single-controller default — targets allow one controller by default. Configurable via amesh init --max-controllers N
  • amesh list now shows [controller] / [target] role tags
  • Legacy migration — existing allow lists without role field default to controller on first read
  • ADR-010 documents the design decision and trade-offs
  • All docs, landing page, sitemap updated to reflect one-way trust model

Hardware-only key storage

  • Dropped the encrypted-file backend — amesh now requires Secure Enclave, macOS Keychain, or TPM 2.0. No software-only fallback.
  • Removed all passphrase / AUTH_MESH_PASSPHRASE plumbing from CLI, SDK, detection chain, and all documentation.
  • Removed CI/CD and Kubernetes use case pages from the landing page — ephemeral compute without hardware is not supported.

Files changed (22 files, +357/-92 in latest commit)

Code

  • packages/keystore/src/allow-list.tsrole field, countByRole(), replaceByRole(), legacy migration
  • packages/sdk/src/middleware.ts — Step 3b directionality check (rejects role: "target")
  • packages/sdk/src/amesh.ts — Same directionality check in simple verify API
  • packages/cli/src/commands/listen.ts — Sets peer role to controller, enforces maxControllers limit with replace prompt
  • packages/cli/src/commands/invite.ts — Sets peer role to target
  • packages/cli/src/commands/init.ts--max-controllers flag
  • packages/cli/src/commands/list.ts — Shows [controller]/[target] tags
  • packages/cli/src/identity.tsmaxControllers optional field
  • packages/sdk/src/bootstrap.ts — Sets role to controller for bootstrap flow
  • packages/keystore/src/detect.ts — Hardware-only detection

Tests

  • packages/keystore/src/__tests__/allow-list.test.ts — 4 new tests (role storage, countByRole, replaceByRole, legacy migration)
  • packages/sdk/src/__tests__/middleware.test.ts — 1 new test (rejects target-role device)

Documentation

  • README.md — One-way trust in architecture diagram and "How It Works"
  • docs/protocol-spec.md — Step 3b, role field in allow list schema, security considerations
  • docs/architecture-decisions.md — ADR-010: One-way trust directionality
  • docs/guide.md — Role tags in amesh list, pairing section explains one-way trust
  • docs/integration-guide.md — Architecture diagrams, setup comments, microservices recipe
  • docs/self-hosting.md — Architecture diagram with controller/target labels
  • docs/why-amesh.md — Security model sentence

Landing page

  • landpage/src/routes/+page.svelte — CLI output, feature card, step descriptions
  • landpage/src/routes/docs/integration/+page.svelte — Architecture overview, setup comments
  • landpage/src/routes/use-cases/microservices/+page.svelte — Terminal tab
  • landpage/static/sitemap.xml — Updated lastmod dates

Test plan

  • bun run build passes (all packages + landing page)
  • bun run test passes (all existing + 5 new tests)
  • Middleware rejects requests from devices with role: "target" (401)
  • Legacy allow lists without role field migrate to controller on read
  • replaceByRole() correctly swaps controllers and preserves targets
  • Manual: pair two devices, verify amesh list shows correct roles
  • Visual review of landing page after deploy

🤖 Generated with Claude Code

Final sweep across protocol-spec, architecture-decisions, why-amesh,
sitemap, keystore package.json, and nonce.ts. Replaces Lambda examples
with generic server names, removes Tier 4 fallback from spec diagrams,
and updates all stale references.
…ets only

Enforce asymmetric trust: after pairing, controllers can authenticate
to targets but targets cannot authenticate back. Limits blast radius
of a compromised server. Default single-controller per target.

- Add `role` field to AllowListDevice (controller | target)
- Middleware rejects devices with role "target" (Step 3b)
- `amesh listen` sets peer role to controller, enforces maxControllers
- `amesh invite` sets peer role to target
- `amesh list` shows [controller]/[target] role tags
- `amesh init --max-controllers N` configures limit
- Legacy allow lists migrate role to "controller" on first read
- ADR-010 documents the design decision
- All docs, landpage, and sitemap updated
@YairEtzion YairEtzion changed the title docs: require hardware-backed key storage, remove encrypted-file references feat: one-way trust + require hardware-backed key storage Mar 31, 2026
@YairEtzion
YairEtzion merged commit 1c0ea6b into main Mar 31, 2026
1 check passed
@YairEtzion
YairEtzion deleted the fix/hardware-only-docs branch March 31, 2026 16:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant