chainlesschain 0.162.147 → 0.162.148

package/src/harness/remote-session-crypto.js

@@ -0,0 +1,217 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+} from "crypto";
+
+const PROTOCOL = "chainlesschain.remote-session.e2ee.v1";
+const PAIRING_SCHEME = "chainlesschain://remote-session/pair#";
+
+function b64(value) {
+  return Buffer.from(value).toString("base64url");
+}
+
+function unb64(value) {
+  return Buffer.from(value, "base64url");
+}
+
+function exportPublicKey(key) {
+  return b64(key.export({ type: "spki", format: "der" }));
+}
+
+function importPublicKey(value) {
+  let der = unb64(value);
+  if (der.length === 32) {
+    // RFC 8410 SubjectPublicKeyInfo prefix for a raw X25519 public key.
+    der = Buffer.concat([Buffer.from("302a300506032b656e032100", "hex"), der]);
+  }
+  return createPublicKey({ key: der, type: "spki", format: "der" });
+}
+
+function aad(sessionId, senderId, sequence) {
+  return Buffer.from(
+    `${PROTOCOL}\n${sessionId}\n${senderId}\n${sequence}`,
+    "utf8",
+  );
+}
+
+function deriveKey(privateKey, peerPublicKey, sessionId, pairingToken) {
+  const secret = diffieHellman({ privateKey, publicKey: peerPublicKey });
+  const salt = createHash("sha256").update(pairingToken, "utf8").digest();
+  return Buffer.from(
+    hkdfSync(
+      "sha256",
+      secret,
+      salt,
+      Buffer.from(`${PROTOCOL}:${sessionId}`),
+      32,
+    ),
+  );
+}
+
+export function createRemoteSessionKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  return {
+    publicKey: exportPublicKey(publicKey),
+    privateKey: b64(privateKey.export({ type: "pkcs8", format: "der" })),
+  };
+}
+
+export function createRemotePairingUri({
+  relayUrl,
+  remoteSessionId,
+  hostPeerId,
+  hostPublicKey,
+  pairingToken,
+  expiresAt,
+}) {
+  if (
+    !relayUrl ||
+    !remoteSessionId ||
+    !hostPeerId ||
+    !hostPublicKey ||
+    !pairingToken
+  ) {
+    throw new Error("Incomplete Remote Session pairing payload");
+  }
+  const payload = {
+    v: 1,
+    relayUrl,
+    remoteSessionId,
+    hostPeerId,
+    hostPublicKey,
+    pairingToken,
+    expiresAt,
+  };
+  return `${PAIRING_SCHEME}${b64(JSON.stringify(payload))}`;
+}
+
+export function parseRemotePairingUri(uri, now = Date.now()) {
+  if (typeof uri !== "string" || !uri.startsWith(PAIRING_SCHEME)) {
+    throw new Error("Invalid Remote Session pairing URI");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(
+      unb64(uri.slice(PAIRING_SCHEME.length)).toString("utf8"),
+    );
+  } catch {
+    throw new Error("Malformed Remote Session pairing payload");
+  }
+  if (
+    payload.v !== 1 ||
+    !payload.relayUrl ||
+    !payload.remoteSessionId ||
+    !payload.hostPeerId ||
+    !payload.hostPublicKey ||
+    !payload.pairingToken
+  ) {
+    throw new Error("Incomplete Remote Session pairing payload");
+  }
+  if (payload.expiresAt && payload.expiresAt <= now) {
+    throw new Error("Remote Session pairing payload expired");
+  }
+  return payload;
+}
+
+export class RemoteSessionCryptoContext {
+  constructor({ sessionId, localPeerId, privateKey, publicKey } = {}) {
+    if (!sessionId || !localPeerId)
+      throw new Error("sessionId and localPeerId are required");
+    let keyPair;
+    if (!privateKey || !publicKey) keyPair = createRemoteSessionKeyPair();
+    this.sessionId = sessionId;
+    this.localPeerId = localPeerId;
+    this.privateKey = createPrivateKey({
+      key: unb64(privateKey || keyPair.privateKey),
+      type: "pkcs8",
+      format: "der",
+    });
+    this.publicKey = publicKey || keyPair.publicKey;
+    this.keys = new Map();
+    this.sendSequence = 0;
+    this.receivedSequences = new Map();
+  }
+
+  pair(peerId, peerPublicKey, pairingToken) {
+    if (!peerId || !peerPublicKey || !pairingToken)
+      throw new Error("Incomplete peer key material");
+    this.keys.set(
+      peerId,
+      deriveKey(
+        this.privateKey,
+        importPublicKey(peerPublicKey),
+        this.sessionId,
+        pairingToken,
+      ),
+    );
+  }
+
+  encrypt(peerId, message) {
+    const key = this.keys.get(peerId);
+    if (!key) throw new Error(`No encryption key for peer: ${peerId}`);
+    const sequence = ++this.sendSequence;
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(aad(this.sessionId, this.localPeerId, sequence));
+    const ciphertext = Buffer.concat([
+      cipher.update(JSON.stringify(message), "utf8"),
+      cipher.final(),
+    ]);
+    return {
+      v: 1,
+      sessionId: this.sessionId,
+      senderId: this.localPeerId,
+      sequence,
+      nonce: b64(nonce),
+      ciphertext: b64(ciphertext),
+      tag: b64(cipher.getAuthTag()),
+    };
+  }
+
+  decrypt(envelope) {
+    if (envelope?.v !== 1 || envelope.sessionId !== this.sessionId) {
+      throw new Error("Invalid encrypted Remote Session envelope");
+    }
+    const key = this.keys.get(envelope.senderId);
+    if (!key)
+      throw new Error(`No encryption key for peer: ${envelope.senderId}`);
+    const previous = this.receivedSequences.get(envelope.senderId) || 0;
+    if (
+      !Number.isSafeInteger(envelope.sequence) ||
+      envelope.sequence <= previous
+    ) {
+      throw new Error(
+        "Remote Session replay or out-of-order envelope rejected",
+      );
+    }
+    try {
+      const decipher = createDecipheriv(
+        "aes-256-gcm",
+        key,
+        unb64(envelope.nonce),
+      );
+      decipher.setAAD(
+        aad(this.sessionId, envelope.senderId, envelope.sequence),
+      );
+      decipher.setAuthTag(unb64(envelope.tag));
+      const plaintext = Buffer.concat([
+        decipher.update(unb64(envelope.ciphertext)),
+        decipher.final(),
+      ]);
+      const message = JSON.parse(plaintext.toString("utf8"));
+      this.receivedSequences.set(envelope.senderId, envelope.sequence);
+      return message;
+    } catch (error) {
+      throw new Error(
+        `Remote Session envelope authentication failed: ${error.message}`,
+      );
+    }
+  }
+}

package/src/harness/remote-session-push-fcm.js

@@ -0,0 +1,254 @@
+// Remote Session vendor push — Firebase Cloud Messaging (HTTP v1) sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender`
+// contract that delivers approval wake-ups to Android devices through FCM's
+// current HTTP v1 API (the legacy server-key API is retired). Auth uses a
+// Google service account: a short-lived OAuth2 access token minted by signing a
+// JWT (RS256) with the service account private key and exchanging it at
+// oauth2.googleapis.com — no long-lived server key on disk.
+//
+// Everything is injectable (fetch, clock, signer, fs) so the whole chain is
+// unit-testable with a generated keypair and a fake transport — no real
+// credentials or network. The payload carries NO session content, only the
+// routing shape (aligns with the audit log's privacy-first stance).
+
+import { createSign } from "node:crypto";
+import fs from "node:fs";
+
+const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+const DEFAULT_TOKEN_URI = "https://oauth2.googleapis.com/token";
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+const ACCESS_TOKEN_SKEW_MS = 60_000; // refresh a minute before real expiry
+const ASSERTION_TTL_SEC = 3600;
+
+function base64url(input) {
+  return Buffer.from(input)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+function dropUndefined(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * A device token the vendor reports as no longer valid (uninstalled app, token
+ * rotated). The caller should prune it so it is never retried.
+ */
+export class PushTokenUnregisteredError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PushTokenUnregisteredError";
+    this.code = "PUSH_TOKEN_UNREGISTERED";
+  }
+}
+
+/** Mints + caches OAuth2 access tokens from a Google service account. */
+export class GoogleServiceAccountTokenProvider {
+  constructor(serviceAccount = {}, options = {}) {
+    if (!serviceAccount.client_email || !serviceAccount.private_key) {
+      throw new Error(
+        "Service account must include client_email and private_key",
+      );
+    }
+    this.clientEmail = serviceAccount.client_email;
+    this.privateKey = serviceAccount.private_key;
+    this.tokenUri = serviceAccount.token_uri || DEFAULT_TOKEN_URI;
+    this.scope = options.scope || FCM_SCOPE;
+    this.now = options.now || Date.now;
+    this.fetch = options.fetch || globalThis.fetch;
+    // RS256 = RSA PKCS#1 v1.5 over SHA-256. Injectable for tests.
+    this.sign =
+      options.sign ||
+      ((signingInput, key) =>
+        createSign("RSA-SHA256").update(signingInput).sign(key));
+    this._cached = null; // { token, expiresAt }
+  }
+
+  async getAccessToken() {
+    const now = this.now();
+    if (this._cached && this._cached.expiresAt - ACCESS_TOKEN_SKEW_MS > now) {
+      return this._cached.token;
+    }
+    const assertion = this._buildAssertion(now);
+    const body = new URLSearchParams({
+      grant_type: JWT_BEARER_GRANT,
+      assertion,
+    });
+    const res = await this.fetch(this.tokenUri, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `OAuth token request failed (${res.status}): ${await safeText(res)}`,
+      );
+    }
+    const json = await res.json();
+    if (!json.access_token) {
+      throw new Error("OAuth token response missing access_token");
+    }
+    const expiresInMs = (Number(json.expires_in) || ASSERTION_TTL_SEC) * 1000;
+    this._cached = { token: json.access_token, expiresAt: now + expiresInMs };
+    return this._cached.token;
+  }
+
+  _buildAssertion(now) {
+    const iat = Math.floor(now / 1000);
+    const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+    const payload = base64url(
+      JSON.stringify({
+        iss: this.clientEmail,
+        scope: this.scope,
+        aud: this.tokenUri,
+        iat,
+        exp: iat + ASSERTION_TTL_SEC,
+      }),
+    );
+    const signingInput = `${header}.${payload}`;
+    const signature = base64url(this.sign(signingInput, this.privateKey));
+    return `${signingInput}.${signature}`;
+  }
+}
+
+/** Sends one high-priority data+notification message via FCM HTTP v1. */
+export class FcmV1PushSender {
+  constructor(options = {}) {
+    if (!options.projectId) {
+      throw new Error("FcmV1PushSender requires projectId");
+    }
+    if (!options.tokenProvider) {
+      throw new Error("FcmV1PushSender requires a tokenProvider");
+    }
+    this.projectId = options.projectId;
+    this.tokenProvider = options.tokenProvider;
+    this.fetch = options.fetch || globalThis.fetch;
+    this.endpoint =
+      options.endpoint ||
+      `https://fcm.googleapis.com/v1/projects/${options.projectId}/messages:send`;
+  }
+
+  /** Bound function matching the dispatcher's `sender` contract. */
+  get handler() {
+    return (payload) => this.send(payload);
+  }
+
+  async send({ token, notification, sessionId, clientId } = {}) {
+    if (!token) throw new Error("FCM send requires a device token");
+    const accessToken = await this.tokenProvider.getAccessToken();
+    const message = {
+      message: dropUndefined({
+        token,
+        notification: notification
+          ? dropUndefined({
+              title: notification.title,
+              body: notification.body,
+            })
+          : undefined,
+        // Data-only fields let the app route the wake-up; no session content.
+        data: dropUndefined({
+          type: "remote-session.approval-request",
+          sessionId: sessionId != null ? String(sessionId) : undefined,
+          clientId: clientId != null ? String(clientId) : undefined,
+        }),
+        android: { priority: "high" },
+        apns: { headers: { "apns-priority": "10" } },
+      }),
+    };
+    const res = await this.fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(message),
+    });
+    if (res.ok) {
+      const json = await res.json().catch(() => ({}));
+      return { id: json.name || null };
+    }
+    const text = await safeText(res);
+    // A retired/uninstalled token surfaces as HTTP 404 or an UNREGISTERED /
+    // NOT_FOUND error status — prune it rather than retry forever.
+    if (res.status === 404 || /UNREGISTERED|NOT_FOUND/i.test(text)) {
+      throw new PushTokenUnregisteredError(`FCM token unregistered: ${text}`);
+    }
+    throw new Error(`FCM send failed (${res.status}): ${text}`);
+  }
+}
+
+function loadServiceAccount(env, options) {
+  if (options.serviceAccount) return options.serviceAccount;
+  const inline = env.CHAINLESSCHAIN_REMOTE_SESSION_FCM_SERVICE_ACCOUNT_JSON;
+  if (inline) {
+    try {
+      return JSON.parse(inline);
+    } catch {
+      return null;
+    }
+  }
+  const filePath = env.CHAINLESSCHAIN_REMOTE_SESSION_FCM_SERVICE_ACCOUNT;
+  if (filePath) {
+    const fsMod = options.fs || fs;
+    try {
+      return JSON.parse(fsMod.readFileSync(filePath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a concrete push `sender` from env, or null when unconfigured / for a
+ * provider that is not yet implemented. Returns the bound sender function the
+ * RemoteSessionPushDispatcher expects.
+ *
+ * FCM env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER      = "fcm" (default)
+ *   CHAINLESSCHAIN_REMOTE_SESSION_FCM_SERVICE_ACCOUNT      (path to JSON), or
+ *   CHAINLESSCHAIN_REMOTE_SESSION_FCM_SERVICE_ACCOUNT_JSON (inline JSON)
+ *   CHAINLESSCHAIN_REMOTE_SESSION_FCM_PROJECT_ID     (optional; else service
+ *                                                     account project_id)
+ */
+export function createRemoteSessionPushSender(env = {}, options = {}) {
+  const provider = (
+    env.CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER || "fcm"
+  ).toLowerCase();
+  if (provider !== "fcm") {
+    // APNs / HMS / Xiaomi / OPPO senders are not implemented yet; the injection
+    // seam means they can be added without touching the dispatcher.
+    return null;
+  }
+  const serviceAccount = loadServiceAccount(env, options);
+  if (!serviceAccount) return null;
+  const projectId =
+    env.CHAINLESSCHAIN_REMOTE_SESSION_FCM_PROJECT_ID ||
+    serviceAccount.project_id;
+  if (!projectId) return null;
+  let tokenProvider;
+  try {
+    tokenProvider =
+      options.tokenProvider ||
+      new GoogleServiceAccountTokenProvider(serviceAccount, options);
+  } catch {
+    return null; // Malformed service account — stay disabled rather than crash.
+  }
+  const sender = new FcmV1PushSender({ projectId, tokenProvider, ...options });
+  return sender.handler;
+}

package/src/harness/remote-session-push.js

@@ -0,0 +1,104 @@
+// Remote Session push notifications (vendor push).
+//
+// Wakes a paired device for time-sensitive events (an approval request) even
+// when its relay WebSocket is suspended — the case a foreground-only local
+// notification can't cover. The actual delivery (FCM / APNs / Xiaomi / Huawei /
+// OPPO) is a pluggable `sender` injected by the host, so this layer stays
+// credential-free and fully unit-testable; with no sender it degrades to a
+// recorded no-op. Payloads carry NO session content, only the shape needed to
+// route the wake-up (aligns with the audit log's privacy-first stance).
+
+const DEFAULT_DEDUPE_WINDOW_MS = 30_000;
+
+/**
+ * True for host events that should wake a backgrounded device. Approval /
+ * permission requests qualify; their `resolved` counterparts do not.
+ */
+export function isApprovalRequestEvent(type) {
+  const value = String(type || "");
+  return /approval|permission/i.test(value) && !/resolv/i.test(value);
+}
+
+export class RemoteSessionPushDispatcher {
+  constructor(options = {}) {
+    this.now = options.now || Date.now;
+    this.sender = typeof options.sender === "function" ? options.sender : null;
+    this.provider = options.provider || null;
+    this.dedupeWindowMs = options.dedupeWindowMs || DEFAULT_DEDUPE_WINDOW_MS;
+    this.recent = new Map();
+    this.stats = { sent: 0, skipped: 0, failed: 0 };
+  }
+
+  get enabled() {
+    return Boolean(this.sender);
+  }
+
+  /**
+   * Deliver one wake-up. Never throws — a push is best-effort; the relay event
+   * and in-app notification remain the primary channels. Returns a structured
+   * outcome the caller can audit.
+   */
+  async dispatch({
+    token,
+    provider,
+    sessionId,
+    clientId,
+    notification,
+    dedupeKey,
+  } = {}) {
+    if (!token) return this._skip("no-token");
+    if (!this.sender) return this._skip("no-sender");
+    if (dedupeKey && this._isDuplicate(clientId, dedupeKey)) {
+      return this._skip("deduplicated");
+    }
+    try {
+      const result = await this.sender({
+        token,
+        provider: provider || this.provider,
+        sessionId,
+        clientId,
+        notification,
+      });
+      this.stats.sent += 1;
+      return { status: "sent", provider: provider || this.provider, result };
+    } catch (error) {
+      this.stats.failed += 1;
+      // Propagate a typed code (e.g. PUSH_TOKEN_UNREGISTERED) so the caller can
+      // prune a dead device token instead of retrying it forever.
+      return {
+        status: "failed",
+        error: error.message,
+        code: error.code || null,
+      };
+    }
+  }
+
+  _skip(reason) {
+    this.stats.skipped += 1;
+    return { status: "skipped", reason };
+  }
+
+  _isDuplicate(clientId, dedupeKey) {
+    const key = `${clientId || ""}:${dedupeKey}`;
+    const now = this.now();
+    const last = this.recent.get(key);
+    if (last != null && now - last < this.dedupeWindowMs) return true;
+    this.recent.set(key, now);
+    this._gc(now);
+    return false;
+  }
+
+  _gc(now) {
+    if (this.recent.size < 500) return;
+    for (const [key, ts] of this.recent) {
+      if (now - ts >= this.dedupeWindowMs) this.recent.delete(key);
+    }
+  }
+
+  static fromEnv(env = {}, options = {}) {
+    return new RemoteSessionPushDispatcher({
+      provider: env.CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER || null,
+      ...options,
+    });
+  }
+}