pd-relay-zero-trust

license	Apache-2.0
name	pd-relay-zero-trust
description	Architects Port Daddy's outbound-only event relay and the zero-trust crypto stack that governs it — PKI choice (ACME vs OIDC vs Web-of-Trust), per-publisher Merkle event chains, harbor cards on the wire, Phase 3 capability attenuation, E2E payload encryption, ProVerif extension, and the V4 remote-harbor redefinition. Use when designing the relay, writing the PKI/relay/V4 ADRs, deciding PKI strategy with proponent/pragmatic/antagonist deliberation, scaffolding ACME or OIDC, building Merkle chain primitives, or extending the symbolic protocol model. NOT for implementing the local daemon, generic harbor-card refactors, Float Plan economic settlement (deferred), or generic zero-trust theory (use agentic-zero-trust-security).
allowed-tools	Read,Write,Edit,Bash,Grep,Glob
metadata	{"category":"Security & Architecture","argument-hint":"[task: pki-decide|design-relay|build-merkle|attenuate|encrypt|extend-proverif|redefine-v4|threat-review]","tags":["zero-trust","relay","pki","merkle","harbor-cards","macaroons","proverif","port-daddy"],"pairs-with":["agentic-zero-trust-security","proverif-tamarin-protocol-modeling","skill-architect"],"subagents":["acme-specialist","proponent","pragmatic","antagonist"]}

pd-relay-zero-trust

Authoritative skill for designing and shipping the Port Daddy event relay under a zero-trust threat model. The relay is the cloud-side fabric that lets local daemons, CI runners, and apps publish/subscribe across machines without inbound holes, without trusted intermediaries reading payloads, and with cryptographic non-equivocation of every event stream.

This skill is deliberation-aware: most decisions fork into a four-voice debate (ACME specialist for PKI fluency, proponent / pragmatic / antagonist for design pressure-testing) before producing an ADR.

---

When to Use

✅ Use for:

• Choosing PKI for the relay (ACME vs OIDC vs Web-of-Trust vs hybrid)
• Designing the daemon → relay handshake and outbound SSE transport
• Specifying per-publisher Merkle event chains (apply ADR-0014 primitive)
• Writing Phase 3 Macaroon-style attenuation for delegated publishers (GH Actions, Slack)
• E2E payload encryption between publisher and subscriber (relay sees only metadata)
• Extending ProVerif models to cover daemon ↔ relay ↔ daemon
• Killing Part XVII scope creep — redefining "remote harbor" as shared keypair + relay namespace
• Drafting the threat model and adversary catalog for the relay
• Generating ADRs for any of the above decisions

❌ NOT for:

• Local-only daemon work (use port-daddy and daemon-development skills)
• Generic zero-trust theory unrelated to PD (use agentic-zero-trust-security)
• Float Plan economic settlement — deferred until after the relay ships
• Frontend or dashboard work
• Generic harbor-card refactors that don't involve the wire

---

Sequencing (Hard Order)

The decisions below have dependencies. Do not skip ahead.

flowchart TD
  A[1. PKI Decision ADR] --> B[2. Threat Model Review]
  B --> C[3. Merkle-over-Events Spec]
  C --> D[4. Relay v0 ADR + OpenAPI]
  D --> E[5. Phase 3 Attenuation]
  E --> F[6. ProVerif Extension]
  F --> G[7. V4 Remote-Harbor Redefinition]
  G --> H[8. Float Plans Composition Sketch — defer build]

Why this order: PKI choice constrains the handshake. Threat model determines what the Merkle chain must commit to. Merkle primitives are pure functions and can land before the relay. Relay v0 needs PKI + Merkle. Attenuation refines the auth model already in v0. ProVerif cannot model what isn't specified. V4 redefinition only makes sense once the actual relay shape is committed. Float Plans compose over the relay; do not couple them to it.

---

Task Branches

Pass argument-hint to enter a specific branch. Each branch loads only the references it needs.

pki-decide

Drives the deliberation between ACME, OIDC, Web-of-Trust, and hybrids. Outputs ADR-0025.

Deliberate:
├─ Load references/pki-options-acme.md, pki-options-oidc.md, pki-options-web-of-trust.md
├─ Score with scripts/pki_decision.py against criteria in references/pki-decision-matrix.md
├─ Fork: dispatch agents/proponent.md (argues for proposed choice)
├─ Fork: dispatch agents/pragmatic.md (argues for fastest shippable + reversible)
├─ Fork: dispatch agents/antagonist.md (red-teams every option)
├─ Consult agents/acme-specialist.md for ACME-specific detail when ACME is in contention
└─ Synthesize: write templates/ADR-PKI-Decision.md filled in

design-relay

Produces the Relay v0 ADR + OpenAPI surface.

Build:
├─ Load references/relay-architecture.md, threat-model.md
├─ Confirm PKI ADR (0025) is accepted, else block
├─ Generate openapi.yaml (or update if exists)
├─ Validate handshake with scripts/verify_relay_handshake.py against schemas/relay-handshake.schema.json
└─ Output: templates/ADR-Relay-Architecture.md filled in

build-merkle

Implements per-publisher Merkle event chains (ADR-0014 primitive in its natural home).

Implement:
├─ Load references/merkle-chain-design.md
├─ Schema: schemas/event-envelope.schema.json, schemas/merkle-chain-head.schema.json
├─ Use scripts/chain_verify.py and scripts/chain_anchor.py
├─ Wire into lib/ (defer — PR after spec is accepted)
└─ Walk examples/chain-verification.md

attenuate

Phase 3 Macaroons-style capability attenuation for delegated publishers.

Specify:
├─ Load references/harbor-card-attenuation.md
├─ Schema: schemas/attenuated-card.schema.json
├─ Use scripts/attenuate_card.py to generate sample chains
└─ Walk examples/attenuation-walkthrough.md

encrypt

End-to-end payload encryption envelope so the relay sees only metadata.

Specify:
├─ Load references/e2e-payload-encryption.md
├─ Use scripts/e2e_encrypt.py for round-trip tests
└─ Reuse note-encryption envelope; do not invent new crypto

extend-proverif

Symbolic-model extension covering daemon ↔ relay ↔ daemon.

Model:
├─ Load references/proverif-relay-extension.md
├─ Pair with skill proverif-tamarin-protocol-modeling
├─ Extend templates/proverif-relay.pv
└─ Walk examples/proverif-extension-example.md

redefine-v4

Kill Part XVII scope creep; redefine remote harbor as shared keypair + relay namespace.

Reframe:
├─ Load references/v4-remote-harbor-redefinition.md
├─ Diff current V4-DAG.md and v4.dag.yaml
└─ Output: templates/ADR-V4-Remote-Harbor-Redefinition.md filled in

threat-review

Walks the adversary catalog and enumerates assumptions.

Review:
├─ Load references/threat-model.md
├─ Run scripts/threat_review.py to checklist findings
└─ Update threat model for any new surface introduced by the proposed change

---

Subagents (Deliberation Set)

The relay is high-stakes; one voice is not enough. Four subagents live in agents/:

Subagent	Role	Dispatch When
acme-specialist	ACME / Let's Encrypt / draft-ietf-acme expertise. Knows DV/OV/EV, ARI, ACME-DNS, CAA.	PKI option includes ACME
proponent	Argues for the proposed design, marshals strongest evidence	Always, after a candidate is named
pragmatic	Argues for fastest shippable path with clean reversibility	Always
antagonist	Red-teams: assumes bad-faith relay, hostile network, key compromise	Always

Synthesis is the human's responsibility (or the calling agent's), not a subagent's. Each subagent returns a structured opinion (see agents/*.md for output contracts). The synthesis becomes the body of the ADR.

---

Threat Model Snapshot (Full Catalog in references/threat-model.md)

In-scope adversaries:

• A1: Honest-but-curious relay operator (observes metadata, may store)
• A2: Malicious relay operator (rewrites, equivocates, drops)
• A3: Network-on-path (passive + active)
• A4: Compromised publisher (forges events under stolen card)
• A5: Compromised subscriber (replays, exfiltrates)
• A6: Compromised daemon (issues bad cards)

Out-of-scope:

• Side-channel timing attacks against AES-256-GCM
• Quantum attacks on Ed25519 (separate roadmap item)
• Physical key extraction from ~/.port-daddy/master.key
• Long-tail compromise of the publishing OS

Invariants we preserve:

• I1: Relay never sees payload plaintext
• I2: Subscribers detect equivocation by the relay (per-publisher Merkle)
• I3: Stolen card is bounded by exp, cap, aud and revocable
• I4: Capability attenuation never expands rights (only contracts)
• I5: Loss of relay does not lose past evidence (chain heads are anchored)

---

Anti-Patterns

Conflating Auth with Encryption

Novice: "Harbor cards authorize the publisher; therefore the relay can read payloads." Expert: Auth and confidentiality are orthogonal. Card = "you can publish to this channel." E2E envelope = "only the channel's subscribers can read." The relay enforces auth and routes ciphertext. Detection: Code paths that decrypt at the relay; APIs that take plaintext as required.

Re-implementing the Sync Protocol (Part XVII Trap)

Novice: "Remote harbors need bidirectional state replication between daemons." Expert: The user-facing win of remote harbors is "my fleet sees my CI's events." That's pub/sub federation, not state sync. Part XVII is 1,500 LOE we don't need. Timeline: V4-DAG.md (v3.x) over-spec'd this. ADR-0027 (this skill's output) deletes the scope creep.

Trusted Sequencer for Merkle Order

Novice: "The relay mints the next hash; everyone trusts the relay." Expert: Per-publisher chains. Each publisher signs their own chain head; subscribers verify against the publisher's key. The relay persists chains but is not the trust root. LLM mistake: LLMs reach for centralized sequencers because they're operationally simpler. Resist.

Float Plans on the Critical Path

Novice: "Wire economic settlement into the relay handshake; bill per event." Expert: SaaS billing ≠ Float Plans. Float Plans are agent-to-agent work contracts that compose over the relay later. Coupling them blocks the relay on a paper. Detection: Any ADR draft that mentions credits, escrow, or anchors in the handshake spec.

Premature Phase 3 Universalism

Novice: "Every card is attenuated by default." Expert: Phase 3 is for delegation across daemon boundaries (GH Action, Slack bot). Local agent ↔ daemon stays Phase 2. Don't pay attenuation cost where it has no benefit.

"Formally Verified Relay" Without ProVerif Extension

Novice: "Anchor Protocol is formally verified, so the relay is too." Expert: Existing ProVerif coverage is agent ↔ daemon. Adding the relay moves the trust boundary. Until extend-proverif ships, do not put "formally verified" within ten paragraphs of "relay" in marketing.

---

Quality Gates (Per Decision)

□ ADR template filled in (no [PLACEHOLDER] left)
□ Threat model lists which invariants the change preserves or weakens
□ All four subagents dispatched; their reports cited in ADR
□ OpenAPI surface matches schemas/ JSON schemas (run validate_skill.py)
□ Scripts under scripts/ run with --selftest and exit 0
□ At least one example walkthrough exists for the new primitive
□ References cite specific RFC / paper / ADR sections (not "see whitepaper")
□ NO mention of Float Plans on the critical path
□ NO mention of state-sync between daemons (Part XVII trap)
□ If touching crypto: ProVerif task added to backlog

---

Reference Files

File	Consult When
references/zero-trust-foundations.md	Need NIST SP 800-207 / BeyondCorp grounding for an argument
references/pki-options-acme.md	Evaluating ACME (Let's Encrypt, ACME-DNS, ARI, ZeroSSL)
references/pki-options-oidc.md	Evaluating OIDC (GitHub OIDC, Google, Auth0, custom IdP)
references/pki-options-web-of-trust.md	Evaluating cross-cert / WoT / SSH-style TOFU
references/pki-decision-matrix.md	Scoring PKI options against criteria; running pki_decision.py
references/merkle-chain-design.md	Specifying or implementing per-publisher Merkle chains
references/relay-architecture.md	Drafting the relay handshake, transport, namespacing
references/harbor-card-attenuation.md	Phase 3 Macaroon-style attenuation specification
references/e2e-payload-encryption.md	Specifying E2E envelope; reusing note-encryption design
references/proverif-relay-extension.md	Extending the symbolic model to cover the relay
references/float-plans-deferred.md	Composing Float Plans over the relay later — and what NOT to wire now
references/v4-remote-harbor-redefinition.md	Killing Part XVII scope creep; redefining remote harbors
references/threat-model.md	Adversary catalog, invariants, out-of-scope rationale

Schemas

File	Used By
schemas/script-io.schema.json	All scripts wrap their stdin/stdout against this envelope
schemas/harbor-card.schema.json	Phase 2 harbor card JWT payload
schemas/attenuated-card.schema.json	Phase 3 attenuated chain
schemas/event-envelope.schema.json	Wire format for events on the relay
schemas/merkle-chain-head.schema.json	Signed chain head
schemas/relay-handshake.schema.json	Daemon → relay opening exchange

Scripts

Script	Purpose
scripts/_envelope.py	Shared stdin/stdout envelope helpers imported by all other scripts
scripts/pki_decision.py	Score ACME/OIDC/WoT against weighted criteria
scripts/verify_relay_handshake.py	Verify a captured handshake against schema + sig
scripts/chain_verify.py	Walk a per-publisher chain; detect breaks/forks
scripts/chain_anchor.py	Sign + emit a chain head suitable for external anchoring
scripts/attenuate_card.py	Generate a Phase 3 attenuated card chain
scripts/e2e_encrypt.py	AES-256-GCM envelope wrap/unwrap; round-trip selftest
scripts/threat_review.py	Walk threat model checklist against a proposal
scripts/validate_skill.py	Skill self-check (frontmatter, references, schema validity)

Templates

Template	Output
templates/ADR-PKI-Decision.md	ADR-0025
templates/ADR-Relay-Architecture.md	ADR-0026
templates/ADR-V4-Remote-Harbor-Redefinition.md	ADR-0027
templates/relay-handshake-message.json	Reference handshake payload
templates/attenuated-card.json	Reference Phase 3 chain
templates/proverif-relay.pv	Skeleton ProVerif model

Examples

Example	Walks Through
examples/handshake-trace.md	Full daemon → relay handshake with crypto traces
examples/chain-verification.md	Detecting equivocation and forks in a Merkle chain
examples/attenuation-walkthrough.md	Macaroons-style chain for a GH Actions publisher
examples/proverif-extension-example.md	Extending an existing ProVerif file for the relay
examples/pd-tube-tutorial.md	Hands-on walkthrough of pd tube — publish/read over Port Daddy message channels (local daemon; designed to compose with the relay)

OpenAPI

openapi.yaml — relay surface (handshake, publish, subscribe, chain head, revocation broadcast, key discovery).

---

Subagent Output Contract (Common)

Each subagent returns:

verdict: accept | reject | accept-with-conditions
confidence: low | medium | high
top_three_reasons: [...]
top_three_risks: [...]
ship_blocker: true | false
ship_blocker_explanation: <if true>
suggested_amendments: [...]
references_cited: [...]

The synthesizer cross-tabulates verdicts. Any ship_blocker: true from antagonist requires explicit refutation in the ADR's Consequences section.

---

Bundled Assets

Subdirectory	Index
agents/	agents/INDEX.md — deliberation subagents
examples/	examples/INDEX.md — worked examples and tutorials
references/	references/INDEX.md — design references and option analyses
schemas/	schemas/INDEX.md — JSON schemas for all wire types
scripts/	scripts/INDEX.md — executable scripts with selftest
templates/	templates/INDEX.md — ADR templates and reference payloads