@lightninglabs/wavelength-react-native 0.1.0

package/dist/client.js

@@ -0,0 +1,143 @@
+import { BaseWavelengthClient, WavelengthError, errorMessage, } from '@lightninglabs/wavelength-core';
+/**
+* The React Native transport: implements {@link BaseWavelengthClient}'s pipe
+* over the gomobile Turbo Module. JSON strings cross the RN bridge, then the
+* shared base client normalizes responses and streamed entries in TS.
+*/
+export class NativeWavelengthClient extends BaseWavelengthClient {
+    // The embedded daemon runs natively, so it dials the servers over gRPC.
+    serverTransport = 'grpc';
+    removeNativeListener = null;
+    // Serializes start/stop native ops so a start always waits for a pending
+    // stop's native close to finish before it subscribes.
+    opChain = Promise.resolve();
+    // Whether a native subscription is currently open. Only read and written
+    // inside serialized ops, so it never races.
+    streamOpen = false;
+    native;
+    subscribeToNativeEvents;
+    constructor(native, subscribeToNativeEvents) {
+        super();
+        this.native = native;
+        this.subscribeToNativeEvents = subscribeToNativeEvents;
+    }
+    // enqueue runs op after the previous op settles, whether it fulfilled or
+    // rejected, so a rejected native call cannot stall the chain.
+    enqueue(op) {
+        const next = this.opChain.then(op, op);
+        this.opChain = next;
+        return next;
+    }
+    // The runtime is compiled into the app binary, so there is nothing to load.
+    ready() {
+        return Promise.resolve();
+    }
+    // start fills in the platform default data directory when the caller did
+    // not choose one; only the native side knows the app's sandbox paths.
+    async start(config) {
+        return super.start({
+            ...config,
+            dataDir: config.dataDir ?? (await this.native.getDefaultDataDir()),
+        });
+    }
+    async invokeFacade(method, params = {}) {
+        try {
+            const resultJson = await this.native.call(method, JSON.stringify(params ?? {}));
+            return (resultJson ? JSON.parse(resultJson) : null);
+        }
+        catch (err) {
+            throw new WavelengthError(errorMessage(err), 'wavelength_error', {
+                cause: err,
+            });
+        }
+    }
+    // startActivity opens the native pull subscription; the native side pumps
+    // entries to 'wavelengthActivity' device events, which are re-emitted here
+    // as typed 'activity' events. Idempotent while a stream is open.
+    async openActivityStream(opts) {
+        return this.enqueue(async () => {
+            if (this.streamOpen) {
+                return;
+            }
+            this.removeNativeListener ??= this.subscribeToNativeEvents((event) => this.onNativeEvent(event));
+            await this.native.startActivity(JSON.stringify({
+                includeExisting: opts.includeExisting ?? false,
+                kinds: opts.kinds ?? [],
+                cursor: opts.cursor ?? 0,
+            }));
+            this.streamOpen = true;
+        });
+    }
+    stopActivity() {
+        void this.enqueue(async () => {
+            if (!this.streamOpen) {
+                return;
+            }
+            // Native stop detaches the old subscription before close and emits no
+            // terminal event for it, so a queued start can safely open a new pump.
+            this.streamOpen = false;
+            try {
+                await this.native.stopActivity();
+            }
+            catch (err) {
+                // A failed native close means the pump may still be running; surface
+                // it instead of swallowing so a zombie stream is at least diagnosable.
+                this.emit({
+                    type: 'log',
+                    payload: {
+                        level: 'warn',
+                        message: `failed to close the activity stream: ${errorMessage(err)}`,
+                    },
+                });
+            }
+        });
+    }
+    onNativeEvent(event) {
+        switch (event.kind) {
+            case 'entry': {
+                let entry;
+                try {
+                    entry = this.normalizeActivityEntry(JSON.parse(event.payload));
+                }
+                catch (err) {
+                    this.emit({
+                        type: 'log',
+                        payload: {
+                            level: 'error',
+                            message: `dropped an unparseable activity entry: ${errorMessage(err)}`,
+                        },
+                    });
+                    return;
+                }
+                this.emit({ type: 'activity', payload: entry });
+                return;
+            }
+            case 'end':
+                this.streamOpen = false;
+                this.emit({ type: 'activityStream', payload: { state: 'ended' } });
+                return;
+            case 'error':
+                this.streamOpen = false;
+                this.emit({
+                    type: 'activityStream',
+                    payload: { state: 'failed', message: event.payload },
+                });
+                return;
+            default:
+                this.emit({
+                    type: 'log',
+                    payload: {
+                        level: 'warn',
+                        message: `unknown wavelength native event: ${event.kind}`,
+                    },
+                });
+        }
+    }
+    dispose() {
+        // super.dispose() calls stopActivity(). Keep streamOpen intact until that
+        // queued stop reads it, or disposal would leak the native pump.
+        super.dispose();
+        this.removeNativeListener?.();
+        this.removeNativeListener = null;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import { type PresetNetwork, type RuntimeConfig } from '@lightninglabs/wavelength-core';
+/**
+ * Returns a ready-to-use {@link RuntimeConfig} for a network on the React
+ * Native transport, preloaded with the canonical public gRPC host:port
+ * addresses and merged with any overrides. Pass overrides to set dataDir or
+ * point at your own infrastructure, e.g.
+ * `defaultConfig('signet', { dataDir: '/wallet' })`.
+ *
+ * Only the preset networks are accepted (see {@link PresetNetwork}). mainnet
+ * and regtest have no preset: build their config by hand, mainnet with your
+ * own gRPC addresses and allowMainnet, regtest with local addresses and the
+ * insecure-transport flags.
+ *
+ * @param network - The Bitcoin network to build a config for.
+ * @param overrides - Fields that override the network preset's defaults.
+ * @returns The merged runtime configuration.
+ */
+export declare function defaultConfig(network: PresetNetwork, overrides?: Partial<RuntimeConfig>): RuntimeConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GACrC,aAAa,CAEf"}

package/dist/config.js

@@ -0,0 +1,20 @@
+import { networkDefaults, } from '@lightninglabs/wavelength-core';
+/**
+ * Returns a ready-to-use {@link RuntimeConfig} for a network on the React
+ * Native transport, preloaded with the canonical public gRPC host:port
+ * addresses and merged with any overrides. Pass overrides to set dataDir or
+ * point at your own infrastructure, e.g.
+ * `defaultConfig('signet', { dataDir: '/wallet' })`.
+ *
+ * Only the preset networks are accepted (see {@link PresetNetwork}). mainnet
+ * and regtest have no preset: build their config by hand, mainnet with your
+ * own gRPC addresses and allowMainnet, regtest with local addresses and the
+ * insecure-transport flags.
+ *
+ * @param network - The Bitcoin network to build a config for.
+ * @param overrides - Fields that override the network preset's defaults.
+ * @returns The merged runtime configuration.
+ */
+export function defaultConfig(network, overrides = {}) {
+    return { network, ...networkDefaults(network, 'grpc'), ...overrides };
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { type WavelengthClient, type PasskeyCeremony, type DistributiveOmit, type WalletEngine, type WalletEngineOptions } from '@lightninglabs/wavelength-core';
+import { type NativePasskeyCeremonyOptions } from './passkey.ts';
+/**
+ * Creates a {@link WavelengthClient} backed by the React Native transport: the
+ * daemon compiled into the app via the gomobile bindings. Takes no options
+ * today; an options parameter can be added later without a breaking change.
+ */
+export declare function createNativeClient(): WavelengthClient;
+/**
+ * Options for {@link createNativeWalletEngine}. See {@link WalletEngineOptions}
+ * for the config/autoStart field docs; the type requires config when
+ * autoStart is true.
+ */
+export type NativeWalletEngineOptions = DistributiveOmit<WalletEngineOptions, 'client'>;
+/**
+ * Creates a {@link WalletEngine} over the React Native transport: the
+ * one-call setup for an RN app. Pass the engine to WavelengthProvider from
+ * \@lightninglabs/wavelength-react.
+ */
+export declare function createNativeWalletEngine(options?: NativeWalletEngineOptions): WalletEngine;
+/**
+ * Creates the native (Android Credential Manager / iOS AuthenticationServices)
+ * implementation of the {@link PasskeyCeremony} contract; pass it to
+ * useWalletPasskey, or drive it directly. Requires the relying-party domain
+ * to be associated with your app (assetlinks.json on Android, an Associated
+ * Domains entitlement plus apple-app-site-association on iOS). iOS support is
+ * experimental and needs iOS 18 or newer at runtime.
+ */
+export declare function createNativePasskeyCeremony(options: NativePasskeyCeremonyOptions): PasskeyCeremony;
+/**
+ * Resolves the platform default wallet data directory (the same directory
+ * {@link createNativeClient}'s client uses when RuntimeConfig.dataDir is not
+ * set). Exposed for app-level data management: showing the storage location,
+ * backing it up, or deleting it to wipe the wallet.
+ *
+ * Returns a plain absolute filesystem path with no URI scheme; a consumer that
+ * needs a `file://` URL (for example to delete the directory) must add it. The
+ * directory is not guaranteed to exist until the runtime has started.
+ */
+export declare function getDefaultDataDir(): Promise<string>;
+export type { NativePasskeyCeremonyOptions, WavelengthPasskeyNativeModule, } from './passkey.ts';
+export { defaultConfig } from './config.ts';
+export { NativeWavelengthClient } from './client.ts';
+export type { NativeActivityEvent, SubscribeToNativeEvents, WavelengthNativeModule, } from './client.ts';
+export * from '@lightninglabs/wavelength-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,gBAAgB,CAWrD;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,gBAAgB,CACtD,mBAAmB,EACnB,QAAQ,CACT,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,YAAY,CAKd;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,eAAe,CAEjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEnD;AAED,YAAY,EACV,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAIrB,cAAc,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,60 @@
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import { createWalletEngine, } from '@lightninglabs/wavelength-core';
+import NativeWavelength from "./NativeWavelength.js";
+import { NativeWavelengthClient } from "./client.js";
+import { nativePasskeyCeremony, } from "./passkey.js";
+/**
+ * Creates a {@link WavelengthClient} backed by the React Native transport: the
+ * daemon compiled into the app via the gomobile bindings. Takes no options
+ * today; an options parameter can be added later without a breaking change.
+ */
+export function createNativeClient() {
+    // NativeModules.Wavelength is the interop view of the Turbo Module; the
+    // emitter needs it (or any module carrying addListener/removeListeners) to
+    // route 'wavelengthActivity' device events on both platforms.
+    const emitter = new NativeEventEmitter(NativeModules.Wavelength);
+    return new NativeWavelengthClient(NativeWavelength, (listener) => {
+        const subscription = emitter.addListener('wavelengthActivity', listener);
+        return () => subscription.remove();
+    });
+}
+/**
+ * Creates a {@link WalletEngine} over the React Native transport: the
+ * one-call setup for an RN app. Pass the engine to WavelengthProvider from
+ * \@lightninglabs/wavelength-react.
+ */
+export function createNativeWalletEngine(options = {}) {
+    return createWalletEngine({
+        client: createNativeClient(),
+        ...options,
+    });
+}
+/**
+ * Creates the native (Android Credential Manager / iOS AuthenticationServices)
+ * implementation of the {@link PasskeyCeremony} contract; pass it to
+ * useWalletPasskey, or drive it directly. Requires the relying-party domain
+ * to be associated with your app (assetlinks.json on Android, an Associated
+ * Domains entitlement plus apple-app-site-association on iOS). iOS support is
+ * experimental and needs iOS 18 or newer at runtime.
+ */
+export function createNativePasskeyCeremony(options) {
+    return nativePasskeyCeremony(NativeWavelength, options);
+}
+/**
+ * Resolves the platform default wallet data directory (the same directory
+ * {@link createNativeClient}'s client uses when RuntimeConfig.dataDir is not
+ * set). Exposed for app-level data management: showing the storage location,
+ * backing it up, or deleting it to wipe the wallet.
+ *
+ * Returns a plain absolute filesystem path with no URI scheme; a consumer that
+ * needs a `file://` URL (for example to delete the directory) must add it. The
+ * directory is not guaranteed to exist until the runtime has started.
+ */
+export function getDefaultDataDir() {
+    return NativeWavelength.getDefaultDataDir();
+}
+export { defaultConfig } from "./config.js";
+export { NativeWavelengthClient } from "./client.js";
+// Re-export the core contract so an RN consumer can import the client and
+// every type/enum from this one package, the way wavelength-web already does.
+export * from '@lightninglabs/wavelength-core';

package/dist/passkey.d.ts

@@ -0,0 +1,32 @@
+import type { PasskeyCeremony } from '@lightninglabs/wavelength-core';
+/**
+ * The subset of the native Turbo Module the passkey ceremony depends on.
+ * Narrowed to an interface (rather than the generated Spec) so unit tests can
+ * inject a fake without loading react-native.
+ */
+export type WavelengthPasskeyNativeModule = {
+    /** Reports whether the platform can run a passkey PRF ceremony. */
+    passkeySupported(): Promise<boolean>;
+    /** Runs a passkey registration ceremony; WebAuthn JSON in and out. */
+    passkeyCreate(requestJson: string): Promise<string>;
+    /** Runs a passkey assertion ceremony; WebAuthn JSON in and out. */
+    passkeyGet(requestJson: string): Promise<string>;
+};
+/** Options for creating the native passkey ceremony. */
+export type NativePasskeyCeremonyOptions = {
+    /**
+     * The WebAuthn relying-party id: the domain whose
+     * /.well-known/assetlinks.json (Android) and apple-app-site-association
+     * (iOS) vouch for this app. Native apps have no window.location, so the
+     * rpId is explicit configuration.
+     */
+    rpId: string;
+};
+/**
+ * Builds a {@link PasskeyCeremony} over the given native ceremony methods.
+ * The factory in index.ts wires the real Turbo Module; unit tests inject a
+ * fake. Request and response payloads are standard WebAuthn JSON with
+ * base64url binary fields, the format both platform APIs speak natively.
+ */
+export declare function nativePasskeyCeremony(native: WavelengthPasskeyNativeModule, options: NativePasskeyCeremonyOptions): PasskeyCeremony;
+//# sourceMappingURL=passkey.d.ts.map

package/dist/passkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkey.d.ts","sourceRoot":"","sources":["../src/passkey.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,eAAe,EAChB,MAAM,gCAAgC,CAAC;AAgExC;;;;GAIG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,mEAAmE;IACnE,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,sEAAsE;IACtE,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,mEAAmE;IACnE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,6BAA6B,EACrC,OAAO,EAAE,4BAA4B,GACpC,eAAe,CAsGjB"}

package/dist/passkey.js

@@ -0,0 +1,244 @@
+import { PASSKEY_PRF_SALT_HEX, PasskeyCancelledError, } from '@lightninglabs/wavelength-core';
+// Whether a native ceremony rejection means the user dismissed the OS prompt.
+// iOS surfaces ASAuthorizationError code 1001 ("canceled"); Android surfaces
+// GetCredentialCancellationException / CreateCredentialCancellationException
+// with "cancel" in the type or message. Message matching is the only signal
+// that crosses the bridge uniformly, since the bridge flattens native
+// exceptions to a plain Error with no structured code. Known exception type
+// names are matched first, since they are unambiguous; the narrowed
+// "user cancel" regex is a fallback for messages that carry the platform
+// wording without the type name. A bare /cancel/i is deliberately avoided so
+// an unrelated failure whose message merely contains "cancel" (e.g.
+// "cancellation token invalid") is not misclassified as a user cancellation.
+// Follow-up: a native-side sentinel (an error code field rather than message
+// text) would make this exact instead of best-effort.
+function isNativeCancel(err) {
+    const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+    if (/GetCredentialCancellationException/.test(message) ||
+        /CreateCredentialCancellationException/.test(message)) {
+        return true;
+    }
+    if (/ASAuthorizationError/.test(message) && /\b1001\b/.test(message)) {
+        return true;
+    }
+    if (/\berror\s*1001\b/i.test(message)) {
+        return true;
+    }
+    return /\buser.{0,10}cancel/i.test(message);
+}
+// A passkey ceremony that neither resolves nor rejects within this bound has
+// wedged (a silent native provider); reject so useWalletPasskey's
+// createPending/openPending flags cannot stick until an app restart.
+// Generous enough that a real user completing biometrics or a PIN never
+// trips it.
+const PASSKEY_TIMEOUT_MS = 120000;
+// withPasskeyTimeout rejects if the native ceremony call has not settled
+// within PASSKEY_TIMEOUT_MS. It does not cancel the native ceremony; it only
+// unwedges the JavaScript promise.
+function withPasskeyTimeout(op, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`passkey ${label} timed out`)), PASSKEY_TIMEOUT_MS);
+        op.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Builds a {@link PasskeyCeremony} over the given native ceremony methods.
+ * The factory in index.ts wires the real Turbo Module; unit tests inject a
+ * fake. Request and response payloads are standard WebAuthn JSON with
+ * base64url binary fields, the format both platform APIs speak natively.
+ */
+export function nativePasskeyCeremony(native, options) {
+    const saltB64url = hexToBase64Url(PASSKEY_PRF_SALT_HEX);
+    // The memoized probe promise for this ceremony instance. The probe reads
+    // native.passkeySupported(), which does not depend on options (rpId etc.),
+    // but a fresh native module can be wired into a different ceremony
+    // instance, so the memo lives per instance rather than at module scope.
+    let supportsPasskeyPrfProbe = null;
+    const assertPasskeyPrf = async (allowCredentialId) => {
+        const request = {
+            challenge: saltB64url,
+            rpId: options.rpId,
+            allowCredentials: allowCredentialId
+                ? [{ type: 'public-key', id: allowCredentialId }]
+                : [],
+            userVerification: 'required',
+            extensions: { prf: { eval: { first: saltB64url } } },
+        };
+        let responseJson;
+        try {
+            responseJson = await withPasskeyTimeout(native.passkeyGet(JSON.stringify(request)), 'authentication');
+        }
+        catch (err) {
+            throw isNativeCancel(err) ? new PasskeyCancelledError() : err;
+        }
+        const response = JSON.parse(responseJson);
+        return { prfOutput: requirePrfHex(response), credentialId: response.id };
+    };
+    return {
+        // Memoized per ceremony instance: the first call stores the in-flight
+        // probe and every later call reuses it. A rejection is not cached: the
+        // memo is cleared first so a later call retries the probe, and this
+        // call still degrades to false rather than leaving an unhandled
+        // rejection.
+        async supportsPasskeyPrf() {
+            if (!supportsPasskeyPrfProbe) {
+                supportsPasskeyPrfProbe = native.passkeySupported();
+            }
+            try {
+                return await supportsPasskeyPrfProbe;
+            }
+            catch {
+                supportsPasskeyPrfProbe = null;
+                return false;
+            }
+        },
+        async registerPasskeyWallet(appName) {
+            const request = {
+                challenge: saltB64url,
+                rp: { id: options.rpId, name: appName },
+                user: {
+                    id: randomUserIdBase64Url(),
+                    name: appName,
+                    displayName: appName,
+                },
+                pubKeyCredParams: [
+                    { alg: -7, type: 'public-key' },
+                    { alg: -257, type: 'public-key' },
+                ],
+                authenticatorSelection: {
+                    authenticatorAttachment: 'platform',
+                    userVerification: 'required',
+                    residentKey: 'required',
+                },
+                extensions: { prf: { eval: { first: saltB64url } } },
+            };
+            let responseJson;
+            try {
+                responseJson = await withPasskeyTimeout(native.passkeyCreate(JSON.stringify(request)), 'registration');
+            }
+            catch (err) {
+                throw isNativeCancel(err) ? new PasskeyCancelledError() : err;
+            }
+            const response = JSON.parse(responseJson);
+            const first = prfFirst(response);
+            if (first) {
+                return {
+                    prfOutput: prfOutputHex(first),
+                    credentialId: response.id,
+                };
+            }
+            // Some providers do not surface PRF from create; read it with an
+            // assertion scoped to the just-created credential, mirroring the web
+            // ceremony's fallback.
+            return assertPasskeyPrf(response.id);
+        },
+        assertPasskeyPrf,
+    };
+}
+// prfFirst plucks the base64url PRF output from a response, or null.
+function prfFirst(response) {
+    return response?.clientExtensionResults?.prf?.results?.first ?? null;
+}
+// requirePrfHex reads the mandatory PRF output as hex, matching the web
+// ceremony's error when the authenticator did not return one.
+function requirePrfHex(response) {
+    const first = prfFirst(response);
+    if (!first) {
+        throw new Error('passkey PRF extension result was not returned by this authenticator');
+    }
+    return prfOutputHex(first);
+}
+// prfOutputHex decodes a PRF output and requires the WebAuthn-mandated 32
+// bytes: short or padded key material must never reach wallet derivation.
+function prfOutputHex(firstB64url) {
+    const hex = base64UrlToHex(firstB64url);
+    if (hex.length !== 64) {
+        throw new Error('passkey PRF output is not 32 bytes');
+    }
+    return hex;
+}
+// randomUserIdBase64Url makes a fresh 16-byte WebAuthn user handle. user.id
+// is an account identifier, not key material, so cryptographic randomness is
+// not required; crypto.getRandomValues is still preferred when the runtime
+// provides it.
+function randomUserIdBase64Url() {
+    const bytes = new Uint8Array(16);
+    // Typed structurally (not as the DOM lib's Crypto) because this package's
+    // tsconfig targets ES2022 without DOM, matching its Hermes/RN runtime.
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.getRandomValues) {
+        cryptoApi.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = Math.floor(Math.random() * 256);
+        }
+    }
+    return bytesToBase64Url(bytes);
+}
+// The base64url alphabet, indexed by 6-bit value.
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+// hexToBase64Url re-encodes a lower-case hex string as unpadded base64url.
+// Hand-rolled because Hermes offers neither Buffer nor a guaranteed atob.
+function hexToBase64Url(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytesToBase64Url(bytes);
+}
+// base64UrlToHex decodes unpadded base64url and renders lower-case hex.
+function base64UrlToHex(value) {
+    return Array.from(base64UrlToBytes(value))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function bytesToBase64Url(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = i + 1 < bytes.length ? bytes[i + 1] : undefined;
+        const c = i + 2 < bytes.length ? bytes[i + 2] : undefined;
+        out += B64URL[a >> 2];
+        out += B64URL[((a & 0x03) << 4) | ((b ?? 0) >> 4)];
+        if (b !== undefined) {
+            out += B64URL[((b & 0x0f) << 2) | ((c ?? 0) >> 6)];
+        }
+        if (c !== undefined) {
+            out += B64URL[c & 0x3f];
+        }
+    }
+    return out;
+}
+function base64UrlToBytes(value) {
+    // Tolerate standard base64 alphabet and padding so provider quirks cannot
+    // bite, but fail closed on anything else: this decodes wallet key
+    // material, and silently skipping a corrupted character would derive a
+    // different wallet instead of surfacing an error.
+    const normalized = value.replace(/\+/g, '-').replace(/\//g, '_');
+    const out = [];
+    let buffer = 0;
+    let bits = 0;
+    for (const ch of normalized) {
+        const idx = B64URL.indexOf(ch);
+        if (idx < 0) {
+            if (ch === '=' || /\s/.test(ch)) {
+                continue;
+            }
+            throw new Error('malformed base64url payload in passkey response');
+        }
+        buffer = (buffer << 6) | idx;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out.push((buffer >> bits) & 0xff);
+        }
+    }
+    return Uint8Array.from(out);
+}

package/ios/WavelengthModule.h

@@ -0,0 +1,8 @@
+#import <React/RCTEventEmitter.h>
+
+// The codegen spec conformance is declared in the implementation file, not
+// here: this public header must stay pure Objective-C so the pod's Clang
+// module (required by the Swift ceremony source) can build without pulling
+// in C++ codegen headers.
+@interface WavelengthModule : RCTEventEmitter
+@end