@uxnan/shared 0.0.7-alpha.20260719 → 0.0.9-alpha.20260721

package/README.md

@@ -52,7 +52,7 @@ flowchart TB
 | 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 (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), approval, question (interactive multiple-choice) |
+| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), bridge-owned profile metrics (complete-ledger export/import), approval, question (interactive multiple-choice) |
 | Agents | `IAgentAdapter` (with `respondApproval`, `listModels`, `nativeSessionId`, `SendTurnOptions { threadId, turnId, text, service?, effort?, options?, attachments?, cwd?, accessMode? }`), `AgentModel` (incl. `version?`, `isDefault?`, `options?`, `contextWindow?`, `isLatestAlias?`), `AgentCapabilities` (incl. `images`, `approvals`, `reportsContextUsage`), `AgentConfig` (cwd, agentId, model, plus optional `binaryPath`/`extraArgs`) |
 | Version | `compareVersions` / `isNewerVersion` — dependency-free SemVer precedence (used by the bridge's npm update check) |
 | Validation | Ajv validators for requests, responses, envelopes, pairing payload, push payloads |

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/dist/src/models/metrics.d.ts

@@ -6,10 +6,10 @@
  * agents/models used, connection time, git actions, an activity heatmap). Those
  * were derived on the phone from local storage and so were lost on an app
  * uninstall (the app has no cloud login). To make them durable, the **bridge**
- * becomes the source of truth: it computes them from its own authoritative data
- * (the conversation store) plus persisted session + git-action event logs it
- * observes itself, and serves them over `metrics/get`. The phone renders one
- * snapshot per PC and sums across PCs.
+ * becomes the source of truth: it persists a complete activity ledger
+ * (conversations, turns/messages, reported tokens, sessions and Git actions)
+ * and serves it over `metrics/get`. Deleting mutable conversation history does
+ * not subtract activity. The phone renders one snapshot per PC and sums PCs.
  *
  * A `metrics/export` produces an opaque, tamper-proof file only the SAME bridge
  * can later verify + decrypt (AES-256-GCM under a secret held in the PC's OS
@@ -76,10 +76,9 @@ export interface MetricsActivityDay {
 }
 /**
  * Aggregated metrics for ONE PC (the bridge that returns it), built from the
- * bridge's own authoritative data: the conversation store (threads/turns) plus
- * its persisted session + git-action event logs. The phone renders this per PC
- * and sums across PCs for the all-PCs profile. Every field is a count the phone
- * cannot inflate — the bridge observes it. Source of `metrics/get`.
+ * bridge's durable activity ledger. The phone renders this per PC and sums
+ * across PCs for the all-PCs profile. Every field is a count the phone cannot
+ * inflate — the bridge observes and retains it. Source of `metrics/get`.
  */
 export interface MetricsSnapshot {
     /** Schema version, for forward-compatible parsing. */
@@ -123,7 +122,7 @@ export interface MetricsSnapshot {
     updatedAt: number;
 }
 /**
- * `metrics/export` request. The bridge seals its metrics event log into an
+ * `metrics/export` request. The bridge seals its complete metrics ledger into an
  * opaque, tamper-proof blob that only THIS same bridge can later verify +
  * decrypt (AES-256-GCM under a secret held in the OS keychain). An optional user
  * [passphrase] adds a second confidentiality layer (scrypt-derived), so a leaked
@@ -145,8 +144,8 @@ export interface MetricsExportResult {
  * `metrics/import` request. The phone sends back a previously exported [blob].
  * The bridge verifies it was sealed by THIS PC — a foreign or edited file is
  * rejected — decrypts it (using [passphrase] when the file was passphrase-locked)
- * and merges its events by id (idempotent: re-importing the same file changes
- * nothing). Returns the refreshed snapshot.
+ * and merges its ledger rows by id (idempotent: re-importing the same file
+ * changes nothing). Returns the refreshed snapshot.
  */
 export interface MetricsImportParams {
     /** The sealed blob produced by a prior `metrics/export` on this PC. */
@@ -155,7 +154,7 @@ export interface MetricsImportParams {
     passphrase?: string;
 }
 export interface MetricsImportResult {
-    /** How many new session + git-action events were merged in. */
+    /** How many ledger rows were inserted or advanced. */
     imported: number;
     /** The refreshed snapshot after the merge. */
     snapshot: MetricsSnapshot;

package/dist/src/models/metrics.js

@@ -6,10 +6,10 @@
  * agents/models used, connection time, git actions, an activity heatmap). Those
  * were derived on the phone from local storage and so were lost on an app
  * uninstall (the app has no cloud login). To make them durable, the **bridge**
- * becomes the source of truth: it computes them from its own authoritative data
- * (the conversation store) plus persisted session + git-action event logs it
- * observes itself, and serves them over `metrics/get`. The phone renders one
- * snapshot per PC and sums across PCs.
+ * becomes the source of truth: it persists a complete activity ledger
+ * (conversations, turns/messages, reported tokens, sessions and Git actions)
+ * and serves it over `metrics/get`. Deleting mutable conversation history does
+ * not subtract activity. The phone renders one snapshot per PC and sums PCs.
  *
  * A `metrics/export` produces an opaque, tamper-proof file only the SAME bridge
  * can later verify + decrypt (AES-256-GCM under a secret held in the PC's OS

package/package.json

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