@exortek/challenge 1.0.0

package/dist/token.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Token codec for `@exortek/challenge`.
+ *
+ * Format:
+ *
+ *     <prefix>.<base64url(JSON payload)>.<base64url(HMAC-SHA256 tag)>
+ *
+ * The default prefix is {@link DEFAULT_PREFIX} (`chall_v1`) — deliberately
+ * unlike a JWT so the two token families cannot be confused at a call
+ * site. Callers may override it (e.g. `'server_challenge'`,
+ * `'myapp_v1'`) to brand the wire format for a specific service; the
+ * same prefix must be used at create and verify time, or verification
+ * returns `reason: 'malformed'`.
+ *
+ * HMAC covers `<prefix>.<b64u payload>` — the same string the caller
+ * received minus the trailing tag. Any change to prefix or payload
+ * invalidates the signature; a token minted with one prefix cannot be
+ * accepted under another even by the same secret.
+ */
+export declare const DEFAULT_PREFIX = "chall_v1";
+/**
+ * Assert a prefix is well-shaped. Throws via the caller's `invalidArg`
+ * function so `createChallenge` / `verifyChallenge` can raise
+ * `ChallengeError` with the right code — this module stays free of the
+ * error class dependency.
+ *
+ * @param {string} prefix
+ * @param {string} name
+ * @param {(msg: string) => Error} invalidArg
+ * @returns {string}
+ */
+export declare function assertPrefix(prefix: string, name: string, invalidArg: (msg: string) => Error): string;
+/**
+ * Random ID for the token's `jti` claim — 128 bits of entropy, encoded
+ * as 22 base64url characters. Used as the store key for single-use
+ * enforcement, so it must be unpredictable and unique per token.
+ *
+ * @returns {string}
+ */
+export declare function newJti(): string;
+/**
+ * Sign a payload with `secret` and return the compact token string.
+ *
+ * @param {object} payload
+ * @param {Buffer} secret     32+ raw bytes; caller validates length.
+ * @param {string} [prefix]   Wire prefix; defaults to {@link DEFAULT_PREFIX}.
+ * @returns {string}
+ */
+export declare function sign(payload: object, secret: Buffer, prefix?: string): string;
+/**
+ * Parse + HMAC-verify a token. Returns the decoded payload on success,
+ * or a reason string on any failure. Never throws on user-input
+ * problems — a wrong token is a normal auth outcome.
+ *
+ * @param {string} token
+ * @param {Buffer} secret
+ * @param {string} [prefix]   Expected prefix; defaults to {@link DEFAULT_PREFIX}.
+ * @returns {{ payload: object } | { reason: 'malformed' | 'bad_signature' }}
+ */
+export declare function decode(token: string, secret: Buffer, prefix?: string): {
+    payload: object;
+} | {
+    reason: 'malformed' | 'bad_signature';
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@exortek/challenge",
+  "version": "1.0.0",
+  "description": "Signed, single-use challenge tokens for multi-step auth flows on Node.js — carries userId / method / step / metadata across a redirect or a second request without a server-side session; HMAC-signed, expiring, optional IP-binding, single-use enforcement via any @exortek/security store.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./stores": {
+      "types": "./dist/stores/index.d.ts",
+      "import": "./dist/stores.mjs",
+      "require": "./dist/stores.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && rollup -c rollup.config.js && tsc -p tsconfig.json",
+    "build:watch": "rollup -c rollup.config.js --watch",
+    "build:types": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test 'tests/**/*.test.js'",
+    "test:coverage": "node --test --experimental-test-coverage 'tests/**/*.test.js'",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "cp ../../LICENSE ./LICENSE"
+  },
+  "keywords": [
+    "backend",
+    "security",
+    "auth",
+    "mfa",
+    "2fa",
+    "challenge",
+    "multi-step",
+    "signed-token",
+    "hmac",
+    "single-use",
+    "flow-token",
+    "step-up",
+    "node-crypto"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/ExorTek/auth/tree/master/packages/challenge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExorTek/auth.git",
+    "directory": "packages/challenge"
+  },
+  "bugs": {
+    "url": "https://github.com/ExorTek/auth/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@exortek/shared": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}