@1shotapi/ows-signer 0.2.2 → 0.3.0

package/README.md

@@ -37,17 +37,20 @@ Only accepts messages when `event.source === window.parent`. Replies use the par
 | Method | Params | Success events |
 |--------|--------|----------------|
 | `getVersion` | — | `Version` |
-| `createCredential` | `name`, `options?` (`rpName`, `userDisplayName`, `userId`) | `KeyDerived`, `CredentialCreated` |
-| `signDigest` | `digestData`, `scheme`, `credentialId?` | `KeyDerived` (PRF path), `DigestSigned` |
-| `revealPrivateKey` | `credentialId?` | `KeyDerived` (+ DOM display) |
-| `createRecoveryData` | `passwordText`, `buttonText`, `minPasswordLength`, `credentialId?` | `KeyDerived`, `RecoveryDataCreated` |
-| `recoverKey` | `aes256EncryptedPrivateKey`, `passwordText`, `buttonText`, `credentialId?` | DOM display; `RecoverySessionStarted` or re-bind → `RecoverySessionCleared` |
-| `getPublicKey` | `credentialId?`, `challenge?` | `KeyDerived`, `PublicKey`, `ChallengeSigned?` |
+| `createCredential` | `name`, `options?` (incl. ceremony UI) | `KeyDerived`, `CredentialCreated` |
+| `signDigest` | `digests[]`, `credentialId?`, ceremony UI? | `KeyDerived` (PRF path), `DigestSigned` (`results[]`) |
+| `executeBatch` | batch fields + ceremony UI? | `KeyDerived` (when keys derived), `BatchExecuted` |
+| `revealPrivateKey` | `credentialId?`, ceremony UI? | `KeyDerived` (+ DOM display) |
+| `createRecoveryData` | passphrase fields + ceremony UI? | `KeyDerived`, `RecoveryDataCreated` |
+| `recoverKey` | envelope + passphrase fields + ceremony UI? | DOM display; `RecoverySessionStarted` or re-bind → `RecoverySessionCleared` |
+| `getPublicKey` | `credentialId?`, `challenge?`, ceremony UI? | `KeyDerived`, `PublicKey`, `ChallengeSigned?` |
 | `clearRecoverySession` | — | `RecoverySessionCleared` |
-| `encryptAES256` | `plaintexts[]`, `credentialId?` | `KeyDerived` (PRF path), `AES256Encrypted` |
-| `decryptAES256` | `ciphertexts[]`, `credentialId?` | `KeyDerived` (PRF path), `AES256Decrypted` |
+| `encryptAES256` | `plaintexts[]`, `credentialId?`, ceremony UI? | `KeyDerived` (PRF path), `AES256Encrypted` |
+| `decryptAES256` | `ciphertexts[]`, `credentialId?`, ceremony UI? | `KeyDerived` (PRF path), `AES256Decrypted` |
 
-Failure events: `NotAllowed`, `InvalidRequest`.
+Failure events: `SignDenied` (user cancelled Confirm UI), `NotAllowed` (WebAuthn cancel/policy), `InvalidRequest`.
+
+Ceremony UI params (optional on WebAuthn-triggering methods): `explanationHeader`, `explanationText`, `confirmButtonText`, `denyButtonText`. Defaults: “Confirm passkey” / “Your device will ask for a passkey to continue.” / “Continue” / “Cancel”. Confirm click starts WebAuthn in the same turn (mobile activation).
 
 `createCredential` options:
 
@@ -59,7 +62,7 @@ Failure events: `NotAllowed`, `InvalidRequest`.
 
 `secp256k1-ecdsa`, `secp256k1-ecdsa-recoverable`, `secp256k1-bip340` (not yet implemented), `ed25519`.
 
-`digestData` is `0x`-prefixed hex. Hash schemes require 32 bytes.
+`digestData` is `0x`-prefixed hex. Hash schemes require 32 bytes. `signDigest` and `executeBatch` take **arrays** of digests so one passkey ceremony covers many signatures. Empty `digests` arrays succeed without a ceremony. `executeBatch` with a `challenge` always forces a real WebAuthn assertion (recovery session alone cannot produce an assertion signature).
 
 ## PRF labels
 
@@ -77,7 +80,7 @@ Failure events: `NotAllowed`, `InvalidRequest`.
 
 ## Recovery session
 
-`recoverKey` caches the secp256k1 scalar in memory for subsequent `signDigest` / `encryptAES256` / `decryptAES256` calls without PRF. Cleared via `clearRecoverySession` or successful `credentialId` re-bind after recovery.
+`recoverKey` caches the secp256k1 scalar in memory for subsequent `signDigest` / `encryptAES256` / `decryptAES256` / `executeBatch` (without `challenge`) calls without PRF. Cleared via `clearRecoverySession` or successful `credentialId` re-bind after recovery.
 
 ## Layout
 

package/html/index.html

@@ -9,15 +9,28 @@
       color-scheme: light dark;
       font-family: system-ui, sans-serif;
     }
+    html,
     body {
+      height: 100%;
       margin: 0;
-      padding: 8px;
+      overflow: hidden;
+    }
+    body {
+      box-sizing: border-box;
     }
     .ows-signer-ui {
       display: flex;
       flex-direction: column;
       gap: 8px;
+      box-sizing: border-box;
+      width: 100%;
+      height: 100%;
       max-width: 100%;
+      padding: 12px;
+      overflow: hidden;
+    }
+    .ows-signer-ui--ceremony {
+      gap: 0;
     }
     .ows-key {
       margin: 0;
@@ -28,6 +41,9 @@
       font-size: 12px;
       word-break: break-all;
       white-space: pre-wrap;
+      overflow: auto;
+      flex: 1 1 auto;
+      min-height: 0;
     }
     .ows-password {
       padding: 8px;
@@ -35,8 +51,35 @@
       border-radius: 4px;
       font: inherit;
     }
+    .ows-ceremony-header {
+      flex: 0 0 auto;
+      margin: 0 0 8px;
+      font-size: 1.1rem;
+      font-weight: 700;
+      line-height: 1.3;
+    }
+    .ows-ceremony-body {
+      flex: 1 1 auto;
+      min-height: 0;
+      overflow-x: hidden;
+      overflow-y: auto;
+      margin: 0 0 12px;
+    }
+    .ows-ceremony-text {
+      margin: 0;
+      font-size: 0.95rem;
+      line-height: 1.4;
+      opacity: 0.9;
+    }
+    .ows-ceremony-actions {
+      flex: 0 0 auto;
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+    }
     .ows-copy,
-    .ows-confirm {
+    .ows-confirm,
+    .ows-deny {
       padding: 8px 12px;
       border: 1px solid #8884;
       border-radius: 4px;
@@ -45,6 +88,14 @@
       cursor: pointer;
       align-self: flex-start;
     }
+    .ows-confirm {
+      font-weight: 600;
+    }
+    .ows-confirm:disabled,
+    .ows-deny:disabled {
+      opacity: 0.45;
+      cursor: default;
+    }
   </style>
 </head>
 <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1shotapi/ows-signer",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "OWS Signing Layer — plain JavaScript WebAuthn PRF key custody with curve-based signing (on-chain via EIP-8244)",
   "type": "module",
   "files": [

package/src/constants.js

@@ -27,4 +27,5 @@ export const METHODS = [
   "clearRecoverySession",
   "encryptAES256",
   "decryptAES256",
+  "executeBatch",
 ];

package/src/handlers.js

@@ -30,7 +30,7 @@ import {
   withCeremony,
   zeroize,
 } from "./state.js";
-import { clearUi, promptPassphrase, showPrivateKey } from "./ui.js";
+import { clearUi, CeremonyDeniedError, promptCeremonyConfirm, promptPassphrase, showPrivateKey } from "./ui.js";
 import {
   createPasskeyCredential,
   getAssertionSignatureBase64Url,
@@ -157,12 +157,34 @@ export async function handleRequest(
       case "decryptAES256":
         await handleDecryptAES256(params, correlationId, targetOrigin);
         return;
+
+      case "executeBatch":
+        await handleExecuteBatch(params, correlationId, targetOrigin);
+        return;
     }
   } catch (error) {
     handleError(error, correlationId, targetOrigin);
   }
 }
 
+/**
+ * @param {Record<string, unknown>} params
+ * @returns {{
+ *   explanationHeader?: unknown,
+ *   explanationText?: unknown,
+ *   confirmButtonText?: unknown,
+ *   denyButtonText?: unknown,
+ * }}
+ */
+function ceremonyFieldsFromParams(params) {
+  return {
+    explanationHeader: params.explanationHeader,
+    explanationText: params.explanationText,
+    confirmButtonText: params.confirmButtonText,
+    denyButtonText: params.denyButtonText,
+  };
+}
+
 /**
  * PRF bytes are returned on assertion (`prf.eval`), not registration (`prf.enable`).
  * Some platforms may return results on create; otherwise run a follow-up get.
@@ -184,6 +206,7 @@ async function credentialForKeyDerivation(credential, credentialId) {
   debugLog("no PRF results on registration; running assertion with prf.eval", {
     credentialId: id,
   });
+  // Same RPC — no second Confirm (one screen per call).
   const assertion = await getPasskeyAssertion(undefined, id);
   debugLog(
     "assertion extension results",
@@ -205,13 +228,15 @@ async function handleCreateCredential(params, correlationId, targetOrigin) {
   }
   const options =
     params.options && typeof params.options === "object"
-      ? /** @type {{ rpName?: string, userDisplayName?: string, userId?: string }} */ (
+      ? /** @type {{ rpName?: string, userDisplayName?: string, userId?: string, explanationHeader?: string, explanationText?: string, confirmButtonText?: string, denyButtonText?: string }} */ (
           params.options
         )
       : {};
 
   await withCeremony(async () => {
-    const credential = await createPasskeyCredential(name, options);
+    const credential = await promptCeremonyConfirm(options, () =>
+      createPasskeyCredential(name, options),
+    );
     const credentialId = getCredentialId(credential);
     const prfCredential = await credentialForKeyDerivation(
       credential,
@@ -234,58 +259,146 @@ async function handleCreateCredential(params, correlationId, targetOrigin) {
   });
 }
 
+/**
+ * @typedef {{
+ *   digestData: string,
+ *   scheme: import('./constants.js').SignScheme,
+ *   digest: Uint8Array,
+ * }} ParsedDigestItem
+ */
+
+/**
+ * @param {unknown} digests
+ * @returns {{ ok: true, items: ParsedDigestItem[] } | { ok: false, reason: string }}
+ */
+function parseDigestItems(digests) {
+  if (!Array.isArray(digests)) {
+    return { ok: false, reason: "invalidParams" };
+  }
+  /** @type {ParsedDigestItem[]} */
+  const items = [];
+  for (const entry of digests) {
+    if (!entry || typeof entry !== "object") {
+      return { ok: false, reason: "invalidParams" };
+    }
+    const record = /** @type {Record<string, unknown>} */ (entry);
+    const digestData = record.digestData;
+    const scheme = record.scheme;
+    if (typeof digestData !== "string" || typeof scheme !== "string") {
+      return { ok: false, reason: "invalidParams" };
+    }
+    if (
+      !SIGN_SCHEMES.includes(
+        /** @type {import('./constants.js').SignScheme} */ (scheme),
+      )
+    ) {
+      return { ok: false, reason: "unknownScheme" };
+    }
+    const digest = parse0xHex(digestData);
+    try {
+      validateSignPayload(
+        /** @type {import('./constants.js').SignScheme} */ (scheme),
+        digest,
+      );
+    } catch (error) {
+      return {
+        ok: false,
+        reason: error instanceof Error ? error.message : "invalidPayload",
+      };
+    }
+    items.push({
+      digestData,
+      scheme: /** @type {import('./constants.js').SignScheme} */ (scheme),
+      digest,
+    });
+  }
+  return { ok: true, items };
+}
+
+/**
+ * @param {ParsedDigestItem[]} items
+ * @param {Uint8Array} secp256k1PrivateKey
+ * @param {Uint8Array} ed25519Seed
+ * @param {string | null} credentialId
+ * @returns {Promise<Array<{
+ *   digest: string,
+ *   scheme: string,
+ *   signature: string,
+ *   credentialId: string | null,
+ * }>>}
+ */
+async function signParsedDigests(
+  items,
+  secp256k1PrivateKey,
+  ed25519Seed,
+  credentialId,
+) {
+  /** @type {Array<{ digest: string, scheme: string, signature: string, credentialId: string | null }>} */
+  const results = [];
+  for (const item of items) {
+    const signature = await signWithScheme(
+      item.scheme,
+      item.digest,
+      secp256k1PrivateKey,
+      ed25519Seed,
+    );
+    results.push({
+      digest: item.digestData,
+      scheme: item.scheme,
+      signature,
+      credentialId,
+    });
+  }
+  return results;
+}
+
 /**
  * @param {Record<string, unknown>} params
  * @param {string | undefined} correlationId
  * @param {string} targetOrigin
  */
 async function handleSignDigest(params, correlationId, targetOrigin) {
-  const digestData = params.digestData;
-  const scheme = params.scheme;
   const credentialId =
     typeof params.credentialId === "string" ? params.credentialId : undefined;
-
-  if (typeof digestData !== "string" || typeof scheme !== "string") {
-    emitInvalid(correlationId, targetOrigin, "invalidParams");
+  const parsed = parseDigestItems(params.digests);
+  if (!parsed.ok) {
+    emitInvalid(correlationId, targetOrigin, parsed.reason);
     return;
   }
-  if (
-    !SIGN_SCHEMES.includes(
-      /** @type {import('./constants.js').SignScheme} */ (scheme),
-    )
-  ) {
-    emitInvalid(correlationId, targetOrigin, "unknownScheme");
+  const { items } = parsed;
+
+  if (items.length === 0) {
+    emitEvent(window.parent, targetOrigin, "DigestSigned", correlationId, {
+      results: [],
+    });
     return;
   }
 
-  const digest = parse0xHex(digestData);
-  validateSignPayload(
-    /** @type {import('./constants.js').SignScheme} */ (scheme),
-    digest,
-  );
-
   if (hasRecoverySession()) {
     const cached = getRecoveryPrivateKey();
     if (!cached) throw new Error("recoverySessionEmpty");
     const ed25519Seed = await ed25519SeedFromSecp256k1Scalar(cached);
-    const signature = await signWithScheme(
-      /** @type {import('./constants.js').SignScheme} */ (scheme),
-      digest,
-      cached,
-      ed25519Seed,
-    );
-    zeroize(ed25519Seed);
-    emitEvent(window.parent, targetOrigin, "DigestSigned", correlationId, {
-      digest: digestData,
-      scheme,
-      signature,
-      credentialId: credentialId ?? null,
-    });
+    try {
+      const results = await signParsedDigests(
+        items,
+        cached,
+        ed25519Seed,
+        credentialId ?? null,
+      );
+      emitEvent(window.parent, targetOrigin, "DigestSigned", correlationId, {
+        results,
+      });
+    } finally {
+      zeroize(ed25519Seed);
+    }
     return;
   }
 
   await withCeremony(async () => {
-    const credential = await getPasskeyAssertion(undefined, credentialId);
+    const credential = await promptCeremonyConfirm(
+      ceremonyFieldsFromParams(params),
+      () => getPasskeyAssertion(undefined, credentialId),
+    );
     const keys = await deriveKeysFromCredential(credential);
     const ed25519Seed = await ed25519SeedFromCredential(credential);
     emitKeyDerived(
@@ -294,22 +407,20 @@ async function handleSignDigest(params, correlationId, targetOrigin) {
       keys.secp256k1PublicKey,
       keys.ed25519PublicKey,
     );
-
-    const signature = await signWithScheme(
-      /** @type {import('./constants.js').SignScheme} */ (scheme),
-      digest,
-      keys.secp256k1PrivateKey,
-      ed25519Seed,
-    );
-    zeroize(keys.secp256k1PrivateKey);
-    zeroize(ed25519Seed);
-
-    emitEvent(window.parent, targetOrigin, "DigestSigned", correlationId, {
-      digest: digestData,
-      scheme,
-      signature,
-      credentialId: credentialId ?? getCredentialId(credential),
-    });
+    try {
+      const results = await signParsedDigests(
+        items,
+        keys.secp256k1PrivateKey,
+        ed25519Seed,
+        credentialId ?? getCredentialId(credential),
+      );
+      emitEvent(window.parent, targetOrigin, "DigestSigned", correlationId, {
+        results,
+      });
+    } finally {
+      zeroize(keys.secp256k1PrivateKey);
+      zeroize(ed25519Seed);
+    }
   });
 }
 
@@ -323,7 +434,10 @@ async function handleRevealPrivateKey(params, correlationId, targetOrigin) {
     typeof params.credentialId === "string" ? params.credentialId : undefined;
 
   await withCeremony(async () => {
-    const credential = await getPasskeyAssertion(undefined, credentialId);
+    const credential = await promptCeremonyConfirm(
+      ceremonyFieldsFromParams(params),
+      () => getPasskeyAssertion(undefined, credentialId),
+    );
     const keys = await deriveKeysFromCredential(credential);
     emitKeyDerived(
       targetOrigin,
@@ -390,7 +504,10 @@ async function handleCreateRecoveryData(params, correlationId, targetOrigin) {
   }
 
   await withCeremony(async () => {
-    const credential = await getPasskeyAssertion(undefined, credentialId);
+    const credential = await promptCeremonyConfirm(
+      ceremonyFieldsFromParams(params),
+      () => getPasskeyAssertion(undefined, credentialId),
+    );
     const keys = await deriveKeysFromCredential(credential);
     emitKeyDerived(
       targetOrigin,
@@ -455,7 +572,9 @@ async function handleRecoverKey(params, correlationId, targetOrigin) {
 
   if (credentialId) {
     await withCeremony(async () => {
-      await getPasskeyAssertion(undefined, credentialId);
+      await promptCeremonyConfirm(ceremonyFieldsFromParams(params), () =>
+        getPasskeyAssertion(undefined, credentialId),
+      );
       clearRecoveryPrivateKey();
     });
     emitEvent(
@@ -522,7 +641,10 @@ async function handleEncryptAES256(params, correlationId, targetOrigin) {
   }
 
   await withCeremony(async () => {
-    const credential = await getPasskeyAssertion(undefined, credentialId);
+    const credential = await promptCeremonyConfirm(
+      ceremonyFieldsFromParams(params),
+      () => getPasskeyAssertion(undefined, credentialId),
+    );
     const keys = await deriveKeysFromCredential(credential);
     emitKeyDerived(
       targetOrigin,
@@ -579,7 +701,10 @@ async function handleDecryptAES256(params, correlationId, targetOrigin) {
   }
 
   await withCeremony(async () => {
-    const credential = await getPasskeyAssertion(undefined, credentialId);
+    const credential = await promptCeremonyConfirm(
+      ceremonyFieldsFromParams(params),
+      () => getPasskeyAssertion(undefined, credentialId),
+    );
     const keys = await deriveKeysFromCredential(credential);
     emitKeyDerived(
       targetOrigin,
@@ -615,7 +740,10 @@ async function handleGetPublicKey(params, correlationId, targetOrigin) {
       : undefined;
 
   await withCeremony(async () => {
-    const credential = await getPasskeyAssertion(challenge, credentialId);
+    const credential = await promptCeremonyConfirm(
+      ceremonyFieldsFromParams(params),
+      () => getPasskeyAssertion(challenge, credentialId),
+    );
     const keys = await deriveKeysFromCredential(credential);
     emitKeyDerived(
       targetOrigin,
@@ -651,6 +779,182 @@ async function handleGetPublicKey(params, correlationId, targetOrigin) {
   });
 }
 
+/**
+ * Mixed ceremony: digests + AES + public key + optional WebAuthn challenge.
+ *
+ * @param {Record<string, unknown>} params
+ * @param {string | undefined} correlationId
+ * @param {string} targetOrigin
+ */
+async function handleExecuteBatch(params, correlationId, targetOrigin) {
+  const credentialId =
+    typeof params.credentialId === "string" ? params.credentialId : undefined;
+  const includePublicKey = params.includePublicKey === true;
+  const challengeHex =
+    typeof params.challenge === "string" ? params.challenge : undefined;
+  const challenge = challengeHex ? parse0xHex(challengeHex) : undefined;
+
+  /** @type {ParsedDigestItem[] | undefined} */
+  let digestItems;
+  if (params.digests !== undefined) {
+    const parsed = parseDigestItems(params.digests);
+    if (!parsed.ok) {
+      emitInvalid(correlationId, targetOrigin, parsed.reason);
+      return;
+    }
+    digestItems = parsed.items;
+  }
+
+  /** @type {string[] | undefined} */
+  let plaintexts;
+  if (params.plaintexts !== undefined) {
+    if (!isStringArray(params.plaintexts)) {
+      emitInvalid(correlationId, targetOrigin, "invalidParams");
+      return;
+    }
+    plaintexts = params.plaintexts;
+  }
+
+  /** @type {string[] | undefined} */
+  let ciphertextsIn;
+  if (params.ciphertexts !== undefined) {
+    if (!isStringArray(params.ciphertexts)) {
+      emitInvalid(correlationId, targetOrigin, "invalidParams");
+      return;
+    }
+    ciphertextsIn = params.ciphertexts;
+  }
+
+  const hasDigests = (digestItems?.length ?? 0) > 0;
+  const hasPlaintexts = (plaintexts?.length ?? 0) > 0;
+  const hasCiphertexts = (ciphertextsIn?.length ?? 0) > 0;
+  if (
+    !hasDigests &&
+    !hasPlaintexts &&
+    !hasCiphertexts &&
+    !includePublicKey &&
+    !challenge
+  ) {
+    emitInvalid(correlationId, targetOrigin, "emptyBatch");
+    return;
+  }
+
+  /**
+   * @param {Uint8Array} secp256k1PrivateKey
+   * @param {Uint8Array} ed25519Seed
+   * @param {Uint8Array} secp256k1PublicKey
+   * @param {Uint8Array} ed25519PublicKey
+   * @param {string | null} resolvedCredentialId
+   * @param {PublicKeyCredential | null} credential
+   */
+  async function runOps(
+    secp256k1PrivateKey,
+    ed25519Seed,
+    secp256k1PublicKey,
+    ed25519PublicKey,
+    resolvedCredentialId,
+    credential,
+  ) {
+    /** @type {Record<string, unknown>} */
+    const data = { credentialId: resolvedCredentialId };
+
+    if (hasDigests && digestItems) {
+      data.results = await signParsedDigests(
+        digestItems,
+        secp256k1PrivateKey,
+        ed25519Seed,
+        resolvedCredentialId,
+      );
+    }
+    if (hasPlaintexts && plaintexts) {
+      data.ciphertexts = await encryptAes256Batch(
+        plaintexts,
+        secp256k1PrivateKey,
+      );
+    }
+    if (hasCiphertexts && ciphertextsIn) {
+      data.plaintexts = await decryptAes256Batch(
+        ciphertextsIn,
+        secp256k1PrivateKey,
+      );
+    }
+    if (includePublicKey) {
+      data.publicKey = {
+        credentialId: resolvedCredentialId ?? undefined,
+        cosePublicKey: credential
+          ? getCosePublicKeyBase64Url(credential)
+          : null,
+        secp256k1PublicKey: to0xHex(secp256k1PublicKey),
+        ed25519PublicKey: to0xHex(ed25519PublicKey),
+      };
+    }
+    if (challenge && credential) {
+      const signature = getAssertionSignatureBase64Url(credential);
+      if (signature) {
+        data.challengeSignature = signature;
+      }
+    }
+
+    emitEvent(window.parent, targetOrigin, "BatchExecuted", correlationId, data);
+  }
+
+  // Challenge always forces a real assertion (assertion signature required).
+  if (challenge || !hasRecoverySession()) {
+    await withCeremony(async () => {
+      const credential = await promptCeremonyConfirm(
+        ceremonyFieldsFromParams(params),
+        () => getPasskeyAssertion(challenge, credentialId),
+      );
+      const keys = await deriveKeysFromCredential(credential);
+      const ed25519Seed = await ed25519SeedFromCredential(credential);
+      emitKeyDerived(
+        targetOrigin,
+        correlationId,
+        keys.secp256k1PublicKey,
+        keys.ed25519PublicKey,
+      );
+      try {
+        await runOps(
+          keys.secp256k1PrivateKey,
+          ed25519Seed,
+          keys.secp256k1PublicKey,
+          keys.ed25519PublicKey,
+          credentialId ?? getCredentialId(credential),
+          credential,
+        );
+      } finally {
+        zeroize(keys.secp256k1PrivateKey);
+        zeroize(ed25519Seed);
+      }
+    });
+    return;
+  }
+
+  const cached = getRecoveryPrivateKey();
+  if (!cached) throw new Error("recoverySessionEmpty");
+  const ed25519Seed = await ed25519SeedFromSecp256k1Scalar(cached);
+  const secp256k1PublicKey = secpGetPublicKey(cached, false);
+  const ed25519PublicKey = await edGetPublicKeyAsync(ed25519Seed);
+  emitKeyDerived(
+    targetOrigin,
+    correlationId,
+    secp256k1PublicKey,
+    ed25519PublicKey,
+  );
+  try {
+    await runOps(
+      cached,
+      ed25519Seed,
+      secp256k1PublicKey,
+      ed25519PublicKey,
+      credentialId ?? null,
+      null,
+    );
+  } finally {
+    zeroize(ed25519Seed);
+  }
+}
+
 /**
  * @param {unknown} error
  * @param {string | undefined} correlationId
@@ -660,6 +964,13 @@ function handleError(error, correlationId, targetOrigin) {
   const name = error instanceof Error ? error.name : "";
   const message = error instanceof Error ? error.message : String(error);
 
+  if (error instanceof CeremonyDeniedError || name === "CeremonyDeniedError") {
+    emitEvent(window.parent, targetOrigin, "SignDenied", correlationId, {
+      reason: message || "signDenied",
+    });
+    return;
+  }
+
   if (name === "NotAllowedError" || message.includes("NotAllowed")) {
     emitEvent(window.parent, targetOrigin, "NotAllowed", correlationId, {
       reason: message || "notAllowed",

package/src/main.js

@@ -1,9 +1,10 @@
 import { handleRequest } from "./handlers.js";
 import {
+  abandonCeremony,
   isValidNesting,
   setTrustedParentOrigin,
 } from "./state.js";
-import { initUi } from "./ui.js";
+import { cancelPendingCeremonyConfirm, initUi } from "./ui.js";
 import { isValidParentMessage, parseRequest } from "./rpc.js";
 
 function bootstrap() {
@@ -20,14 +21,29 @@ function bootstrap() {
 
   window.addEventListener("message", async (event) => {
     if (!isValidParentMessage(event)) return;
-    if (!parseRequest(event.data)) return;
+
+    const data = event.data;
+    if (
+      data &&
+      typeof data === "object" &&
+      /** @type {{ kind?: unknown }} */ (data).kind === "cancel"
+    ) {
+      setTrustedParentOrigin(event.origin);
+      await abandonCeremony(cancelPendingCeremonyConfirm);
+      return;
+    }
+
+    if (!parseRequest(data)) return;
 
     setTrustedParentOrigin(event.origin);
     const targetOrigin = event.origin;
     const { method, correlationId, params = {} } = /** @type {{ method: string, correlationId?: string, params?: Record<string, unknown> }} */ (
-      event.data
+      data
     );
 
+    // Drop a stuck Confirm wait (e.g. parent timed out) before starting anew.
+    await abandonCeremony(cancelPendingCeremonyConfirm);
+
     await handleRequest(
       method,
       /** @type {Record<string, unknown>} */ (params),

package/src/state.js

@@ -84,7 +84,26 @@ export async function withCeremony(fn) {
   try {
     return await promise;
   } finally {
-    ceremonyPromise = null;
+    if (ceremonyPromise === promise) {
+      ceremonyPromise = null;
+    }
+  }
+}
+
+/**
+ * Cancel an open Confirm UI and wait for any in-flight ceremony lock to clear.
+ * Used when the parent times out or starts a new RPC.
+ *
+ * @param {() => void} cancelPendingConfirm
+ */
+export async function abandonCeremony(cancelPendingConfirm) {
+  cancelPendingConfirm();
+  const pending = ceremonyPromise;
+  if (!pending) return;
+  try {
+    await pending;
+  } catch {
+    // Prior ceremony was cancelled or failed — lock clears in withCeremony finally.
   }
 }
 

package/src/ui.js

@@ -3,6 +3,59 @@ import { to0xHex } from "./hex.js";
 /** @type {HTMLElement | null} */
 let root = null;
 
+/** @type {((reason?: Error) => void) | null} */
+let pendingConfirmReject = null;
+
+const DEFAULT_CEREMONY_HEADER = "Confirm passkey";
+const DEFAULT_CEREMONY_TEXT =
+  "Your device will ask for a passkey to continue.";
+const DEFAULT_CONFIRM_TEXT = "Continue";
+const DEFAULT_DENY_TEXT = "Cancel";
+
+const MAX_HEADER_LENGTH = 120;
+const MAX_EXPLANATION_LENGTH = 2_000;
+const MAX_BUTTON_LABEL_LENGTH = 64;
+const MAX_PASSPHRASE_PROMPT_LENGTH = 200;
+
+/**
+ * Plain-text sanitize Branding-supplied copy before it touches the DOM.
+ * Tags are stripped; remaining text is assigned via `textContent` (never HTML).
+ *
+ * @param {unknown} value
+ * @param {{ maxLength?: number, allowNewlines?: boolean }} [options]
+ * @returns {string}
+ */
+export function sanitizeDisplayText(value, options = {}) {
+  if (typeof value !== "string") return "";
+  const maxLength = options.maxLength ?? 500;
+  const allowNewlines = options.allowNewlines === true;
+
+  let text = value.replace(/<[^>]*>/g, "");
+  // Decode a few common entities so stripped markup cannot leave `&lt;script&gt;`-shaped bait.
+  text = text
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/gi, "&");
+  // Strip again after entity decode (e.g. `&lt;img onerror=...&gt;`).
+  text = text.replace(/<[^>]*>/g, "");
+
+  if (allowNewlines) {
+    text = text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+    text = text.replace(/\r\n?/g, "\n");
+  } else {
+    text = text.replace(/[\u0000-\u001F\u007F]/g, " ");
+    text = text.replace(/\s+/g, " ");
+  }
+
+  text = text.trim();
+  if (text.length > maxLength) {
+    text = text.slice(0, maxLength).trimEnd();
+  }
+  return text;
+}
+
 /**
  * @param {HTMLElement} container
  */
@@ -13,7 +66,162 @@ export function initUi(container) {
 }
 
 export function clearUi() {
-  if (root) root.innerHTML = "";
+  if (root) {
+    root.innerHTML = "";
+    root.className = "ows-signer-ui";
+  }
+}
+
+/**
+ * Error thrown when the user cancels the ceremony Confirm UI.
+ * Mapped to the `SignDenied` event by handlers.
+ */
+export class CeremonyDeniedError extends Error {
+  constructor(message = "signDenied") {
+    super(message);
+    this.name = "CeremonyDeniedError";
+  }
+}
+
+/**
+ * Abort an open Confirm panel (e.g. client timeout or superseding RPC).
+ * Does nothing if no confirm is waiting.
+ */
+export function cancelPendingCeremonyConfirm() {
+  if (!pendingConfirmReject) return;
+  const reject = pendingConfirmReject;
+  pendingConfirmReject = null;
+  clearUi();
+  reject(new CeremonyDeniedError("ceremonyCancelled"));
+}
+
+/**
+ * @typedef {{
+ *   explanationHeader?: string,
+ *   explanationText?: string,
+ *   confirmButtonText?: string,
+ *   denyButtonText?: string,
+ * }} CeremonyUiFields
+ */
+
+/**
+ * Resolve ceremony copy with defaults.
+ * @param {CeremonyUiFields | Record<string, unknown> | undefined} fields
+ */
+export function resolveCeremonyUi(fields) {
+  const src = fields && typeof fields === "object" ? fields : {};
+  const header = sanitizeDisplayText(src.explanationHeader, {
+    maxLength: MAX_HEADER_LENGTH,
+  });
+  const explanation = sanitizeDisplayText(src.explanationText, {
+    maxLength: MAX_EXPLANATION_LENGTH,
+    allowNewlines: true,
+  });
+  const confirmButtonText = sanitizeDisplayText(src.confirmButtonText, {
+    maxLength: MAX_BUTTON_LABEL_LENGTH,
+  });
+  const denyButtonText = sanitizeDisplayText(src.denyButtonText, {
+    maxLength: MAX_BUTTON_LABEL_LENGTH,
+  });
+  return {
+    header: header || DEFAULT_CEREMONY_HEADER,
+    explanation: explanation || DEFAULT_CEREMONY_TEXT,
+    confirmButtonText: confirmButtonText || DEFAULT_CONFIRM_TEXT,
+    denyButtonText: denyButtonText || DEFAULT_DENY_TEXT,
+  };
+}
+
+/**
+ * Show Confirm/Cancel. On Confirm, runs `runOnConfirm` **synchronously from the
+ * click handler** so WebAuthn keeps user activation / document focus on mobile.
+ *
+ * Copy stays visible while the ceremony runs; buttons are disabled until it
+ * settles. The panel is cleared only on deny, success, failure, or cancel.
+ *
+ * Layout: header + actions stay fixed; only explanation text scrolls.
+ * Branding strings are sanitized then set with `textContent` (plain text only).
+ *
+ * @template T
+ * @param {CeremonyUiFields | Record<string, unknown> | undefined} fields
+ * @param {() => T | Promise<T>} runOnConfirm
+ * @returns {Promise<T>}
+ */
+export function promptCeremonyConfirm(fields, runOnConfirm) {
+  if (!root) {
+    return Promise.reject(new Error("uiNotInitialized"));
+  }
+  cancelPendingCeremonyConfirm();
+  clearUi();
+  root.className = "ows-signer-ui ows-signer-ui--ceremony";
+  const ui = resolveCeremonyUi(fields);
+
+  return new Promise((resolve, reject) => {
+    pendingConfirmReject = reject;
+
+    const header = document.createElement("h2");
+    header.className = "ows-ceremony-header";
+    header.textContent = ui.header;
+
+    const body = document.createElement("div");
+    body.className = "ows-ceremony-body";
+    const text = document.createElement("p");
+    text.className = "ows-ceremony-text";
+    text.textContent = ui.explanation;
+    body.append(text);
+
+    const actions = document.createElement("div");
+    actions.className = "ows-ceremony-actions";
+
+    const confirmBtn = document.createElement("button");
+    confirmBtn.type = "button";
+    confirmBtn.className = "ows-confirm";
+    confirmBtn.textContent = ui.confirmButtonText;
+
+    const denyBtn = document.createElement("button");
+    denyBtn.type = "button";
+    denyBtn.className = "ows-deny";
+    denyBtn.textContent = ui.denyButtonText;
+
+    const finishWaiting = () => {
+      pendingConfirmReject = null;
+    };
+
+    const settleSuccess = (result) => {
+      // Cancel may have already cleared the waiter / panel.
+      if (pendingConfirmReject !== reject) return;
+      finishWaiting();
+      clearUi();
+      resolve(result);
+    };
+
+    const settleFailure = (error) => {
+      if (pendingConfirmReject !== reject) return;
+      finishWaiting();
+      clearUi();
+      reject(error);
+    };
+
+    confirmBtn.addEventListener("click", () => {
+      confirmBtn.disabled = true;
+      denyBtn.disabled = true;
+      try {
+        // Start WebAuthn in the same turn as the click (no prior await).
+        // Keep copy visible until the ceremony settles.
+        Promise.resolve(runOnConfirm()).then(settleSuccess, settleFailure);
+      } catch (error) {
+        settleFailure(error);
+      }
+    });
+
+    denyBtn.addEventListener("click", () => {
+      finishWaiting();
+      clearUi();
+      reject(new CeremonyDeniedError());
+    });
+
+    actions.append(confirmBtn, denyBtn);
+    root.append(header, body, actions);
+  });
 }
 
 /**
@@ -21,6 +229,7 @@ export function clearUi() {
  */
 export function showPrivateKey(privateKey) {
   if (!root) return;
+  cancelPendingCeremonyConfirm();
   clearUi();
   const pre = document.createElement("pre");
   pre.className = "ows-key";
@@ -45,16 +254,23 @@ export function promptPassphrase(passwordText, buttonText, minPasswordLength) {
   if (!root) {
     return Promise.reject(new Error("uiNotInitialized"));
   }
+  cancelPendingCeremonyConfirm();
   clearUi();
+  const safePlaceholder = sanitizeDisplayText(passwordText, {
+    maxLength: MAX_PASSPHRASE_PROMPT_LENGTH,
+  });
+  const safeButton = sanitizeDisplayText(buttonText, {
+    maxLength: MAX_BUTTON_LABEL_LENGTH,
+  });
   return new Promise((resolve, reject) => {
     const input = document.createElement("input");
     input.type = "password";
     input.className = "ows-password";
-    input.placeholder = passwordText;
+    input.placeholder = safePlaceholder || "Passphrase";
     const button = document.createElement("button");
     button.type = "button";
     button.className = "ows-confirm";
-    button.textContent = buttonText;
+    button.textContent = safeButton || "Continue";
     button.addEventListener("click", () => {
       if (input.value.length < minPasswordLength) {
         reject(new Error("passwordTooShort"));