@1shotapi/ows-signer 0.2.0

package/README.md

@@ -0,0 +1,106 @@
+# @1shotapi/ows-signer
+
+The **OWS Signing Layer** — plain JavaScript, zero npm dependencies, no build step.
+
+## Design
+
+Minimal **KMS/HSM** iframe: WebAuthn PRF key custody, curve-based signing, optional export/recovery UI. Chain-specific marshalling lives in `@1shotapi/ows-signer-utils`.
+
+## Deployment and rpId (hybrid)
+
+- `rpId` is always **`window.location.hostname`** (the signer document origin).
+- **Canonical CDN / on-chain gateway:** shared passkey namespace for all integrators on that host.
+- **Per-brand rpId:** self-host or reverse-proxy signer HTML on your branding origin.
+
+## Nesting
+
+Must be embedded as **iframe inside a Branding Layer iframe** (not directly in the host). Rejects messages unless `window.parent !== window.top`.
+
+## Wire protocol
+
+Parent → signer:
+
+```json
+{ "v": 1, "kind": "request", "method": "signDigest", "correlationId": "…", "params": { } }
+```
+
+Signer → parent:
+
+```json
+{ "v": 1, "kind": "event", "event": "DigestSigned", "correlationId": "…", "data": { } }
+```
+
+Only accepts messages when `event.source === window.parent`. Replies use the parent's `event.origin` as `targetOrigin`.
+
+## Methods
+
+| 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?` |
+| `clearRecoverySession` | — | `RecoverySessionCleared` |
+| `encryptAES256` | `plaintexts[]`, `credentialId?` | `KeyDerived` (PRF path), `AES256Encrypted` |
+| `decryptAES256` | `ciphertexts[]`, `credentialId?` | `KeyDerived` (PRF path), `AES256Decrypted` |
+
+Failure events: `NotAllowed`, `InvalidRequest`.
+
+`createCredential` options:
+
+- `rpName` — relying party display name in passkey UI (default `"OWS"`); does not affect `rpId`
+- `userDisplayName` — friendly account label (defaults to `name`)
+- `userId` — stable user handle bytes (base64); random if omitted
+
+## Signing schemes
+
+`secp256k1-ecdsa`, `secp256k1-ecdsa-recoverable`, `secp256k1-bip340` (not yet implemented), `ed25519`.
+
+`digestData` is `0x`-prefixed hex. Hash schemes require 32 bytes.
+
+## PRF labels
+
+- `ows-v1/secp256k1`
+- `ows-v1/ed25519` (derived via HKDF from PRF output)
+- `ows-v1/aes256-gcm` (HKDF from the secp256k1 scalar — same material as `signDigest`)
+
+## Recovery envelope
+
+`ows1:0x…` — version byte, 16-byte salt, 12-byte IV, AES-GCM-256 ciphertext (PBKDF2-SHA256, 250k iterations).
+
+## AES-256 seal envelope (credentials / general payload)
+
+`ows-aes1:0x…` — version byte, 12-byte IV, AES-GCM-256 ciphertext+tag. Key is HKDF-SHA256 of the wallet secp256k1 scalar with info `ows-v1/aes256-gcm` (no PBKDF2). Works under a recovery session without a new WebAuthn ceremony. Batch methods amortize one ceremony across many plaintexts/ciphertexts.
+
+## 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.
+
+## Layout
+
+```
+html/index.html           Entry document
+src/main.js               Bootstrap + message listener
+src/handlers.js           RPC dispatch
+src/webauthn.js           Passkey ceremonies
+src/crypto/               PRF, signing, recovery
+src/crypto/vendor/        Vendored @noble/secp256k1 + ed25519 (MIT)
+reference/                1ShotPay reference (not published)
+```
+
+## On-chain
+
+See `@1shotapi/ows-onchain`.
+
+## Integrity (planned)
+
+Client-side confirmation that official signer bytes are loaded (signed manifest + verify-before-execute, optional EIP-8244 pin) is **specced and tabled** — see [docs/trusted-loader-plan.md](docs/trusted-loader-plan.md). Not implemented yet.
+
+## Tests
+
+```bash
+npm test -w @1shotapi/ows-signer
+```

package/html/index.html

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>OWS Custody Signer</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      font-family: system-ui, sans-serif;
+    }
+    body {
+      margin: 0;
+      padding: 8px;
+    }
+    .ows-signer-ui {
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+      max-width: 100%;
+    }
+    .ows-key {
+      margin: 0;
+      padding: 8px;
+      border: 1px solid #8884;
+      border-radius: 4px;
+      font-family: ui-monospace, monospace;
+      font-size: 12px;
+      word-break: break-all;
+      white-space: pre-wrap;
+    }
+    .ows-password {
+      padding: 8px;
+      border: 1px solid #8884;
+      border-radius: 4px;
+      font: inherit;
+    }
+    .ows-copy,
+    .ows-confirm {
+      padding: 8px 12px;
+      border: 1px solid #8884;
+      border-radius: 4px;
+      background: transparent;
+      font: inherit;
+      cursor: pointer;
+      align-self: flex-start;
+    }
+  </style>
+</head>
+<body>
+  <div id="ows-signer-root"></div>
+  <script type="module" src="../src/main.js"></script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@1shotapi/ows-signer",
+  "version": "0.2.0",
+  "description": "OWS Signing Layer — plain JavaScript WebAuthn PRF key custody with curve-based signing (on-chain via EIP-8244)",
+  "type": "module",
+  "files": [
+    "src",
+    "html",
+    "README.md"
+  ],
+  "exports": {
+    "./html": "./html/index.html",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "ows",
+    "open-wallet-standard",
+    "webauthn",
+    "prf",
+    "passkey",
+    "signer",
+    "custody",
+    "secp256k1"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1Shot-API/open-wallet.git",
+    "directory": "packages/ows-signer"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/constants.js

@@ -0,0 +1,30 @@
+/** @typedef {'secp256k1-ecdsa' | 'secp256k1-ecdsa-recoverable' | 'secp256k1-bip340' | 'ed25519'} SignScheme */
+
+export const API_VERSION = 1;
+export const SIGNER_VERSION = "0.1.0";
+
+export const PRF_LABEL_SECP256K1 = new TextEncoder().encode("ows-v1/secp256k1");
+export const PRF_LABEL_ED25519 = new TextEncoder().encode("ows-v1/ed25519");
+/** HKDF info for AES-256-GCM — IKM is the secp256k1 scalar (`signDigest` material). */
+export const PRF_LABEL_AES256 = new TextEncoder().encode("ows-v1/aes256-gcm");
+
+/** @type {SignScheme[]} */
+export const SIGN_SCHEMES = [
+  "secp256k1-ecdsa",
+  "secp256k1-ecdsa-recoverable",
+  "secp256k1-bip340",
+  "ed25519",
+];
+
+export const METHODS = [
+  "getVersion",
+  "createCredential",
+  "signDigest",
+  "revealPrivateKey",
+  "createRecoveryData",
+  "recoverKey",
+  "getPublicKey",
+  "clearRecoverySession",
+  "encryptAES256",
+  "decryptAES256",
+];

package/src/crypto/aes256.js

@@ -0,0 +1,115 @@
+import { PRF_LABEL_AES256 } from "../constants.js";
+import { parse0xHex, to0xHex } from "../hex.js";
+import { hkdfExpand } from "./prf.js";
+
+/** Envelope prefix — distinct from recovery `ows1:` (PBKDF2). */
+export const AES256_ENVELOPE_PREFIX = "ows-aes1:";
+const AES256_VERSION = 1;
+const IV_LENGTH = 12;
+
+/**
+ * Derive an AES-256-GCM CryptoKey from the wallet secp256k1 scalar
+ * (same material `signDigest` uses), via HKDF domain separation.
+ *
+ * @param {Uint8Array} secp256k1PrivateKey
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveAes256KeyFromSecp256k1(secp256k1PrivateKey) {
+  const raw = await hkdfExpand(
+    secp256k1PrivateKey.buffer.slice(
+      secp256k1PrivateKey.byteOffset,
+      secp256k1PrivateKey.byteOffset + secp256k1PrivateKey.byteLength,
+    ),
+    PRF_LABEL_AES256,
+    32,
+  );
+  try {
+    return await crypto.subtle.importKey(
+      "raw",
+      raw,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"],
+    );
+  } finally {
+    raw.fill(0);
+  }
+}
+
+/**
+ * Encrypt a UTF-8 plaintext. Envelope: `ows-aes1:0x` ‖ version ‖ IV ‖ ciphertext+tag.
+ *
+ * @param {string} plaintext
+ * @param {CryptoKey} aesKey
+ * @returns {Promise<string>}
+ */
+export async function encryptAes256String(plaintext, aesKey) {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const encoded = new TextEncoder().encode(plaintext);
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: "AES-GCM", iv }, aesKey, encoded),
+  );
+  const payload = new Uint8Array(1 + IV_LENGTH + ciphertext.length);
+  payload[0] = AES256_VERSION;
+  payload.set(iv, 1);
+  payload.set(ciphertext, 1 + IV_LENGTH);
+  return `${AES256_ENVELOPE_PREFIX}${to0xHex(payload)}`;
+}
+
+/**
+ * Decrypt an `ows-aes1:` envelope to a UTF-8 string.
+ *
+ * @param {string} envelope
+ * @param {CryptoKey} aesKey
+ * @returns {Promise<string>}
+ */
+export async function decryptAes256String(envelope, aesKey) {
+  if (!envelope.startsWith(AES256_ENVELOPE_PREFIX)) {
+    throw new Error("invalidAes256Envelope");
+  }
+  const bytes = parse0xHex(envelope.slice(AES256_ENVELOPE_PREFIX.length));
+  if (bytes.length < 1 + IV_LENGTH + 16) {
+    throw new Error("invalidAes256Envelope");
+  }
+  if (bytes[0] !== AES256_VERSION) {
+    throw new Error("unsupportedAes256Version");
+  }
+  const iv = bytes.slice(1, 1 + IV_LENGTH);
+  const ciphertext = bytes.slice(1 + IV_LENGTH);
+  try {
+    const plain = new Uint8Array(
+      await crypto.subtle.decrypt({ name: "AES-GCM", iv }, aesKey, ciphertext),
+    );
+    return new TextDecoder().decode(plain);
+  } catch {
+    throw new Error("decryptionFailed");
+  }
+}
+
+/**
+ * @param {string[]} plaintexts
+ * @param {Uint8Array} secp256k1PrivateKey
+ * @returns {Promise<string[]>}
+ */
+export async function encryptAes256Batch(plaintexts, secp256k1PrivateKey) {
+  const aesKey = await deriveAes256KeyFromSecp256k1(secp256k1PrivateKey);
+  const out = [];
+  for (const plaintext of plaintexts) {
+    out.push(await encryptAes256String(plaintext, aesKey));
+  }
+  return out;
+}
+
+/**
+ * @param {string[]} envelopes
+ * @param {Uint8Array} secp256k1PrivateKey
+ * @returns {Promise<string[]>}
+ */
+export async function decryptAes256Batch(envelopes, secp256k1PrivateKey) {
+  const aesKey = await deriveAes256KeyFromSecp256k1(secp256k1PrivateKey);
+  const out = [];
+  for (const envelope of envelopes) {
+    out.push(await decryptAes256String(envelope, aesKey));
+  }
+  return out;
+}

package/src/crypto/prf.js

@@ -0,0 +1,119 @@
+import { PRF_LABEL_ED25519, PRF_LABEL_SECP256K1 } from "../constants.js";
+import { getPublicKeyAsync as edGetPublicKeyAsync } from "./vendor/noble-ed25519.js";
+import { getPublicKey as secpGetPublicKey } from "./vendor/noble-secp256k1.js";
+
+const SECP256K1_N = BigInt(
+  "0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141",
+);
+
+/**
+ * @param {unknown} prfOutput
+ * @returns {ArrayBuffer | null}
+ */
+export function normalizePrfOutputToArrayBuffer(prfOutput) {
+  if (prfOutput instanceof ArrayBuffer) return prfOutput;
+  if (prfOutput instanceof Uint8Array) {
+    return prfOutput.buffer.slice(
+      prfOutput.byteOffset,
+      prfOutput.byteOffset + prfOutput.byteLength,
+    );
+  }
+  if (ArrayBuffer.isView(prfOutput)) {
+    const view = /** @type {ArrayBufferView} */ (prfOutput);
+    return view.buffer.slice(
+      view.byteOffset,
+      view.byteOffset + view.byteLength,
+    );
+  }
+  if (Array.isArray(prfOutput)) {
+    return new Uint8Array(prfOutput).buffer;
+  }
+  return null;
+}
+
+/**
+ * @param {ArrayBuffer} prfBuffer
+ * @param {Uint8Array} infoLabel
+ * @param {number} length
+ * @returns {Promise<Uint8Array>}
+ */
+export async function hkdfExpand(prfBuffer, infoLabel, length) {
+  const ikm = new Uint8Array(prfBuffer);
+  const baseKey = await crypto.subtle.importKey("raw", ikm, "HKDF", false, [
+    "deriveBits",
+  ]);
+  const salt = new Uint8Array(32);
+  const bits = await crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt,
+      info: infoLabel,
+    },
+    baseKey,
+    length * 8,
+  );
+  return new Uint8Array(bits);
+}
+
+/**
+ * @param {ArrayBuffer} prfBuffer
+ * @param {Uint8Array} infoLabel
+ * @returns {Promise<Uint8Array>}
+ */
+export async function deriveScalarFromPrf(prfBuffer, infoLabel) {
+  for (let counter = 0; counter < 255; counter++) {
+    const info = new Uint8Array(infoLabel.length + 1);
+    info.set(infoLabel);
+    info[infoLabel.length] = counter;
+    const candidate = await hkdfExpand(prfBuffer, info, 32);
+    const scalar = bytesToBigInt(candidate);
+    if (scalar > 0n && scalar < SECP256K1_N) {
+      return candidate;
+    }
+  }
+  throw new Error("Failed to derive valid secp256k1 scalar from PRF");
+}
+
+/**
+ * @param {ArrayBuffer} prfBuffer
+ * @returns {Promise<Uint8Array>}
+ */
+export async function deriveEd25519SeedFromPrf(prfBuffer) {
+  return hkdfExpand(prfBuffer, PRF_LABEL_ED25519, 32);
+}
+
+/**
+ * @param {PublicKeyCredential} credential
+ * @returns {Promise<{ secp256k1PrivateKey: Uint8Array, secp256k1PublicKey: Uint8Array, ed25519PublicKey: Uint8Array }>}
+ */
+export async function deriveKeysFromCredential(credential) {
+  const rawPrf = /** @type {{ prf?: { results?: { first?: unknown } } }} */ (
+    credential.getClientExtensionResults()
+  ).prf?.results?.first;
+  const prfBuffer = normalizePrfOutputToArrayBuffer(rawPrf);
+  if (!prfBuffer) {
+    throw new Error("Passkey does not support PRF or PRF output missing");
+  }
+
+  const secp256k1PrivateKey = await deriveScalarFromPrf(
+    prfBuffer,
+    PRF_LABEL_SECP256K1,
+  );
+  const ed25519Seed = await deriveEd25519SeedFromPrf(prfBuffer);
+  // Uncompressed (0x04 ‖ X ‖ Y) — required by viem `publicKeyToAddress`.
+  const secp256k1PublicKey = secpGetPublicKey(secp256k1PrivateKey, false);
+  const ed25519PublicKey = await edGetPublicKeyAsync(ed25519Seed);
+
+  return { secp256k1PrivateKey, secp256k1PublicKey, ed25519PublicKey };
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {bigint}
+ */
+function bytesToBigInt(bytes) {
+  let result = 0n;
+  for (const b of bytes) result = (result << 8n) + BigInt(b);
+  return result;
+}

package/src/crypto/recovery.js

@@ -0,0 +1,81 @@
+import { parse0xHex, to0xHex } from "../hex.js";
+
+const RECOVERY_VERSION = 1;
+const PBKDF2_ITERATIONS = 250_000;
+
+/**
+ * @param {string} passphrase
+ * @param {Uint8Array} salt
+ * @returns {Promise<CryptoKey>}
+ */
+async function deriveAesKey(passphrase, salt) {
+  const enc = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(passphrase),
+    "PBKDF2",
+    false,
+    ["deriveKey"],
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt,
+      iterations: PBKDF2_ITERATIONS,
+      hash: "SHA-256",
+    },
+    keyMaterial,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * @param {Uint8Array} privateKey
+ * @param {string} passphrase
+ * @returns {Promise<string>}
+ */
+export async function encryptPrivateKey(privateKey, passphrase) {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const aesKey = await deriveAesKey(passphrase, salt);
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: "AES-GCM", iv }, aesKey, privateKey),
+  );
+  const payload = new Uint8Array(
+    1 + salt.length + iv.length + ciphertext.length,
+  );
+  payload[0] = RECOVERY_VERSION;
+  payload.set(salt, 1);
+  payload.set(iv, 1 + salt.length);
+  payload.set(ciphertext, 1 + salt.length + iv.length);
+  return `ows1:${to0xHex(payload)}`;
+}
+
+/**
+ * @param {string} envelope
+ * @returns {Promise<Uint8Array>}
+ */
+export async function decryptPrivateKey(envelope, passphrase) {
+  if (!envelope.startsWith("ows1:")) {
+    throw new Error("invalidRecoveryEnvelope");
+  }
+  const bytes = parse0xHex(envelope.slice(5));
+  if (bytes[0] !== RECOVERY_VERSION) {
+    throw new Error("unsupportedRecoveryVersion");
+  }
+  const salt = bytes.slice(1, 17);
+  const iv = bytes.slice(17, 29);
+  const ciphertext = bytes.slice(29);
+  const aesKey = await deriveAesKey(passphrase, salt);
+  try {
+    const plain = new Uint8Array(
+      await crypto.subtle.decrypt({ name: "AES-GCM", iv }, aesKey, ciphertext),
+    );
+    if (plain.length !== 32) throw new Error("invalidDecryptedKey");
+    return plain;
+  } catch {
+    throw new Error("decryptionFailed");
+  }
+}

package/src/crypto/sign.js

@@ -0,0 +1,59 @@
+import { to0xHex } from "../hex.js";
+import { signAsync as edSignAsync } from "./vendor/noble-ed25519.js";
+import { signAsync as secpSignAsync } from "./vendor/noble-secp256k1.js";
+
+/**
+ * @param {import('../constants.js').SignScheme} scheme
+ * @param {Uint8Array} digest
+ * @param {Uint8Array} secp256k1PrivateKey
+ * @param {Uint8Array} ed25519Seed
+ * @returns {Promise<`0x${string}`>}
+ */
+export async function signWithScheme(
+  scheme,
+  digest,
+  secp256k1PrivateKey,
+  ed25519Seed,
+) {
+  switch (scheme) {
+    case "secp256k1-ecdsa": {
+      const sig = await secpSignAsync(digest, secp256k1PrivateKey, {
+        lowS: true,
+      });
+      return to0xHex(sig.toCompactRawBytes());
+    }
+    case "secp256k1-ecdsa-recoverable": {
+      const sig = await secpSignAsync(digest, secp256k1PrivateKey, {
+        lowS: true,
+      });
+      const compact = sig.toCompactRawBytes();
+      const recovery = sig.recovery ?? 0;
+      const out = new Uint8Array(65);
+      out.set(compact, 0);
+      out[64] = recovery;
+      return to0xHex(out);
+    }
+    case "secp256k1-bip340":
+      throw new Error("schemeNotImplemented");
+    case "ed25519": {
+      const sig = await edSignAsync(digest, ed25519Seed);
+      return to0xHex(sig);
+    }
+    default:
+      throw new Error("unknownScheme");
+  }
+}
+
+/**
+ * @param {import('../constants.js').SignScheme} scheme
+ * @param {Uint8Array} payload
+ */
+export function validateSignPayload(scheme, payload) {
+  if (scheme === "ed25519") {
+    if (payload.length === 0) throw new Error("invalidPayload");
+    return;
+  }
+  if (payload.length !== 32) {
+    throw new Error("digestMustBe32Bytes");
+  }
+}