@exortek/apikey 1.0.0

package/dist/token.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @param {string} prefix
+ * @param {string} name
+ * @param {(msg: string) => Error} invalidArg
+ * @returns {string}
+ */
+export function assertPrefix(prefix: string, name: string, invalidArg: (msg: string) => Error): string;
+/**
+ * Mint the raw pieces of a new key. Returns the wire token, the
+ * plaintext id (for DB lookup), and the storage hash of the secret.
+ *
+ * @param {string} prefix
+ * @param {Buffer | null} pepper   Newest pepper, or null when unconfigured.
+ * @returns {{ key: string, id: string, hash: string }}
+ */
+export function mint(prefix: string, pepper: Buffer | null): {
+    key: string;
+    id: string;
+    hash: string;
+};
+/**
+ * Compute the storage hash of a raw secret. With a pepper: HMAC-SHA256
+ * keyed by the pepper. Without: plain SHA-256. Both return the digest
+ * as a 43-char base64url string.
+ *
+ * @param {Buffer} secretBytes
+ * @param {Buffer | null} pepper
+ * @returns {string}
+ */
+export function hashSecret(secretBytes: Buffer, pepper: Buffer | null): string;
+/**
+ * Timing-safe compare of a candidate hash against a stored hash. Both
+ * inputs are base64url strings of equal length — a length mismatch is
+ * treated as a mismatch after a fixed decode step, so an outside
+ * observer cannot learn the stored hash's length via timing.
+ *
+ * @param {string} candidate
+ * @param {string} stored
+ * @returns {boolean}
+ */
+export function hashesMatch(candidate: string, stored: string): boolean;
+/**
+ * Parse a raw key without verifying it. Returns the segments, or
+ * `null` when the shape is wrong. Never throws.
+ *
+ * Callers can use `parseApiKey(key).prefix` to route by key family
+ * in a middleware before hitting the store — but the parse result
+ * MUST NOT be trusted as authenticated. Only `verifyApiKey` proves
+ * the holder possesses the real secret.
+ *
+ * @param {string} key
+ * @returns {{ prefix: string, id: string, secret: string } | null}
+ */
+export function parseApiKey(key: string): {
+    prefix: string;
+    id: string;
+    secret: string;
+} | null;
+/**
+ * Compute the storage hash for a candidate raw key's secret half,
+ * trying peppers newest-first. Returns the hash + which pepper matched
+ * (or null if no pepper array was supplied).
+ *
+ * Used by `verifyApiKey` — it hashes the incoming secret with each
+ * pepper in the rotation and lets the caller decide which one to
+ * compare against. The needsRehash signal (secret matched an older
+ * pepper) is exposed to consumers so they can silently upgrade
+ * storage on the next successful auth.
+ *
+ * @param {string} rawSecret     The base64url secret segment.
+ * @param {Buffer[] | null} peppers
+ * @returns {{ candidateHashes: string[] }}
+ */
+export function candidateHashesFor(rawSecret: string, peppers: Buffer[] | null): {
+    candidateHashes: string[];
+};
+/**
+ * Log-safe display for a key. Returns `<prefix>_<first-N-of-id>…<last-M-of-secret>`
+ * so the value is recognisable in an audit log without disclosing the
+ * secret. The default masks all but the first 6 chars of the id and
+ * the last 4 chars of the secret.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+export function mask(key: string): string;
+import { isBytes } from '@exortek/shared/predicates';
+export { nodeTimingSafeEqual as _nodeTimingSafeEqual, isBytes as _isBytes };

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@exortek/apikey",
+  "version": "1.0.0",
+  "description": "Stripe-style prefixed API keys for Node.js — 3-segment tokens (prefix_id_secret), HMAC-SHA256 storage hash with pepper rotation, scope allowlists with wildcard match, opt-in lastUsedAt tracking, memory + Redis stores, Express + Fastify middleware. Server-only. Zero non-@exortek runtime dependencies.",
+  "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"
+    },
+    "./middleware/express": {
+      "types": "./dist/middleware/express.d.ts",
+      "import": "./dist/middleware/express.mjs",
+      "require": "./dist/middleware/express.cjs"
+    },
+    "./middleware/fastify": {
+      "types": "./dist/middleware/fastify.d.ts",
+      "import": "./dist/middleware/fastify.mjs",
+      "require": "./dist/middleware/fastify.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",
+    "api-key",
+    "apikey",
+    "stripe",
+    "prefixed-token",
+    "hmac",
+    "scopes",
+    "server-only",
+    "node-crypto"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/ExorTek/auth/tree/master/packages/apikey#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExorTek/auth.git",
+    "directory": "packages/apikey"
+  },
+  "bugs": {
+    "url": "https://github.com/ExorTek/auth/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "express": ">=4",
+    "fastify": ">=4",
+    "fastify-plugin": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "fastify-plugin": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@exortek/shared": "0.0.0",
+    "express": "^5.2.1",
+    "fastify": "^5.10.0",
+    "fastify-plugin": "^6.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}