@kangentic/protocol 0.6.0 → 0.7.0

package/dist/crypto/push-envelope.d.ts

@@ -1,4 +1,4 @@
-export declare const PUSH_CATEGORIES: readonly ["permission-needed", "agent-question", "turn-complete", "session-failed"];
+export declare const PUSH_CATEGORIES: readonly ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
 export type PushCategory = (typeof PUSH_CATEGORIES)[number];
 export declare function isPushCategory(value: unknown): value is PushCategory;
 /** Reject an opened envelope whose sentAt is older than this (stale replay). */

package/dist/index.cjs

@@ -5186,6 +5186,56 @@ function base64UrlDecode(encoded) {
   return bytes;
 }
 
+// src/crypto/push-envelope.ts
+var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+function isPushCategory(value) {
+  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
+}
+var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+function requireEnvelopeString(record, field) {
+  const value = record[field];
+  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
+  return value;
+}
+function parsePushEnvelopePlaintext(value) {
+  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
+  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
+  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
+    throw new Error('push envelope plaintext has an invalid "sentAt"');
+  }
+  return {
+    category: value.category,
+    projectId: requireEnvelopeString(value, "projectId"),
+    taskId: requireEnvelopeString(value, "taskId"),
+    sessionId: requireEnvelopeString(value, "sessionId"),
+    taskTitle: requireEnvelopeString(value, "taskTitle"),
+    detail: requireEnvelopeString(value, "detail"),
+    sentAt: value.sentAt
+  };
+}
+function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
+  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
+  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
+  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
+  return base64UrlEncode(concatBytes4(nonce, ciphertext));
+}
+function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
+  const bytes = base64UrlDecode(blob);
+  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
+    throw new Error("push envelope blob is too short");
+  }
+  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
+  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
+  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
+  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
+  const plaintext = parsePushEnvelopePlaintext(decoded);
+  const now = Date.now();
+  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
+  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
+  return plaintext;
+}
+
 // src/events/payloads.ts
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
@@ -5651,6 +5701,12 @@ function parseRegisterPushRequestPayload(payload) {
     }
     request.platform = payload.platform;
   }
+  if (payload.categories !== void 0) {
+    if (!Array.isArray(payload.categories) || !payload.categories.every((entry) => typeof entry === "string")) {
+      throw new Error('register-push payload has a malformed "categories"');
+    }
+    request.categories = payload.categories.filter(isPushCategory);
+  }
   if (request.action === "register") {
     if (request.expoPushToken === void 0) throw new Error('register-push register payload missing "expoPushToken"');
     if (request.pushKeyBase64 === void 0) throw new Error('register-push register payload missing "pushKeyBase64"');
@@ -5685,56 +5741,6 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
-// src/crypto/push-envelope.ts
-var PUSH_CATEGORIES = ["permission-needed", "agent-question", "turn-complete", "session-failed"];
-function isPushCategory(value) {
-  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
-}
-var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
-var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
-function requireEnvelopeString(record, field) {
-  const value = record[field];
-  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
-  return value;
-}
-function parsePushEnvelopePlaintext(value) {
-  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
-  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
-  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
-    throw new Error('push envelope plaintext has an invalid "sentAt"');
-  }
-  return {
-    category: value.category,
-    projectId: requireEnvelopeString(value, "projectId"),
-    taskId: requireEnvelopeString(value, "taskId"),
-    sessionId: requireEnvelopeString(value, "sessionId"),
-    taskTitle: requireEnvelopeString(value, "taskTitle"),
-    detail: requireEnvelopeString(value, "detail"),
-    sentAt: value.sentAt
-  };
-}
-function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
-  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
-  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
-  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
-  return base64UrlEncode(concatBytes4(nonce, ciphertext));
-}
-function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
-  const bytes = base64UrlDecode(blob);
-  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("push envelope blob is too short");
-  }
-  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
-  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
-  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
-  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
-  const plaintext = parsePushEnvelopePlaintext(decoded);
-  const now = Date.now();
-  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
-  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
-  return plaintext;
-}
-
 // src/pairing/qr.ts
 var PAIRING_URI_SCHEME = "kangentic-pair";
 var PAYLOAD_VERSION = 1;

package/dist/index.mjs

@@ -5075,6 +5075,56 @@ function base64UrlDecode(encoded) {
   return bytes;
 }
 
+// src/crypto/push-envelope.ts
+var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+function isPushCategory(value) {
+  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
+}
+var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+function requireEnvelopeString(record, field) {
+  const value = record[field];
+  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
+  return value;
+}
+function parsePushEnvelopePlaintext(value) {
+  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
+  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
+  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
+    throw new Error('push envelope plaintext has an invalid "sentAt"');
+  }
+  return {
+    category: value.category,
+    projectId: requireEnvelopeString(value, "projectId"),
+    taskId: requireEnvelopeString(value, "taskId"),
+    sessionId: requireEnvelopeString(value, "sessionId"),
+    taskTitle: requireEnvelopeString(value, "taskTitle"),
+    detail: requireEnvelopeString(value, "detail"),
+    sentAt: value.sentAt
+  };
+}
+function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
+  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
+  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
+  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
+  return base64UrlEncode(concatBytes4(nonce, ciphertext));
+}
+function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
+  const bytes = base64UrlDecode(blob);
+  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
+    throw new Error("push envelope blob is too short");
+  }
+  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
+  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
+  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
+  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
+  const plaintext = parsePushEnvelopePlaintext(decoded);
+  const now = Date.now();
+  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
+  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
+  return plaintext;
+}
+
 // src/events/payloads.ts
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
@@ -5540,6 +5590,12 @@ function parseRegisterPushRequestPayload(payload) {
     }
     request.platform = payload.platform;
   }
+  if (payload.categories !== void 0) {
+    if (!Array.isArray(payload.categories) || !payload.categories.every((entry) => typeof entry === "string")) {
+      throw new Error('register-push payload has a malformed "categories"');
+    }
+    request.categories = payload.categories.filter(isPushCategory);
+  }
   if (request.action === "register") {
     if (request.expoPushToken === void 0) throw new Error('register-push register payload missing "expoPushToken"');
     if (request.pushKeyBase64 === void 0) throw new Error('register-push register payload missing "pushKeyBase64"');
@@ -5574,56 +5630,6 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
-// src/crypto/push-envelope.ts
-var PUSH_CATEGORIES = ["permission-needed", "agent-question", "turn-complete", "session-failed"];
-function isPushCategory(value) {
-  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
-}
-var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
-var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
-function requireEnvelopeString(record, field) {
-  const value = record[field];
-  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
-  return value;
-}
-function parsePushEnvelopePlaintext(value) {
-  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
-  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
-  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
-    throw new Error('push envelope plaintext has an invalid "sentAt"');
-  }
-  return {
-    category: value.category,
-    projectId: requireEnvelopeString(value, "projectId"),
-    taskId: requireEnvelopeString(value, "taskId"),
-    sessionId: requireEnvelopeString(value, "sessionId"),
-    taskTitle: requireEnvelopeString(value, "taskTitle"),
-    detail: requireEnvelopeString(value, "detail"),
-    sentAt: value.sentAt
-  };
-}
-function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
-  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
-  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
-  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
-  return base64UrlEncode(concatBytes4(nonce, ciphertext));
-}
-function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
-  const bytes = base64UrlDecode(blob);
-  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("push envelope blob is too short");
-  }
-  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
-  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
-  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
-  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
-  const plaintext = parsePushEnvelopePlaintext(decoded);
-  const now = Date.now();
-  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
-  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
-  return plaintext;
-}
-
 // src/pairing/qr.ts
 var PAIRING_URI_SCHEME = "kangentic-pair";
 var PAYLOAD_VERSION = 1;

package/dist/wire/payloads.d.ts

@@ -15,6 +15,7 @@
  */
 import type { CapabilityVerb } from '../capabilities/verbs';
 import type { JsonValue } from './messages';
+import { type PushCategory } from '../crypto/push-envelope';
 import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
 export interface ReadStreamRequestPayload {
     sessionId: string;
@@ -207,12 +208,20 @@ export interface BoardToolResponsePayload {
  * notification envelope with (see crypto/push-envelope.ts); 'unregister'
  * carries neither. The desktop keys the registration by the requesting
  * device's roster identity, never by anything in this payload.
+ *
+ * `categories`, when present, is the device's push preferences: the desktop
+ * filters outgoing notifications to this set before sending, so preference
+ * enforcement never depends on the receiving device (a future iOS
+ * Notification Service Extension stays preference-free). Absent means every
+ * category (the default, and what an older device that predates this field
+ * implicitly requests); an explicit empty array means none.
  */
 export interface RegisterPushRequestPayload {
     action: 'register' | 'unregister';
     expoPushToken?: string;
     pushKeyBase64?: string;
     platform?: 'android' | 'ios';
+    categories?: PushCategory[];
 }
 export interface RegisterPushResponsePayload {
     registered: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.6.0",
+  "version": "0.7.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",