@swiftbrowser/native 0.17.6 → 0.17.8

package/src/notifications.ts

@@ -0,0 +1,317 @@
+/**
+ * Notifications in the native app: the browser's `Notification` (the
+ * permission, local notifications and their clicks) and `navigator.setAppBadge`
+ * over the host's UserNotifications (Native/Sources/SwiftBrowserNative/Host/NotificationBridge.swift),
+ * and remote notifications: `registerForPush` resolves with the device token
+ * (APNs, as hex) and `onNotification` delivers what the viewer opened and what
+ * arrived while the app is open.
+ *
+ * ```ts
+ * const token = await registerForPush();
+ * await fetch('/api/devices', { method: 'POST', body: JSON.stringify({ token }) });
+ * useEffect(() => onNotification((n) => { if (n.event === 'opened') show(n.data.postId); }), []);
+ * ```
+ *
+ * In the page (the round trip, or any browser) the host has no bridge for
+ * these: `Notification` is the browser's own, and `registerForPush` subscribes
+ * to Web Push through the site's service worker (`sw.js`, which the web
+ * renderer ships: docs/ops-protocol.md, "Push notifications") with the
+ * `applicationServerKey` given, resolving with the subscription's JSON as
+ * the token; the worker's messages become `onNotification` events. A server
+ * sends to both with one payload: APNs' (`aps.alert`, `aps.badge`), which
+ * the worker reads too.
+ */
+
+import type { NativeBridge } from './bridge';
+
+export type NotificationPermissionState = 'default' | 'granted' | 'denied';
+
+/** What the viewer did with a notification, or one that arrived while the app is open. */
+export interface NotificationEvent {
+  event: 'opened' | 'received';
+  /** Whether it came from the push service. */
+  remote: boolean;
+  /** The notification's identifier (`tag`, or the push payload's `id`). */
+  id: string;
+  title: string;
+  body: string;
+  /** A push's payload, or what `new Notification(title, { data })` gave. */
+  data: Record<string, unknown>;
+  /** `opened`: the action the viewer chose, empty for the notification itself. */
+  action?: string;
+}
+
+export interface NativeNotificationOptions {
+  body?: string;
+  /** The notification's identifier: a later one with the same tag replaces it. */
+  tag?: string;
+  data?: unknown;
+  silent?: boolean;
+  /** The app badge to set with it. */
+  badge?: number;
+}
+
+export interface RegisterForPushOptions {
+  /** The Web Push application server key (the server's VAPID public key, base64url), for the page. */
+  applicationServerKey?: string;
+}
+
+type Listener = (notification: NotificationEvent) => void;
+
+/** The message types the web renderer's service worker posts (Web/public/sw.js). */
+const PUSH_MESSAGE = 'swiftbrowser:push';
+const CLICK_MESSAGE = 'swiftbrowser:notificationclick';
+
+/** The bridge functions notifications need. */
+export type NotificationBridge = Pick<NativeBridge, 'notificationsReady' | 'notificationPermission' | 'notificationShow' | 'notificationClose' | 'setBadge' | 'pushRegister'>;
+
+export interface NotificationGlobals {
+  Notification: NativeNotificationClass;
+  __sbNotificationPermission: (id: number, permission: NotificationPermissionState) => void;
+  __sbPushRegistered: (id: number, result: { token?: string; error?: string }) => void;
+  __sbNotification: (json: string) => void;
+  /** `navigator.setAppBadge` and `clearAppBadge`. */
+  setAppBadge: (count?: number) => Promise<void>;
+  clearAppBadge: () => Promise<void>;
+  /** The native `registerForPush`. */
+  registerForPush: (options?: RegisterForPushOptions) => Promise<string>;
+}
+
+export interface NativeNotificationClass {
+  new (title: string, options?: NativeNotificationOptions): NativeNotificationInstance;
+  readonly permission: NotificationPermissionState;
+  requestPermission(): Promise<NotificationPermissionState>;
+}
+
+export interface NativeNotificationInstance {
+  readonly title: string;
+  readonly body: string;
+  readonly tag: string;
+  readonly data: unknown;
+  onclick: ((event: { notification: NativeNotificationInstance; action: string }) => void) | null;
+  close(): void;
+}
+
+const listeners = new Set<Listener>();
+let pending: NotificationEvent[] = [];
+/** Where the events come from once installed: the bridge, or the page's service worker. */
+let installed: 'native' | 'page' | null = null;
+let nativeRegister: ((options?: RegisterForPushOptions) => Promise<string>) | null = null;
+
+/**
+ * Listens for notifications the viewer opened and ones that arrived while
+ * the app is open; returns what stops listening. Events before any listener
+ * (a tap that launched the app) wait for the first one.
+ */
+export function onNotification(listener: Listener): () => void {
+  listeners.add(listener);
+  if (installed === null && typeof navigator !== 'undefined') listenToPage();
+  if (pending.length > 0) {
+    const events = pending;
+    pending = [];
+    for (const event of events) listener(event);
+  }
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** The runtime's `__sbNotification(json)`, and what the page's worker messages become. */
+export function receiveNotification(event: NotificationEvent): void {
+  if (listeners.size === 0) {
+    pending.push(event);
+    return;
+  }
+  for (const listener of listeners) listener(event);
+}
+
+/**
+ * Registers for remote notifications and resolves with the device token:
+ * APNs' as hex in the native app, the Web Push subscription's JSON in the
+ * page (which needs `applicationServerKey`). Rejects with the reason the
+ * system or the browser refused.
+ */
+export function registerForPush(options: RegisterForPushOptions = {}): Promise<string> {
+  if (nativeRegister) return nativeRegister(options);
+  return registerForWebPush(options);
+}
+
+/** Resets the listeners and the delivery source, for tests. */
+export function resetNotifications(): void {
+  listeners.clear();
+  pending = [];
+  installed = null;
+  nativeRegister = null;
+}
+
+// MARK: The native app
+
+/** The globals for a host with the notification bridge. */
+export function createNotificationGlobals(native: NotificationBridge): NotificationGlobals {
+  installed = 'native';
+  let permission: NotificationPermissionState = 'default';
+  let nextId = 1;
+  const permissionWaits = new Map<number, (permission: NotificationPermissionState) => void>();
+  const registrations = new Map<number, { resolve: (token: string) => void; reject: (error: Error) => void }>();
+  const open = new Map<string, NativeNotification>();
+
+  const askPermission = (request: boolean): Promise<NotificationPermissionState> =>
+    new Promise((resolve) => {
+      const id = nextId++;
+      permissionWaits.set(id, resolve);
+      native.notificationPermission?.(id, request);
+    });
+
+  class NativeNotification implements NativeNotificationInstance {
+    static get permission(): NotificationPermissionState {
+      return permission;
+    }
+
+    static requestPermission(): Promise<NotificationPermissionState> {
+      return askPermission(true);
+    }
+
+    readonly title: string;
+    readonly body: string;
+    readonly tag: string;
+    readonly data: unknown;
+    onclick: NativeNotificationInstance['onclick'] = null;
+
+    constructor(title: string, options: NativeNotificationOptions = {}) {
+      this.title = String(title);
+      this.body = options.body ?? '';
+      this.tag = options.tag ?? `notification-${nextId++}`;
+      this.data = options.data;
+      const show: Record<string, unknown> = { id: this.tag, title: this.title, body: this.body, silent: options.silent ?? false };
+      if (options.badge !== undefined) show['badge'] = options.badge;
+      if (options.data !== undefined && typeof options.data === 'object' && options.data !== null) show['data'] = options.data;
+      const problem = native.notificationShow?.(JSON.stringify(show));
+      if (problem) throw new TypeError(problem);
+      open.set(this.tag, this);
+    }
+
+    close(): void {
+      if (open.get(this.tag) === this) open.delete(this.tag);
+      native.notificationClose?.(JSON.stringify([this.tag]));
+    }
+  }
+
+  const setAppBadge = async (count = 0): Promise<void> => {
+    native.setBadge?.(Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0);
+  };
+
+  nativeRegister = (options = {}) =>
+    new Promise<string>((resolve, reject) => {
+      const id = nextId++;
+      registrations.set(id, { resolve, reject });
+      native.pushRegister?.(id, options.applicationServerKey);
+    });
+
+  // The permission as it stands, so `Notification.permission` reads right
+  // from the first render; and the app listens, so what came before arrives.
+  void askPermission(false);
+  native.notificationsReady?.();
+
+  return {
+    Notification: NativeNotification,
+    __sbNotificationPermission: (id, state) => {
+      permission = state;
+      const resolve = permissionWaits.get(id);
+      permissionWaits.delete(id);
+      resolve?.(state);
+    },
+    __sbPushRegistered: (id, result) => {
+      const registration = registrations.get(id);
+      registrations.delete(id);
+      if (!registration) return;
+      if (typeof result.token === 'string') registration.resolve(result.token);
+      else registration.reject(new Error(result.error ?? 'push: registration failed'));
+    },
+    __sbNotification: (json) => {
+      let event: NotificationEvent;
+      try {
+        event = JSON.parse(json) as NotificationEvent;
+      } catch {
+        return;
+      }
+      if (event.event === 'opened') {
+        const notification = open.get(event.id);
+        if (notification) {
+          open.delete(event.id);
+          notification.onclick?.({ notification, action: event.action ?? '' });
+        }
+      }
+      receiveNotification(event);
+    },
+    setAppBadge,
+    clearAppBadge: () => setAppBadge(0),
+    registerForPush: nativeRegister,
+  };
+}
+
+// MARK: The page
+
+/** The event a service worker message carries (Web/src/notifications.ts), or null. */
+export function notificationEventOf(data: unknown): NotificationEvent | null {
+  if (typeof data !== 'object' || data === null) return null;
+  const message = data as { type?: unknown; payload?: unknown; action?: unknown };
+  if (message.type !== PUSH_MESSAGE && message.type !== CLICK_MESSAGE) return null;
+  const payload = typeof message.payload === 'object' && message.payload !== null ? (message.payload as Record<string, unknown>) : {};
+  const aps = typeof payload['aps'] === 'object' && payload['aps'] !== null ? (payload['aps'] as Record<string, unknown>) : {};
+  const alert = typeof aps['alert'] === 'object' && aps['alert'] !== null ? (aps['alert'] as Record<string, unknown>) : {};
+  const text = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
+  const event: NotificationEvent = {
+    event: message.type === CLICK_MESSAGE ? 'opened' : 'received',
+    remote: true,
+    id: text(payload['id']) ?? text(payload['tag']) ?? '',
+    title: text(payload['title']) ?? text(alert['title']) ?? '',
+    body: text(payload['body']) ?? text(alert['body']) ?? text(aps['alert']) ?? '',
+    data: payload,
+  };
+  if (message.type === CLICK_MESSAGE) event.action = typeof message.action === 'string' ? message.action : '';
+  return event;
+}
+
+function listenToPage(): void {
+  installed = 'page';
+  const container = navigator.serviceWorker;
+  if (!container || typeof container.addEventListener !== 'function') return;
+  container.addEventListener('message', (message: MessageEvent) => {
+    const event = notificationEventOf(message.data);
+    if (event) receiveNotification(event);
+  });
+}
+
+/** A VAPID public key (base64url) as the bytes `subscribe` takes. */
+function keyBytes(key: string): Uint8Array<ArrayBuffer> {
+  const base64 = key.replace(/-/g, '+').replace(/_/g, '/');
+  const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function registerForWebPush(options: RegisterForPushOptions): Promise<string> {
+  if (typeof navigator === 'undefined' || !navigator.serviceWorker || typeof PushManager === 'undefined') {
+    throw new Error('push: this browser has no push service');
+  }
+  if (!options.applicationServerKey) throw new Error('push: no applicationServerKey');
+  if (typeof Notification !== 'undefined' && Notification.permission === 'default') await Notification.requestPermission();
+  if (typeof Notification !== 'undefined' && Notification.permission !== 'granted') throw new Error('push: notifications are not allowed');
+  if (installed === null) listenToPage();
+  const scope = new URL('./', typeof document !== 'undefined' ? document.baseURI : location.href).href;
+  const existing = await navigator.serviceWorker.getRegistration(scope);
+  const registration = existing?.active && existing.scope === scope ? existing : await navigator.serviceWorker.register(new URL('sw.js', scope).href, { scope });
+  await navigator.serviceWorker.ready;
+  const init: PushSubscriptionOptionsInit = { userVisibleOnly: true, applicationServerKey: keyBytes(options.applicationServerKey) };
+  const current = await registration.pushManager.getSubscription();
+  let subscription: PushSubscription;
+  try {
+    subscription = current ?? (await registration.pushManager.subscribe(init));
+  } catch (error) {
+    if (!current) throw error;
+    await current.unsubscribe().catch(() => undefined);
+    subscription = await registration.pushManager.subscribe(init);
+  }
+  return JSON.stringify(subscription.toJSON());
+}

package/src/run.ts

@@ -11,7 +11,10 @@
 import { createSwiftUIRoot, type SwiftUIRoot } from '@swiftbrowser/react';
 import type { Op, RendererEvent } from '@swiftbrowser/web/src/protocol';
 import type { ReactNode } from 'react';
+import { browserEnvironment } from '@swiftbrowser/web/src/hostRequests';
 import { nativeBridge, type NativeBridge } from './bridge';
+import { installHostEnvironment } from './hostRequests';
+import { updateMediaEnvironment } from './matchMedia';
 
 export interface RunOptions {
   /** The bridge to render through; the global `__sbNative` by default. */
@@ -41,6 +44,9 @@ export function run(element: ReactNode, options: RunOptions = {}): Running {
   const native = options.native ?? nativeBridge();
   if (!native) throw new Error('run(): no native bridge (__sbNative); this entry runs inside a SwiftBrowser Native app');
   const report = options.onError ?? ((error: unknown) => native.log('error', error instanceof Error ? (error.stack ?? error.message) : String(error)));
+  // What `ShareLink`, `fileImporter` and the clipboard ask the browser for,
+  // answered by the host where the page has nothing (hostRequests.ts).
+  installHostEnvironment(browserEnvironment as unknown as Record<string, unknown>);
 
   if (current) {
     // Fast Refresh (devBuild.ts): the app bundle was evaluated again. Its
@@ -68,7 +74,10 @@ export function run(element: ReactNode, options: RunOptions = {}): Running {
       if (parsed.type === 'environment') {
         const fields = parsed as EnvironmentFields;
         const next: Partial<{ colorScheme: 'light' | 'dark'; dynamicTypeSize: never; horizontalSizeClass: 'compact' | 'regular' }> = {};
-        if (fields.colorScheme) next.colorScheme = fields.colorScheme;
+        if (fields.colorScheme) {
+          next.colorScheme = fields.colorScheme;
+          updateMediaEnvironment({ colorScheme: fields.colorScheme });
+        }
         if (fields.dynamicTypeSize) (next as Record<string, unknown>)['dynamicTypeSize'] = fields.dynamicTypeSize;
         if (fields.horizontalSizeClass) next.horizontalSizeClass = fields.horizontalSizeClass;
         if (Object.keys(next).length > 0) root.setEnvironment(next);

package/src/runtime.ts

@@ -11,9 +11,11 @@
  * `atob`, `btoa`, `fetch` with `Headers`, `Request`, `Response`,
  * `AbortController` and `AbortSignal`, `URL`, `URLSearchParams`, `crypto`
  * (`getRandomValues`, `randomUUID`), `localStorage`, `structuredClone`,
- * `navigator`, `Image` (image.ts, on a bridge with `probeImage`) with the
+ * `navigator` (with `mediaSession` and `MediaMetadata` on a bridge with
+ * `mediaSession`, mediaSession.ts), `Image` (image.ts, on a bridge with `probeImage`) with the
  * bridge's `__sbImageProbed`, `Worker` (worker.ts) with the bridge's
  * `__sbWorkerMessage` and `__sbWorkerError`, `__sbOpenURL` (openURL.ts),
+ * `__sbNotificationPermission`, `__sbPushRegistered` and `__sbNotification` (notifications.ts),
  * and the bridge's callbacks `__sbTimerFired` and `__sbFetchResult`. In a
  * worker's own context (its bridge has
  * `workerPostMessage`), `self`, `postMessage`, `addEventListener` and
@@ -28,7 +30,15 @@ import { createFetch } from './fetch';
 import { createImageGlobals } from './image';
 import { SimpleURL, SimpleURLSearchParams } from './url';
 import { installWorkerScope, NativeWorker } from './worker';
+import { createMediaSession, NativeMediaMetadata } from './mediaSession';
+import { createNotificationGlobals } from './notifications';
 import { receiveOpenURL } from './openURL';
+import { objectURL, SimpleBlob, SimpleFile, SimpleFormData } from './blob';
+import { setBodyRandomness } from './fetch';
+import { NativeWebSocket } from './webSocket';
+import { createSubtleCrypto } from './subtle';
+import { matchMedia } from './matchMedia';
+import { installHostRequests, receiveHostResponse } from './hostRequests';
 
 type AnyGlobal = Record<string, unknown>;
 
@@ -170,6 +180,35 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
   define('URL', SimpleURL);
   define('URLSearchParams', SimpleURLSearchParams);
 
+  // Bytes with a type, files and forms (blob.ts): what `fetch` uploads, and
+  // what a picked file or a built image is. `URL.createObjectURL` is a `data:` URL.
+  define('Blob', SimpleBlob);
+  define('File', SimpleFile);
+  define('FormData', SimpleFormData);
+  const urlStatics = target['URL'] as { createObjectURL?: unknown; revokeObjectURL?: unknown };
+  if (urlStatics && typeof urlStatics.createObjectURL !== 'function') {
+    urlStatics.createObjectURL = (blob: SimpleBlob) => objectURL(blob);
+    urlStatics.revokeObjectURL = () => {};
+  }
+  const random = (count: number): Uint8Array => base64Decode(native.randomBytes(count));
+  setBodyRandomness(random);
+
+  // WebSockets (webSocket.ts) over the host's `URLSessionWebSocketTask`.
+  if (native.wsOpen && native.wsSend && native.wsClose) {
+    NativeWebSocket.install({ wsOpen: native.wsOpen.bind(native), wsSend: native.wsSend.bind(native), wsClose: native.wsClose.bind(native) });
+    define('WebSocket', NativeWebSocket);
+    define('__sbWebSocketEvent', NativeWebSocket.receive);
+  }
+
+  // `matchMedia`: the color scheme the host sends (run.ts), nothing else.
+  define('matchMedia', matchMedia);
+
+  // Host requests (hostRequests.ts): the share sheet, the pickers, the pasteboard, a sign-in.
+  if (native.hostRequest && !native.workerPostMessage) {
+    installHostRequests({ hostRequest: native.hostRequest.bind(native) });
+    define('__sbHostResponse', receiveHostResponse);
+  }
+
   // `Image`, for code that loads a picture to learn its size (React's
   // `AsyncImage`): the host reads it through its image loader.
   if (native.probeImage && !native.workerPostMessage) {
@@ -184,6 +223,8 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
       new Uint8Array(array.buffer, array.byteOffset, array.byteLength).set(bytes.subarray(0, array.byteLength));
       return array;
     },
+    // Digests and HMAC on the host's CryptoKit (subtle.ts).
+    subtle: createSubtleCrypto(native),
     randomUUID: (): string => {
       const bytes = base64Decode(native.randomBytes(16));
       bytes[6] = (bytes[6]! & 0x0f) | 0x40;
@@ -207,14 +248,43 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
 
   define('structuredClone', <T>(value: T): T => (value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T)));
 
-  define('navigator', {
+  const navigator: Record<string, unknown> = {
     userAgent: 'SwiftBrowserNative',
     language: native.locale().replace('_', '-'),
     languages: [native.locale().replace('_', '-')],
     onLine: true,
     platform: 'iOS',
     hardwareConcurrency: 1,
-  });
+    // A haptic for a vibration; the pattern's length does not matter.
+    vibrate: (pattern: number | number[]): boolean => {
+      if (!native.haptic) return false;
+      const length = Array.isArray(pattern) ? pattern.reduce((sum, ms) => sum + Number(ms), 0) : Number(pattern);
+      if (!(length > 0)) return true;
+      native.haptic(length >= 200 ? 'impact' : 'selection');
+      return true;
+    },
+  };
+  // What plays, for the lock screen and the media keys (mediaSession.ts); not in a worker.
+  const mediaSession = native.mediaSession && !native.workerPostMessage ? createMediaSession(native) : null;
+  if (mediaSession) navigator['mediaSession'] = mediaSession.session;
+  // Notifications (notifications.ts): the browser's `Notification` and the
+  // badge over UserNotifications, and the push registration; not in a worker.
+  const notifications = native.notificationShow && !native.workerPostMessage ? createNotificationGlobals(native) : null;
+  if (notifications) {
+    navigator['setAppBadge'] = notifications.setAppBadge;
+    navigator['clearAppBadge'] = notifications.clearAppBadge;
+  }
+  define('navigator', navigator);
+  if (mediaSession) {
+    define('MediaMetadata', NativeMediaMetadata);
+    define('__sbMediaSessionCommand', mediaSession.receive);
+  }
+  if (notifications) {
+    define('Notification', notifications.Notification);
+    define('__sbNotificationPermission', notifications.__sbNotificationPermission);
+    define('__sbPushRegistered', notifications.__sbPushRegistered);
+    define('__sbNotification', notifications.__sbNotification);
+  }
 
   if (native.workerPostMessage) {
     installed.push(...installWorkerScope(native, target));

package/src/secureStorage.ts

@@ -0,0 +1,39 @@
+/**
+ * `secureStorage`: `localStorage`'s shape over the Keychain, for what must
+ * not sit in plain text (a session token). The host's `secureGet`,
+ * `secureSet` and `secureRemove` are generic-password items of the app's
+ * (`kSecAttrAccessibleAfterFirstUnlock`, so a background fetch can read
+ * them). In the page (the round trip, or a browser) there is no Keychain:
+ * the values go to `localStorage` under a prefix, as a web app keeps them.
+ */
+
+import { nativeBridge, type NativeBridge } from './bridge';
+
+export type SecureStorageBridge = Pick<NativeBridge, 'secureGet' | 'secureSet' | 'secureRemove'>;
+
+export interface SecureStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+const PREFIX = 'swiftbrowser.secure.';
+
+/** Secure storage over `native`, or over `localStorage` when the host has no Keychain. */
+export function createSecureStorage(native: SecureStorageBridge | undefined, fallback: () => Storage | undefined): SecureStorage {
+  if (native?.secureGet && native.secureSet && native.secureRemove) {
+    return {
+      getItem: (key) => native.secureGet!(String(key)),
+      setItem: (key, value) => native.secureSet!(String(key), String(value)),
+      removeItem: (key) => native.secureRemove!(String(key)),
+    };
+  }
+  return {
+    getItem: (key) => fallback()?.getItem(PREFIX + String(key)) ?? null,
+    setItem: (key, value) => fallback()?.setItem(PREFIX + String(key), String(value)),
+    removeItem: (key) => fallback()?.removeItem(PREFIX + String(key)),
+  };
+}
+
+/** The app's secure storage: the Keychain in the native app, `localStorage` in the page. */
+export const secureStorage: SecureStorage = createSecureStorage(nativeBridge(), () => (typeof localStorage === 'undefined' ? undefined : localStorage));

package/src/subtle.ts

@@ -0,0 +1,87 @@
+/**
+ * `crypto.subtle` for the native app, as far as apps use it for a PKCE
+ * challenge or a signature: `digest` (SHA-1, SHA-256, SHA-384, SHA-512) and
+ * HMAC keys with `importKey`, `sign` and `verify`, over the bridge's
+ * `digest` and `hmac` (CryptoKit on the Swift side). Both are synchronous
+ * there; the promises resolve at once.
+ */
+
+import type { NativeBridge } from './bridge';
+import { base64Decode, base64Encode } from './encoding';
+
+export type SubtleBridge = Pick<NativeBridge, 'digest' | 'hmac'>;
+
+type Algorithm = string | { name: string; hash?: string | { name: string } };
+
+interface HmacKey {
+  type: 'secret';
+  extractable: boolean;
+  algorithm: { name: 'HMAC'; hash: { name: string }; length: number };
+  usages: string[];
+  /** The key's bytes, kept here: the host signs with them each time. */
+  readonly bytes: Uint8Array;
+}
+
+const DIGESTS = new Set(['SHA-1', 'SHA-256', 'SHA-384', 'SHA-512']);
+
+function algorithmName(algorithm: Algorithm): string {
+  return (typeof algorithm === 'string' ? algorithm : algorithm.name).toUpperCase();
+}
+
+function hashName(algorithm: Algorithm): string {
+  if (typeof algorithm === 'string') return algorithm.toUpperCase();
+  const hash = algorithm.hash;
+  return (typeof hash === 'string' ? hash : hash?.name ?? '').toUpperCase();
+}
+
+function bytesOf(data: ArrayBuffer | ArrayBufferView): Uint8Array {
+  return data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+
+function toBuffer(base64: string): ArrayBuffer {
+  const bytes = base64Decode(base64);
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+function notSupported(what: string): Error {
+  const error = new Error(`crypto.subtle: ${what} is not supported in the native app`);
+  error.name = 'NotSupportedError';
+  return error;
+}
+
+/** `crypto.subtle` over the bridge. */
+export function createSubtleCrypto(native: SubtleBridge) {
+  return {
+    async digest(algorithm: Algorithm, data: ArrayBuffer | ArrayBufferView): Promise<ArrayBuffer> {
+      const name = algorithmName(algorithm);
+      if (!DIGESTS.has(name)) throw notSupported(`the ${name} digest`);
+      const result = native.digest?.(name, base64Encode(bytesOf(data)));
+      if (!result) throw notSupported(`the ${name} digest`);
+      return toBuffer(result);
+    },
+
+    async importKey(format: string, keyData: ArrayBuffer | ArrayBufferView, algorithm: Algorithm, extractable: boolean, usages: string[]): Promise<HmacKey> {
+      if (format !== 'raw' || algorithmName(algorithm) !== 'HMAC') throw notSupported(`importing a ${format} ${algorithmName(algorithm)} key`);
+      const hash = hashName(algorithm);
+      if (!DIGESTS.has(hash)) throw notSupported(`HMAC with ${hash}`);
+      const bytes = bytesOf(keyData);
+      return { type: 'secret', extractable, algorithm: { name: 'HMAC', hash: { name: hash }, length: bytes.byteLength * 8 }, usages: [...usages], bytes };
+    },
+
+    async sign(algorithm: Algorithm, key: HmacKey, data: ArrayBuffer | ArrayBufferView): Promise<ArrayBuffer> {
+      if (algorithmName(algorithm) !== 'HMAC' || key.algorithm?.name !== 'HMAC') throw notSupported(`signing with ${algorithmName(algorithm)}`);
+      const result = native.hmac?.(key.algorithm.hash.name, base64Encode(key.bytes), base64Encode(bytesOf(data)));
+      if (!result) throw notSupported('HMAC');
+      return toBuffer(result);
+    },
+
+    async verify(algorithm: Algorithm, key: HmacKey, signature: ArrayBuffer | ArrayBufferView, data: ArrayBuffer | ArrayBufferView): Promise<boolean> {
+      const expected = new Uint8Array(await this.sign(algorithm, key, data));
+      const given = bytesOf(signature);
+      if (expected.byteLength !== given.byteLength) return false;
+      let difference = 0;
+      for (let i = 0; i < expected.byteLength; i += 1) difference |= expected[i]! ^ given[i]!;
+      return difference === 0;
+    },
+  };
+}