@virtonetwork/authenticators-webauthn 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# WebAuthn Authenticator for Virto Network
+
+A TypeScript helper that wires **passkeys** (WebAuthn resident credentials) to the [@virtonetwork/signer](https://github.com/virto-network/papi-signers) stack. It exposes a single class, `WebAuthn`, that fulfils the `Authenticator<number>` interface used by `PassSigner`.
+The implementation is **browser‑only** and keeps all credential mapping in the caller’s hands — perfect for SPAs or wallet extensions that already manage users.
+
+## ✨ Features
+
+* **One‑line setup** → `await new WebAuthn(user).setup()`
+* **Kreivo‑compatible challenges** for secure on‑chain attestations
+* Deterministic `deviceId = Blake2‑256(credentialId)`
+* Produces SCALE‑encoded `Attestation` / `PassAuthenticate` objects
+* Zero persistence: inject or register credentials as you see fit
+
+## 📦 Installation
+
+```bash
+npm i @virtonetwork/authenticators-webauthn
+```
+
+## 🚀 Quick start
+
+```ts
+import { WebAuthn } from "@virtonetwork/authenticators-webauthn";
+import { PassSigner } from "@virtonetwork/signer";
+
+// 1️⃣  Restore user → credential mapping (from DB, localStorage…)
+const savedId = await db.getCredentialId("alice@example.com");
+
+// 2️⃣  Bootstrap helper
+const wa = await new WebAuthn("alice@example.com", savedId).setup();
+
+// 3️⃣  Enrol a new pass‑key if needed
+if (!savedId) {
+  const att = await wa.register(blockNumber, blockHash);
+  await db.saveCredentialId("alice@example.com", att.credentialId);
+}
+
+// 4️⃣  Sign any runtime challenge
+await passSigner.credentials(
+  await wa.authenticate(challenge, blockNumber),
+);
+```
+
+## 🛠️ API
+
+| Method                                        | Returns                         | Notes                                                                                  |
+| --------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| `setup()`                                     | `Promise< this >`               | Computes `hashedUserId`. Call once.                                                    |
+| `register(blockNo, blockHash, [displayName])` | `Promise<TAttestation<number>>` | Generates a WebAuthn credential and attestation. Throws if `credentialId` already set. |
+| `authenticate(challenge, context)`            | `Promise<TPassAuthenticate>`    | Signs an arbitrary 32‑byte challenge. Requires `credentialId`.                         |
+| `getDeviceId(webAuthn)                        | `Promise<DeviceId>`             | `Blake2‑256(credentialId)` wrapped in `Binary`.                                        |
+| `setCredentialId(id)`                         | `void`                          | Inject credential id after construction.                                               |
+
+> **Type parameter** `<number>` → `context` inside attestations/assertions is the **block number**.
+
+## 📝 Persistence Strategy
+
+This package **does not** store credential ids. A typical strategy is:
+
+1. During **registration**, persist `attestation.publicKey.bytes` keyed by `userId`.
+2. On next load, feed that id into the `WebAuthn` constructor.
+3. For multiple devices per account, maintain an *array* of ids and pick one UI‑side.
+
+## ⚠️ Error Handling
+
+| Error message                  | Cause                                                    | Fix                                           |
+| ------------------------------ | -------------------------------------------------------- | --------------------------------------------- |
+| `Already have a credentialId…` | Called `register()` when id already present              | Skip registration or call with a new instance |
+| `credentialId unknown…`        | Tried to authenticate/get device id without a credential | Inject stored id or call `register()`         |
+| `DOMException: …`              | User dismissed the WebAuthn prompt                       | Ask user to retry                             |
+
+## 🧳 Dependencies
+
+* **@virtonetwork/signer** ≥ 0.10  — interfaces, `KreivoBlockChallenger`, `PassSigner`
+* **@polkadot-api/substrate-bindings**  — `Binary`, `Blake2256`
+* Browser with WebAuthn (Chrome ≥ 109, Firefox ≥ 106, Safari ≥ 16)
+
+## 🩹 Development
+
+```bash
+# lint & type‑check
+npm run lint && npm run typecheck
+```
+
+### Tests
+
+Go to `tests/test.ts` to check out our tests.
+
+## 📄 License
+
+MIT © Virto Network contributors

package/dist/cjs/index.js

@@ -0,0 +1,261 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebAuthn = exports.KREIVO_AUTHORITY_ID = void 0;
+/**
+ * WebAuthn pass‑key authenticator for Virto Network.
+ *
+ * Exposes a browser‑side implementation of {@link Authenticator} that creates,
+ * stores, and uses WebAuthn resident credentials ("passkeys") while producing
+ * SCALE‑encoded data structures understood by the Kreivo signer pallet.
+ *
+ * Responsibilities
+ * ─────────────────────────────────────────────────────────
+ * • Derive a deterministic `deviceId` from the raw credential id
+ * • Emit `TAttestation<number>` during registration
+ * • Emit `TPassAuthenticate` during authentication
+ * • Never persist the credential mapping; that is delegated to the caller
+ *
+ * @module WebAuthn
+ */
+var signer_1 = require("@virtonetwork/signer");
+var substrate_bindings_1 = require("@polkadot-api/substrate-bindings");
+var types_ts_1 = require("./types.js");
+var utils_1 = require("polkadot-api/utils");
+/** Fixed authority id for Kreivo pass‑key attestors. */
+exports.KREIVO_AUTHORITY_ID = substrate_bindings_1.Binary.fromText("kreivo_p".padEnd(32, "\0"));
+/**
+ * Browser‑side Authenticator that wraps the WebAuthn API.
+ *
+ * The generic type parameter `<number>` indicates that the **context**
+ * carried inside attestations and assertions is the block number that
+ * originated the challenge.
+ *
+ * @implements {Authenticator<number>}
+ */
+var WebAuthn = /** @class */ (function () {
+    /**
+     * Creates a new WebAuthn helper.
+     *
+     * @param userId - Logical user identifier (e‑mail, DID, etc.).
+     * @param [credentialId] - Raw credential id obtained from a previous
+     *   registration flow; omit it if the user must enrol a new pass‑key.
+     */
+    function WebAuthn(userId, credentialId) {
+        this.userId = userId;
+        this.credentialId = credentialId;
+        /**
+         * SHA‑256 hash of {@link userId}. Filled once by {@link setup} and reused
+         * for all WebAuthn operations.
+         */
+        this.hashedUserId = new Uint8Array(32);
+    }
+    /**
+     * Deterministic identifier of the hardware/software authenticator
+     * (`deviceId = Blake2‑256(credentialId)`).
+     *
+     * @returns DeviceId suitable for on‑chain storage.
+     * @throws Error If this instance does not yet know a credential id.
+     */
+    WebAuthn.getDeviceId = function (wa) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!wa.credentialId) {
+                    throw new Error("credentialId unknown – call register() first or inject it via constructor/setCredentialId()");
+                }
+                return [2 /*return*/, substrate_bindings_1.Binary.fromBytes((0, substrate_bindings_1.Blake2256)(wa.credentialId))];
+            });
+        });
+    };
+    /**
+     * Injects a credential id discovered by the caller after construction.
+     *
+     * @param id - Raw credential id obtained from storage or backend.
+     */
+    WebAuthn.prototype.setCredentialId = function (id) {
+        this.credentialId = id;
+    };
+    /**
+     * Pre‑computes {@link hashedUserId}.
+     *
+     * Must be awaited **once** before any other interaction.
+     * Returns `this` for fluent chaining.
+     */
+    WebAuthn.prototype.setup = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        _a = this;
+                        _b = Uint8Array.bind;
+                        return [4 /*yield*/, crypto.subtle.digest("SHA-256", new TextEncoder().encode(this.userId))];
+                    case 1:
+                        _a.hashedUserId = new (_b.apply(Uint8Array, [void 0, _c.sent()]))();
+                        return [2 /*return*/, this];
+                }
+            });
+        });
+    };
+    /**
+     * Registers a **new** resident credential (pass‑key) with the user’s
+     * authenticator and returns a SCALE‑ready attestation.
+     *
+     * @param blockNumber - The number of the block whose hash seeds the challenge.
+     * @param blockHash   - The block hash used to derive a deterministic challenge.
+     * @param [displayName=this.userId] - Friendly name shown by the authenticator.
+     *
+     * @throws Error If this instance already has a credential id.
+     * @returns {Promise<TAttestation<number>>} SCALE‑encoded attestation object.
+     */
+    WebAuthn.prototype.register = function (blockNumber_1, blockHash_1) {
+        return __awaiter(this, arguments, void 0, function (blockNumber, blockHash, displayName) {
+            var challenger, challenge, credentials, _a, attestationObject, clientDataJSON, getPublicKey, publicKey;
+            var _b, _c;
+            if (displayName === void 0) { displayName = this.userId; }
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        if (this.credentialId) {
+                            throw new Error("Already have a credentialId; no need to register");
+                        }
+                        challenger = new signer_1.KreivoBlockChallenger();
+                        challenge = challenger.generate((0, utils_1.fromHex)(blockHash), new Uint8Array());
+                        return [4 /*yield*/, navigator.credentials.create({
+                                publicKey: {
+                                    challenge: challenge,
+                                    rp: { name: "Virto Passkeys" },
+                                    user: {
+                                        id: this.hashedUserId,
+                                        name: this.userId,
+                                        displayName: displayName,
+                                    },
+                                    pubKeyCredParams: [{ type: "public-key", alg: -7 /* ES256 */ }],
+                                    authenticatorSelection: { userVerification: "preferred" },
+                                    attestation: "none",
+                                    timeout: 60000,
+                                },
+                            })];
+                    case 1:
+                        credentials = (_d.sent());
+                        _a = credentials.response, attestationObject = _a.attestationObject, clientDataJSON = _a.clientDataJSON, getPublicKey = _a.getPublicKey;
+                        // Save raw credential id for future auth calls
+                        this.credentialId = new Uint8Array(credentials.rawId);
+                        publicKey = getPublicKey();
+                        if (!publicKey) {
+                            throw new Error("The credentials don't expose a public key. Please use another authenticator device.");
+                        }
+                        _b = {};
+                        _c = {
+                            authorityId: exports.KREIVO_AUTHORITY_ID
+                        };
+                        return [4 /*yield*/, WebAuthn.getDeviceId(this)];
+                    case 2: return [2 /*return*/, (_b.meta = (_c.deviceId = _d.sent(),
+                            _c.context = blockNumber,
+                            _c),
+                            _b.authenticatorData = substrate_bindings_1.Binary.fromBytes(new Uint8Array(attestationObject)),
+                            _b.clientData = substrate_bindings_1.Binary.fromBytes(new Uint8Array(clientDataJSON)),
+                            _b.publicKey = substrate_bindings_1.Binary.fromBytes(new Uint8Array(publicKey)),
+                            _b)];
+                }
+            });
+        });
+    };
+    /**
+     * Signs an arbitrary challenge with the pass‑key and produces a
+     * {@link TPassAuthenticate} payload understood by `PassSigner`.
+     *
+     * @param challenge - 32‑byte buffer supplied by the runtime.
+     * @param context   - Block number (or any numeric context expected by the pallet).
+     *
+     * @returns SCALE‑encoded authentication payload.
+     * @throws Error If no credential id is available.
+     */
+    WebAuthn.prototype.authenticate = function (challenge, context) {
+        return __awaiter(this, void 0, void 0, function () {
+            var publicKey, cred, _a, authenticatorData, clientDataJSON, signature, assertion;
+            var _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        if (!this.credentialId) {
+                            throw new Error("credentialId unknown – call register() first or inject it via constructor/setCredentialId()");
+                        }
+                        publicKey = {
+                            challenge: challenge,
+                            allowCredentials: [
+                                {
+                                    id: this.credentialId.buffer,
+                                    type: "public-key",
+                                    transports: ["usb", "ble", "nfc", "internal"],
+                                },
+                            ],
+                            userVerification: "preferred",
+                            timeout: 60000,
+                        };
+                        return [4 /*yield*/, navigator.credentials.get({
+                                publicKey: publicKey,
+                            })];
+                    case 1:
+                        cred = (_c.sent());
+                        _a = cred.response, authenticatorData = _a.authenticatorData, clientDataJSON = _a.clientDataJSON, signature = _a.signature;
+                        assertion = {
+                            meta: {
+                                authorityId: exports.KREIVO_AUTHORITY_ID,
+                                userId: substrate_bindings_1.Binary.fromBytes(this.hashedUserId),
+                                context: context,
+                            },
+                            authenticatorData: substrate_bindings_1.Binary.fromBytes(new Uint8Array(authenticatorData)),
+                            clientData: substrate_bindings_1.Binary.fromBytes(new Uint8Array(clientDataJSON)),
+                            signature: substrate_bindings_1.Binary.fromBytes(new Uint8Array(signature)),
+                        };
+                        _b = {};
+                        return [4 /*yield*/, WebAuthn.getDeviceId(this)];
+                    case 2: return [2 /*return*/, (_b.deviceId = _c.sent(),
+                            _b.credentials = {
+                                tag: "WebAuthn",
+                                value: types_ts_1.Assertion.enc(assertion),
+                            },
+                            _b)];
+                }
+            });
+        });
+    };
+    return WebAuthn;
+}());
+exports.WebAuthn = WebAuthn;

package/dist/cjs/types.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Assertion = exports.Attestation = void 0;
+var substrate_bindings_1 = require("@polkadot-api/substrate-bindings");
+var scale_ts_1 = require("scale-ts");
+var AttestationMeta = (0, scale_ts_1.Struct)({
+    authorityId: (0, substrate_bindings_1.Bin)(32),
+    deviceId: (0, substrate_bindings_1.Bin)(32),
+    context: scale_ts_1.u32,
+});
+exports.Attestation = (0, scale_ts_1.Struct)({
+    meta: AttestationMeta,
+    authenticatorData: (0, substrate_bindings_1.Bin)(),
+    clientData: (0, substrate_bindings_1.Bin)(),
+    publicKey: (0, substrate_bindings_1.Bin)(),
+});
+var AssertionMeta = (0, scale_ts_1.Struct)({
+    authorityId: (0, substrate_bindings_1.Bin)(32),
+    userId: (0, substrate_bindings_1.Bin)(32),
+    context: scale_ts_1.u32,
+});
+exports.Assertion = (0, scale_ts_1.Struct)({
+    meta: AssertionMeta,
+    authenticatorData: (0, substrate_bindings_1.Bin)(),
+    clientData: (0, substrate_bindings_1.Bin)(),
+    signature: (0, substrate_bindings_1.Bin)(),
+});

package/dist/esm/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * WebAuthn pass‑key authenticator for Virto Network.
+ *
+ * Exposes a browser‑side implementation of {@link Authenticator} that creates,
+ * stores, and uses WebAuthn resident credentials ("passkeys") while producing
+ * SCALE‑encoded data structures understood by the Kreivo signer pallet.
+ *
+ * Responsibilities
+ * ─────────────────────────────────────────────────────────
+ * • Derive a deterministic `deviceId` from the raw credential id
+ * • Emit `TAttestation<number>` during registration
+ * • Emit `TPassAuthenticate` during authentication
+ * • Never persist the credential mapping; that is delegated to the caller
+ *
+ * @module WebAuthn
+ */
+import { Authenticator, DeviceId } from "@virtonetwork/signer";
+import { Binary } from "@polkadot-api/substrate-bindings";
+import type { BlockHash, TAttestation } from "./types.ts";
+import type { TPassAuthenticate } from "@virtonetwork/signer";
+/** Fixed authority id for Kreivo pass‑key attestors. */
+export declare const KREIVO_AUTHORITY_ID: Binary;
+/**
+ * Browser‑side Authenticator that wraps the WebAuthn API.
+ *
+ * The generic type parameter `<number>` indicates that the **context**
+ * carried inside attestations and assertions is the block number that
+ * originated the challenge.
+ *
+ * @implements {Authenticator<number>}
+ */
+export declare class WebAuthn implements Authenticator<number> {
+    readonly userId: string;
+    credentialId?: Uint8Array | undefined;
+    /**
+     * SHA‑256 hash of {@link userId}. Filled once by {@link setup} and reused
+     * for all WebAuthn operations.
+     */
+    hashedUserId: Uint8Array;
+    /**
+     * Creates a new WebAuthn helper.
+     *
+     * @param userId - Logical user identifier (e‑mail, DID, etc.).
+     * @param [credentialId] - Raw credential id obtained from a previous
+     *   registration flow; omit it if the user must enrol a new pass‑key.
+     */
+    constructor(userId: string, credentialId?: Uint8Array | undefined);
+    /**
+     * Deterministic identifier of the hardware/software authenticator
+     * (`deviceId = Blake2‑256(credentialId)`).
+     *
+     * @returns DeviceId suitable for on‑chain storage.
+     * @throws Error If this instance does not yet know a credential id.
+     */
+    static getDeviceId(wa: WebAuthn): Promise<DeviceId>;
+    /**
+     * Injects a credential id discovered by the caller after construction.
+     *
+     * @param id - Raw credential id obtained from storage or backend.
+     */
+    setCredentialId(id: Uint8Array): void;
+    /**
+     * Pre‑computes {@link hashedUserId}.
+     *
+     * Must be awaited **once** before any other interaction.
+     * Returns `this` for fluent chaining.
+     */
+    setup(): Promise<this>;
+    /**
+     * Registers a **new** resident credential (pass‑key) with the user’s
+     * authenticator and returns a SCALE‑ready attestation.
+     *
+     * @param blockNumber - The number of the block whose hash seeds the challenge.
+     * @param blockHash   - The block hash used to derive a deterministic challenge.
+     * @param [displayName=this.userId] - Friendly name shown by the authenticator.
+     *
+     * @throws Error If this instance already has a credential id.
+     * @returns {Promise<TAttestation<number>>} SCALE‑encoded attestation object.
+     */
+    register(blockNumber: number, blockHash: BlockHash, displayName?: string): Promise<TAttestation<number>>;
+    /**
+     * Signs an arbitrary challenge with the pass‑key and produces a
+     * {@link TPassAuthenticate} payload understood by `PassSigner`.
+     *
+     * @param challenge - 32‑byte buffer supplied by the runtime.
+     * @param context   - Block number (or any numeric context expected by the pallet).
+     *
+     * @returns SCALE‑encoded authentication payload.
+     * @throws Error If no credential id is available.
+     */
+    authenticate(challenge: Uint8Array, context: number): Promise<TPassAuthenticate>;
+}

package/dist/esm/index.js

@@ -0,0 +1,181 @@
+/**
+ * WebAuthn pass‑key authenticator for Virto Network.
+ *
+ * Exposes a browser‑side implementation of {@link Authenticator} that creates,
+ * stores, and uses WebAuthn resident credentials ("passkeys") while producing
+ * SCALE‑encoded data structures understood by the Kreivo signer pallet.
+ *
+ * Responsibilities
+ * ─────────────────────────────────────────────────────────
+ * • Derive a deterministic `deviceId` from the raw credential id
+ * • Emit `TAttestation<number>` during registration
+ * • Emit `TPassAuthenticate` during authentication
+ * • Never persist the credential mapping; that is delegated to the caller
+ *
+ * @module WebAuthn
+ */
+import { KreivoBlockChallenger, } from "@virtonetwork/signer";
+import { Binary, Blake2256 } from "@polkadot-api/substrate-bindings";
+import { Assertion } from "./types.js";
+import { fromHex } from "polkadot-api/utils";
+/** Fixed authority id for Kreivo pass‑key attestors. */
+export const KREIVO_AUTHORITY_ID = Binary.fromText("kreivo_p".padEnd(32, "\0"));
+/**
+ * Browser‑side Authenticator that wraps the WebAuthn API.
+ *
+ * The generic type parameter `<number>` indicates that the **context**
+ * carried inside attestations and assertions is the block number that
+ * originated the challenge.
+ *
+ * @implements {Authenticator<number>}
+ */
+export class WebAuthn {
+    userId;
+    credentialId;
+    /**
+     * SHA‑256 hash of {@link userId}. Filled once by {@link setup} and reused
+     * for all WebAuthn operations.
+     */
+    hashedUserId = new Uint8Array(32);
+    /**
+     * Creates a new WebAuthn helper.
+     *
+     * @param userId - Logical user identifier (e‑mail, DID, etc.).
+     * @param [credentialId] - Raw credential id obtained from a previous
+     *   registration flow; omit it if the user must enrol a new pass‑key.
+     */
+    constructor(userId, credentialId) {
+        this.userId = userId;
+        this.credentialId = credentialId;
+    }
+    /**
+     * Deterministic identifier of the hardware/software authenticator
+     * (`deviceId = Blake2‑256(credentialId)`).
+     *
+     * @returns DeviceId suitable for on‑chain storage.
+     * @throws Error If this instance does not yet know a credential id.
+     */
+    static async getDeviceId(wa) {
+        if (!wa.credentialId) {
+            throw new Error("credentialId unknown – call register() first or inject it via constructor/setCredentialId()");
+        }
+        return Binary.fromBytes(Blake2256(wa.credentialId));
+    }
+    /**
+     * Injects a credential id discovered by the caller after construction.
+     *
+     * @param id - Raw credential id obtained from storage or backend.
+     */
+    setCredentialId(id) {
+        this.credentialId = id;
+    }
+    /**
+     * Pre‑computes {@link hashedUserId}.
+     *
+     * Must be awaited **once** before any other interaction.
+     * Returns `this` for fluent chaining.
+     */
+    async setup() {
+        this.hashedUserId = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(this.userId)));
+        return this;
+    }
+    /**
+     * Registers a **new** resident credential (pass‑key) with the user’s
+     * authenticator and returns a SCALE‑ready attestation.
+     *
+     * @param blockNumber - The number of the block whose hash seeds the challenge.
+     * @param blockHash   - The block hash used to derive a deterministic challenge.
+     * @param [displayName=this.userId] - Friendly name shown by the authenticator.
+     *
+     * @throws Error If this instance already has a credential id.
+     * @returns {Promise<TAttestation<number>>} SCALE‑encoded attestation object.
+     */
+    async register(blockNumber, blockHash, displayName = this.userId) {
+        if (this.credentialId) {
+            throw new Error("Already have a credentialId; no need to register");
+        }
+        const challenger = new KreivoBlockChallenger();
+        const challenge = challenger.generate(fromHex(blockHash), new Uint8Array());
+        const credentials = (await navigator.credentials.create({
+            publicKey: {
+                challenge,
+                rp: { name: "Virto Passkeys" },
+                user: {
+                    id: this.hashedUserId,
+                    name: this.userId,
+                    displayName,
+                },
+                pubKeyCredParams: [{ type: "public-key", alg: -7 /* ES256 */ }],
+                authenticatorSelection: { userVerification: "preferred" },
+                attestation: "none",
+                timeout: 60_000,
+            },
+        }));
+        const { attestationObject, clientDataJSON, getPublicKey } = credentials.response;
+        // Save raw credential id for future auth calls
+        this.credentialId = new Uint8Array(credentials.rawId);
+        // Ensure publicKey is obtained in the registration process.
+        const publicKey = getPublicKey();
+        if (!publicKey) {
+            throw new Error("The credentials don't expose a public key. Please use another authenticator device.");
+        }
+        return {
+            meta: {
+                authorityId: KREIVO_AUTHORITY_ID,
+                deviceId: await WebAuthn.getDeviceId(this),
+                context: blockNumber,
+            },
+            authenticatorData: Binary.fromBytes(new Uint8Array(attestationObject)),
+            clientData: Binary.fromBytes(new Uint8Array(clientDataJSON)),
+            publicKey: Binary.fromBytes(new Uint8Array(publicKey)),
+        };
+    }
+    /**
+     * Signs an arbitrary challenge with the pass‑key and produces a
+     * {@link TPassAuthenticate} payload understood by `PassSigner`.
+     *
+     * @param challenge - 32‑byte buffer supplied by the runtime.
+     * @param context   - Block number (or any numeric context expected by the pallet).
+     *
+     * @returns SCALE‑encoded authentication payload.
+     * @throws Error If no credential id is available.
+     */
+    async authenticate(challenge, context) {
+        if (!this.credentialId) {
+            throw new Error("credentialId unknown – call register() first or inject it via constructor/setCredentialId()");
+        }
+        const publicKey = {
+            challenge,
+            allowCredentials: [
+                {
+                    id: this.credentialId.buffer,
+                    type: "public-key",
+                    transports: ["usb", "ble", "nfc", "internal"],
+                },
+            ],
+            userVerification: "preferred",
+            timeout: 60_000,
+        };
+        const cred = (await navigator.credentials.get({
+            publicKey,
+        }));
+        const { authenticatorData, clientDataJSON, signature } = cred.response;
+        const assertion = {
+            meta: {
+                authorityId: KREIVO_AUTHORITY_ID,
+                userId: Binary.fromBytes(this.hashedUserId),
+                context,
+            },
+            authenticatorData: Binary.fromBytes(new Uint8Array(authenticatorData)),
+            clientData: Binary.fromBytes(new Uint8Array(clientDataJSON)),
+            signature: Binary.fromBytes(new Uint8Array(signature)),
+        };
+        return {
+            deviceId: await WebAuthn.getDeviceId(this),
+            credentials: {
+                tag: "WebAuthn",
+                value: Assertion.enc(assertion),
+            },
+        };
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,28 @@
+import { AuthorityId, DeviceId, HashedUserId } from "@virtonetwork/signer";
+import { Binary, HexString } from "@polkadot-api/substrate-bindings";
+import { Codec } from "scale-ts";
+export type BlockHash = HexString;
+export type TAttestationMeta<Cx> = {
+    authorityId: AuthorityId;
+    deviceId: DeviceId;
+    context: Cx;
+};
+export type TAttestation<Cx> = {
+    meta: TAttestationMeta<Cx>;
+    authenticatorData: Binary;
+    clientData: Binary;
+    publicKey: Binary;
+};
+export declare const Attestation: Codec<TAttestation<number>>;
+export type TAssertionMeta<Cx> = {
+    authorityId: AuthorityId;
+    userId: HashedUserId;
+    context: Cx;
+};
+export type TAssertion<Cx> = {
+    meta: TAssertionMeta<Cx>;
+    authenticatorData: Binary;
+    clientData: Binary;
+    signature: Binary;
+};
+export declare const Assertion: Codec<TAssertion<number>>;

package/dist/esm/types.js

@@ -0,0 +1,24 @@
+import { Bin } from "@polkadot-api/substrate-bindings";
+import { Struct, u32 } from "scale-ts";
+const AttestationMeta = Struct({
+    authorityId: Bin(32),
+    deviceId: Bin(32),
+    context: u32,
+});
+export const Attestation = Struct({
+    meta: AttestationMeta,
+    authenticatorData: Bin(),
+    clientData: Bin(),
+    publicKey: Bin(),
+});
+const AssertionMeta = Struct({
+    authorityId: Bin(32),
+    userId: Bin(32),
+    context: u32,
+});
+export const Assertion = Struct({
+    meta: AssertionMeta,
+    authenticatorData: Bin(),
+    clientData: Bin(),
+    signature: Bin(),
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@virtonetwork/authenticators-webauthn",
+  "description": "An Authenticator compatible with KreivoPassSigner that uses the WebAuthn standard",
+  "version": "1.0.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "module": "./dist/esm/index.js",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "browser": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "scripts": {
+    "test": "node --loader ts-node/esm test/test.ts",
+    "build": "tsc && tsc -p tsconfig.cjs.json",
+    "prepack": "npm run build"
+  },
+  "author": "Virto Network <contact@virto.networks>",
+  "license": "MIT",
+  "keywords": [
+    "virto-sdk",
+    "signer",
+    "papi",
+    "scale",
+    "polkadot.js",
+    "polkadot"
+  ],
+  "dependencies": {
+    "@simplewebauthn/server": "^13.1.1",
+    "@virtonetwork/signer": "^1.0.4",
+    "nid-webauthn-emulator": "^0.2.4"
+  },
+  "devDependencies": {
+    "esmock": "^2.7.0",
+    "sinon": "^20.0.0",
+    "ts-node": "^10.9.2"
+  },
+  "repository": {
+    "url": "https://github.com/virto-network/papi-signers",
+    "directory": "authenticators/webauthn"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}