humankey 0.2.0 → 0.3.1

package/README.md

@@ -25,7 +25,12 @@ humankey/
 │   ├── verify.ts             # Server-side proof verification (humankey/verify)
 │   ├── registration-verify.ts # Server-side registration verification
 │   ├── challenge.ts          # Server-side challenge generation
+│   ├── adapter-core.ts       # Shared handler logic for all framework adapters
 │   ├── express.ts            # Express framework adapter (humankey/express)
+│   ├── nextjs.ts             # Next.js App Router adapter (humankey/nextjs)
+│   ├── hono.ts               # Hono adapter (humankey/hono)
+│   ├── fastify.ts            # Fastify plugin (humankey/fastify)
+│   ├── react.ts              # React hook (humankey/react)
 │   ├── hash.ts               # SHA-256 canonical JSON hashing (isomorphic)
 │   ├── types.ts              # All type definitions
 │   └── errors.ts             # Typed error classes
@@ -36,10 +41,14 @@ humankey/
 └── examples/basic/           # Working Express + HTML example
 ```
 
-**Three entry points:**
+**Seven entry points:**
 - `humankey` — browser SDK (confirm + tap + register)
 - `humankey/verify` — server-side verification, registration, and challenge generation (any JS runtime)
 - `humankey/express` — Express router with built-in challenge lifecycle, registration, and verification
+- `humankey/nextjs` — Next.js App Router route handlers
+- `humankey/hono` — Hono app with humankey routes
+- `humankey/fastify` — Fastify plugin
+- `humankey/react` — React hook for the confirm → tap flow
 
 ## How It Works
 
@@ -61,10 +70,18 @@ npm install humankey @simplewebauthn/browser
 
 `@simplewebauthn/browser` is a peer dependency (only needed in the browser).
 
-For the Express adapter:
+For framework adapters, install the framework alongside humankey:
 
 ```bash
-npm install humankey express
+npm install humankey express        # Express
+npm install humankey hono           # Hono
+npm install humankey fastify        # Fastify
+```
+
+For the React hook:
+
+```bash
+npm install humankey @simplewebauthn/browser react
 ```
 
 ## Usage
@@ -143,6 +160,146 @@ class RedisChallengeStore implements ChallengeStore {
 }
 ```
 
+### Next.js Adapter
+
+For Next.js App Router. Each route handler is a separate file:
+
+```ts
+// app/api/humankey/challenge/route.ts
+import { createHumanKeyHandlers } from 'humankey/nextjs';
+import type { TapCredential } from 'humankey/verify';
+
+const credentials = new Map<string, TapCredential>();
+
+const hk = createHumanKeyHandlers({
+  rpID: 'example.com',
+  rpName: 'My App',
+  origin: 'https://example.com',
+  getCredential: async (id) => credentials.get(id) ?? null,
+  onRegister: async (credential) => {
+    credentials.set(credential.id, credential);
+  },
+});
+
+export const POST = hk.challenge;
+```
+
+```ts
+// app/api/humankey/register/route.ts
+export const POST = hk.register;
+
+// app/api/humankey/verify/route.ts
+export const POST = hk.verify;
+```
+
+Uses the Web `Request`/`Response` API — no Next.js-specific types required.
+
+### Hono Adapter
+
+```ts
+import { Hono } from 'hono';
+import { createHumanKeyApp } from 'humankey/hono';
+import type { TapCredential } from 'humankey/verify';
+
+const app = new Hono();
+const credentials = new Map<string, TapCredential>();
+
+app.route('/api', createHumanKeyApp({
+  rpID: 'example.com',
+  rpName: 'My App',
+  origin: 'https://example.com',
+  getCredential: async (id) => credentials.get(id) ?? null,
+  onRegister: async (credential) => {
+    credentials.set(credential.id, credential);
+  },
+}));
+
+export default app;
+```
+
+### Fastify Adapter
+
+```ts
+import Fastify from 'fastify';
+import { humanKeyPlugin } from 'humankey/fastify';
+import type { TapCredential } from 'humankey/verify';
+
+const app = Fastify();
+const credentials = new Map<string, TapCredential>();
+
+app.register(humanKeyPlugin, {
+  prefix: '/api',
+  rpID: 'example.com',
+  rpName: 'My App',
+  origin: 'https://example.com',
+  getCredential: async (id) => credentials.get(id) ?? null,
+  onRegister: async (credential) => {
+    credentials.set(credential.id, credential);
+  },
+});
+
+app.listen({ port: 3000 });
+```
+
+### React Hook
+
+The `useHumanKey` hook manages the full client-side flow: fetch challenge, show confirmation code, trigger hardware key tap, and verify.
+
+```tsx
+import { useHumanKey } from 'humankey/react';
+
+function TransferButton({ credentialId }: { credentialId: string }) {
+  const {
+    status,
+    confirmationCode,
+    error,
+    startAction,
+    confirmCode,
+    reset,
+  } = useHumanKey({ rpID: 'example.com', apiBase: '/api' });
+
+  const handleTransfer = async () => {
+    // Step 1: Start the action — fetches challenge, generates confirmation code
+    await startAction(
+      { action: 'transfer', data: { to: 'bob', amount: 100 } },
+      [{ id: credentialId }],
+    );
+    // status is now 'confirming', confirmationCode is e.g. 'A7X3'
+  };
+
+  const handleConfirm = async (userInput: string) => {
+    // Step 2: User typed the code — triggers YubiKey tap and server verification
+    const proof = await confirmCode(userInput);
+    // status is now 'verified', proof contains the signed assertion
+  };
+
+  return (
+    <div>
+      {status === 'idle' && <button onClick={handleTransfer}>Send $100</button>}
+      {status === 'confirming' && (
+        <div>
+          <p>Type this code: <strong>{confirmationCode}</strong></p>
+          <input onKeyDown={(e) => {
+            if (e.key === 'Enter') handleConfirm(e.currentTarget.value);
+          }} />
+        </div>
+      )}
+      {status === 'tapping' && <p>Tap your YubiKey...</p>}
+      {status === 'verified' && <p>Transfer approved!</p>}
+      {status === 'error' && <p>Error: {error?.message} <button onClick={reset}>Retry</button></p>}
+    </div>
+  );
+}
+```
+
+The hook also exposes a `register` function for one-time key registration:
+
+```tsx
+const { register } = useHumanKey({ rpID: 'example.com' });
+const result = await register('alice');
+// result.credentialId — store this for future use
+```
+
 ### Server (manual — challenge + registration + verify)
 
 ```ts
@@ -310,7 +467,11 @@ For production, consider:
 |---|---|---|
 | `humankey` | Browser | `createConfirmation`, `requestTap`, `registerKey`, `isHumanKeySupported`, `hashAction`, `HumanKeyError` |
 | `humankey/verify` | Server (any JS runtime) | `verifyTapProof`, `verifyRegistration`, `createChallenge`, `HumanKeyError` |
-| `humankey/express` | Server (Express) | `createHumanKeyRouter`, `MemoryChallengeStore`, `ChallengeStore`, `HumanKeyExpressConfig` |
+| `humankey/express` | Server (Express) | `createHumanKeyRouter`, `MemoryChallengeStore`, `ChallengeStore` |
+| `humankey/nextjs` | Server (Next.js App Router) | `createHumanKeyHandlers`, `MemoryChallengeStore`, `ChallengeStore` |
+| `humankey/hono` | Server (Hono) | `createHumanKeyApp`, `MemoryChallengeStore`, `ChallengeStore` |
+| `humankey/fastify` | Server (Fastify) | `humanKeyPlugin`, `MemoryChallengeStore`, `ChallengeStore` |
+| `humankey/react` | Browser (React) | `useHumanKey` |
 
 ### Error Codes
 

package/dist/adapter-core-CFN3y3L0.d.ts

@@ -0,0 +1,41 @@
+import { c as TapCredential, V as VerifyResult, A as ActionPayload } from './types-By44RNIt.js';
+
+/** Abstraction for challenge storage with TTL and single-use semantics. */
+interface ChallengeStore {
+    /** Store a challenge with a TTL. */
+    set(id: string, challenge: string, ttlMs: number): Promise<void>;
+    /** Retrieve and delete a challenge (single-use). Returns null if expired or not found. */
+    get(id: string): Promise<string | null>;
+}
+/** In-memory challenge store with TTL enforcement. Use a database or Redis in production. */
+declare class MemoryChallengeStore implements ChallengeStore {
+    private store;
+    set(id: string, challenge: string, ttlMs: number): Promise<void>;
+    get(id: string): Promise<string | null>;
+    private cleanup;
+}
+/** Shared configuration for all framework adapters. */
+interface HumanKeyAdapterConfig {
+    /** Relying party ID, e.g. "example.com" */
+    rpID: string;
+    /** Relying party display name */
+    rpName: string;
+    /** Expected origin(s), e.g. "https://example.com" */
+    origin: string | string[];
+    /** Challenge TTL in ms (default: 60000) */
+    challengeTTL?: number;
+    /** Custom challenge store (default: MemoryChallengeStore) */
+    challengeStore?: ChallengeStore;
+    /** Look up a stored credential by ID */
+    getCredential: (credentialId: string) => Promise<TapCredential | null>;
+    /** Called after successful registration — store the credential */
+    onRegister: (credential: TapCredential) => Promise<void>;
+    /** Called after successful tap verification */
+    onVerify?: (result: VerifyResult, action: ActionPayload) => Promise<void>;
+    /** Require user verification (default: true) */
+    requireUserVerification?: boolean;
+    /** Restrict to specific authenticator models by AAGUID */
+    allowedAAGUIDs?: string[];
+}
+
+export { type ChallengeStore as C, type HumanKeyAdapterConfig as H, MemoryChallengeStore as M };

package/dist/adapter-core-CoBcSqdG.d.cts

@@ -0,0 +1,41 @@
+import { c as TapCredential, V as VerifyResult, A as ActionPayload } from './types-By44RNIt.cjs';
+
+/** Abstraction for challenge storage with TTL and single-use semantics. */
+interface ChallengeStore {
+    /** Store a challenge with a TTL. */
+    set(id: string, challenge: string, ttlMs: number): Promise<void>;
+    /** Retrieve and delete a challenge (single-use). Returns null if expired or not found. */
+    get(id: string): Promise<string | null>;
+}
+/** In-memory challenge store with TTL enforcement. Use a database or Redis in production. */
+declare class MemoryChallengeStore implements ChallengeStore {
+    private store;
+    set(id: string, challenge: string, ttlMs: number): Promise<void>;
+    get(id: string): Promise<string | null>;
+    private cleanup;
+}
+/** Shared configuration for all framework adapters. */
+interface HumanKeyAdapterConfig {
+    /** Relying party ID, e.g. "example.com" */
+    rpID: string;
+    /** Relying party display name */
+    rpName: string;
+    /** Expected origin(s), e.g. "https://example.com" */
+    origin: string | string[];
+    /** Challenge TTL in ms (default: 60000) */
+    challengeTTL?: number;
+    /** Custom challenge store (default: MemoryChallengeStore) */
+    challengeStore?: ChallengeStore;
+    /** Look up a stored credential by ID */
+    getCredential: (credentialId: string) => Promise<TapCredential | null>;
+    /** Called after successful registration — store the credential */
+    onRegister: (credential: TapCredential) => Promise<void>;
+    /** Called after successful tap verification */
+    onVerify?: (result: VerifyResult, action: ActionPayload) => Promise<void>;
+    /** Require user verification (default: true) */
+    requireUserVerification?: boolean;
+    /** Restrict to specific authenticator models by AAGUID */
+    allowedAAGUIDs?: string[];
+}
+
+export { type ChallengeStore as C, type HumanKeyAdapterConfig as H, MemoryChallengeStore as M };

package/dist/chunk-2KMBF2TH.cjs

@@ -0,0 +1,27 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+var _chunkJI6NIMGKcjs = require('./chunk-JI6NIMGK.cjs');
+
+// src/confirm.ts
+async function createConfirmation(action) {
+  const hashBuffer = await _chunkJI6NIMGKcjs.hashAction.call(void 0, action);
+  const code = _chunkJI6NIMGKcjs.deriveConfirmationCode.call(void 0, hashBuffer);
+  const actionHash = _chunkJI6NIMGKcjs.bufferToBase64url.call(void 0, hashBuffer);
+  return { code, actionHash };
+}
+function validateConfirmation(confirmation, userInput) {
+  if (userInput.toUpperCase().trim() !== confirmation.code.toUpperCase()) {
+    throw new (0, _chunkJI6NIMGKcjs.HumanKeyError)(
+      "Confirmation code mismatch",
+      "CONFIRMATION_MISMATCH"
+    );
+  }
+}
+
+
+
+
+exports.createConfirmation = createConfirmation; exports.validateConfirmation = validateConfirmation;

package/dist/chunk-G2IT2ZP5.cjs

@@ -0,0 +1,124 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;
+
+
+
+var _chunkFW3YUVJCcjs = require('./chunk-FW3YUVJC.cjs');
+
+
+var _chunkJI6NIMGKcjs = require('./chunk-JI6NIMGK.cjs');
+
+// src/adapter-core.ts
+var MemoryChallengeStore = (_class = class {constructor() { _class.prototype.__init.call(this); }
+  __init() {this.store = /* @__PURE__ */ new Map()}
+  async set(id, challenge, ttlMs) {
+    this.store.set(id, { challenge, expiresAt: Date.now() + ttlMs });
+    this.cleanup();
+  }
+  async get(id) {
+    const entry = this.store.get(id);
+    if (!entry) return null;
+    this.store.delete(id);
+    if (Date.now() > entry.expiresAt) return null;
+    return entry.challenge;
+  }
+  cleanup() {
+    const now = Date.now();
+    for (const [id, entry] of this.store) {
+      if (now > entry.expiresAt) this.store.delete(id);
+    }
+  }
+}, _class);
+function resolveConfig(config) {
+  return {
+    rpID: config.rpID,
+    rpName: config.rpName,
+    origin: config.origin,
+    challengeTTL: _nullishCoalesce(config.challengeTTL, () => ( 6e4)),
+    challengeStore: _nullishCoalesce(config.challengeStore, () => ( new MemoryChallengeStore())),
+    getCredential: config.getCredential,
+    onRegister: config.onRegister,
+    onVerify: config.onVerify,
+    requireUserVerification: _nullishCoalesce(config.requireUserVerification, () => ( true)),
+    allowedAAGUIDs: config.allowedAAGUIDs
+  };
+}
+async function handleChallenge(config) {
+  try {
+    const challenge = _chunkFW3YUVJCcjs.createChallenge.call(void 0, );
+    const challengeId = crypto.randomUUID();
+    await config.challengeStore.set(challengeId, challenge, config.challengeTTL);
+    return { status: 200, body: { challengeId, challenge } };
+  } catch (e) {
+    return { status: 500, body: { error: "Internal server error" } };
+  }
+}
+async function handleRegister(config, body) {
+  try {
+    const challenge = await config.challengeStore.get(body.challengeId);
+    if (!challenge) {
+      return { status: 400, body: { error: "Challenge not found or expired" } };
+    }
+    const result = await _chunkFW3YUVJCcjs.verifyRegistration.call(void 0, {
+      response: body.response,
+      expectedChallenge: challenge,
+      expectedOrigin: config.origin,
+      expectedRPID: config.rpID,
+      requireUserVerification: config.requireUserVerification,
+      allowedAAGUIDs: config.allowedAAGUIDs
+    });
+    await config.onRegister(result.credential);
+    return { status: 200, body: { ok: true, credentialId: result.credential.id } };
+  } catch (error) {
+    return errorResult(error);
+  }
+}
+async function handleVerify(config, body) {
+  try {
+    const challenge = await config.challengeStore.get(body.challengeId);
+    if (!challenge) {
+      return { status: 400, body: { error: "Challenge not found or expired" } };
+    }
+    const proof = body.proof;
+    const credential = await config.getCredential(_optionalChain([proof, 'access', _ => _.response, 'optionalAccess', _2 => _2.id]));
+    if (!credential) {
+      return { status: 400, body: { error: "Credential not found" } };
+    }
+    const result = await _chunkFW3YUVJCcjs.verifyTapProof.call(void 0, {
+      proof,
+      credential,
+      expectedChallenge: challenge,
+      expectedAction: body.action,
+      expectedOrigin: config.origin,
+      expectedRPID: config.rpID,
+      requireUserVerification: config.requireUserVerification
+    });
+    credential.counter = result.newCounter;
+    if (config.onVerify) {
+      await config.onVerify(result, body.action);
+    }
+    return {
+      status: 200,
+      body: {
+        verified: result.verified,
+        confirmationValid: result.confirmationValid,
+        userVerified: result.userVerified
+      }
+    };
+  } catch (error) {
+    return errorResult(error);
+  }
+}
+function errorResult(error) {
+  if (error instanceof _chunkJI6NIMGKcjs.HumanKeyError) {
+    return { status: 400, body: { error: error.message, code: error.code } };
+  }
+  return { status: 500, body: { error: "Internal server error" } };
+}
+
+
+
+
+
+
+
+exports.MemoryChallengeStore = MemoryChallengeStore; exports.resolveConfig = resolveConfig; exports.handleChallenge = handleChallenge; exports.handleRegister = handleRegister; exports.handleVerify = handleVerify;

package/dist/chunk-G2X46ZRM.mjs

@@ -0,0 +1,27 @@
+import {
+  HumanKeyError,
+  bufferToBase64url,
+  deriveConfirmationCode,
+  hashAction
+} from "./chunk-CLQSCDXC.mjs";
+
+// src/confirm.ts
+async function createConfirmation(action) {
+  const hashBuffer = await hashAction(action);
+  const code = deriveConfirmationCode(hashBuffer);
+  const actionHash = bufferToBase64url(hashBuffer);
+  return { code, actionHash };
+}
+function validateConfirmation(confirmation, userInput) {
+  if (userInput.toUpperCase().trim() !== confirmation.code.toUpperCase()) {
+    throw new HumanKeyError(
+      "Confirmation code mismatch",
+      "CONFIRMATION_MISMATCH"
+    );
+  }
+}
+
+export {
+  createConfirmation,
+  validateConfirmation
+};

package/dist/chunk-RANGHXC7.mjs

@@ -0,0 +1,75 @@
+import {
+  validateConfirmation
+} from "./chunk-G2X46ZRM.mjs";
+import {
+  HumanKeyError,
+  base64urlToBuffer,
+  bufferToBase64url,
+  combineAndHash,
+  hashAction
+} from "./chunk-CLQSCDXC.mjs";
+
+// src/tap.ts
+import { startAuthentication } from "@simplewebauthn/browser";
+async function requestTap(request) {
+  const {
+    challenge,
+    action,
+    confirmation,
+    userInput,
+    allowCredentials,
+    rpID,
+    userVerification = "required",
+    timeout = 6e4
+  } = request;
+  validateConfirmation(confirmation, userInput);
+  const actionHashBuffer = await hashAction(action);
+  const confirmationInput = `${confirmation.code}:${userInput.toUpperCase().trim()}`;
+  const confirmationHashBuffer = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(confirmationInput)
+  );
+  const challengeBuffer = base64urlToBuffer(challenge);
+  const finalChallenge = await combineAndHash(
+    challengeBuffer,
+    actionHashBuffer,
+    confirmationHashBuffer
+  );
+  const actionHash = bufferToBase64url(actionHashBuffer);
+  const confirmationHash = bufferToBase64url(confirmationHashBuffer);
+  try {
+    const response = await startAuthentication({
+      optionsJSON: {
+        challenge: bufferToBase64url(finalChallenge),
+        rpId: rpID,
+        allowCredentials: allowCredentials.map((cred) => ({
+          id: cred.id,
+          type: "public-key",
+          transports: cred.transports
+        })),
+        userVerification,
+        timeout
+      }
+    });
+    return {
+      response,
+      action,
+      actionHash,
+      confirmationHash,
+      userInput: userInput.toUpperCase().trim()
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "NotAllowedError") {
+      throw new HumanKeyError(
+        "User cancelled the hardware key tap",
+        "USER_CANCELLED",
+        error
+      );
+    }
+    throw error;
+  }
+}
+
+export {
+  requestTap
+};

package/dist/chunk-RQSBOE7B.cjs

@@ -0,0 +1,76 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkJI6NIMGKcjs = require('./chunk-JI6NIMGK.cjs');
+
+// src/register.ts
+var _browser = require('@simplewebauthn/browser');
+async function registerKey(request) {
+  const {
+    challenge,
+    rpID,
+    rpName,
+    userName,
+    userDisplayName = userName,
+    excludeCredentials = [],
+    attestation = "direct",
+    userVerification = "required",
+    timeout = 6e4
+  } = request;
+  const userIdBytes = new TextEncoder().encode(userName);
+  const userIdHash = await crypto.subtle.digest("SHA-256", userIdBytes);
+  const userId = _chunkJI6NIMGKcjs.bufferToBase64url.call(void 0, userIdHash);
+  try {
+    const response = await _browser.startRegistration.call(void 0, {
+      optionsJSON: {
+        rp: { name: rpName, id: rpID },
+        user: {
+          id: userId,
+          name: userName,
+          displayName: userDisplayName
+        },
+        challenge,
+        pubKeyCredParams: [
+          { alg: -7, type: "public-key" },
+          // ES256
+          { alg: -257, type: "public-key" }
+          // RS256
+        ],
+        timeout,
+        attestation,
+        excludeCredentials: excludeCredentials.map((cred) => ({
+          id: cred.id,
+          type: "public-key",
+          transports: cred.transports
+        })),
+        authenticatorSelection: {
+          authenticatorAttachment: "cross-platform",
+          residentKey: "preferred",
+          userVerification
+        }
+      }
+    });
+    return {
+      credentialId: response.id,
+      response,
+      transports: response.response.transports
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "NotAllowedError") {
+      throw new (0, _chunkJI6NIMGKcjs.HumanKeyError)(
+        "User cancelled hardware key registration",
+        "USER_CANCELLED",
+        error
+      );
+    }
+    throw new (0, _chunkJI6NIMGKcjs.HumanKeyError)(
+      `Registration failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      "REGISTRATION_FAILED",
+      error
+    );
+  }
+}
+
+
+
+exports.registerKey = registerKey;