@scalebun/react-native 1.10.5 → 1.10.7

package/src/features/ota/crypto/builtinVerifier.ts

@@ -0,0 +1,257 @@
+/**
+ * Built-in ed25519 verifier, assembled from OPTIONAL peer dependencies.
+ *
+ * WHAT THIS REPLACES. Pinning `ota.publicSigningKey` used to require the host
+ * app to write its own `verifySignature` — roughly a hundred lines of hex and
+ * base64 decoding wrapped around a crypto library. That put the single most
+ * security-critical operation in the product, the one deciding whether remote
+ * code is authentic before it executes, in code the SDK could neither test nor
+ * audit. Three failure modes all landed on the app author:
+ *
+ *   - A verifier that always returns `true` silently disables the feature, and
+ *     nothing can detect it.
+ *   - @noble's hash-provider property moved between major versions, so a
+ *     routine dependency bump made every update fail closed with no signal
+ *     pointing at the cause.
+ *   - Hand-written base64 decoders tend to omit base64url, so a signature
+ *     containing `-` or `_` is rejected as a forgery.
+ *
+ * All three are now the SDK's problem, which is where they belong. A host that
+ * installs `@noble/ed25519` and `@noble/hashes` gets verification by pinning a
+ * key and writing no code at all.
+ *
+ * WHY OPTIONAL AND NOT A HARD DEPENDENCY. Most apps never adopt bundle
+ * signing, and they should not carry curve arithmetic they will not run. The
+ * `verifySignature` hook remains supported and still WINS over this, for teams
+ * with their own crypto policy or a native implementation to delegate to.
+ *
+ * WHAT THIS DOES NOT FIX. Verification still happens in JS, inside the very
+ * bundle it protects. An attacker who lands one malicious bundle by other means
+ * can neuter the check for every update after it. Closing that needs native
+ * verification — CryptoKit on iOS (13.4+, already the deployment target) and
+ * `Signature.getInstance("Ed25519")` on Android API 33+, with a fallback below.
+ */
+
+import { loadEd25519, type NobleEd25519 } from './loadEd25519';
+import { loadSha512, type Sha512Fn } from './loadSha512';
+import { logger } from '../../../core/logger/internalLogger';
+import type { SignatureVerifier } from '../signature';
+
+const ED25519_SIGNATURE_BYTES = 64;
+const ED25519_PUBLIC_KEY_BYTES = 32;
+
+/** Hex → bytes. Returns null rather than throwing; callers treat null as "reject". */
+function hexToBytes(hex: string): Uint8Array | null {
+    const clean = hex.trim().toLowerCase().replace(/^0x/, '');
+    if (clean.length === 0 || clean.length % 2 !== 0 || /[^0-9a-f]/.test(clean)) return null;
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+
+const B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * Base64 → bytes, accepting base64url as well.
+ *
+ * The `-`/`_` handling is the point. A verifier that omits it rejects a
+ * perfectly valid signature as a forgery the moment the signing side emits
+ * base64url, and the resulting symptom — updates silently stop installing —
+ * looks nothing like a decoding bug.
+ */
+function base64ToBytes(b64: string): Uint8Array | null {
+    const s = b64.trim().replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+    if (s.length === 0) return null;
+    const out: number[] = [];
+    let buffer = 0;
+    let bits = 0;
+    for (const ch of s) {
+        const idx = B64_ALPHABET.indexOf(ch);
+        if (idx === -1) return null;
+        buffer = (buffer << 6) | idx;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out.push((buffer >> bits) & 0xff);
+        }
+    }
+    return Uint8Array.from(out);
+}
+
+/**
+ * Decode a detached signature that may arrive hex- or base64-encoded.
+ *
+ * Tries the unambiguous case first: 128 hex characters is exactly 64 bytes and
+ * cannot be anything else. Otherwise base64, then hex as a last resort. Only a
+ * result of exactly 64 bytes is accepted, so a string that decodes under the
+ * wrong scheme is rejected rather than fed to the curve code as garbage.
+ */
+export function decodeSignature(sig: string): Uint8Array | null {
+    const trimmed = sig.trim();
+    if (/^(0x)?[0-9a-fA-F]{128}$/.test(trimmed)) {
+        const hex = hexToBytes(trimmed);
+        if (hex && hex.length === ED25519_SIGNATURE_BYTES) return hex;
+    }
+    const b64 = base64ToBytes(trimmed);
+    if (b64 && b64.length === ED25519_SIGNATURE_BYTES) return b64;
+    const hex = hexToBytes(trimmed);
+    if (hex && hex.length === ED25519_SIGNATURE_BYTES) return hex;
+    return null;
+}
+
+/**
+ * Give @noble its SHA-512 provider.
+ *
+ * The property it reads moved between major versions — v2 wants
+ * `etc.sha512Sync`, v3 wants `hashes.sha512` — so both are populated when
+ * present. Getting this wrong does not fail loudly: verification simply throws
+ * from inside the curve code and the outer catch converts it to "rejected",
+ * which is indistinguishable from an actual forgery. That ambiguity is exactly
+ * what made this a bad thing to ask app authors to maintain.
+ */
+function wireSha512(ed: NobleEd25519, sha512: Sha512Fn): boolean {
+    // VARIADIC ON PURPOSE. @noble calls its hash provider with several byte
+    // arrays to be hashed as one concatenated message. A wrapper taking a
+    // single argument hashes only the first, silently produces the wrong
+    // digest, and every genuine signature is then reported as INVALID — no
+    // error, no exception, just an authenticity check that always says no.
+    // Verified against a real CLI-produced signature; the single-argument form
+    // failed every positive case while passing every negative one, which is
+    // the most misleading shape a bug of this kind can take.
+    const concat = (parts: Uint8Array[]): Uint8Array => {
+        if (parts.length === 1) return parts[0];
+        let total = 0;
+        for (const p of parts) total += p.length;
+        const out = new Uint8Array(total);
+        let off = 0;
+        for (const p of parts) {
+            out.set(p, off);
+            off += p.length;
+        }
+        return out;
+    };
+    const sync = (...msgs: Uint8Array[]) => sha512(concat(msgs));
+    const asyncFn = async (...msgs: Uint8Array[]) => sha512(concat(msgs));
+
+    // EACH BRANCH GETS ITS OWN try. Wrapping both in one is a trap, and it cost
+    // an afternoon: under v3 the `hashes` assignment succeeds and the `etc`
+    // object is FROZEN, so the v2-shaped assignment throws "object is not
+    // extensible" — discarding a verifier that was, by then, already correctly
+    // wired. Only "neither shape took" means unavailable.
+    let wired = false;
+
+    try {
+        if (ed.hashes && typeof ed.hashes === 'object') {
+            if (typeof ed.hashes.sha512 !== 'function') ed.hashes.sha512 = sync;
+            if (typeof ed.hashes.sha512Async !== 'function') ed.hashes.sha512Async = asyncFn;
+            wired = typeof ed.hashes.sha512 === 'function';
+        }
+    } catch {
+        /* frozen or absent — try the other shape */
+    }
+
+    try {
+        if (ed.etc && typeof ed.etc === 'object') {
+            if (typeof ed.etc.sha512Sync !== 'function') ed.etc.sha512Sync = sync;
+            if (typeof ed.etc.sha512Async !== 'function') ed.etc.sha512Async = asyncFn;
+            wired = wired || typeof ed.etc.sha512Sync === 'function';
+        }
+    } catch {
+        /* frozen or absent — `wired` already records whether the other shape took */
+    }
+
+    return wired;
+}
+
+let resolved: SignatureVerifier | null | undefined;
+
+/**
+ * The built-in verifier, or null when the optional deps are not installed.
+ * Resolution is cached, including the negative result — a missing dependency
+ * does not become present at runtime, and retrying the require on every update
+ * check would be pure overhead.
+ */
+export function getBuiltinVerifier(): SignatureVerifier | null {
+    if (resolved !== undefined) return resolved;
+
+    const ed = loadEd25519();
+    const sha512 = loadSha512();
+
+    if (!ed || !sha512) {
+        resolved = null;
+        return null;
+    }
+
+    if (!wireSha512(ed, sha512)) {
+        // A shape neither branch matched — a @noble major this SDK predates.
+        // Report "no verifier", which is actionable, rather than letting every
+        // update fail deep inside the curve code with an opaque error.
+        logger.error(
+            '[OTA] @noble/ed25519 is installed but its SHA-512 provider could not be ' +
+                'wired (unrecognised version shape). Supply `ota.verifySignature` ' +
+                'yourself, or pin a @noble/ed25519 version this SDK supports.',
+        );
+        resolved = null;
+        return null;
+    }
+
+    resolved = async ({ messageHex, signature, publicKey }) => {
+        const message = hexToBytes(messageHex);
+        const pub = hexToBytes(publicKey);
+        const sig = decodeSignature(signature);
+
+        if (!message) {
+            logger.error('[OTA] Bundle SHA-256 is not valid hex — refusing to stage.');
+            return false;
+        }
+        if (!pub || pub.length !== ED25519_PUBLIC_KEY_BYTES) {
+            // Worth naming precisely: a mistyped or wrongly-encoded key would
+            // otherwise present as "every update is a forgery".
+            logger.error(
+                `[OTA] ota.publicSigningKey must be ${ED25519_PUBLIC_KEY_BYTES} bytes of hex ` +
+                    `(${ED25519_PUBLIC_KEY_BYTES * 2} characters) — got ` +
+                    `${pub ? `${pub.length} bytes` : 'a value that is not hex'}.`,
+            );
+            return false;
+        }
+        if (!sig) {
+            logger.error('[OTA] Bundle signature is not a 64-byte hex/base64 value.');
+            return false;
+        }
+
+        // @noble THROWS rather than returning false for bytes that are not a
+        // well-formed point — which is most forgeries, since a tampered
+        // signature usually decodes to garbage rather than to a valid-but-wrong
+        // point. Swallowing that here is deliberate: from the SDK's side a
+        // malformed signature IS a rejection, and letting it escape would
+        // surface as `verifier_threw`, the outcome reserved for a HOST verifier
+        // misbehaving. Conflating "this bundle is forged" with "your verifier
+        // is broken" would point every investigation in the wrong direction.
+        try {
+            // SYNC FIRST, and this is not a style preference. @noble's
+            // `verifyAsync` reaches for `crypto.subtle` — "crypto.subtle must be
+            // defined, consider polyfill" — which React Native does not provide
+            // and neither does a plain Node test environment. The sync `verify`
+            // uses the SHA-512 provider wired above and needs no WebCrypto, so
+            // it is the path that actually works on a phone. Verification is a
+            // few hundred microseconds over a 32-byte digest, once per update
+            // check, so there is nothing to gain from the async form anyway.
+            if (typeof ed.verify === 'function') return ed.verify(sig, message, pub);
+            if (typeof ed.verifyAsync === 'function') return await ed.verifyAsync(sig, message, pub);
+            return false;
+        } catch {
+            return false;
+        }
+    };
+
+    __DEV__ &&
+        logger.debug('[OTA] Using built-in ed25519 verifier (@noble/ed25519 detected).');
+    return resolved;
+}
+
+/** Test seam — clears the cached resolution. */
+export function _resetBuiltinVerifier(): void {
+    resolved = undefined;
+}

package/src/features/ota/crypto/loadEd25519.ts

@@ -0,0 +1,41 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@noble/ed25519` dep.
+ *
+ * WHY ITS OWN FILE: Metro's dependency collector emits a dependency map one
+ * entry short for a module containing TWO OR MORE different-string inline
+ * `require()` calls, so the require indices desync and `_dependencyMap[N]`
+ * reads `undefined` ("Requiring unknown module 'undefined'"). Exactly ONE
+ * inline require per module avoids the miscount. `loadSha512` is a sibling file
+ * for the same reason — see `push/adapters/loadNotifee.ts`, which hit this first.
+ *
+ * The string must still be STATICALLY resolvable at bundle time; hosts that do
+ * not install it stub it via `withScaleBun`.
+ */
+
+/** The subset of the @noble/ed25519 surface this SDK uses. */
+export interface NobleEd25519 {
+    verifyAsync?: (sig: Uint8Array, msg: Uint8Array, pub: Uint8Array) => Promise<boolean>;
+    verify?: (sig: Uint8Array, msg: Uint8Array, pub: Uint8Array) => boolean;
+    /** v3 shape: `ed.hashes.sha512` */
+    hashes?: { sha512?: unknown; sha512Async?: unknown };
+    /** v2 shape: `ed.etc.sha512Sync` */
+    etc?: { sha512Sync?: unknown; sha512Async?: unknown };
+}
+
+export function loadEd25519(): NobleEd25519 | null {
+    try {
+        const mod = require('@noble/ed25519');
+        const ed = (mod?.default ?? mod) as NobleEd25519;
+        // Validate the API actually used, not mere truthiness: when the package
+        // is absent `withScaleBun` resolves it to an EMPTY STUB MODULE, which is
+        // a perfectly truthy object. A stub must read as "unavailable", because
+        // treating it as available would make every signed update fail with a
+        // crypto error instead of the actionable "no verifier" message.
+        if (typeof ed?.verifyAsync === 'function' || typeof ed?.verify === 'function') {
+            return ed;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}

package/src/features/ota/crypto/loadSha512.ts

@@ -0,0 +1,35 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@noble/hashes` SHA-512.
+ *
+ * Separate file from `loadEd25519` because Metro miscounts a module holding two
+ * different-string inline `require()` calls — see the comment there.
+ *
+ * ed25519 is defined in terms of SHA-512, and React Native has no native
+ * SHA-512, so @noble/ed25519 cannot verify anything until a hash provider is
+ * wired into it. Which property it expects differs by major version, so the
+ * wiring lives in `builtinVerifier`, not here; this module only obtains the
+ * function.
+ */
+
+export type Sha512Fn = (msg: Uint8Array) => Uint8Array;
+
+export function loadSha512(): Sha512Fn | null {
+    try {
+        // The `.js` SUFFIX IS REQUIRED, not stylistic. @noble/hashes v2 declares
+        // its exports map with extensions — `"./sha2.js"`, not `"./sha2"` — so
+        // the extensionless form misses the map entirely. Node still resolves it
+        // by falling back to file-based lookup, which is why it passes here,
+        // but Metro prints
+        //   "Attempted to import … not listed in the exports … Falling back to
+        //    file-based resolution"
+        // on every bundle, and that fallback is exactly what a stricter resolver
+        // (or a future Metro) drops. Caught while bundling a real Expo app.
+        const mod = require('@noble/hashes/sha2.js');
+        const sha512 = (mod?.sha512 ?? mod?.default?.sha512) as Sha512Fn | undefined;
+        // A stubbed module yields undefined here, which correctly reads as
+        // "unavailable" rather than throwing deep inside the curve code later.
+        return typeof sha512 === 'function' ? sha512 : null;
+    } catch {
+        return null;
+    }
+}

package/src/features/ota/crypto/nativeVerifier.ts

@@ -0,0 +1,117 @@
+/**
+ * Native ed25519 verifier — platform crypto wrapped as a SignatureVerifier.
+ *
+ * WHY IT EXISTS. The built-in @noble verifier runs in JS, inside the very
+ * bundle it protects: an attacker who lands one malicious bundle can neuter a
+ * JS check for every update after it. Platform crypto (CryptoKit on iOS,
+ * Android's conscrypt on API 33+) sits outside the bundle's reach — and using
+ * it also drops the runtime dependency on the optional @noble peers wherever
+ * the OS provides ed25519.
+ *
+ * WHAT IT DOES NOT FIX, stated plainly: the ORCHESTRATION still lives in JS.
+ * A hostile bundle can skip calling any verifier and drive the native staging
+ * methods directly. Moving the crypto native shrinks the attack surface (no
+ * more tampering with a bundled crypto lib to flip a verdict) but the full
+ * close needs native-ENFORCED staging with a natively-pinned key — an
+ * architectural change tracked separately, not smuggled into this one.
+ *
+ * VERDICT CONTRACT (mirrors the spec): the native side resolves
+ * 'valid' | 'invalid' | 'unavailable'. 'invalid' is a definitive NO.
+ * 'unavailable' (Android < 33, malformed input, machinery failure) means this
+ * source cannot answer — the composed verifier below then delegates to the
+ * @noble builtin, and when that is absent too it THROWS, which the policy
+ * layer converts to a rejection. Every path that cannot verify refuses.
+ */
+
+import NativeScaleBunOta from '../../../specs/NativeScaleBunOta';
+import { logger } from '../../../core/logger/internalLogger';
+import { decodeSignature, getBuiltinVerifier } from './builtinVerifier';
+import type { SignatureVerifier } from '../signature';
+
+const ED25519_PUBLIC_KEY_HEX_CHARS = 64;
+
+/** bytes → lowercase hex (the native side takes clean hex only). */
+function bytesToHex(bytes: Uint8Array): string {
+    let out = '';
+    for (const b of bytes) out += b.toString(16).padStart(2, '0');
+    return out;
+}
+
+/** Strict lowercase-hex normalization; null when the value is not hex. */
+function normalizeHex(value: string, expectedChars: number): string | null {
+    const clean = value.trim().toLowerCase().replace(/^0x/, '');
+    if (clean.length !== expectedChars || /[^0-9a-f]/.test(clean)) return null;
+    return clean;
+}
+
+let resolved: SignatureVerifier | null | undefined;
+
+/**
+ * The native-first verifier, or null when the native module (or its
+ * verifyEd25519 method — an app running new JS against an old binary) is
+ * absent. Cached like the builtin: module availability does not change at
+ * runtime, and this is consulted on every update check.
+ */
+export function getNativeVerifier(): SignatureVerifier | null {
+    if (resolved !== undefined) return resolved;
+
+    const native = NativeScaleBunOta;
+    if (!native || typeof (native as any).verifyEd25519 !== 'function') {
+        // Old binary, Jest, web/SSR — not an error, just not this source.
+        resolved = null;
+        return null;
+    }
+
+    resolved = async ({ messageHex, signature, publicKey }) => {
+        // All decoding and validation happens HERE, in one place, so both
+        // platforms' native code only ever sees clean fixed-length hex. The
+        // signature may arrive hex or base64 (the wire allows both) — reuse
+        // the builtin's decoder rather than growing a second, subtly
+        // different one.
+        const message = normalizeHex(messageHex, 64);
+        const key = normalizeHex(publicKey, ED25519_PUBLIC_KEY_HEX_CHARS);
+        const sigBytes = decodeSignature(signature);
+        if (!message || !key || !sigBytes) {
+            // Same messages-by-symptom philosophy as the builtin: a mistyped
+            // key must not present as "every update is a forgery".
+            logger.error(
+                '[OTA] Signature inputs malformed (bundle hash, signature, or public key) — refusing to stage.',
+            );
+            return false;
+        }
+
+        let verdict: string;
+        try {
+            verdict = await (native as any).verifyEd25519(message, bytesToHex(sigBytes), key);
+        } catch (err: any) {
+            // A rejected promise is machinery failure, not a forgery verdict.
+            logger.warn(`[OTA] Native ed25519 verify failed to run: ${err?.message ?? err}`);
+            verdict = 'unavailable';
+        }
+
+        if (verdict === 'valid') return true;
+        if (verdict === 'invalid') return false;
+
+        // 'unavailable' (Android < 33) — fall back to the JS verifier so those
+        // devices keep verifying rather than losing enforcement.
+        const builtin = getBuiltinVerifier();
+        if (builtin) {
+            return builtin({ messageHex, signature, publicKey });
+        }
+        // No source can verify. Throwing (rather than returning false) keeps
+        // the policy layer's outcome labels honest: this surfaces as machinery
+        // failure with an actionable message, not as "the bundle is forged".
+        throw new Error(
+            'ed25519 unavailable: this OS has no native implementation (Android < 13) and the ' +
+                'optional peers @noble/ed25519 + @noble/hashes are not installed.',
+        );
+    };
+
+    __DEV__ && logger.debug('[OTA] Using native ed25519 verifier (platform crypto).');
+    return resolved;
+}
+
+/** Test seam — clears the cached resolution. */
+export function _resetNativeVerifier(): void {
+    resolved = undefined;
+}

package/src/features/ota/signature.ts

@@ -1,4 +1,6 @@
 import { logger } from '../../core/logger/internalLogger';
+import { getBuiltinVerifier } from './crypto/builtinVerifier';
+import { getNativeVerifier } from './crypto/nativeVerifier';
 
 /**
  * Bundle signature verification (OTA-03).
@@ -13,10 +15,17 @@ import { logger } from '../../core/logger/internalLogger';
  * download and nothing else. On a platform whose entire purpose is remote code
  * delivery, that is the control that matters most.
  *
- * WHY IT IS SHAPED LIKE THIS. The SDK ships zero third-party runtime
- * dependencies, and React Native has no built-in ed25519. So verification is
- * delegated to a host-provided verifier when one is installed, and the SDK's job
- * is to decide — unambiguously — what happens when there is not one.
+ * WHY IT IS SHAPED LIKE THIS. React Native has no built-in ed25519, so the
+ * verification primitive has to come from somewhere. It is resolved in order:
+ * a host-supplied verifier, else the built-in one assembled from the OPTIONAL
+ * `@noble/ed25519` + `@noble/hashes` peers, else nothing — and the SDK's job is
+ * to decide, unambiguously, what happens in that last case.
+ *
+ * The built-in path exists because requiring every adopter to hand-write a
+ * verifier put the most security-critical operation in the product in code the
+ * SDK could neither test nor audit, and made a routine dependency bump able to
+ * silently stop all updates. See `crypto/builtinVerifier.ts`. Signing stays
+ * opt-in, and apps that never adopt it carry no curve arithmetic.
  *
  * THE POLICY, which is the important part:
  *
@@ -44,15 +53,26 @@ export type SignatureVerifier = (input: {
 }) => boolean | Promise<boolean>;
 
 export interface SignatureConfig {
-  /** ed25519 public key shipped in the app binary. Absent = signing not adopted. */
-  publicKey?: string;
+  /**
+   * ed25519 public key(s) shipped in the app binary. Absent = signing not
+   * adopted. An ARRAY pins several keys at once and a bundle is accepted when
+   * ANY of them verifies — this is what makes key rotation possible without an
+   * app-store release: ship a build pinning [old, new], start signing with new,
+   * drop old from the next build. With a single pinnable key, losing the
+   * private key meant no OTA capability until a new binary cleared review —
+   * the exact emergency OTA exists to solve.
+   */
+  publicKey?: string | string[];
   /** Host-provided ed25519 verification function. */
   verifier?: SignatureVerifier;
 }
 
 export type SignatureOutcome =
   | { ok: true; reason: 'verified' | 'not_configured' }
-  | { ok: false; reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw' };
+  | {
+      ok: false;
+      reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw' | 'no_keys';
+    };
 
 let warnedNotConfigured = false;
 
@@ -69,10 +89,18 @@ export async function verifyBundleSignature(
   signature: string | undefined,
   config: SignatureConfig | undefined,
 ): Promise<SignatureOutcome> {
-  const publicKey = config?.publicKey;
+  const rawKey = config?.publicKey;
+
+  // Normalize to a list. A single non-empty string is the pre-rotation config
+  // shape and behaves exactly as before; an array pins several keys at once.
+  const keys = (Array.isArray(rawKey) ? rawKey : rawKey ? [rawKey] : []).filter(
+    (k): k is string => typeof k === 'string' && k.trim().length > 0,
+  );
 
-  // Signing not adopted by this app — nothing to enforce.
-  if (!publicKey) {
+  // Signing not adopted by this app — nothing to enforce. Parity note: a
+  // falsy single value (undefined, '') has always meant "not configured" and
+  // still does.
+  if (rawKey === undefined || rawKey === '' || rawKey === null) {
     if (!warnedNotConfigured) {
       warnedNotConfigured = true;
       logger.warn(
@@ -83,6 +111,20 @@ export async function verifyBundleSignature(
     return { ok: true, reason: 'not_configured' };
   }
 
+  // The host PROVIDED a key config that resolves to zero usable keys — an
+  // empty array, or an array of blank strings. That is a broken attempt to
+  // enable signing, not an absence of one, and the two must not collapse:
+  // treating `publicSigningKeys: []` as "not configured" would let a config
+  // mistake silently downgrade an app to unverified installs. Fail closed.
+  if (keys.length === 0) {
+    logger.error(
+      '[OTA] Signing key config resolves to zero usable keys (empty array or blank ' +
+        'strings) — refusing to stage. Remove the config to disable signing, or pin ' +
+        'at least one real key.',
+    );
+    return { ok: false, reason: 'no_keys' };
+  }
+
   // The app opted in, so a bundle without a signature is a refusal, not a pass.
   if (!signature) {
     logger.error(
@@ -91,30 +133,71 @@ export async function verifyBundleSignature(
     return { ok: false, reason: 'missing_signature' };
   }
 
-  if (typeof config?.verifier !== 'function') {
+  // Resolution order, and the order matters:
+  //   1. A host-supplied verifier ALWAYS wins. A team with its own crypto
+  //      policy must be able to override whatever the SDK would otherwise pick.
+  //   2. Otherwise the NATIVE verifier (CryptoKit / Android 13+ platform
+  //      ed25519). Preferred over the JS one because it runs outside the
+  //      bundle it protects and needs no optional peers; on OS levels without
+  //      ed25519 it delegates to the builtin internally.
+  //   3. Otherwise the built-in @noble verifier, if the optional peers are
+  //      installed. This is the path that removes ~100 lines of hand-written
+  //      crypto plumbing from every app that adopts signing.
+  //   4. Otherwise reject, because a configured key is a request for
+  //      enforcement and quietly installing unverified code would turn a
+  //      security feature into a placebo.
+  const verifier =
+    typeof config?.verifier === 'function'
+      ? config.verifier
+      : (getNativeVerifier() ?? getBuiltinVerifier());
+
+  if (!verifier) {
     logger.error(
       '[OTA] A signing key is configured but no signature verifier is available — ' +
-        'refusing to stage. Provide `ota.verifySignature` so signatures can be checked.',
+        'refusing to stage. Either install the optional peers ' +
+        '`@noble/ed25519` and `@noble/hashes` (the SDK then verifies with no ' +
+        'further code), or provide your own `ota.verifySignature`.',
     );
     return { ok: false, reason: 'no_verifier' };
   }
 
-  try {
-    const valid = await config.verifier({
-      messageHex: bundleSha256,
-      signature,
-      publicKey,
-    });
-    if (!valid) {
-      logger.error('[OTA] Bundle signature is INVALID — refusing to stage.');
-      return { ok: false, reason: 'invalid_signature' };
+  // Try every pinned key; any single match accepts. The verifier contract is
+  // unchanged (one key per call) so host-supplied verifiers keep working.
+  //
+  // Outcome labelling when nothing matched, and why it matters: if at least
+  // one verifier call RAN TO COMPLETION and said no, the bundle failed
+  // verification — 'invalid_signature'. Only when EVERY call threw is the
+  // machinery itself suspect — 'verifier_threw'. Collapsing those (e.g. by
+  // letting the last key's throw win) would point an investigation at the
+  // host's verifier when the actual event was a forged bundle, or vice versa.
+  let sawThrow = false;
+  let sawCompletion = false;
+  for (const key of keys) {
+    try {
+      const valid = await verifier({
+        messageHex: bundleSha256,
+        signature,
+        publicKey: key,
+      });
+      sawCompletion = true;
+      if (valid) return { ok: true, reason: 'verified' };
+    } catch (err: any) {
+      // A throwing verifier is treated as a failed verification for this key,
+      // never as a pass — but the remaining keys still get their chance.
+      sawThrow = true;
+      logger.error(`[OTA] Signature verifier threw: ${err?.message ?? err}`);
     }
-    return { ok: true, reason: 'verified' };
-  } catch (err: any) {
-    // A throwing verifier is treated as a failed verification, never as a pass.
-    logger.error(`[OTA] Signature verifier threw: ${err?.message ?? err}`);
+  }
+
+  if (sawThrow && !sawCompletion) {
     return { ok: false, reason: 'verifier_threw' };
   }
+  logger.error(
+    keys.length > 1
+      ? `[OTA] Bundle signature is INVALID under all ${keys.length} pinned keys — refusing to stage.`
+      : '[OTA] Bundle signature is INVALID — refusing to stage.',
+  );
+  return { ok: false, reason: 'invalid_signature' };
 }
 
 /** Test seam — resets the once-per-process "not configured" warning. */