@dp-pcs/ogp 0.9.0 → 0.10.0

package/dist/shared/relay-protocol.d.ts

@@ -0,0 +1,91 @@
+/** The opaque, end-to-end-signed unit the relay forwards verbatim. Identical to
+ *  the JSON body posted to POST /federation/message in direct mode. */
+export interface RelayFrame {
+    message: unknown;
+    messageStr: string;
+    signature: string;
+}
+/** Whether a daemon's socket is a persistent receiver (registered in the relay
+ *  routing table) or a transient sender (opened only to await a response leg). */
+export type RelayRole = 'receiver' | 'sender';
+/** Error codes the relay may return in an `error` frame. */
+export type RelayErrorCode = 'peer-not-connected' | 'unauthorized' | 'bad-frame' | 'payload-too-large' | 'challenge-expired';
+/** Max accepted frame size. Envelopes are small; this caps abuse. */
+export declare const MAX_FRAME_BYTES: number;
+/** App-level heartbeat period (must stay < ALB 60s idle timeout). */
+export declare const HEARTBEAT_MS = 35000;
+/** How long a server-issued auth challenge stays valid. */
+export declare const CHALLENGE_TTL_MS = 10000;
+/** (1) S→C, on socket open. */
+export interface ChallengeFrame {
+    type: 'challenge';
+    challengeId: string;
+    nonce: string;
+    serverTime: string;
+}
+/** (2) C→S. payloadStr/signature = signCanonical({pubkey, challengeId, nonce, role}). */
+export interface AuthFrame {
+    type: 'auth';
+    pubkey: string;
+    challengeId: string;
+    payloadStr: string;
+    signature: string;
+}
+/** (3) S→C success. */
+export interface AuthOkFrame {
+    type: 'auth-ok';
+    pubkey: string;
+}
+/** (3) S→C failure (socket closes after). */
+export interface AuthErrFrame {
+    type: 'auth-err';
+    reason: string;
+}
+/** (4) C→S deliver request / (5) S→C forwarded deliver.
+ *  `to` is set by the sender; `from` is added by the relay for logging only
+ *  (never trusted — the signed `frame` is the trust unit). */
+export interface DeliverFrame {
+    type: 'deliver';
+    reqId: string;
+    to?: string;
+    from?: string;
+    frame: RelayFrame;
+}
+/** (6) C→S / (7) S→C response leg. `result` is the recipient's MessageResponse. */
+export interface ResponseFrame {
+    type: 'response';
+    reqId: string;
+    result: unknown;
+}
+/** (8) S→C error. */
+export interface ErrorFrame {
+    type: 'error';
+    reqId?: string;
+    code: RelayErrorCode;
+    message: string;
+}
+/** (9) app-level keepalive, either direction. */
+export interface PingFrame {
+    type: 'ping';
+}
+export interface PongFrame {
+    type: 'pong';
+}
+export type RelayClientFrame = AuthFrame | DeliverFrame | ResponseFrame | PingFrame | PongFrame;
+export type RelayServerFrame = ChallengeFrame | AuthOkFrame | AuthErrFrame | DeliverFrame | ResponseFrame | ErrorFrame | PingFrame | PongFrame;
+export type RelayAnyFrame = RelayClientFrame | RelayServerFrame;
+/** Parse a raw WS text frame into a typed object, or null if not a `{type}` object. */
+export declare function parseFrame(raw: string): RelayAnyFrame | null;
+export declare function isChallengeFrame(f: RelayAnyFrame): f is ChallengeFrame;
+export declare function isAuthFrame(f: RelayAnyFrame): f is AuthFrame;
+export declare function isDeliverFrame(f: RelayAnyFrame): f is DeliverFrame;
+export declare function isResponseFrame(f: RelayAnyFrame): f is ResponseFrame;
+/** The canonical payload a daemon signs to answer an auth challenge. The nonce
+ *  is INSIDE the signed bytes so the signature covers it (replay resistance). */
+export interface AuthChallengePayload {
+    pubkey: string;
+    challengeId: string;
+    nonce: string;
+    role: RelayRole;
+}
+//# sourceMappingURL=relay-protocol.d.ts.map

package/dist/shared/relay-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-protocol.d.ts","sourceRoot":"","sources":["../../src/shared/relay-protocol.ts"],"names":[],"mappings":"AAUA;uEACuE;AACvE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;kFACkF;AAClF,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,cAAc,GACd,WAAW,GACX,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,qEAAqE;AACrE,eAAO,MAAM,eAAe,QAAa,CAAC;AAE1C,qEAAqE;AACrE,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAIvC,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uBAAuB;AACvB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;8DAE8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAqB;AACrB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IAAG,IAAI,EAAE,MAAM,CAAC;CAAE;AAC5C,MAAM,WAAW,SAAS;IAAG,IAAI,EAAE,MAAM,CAAC;CAAE;AAE5C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAChG,MAAM,MAAM,gBAAgB,GACxB,cAAc,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AACpH,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAIhE,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAW5D;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,IAAI,cAAc,CAItE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,IAAI,SAAS,CAO5D;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,IAAI,YAAY,CAOlE;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,IAAI,aAAa,CAEpE;AAED;iFACiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;CACjB"}

package/dist/shared/relay-protocol.js

@@ -0,0 +1,55 @@
+// Relay transport wire protocol (bd-b7em Phase 2).
+//
+// Frames are JSON text over a WebSocket between a daemon and the relay server.
+// The relay is UNTRUSTED: it routes opaque `frame` payloads (the exact body a
+// daemon would POST to /federation/message) by recipient pubkey and never
+// inspects or forges them. End-to-end Ed25519 lives entirely inside `frame`.
+//
+// Auth proves pubkey ownership via a server-issued challenge nonce signed with
+// signCanonical (src/shared/signing.ts). See docs/TRANSPORT-MODES-DESIGN.md.
+/** Max accepted frame size. Envelopes are small; this caps abuse. */
+export const MAX_FRAME_BYTES = 256 * 1024;
+/** App-level heartbeat period (must stay < ALB 60s idle timeout). */
+export const HEARTBEAT_MS = 35_000;
+/** How long a server-issued auth challenge stays valid. */
+export const CHALLENGE_TTL_MS = 10_000;
+// ── Parsing / guards ─────────────────────────────────────────────────────────
+/** Parse a raw WS text frame into a typed object, or null if not a `{type}` object. */
+export function parseFrame(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object' || typeof obj.type !== 'string') {
+        return null;
+    }
+    return obj;
+}
+export function isChallengeFrame(f) {
+    return f.type === 'challenge'
+        && typeof f.challengeId === 'string'
+        && typeof f.nonce === 'string';
+}
+export function isAuthFrame(f) {
+    const a = f;
+    return f.type === 'auth'
+        && typeof a.pubkey === 'string'
+        && typeof a.challengeId === 'string'
+        && typeof a.payloadStr === 'string'
+        && typeof a.signature === 'string';
+}
+export function isDeliverFrame(f) {
+    const d = f;
+    return f.type === 'deliver'
+        && typeof d.reqId === 'string'
+        && !!d.frame && typeof d.frame === 'object'
+        && typeof d.frame.messageStr === 'string'
+        && typeof d.frame.signature === 'string';
+}
+export function isResponseFrame(f) {
+    return f.type === 'response' && typeof f.reqId === 'string';
+}
+//# sourceMappingURL=relay-protocol.js.map

package/dist/shared/relay-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-protocol.js","sourceRoot":"","sources":["../../src/shared/relay-protocol.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAsB7E,qEAAqE;AACrE,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,GAAG,IAAI,CAAC;AAE1C,qEAAqE;AACrE,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAoEvC,gFAAgF;AAEhF,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAQ,GAA0B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAoB,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAgB;IAC/C,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW;WACxB,OAAQ,CAAoB,CAAC,WAAW,KAAK,QAAQ;WACrD,OAAQ,CAAoB,CAAC,KAAK,KAAK,QAAQ,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAgB;IAC1C,MAAM,CAAC,GAAG,CAAc,CAAC;IACzB,OAAO,CAAC,CAAC,IAAI,KAAK,MAAM;WACnB,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;WAC5B,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;WACjC,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;WAChC,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAgB;IAC7C,MAAM,CAAC,GAAG,CAAiB,CAAC;IAC5B,OAAO,CAAC,CAAC,IAAI,KAAK,SAAS;WACtB,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;WAC3B,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;WACxC,OAAO,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,QAAQ;WACtC,OAAO,CAAC,CAAC,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAgB;IAC9C,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,OAAQ,CAAmB,CAAC,KAAK,KAAK,QAAQ,CAAC;AACjF,CAAC"}

package/docs/CLI-REFERENCE.md

@@ -5,6 +5,7 @@ Complete command-line reference for OGP (Open Gateway Protocol).
 ## Table of Contents
 
 - [Global Options](#global-options)
+- [Environment Variables](#environment-variables)
 - [Setup and Configuration](#setup-and-configuration)
 - [Daemon Management](#daemon-management)
 - [Federation Commands](#federation-commands)
@@ -49,6 +50,10 @@ ogp --for all status
 - If multiple frameworks are configured and no default is set, prompts interactively
 - If a default framework is set, uses default (can override with `--for`)
 - `--for all` runs command on all enabled frameworks and aggregates output
+- If the meta-registry is empty (no `ogp setup` was run) but `OGP_HOME` is set,
+  `--for <framework>` honors `OGP_HOME` and prints a warning instead of failing.
+  This is the common case in server/container deployments where the daemon is
+  launched by setting `OGP_HOME` directly. See [Environment Variables](#environment-variables).
 
 ### --help, -h
 
@@ -70,6 +75,39 @@ Shows OGP version.
 ogp --version
 ```
 
+## Environment Variables
+
+OGP does **not** hardcode its storage location. The default is `~/.ogp`, but
+every path is resolved at runtime and can be overridden via environment
+variables. This is the supported way to run OGP in containers, on servers
+(ECS/nginx), or anywhere `$HOME` is not where you want config to live — no code
+changes or recompilation required.
+
+| Variable | Overrides | Default |
+| --- | --- | --- |
+| `OGP_HOME` | Per-framework data dir: `config.json`, `peers.json`, identity, keychain. **The daemon only needs this.** | `~/.ogp` |
+| `OGP_META_HOME` | The multi-framework meta-registry (`config.json` listing frameworks for `--for`). | `~/.ogp-meta` |
+
+**Server / container deployment (recommended):**
+```bash
+# Point both the daemon and the CLI at the same writable location.
+export OGP_HOME=/data/ogp        # or e.g. /home/node/.openclaw/.ogp
+ogp start --background
+ogp peers list                   # CLI inherits OGP_HOME, talks to the daemon
+```
+
+**Common pitfall:** If the daemon is launched with `OGP_HOME` set but you then
+run `ogp --for openclaw ...`, the CLI looks up `openclaw` in the meta-registry
+(`OGP_META_HOME`), which was never populated by an interactive `ogp setup`.
+As of this version, `--for` falls back to `OGP_HOME` with a warning instead of
+erroring. The clean fix is to **not pass `--for` on a single-home server** — just
+export `OGP_HOME` and let every `ogp` invocation inherit it.
+
+**$HOME mismatch:** If the daemon and CLI run under different users/`$HOME`
+values (common in containers), the meta-registry can silently "not exist" for
+one of them. Set `OGP_META_HOME` (and `OGP_HOME`) explicitly so both processes
+resolve the same paths.
+
 ## Setup and Configuration
 
 ### ogp setup

package/docs/TRANSPORT-MODES-DESIGN.md

@@ -0,0 +1,164 @@
+# Transport Modes Design
+
+**Status:** 🚧 Proposed — under review. The rendezvous registration schema change is adjacent to the Ed25519 trust model and should be reviewed carefully before merge.
+
+**Date:** 2026-06-08
+
+## Problem
+
+OGP's biggest adoption deterrent is the tunnel requirement. Today peers deliver
+Ed25519-signed envelopes by **direct HTTP POST to each other's public
+`gatewayUrl`**, and the rendezvous server is a pubkey→address directory that
+hands back a raw `ip:port`. Even *with* rendezvous, a peer must be publicly
+reachable — which is exactly the job the cloudflared/ngrok tunnel does.
+
+The tunnel is **not a transport requirement — it's a reachability hack.** We want
+to make reachability a *user choice*, so people who don't want to run a tunnel can
+opt into a relay instead, without forcing anyone already on tunnels to change.
+
+## Key insight that makes this safe
+
+**OGP messages are already Ed25519-signed end-to-end.** Any relay/transport in the
+middle is *untrusted by design* — it can see envelope metadata but cannot forge,
+alter, or impersonate. This radically lowers the security bar for the transport
+layer and makes "route through a relay" perfectly acceptable. This single fact is
+what makes a pluggable transport possible without weakening the trust model.
+
+## Goal
+
+A per-user, per-daemon `transport` setting that lets each operator choose how their
+daemon is reached, defaulting to **today's behavior** so no existing setup breaks:
+
+- **`direct`** (default) — public `gatewayUrl` via tunnel / public IP / port-forward. Exactly what works today. Zero change for current users.
+- **`relay`** — daemon holds a persistent outbound WebSocket to a relay; messages route peer→relay→peer. No inbound port, no tunnel. User picks *which* relay (ours by default, or a self-hosted one).
+- **`iroh`** — daemon uses Iroh (QUIC). ~90% of pairs get a direct P2P connection; the rest fall back through a relay. E2E-encrypted regardless. Self-hostable relay. The deliberate pilot.
+
+## User experience
+
+```bash
+# Default — nothing changes for existing users
+ogp config get transport.mode          # => direct
+
+# Opt into relay (no tunnel needed)
+ogp config set transport.mode relay
+ogp config set transport.relay.url wss://relay.example.com/relay   # default if omitted
+
+# Power user / privacy: self-hosted relay
+ogp config set transport.relay.url wss://relay.mycorp.internal
+
+# Pilot iroh
+ogp config set transport.mode iroh
+ogp config set transport.iroh.relayUrl https://my-dedicated-relay   # omit = public dev relays
+```
+
+A mixed fleet works: each peer advertises *how* to reach it, and senders branch on
+the **receiver's** advertised transport (see schema change below).
+
+## Config shape
+
+Add a `transport` block to `OGPConfig` (`src/shared/config.ts`). Absent ⇒ `direct`.
+
+```ts
+export type TransportMode = 'direct' | 'relay' | 'iroh';
+
+export interface TransportConfig {
+  mode: TransportMode;            // default 'direct'
+  relay?: {
+    url: string;                  // websocket relay endpoint; default wss://<rendezvous>/relay
+  };
+  iroh?: {
+    relayUrl?: string;            // dedicated/self-hosted iroh relay; omit = public dev relays
+  };
+}
+
+// OGPConfig:
+//   transport?: TransportConfig;
+```
+
+## The keystone change — rendezvous advertises *how*, not just *where*
+
+This is the one structural change everything else depends on, and the part that
+**must be reviewed carefully before merge** (it sits next to the signed
+registration / trust model).
+
+Today the rendezvous `/register` stores `{ pubkey, ip, port, lastSeen }` and
+`/peer/:pubkey` returns `{ pubkey, ip, port, lastSeen }`. We extend the registered
+record with a **transport descriptor** so a sender knows which path to use:
+
+```jsonc
+// direct (default / backward compatible — missing descriptor ⇒ direct)
+{ "transport": "direct", "gatewayUrl": "https://peer.example.com" }
+
+// relay
+{ "transport": "relay", "relayUrl": "wss://relay.example.com/relay" }
+
+// iroh
+{ "transport": "iroh", "nodeId": "<iroh-node-id>", "relayUrl": "https://..." }
+```
+
+Rules:
+- **Additive & backward compatible.** A registration with no descriptor is treated
+  as `direct` with the existing `ip:port` / `gatewayUrl`. Old daemons keep working.
+- The descriptor rides **inside the existing signed registration envelope**
+  (`signCanonical` over the inner payload) so the rendezvous can't be tricked into
+  advertising a transport the keyholder didn't choose. **This is the trust-model
+  touchpoint — review carefully before merge.**
+- Senders branch delivery on the peer's advertised `transport`, not their own.
+
+## Relay server (mode = `relay`)
+
+Extends the existing rendezvous service (Node/Express on ECS Fargate). No new box.
+
+- New `wss://<rendezvous>/relay` endpoint. Each daemon opens a **persistent
+  outbound** WebSocket and authenticates by signing a challenge with its Ed25519
+  key (proving pubkey ownership, same property as `/register`).
+- Routing table: `pubkey → live socket`. To deliver, sender pushes
+  `{ to: pubkeyB, envelope }`; server forwards down B's socket. Optional
+  store-and-forward queue for offline peers, flushed on reconnect.
+- **ECS/ALB gotcha (confirmed):** ALB idle timeout defaults to 60s, max 4000s. We
+  **must** send app-level WS ping/heartbeat (~30–50s) or idle sockets get dropped.
+- **Horizontal scale:** one Node process handles tens of thousands of idle
+  sockets; past one Fargate task we need a shared routing table (Redis pub/sub) so
+  a message arriving on task-1 reaches a socket on task-2.
+- Server stays **untrusted** — it sees envelopes but can't forge them (E2E Ed25519).
+
+## Iroh (mode = `iroh`) — pilot notes
+
+- QUIC, node-ID addressing. Relays do (1) NAT-traversal coordination and (2)
+  encrypted fallback; **relays cannot read traffic** (E2E). ~9/10 pairs get a
+  direct connection; traversal is deterministic once it works for a pair.
+- Relays are **stateless/disposable** (no DB, no state migration, reconnect to any).
+- **Cost/effort caveats:** Iroh is Rust; OGP is Node. Official **NAPI Node bindings**
+  exist (`iroh` npm), so it's a native-addon dependency with per-platform prebuilds,
+  not a full rewrite — but it *is* a new native dep for a daemon that ships daily.
+  Public relays are **dev/test only** (rate-limited, no SLA); production = dedicated
+  relays (self-hosted open-source binary from n0-computer, or n0's paid Iroh
+  Services). Addressing changes from URL → node ID, so the delivery path is rewired.
+- Treat as **opt-in pilot**, not default. Once the transport descriptor exists,
+  iroh is "just another transport value," not a rewrite-or-nothing bet.
+
+Sources: https://docs.iroh.computer/concepts/relays ,
+https://docs.aws.amazon.com/elasticloadbalancing/latest/application/edit-load-balancer-attributes.html
+
+## Phased build plan
+
+1. **Transport descriptor in register/lookup** (additive, backward compatible;
+   missing ⇒ `direct`). Unblocks everything, low risk. **Schema/trust touchpoint —
+   review carefully before merge.**
+2. **`relay` mode** — WebSocket through rendezvous + signed-challenge auth +
+   ALB heartbeat. Lowest code; kills the tunnel requirement; opt-in dogfooding.
+3. **`iroh` mode pilot** — once relay is proven, add iroh as another descriptor
+   value behind a dedicated/self-hosted relay.
+
+## Hard rules / guardrails
+
+- **Default stays `direct`** — never silently change how existing users' traffic moves.
+- **No auto-deploy** of the rendezvous/relay server — changes are proposed and reviewed, not shipped automatically.
+- **Registration-schema + relay-auth code requires careful review before merge** — it's adjacent to the Ed25519 trust model, which is the product.
+- E2E Ed25519 signing is preserved in **every** mode; the relay is always untrusted.
+
+## Non-goals (for now)
+
+- Replacing direct mode. It stays as the privacy/no-third-party path.
+- Picking iroh vs websocket-relay as the *single* answer. The point is choice +
+  real-world dogfooding before committing a default beyond `direct`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-pcs/ogp",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Open Gateway Protocol (OGP) - Peer-to-peer federation daemon for OpenClaw AI gateways with cryptographic signatures",
   "type": "module",
   "main": "./dist/index.js",