@uxnan/shared 0.0.1-alpha.20260627

package/README.md

@@ -0,0 +1,96 @@
+# @uxnan/shared
+
+![TypeScript](https://img.shields.io/badge/TypeScript-ESM-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
+![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
+![JSON Schema](https://img.shields.io/badge/validation-Ajv-000000?style=for-the-badge&logo=json&logoColor=white)
+![Contracts](https://img.shields.io/badge/60_methods_%7C_8_notifications-blue?style=for-the-badge)
+
+Shared JSON-RPC and E2EE contracts for the [Uxnan](../README.md) ecosystem — the
+single source of truth every component agrees on. Consumed as a local workspace
+dependency by the **[bridge](../bridge/README.md)** and the
+**[relay](../relay/README.md)**; the mobile app keeps manually-synced Dart
+equivalents (see
+[`architecture/02b-contracts-and-requirements.md`](../architecture/02b-contracts-and-requirements.md)
+§1 for the canonical contract list).
+
+> **Status:** implemented and stable — **60 JSON-RPC methods** + **8 streaming
+> notifications**, kept lock-step at build time with the `METHOD_NAMES` array and
+> the `StreamNotification` enum (a compile-time assertion in
+> `src/jsonrpc/method-registry.ts` fails the build on any drift). Changes are
+> recorded in [`CHANGELOG.md`](CHANGELOG.md).
+
+## Why it exists
+
+Three independent codebases — a Node.js bridge, a Node.js relay, and a Flutter app
+— have to agree on exactly the same messages on the wire. Rather than letting each
+one drift its own way, every shape lives here once: the request and response
+envelopes, the streaming notifications, the E2EE handshake, the pairing payload,
+and the domain and agent models. The bridge and relay import this package
+directly; the mobile app mirrors it in Dart. When a contract changes, it changes
+here first, and the build refuses to pass if the registry and the spec disagree.
+
+<details>
+<summary><b>Diagram — one contract, three consumers</b></summary>
+
+```mermaid
+flowchart TB
+  shared["@uxnan/shared<br/>JSON-RPC + E2EE contracts"]
+  bridge["uxnan-bridge<br/>(imports directly)"]
+  relay["uxnan-relay<br/>(imports directly)"]
+  mobile["uxnanmobile<br/>(hand-synced Dart mirror)"]
+  shared --> bridge
+  shared --> relay
+  shared -. mirrored .-> mobile
+```
+
+</details>
+
+## What's inside
+
+| Area | Exports |
+|---|---|
+| JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32008`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
+| Streaming | `StreamNotification` enum + param types (`TurnStartedParams`, `MessageDeltaParams`, `ThinkingDeltaParams`, `ContentBlockParams`, `TurnCompletedParams`, `TurnUsage`, `TurnErrorParams`, `TurnAbortedParams`, `ModelResolvedParams`) |
+| E2EE | handshake messages (`clientHello` / `serverHello` / `clientAuth` / `ready`), `buildHandshakeTranscript`, `SecureEnvelope`, `PairingPayload` v2 (`relay` optional + `hosts: string[]`) with `Base64(utf8(JSON))` QR encoding |
+| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust, approval |
+| Agents | `IAgentAdapter` (with `respondApproval`, `listModels`, `nativeSessionId`, `SendTurnOptions { threadId, turnId, text, service?, effort?, options?, attachments?, cwd?, accessMode? }`), `AgentModel` (incl. `version?`, `isDefault?`, `options?`, `contextWindow?`), `AgentCapabilities` (incl. `images`, `approvals`, `reportsContextUsage`), `AgentConfig` (cwd, agentId, model, plus optional `binaryPath`/`extraArgs`) |
+| Validation | Ajv validators for requests, responses, envelopes, pairing payload, push payloads |
+
+## Usage
+
+```ts
+import {
+  makeRequest,
+  isKnownMethod,
+  validateJsonRpcRequest,
+  METHOD_NAMES,
+  type AgentModel,
+  type PairingPayload,
+} from '@uxnan/shared';
+```
+
+## Develop
+
+```bash
+npm run build      # tsc → dist/
+npm test           # tsc + node --test dist/test
+npm run typecheck  # tsc --noEmit
+```
+
+Requires Node ≥18. The package is ESM-only.
+
+## Source of truth
+
+The canonical contract list lives in this package — see
+[`src/jsonrpc/method-registry.ts`](src/jsonrpc/method-registry.ts) (`METHOD_NAMES`)
+and [`src/jsonrpc/notifications.ts`](src/jsonrpc/notifications.ts)
+(`StreamNotification`). The spec mirrors it in
+[`architecture/02b-contracts-and-requirements.md`](../architecture/02b-contracts-and-requirements.md)
+§1.2 / §1.4. Per `AGENTS.md` → *Spec drift control*, any change here MUST be
+reflected in the spec in the same change set.
+
+## Publish (planned)
+
+`@uxnan/shared` is published to npm **first**; `uxnan-bridge` and `uxnan-relay`
+then pin `"@uxnan/shared": "^0.x"` instead of the `"*"` workspace spec they
+use today. See `bridge/FOR-DEV.md` → *Packaging*.

package/dist/src/agents/agent-adapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Contract every agent CLI adapter must implement.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (adapters/base-adapter).
+ */
+import type { AgentCapabilities, AgentId, AgentModel } from './agent-capabilities.js';
+import type { AgentConfig } from './agent-config.js';
+import type { TurnAttachment } from '../models/workspace.js';
+import type { ApprovalDecision } from '../models/approval.js';
+import type { AccessMode } from '../models/thread.js';
+/** A single streamed event produced by a running agent turn. */
+export interface AgentStreamEvent {
+    type: 'delta'
+    /** A chunk of the agent's reasoning / "thinking" (`data.text`). */
+     | 'thinking'
+    /** A structured content block — command/diff/tool (`data.content`). */
+     | 'block' | 'turn_started' | 'turn_completed' | 'turn_error' | 'turn_aborted'
+    /** The agent reported the concrete model it resolved an alias to (`data.text`). */
+     | 'model_resolved';
+    threadId: string;
+    turnId: string;
+    /** Free-form payload depending on `type`. */
+    data?: unknown;
+}
+export interface SendTurnOptions {
+    threadId: string;
+    turnId: string;
+    text: string;
+    /** Model/service identifier (e.g. `provider/model`) for adapters that accept one. */
+    service?: string;
+    /** Legacy flat reasoning effort / variant (e.g. `high`, `max`, `minimal`). */
+    effort?: string;
+    /**
+     * Chosen per-model run-option values keyed by `AgentModelOption.key` (e.g.
+     * `{ reasoning: 'high' }`). Adapters translate these into CLI flags; the
+     * legacy `effort` is used as a fallback for the `reasoning` knob.
+     */
+    options?: Record<string, string | boolean>;
+    /**
+     * Inline image attachments for this turn. The {@link AgentManager}
+     * materializes these to temp files and appends a reference to {@link text}
+     * before the adapter runs, so adapters need no per-CLI image handling.
+     */
+    attachments?: TurnAttachment[];
+    /** Working directory the agent should run in for this turn. */
+    cwd?: string;
+    /**
+     * The thread's persisted access (approval) mode (see {@link AccessMode}).
+     * Adapters that gate tool execution map it to their per-turn permission flag
+     * — `requestApproval` keeps interactive approvals in play, `approveForMe`
+     * auto-approves, `fullAccess` bypasses gating. Absent → the adapter's
+     * configured default posture (no behaviour change).
+     */
+    accessMode?: AccessMode;
+}
+export interface IAgentAdapter {
+    readonly agentId: AgentId;
+    readonly capabilities: AgentCapabilities;
+    /** Start (or attach to) the agent runtime for the given config. */
+    start(config: AgentConfig): Promise<void>;
+    /** Stop the agent runtime and release resources. */
+    stop(): Promise<void>;
+    /** Send a user turn; streamed events are delivered via {@link onEvent}. */
+    sendTurn(options: SendTurnOptions): Promise<void>;
+    /** Cancel an in-flight turn. */
+    cancelTurn(threadId: string, turnId: string): Promise<void>;
+    /**
+     * Reply to a pending approval the agent emitted (as an `approval` content
+     * block) for {@link threadId}. Optional: adapters that never request approval
+     * (or that run non-interactively) don't implement it. Implementations should
+     * be a no-op when there is no pending approval for `approvalId`.
+     */
+    respondApproval?(threadId: string, approvalId: string, decision: ApprovalDecision): Promise<void>;
+    /** Subscribe to streaming events. Returns an unsubscribe function. */
+    onEvent(listener: (event: AgentStreamEvent) => void): () => void;
+    /** List the models this agent's CLI reports as available (optional). */
+    listModels?(): Promise<AgentModel[]>;
+}

package/dist/src/agents/agent-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-adapter.js.map

package/dist/src/agents/agent-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-adapter.js","sourceRoot":"","sources":["../../../src/agents/agent-adapter.ts"],"names":[],"mappings":""}

package/dist/src/agents/agent-capabilities.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Declarative description of what an agent CLI adapter supports.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (adapters).
+ */
+export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli' | 'pi-agent' | 'aider'
+/** Built-in reference/dev agent that echoes the prompt (no external CLI). */
+ | 'echo';
+export interface AgentCapabilities {
+    /** Agent supports interactive plan mode. */
+    planMode: boolean;
+    /** Agent emits streaming token deltas. */
+    streaming: boolean;
+    /** Agent supports approval requests (tool gating). */
+    approvals: boolean;
+    /** Agent supports forking / resuming threads. */
+    forking: boolean;
+    /** Agent supports image inputs. */
+    images: boolean;
+    /**
+     * Agent reports per-turn token/context usage (`usage` on `turn/completed`),
+     * so the phone can show a context meter (at 0 until the first turn). Optional
+     * for back-compat; absent/false means the agent reports no usage (e.g.
+     * OpenCode) and the meter stays hidden.
+     */
+    reportsContextUsage?: boolean;
+}
+/**
+ * A registered agent the phone can pick for a thread, returned by `agent/list`.
+ */
+export interface AgentDescriptor {
+    agentId: AgentId;
+    /** Human-facing label (e.g. "OpenCode"). */
+    displayName: string;
+    /** Whether the agent's CLI/runtime is resolvable on this PC right now. */
+    available: boolean;
+    capabilities: AgentCapabilities;
+    /** Default model the bridge will use when the phone does not pick one. */
+    defaultModel?: string;
+}
+/** One selectable value of an {@link AgentModelOption} of kind `enum`. */
+export interface AgentModelOptionValue {
+    /** Value sent back in `turn/send` `options` when chosen. */
+    value: string;
+    /** Human-facing label for this value. */
+    label: string;
+}
+/**
+ * A per-model run-option "knob" the phone should let the user set for a turn
+ * (e.g. reasoning effort). Declared per {@link AgentModel} because the same
+ * agent's models can differ. The phone is a generic renderer: it shows only the
+ * knobs the bridge advertises and sends the chosen values back on `turn/send`
+ * (keyed by {@link AgentModelOption.key}); the bridge translates them into each
+ * CLI's real flag. Consumers MUST ignore an unknown `kind` so adding a knob
+ * never breaks an older app.
+ */
+export interface AgentModelOption {
+    /** Stable key echoed back in `turn/send` `options` (e.g. `reasoning`). */
+    key: string;
+    /** Control kind. Unknown kinds are ignored by the phone (forward-compatible). */
+    kind: 'enum' | 'toggle';
+    /** Human-facing label for the control. */
+    label: string;
+    /** For `enum`: the selectable values (omit for `toggle`). */
+    values?: AgentModelOptionValue[];
+    /** Default value when the agent has one (string for `enum`, boolean for `toggle`). */
+    default?: string | boolean;
+}
+/**
+ * A selectable model an agent reports, returned by `agent/models`.
+ *
+ * `id` is the wire value passed back to the agent for routing — a stable alias
+ * for Claude Code (`opus`/`sonnet`/`haiku`), a `provider/model` id for OpenCode,
+ * or a concrete model id for Codex. `displayName`, `description`, `version` and
+ * `isDefault` are presentation hints; consumers must tolerate any of them being
+ * absent (older bridges report bare id strings).
+ */
+export interface AgentModel {
+    /** Value sent back to the agent to select this model (the routing key). */
+    id: string;
+    /** Human-facing label. Falls back to `id` when the CLI offers nothing better. */
+    displayName: string;
+    /** One-line description, when the CLI provides one (e.g. Codex). */
+    description?: string;
+    /**
+     * Concrete underlying version when `id` is an alias that resolves to a
+     * moving target — e.g. Claude Code's `opus` → `claude-opus-4-8`. Surfaced so
+     * the user can see which exact model an alias currently maps to.
+     */
+    version?: string;
+    /** Whether this is the agent's current default model. */
+    isDefault?: boolean;
+    /**
+     * Per-model run-option knobs (reasoning effort, etc.) the phone may let the
+     * user set. Absent/empty when the model has none. The phone renders these
+     * generically and sends chosen values on `turn/send` via `options`.
+     */
+    options?: AgentModelOption[];
+    /**
+     * Context-window size in tokens, when the CLI reports it (e.g. pi's
+     * `--list-models` `context` column). Lets the adapter emit `usage.contextWindow`
+     * per turn so the phone can show context usage as a percentage. Absent when the
+     * CLI does not expose it.
+     */
+    contextWindow?: number;
+}

package/dist/src/agents/agent-capabilities.js

@@ -0,0 +1,7 @@
+/**
+ * Declarative description of what an agent CLI adapter supports.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (adapters).
+ */
+export {};
+//# sourceMappingURL=agent-capabilities.js.map

package/dist/src/agents/agent-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-capabilities.js","sourceRoot":"","sources":["../../../src/agents/agent-capabilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/agents/agent-config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-project agent configuration.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2.
+ */
+import type { AgentId } from './agent-capabilities.js';
+export interface AgentConfig {
+    agentId: AgentId;
+    /** Absolute path to the agent CLI binary, or null to resolve from PATH. */
+    binaryPath?: string;
+    /** Extra CLI arguments passed on every invocation. */
+    extraArgs?: string[];
+    /** Working directory override; defaults to the project cwd. */
+    cwd?: string;
+    /** Default model for this project/agent (e.g. `provider/model`), when pinned. */
+    model?: string;
+}

package/dist/src/agents/agent-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-config.js.map

package/dist/src/agents/agent-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config.js","sourceRoot":"","sources":["../../../src/agents/agent-config.ts"],"names":[],"mappings":""}

package/dist/src/constants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Protocol-wide constants shared by the bridge, relay and mobile app.
+ *
+ * These mirror the mobile side's `lib/core/constants/protocol_constants.dart`
+ * and MUST stay byte-for-byte compatible with it.
+ *
+ * Source: architecture/02a-system-architecture.md §5.9.1.
+ */
+/** Secure transport protocol version negotiated in the handshake. */
+export declare const SECURE_PROTOCOL_VERSION = 1;
+/** Version stamped into the pairing QR payload. */
+export declare const PAIRING_QR_VERSION = 2;
+/** HKDF `info` tag used when deriving the session key. */
+export declare const HKDF_INFO_TAG = "uxnan-e2ee-v1";
+/** Maximum age of a pairing payload before it is rejected (5 minutes). */
+export declare const MAX_PAIRING_AGE_MS = 300000;
+/** Allowed clock skew during handshake validation (60 seconds). */
+export declare const CLOCK_SKEW_TOLERANCE_MS = 60000;
+/** Allowed clock skew during trusted reconnect (90 seconds). */
+export declare const TRUSTED_RECONNECT_SKEW_MS = 90000;
+/** Bridge outbound buffer cap (messages) for catch-up on reconnect. */
+export declare const MAX_BRIDGE_OUTBOUND_MESSAGES = 500;
+/** Bridge outbound buffer cap (bytes) for catch-up on reconnect — 10 MiB. */
+export declare const MAX_BRIDGE_OUTBOUND_BYTES = 10485760;
+/** Default relay endpoint. */
+export declare const DEFAULT_RELAY_URL = "wss://relay.uxnan.io";
+/** Default LAN port for direct WebSocket connections. */
+export declare const DEFAULT_LAN_PORT = 19850;
+/** JSON-RPC protocol version string. */
+export declare const JSONRPC_VERSION = "2.0";

package/dist/src/constants.js

@@ -0,0 +1,31 @@
+/**
+ * Protocol-wide constants shared by the bridge, relay and mobile app.
+ *
+ * These mirror the mobile side's `lib/core/constants/protocol_constants.dart`
+ * and MUST stay byte-for-byte compatible with it.
+ *
+ * Source: architecture/02a-system-architecture.md §5.9.1.
+ */
+/** Secure transport protocol version negotiated in the handshake. */
+export const SECURE_PROTOCOL_VERSION = 1;
+/** Version stamped into the pairing QR payload. */
+export const PAIRING_QR_VERSION = 2;
+/** HKDF `info` tag used when deriving the session key. */
+export const HKDF_INFO_TAG = 'uxnan-e2ee-v1';
+/** Maximum age of a pairing payload before it is rejected (5 minutes). */
+export const MAX_PAIRING_AGE_MS = 300_000;
+/** Allowed clock skew during handshake validation (60 seconds). */
+export const CLOCK_SKEW_TOLERANCE_MS = 60_000;
+/** Allowed clock skew during trusted reconnect (90 seconds). */
+export const TRUSTED_RECONNECT_SKEW_MS = 90_000;
+/** Bridge outbound buffer cap (messages) for catch-up on reconnect. */
+export const MAX_BRIDGE_OUTBOUND_MESSAGES = 500;
+/** Bridge outbound buffer cap (bytes) for catch-up on reconnect — 10 MiB. */
+export const MAX_BRIDGE_OUTBOUND_BYTES = 10_485_760;
+/** Default relay endpoint. */
+export const DEFAULT_RELAY_URL = 'wss://relay.uxnan.io';
+/** Default LAN port for direct WebSocket connections. */
+export const DEFAULT_LAN_PORT = 19850;
+/** JSON-RPC protocol version string. */
+export const JSONRPC_VERSION = '2.0';
+//# sourceMappingURL=constants.js.map

package/dist/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,mDAAmD;AACnD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C,mEAAmE;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C,gEAAgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD,uEAAuE;AACvE,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEpD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AAExD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,wCAAwC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC"}

package/dist/src/e2ee/envelope.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Encrypted transport envelope (AES-256-GCM).
+ *
+ * Source: architecture/02a-system-architecture.md §5.9.1 (Phase 3).
+ */
+export interface SecureEnvelope {
+    kind: 'encryptedEnvelope';
+    sessionId: string;
+    /** Monotonic sequence number (replay protection). */
+    seq: number;
+    /** Per-message random nonce (hex, 12 bytes). */
+    nonce: string;
+    /** base64 AES-256-GCM ciphertext. */
+    ciphertext: string;
+    /** base64 GCM auth tag (16 bytes). */
+    tag: string;
+}

package/dist/src/e2ee/envelope.js

@@ -0,0 +1,7 @@
+/**
+ * Encrypted transport envelope (AES-256-GCM).
+ *
+ * Source: architecture/02a-system-architecture.md §5.9.1 (Phase 3).
+ */
+export {};
+//# sourceMappingURL=envelope.js.map

package/dist/src/e2ee/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/e2ee/envelope.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/e2ee/handshake.d.ts

@@ -0,0 +1,82 @@
+/**
+ * E2EE handshake message types.
+ *
+ * Source: architecture/02a-system-architecture.md §5.9.1.
+ *
+ * Canonical transcript encoding (the bytes that get signed) — the bridge MUST
+ * reproduce this byte-for-byte to interoperate with the mobile app:
+ *
+ *   transcript = clientNonce || phoneEphemeralPublicKey || macEphemeralPublicKey
+ *              || serverNonce || sessionId || keyEpoch || expiresAtForTranscript
+ *
+ * Each field is encoded in its *wire* form and UTF-8 concatenated, in order:
+ *   - byte fields (nonces, ephemeral keys): lowercase hex
+ *   - sessionId: the string as-is
+ *   - integers (keyEpoch, expiresAtForTranscript): decimal string
+ */
+import type { HandshakeMode } from '../models/session.js';
+export interface ClientHello {
+    kind: 'clientHello';
+    protocolVersion: number;
+    sessionId: string;
+    handshakeMode: HandshakeMode;
+    phoneDeviceId: string;
+    /** Ed25519 identity public key (hex, 32 bytes). */
+    phoneIdentityPublicKey: string;
+    /** X25519 ephemeral public key (hex, 32 bytes). */
+    phoneEphemeralPublicKey: string;
+    /** Random nonce (hex, 32 bytes). */
+    clientNonce: string;
+    resumeState?: ResumeState;
+}
+export interface ResumeState {
+    lastAppliedBridgeOutboundSeq: number;
+}
+export interface ServerHello {
+    kind: 'serverHello';
+    protocolVersion: number;
+    sessionId: string;
+    handshakeMode: HandshakeMode;
+    macDeviceId: string;
+    /** Ed25519 identity public key (hex, 32 bytes). */
+    macIdentityPublicKey: string;
+    /** X25519 ephemeral public key (hex, 32 bytes). */
+    macEphemeralPublicKey: string;
+    /** Random nonce (hex, 32 bytes). */
+    serverNonce: string;
+    keyEpoch: number;
+    expiresAtForTranscript: number;
+    /** Ed25519 signature over the transcript (hex, 64 bytes). */
+    macSignature: string;
+    /** Echo of the client nonce (hex). */
+    clientNonce: string;
+    displayName: string;
+}
+export interface ClientAuth {
+    kind: 'clientAuth';
+    sessionId: string;
+    phoneDeviceId: string;
+    keyEpoch: number;
+    /** Ed25519 signature over the same transcript (hex, 64 bytes). */
+    phoneSignature: string;
+}
+export interface HandshakeReady {
+    kind: 'ready';
+    sessionId: string;
+    keyEpoch: number;
+    macDeviceId: string;
+}
+export type HandshakeMessage = ClientHello | ServerHello | ClientAuth | HandshakeReady;
+/**
+ * Build the canonical transcript string that both peers sign. See the module
+ * docstring for the exact encoding contract.
+ */
+export declare function buildHandshakeTranscript(fields: {
+    clientNonce: string;
+    phoneEphemeralPublicKey: string;
+    macEphemeralPublicKey: string;
+    serverNonce: string;
+    sessionId: string;
+    keyEpoch: number;
+    expiresAtForTranscript: number;
+}): string;

package/dist/src/e2ee/handshake.js

@@ -0,0 +1,14 @@
+/**
+ * Build the canonical transcript string that both peers sign. See the module
+ * docstring for the exact encoding contract.
+ */
+export function buildHandshakeTranscript(fields) {
+    return (fields.clientNonce +
+        fields.phoneEphemeralPublicKey +
+        fields.macEphemeralPublicKey +
+        fields.serverNonce +
+        fields.sessionId +
+        String(fields.keyEpoch) +
+        String(fields.expiresAtForTranscript));
+}
+//# sourceMappingURL=handshake.js.map

package/dist/src/e2ee/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../../src/e2ee/handshake.ts"],"names":[],"mappings":"AA4EA;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAQxC;IACC,OAAO,CACL,MAAM,CAAC,WAAW;QAClB,MAAM,CAAC,uBAAuB;QAC9B,MAAM,CAAC,qBAAqB;QAC5B,MAAM,CAAC,WAAW;QAClB,MAAM,CAAC,SAAS;QAChB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;QACvB,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CACtC,CAAC;AACJ,CAAC"}

package/dist/src/e2ee/pairing-payload.d.ts

@@ -0,0 +1,44 @@
+export interface PairingPayload {
+    /** Payload version. Always {@link PAIRING_QR_VERSION}. */
+    v: number;
+    /**
+     * Relay WebSocket URL — the remote fallback transport. OPTIONAL: a LAN/Tailscale
+     * setup pairs over {@link hosts} alone with no hosted relay.
+     */
+    relay?: string;
+    /**
+     * Direct `host:port` addresses where the bridge's LAN server listens (the bridge's
+     * non-internal IPv4s — LAN and e.g. a Tailscale `100.x` address). The phone should
+     * try these FIRST and fall back to {@link relay}. At least one of `hosts`/`relay`
+     * must be present.
+     */
+    hosts?: string[];
+    sessionId: string;
+    macDeviceId: string;
+    /** Bridge Ed25519 identity public key (hex, 32 bytes). */
+    macIdentityPublicKey: string;
+    /** Unix epoch ms when this payload expires. */
+    expiresAt: number;
+    displayName: string;
+}
+export type PairingValidationError = 'invalid_json' | 'not_an_object' | 'unsupported_version' | 'missing_field' | 'missing_transport' | 'expired';
+export type PairingValidationResult = {
+    valid: true;
+    payload: PairingPayload;
+} | {
+    valid: false;
+    error: PairingValidationError;
+    detail?: string;
+};
+/** Serialize a pairing payload to the QR string: Base64 of the UTF-8 JSON. */
+export declare function encodePairingQr(payload: PairingPayload): string;
+/**
+ * Validate a decoded pairing payload object against the v2 contract.
+ *
+ * @param now current time in epoch ms (injected for testability)
+ */
+export declare function validatePairingPayload(value: unknown, now: number): PairingValidationResult;
+/** Parse a QR string (Base64 of UTF-8 JSON) and validate it in one step. */
+export declare function parsePairingQr(qr: string, now: number): PairingValidationResult;
+/** Convenience: the default expiry for a freshly generated payload. */
+export declare function defaultPairingExpiry(now: number): number;

package/dist/src/e2ee/pairing-payload.js

@@ -0,0 +1,82 @@
+/**
+ * Pairing QR payload (version 2).
+ *
+ * Source: architecture/02a-system-architecture.md §5.9.1 (Phase 1) and
+ * uxnandesktop/architecture/02e-bridge-integration.md §5.3.
+ *
+ * The bridge GENERATES this payload; the mobile app parses it
+ * (`PairingPayload.fromQrString`). The wire field names below are the contract.
+ *
+ * QR string encoding: **Base64 of the UTF-8 JSON** — verified against the mobile
+ * `PairingPayload.fromQrString` (spec 02a §5.5.4), which does
+ * `base64.decode(base64.normalize(qr))` then `jsonDecode`.
+ */
+import { MAX_PAIRING_AGE_MS, PAIRING_QR_VERSION } from '../constants.js';
+const REQUIRED_STRING_FIELDS = [
+    'sessionId',
+    'macDeviceId',
+    'macIdentityPublicKey',
+    'displayName',
+];
+/** Serialize a pairing payload to the QR string: Base64 of the UTF-8 JSON. */
+export function encodePairingQr(payload) {
+    return Buffer.from(JSON.stringify(payload), 'utf-8').toString('base64');
+}
+/**
+ * Validate a decoded pairing payload object against the v2 contract.
+ *
+ * @param now current time in epoch ms (injected for testability)
+ */
+export function validatePairingPayload(value, now) {
+    if (typeof value !== 'object' || value === null) {
+        return { valid: false, error: 'not_an_object' };
+    }
+    const obj = value;
+    if (obj['v'] !== PAIRING_QR_VERSION) {
+        return { valid: false, error: 'unsupported_version', detail: String(obj['v']) };
+    }
+    for (const field of REQUIRED_STRING_FIELDS) {
+        if (typeof obj[field] !== 'string' || obj[field].length === 0) {
+            return { valid: false, error: 'missing_field', detail: field };
+        }
+    }
+    if (typeof obj['expiresAt'] !== 'number') {
+        return { valid: false, error: 'missing_field', detail: 'expiresAt' };
+    }
+    if (obj['expiresAt'] <= now) {
+        return { valid: false, error: 'expired' };
+    }
+    // Transport fields: `relay` (string) and/or `hosts` (string[]) — at least one.
+    const relay = obj['relay'];
+    if (relay !== undefined && (typeof relay !== 'string' || relay.length === 0)) {
+        return { valid: false, error: 'missing_field', detail: 'relay' };
+    }
+    const hosts = obj['hosts'];
+    if (hosts !== undefined &&
+        (!Array.isArray(hosts) || hosts.some((h) => typeof h !== 'string' || h.length === 0))) {
+        return { valid: false, error: 'missing_field', detail: 'hosts' };
+    }
+    const hasRelay = typeof relay === 'string' && relay.length > 0;
+    const hasHosts = Array.isArray(hosts) && hosts.length > 0;
+    if (!hasRelay && !hasHosts) {
+        return { valid: false, error: 'missing_transport' };
+    }
+    return { valid: true, payload: obj };
+}
+/** Parse a QR string (Base64 of UTF-8 JSON) and validate it in one step. */
+export function parsePairingQr(qr, now) {
+    let decoded;
+    try {
+        const json = Buffer.from(qr.trim(), 'base64').toString('utf-8');
+        decoded = JSON.parse(json);
+    }
+    catch {
+        return { valid: false, error: 'invalid_json' };
+    }
+    return validatePairingPayload(decoded, now);
+}
+/** Convenience: the default expiry for a freshly generated payload. */
+export function defaultPairingExpiry(now) {
+    return now + MAX_PAIRING_AGE_MS;
+}
+//# sourceMappingURL=pairing-payload.js.map