humankey 0.2.0

package/dist/types-By44RNIt.d.ts

@@ -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 };

package/dist/verify.cjs

@@ -0,0 +1,14 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunkFW3YUVJCcjs = require('./chunk-FW3YUVJC.cjs');
+
+
+var _chunkJI6NIMGKcjs = require('./chunk-JI6NIMGK.cjs');
+
+
+
+
+
+exports.HumanKeyError = _chunkJI6NIMGKcjs.HumanKeyError; exports.createChallenge = _chunkFW3YUVJCcjs.createChallenge; exports.verifyRegistration = _chunkFW3YUVJCcjs.verifyRegistration; exports.verifyTapProof = _chunkFW3YUVJCcjs.verifyTapProof;

package/dist/verify.d.cts

@@ -0,0 +1,59 @@
+import { c as TapCredential, d as VerifyTapProofRequest, V as VerifyResult } from './types-By44RNIt.cjs';
+export { A as ActionPayload, a as TapProof } from './types-By44RNIt.cjs';
+export { H as HumanKeyError, a as HumanKeyErrorCode } from './errors-BmtCXo7w.cjs';
+import { RegistrationResponseJSON } from '@simplewebauthn/server';
+export { RegistrationResponseJSON } from '@simplewebauthn/server';
+
+/**
+ * Generate a cryptographically random challenge string (base64url).
+ * Use this server-side to create challenges for registration and tap flows.
+ *
+ * @param byteLength Number of random bytes (default: 32, producing a 256-bit challenge)
+ * @returns A base64url-encoded random challenge string
+ */
+declare function createChallenge(byteLength?: number): string;
+
+/** Input for verifyRegistration() */
+interface VerifyRegistrationRequest {
+    /** The registration response from the client */
+    response: RegistrationResponseJSON;
+    /** The challenge you generated server-side (base64url) */
+    expectedChallenge: string;
+    /** Expected origin(s), e.g. "https://example.com" */
+    expectedOrigin: string | string[];
+    /** Expected relying party ID */
+    expectedRPID?: string | string[];
+    /** Require user verification (default: true) */
+    requireUserVerification?: boolean;
+    /** Restrict registration to specific authenticator models by AAGUID.
+     *  When set, only authenticators with a matching AAGUID are accepted. */
+    allowedAAGUIDs?: string[];
+}
+/** Result of verifyRegistration() */
+interface VerifyRegistrationResult {
+    /** The verified credential — store this server-side */
+    credential: TapCredential;
+    /** Whether the registration was verified */
+    verified: boolean;
+}
+/**
+ * Verify a registration response on the server and extract the credential.
+ * Wraps @simplewebauthn/server's verifyRegistrationResponse and returns
+ * a TapCredential ready for storage.
+ */
+declare function verifyRegistration(request: VerifyRegistrationRequest): Promise<VerifyRegistrationResult>;
+
+/**
+ * Verify a TapProof on the server.
+ * Re-derives all hashes from the server's copy of the action to ensure integrity.
+ *
+ * Checks:
+ * 1. Action hash matches (client didn't tamper with the action)
+ * 2. Confirmation code is valid for this action
+ * 3. WebAuthn signature is valid
+ * 4. User verification flag is set (independent of browser claim)
+ * 5. Signature counter increased (replay protection)
+ */
+declare function verifyTapProof(request: VerifyTapProofRequest): Promise<VerifyResult>;
+
+export { TapCredential, type VerifyRegistrationRequest, type VerifyRegistrationResult, VerifyResult, VerifyTapProofRequest, createChallenge, verifyRegistration, verifyTapProof };

package/dist/verify.d.ts

@@ -0,0 +1,59 @@
+import { c as TapCredential, d as VerifyTapProofRequest, V as VerifyResult } from './types-By44RNIt.js';
+export { A as ActionPayload, a as TapProof } from './types-By44RNIt.js';
+export { H as HumanKeyError, a as HumanKeyErrorCode } from './errors-BmtCXo7w.js';
+import { RegistrationResponseJSON } from '@simplewebauthn/server';
+export { RegistrationResponseJSON } from '@simplewebauthn/server';
+
+/**
+ * Generate a cryptographically random challenge string (base64url).
+ * Use this server-side to create challenges for registration and tap flows.
+ *
+ * @param byteLength Number of random bytes (default: 32, producing a 256-bit challenge)
+ * @returns A base64url-encoded random challenge string
+ */
+declare function createChallenge(byteLength?: number): string;
+
+/** Input for verifyRegistration() */
+interface VerifyRegistrationRequest {
+    /** The registration response from the client */
+    response: RegistrationResponseJSON;
+    /** The challenge you generated server-side (base64url) */
+    expectedChallenge: string;
+    /** Expected origin(s), e.g. "https://example.com" */
+    expectedOrigin: string | string[];
+    /** Expected relying party ID */
+    expectedRPID?: string | string[];
+    /** Require user verification (default: true) */
+    requireUserVerification?: boolean;
+    /** Restrict registration to specific authenticator models by AAGUID.
+     *  When set, only authenticators with a matching AAGUID are accepted. */
+    allowedAAGUIDs?: string[];
+}
+/** Result of verifyRegistration() */
+interface VerifyRegistrationResult {
+    /** The verified credential — store this server-side */
+    credential: TapCredential;
+    /** Whether the registration was verified */
+    verified: boolean;
+}
+/**
+ * Verify a registration response on the server and extract the credential.
+ * Wraps @simplewebauthn/server's verifyRegistrationResponse and returns
+ * a TapCredential ready for storage.
+ */
+declare function verifyRegistration(request: VerifyRegistrationRequest): Promise<VerifyRegistrationResult>;
+
+/**
+ * Verify a TapProof on the server.
+ * Re-derives all hashes from the server's copy of the action to ensure integrity.
+ *
+ * Checks:
+ * 1. Action hash matches (client didn't tamper with the action)
+ * 2. Confirmation code is valid for this action
+ * 3. WebAuthn signature is valid
+ * 4. User verification flag is set (independent of browser claim)
+ * 5. Signature counter increased (replay protection)
+ */
+declare function verifyTapProof(request: VerifyTapProofRequest): Promise<VerifyResult>;
+
+export { TapCredential, type VerifyRegistrationRequest, type VerifyRegistrationResult, VerifyResult, VerifyTapProofRequest, createChallenge, verifyRegistration, verifyTapProof };

package/dist/verify.mjs

@@ -0,0 +1,14 @@
+import {
+  createChallenge,
+  verifyRegistration,
+  verifyTapProof
+} from "./chunk-XXJAJHNP.mjs";
+import {
+  HumanKeyError
+} from "./chunk-CLQSCDXC.mjs";
+export {
+  HumanKeyError,
+  createChallenge,
+  verifyRegistration,
+  verifyTapProof
+};

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "humankey",
+  "version": "0.2.0",
+  "description": "Per-action hardware key (YubiKey/FIDO2) verification SDK with built-in confirmation step",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./verify": {
+      "import": {
+        "types": "./dist/verify.d.ts",
+        "default": "./dist/verify.mjs"
+      },
+      "require": {
+        "types": "./dist/verify.d.cts",
+        "default": "./dist/verify.cjs"
+      }
+    },
+    "./express": {
+      "import": {
+        "types": "./dist/express.d.ts",
+        "default": "./dist/express.mjs"
+      },
+      "require": {
+        "types": "./dist/express.d.cts",
+        "default": "./dist/express.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "webauthn",
+    "fido2",
+    "yubikey",
+    "hardware-key",
+    "authentication",
+    "human-verification",
+    "per-action",
+    "security"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@simplewebauthn/server": "^13.3.0"
+  },
+  "peerDependencies": {
+    "@simplewebauthn/browser": "^13.3.0",
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@simplewebauthn/browser": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@simplewebauthn/browser": "^13.3.0",
+    "@types/express": "^5.0.6",
+    "@types/supertest": "^7.2.0",
+    "express": "^5.2.1",
+    "supertest": "^7.2.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}