pulse-updates 1.1.0 → 1.2.0

package/src/config.ts

@@ -20,6 +20,8 @@
  *     config costs a 304 with no body.
  */
 
+import nacl from 'tweetnacl';
+
 export type ConfigValue = boolean | number | string | null | object;
 
 /**
@@ -35,6 +37,16 @@ export interface ConfigExperiment {
   variant: string;
 }
 
+export interface ConfigSignature {
+  alg: string;
+  keyId: string;
+  sig: string;
+  /** Exact canonical response bytes covered by the signature, when supplied by PulseServer. */
+  canonical?: string;
+}
+
+export type ConfigSignatureStatus = 'not-configured' | 'verified' | 'cached-verified' | 'unsigned' | 'invalid';
+
 export interface ConfigStorage {
   getString(key: string): string | null | undefined;
   set(key: string, value: string): void;
@@ -71,6 +83,8 @@ export interface ConfigOptions {
   defaults?: Record<string, ConfigValue>;
   /** Persistence for the last good payload. Without it the cache is memory-only. */
   storage?: ConfigStorage;
+  /** App-scoped key for multi-app/white-label hosts. */
+  storageKey?: string;
   /** Read fresh on every request: the country or plan can change between launches. */
   getContext?: () => ConfigContext;
   /** Foreground poll interval. 0 disables polling (launch + resume still fetch). */
@@ -101,6 +115,14 @@ export interface ConfigOptions {
   reportExposure?: boolean;
   /** Network timeout per request. */
   timeoutMs?: number;
+  /** Ed25519 public key, as raw 32-byte base64. Enables built-in verification. */
+  signingPublicKey?: string;
+  /** Optional key-id pin. A response signed by another key is rejected. */
+  signingKeyId?: string;
+  /** Reject unsigned/unverifiable payloads and keep the last good snapshot. */
+  requireSignature?: boolean;
+  /** Custom verifier for hosts that keep keys in a secure native module. */
+  verifySignature?: (canonicalPayload: string, signature: ConfigSignature) => boolean | Promise<boolean>;
   onError?: (error: unknown) => void;
 }
 
@@ -110,6 +132,8 @@ interface CachedPayload {
   experiments?: ConfigExperiment[];
   etag: string | null;
   fetchedAt: number;
+  signatureVerified?: boolean;
+  signatureKeyId?: string | null;
 }
 
 /**
@@ -148,11 +172,14 @@ let fetchedAt = 0;
  */
 let verifiedAt = 0;
 let source: 'defaults' | 'cache' | 'remote' = 'defaults';
+let signatureStatus: ConfigSignatureStatus = 'not-configured';
+let signatureKeyId: string | null = null;
 let pending: ConfigSnapshot | null = null;
 /** The arm set already reported this session, so a poll does not re-report it. */
 let reportedExposure: string | null = null;
 let inFlight: Promise<boolean> | null = null;
 let pollTimer: ReturnType<typeof setInterval> | null = null;
+let configGeneration = 0;
 const listeners = new Set<(values: Record<string, ConfigValue>) => void>();
 
 /**
@@ -161,17 +188,26 @@ const listeners = new Set<(values: Record<string, ConfigValue>) => void>();
  * while the network call is in flight.
  */
 export function configureConfig(opts: ConfigOptions): void {
+  // A host can switch app/tenant without restarting the JS runtime. Nothing from the
+  // previous app — values, ETag, pending activation or an eventual network response —
+  // may cross that boundary.
+  configGeneration += 1;
+  stopPolling();
   options = opts;
   defaults = { ...(opts.defaults ?? {}) };
+  values = {};
+  experiments = [];
+  etag = null;
+  fetchedAt = 0;
+  verifiedAt = 0;
+  source = 'defaults';
+  signatureStatus = 'not-configured';
+  signatureKeyId = null;
+  pending = null;
+  reportedExposure = null;
+  inFlight = null;
 
-  const cached = readCache(opts.storage);
-  if (cached) {
-    values = cached.values;
-    experiments = cached.experiments ?? [];
-    etag = cached.etag;
-    fetchedAt = cached.fetchedAt;
-    source = 'cache';
-  }
+  applyCachedPayload(readCache(opts.storage, opts.storageKey), opts);
 }
 
 /** Merge more defaults after configure (a late-loading module registering its own). */
@@ -196,7 +232,8 @@ export async function fetchConfig(): Promise<boolean> {
     return false;
   }
 
-  inFlight = (async () => {
+  const requestGeneration = configGeneration;
+  const request = (async () => {
     const opts = options!;
     const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
     const timer = controller
@@ -210,6 +247,8 @@ export async function fetchConfig(): Promise<boolean> {
         signal: controller?.signal,
       });
 
+      if (requestGeneration !== configGeneration || options !== opts) return false;
+
       // Nothing changed — which is a positive answer about freshness, not a
       // non-event: the values we hold are the ones the server would send.
       if (response.status === 304) {
@@ -218,8 +257,11 @@ export async function fetchConfig(): Promise<boolean> {
       }
       if (!response.ok) throw new Error(`Pulse config HTTP ${response.status}`);
 
-      const payload = await response.json();
-      const nextValues = payload?.values;
+      const payload: unknown = await response.json();
+      await verifyConfigPayload(payload, opts, requestGeneration);
+      if (requestGeneration !== configGeneration || options !== opts) return false;
+      const payloadObject = payload as Record<string, unknown>;
+      const nextValues = payloadObject.values;
       // A payload without a values object is a broken response, not "no keys": adopting
       // it would blank every flag at once.
       if (!nextValues || typeof nextValues !== 'object' || Array.isArray(nextValues)) {
@@ -232,7 +274,7 @@ export async function fetchConfig(): Promise<boolean> {
 
       const snapshot: ConfigSnapshot = {
         values: nextValues as Record<string, ConfigValue>,
-        experiments: parseExperiments(payload?.experiments),
+        experiments: parseExperiments(payloadObject.experiments),
       };
 
       if (opts.activateOnFetch === false) {
@@ -248,11 +290,12 @@ export async function fetchConfig(): Promise<boolean> {
       return false;
     } finally {
       if (timer) clearTimeout(timer);
-      inFlight = null;
+      if (requestGeneration === configGeneration) inFlight = null;
     }
   })();
 
-  return inFlight;
+  inFlight = request;
+  return request;
 }
 
 /**
@@ -305,7 +348,14 @@ function applySnapshot(next: ConfigSnapshot, opts: ConfigOptions): boolean {
   values = next.values;
   experiments = next.experiments;
   source = 'remote';
-  writeCache(opts.storage, { values, experiments, etag, fetchedAt });
+  writeCache(opts.storage, {
+    values,
+    experiments,
+    etag,
+    fetchedAt,
+    signatureVerified: signatureStatus === 'verified',
+    signatureKeyId,
+  }, opts.storageKey);
 
   // Reported on apply, never on fetch: with activateOnFetch false a payload can sit
   // unapplied for the rest of a session, and an arm the app is not actually serving
@@ -360,10 +410,137 @@ async function reportExposure(opts: ConfigOptions): Promise<void> {
     });
   } catch {
     // A device that cannot report its arm still has the right arm.
-    reportedExposure = signature;
+    if (options === opts) reportedExposure = signature;
   }
 }
 
+/**
+ * Verifies the exact unsigned JSON object the server signs. A configured verifier
+ * also rejects a bad optional signature: accepting a payload that claims to be
+ * signed but is not valid would make signature stripping safer than tampering.
+ */
+async function verifyConfigPayload(
+  payload: unknown,
+  opts: ConfigOptions,
+  requestGeneration: number,
+): Promise<void> {
+  const setSignatureState = (status: ConfigSignatureStatus, keyId: string | null = null) => {
+    if (requestGeneration !== configGeneration || options !== opts) return;
+    signatureStatus = status;
+    signatureKeyId = keyId;
+  };
+  const verificationConfigured = Boolean(
+    opts.requireSignature || opts.signingPublicKey || opts.signingKeyId || opts.verifySignature,
+  );
+  if (!verificationConfigured) {
+    setSignatureState('not-configured');
+    return;
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    setSignatureState('invalid');
+    throw new Error('Pulse config: malformed signed payload');
+  }
+
+  const record = payload as Record<string, unknown>;
+  const rawSignature = record.signature;
+  if (!isConfigSignature(rawSignature)) {
+    setSignatureState('unsigned');
+    if (opts.requireSignature) throw new Error('Pulse config: signature required but missing');
+    return;
+  }
+
+  setSignatureState('not-configured', rawSignature.keyId);
+  if (rawSignature.alg.toLowerCase() !== 'ed25519' ||
+      (opts.signingKeyId && rawSignature.keyId !== opts.signingKeyId)) {
+    setSignatureState('invalid', rawSignature.keyId);
+    throw new Error('Pulse config: signature algorithm or key id is not trusted');
+  }
+
+  const unsigned = { ...record };
+  delete unsigned.signature;
+  const locallyCanonical = canonicalizeConfigJson(unsigned);
+  let canonical = locallyCanonical;
+  if (rawSignature.canonical) {
+    try {
+      // Compare semantic JSON after parsing, then verify the server's exact bytes.
+      // This preserves tamper detection while avoiding 1.0/1 formatting drift
+      // between System.Text.Json and JavaScript.
+      if (canonicalizeConfigJson(JSON.parse(rawSignature.canonical)) !== locallyCanonical) {
+        throw new Error('canonical payload mismatch');
+      }
+      canonical = rawSignature.canonical;
+    } catch {
+      setSignatureState('invalid', rawSignature.keyId);
+      throw new Error('Pulse config: signed canonical payload does not match response');
+    }
+  }
+  let valid = false;
+  if (opts.verifySignature) {
+    valid = await opts.verifySignature(canonical, rawSignature);
+  } else if (opts.signingPublicKey) {
+    try {
+      valid = nacl.sign.detached.verify(
+        utf8Bytes(canonical),
+        decodeBase64(rawSignature.sig),
+        decodeBase64(opts.signingPublicKey),
+      );
+    } catch {
+      valid = false;
+    }
+  } else if (opts.requireSignature) {
+    setSignatureState('invalid', rawSignature.keyId);
+    throw new Error('Pulse config: signature required but no verifier or public key is configured');
+  } else {
+    setSignatureState('not-configured', rawSignature.keyId);
+    return;
+  }
+
+  if (!valid) {
+    setSignatureState('invalid', rawSignature.keyId);
+    throw new Error('Pulse config: signature verification failed');
+  }
+  setSignatureState('verified', rawSignature.keyId);
+}
+
+function isConfigSignature(value: unknown): value is ConfigSignature {
+  if (!value || typeof value !== 'object') return false;
+  const signature = value as Record<string, unknown>;
+  return typeof signature.alg === 'string' &&
+    typeof signature.keyId === 'string' &&
+    typeof signature.sig === 'string' &&
+    (signature.canonical === undefined || typeof signature.canonical === 'string');
+}
+
+/** Same recursive ordinal-key JSON form used by PulseServer's ManifestSigner. */
+export function canonicalizeConfigJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalizeConfigJson).join(',')}]`;
+  return `{${Object.keys(value as Record<string, unknown>)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalizeConfigJson((value as Record<string, unknown>)[key])}`)
+    .join(',')}}`;
+}
+
+function decodeBase64(value: string): Uint8Array {
+  const atobLike = (globalThis as { atob?: (encoded: string) => string }).atob;
+  if (atobLike) {
+    const decoded = atobLike(value);
+    return Uint8Array.from(decoded, (char) => char.charCodeAt(0));
+  }
+  // Node/older React Native hosts commonly expose Buffer even when atob is absent.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const BufferCtor = require('buffer').Buffer as { from: (input: string, encoding: string) => Uint8Array };
+  return Uint8Array.from(BufferCtor.from(value, 'base64'));
+}
+
+function utf8Bytes(value: string): Uint8Array {
+  const Encoder = (globalThis as { TextEncoder?: new () => { encode: (input: string) => Uint8Array } }).TextEncoder;
+  if (Encoder) return new Encoder().encode(value);
+  // encodeURIComponent is available in every RN JS runtime supported by this package.
+  const encoded = unescape(encodeURIComponent(value));
+  return Uint8Array.from(encoded, (char) => char.charCodeAt(0));
+}
+
 /**
  * The arms as the server sent them, keeping only entries that name both halves.
  *
@@ -507,17 +684,30 @@ export function getConfigInfo(): {
   verifiedAt: number;
   etag: string | null;
   keyCount: number;
+  signatureStatus: ConfigSignatureStatus;
+  signatureKeyId: string | null;
 } {
-  return { source, fetchedAt, verifiedAt, etag, keyCount: Object.keys(getAllConfig()).length };
+  return {
+    source,
+    fetchedAt,
+    verifiedAt,
+    etag,
+    keyCount: Object.keys(getAllConfig()).length,
+    signatureStatus,
+    signatureKeyId,
+  };
 }
 
 /** Test seam: drops every piece of module state. */
 export function resetConfigForTests(): void {
+  configGeneration += 1;
   options = null;
   defaults = {};
   verifiedAt = 0;
   values = {};
   experiments = [];
+  signatureStatus = 'not-configured';
+  signatureKeyId = null;
   etag = null;
   fetchedAt = 0;
   source = 'defaults';
@@ -550,10 +740,19 @@ function buildHeaders(opts: ConfigOptions, currentEtag: string | null): Record<s
   return headers;
 }
 
-function readCache(storage?: ConfigStorage): CachedPayload | null {
+function readCache(storage?: ConfigStorage, key?: string): CachedPayload | null {
   if (!storage) return null;
   try {
-    const raw = storage.getString(STORAGE_KEY);
+    const raw = storage.getString(key?.trim() || STORAGE_KEY);
+    return parseCachedPayload(raw);
+  } catch {
+    // A corrupt cache is not worth a crash at boot: fall back to defaults.
+    return null;
+  }
+}
+
+function parseCachedPayload(raw: string | null | undefined): CachedPayload | null {
+  try {
     if (!raw) return null;
     const parsed = JSON.parse(raw) as CachedPayload;
     if (!parsed || typeof parsed !== 'object' || !parsed.values) return null;
@@ -564,10 +763,24 @@ function readCache(storage?: ConfigStorage): CachedPayload | null {
   }
 }
 
-function writeCache(storage: ConfigStorage | undefined, payload: CachedPayload): void {
+function applyCachedPayload(cached: CachedPayload | null, opts: ConfigOptions): void {
+  if (!cached || (opts.requireSignature && cached.signatureVerified !== true)) return;
+  values = cached.values;
+  experiments = cached.experiments ?? [];
+  etag = cached.etag;
+  fetchedAt = cached.fetchedAt;
+  source = 'cache';
+  if (cached.signatureVerified) {
+    signatureStatus = 'cached-verified';
+    signatureKeyId = cached.signatureKeyId ?? null;
+  }
+  notify();
+}
+
+function writeCache(storage: ConfigStorage | undefined, payload: CachedPayload, key?: string): void {
   if (!storage) return;
   try {
-    storage.set(STORAGE_KEY, JSON.stringify(payload));
+    void storage.set(key?.trim() || STORAGE_KEY, JSON.stringify(payload));
   } catch {
     // Persistence is an optimisation; failing to write must not fail the fetch.
   }

package/src/decisions.ts

@@ -0,0 +1,179 @@
+export type DecisionChannel = 'in_app' | 'encore' | 'replio' | 'email' | 'push' | 'sms' | 'whatsapp' | 'webhook';
+export type DecisionOutcome = 'pending' | 'delivered' | 'dismissed' | 'accepted' | 'converted' | 'failed';
+
+export interface DecisionContext {
+  userId?: string;
+  deviceId?: string;
+  platform?: string;
+  appVersion?: string;
+  country?: string;
+  language?: string;
+  osVersion?: string;
+  attributes?: Record<string, string>;
+}
+
+export interface DecisionAction { kind: string; [key: string]: unknown }
+
+export interface PulseDecision {
+  decisionId: string;
+  replayed: boolean;
+  execute: boolean;
+  mode: 'shadow' | 'live' | string;
+  verdict: string;
+  reasonCode: string;
+  policyKey?: string | null;
+  policyVersion?: number | null;
+  action?: DecisionAction | null;
+}
+
+export interface DecisionHandlerResult {
+  outcome?: DecisionOutcome;
+  metadata?: Record<string, unknown>;
+}
+
+export type DecisionHandler = (
+  action: DecisionAction,
+  decision: PulseDecision,
+) => void | DecisionHandlerResult | Promise<void | DecisionHandlerResult>;
+
+export interface PulseDecisionClientOptions {
+  apiUrl: string;
+  appSlug: string;
+  getContext: () => DecisionContext | Promise<DecisionContext>;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  /** Safe default. User-facing execution needs an explicit per-app opt-in. */
+  executionMode?: 'shadow-only' | 'allow-live';
+  handlers?: Record<string, DecisionHandler>;
+  onError?: (error: unknown) => void;
+}
+
+export interface DecideOptions {
+  channel?: DecisionChannel;
+  idempotencyKey?: string;
+  attributes?: Record<string, string>;
+}
+
+export interface PulseDecisionClient {
+  decide(trigger: string, options?: DecideOptions): Promise<PulseDecision | null>;
+  reportOutcome(decisionId: string, outcome: DecisionOutcome, metadata?: Record<string, unknown>): Promise<boolean>;
+}
+
+/** Generic decision protocol. Product-specific action handlers remain in each app. */
+export function createPulseDecisionClient(options: PulseDecisionClientOptions): PulseDecisionClient {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const base = options.apiUrl.replace(/\/+$/, '');
+  const slug = encodeURIComponent(options.appSlug);
+  const timeoutMs = Math.max(250, options.timeoutMs ?? 3_000);
+  const executionMode = options.executionMode ?? 'shadow-only';
+
+  const reportOutcome = async (
+    decisionId: string,
+    outcome: DecisionOutcome,
+    metadata?: Record<string, unknown>,
+  ): Promise<boolean> => {
+    try {
+      const response = await timedFetch(fetcher,
+        `${base}/pulse/decisions/${slug}/${encodeURIComponent(decisionId)}/outcome`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ outcome, ...(metadata ? { metadata } : {}) }),
+        }, timeoutMs);
+      return response.ok;
+    } catch (error) {
+      options.onError?.(error);
+      return false;
+    }
+  };
+
+  const decide = async (trigger: string, request: DecideOptions = {}): Promise<PulseDecision | null> => {
+    try {
+      const context = await options.getContext();
+      const response = await timedFetch(fetcher, `${base}/pulse/decisions/${slug}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          ...context,
+          attributes: { ...(context.attributes ?? {}), ...(request.attributes ?? {}) },
+          trigger,
+          channel: request.channel ?? 'in_app',
+          idempotencyKey: request.idempotencyKey ?? randomKey(),
+        }),
+      }, timeoutMs);
+      if (!response.ok) throw new Error(`Pulse decision HTTP ${response.status}`);
+
+      const decision = parseDecision(await response.json());
+      if (!decision.execute) return decision;
+      if (executionMode !== 'allow-live') {
+        void reportOutcome(decision.decisionId, 'failed', { reason: 'client_executor_not_armed' });
+        return decision;
+      }
+
+      const action = decision.action;
+      const handler = action?.kind ? options.handlers?.[action.kind] : undefined;
+      if (!action || !handler) {
+        void reportOutcome(decision.decisionId, 'failed', {
+          reason: 'unknown_action_kind',
+          kind: action?.kind ?? null,
+        });
+        return decision;
+      }
+
+      try {
+        const result = await handler(action, decision);
+        void reportOutcome(decision.decisionId, result?.outcome ?? 'accepted', result?.metadata);
+      } catch (error) {
+        options.onError?.(error);
+        void reportOutcome(decision.decisionId, 'failed', { reason: 'handler_failed' });
+      }
+      return decision;
+    } catch (error) {
+      options.onError?.(error);
+      return null;
+    }
+  };
+
+  return { decide, reportOutcome };
+}
+
+function parseDecision(raw: unknown): PulseDecision {
+  if (!raw || typeof raw !== 'object') throw new Error('Malformed Pulse decision');
+  const value = raw as Record<string, unknown>;
+  if (typeof value.decisionId !== 'string' || typeof value.execute !== 'boolean' ||
+      typeof value.mode !== 'string' || typeof value.verdict !== 'string' ||
+      typeof value.reasonCode !== 'string') throw new Error('Malformed Pulse decision');
+  const action = value.action;
+  if (action != null && (typeof action !== 'object' ||
+      typeof (action as Record<string, unknown>).kind !== 'string')) {
+    throw new Error('Malformed Pulse action');
+  }
+  return {
+    decisionId: value.decisionId,
+    replayed: value.replayed === true,
+    execute: value.execute,
+    mode: value.mode,
+    verdict: value.verdict,
+    reasonCode: value.reasonCode,
+    policyKey: typeof value.policyKey === 'string' ? value.policyKey : null,
+    policyVersion: typeof value.policyVersion === 'number' ? value.policyVersion : null,
+    action: (action as DecisionAction | null | undefined) ?? null,
+  };
+}
+
+async function timedFetch(
+  fetcher: typeof globalThis.fetch,
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  try { return await fetcher(url, { ...init, signal: controller?.signal }); }
+  finally { if (timer) clearTimeout(timer); }
+}
+
+function randomKey(): string {
+  const cryptoLike = globalThis.crypto as { randomUUID?: () => string } | undefined;
+  if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();
+  return `moment-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
+}

package/src/index.ts

@@ -5,3 +5,4 @@ export { initializeAssetResolver, updateLocalAssets } from './assetResolver';
 export * from './config';
 export * from './track';
 export * from './init';
+export * from './decisions';