@uxnan/shared 0.0.7-alpha.20260719 → 0.0.8-alpha.20260720

package/dist/src/constants.d.ts

@@ -6,8 +6,29 @@
  *
  * Source: architecture/02a-system-architecture.md §5.9.1.
  */
-/** Secure transport protocol version negotiated in the handshake. */
-export declare const SECURE_PROTOCOL_VERSION = 1;
+/**
+ * Secure transport protocol version negotiated in the handshake. Both sides
+ * reject a mismatch during `clientHello`/`serverHello`, so an incompatible pair
+ * fails fast and legibly instead of completing the handshake and then dropping
+ * every encrypted frame.
+ *
+ * **Bump this whenever the encrypted-frame format changes** (envelope shape,
+ * AAD layout, key derivation) — not just when the handshake JSON changes. The
+ * handshake is the only place the two sides can still talk, so it is the only
+ * place a version gap can be reported.
+ *
+ * - `1` — initial: AES-256-GCM over the envelope's ciphertext only.
+ * - `2` — `sessionId`/`seq`/direction bound as GCM AAD (`buildEnvelopeAad`).
+ */
+export declare const SECURE_PROTOCOL_VERSION = 2;
+/**
+ * AAD direction bytes for {@link SECURE_PROTOCOL_VERSION} ≥ 2. The session key
+ * is shared by both directions, so the direction is bound into the AAD to stop
+ * a frame being reflected back at its own sender as apparently-inbound traffic.
+ * Mirrored in the mobile `ProtocolConstants`.
+ */
+export declare const ENVELOPE_DIRECTION_PHONE_TO_BRIDGE = 1;
+export declare const ENVELOPE_DIRECTION_BRIDGE_TO_PHONE = 2;
 /** Version stamped into the pairing QR payload. */
 export declare const PAIRING_QR_VERSION = 2;
 /** HKDF `info` tag used when deriving the session key. */

package/dist/src/constants.js

@@ -6,8 +6,29 @@
  *
  * Source: architecture/02a-system-architecture.md §5.9.1.
  */
-/** Secure transport protocol version negotiated in the handshake. */
-export const SECURE_PROTOCOL_VERSION = 1;
+/**
+ * Secure transport protocol version negotiated in the handshake. Both sides
+ * reject a mismatch during `clientHello`/`serverHello`, so an incompatible pair
+ * fails fast and legibly instead of completing the handshake and then dropping
+ * every encrypted frame.
+ *
+ * **Bump this whenever the encrypted-frame format changes** (envelope shape,
+ * AAD layout, key derivation) — not just when the handshake JSON changes. The
+ * handshake is the only place the two sides can still talk, so it is the only
+ * place a version gap can be reported.
+ *
+ * - `1` — initial: AES-256-GCM over the envelope's ciphertext only.
+ * - `2` — `sessionId`/`seq`/direction bound as GCM AAD (`buildEnvelopeAad`).
+ */
+export const SECURE_PROTOCOL_VERSION = 2;
+/**
+ * AAD direction bytes for {@link SECURE_PROTOCOL_VERSION} ≥ 2. The session key
+ * is shared by both directions, so the direction is bound into the AAD to stop
+ * a frame being reflected back at its own sender as apparently-inbound traffic.
+ * Mirrored in the mobile `ProtocolConstants`.
+ */
+export const ENVELOPE_DIRECTION_PHONE_TO_BRIDGE = 0x01;
+export const ENVELOPE_DIRECTION_BRIDGE_TO_PHONE = 0x02;
 /** Version stamped into the pairing QR payload. */
 export const PAIRING_QR_VERSION = 2;
 /** HKDF `info` tag used when deriving the session key. */

package/dist/src/constants.js.map

@@ -1 +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"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC;AACvD,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC;AAEvD,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

@@ -5,8 +5,24 @@
  */
 export interface SecureEnvelope {
     kind: 'encryptedEnvelope';
+    /**
+     * Session this envelope belongs to. Travels in the clear (the receiver needs
+     * it before it can look up a key) and is therefore bound as GCM AAD — see
+     * {@link seq}.
+     */
     sessionId: string;
-    /** Monotonic sequence number (replay protection). */
+    /**
+     * Monotonic sequence number (replay protection). Like `sessionId` it is
+     * visible on the wire, so from `SECURE_PROTOCOL_VERSION` 2 both are bound —
+     * together with a direction byte — as the AES-GCM **AAD**:
+     *
+     *   AAD = utf8(sessionId) || 0x00 || u64_be(seq) || 0x00 || direction
+     *
+     * so tampering with either field fails the tag instead of silently passing an
+     * unauthenticated `seq <= lastApplied` check. Both implementations must build
+     * this byte-for-byte identically (`buildEnvelopeAad` on each side); see
+     * architecture/02a §5.9.1.
+     */
     seq: number;
     /** Per-message random nonce (hex, 12 bytes). */
     nonce: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxnan/shared",
-  "version": "0.0.7-alpha.20260719",
+  "version": "0.0.8-alpha.20260720",
   "description": "Shared JSON-RPC and E2EE contracts for the Uxnan ecosystem (bridge, relay, mobile).",
   "license": "MPL-2.0",
   "author": "Luis Donaldo Gamas Vazquez",