@exortek/apikey 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+/**
+ * @typedef {object} ApiKeyRecord
+ * @property {string} id                      Plaintext lookup key (128-bit b64u).
+ * @property {string} hash                    Storage hash of the secret (43-char b64u).
+ * @property {string} prefix                  The prefix the key was minted with.
+ * @property {string} userId
+ * @property {string[]} scopes
+ * @property {string} [name]                  Human label ("Production Backend").
+ * @property {string} [environment]           `'live'` / `'test'` / caller-defined.
+ * @property {Record<string, unknown>} [metadata]
+ * @property {number} createdAt               ms epoch.
+ * @property {number} [expiresAt]             ms epoch; absent = no expiry.
+ * @property {number} [revokedAt]             ms epoch when the record was revoked.
+ * @property {string} [revokedReason]
+ * @property {number} [lastUsedAt]            ms epoch of the last successful verify.
+ * @property {number} [pepperVersion]         Index into the peppers array that was used at mint. 0 = newest.
+ */
+/**
+ * @typedef {object} ApiKeyStore
+ * @property {(record: ApiKeyRecord) => Promise<void>} put
+ * @property {(id: string) => Promise<ApiKeyRecord | null>} getById
+ * @property {(id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>} update
+ * @property {(id: string, reason?: string) => Promise<boolean>} revoke
+ * @property {(userId: string, reason?: string) => Promise<number>} revokeAllForUser
+ * @property {(userId: string) => Promise<ApiKeyRecord[]>} listByUser
+ */
+/**
+ * @typedef {object} CreateApiKeyOptions
+ * @property {string} prefix                       Stripe-style; `sk_live`, `pk_test`, `svc_prod_v2`.
+ * @property {string} userId
+ * @property {string[]} scopes
+ * @property {string} [name]
+ * @property {string} [environment]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {string | number} [expiresIn]         `'1y'` / `'30d'` / ms integer. Omit for no expiry.
+ * @property {ApiKeyStore} store
+ * @property {(Buffer | Uint8Array | string)[]} [peppers]
+ *   Newest first. Each ≥16 bytes. Omit for plain SHA-256 storage.
+ * @property {number} [now]                        Override `Date.now()` for testing.
+ */
+/**
+ * @typedef {object} CreateApiKeyResult
+ * @property {string} key       Wire token — show ONCE to the caller and never again.
+ * @property {string} id        Plaintext lookup key; safe to store / log / display.
+ * @property {ApiKeyRecord} record  What was persisted to the store.
+ */
+/**
+ * @typedef {object} VerifyApiKeyOptions
+ * @property {ApiKeyStore} store
+ * @property {(Buffer | Uint8Array | string)[]} [peppers]
+ * @property {string[]} [requiredScopes]
+ * @property {string} [expectedPrefix]             Reject a valid key whose prefix differs.
+ * @property {boolean} [updateLastUsed=false]      Bump `lastUsedAt` on success (one extra store write).
+ * @property {number} [now]
+ */
+/**
+ * @typedef {'malformed' | 'not_found' | 'expired' | 'revoked'
+ *   | 'bad_secret' | 'prefix_mismatch' | 'missing_scope'
+ *   | 'store_unavailable'} VerifyApiKeyFailureReason
+ */
+/**
+ * @typedef {{
+ *   valid: true,
+ *   id: string,
+ *   userId: string,
+ *   scopes: string[],
+ *   prefix: string,
+ *   name?: string,
+ *   environment?: string,
+ *   metadata?: Record<string, unknown>,
+ *   needsRehash?: boolean,
+ * } | { valid: false, reason: VerifyApiKeyFailureReason }} VerifyApiKeyResult
+ */
+/**
+ * Mint a new API key. The wire `key` is returned once — the caller
+ * MUST show it to the end user immediately and never persist it in
+ * the clear (only the storage `hash` inside the returned `record` is
+ * safe to keep).
+ *
+ * @param {CreateApiKeyOptions} options
+ * @returns {Promise<CreateApiKeyResult>}
+ */
+export function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKeyResult>;
+/**
+ * Verify a raw API key. Returns `{ valid: true, ... }` on success, or
+ * `{ valid: false, reason }` on any expected failure. Never throws on
+ * a bad key — a wrong or stale key is a normal auth outcome.
+ *
+ * On success, callers get the stored `userId` / `scopes` / `metadata`
+ * and can pass them straight to their app's auth context.
+ * `needsRehash: true` in the success result signals the secret matched
+ * an older pepper — call `rehashApiKey(id, options)` to silently
+ * migrate storage to the newest pepper on the next natural chance.
+ *
+ * @param {string} rawKey
+ * @param {VerifyApiKeyOptions} options
+ * @returns {Promise<VerifyApiKeyResult>}
+ */
+export function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Promise<VerifyApiKeyResult>;
+/**
+ * Revoke an API key by id or by the raw wire key. Returns `true` if
+ * a record was actually revoked, `false` if the id was unknown or
+ * the record was already revoked.
+ *
+ * @param {string} keyOrId    Either the raw wire key or its id half.
+ * @param {{ store: ApiKeyStore, reason?: string }} options
+ * @returns {Promise<boolean>}
+ */
+export function revokeApiKey(keyOrId: string, options: {
+    store: ApiKeyStore;
+    reason?: string;
+}): Promise<boolean>;
+/**
+ * Revoke every non-revoked key belonging to `userId`. Useful on
+ * password reset, account termination, etc. Returns the number of
+ * records actually revoked.
+ *
+ * @param {string} userId
+ * @param {{ store: ApiKeyStore, reason?: string }} options
+ * @returns {Promise<number>}
+ */
+export function revokeAllForUser(userId: string, options: {
+    store: ApiKeyStore;
+    reason?: string;
+}): Promise<number>;
+/**
+ * List every key belonging to `userId` — for a "manage API keys" UI.
+ * Callers should hide the storage `hash` before rendering; only the
+ * plaintext `id` is safe to display. Returns most-recently-used first
+ * (falling back to createdAt) so active keys float to the top.
+ *
+ * @param {string} userId
+ * @param {{ store: ApiKeyStore }} options
+ * @returns {Promise<ApiKeyRecord[]>}
+ */
+export function listApiKeys(userId: string, options: {
+    store: ApiKeyStore;
+}): Promise<ApiKeyRecord[]>;
+/**
+ * Migrate the storage hash of an existing key to the newest pepper.
+ * Requires the raw wire key (the plaintext secret is the input to the
+ * new HMAC). Called opportunistically when `verifyApiKey` reports
+ * `needsRehash: true`.
+ *
+ * @param {string} rawKey
+ * @param {{ store: ApiKeyStore, peppers: (Buffer | Uint8Array | string)[] }} options
+ * @returns {Promise<boolean>}
+ */
+export function rehashApiKey(rawKey: string, options: {
+    store: ApiKeyStore;
+    peppers: (Buffer | Uint8Array | string)[];
+}): Promise<boolean>;
+export { maskKey as maskApiKey };
+export type ApiKeyRecord = {
+    /**
+     * Plaintext lookup key (128-bit b64u).
+     */
+    id: string;
+    /**
+     * Storage hash of the secret (43-char b64u).
+     */
+    hash: string;
+    /**
+     * The prefix the key was minted with.
+     */
+    prefix: string;
+    userId: string;
+    scopes: string[];
+    /**
+     * Human label ("Production Backend").
+     */
+    name?: string | undefined;
+    /**
+     * `'live'` / `'test'` / caller-defined.
+     */
+    environment?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    /**
+     * ms epoch.
+     */
+    createdAt: number;
+    /**
+     * ms epoch; absent = no expiry.
+     */
+    expiresAt?: number | undefined;
+    /**
+     * ms epoch when the record was revoked.
+     */
+    revokedAt?: number | undefined;
+    revokedReason?: string | undefined;
+    /**
+     * ms epoch of the last successful verify.
+     */
+    lastUsedAt?: number | undefined;
+    /**
+     * Index into the peppers array that was used at mint. 0 = newest.
+     */
+    pepperVersion?: number | undefined;
+};
+export type ApiKeyStore = {
+    put: (record: ApiKeyRecord) => Promise<void>;
+    getById: (id: string) => Promise<ApiKeyRecord | null>;
+    update: (id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>;
+    revoke: (id: string, reason?: string) => Promise<boolean>;
+    revokeAllForUser: (userId: string, reason?: string) => Promise<number>;
+    listByUser: (userId: string) => Promise<ApiKeyRecord[]>;
+};
+export type CreateApiKeyOptions = {
+    /**
+     * Stripe-style; `sk_live`, `pk_test`, `svc_prod_v2`.
+     */
+    prefix: string;
+    userId: string;
+    scopes: string[];
+    name?: string | undefined;
+    environment?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    /**
+     * `'1y'` / `'30d'` / ms integer. Omit for no expiry.
+     */
+    expiresIn?: string | number | undefined;
+    store: ApiKeyStore;
+    /**
+     * Newest first. Each ≥16 bytes. Omit for plain SHA-256 storage.
+     */
+    peppers?: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    /**
+     * Override `Date.now()` for testing.
+     */
+    now?: number | undefined;
+};
+export type CreateApiKeyResult = {
+    /**
+     * Wire token — show ONCE to the caller and never again.
+     */
+    key: string;
+    /**
+     * Plaintext lookup key; safe to store / log / display.
+     */
+    id: string;
+    /**
+     * What was persisted to the store.
+     */
+    record: ApiKeyRecord;
+};
+export type VerifyApiKeyOptions = {
+    store: ApiKeyStore;
+    peppers?: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    requiredScopes?: string[] | undefined;
+    /**
+     * Reject a valid key whose prefix differs.
+     */
+    expectedPrefix?: string | undefined;
+    /**
+     * Bump `lastUsedAt` on success (one extra store write).
+     */
+    updateLastUsed?: boolean | undefined;
+    now?: number | undefined;
+};
+export type VerifyApiKeyFailureReason = "malformed" | "not_found" | "expired" | "revoked" | "bad_secret" | "prefix_mismatch" | "missing_scope" | "store_unavailable";
+export type VerifyApiKeyResult = {
+    valid: true;
+    id: string;
+    userId: string;
+    scopes: string[];
+    prefix: string;
+    name?: string;
+    environment?: string;
+    metadata?: Record<string, unknown>;
+    needsRehash?: boolean;
+} | {
+    valid: false;
+    reason: VerifyApiKeyFailureReason;
+};
+import { mask as maskKey } from './token.js';
+export { ApiKeyError, ErrorCode } from "./errors.js";
+export { covers, hasAll, hasAny } from "./scopes.js";
+export { parseApiKey, mask } from "./token.js";