pulse-updates 1.1.1 → 1.2.0

package/scripts/publish.mjs

@@ -1086,10 +1086,19 @@ async function publish(options) {
  */
 async function registerCapabilities(options) {
   const config = loadConfig(options);
-  const bundlePath = options['bundle'] || options['embedded-bundle'];
-  if (!bundlePath) {
-    throw new Error('Provide --bundle <path to the embedded JS bundle> (the bundle built into the app binary).');
+  if (!config.platform || !['ios', 'android'].includes(config.platform)) {
+    throw new Error('Platform is required. Pass --platform ios or --platform android.');
   }
+  if (!config.runtimeVersion) {
+    throw new Error('Runtime version is required. Pass --runtime-version or configure it in the native project.');
+  }
+  if (!config.apiUrl) {
+    throw new Error('API URL is required. Set --api-url, PULSE_API_URL, or the native PulseUpdatesURL.');
+  }
+  if (!config.apiKey) {
+    throw new Error('API key is required. Set --api-key, PULSE_API_KEY, or pulse.config.json.');
+  }
+  const bundlePath = resolveCapabilitiesBundle(options, config);
   const nativeModules = extractNativeModules(bundlePath);
   log(`Registering ${nativeModules.length} native module(s) for ${config.runtimeVersion}/${config.platform}`);
   const res = await fetch(`${config.apiUrl}/api/capabilities`, {
@@ -1107,6 +1116,27 @@ async function registerCapabilities(options) {
   logSuccess(`Capabilities registered (${nativeModules.length} native modules)`);
 }
 
+/**
+ * Resolve the embedded bundle used for the capability snapshot. A release pipeline
+ * can pass the exact bundle it just put in the binary; local and CI adoption can use
+ * the zero-config path, which builds the same production Metro graph first.
+ */
+export function resolveCapabilitiesBundle(options, config, bundleFactory = createBundle) {
+  const explicit = options.bundle || options['embedded-bundle'];
+  if (explicit) {
+    const resolved = path.resolve(explicit);
+    if (!fs.existsSync(resolved)) throw new Error(`Capability bundle not found: ${resolved}`);
+    return resolved;
+  }
+
+  logStep('1/2', `Building the ${config.platform} production bundle for capability discovery...`);
+  return bundleFactory(
+    config.platform,
+    path.resolve(config.bundleDir || './dist'),
+    config.entryFile || 'index.ts'
+  );
+}
+
 
 /**
  * The experiments an app is running, and how their split is holding.
@@ -1293,6 +1323,34 @@ ${colors.cyan}App${colors.reset} (PUBLIC — set in Info.plist / AndroidManifest
 `);
 }
 
+/** Generate small app-local contracts from a reviewable schema file. */
+export function generateContracts(options) {
+  const schemaPath = path.resolve(options.schema || 'pulse.schema.json');
+  const outputPath = path.resolve(options.output || 'src/pulse.generated.ts');
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Schema not found: ${schemaPath}. Create pulse.schema.json or pass --schema.`);
+  }
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  const scalar = (value) => ({ boolean: 'boolean', number: 'number', string: 'string', json: 'unknown' }[value] || 'unknown');
+  const objectType = (shape = {}) => `{ ${Object.entries(shape).map(([key, value]) => `${JSON.stringify(key)}?: ${scalar(value)}`).join('; ')} }`;
+  const configEntries = Object.entries(schema.config || {});
+  const eventEntries = Object.entries(schema.events || {});
+  const actionEntries = Object.entries(schema.actions || {});
+  const output = `/* Generated by pulse-updates generate. Do not edit by hand. */\n` +
+    `import type { TrackedEventInput, DecisionAction } from 'pulse-updates';\n\n` +
+    `export interface PulseConfigSchema {\n${configEntries.map(([key, value]) => `  ${JSON.stringify(key)}: ${scalar(value)};`).join('\n')}\n}\n\n` +
+    `export interface PulseEventSchema {\n${eventEntries.map(([key, value]) => `  ${JSON.stringify(key)}: ${objectType(value)};`).join('\n')}\n}\n\n` +
+    `export type PulseEventKey = keyof PulseEventSchema;\n` +
+    `export type PulseTypedEvent<K extends PulseEventKey> = { event: K; props: PulseEventSchema[K]; time?: Date };\n\n` +
+    `export type PulseAction = ${actionEntries.length > 0
+      ? actionEntries.map(([key, value]) => `(DecisionAction & { kind: ${JSON.stringify(key)} } & ${objectType(value)})`).join(' | ')
+      : 'DecisionAction'};\n` +
+    `export type PulseTrack = <K extends PulseEventKey>(event: K, props?: PulseEventSchema[K], time?: TrackedEventInput['time']) => void;\n`;
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, output);
+  logSuccess(`Generated ${path.relative(process.cwd(), outputPath)} from ${path.relative(process.cwd(), schemaPath)}`);
+}
+
 /**
  * Show help
  */
@@ -1307,6 +1365,7 @@ ${colors.cyan}Commands:${colors.reset}
   publish                 Create bundle and publish update to server
   keygen                  Generate an Ed25519 signing keypair (server + app config)
   register-capabilities   Record the embedded bundle's native capability set (crash-prediction)
+  generate                Generate typed config/event/action contracts from pulse.schema.json
 
 ${colors.cyan}Options:${colors.reset}
   --api-url <url>         API server URL (auto-detected from native config)
@@ -1315,6 +1374,7 @@ ${colors.cyan}Options:${colors.reset}
   --runtime-version <v>   Runtime version (auto-detected from native config)
   --channel <channel>     Release channel (default: production)
   --bundle-dir <dir>      Output directory (default: ./dist)
+  --bundle <file>         Embedded bundle for register-capabilities (otherwise built automatically)
   --entry-file <file>     Entry file (default: index.ts)
   --skip-bundle           Skip bundle creation (use existing)
   --dry-run               Build + validate locally without creating a release on the server
@@ -1326,6 +1386,8 @@ ${colors.cyan}Options:${colors.reset}
   --build <number>        Build number (shown in version, e.g., 1.0.0.42)
   --message <msg>         Release message/notes
   --key-id <id>           Key id for keygen (default: auto-generated)
+  --schema <file>         Contract schema for generate (default: pulse.schema.json)
+  --output <file>         Generated TypeScript file (default: src/pulse.generated.ts)
 
 ${colors.cyan}Experiments:${colors.reset}
   pulse-updates experiments                       List them, with the split each one got
@@ -1388,6 +1450,9 @@ async function main() {
       case 'keygen':
         keygen(options);
         break;
+      case 'generate':
+        generateContracts(options);
+        break;
       case 'help':
       case '--help':
       case '-h':

package/src/NativePulseUpdates.ts

@@ -43,6 +43,7 @@ export interface Spec extends TurboModule {
 
   markAppReady(): Promise<void>;
   reportLaunchFailure(reason: string): Promise<void>;
+  verifySignatureAsync(canonicalPayload: string, alg: string, keyId: string, signature: string): Promise<boolean>;
 
   // Event emitter
   addListener(eventName: string): void;

package/src/PulseUpdates.ts

@@ -16,6 +16,42 @@ let _isEmbeddedLaunch = true;
 let _manifest: PulseManifest | null = null;
 let _createdAt: Date | null = null;
 let _localAssets: Record<string, string> | null = null;
+const stateListeners = new Set<() => void>();
+
+export interface PulseNativeState {
+  isEnabled: boolean;
+  updateId: string | null;
+  runtimeVersion: string | null;
+  channel: string | null;
+  isEmbeddedLaunch: boolean;
+  manifest: PulseManifest | null;
+  createdAt: Date | null;
+  localAssets: Record<string, string> | null;
+}
+
+/** A stable read surface for React and for diagnostics. */
+export function getUpdatesState(): PulseNativeState {
+  return {
+    isEnabled: _isEnabled,
+    updateId: _updateId,
+    runtimeVersion: _runtimeVersion,
+    channel: _channel,
+    isEmbeddedLaunch: _isEmbeddedLaunch,
+    manifest: _manifest,
+    createdAt: _createdAt,
+    localAssets: _localAssets,
+  };
+}
+
+/** Subscribe to native-state refreshes without depending on mutable ES exports. */
+export function onUpdatesStateChange(listener: () => void): () => void {
+  stateListeners.add(listener);
+  return () => stateListeners.delete(listener);
+}
+
+function notifyStateListeners(): void {
+  for (const listener of stateListeners) listener();
+}
 
 /**
  * Configure pulse-updates with the given options.
@@ -51,6 +87,9 @@ export function configure(config: PulseUpdatesConfig): void {
   _isConfigured = true;
   _isEnabled = config.enabled;
   _runtimeVersion = config.runtimeVersion;
+  isEnabled = _isEnabled;
+  runtimeVersion = _runtimeVersion;
+  notifyStateListeners();
 }
 
 /**
@@ -133,6 +172,7 @@ export async function refreshStateAsync(): Promise<void> {
     // Read localAssets map for asset resolution
     _localAssets = state.localAssets ?? null;
     localAssets = _localAssets;
+    notifyStateListeners();
   } catch (error) {
     console.warn('[PulseUpdates] Failed to refresh state:', error);
     // Keep current values on error
@@ -241,6 +281,20 @@ export async function reportLaunchFailure(reason: string): Promise<void> {
   await PulseUpdatesModule.reportLaunchFailure(reason);
 }
 
+/** Verify config/decision payloads with the public key already pinned in native config. */
+export async function verifyConfigSignatureAsync(
+  canonicalPayload: string,
+  signature: { alg: string; keyId: string; sig: string },
+): Promise<boolean> {
+  if (!PulseUpdatesModule?.verifySignatureAsync) return false;
+  return PulseUpdatesModule.verifySignatureAsync(
+    canonicalPayload,
+    signature.alg,
+    signature.keyId,
+    signature.sig,
+  );
+}
+
 /**
  * Get the build number from the current update's metadata.
  */

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.
   }