@kangentic/protocol 0.1.0

package/dist/pairing/qr.d.ts

@@ -0,0 +1,19 @@
+export declare const PAIRING_URI_SCHEME = "kangentic-pair";
+export interface PairingQrPayload {
+    desktopStaticPublicKey: Uint8Array;
+    pairingToken: Uint8Array;
+    relayAddress: string;
+    /** ISO 8601. The pairing service is the actual enforcement point; this is carried for the phone's own UX (e.g. "this code expired"). */
+    expiresAt: string;
+    /**
+     * The bridge protocol version (see version.ts's PROTOCOL_VERSION), so the
+     * phone can surface "this desktop is running an incompatible version,
+     * please update" BEFORE attempting a handshake doomed to fail, instead
+     * of only an opaque authentication error. The actual downgrade
+     * PROTECTION is the Noise prologue binding (crypto/pairing-handshake.ts),
+     * which is enforced independent of this field; this is diagnostic only.
+     */
+    protocolVersion: string;
+}
+export declare function encodePairingQrPayload(payload: PairingQrPayload): string;
+export declare function decodePairingQrPayload(uri: string): PairingQrPayload;

package/dist/roster/roster.d.ts

@@ -0,0 +1,33 @@
+import { type CapabilitySet, type CapabilityVerb } from '../capabilities/verbs';
+export interface RosterDeviceEntry {
+    /** Stable identifier for this device, independent of display name - derived from its static public key by the caller. */
+    deviceId: string;
+    /** The device's X25519 static identity public key (32 bytes). */
+    staticPublicKey: Uint8Array;
+    displayName: string;
+    capabilities: CapabilityVerb[];
+    /** ISO 8601. */
+    pairedAt: string;
+    /** ISO 8601, or null for no expiry (Tailscale-style per-device key expiry is opt-in). */
+    expiresAt: string | null;
+    /** Ed25519 signature over encodeForSigning(this entry minus signature), by the roster's master signing key. */
+    signature: Uint8Array;
+}
+export interface DeviceRoster {
+    /** The desktop's Ed25519 master signing public key - the roster's root of trust. */
+    masterSigningPublicKey: Uint8Array;
+    devices: RosterDeviceEntry[];
+}
+/**
+ * A deterministic, unambiguous byte encoding of a roster entry (minus its
+ * signature) for signing/verification. Every field is length-prefixed so
+ * concatenation cannot be reinterpreted across a field boundary (e.g.
+ * deviceId="ab"+displayName="c" cannot collide with deviceId="a"+displayName="bc").
+ */
+export declare function encodeRosterEntryForSigning(entry: Omit<RosterDeviceEntry, 'signature'>): Uint8Array;
+export declare function signRosterEntry(masterSigningSecretKey: Uint8Array, entry: Omit<RosterDeviceEntry, 'signature'>): RosterDeviceEntry;
+export declare function verifyRosterEntry(masterSigningPublicKey: Uint8Array, entry: RosterDeviceEntry): boolean;
+export declare function isRosterEntryExpired(entry: RosterDeviceEntry, now: Date): boolean;
+export declare function findRosterDevice(roster: DeviceRoster, deviceId: string): RosterDeviceEntry | undefined;
+export declare function rosterDeviceCapabilitySet(entry: RosterDeviceEntry): CapabilitySet;
+export declare function capabilitySetToRosterCapabilities(capabilities: CapabilitySet): CapabilityVerb[];

package/dist/transport/transport.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The swappable transport boundary. A Transport moves opaque frames
+ * (already-encrypted secretstream frames, or raw Noise handshake bytes
+ * during pairing/session setup) between two peers; it knows nothing about
+ * Noise, capability verbs, or the message schema. The relay client
+ * (src/main/mobile-bridge/transport/relay-client.ts, desktop-side) is the
+ * v1 implementation; a WebRTC data channel implementation (Phase 4) slots
+ * in behind this exact interface, so nothing above the transport layer
+ * changes when direct P2P becomes available.
+ */
+export type TransportState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+export type Unsubscribe = () => void;
+export interface Transport {
+    readonly state: TransportState;
+    connect(): Promise<void>;
+    /** Sends one opaque frame. Throws if the transport is not connected. */
+    send(frame: Uint8Array): void;
+    /** Synchronous, idempotent teardown. */
+    close(): void;
+    onFrame(listener: (frame: Uint8Array) => void): Unsubscribe;
+    onStateChange(listener: (state: TransportState) => void): Unsubscribe;
+}

package/dist/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The protocol version string. Bumped on any wire-incompatible change to
+ * framing, message shapes, or the handshake patterns in this package.
+ *
+ * Bound into every Noise handshake's prologue (see crypto/noise/kk.ts and
+ * crypto/pairing-handshake.ts), so two peers running different protocol
+ * versions fail the handshake outright instead of silently downgrading: a
+ * differing prologue produces a differing transcript hash `h` from the
+ * first MixHash call, which cascades into every derived key.
+ */
+export declare const PROTOCOL_VERSION = "1";
+export declare function encodeProtocolVersion(version?: string): Uint8Array;

package/dist/wire/base64url.d.ts

@@ -0,0 +1,2 @@
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function base64UrlDecode(encoded: string): Uint8Array;

package/dist/wire/framing.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeMessage } from './messages';
+export declare const MAX_FRAME_LENGTH: number;
+export declare function encodeMessage(message: BridgeMessage): Uint8Array;
+export declare function decodeMessage(bytes: Uint8Array): BridgeMessage;

package/dist/wire/messages.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The application-level message shapes carried inside secretstream frames
+ * once a bridge session is established (crypto/secretstream.ts handles
+ * the encrypted framing; this is what gets encoded/decoded as the
+ * plaintext payload - see framing.ts).
+ *
+ * Phase 1 wires the transport and the message ENVELOPE, not real
+ * capability-verb handlers or event feeds - those are Phase 2 (data
+ * feeds, interactive control) and Phase 3 (notifications). `payload` on
+ * the request/response/event variants is intentionally a generic JSON
+ * value here rather than a fully-typed union per verb/event, since the
+ * real shapes depend on desktop internals (SessionManager, repositories,
+ * DiffService) that Phase 2 integrates with; over-specifying them now
+ * would just be guessing. The capability verb ENUM itself
+ * (capabilities/verbs.ts) and the event type skeleton (events/) are
+ * final for Phase 1; only their payload contents are deferred.
+ */
+import type { CapabilityVerb } from '../capabilities/verbs';
+import type { BridgeEvent } from '../events/event';
+/** JSON-serializable value - deliberately not `any`; every message payload must round-trip through JSON.stringify/parse. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface HeartbeatMessage {
+    type: 'heartbeat';
+}
+export interface CapabilityRequestMessage {
+    type: 'capability-request';
+    requestId: string;
+    verb: CapabilityVerb;
+    payload: JsonValue;
+}
+export interface CapabilityResponseMessage {
+    type: 'capability-response';
+    requestId: string;
+    ok: boolean;
+    payload?: JsonValue;
+    /** Present only when ok is false. */
+    error?: string;
+}
+export interface EventMessage {
+    type: 'event';
+    event: BridgeEvent;
+}
+export type BridgeMessage = HeartbeatMessage | CapabilityRequestMessage | CapabilityResponseMessage | EventMessage;

package/dist/wire/session-frame.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A one-byte frame-kind prefix for the ONGOING SESSION connection only
+ * (not pairing, which never mixes frame kinds on its dedicated
+ * connection). A bridge session periodically re-handshakes on the same
+ * transport connection it also carries application traffic on (Noise KK
+ * every ~2 minutes, per the research doc's bounded post-compromise
+ * security design), so an incoming frame is otherwise ambiguous: "the
+ * next message of an in-progress Noise handshake" and "a secretstream-sealed
+ * application frame" are both just opaque bytes at the transport level.
+ * This tiny, unauthenticated-but-harmless prefix removes that ambiguity
+ * for BOTH peers (desktop and mobile), so it lives here rather than as a
+ * desktop-only convention.
+ */
+export declare const SessionFrameKind: {
+    readonly Handshake: 0;
+    readonly Application: 1;
+};
+export type SessionFrameKind = (typeof SessionFrameKind)[keyof typeof SessionFrameKind];
+export declare function wrapSessionFrame(kind: SessionFrameKind, payload: Uint8Array): Uint8Array;
+export declare function unwrapSessionFrame(frame: Uint8Array): {
+    kind: SessionFrameKind;
+    payload: Uint8Array;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kangentic/protocol",
+  "version": "0.1.0",
+  "description": "Kangentic mobile bridge wire protocol: framing, Noise-based pairing and session handshakes, signed device roster, and capability verbs shared between desktop and mobile.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kangentic/kangentic.git"
+  },
+  "keywords": [
+    "kangentic",
+    "protocol",
+    "noise-protocol",
+    "e2ee",
+    "mobile"
+  ],
+  "author": {
+    "name": "Kangentic",
+    "url": "https://github.com/Kangentic"
+  },
+  "license": "AGPL-3.0-only",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs && tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "typescript": "^6.0.3"
+  }
+}