@kangentic/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+See the LICENSE file in the root of this repository:
+https://github.com/Kangentic/kangentic/blob/main/LICENSE
+
+SPDX-License-Identifier: AGPL-3.0-only
+Copyright (C) 2025-2026 VORPAHL LLC. All rights reserved.

package/README.md

@@ -0,0 +1,27 @@
+# @kangentic/protocol
+
+Shared wire protocol for the Kangentic mobile bridge: frame encoding, the Noise-based pairing
+and session handshakes, secretstream-style AEAD framing, the signed device roster, capability
+verbs, and the transcript/board/activity event contract types the mobile app consumes.
+
+This package is the single source of truth for the desktop (`src/main/mobile-bridge/`) and
+`kangentic-mobile` implementations of the protocol. It is pure TypeScript on top of
+[`@noble/curves`](https://github.com/paulmillr/noble-curves),
+[`@noble/hashes`](https://github.com/paulmillr/noble-hashes), and
+[`@noble/ciphers`](https://github.com/paulmillr/noble-ciphers) so the exact same handshake code
+runs on Node (Electron main) and React Native (via the same pure-JS primitives), with no native
+module coupling.
+
+See `docs/mobile-bridge.md` in the main repository for the pairing ceremony, roster/revocation
+model, and the honest relay-metadata statement.
+
+## Security
+
+- `Noise_KK_25519_ChaChaPoly_BLAKE2s` for ongoing sessions (mutual authentication by construction,
+  no trust-on-first-use).
+- A token-bound Noise PSK handshake for the one-time pairing ceremony, confirmed by a Matrix-style
+  short authentication string (SAS) on both screens.
+- No shell, file, or arbitrary-command verb exists in the protocol.
+
+This package has not undergone a third-party security audit. Report suspected vulnerabilities
+per the repository's security policy rather than filing a public issue.

package/dist/capabilities/verbs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The complete set of capability verbs a paired device may be granted.
+ * There is deliberately NO shell, file-read, or arbitrary-command verb --
+ * absent from the protocol entirely, not filtered at runtime (the SSH
+ * forced-command lesson: Chrome Remote Desktop and VS Code tunnels are the
+ * counter-examples, identity-gated but capability-unscoped). Adding a new
+ * verb here is a protocol change; it does not, by itself, grant anything --
+ * the desktop's capability router (Phase 2) still has to implement and
+ * wire a handler, and a device's roster entry still has to include it in
+ * its CapabilitySet.
+ */
+export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt"];
+export type CapabilityVerb = (typeof CAPABILITY_VERBS)[number];
+export declare function isCapabilityVerb(value: string): value is CapabilityVerb;
+/** Deny-by-default: a verb absent from the set is not authorized. */
+export type CapabilitySet = ReadonlySet<CapabilityVerb>;
+export declare function capabilitySetFromArray(verbs: readonly string[]): CapabilitySet;
+export declare function capabilitySetToArray(capabilities: CapabilitySet): CapabilityVerb[];

package/dist/crypto/noise/cipher-state.d.ts

@@ -0,0 +1,9 @@
+export declare class CipherState {
+    private key;
+    private nonce;
+    initializeKey(key: Uint8Array | null): void;
+    hasKey(): boolean;
+    encryptWithAd(associatedData: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    /** Nonce is only advanced on a SUCCESSFUL decrypt; aeadDecrypt throws on tag failure. */
+    decryptWithAd(associatedData: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+}

package/dist/crypto/noise/handshake-state.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Noise Protocol Framework section 5.3: the HandshakeState object. A
+ * generic token interpreter driven by a NoisePattern, so both the ongoing
+ * session pattern (KK) and the pairing pattern (IKpsk0) share this exact
+ * code - only the pattern table and the supplied key material differ.
+ */
+import { type X25519KeyPair } from '../primitives';
+import { CipherState } from './cipher-state';
+import type { NoisePattern } from './patterns';
+export interface HandshakeStateOptions {
+    pattern: NoisePattern;
+    initiator: boolean;
+    /** Bound into the transcript before any key material - kills downgrade attacks when it encodes the negotiated protocol version. */
+    prologue: Uint8Array;
+    /** Local static keypair. Required whenever the pattern's local role sends or has pre-shared an "s" token. */
+    s?: X25519KeyPair;
+    /** Local ephemeral keypair. Only ever set by a test harness; production code always lets writeMessage() generate it. */
+    e?: X25519KeyPair;
+    /** Remote static public key. Required whenever the pattern's local role receives an "s" pre-message (e.g. KK) or already knows it out-of-band (e.g. IK's responder key from a QR). */
+    rs?: Uint8Array;
+    re?: Uint8Array;
+    /** 32-byte pre-shared key. Required by patterns with a "psk" token. */
+    psk?: Uint8Array;
+    /** Test-only override for ephemeral keypair generation, to replay a fixed test vector. */
+    generateEphemeral?: () => X25519KeyPair;
+}
+export interface HandshakeWriteResult {
+    message: Uint8Array;
+    /** Present once the pattern's last message has been written. */
+    split?: [CipherState, CipherState];
+}
+export interface HandshakeReadResult {
+    payload: Uint8Array;
+    /** Present once the pattern's last message has been read. */
+    split?: [CipherState, CipherState];
+}
+export declare class HandshakeState {
+    private readonly symmetricState;
+    private readonly pattern;
+    private readonly initiator;
+    private readonly generateEphemeral;
+    private readonly psk?;
+    private s?;
+    private e?;
+    private rs?;
+    private re?;
+    private messageIndex;
+    constructor(options: HandshakeStateOptions);
+    private resolvePreMessageKey;
+    private requireLocalKeyPair;
+    private requireRemoteKey;
+    private requirePsk;
+    private dh;
+    private mixDhToken;
+    private nextTokens;
+    private maybeSplit;
+    writeMessage(payload: Uint8Array): HandshakeWriteResult;
+    readMessage(message: Uint8Array): HandshakeReadResult;
+    getHandshakeHash(): Uint8Array;
+    /** See SymmetricState.getChainingKey(): only meaningful once split() has occurred. */
+    getChainingKey(): Uint8Array;
+    /** The remote static public key, once learned (pre-shared or received via an "s" token). */
+    getRemoteStaticKey(): Uint8Array | undefined;
+}

package/dist/crypto/noise/kk.d.ts

@@ -0,0 +1,11 @@
+import type { X25519KeyPair } from '../primitives';
+import { HandshakeState } from './handshake-state';
+export interface KKHandshakeOptions {
+    initiator: boolean;
+    /** Local device's static identity keypair. */
+    localStatic: X25519KeyPair;
+    /** Peer's static public key, already pinned in the signed device roster. */
+    remoteStatic: Uint8Array;
+    protocolVersion?: string;
+}
+export declare function createKKHandshake(options: KKHandshakeOptions): HandshakeState;

package/dist/crypto/noise/patterns.d.ts

@@ -0,0 +1,48 @@
+/** Noise message-pattern tokens (section 5.3, plus "psk" from section 9). */
+export type NoiseToken = 'e' | 's' | 'ee' | 'es' | 'se' | 'ss' | 'psk';
+export interface NoisePattern {
+    /** Used to construct the protocol name, e.g. "KK" -> Noise_KK_25519_ChaChaPoly_BLAKE2s. */
+    readonly name: string;
+    readonly initiatorPreMessage: readonly NoiseToken[];
+    readonly responderPreMessage: readonly NoiseToken[];
+    readonly messages: readonly (readonly NoiseToken[])[];
+    /**
+     * Noise section 9.2: in a PSK handshake every "e" token calls
+     * MixKey(e.public_key) in addition to the MixHash(e.public_key) a
+     * non-PSK handshake always does. This must be a property of the
+     * PATTERN (not inferred from "was a psk option passed"), since it
+     * changes how the "e" token itself is processed, independent of
+     * whether the pattern's own "psk" token has been reached yet.
+     */
+    readonly usesPsk: boolean;
+}
+/**
+ * Both parties' static keys are known in advance (mutual authentication by
+ * construction, no trust-on-first-use). Used for ongoing bridge sessions
+ * once a device is in the signed roster.
+ *
+ *   KK:
+ *     -> s
+ *     <- s
+ *     ...
+ *     -> e, es, ss
+ *     <- e, ee, se
+ */
+export declare const KK_PATTERN: NoisePattern;
+/**
+ * The initiator (phone) knows the responder's (desktop's) static key from
+ * the QR in advance; the responder learns the initiator's static key from
+ * the "s" token in message 1, which is exactly how the desktop learns the
+ * phone's identity key during pairing. The "psk0" modifier mixes the
+ * pairing token in before any Diffie-Hellman step, so message 1 only
+ * decrypts (and the "s"/payload fields inside it only authenticate) for a
+ * peer that has the same token - a wrong guess fails at DecryptAndHash
+ * with no oracle beyond "handshake failed".
+ *
+ *   IKpsk0:
+ *     <- s
+ *     ...
+ *     -> psk, e, es, s, ss
+ *     <- e, ee, se
+ */
+export declare const IKPSK0_PATTERN: NoisePattern;

package/dist/crypto/noise/symmetric-state.d.ts

@@ -0,0 +1,28 @@
+import { CipherState } from './cipher-state';
+export declare class SymmetricState {
+    private readonly cipherState;
+    private chainingKey;
+    private hash;
+    constructor(protocolName: Uint8Array);
+    mixKey(inputKeyMaterial: Uint8Array): void;
+    mixHash(data: Uint8Array): void;
+    /** Processes a "psk" token: MixKeyAndHash(psk) per Noise section 9. */
+    mixKeyAndHash(inputKeyMaterial: Uint8Array): void;
+    getHandshakeHash(): Uint8Array;
+    /**
+     * The raw chaining key, meaningful only after the handshake's message
+     * patterns are exhausted (alongside split()). Exposed so a caller can
+     * derive ADDITIONAL independent key material (e.g. secretstream framing
+     * keys) via its own domain-separated HKDF label - see
+     * crypto/secretstream.ts's deriveTransportKey. This is standard KDF
+     * practice (TLS 1.3's key schedule does the same): reusing one secret
+     * for multiple purposes via distinct labels is safe; Split()'s own
+     * derivation (empty info) and a labeled derivation never collide.
+     */
+    getChainingKey(): Uint8Array;
+    encryptAndHash(plaintext: Uint8Array): Uint8Array;
+    decryptAndHash(ciphertext: Uint8Array): Uint8Array;
+    hasKey(): boolean;
+    /** Only valid once every message pattern has been processed. */
+    split(): [CipherState, CipherState];
+}

package/dist/crypto/pairing-handshake.d.ts

@@ -0,0 +1,20 @@
+import type { X25519KeyPair } from './primitives';
+import { HandshakeState } from './noise/handshake-state';
+export interface PairingInitiatorOptions {
+    /** The phone's own static identity keypair. */
+    localStatic: X25519KeyPair;
+    /** The desktop's static public key, read from the QR payload. */
+    remoteStatic: Uint8Array;
+    /** The 32-byte single-use pairing token from the QR payload, used as the Noise PSK. */
+    pairingToken: Uint8Array;
+    protocolVersion?: string;
+}
+export declare function createPairingInitiatorHandshake(options: PairingInitiatorOptions): HandshakeState;
+export interface PairingResponderOptions {
+    /** The desktop's own static identity keypair (the one published in the QR). */
+    localStatic: X25519KeyPair;
+    /** The same 32-byte single-use pairing token minted for this QR. */
+    pairingToken: Uint8Array;
+    protocolVersion?: string;
+}
+export declare function createPairingResponderHandshake(options: PairingResponderOptions): HandshakeState;

package/dist/crypto/primitives.d.ts

@@ -0,0 +1,53 @@
+import { hexToBytes, bytesToHex } from '@noble/hashes/utils.js';
+export declare const X25519_KEY_LENGTH = 32;
+export declare const ED25519_KEY_LENGTH = 32;
+export declare const ED25519_SIGNATURE_LENGTH = 64;
+export declare const HASH_LENGTH = 32;
+export declare const AEAD_KEY_LENGTH = 32;
+export declare const CHACHA_NONCE_LENGTH = 12;
+export declare const XCHACHA_NONCE_LENGTH = 24;
+export declare const AEAD_TAG_LENGTH = 16;
+export declare function randomBytes(length: number): Uint8Array;
+export { hexToBytes, bytesToHex };
+export interface X25519KeyPair {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+export declare function generateX25519KeyPair(): X25519KeyPair;
+export declare function x25519PublicKeyFrom(secretKey: Uint8Array): Uint8Array;
+/** Diffie-Hellman: DH(localSecretKey, remotePublicKey). Throws on a low-order/invalid peer key. */
+export declare function x25519SharedSecret(secretKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+export interface Ed25519KeyPair {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+export declare function generateEd25519KeyPair(): Ed25519KeyPair;
+export declare function ed25519Sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+export declare function ed25519Verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+export declare function hashBlake2s(data: Uint8Array): Uint8Array;
+/**
+ * Noise's HKDF(chaining_key, input_key_material, num_outputs): HKDF-Extract
+ * with salt=chaining_key, ikm=input_key_material, then HKDF-Expand with an
+ * empty info, chunked into num_outputs HASH_LENGTH-byte blocks. This is
+ * exactly RFC 5869 HKDF with a zero-length info string, so the noble
+ * convenience function (extract+expand combined) is used directly rather
+ * than hand-rolling the counter loop.
+ */
+export declare function noiseHkdf(chainingKey: Uint8Array, inputKeyMaterial: Uint8Array, numOutputs: 2 | 3): Uint8Array[];
+/**
+ * Independent, domain-separated key derivation from a Noise chaining key,
+ * for material that is NOT part of the Noise handshake itself (e.g. the
+ * secretstream framing keys derived once a session's split() has run).
+ * Reusing one secret for multiple purposes via distinct labels is safe
+ * KDF practice as long as every purpose gets its own label; this is a
+ * plain HKDF-Expand-style derivation (salt=chainingKey, ikm=empty,
+ * info=label), independent of noiseHkdf's own empty-info convention.
+ */
+export declare function deriveLabeledKey(chainingKey: Uint8Array, label: string, length: number): Uint8Array;
+export declare function aeadEncrypt(key: Uint8Array, counter: bigint, associatedData: Uint8Array, plaintext: Uint8Array): Uint8Array;
+export declare function aeadDecrypt(key: Uint8Array, counter: bigint, associatedData: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+/** XChaCha20-Poly1305 with a 24-byte nonce - used by the secretstream framing, not the Noise handshake. */
+export declare function xaeadEncrypt(key: Uint8Array, nonce: Uint8Array, associatedData: Uint8Array, plaintext: Uint8Array): Uint8Array;
+export declare function xaeadDecrypt(key: Uint8Array, nonce: Uint8Array, associatedData: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+export declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+export declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;

package/dist/crypto/sas.d.ts

@@ -0,0 +1,7 @@
+export interface ShortAuthenticationString {
+    /** A 6-digit code, e.g. "042917". */
+    digits: string;
+    /** 5 emoji from a fixed 64-entry table. */
+    emoji: string[];
+}
+export declare function deriveShortAuthenticationString(handshakeHash: Uint8Array): ShortAuthenticationString;

package/dist/crypto/secretstream.d.ts

@@ -0,0 +1,39 @@
+export declare const FrameTag: {
+    readonly Message: 0;
+    readonly Rekey: 1;
+    readonly Final: 2;
+};
+export type FrameTag = (typeof FrameTag)[keyof typeof FrameTag];
+export declare class SecretstreamState {
+    private key;
+    private readonly nonceHeader;
+    private counter;
+    constructor(key: Uint8Array, nonceHeader: Uint8Array);
+    private nonceForCounter;
+    /** Encrypts one frame and advances this direction's counter. */
+    seal(plaintext: Uint8Array, tag?: FrameTag): Uint8Array;
+    /**
+     * Decrypts one frame and advances this direction's counter. Throws if
+     * the frame does not authenticate against the counter this instance
+     * currently expects - which is exactly what happens if a frame was
+     * replayed, reordered, or the stream was truncated and resumed wrong.
+     */
+    open(frame: Uint8Array): {
+        tag: FrameTag;
+        plaintext: Uint8Array;
+    };
+    /** Rotates this direction's key without a full Noise re-handshake, matching libsodium's REKEY tag. */
+    rekey(): void;
+}
+export interface SecretstreamDirectionPair {
+    send: SecretstreamState;
+    receive: SecretstreamState;
+}
+/**
+ * Derives both directions' secretstream state from a completed Noise
+ * session's chaining key (HandshakeState.getChainingKey(), valid once
+ * split() has run). Both peers call this with the SAME chaining key and
+ * opposite `isInitiator` values, so `initiator.send` pairs with
+ * `responder.receive` and vice versa.
+ */
+export declare function deriveSecretstreamPair(chainingKey: Uint8Array, isInitiator: boolean): SecretstreamDirectionPair;

package/dist/events/event.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The event contract skeleton the phone consumes. Phase 1 establishes the
+ * three event FAMILIES (transcript, board, activity) and their envelope
+ * shape; Phase 2 (data feeds & interactive control) is what actually maps
+ * desktop internals - SessionManager's `data`/`activity` events,
+ * transcript-service output, repository/DiffService mutations - onto
+ * these envelopes. Keeping `payload` as JsonValue here rather than a
+ * fully-typed shape per event avoids guessing at Phase 2's real mapping
+ * before that integration exists.
+ */
+import type { JsonValue } from '../wire/messages';
+export interface TranscriptEvent {
+    kind: 'transcript';
+    sessionId: string;
+    taskId: string;
+    payload: JsonValue;
+}
+export interface BoardEvent {
+    kind: 'board';
+    taskId: string;
+    payload: JsonValue;
+}
+export interface ActivityEvent {
+    kind: 'activity';
+    sessionId: string;
+    taskId: string;
+    payload: JsonValue;
+}
+export type BridgeEvent = TranscriptEvent | BoardEvent | ActivityEvent;