humankey 0.2.0

package/dist/index.cjs

@@ -0,0 +1,167 @@
+"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"
+    );
+  }
+}
+
+// src/tap.ts
+var _browser = require('@simplewebauthn/browser');
+async function requestTap(request) {
+  const {
+    challenge,
+    action,
+    confirmation,
+    userInput,
+    allowCredentials,
+    rpID,
+    userVerification = "required",
+    timeout = 6e4
+  } = request;
+  validateConfirmation(confirmation, userInput);
+  const actionHashBuffer = await _chunkJI6NIMGKcjs.hashAction.call(void 0, action);
+  const confirmationInput = `${confirmation.code}:${userInput.toUpperCase().trim()}`;
+  const confirmationHashBuffer = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(confirmationInput)
+  );
+  const challengeBuffer = _chunkJI6NIMGKcjs.base64urlToBuffer.call(void 0, challenge);
+  const finalChallenge = await _chunkJI6NIMGKcjs.combineAndHash.call(void 0, 
+    challengeBuffer,
+    actionHashBuffer,
+    confirmationHashBuffer
+  );
+  const actionHash = _chunkJI6NIMGKcjs.bufferToBase64url.call(void 0, actionHashBuffer);
+  const confirmationHash = _chunkJI6NIMGKcjs.bufferToBase64url.call(void 0, confirmationHashBuffer);
+  try {
+    const response = await _browser.startAuthentication.call(void 0, {
+      optionsJSON: {
+        challenge: _chunkJI6NIMGKcjs.bufferToBase64url.call(void 0, 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 (0, _chunkJI6NIMGKcjs.HumanKeyError)(
+        "User cancelled the hardware key tap",
+        "USER_CANCELLED",
+        error
+      );
+    }
+    throw error;
+  }
+}
+
+// src/register.ts
+
+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
+    );
+  }
+}
+
+// src/support.ts
+function isHumanKeySupported() {
+  return typeof window !== "undefined" && typeof window.PublicKeyCredential !== "undefined" && typeof navigator.credentials !== "undefined";
+}
+
+
+
+
+
+
+
+
+exports.HumanKeyError = _chunkJI6NIMGKcjs.HumanKeyError; exports.createConfirmation = createConfirmation; exports.hashAction = _chunkJI6NIMGKcjs.hashAction; exports.isHumanKeySupported = isHumanKeySupported; exports.registerKey = registerKey; exports.requestTap = requestTap; exports.validateConfirmation = validateConfirmation;

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import { A as ActionPayload, C as Confirmation, T as TapRequest, a as TapProof, R as RegisterKeyRequest, b as RegistrationResult } from './types-By44RNIt.cjs';
+export { c as TapCredential, V as VerifyResult, d as VerifyTapProofRequest } from './types-By44RNIt.cjs';
+export { H as HumanKeyError, a as HumanKeyErrorCode } from './errors-BmtCXo7w.cjs';
+import '@simplewebauthn/server';
+
+/**
+ * Generate a confirmation challenge for an action.
+ * Returns a Confirmation containing a 4-char code derived from the action hash.
+ * The developer shows this code in their UI and asks the user to type it back.
+ */
+declare function createConfirmation(action: ActionPayload): Promise<Confirmation>;
+/**
+ * Validate that the user's input matches the expected confirmation code.
+ * Case-insensitive comparison.
+ * Throws CONFIRMATION_MISMATCH if the input doesn't match.
+ */
+declare function validateConfirmation(confirmation: Confirmation, userInput: string): void;
+
+/**
+ * Request a hardware key tap to approve an action.
+ * Requires a valid confirmation (user must have typed the correct code).
+ *
+ * Flow:
+ * 1. Validates the confirmation code
+ * 2. Hashes the action + confirmation into the WebAuthn challenge
+ * 3. Prompts the user to tap their hardware key
+ * 4. Returns a TapProof containing the signed assertion
+ */
+declare function requestTap(request: TapRequest): Promise<TapProof>;
+
+/**
+ * Register a new hardware key for per-action verification.
+ * Defaults to cross-platform authenticators (YubiKey, not Touch ID)
+ * and direct attestation (verifies real hardware).
+ */
+declare function registerKey(request: RegisterKeyRequest): Promise<RegistrationResult>;
+
+/**
+ * Check if WebAuthn is supported in this browser.
+ * Returns true if the browser supports the credential management API
+ * needed for hardware key authentication.
+ */
+declare function isHumanKeySupported(): boolean;
+
+/**
+ * SHA-256 hash of canonicalized action JSON.
+ * Canonical form: keys sorted alphabetically, no whitespace.
+ * Works in both browser and Node.js (via globalThis.crypto).
+ */
+declare function hashAction(action: ActionPayload): Promise<ArrayBuffer>;
+
+export { ActionPayload, Confirmation, RegisterKeyRequest, RegistrationResult, TapProof, TapRequest, createConfirmation, hashAction, isHumanKeySupported, registerKey, requestTap, validateConfirmation };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { A as ActionPayload, C as Confirmation, T as TapRequest, a as TapProof, R as RegisterKeyRequest, b as RegistrationResult } from './types-By44RNIt.js';
+export { c as TapCredential, V as VerifyResult, d as VerifyTapProofRequest } from './types-By44RNIt.js';
+export { H as HumanKeyError, a as HumanKeyErrorCode } from './errors-BmtCXo7w.js';
+import '@simplewebauthn/server';
+
+/**
+ * Generate a confirmation challenge for an action.
+ * Returns a Confirmation containing a 4-char code derived from the action hash.
+ * The developer shows this code in their UI and asks the user to type it back.
+ */
+declare function createConfirmation(action: ActionPayload): Promise<Confirmation>;
+/**
+ * Validate that the user's input matches the expected confirmation code.
+ * Case-insensitive comparison.
+ * Throws CONFIRMATION_MISMATCH if the input doesn't match.
+ */
+declare function validateConfirmation(confirmation: Confirmation, userInput: string): void;
+
+/**
+ * Request a hardware key tap to approve an action.
+ * Requires a valid confirmation (user must have typed the correct code).
+ *
+ * Flow:
+ * 1. Validates the confirmation code
+ * 2. Hashes the action + confirmation into the WebAuthn challenge
+ * 3. Prompts the user to tap their hardware key
+ * 4. Returns a TapProof containing the signed assertion
+ */
+declare function requestTap(request: TapRequest): Promise<TapProof>;
+
+/**
+ * Register a new hardware key for per-action verification.
+ * Defaults to cross-platform authenticators (YubiKey, not Touch ID)
+ * and direct attestation (verifies real hardware).
+ */
+declare function registerKey(request: RegisterKeyRequest): Promise<RegistrationResult>;
+
+/**
+ * Check if WebAuthn is supported in this browser.
+ * Returns true if the browser supports the credential management API
+ * needed for hardware key authentication.
+ */
+declare function isHumanKeySupported(): boolean;
+
+/**
+ * SHA-256 hash of canonicalized action JSON.
+ * Canonical form: keys sorted alphabetically, no whitespace.
+ * Works in both browser and Node.js (via globalThis.crypto).
+ */
+declare function hashAction(action: ActionPayload): Promise<ArrayBuffer>;
+
+export { ActionPayload, Confirmation, RegisterKeyRequest, RegistrationResult, TapProof, TapRequest, createConfirmation, hashAction, isHumanKeySupported, registerKey, requestTap, validateConfirmation };

package/dist/index.mjs

@@ -0,0 +1,167 @@
+import {
+  HumanKeyError,
+  base64urlToBuffer,
+  bufferToBase64url,
+  combineAndHash,
+  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"
+    );
+  }
+}
+
+// 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;
+  }
+}
+
+// src/register.ts
+import { startRegistration } from "@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 = bufferToBase64url(userIdHash);
+  try {
+    const response = await startRegistration({
+      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 HumanKeyError(
+        "User cancelled hardware key registration",
+        "USER_CANCELLED",
+        error
+      );
+    }
+    throw new HumanKeyError(
+      `Registration failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      "REGISTRATION_FAILED",
+      error
+    );
+  }
+}
+
+// src/support.ts
+function isHumanKeySupported() {
+  return typeof window !== "undefined" && typeof window.PublicKeyCredential !== "undefined" && typeof navigator.credentials !== "undefined";
+}
+export {
+  HumanKeyError,
+  createConfirmation,
+  hashAction,
+  isHumanKeySupported,
+  registerKey,
+  requestTap,
+  validateConfirmation
+};

package/dist/types-By44RNIt.d.cts

@@ -0,0 +1,134 @@
+import { AuthenticatorTransportFuture, RegistrationResponseJSON, CredentialDeviceType, AuthenticationResponseJSON } from '@simplewebauthn/server';
+
+/** The action the user is approving */
+interface ActionPayload {
+    /** Unique action type identifier, e.g. "send-message", "approve-transfer" */
+    action: string;
+    /** Arbitrary data that gets hashed into the challenge. Supports nested objects and arrays. */
+    data: Record<string, unknown>;
+}
+/** Output of createConfirmation() — contains the code the user must type */
+interface Confirmation {
+    /** 4-character alphanumeric code derived from the action hash */
+    code: string;
+    /** The SHA-256 hash of the canonical action JSON (base64url) */
+    actionHash: string;
+}
+/** Input for requestTap() */
+interface TapRequest {
+    /** Server-generated challenge (base64url) */
+    challenge: string;
+    /** The action being approved */
+    action: ActionPayload;
+    /** Confirmation from createConfirmation() */
+    confirmation: Confirmation;
+    /** What the user actually typed as their confirmation code */
+    userInput: string;
+    /** Credential IDs the user can authenticate with */
+    allowCredentials: Array<{
+        id: string;
+        transports?: AuthenticatorTransportFuture[];
+    }>;
+    /** Relying party ID, e.g. "example.com" */
+    rpID: string;
+    /** User verification requirement (default: 'required') */
+    userVerification?: UserVerificationRequirement;
+    /** Timeout in ms (default: 60000) */
+    timeout?: number;
+}
+/** The signed proof returned by requestTap() — send this to your server */
+interface TapProof {
+    /** The raw WebAuthn authentication response */
+    response: AuthenticationResponseJSON;
+    /** The action that was approved */
+    action: ActionPayload;
+    /** The action hash that was signed (base64url) */
+    actionHash: string;
+    /** The confirmation hash that was signed (base64url) */
+    confirmationHash: string;
+    /** The user's confirmation input */
+    userInput: string;
+}
+/** Input for registerKey() */
+interface RegisterKeyRequest {
+    /** Server-generated challenge (base64url) */
+    challenge: string;
+    /** Relying party ID */
+    rpID: string;
+    /** Relying party display name */
+    rpName: string;
+    /** Username for this credential */
+    userName: string;
+    /** Display name (defaults to userName) */
+    userDisplayName?: string;
+    /** Credential IDs to exclude (already registered) */
+    excludeCredentials?: Array<{
+        id: string;
+        transports?: AuthenticatorTransportFuture[];
+    }>;
+    /** Attestation type (default: 'direct' — verifies real hardware key) */
+    attestation?: AttestationConveyancePreference;
+    /** User verification requirement (default: 'required') */
+    userVerification?: UserVerificationRequirement;
+    /** Timeout in ms (default: 60000) */
+    timeout?: number;
+}
+/** A registered credential — store this server-side */
+interface TapCredential {
+    /** Base64url credential ID */
+    id: string;
+    /** The credential public key bytes */
+    publicKey: Uint8Array;
+    /** Signature counter for replay detection */
+    counter: number;
+    /** Transports the authenticator supports */
+    transports?: AuthenticatorTransportFuture[];
+    /** Single-device or multi-device credential */
+    deviceType: CredentialDeviceType;
+    /** Whether the credential is backed up */
+    backedUp: boolean;
+    /** Authenticator AAGUID — identifies the make/model of the hardware key */
+    aaguid: string;
+}
+/** Result of registerKey() — send the response to your server for verification */
+interface RegistrationResult {
+    /** Base64url credential ID */
+    credentialId: string;
+    /** The raw registration response — send to your server for verifyRegistration() */
+    response: RegistrationResponseJSON;
+    /** Transports the authenticator supports */
+    transports?: AuthenticatorTransportFuture[];
+}
+/** Input for verifyTapProof() */
+interface VerifyTapProofRequest {
+    /** The TapProof from the client */
+    proof: TapProof;
+    /** The stored credential for this user */
+    credential: TapCredential;
+    /** The challenge you generated server-side (base64url) */
+    expectedChallenge: string;
+    /** Your server's copy of the action (used to re-derive hashes) */
+    expectedAction: ActionPayload;
+    /** Expected origin(s), e.g. "https://example.com" */
+    expectedOrigin: string | string[];
+    /** Expected relying party ID */
+    expectedRPID: string;
+    /** Require user verification (default: true) */
+    requireUserVerification?: boolean;
+    /** When true (default), throw CONFIRMATION_MISMATCH if the user typed the wrong code.
+     *  Set to false to handle confirmation validation manually via result.confirmationValid. */
+    requireConfirmation?: boolean;
+}
+/** Result of verifyTapProof() */
+interface VerifyResult {
+    /** Overall verification passed */
+    verified: boolean;
+    /** User verification (biometric/PIN) was performed */
+    userVerified: boolean;
+    /** User typed the correct confirmation code for this action */
+    confirmationValid: boolean;
+    /** Updated signature counter — store this */
+    newCounter: number;
+}
+
+export type { ActionPayload as A, Confirmation as C, RegisterKeyRequest as R, TapRequest as T, VerifyResult as V, TapProof as a, RegistrationResult as b, TapCredential as c, VerifyTapProofRequest as d };