@donotlb/keypal 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,606 @@
+import { S as Storage, A as ActionContext, a as ApiKeyRecord, b as ApiKeyMetadata, c as AuditLogQuery, d as AuditLog, e as AuditLogStats } from './shared/keypal.kItV-5pB.js';
+export { f as AuditAction, C as CreateApiKeyInput, g as StorageOptions } from './shared/keypal.kItV-5pB.js';
+import Redis from 'ioredis';
+import { Static, Type } from 'typebox';
+
+declare function isExpired(expiresAt: string | null | undefined): boolean;
+declare function getExpirationTime(expiresAt: string | null | undefined): Date | null;
+
+type KeyExtractionOptions = {
+    headerNames?: string[];
+    extractBearer?: boolean;
+};
+declare function extractKeyFromHeaders(headers: Record<string, string | undefined> | Headers, options?: KeyExtractionOptions): string | null;
+declare function hasApiKey(headers: Record<string, string | undefined> | Headers, options?: KeyExtractionOptions): boolean;
+
+type PermissionScope = string;
+type Permission = {
+    scope: PermissionScope;
+    description?: string;
+};
+
+type ScopeCheckOptions = {
+    /** Resource identifier to check resource-specific scopes (e.g., "website:123", "project:456") */
+    resource?: string;
+};
+declare function hasScope(scopes: PermissionScope[] | undefined, requiredScope: PermissionScope, options?: ScopeCheckOptions): boolean;
+declare function hasAnyScope(scopes: PermissionScope[] | undefined, requiredScopes: PermissionScope[], options?: ScopeCheckOptions): boolean;
+declare function hasAllScopes(scopes: PermissionScope[] | undefined, requiredScopes: PermissionScope[], options?: ScopeCheckOptions): boolean;
+
+/**
+ * Fluent API for building resource-specific scopes
+ *
+ * @example
+ * ```ts
+ * const resources = new ResourceBuilder()
+ *   .add('website', 'site123', ['read', 'write'])
+ *   .add('project', 'proj456', ['deploy'])
+ *   .build()
+ * ```
+ */
+declare class ResourceBuilder {
+    private resources;
+    /**
+     * Add scopes for a specific resource
+     * @param resourceType - Type of resource (e.g., 'website', 'project', 'team')
+     * @param resourceId - ID of the resource
+     * @param scopes - Array of scopes to grant for this resource
+     */
+    add(resourceType: string, resourceId: string, scopes: PermissionScope[]): this;
+    /**
+     * Add a single scope to a resource
+     * @param resourceType - Type of resource
+     * @param resourceId - ID of the resource
+     * @param scope - Single scope to grant
+     */
+    addOne(resourceType: string, resourceId: string, scope: PermissionScope): this;
+    /**
+     * Add scopes to multiple resources of the same type
+     * @param resourceType - Type of resource
+     * @param resourceIds - Array of resource IDs
+     * @param scopes - Scopes to grant to all resources
+     */
+    addMany(resourceType: string, resourceIds: string[], scopes: PermissionScope[]): this;
+    /**
+     * Remove a resource entirely
+     */
+    remove(resourceType: string, resourceId: string): this;
+    /**
+     * Remove specific scopes from a resource
+     */
+    removeScopes(resourceType: string, resourceId: string, scopes: PermissionScope[]): this;
+    /**
+     * Check if a resource has been added
+     */
+    has(resourceType: string, resourceId: string): boolean;
+    /**
+     * Get scopes for a specific resource
+     */
+    get(resourceType: string, resourceId: string): PermissionScope[];
+    /**
+     * Clear all resources
+     */
+    clear(): this;
+    /**
+     * Build and return the resources object
+     */
+    build(): Record<string, PermissionScope[]>;
+    /**
+     * Create a new ResourceBuilder from an existing resources object
+     */
+    static from(resources: Record<string, PermissionScope[]>): ResourceBuilder;
+}
+/**
+ * Create a new ResourceBuilder instance
+ */
+declare function createResourceBuilder(): ResourceBuilder;
+
+type Cache = {
+    get(key: string): Promise<string | null> | string | null;
+    set(key: string, value: string, ttl?: number): Promise<void> | void;
+    del(key: string): Promise<void> | void;
+};
+
+declare const ConfigSchema: Type.TObject<{
+    prefix: Type.TOptional<Type.TString>;
+    length: Type.TOptional<Type.TNumber>;
+    algorithm: Type.TOptional<Type.TUnion<[Type.TLiteral<"sha256">, Type.TLiteral<"sha512">]>>;
+    alphabet: Type.TOptional<Type.TString>;
+    salt: Type.TOptional<Type.TString>;
+}>;
+type Config = Static<typeof ConfigSchema>;
+/**
+ * Configuration options for API key management
+ * @example
+ * ```typescript
+ * const keys = createKeys({
+ *   prefix: "sk_live_",
+ *   length: 40,
+ *   storage: "redis",
+ *   redis: redisClient,
+ *   cache: true,
+ *   cacheTtl: 300
+ * });
+ * ```
+ */
+type ConfigInput = {
+    /**
+     * Prefix for all generated API keys (e.g., "sk_live_", "sk_test_")
+     * @example "sk_live_"
+     */
+    prefix?: string;
+    /**
+     * Length of the generated key (excluding prefix)
+     * @default 32
+     * @example 40
+     */
+    length?: number;
+    /**
+     * Hashing algorithm for storing keys
+     * @default "sha256"
+     */
+    algorithm?: "sha256" | "sha512";
+    /**
+     * Custom alphabet for key generation (default: URL-safe base64)
+     * @example "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+     */
+    alphabet?: string;
+    /**
+     * Salt for hashing (increases security)
+     * @example "my-secret-salt"
+     */
+    salt?: string;
+    /**
+     * Storage backend for API keys
+     * - "memory": In-memory storage (default, not persistent)
+     * - "redis": Redis storage (requires redis client)
+     * - Custom Storage object: Use your own storage implementation
+     * @default "memory"
+     */
+    storage?: Storage | "memory" | "redis";
+    /**
+     * Caching strategy for verified keys
+     * - true: In-memory cache
+     * - "redis": Redis cache (requires redis client)
+     * - Custom Cache object: Use your own cache implementation
+     * - false: No caching
+     * @default false
+     */
+    cache?: Cache | boolean | "redis";
+    /**
+     * Cache TTL in seconds
+     * @default 60
+     */
+    cacheTtl?: number;
+    /**
+     * HTTP header names to look for API keys
+     * @default ["authorization", "x-api-key"]
+     */
+    headerNames?: string[];
+    /**
+     * Extract Bearer token from Authorization header
+     * @default true
+     */
+    extractBearer?: boolean;
+    /**
+     * Redis client instance (required when using "redis" storage or cache)
+     */
+    redis?: Redis;
+    /**
+     * TTL in seconds for revoked keys in Redis
+     * @default 604800 (7 days)
+     * @example 0 to keep forever
+     */
+    revokedKeyTtl?: number;
+    /**
+     * Automatically update lastUsedAt when verifying a key
+     * @default true
+     */
+    autoTrackUsage?: boolean;
+    /**
+     * Enable audit logging for key actions
+     * @default false
+     */
+    auditLogs?: boolean;
+    /**
+     * Default context for audit log entries (can be overridden per operation)
+     * @example { userId: 'system', metadata: { service: 'api' } }
+     */
+    auditContext?: ActionContext;
+};
+
+/**
+ * API Key verification error codes
+ */
+declare const ApiKeyErrorCode: {
+    /** No API key was provided */
+    readonly MISSING_KEY: "MISSING_KEY";
+    /** API key format is invalid (e.g., wrong prefix) */
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    /** API key does not exist in storage */
+    readonly INVALID_KEY: "INVALID_KEY";
+    /** API key has expired */
+    readonly EXPIRED: "EXPIRED";
+    /** API key has been revoked */
+    readonly REVOKED: "REVOKED";
+    /** API key is disabled */
+    readonly DISABLED: "DISABLED";
+    /** Storage error occurred */
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    /** Cache error occurred */
+    readonly CACHE_ERROR: "CACHE_ERROR";
+    /** API key is already revoked */
+    readonly ALREADY_REVOKED: "ALREADY_REVOKED";
+    /** API key is already enabled */
+    readonly ALREADY_ENABLED: "ALREADY_ENABLED";
+    /** API key is already disabled */
+    readonly ALREADY_DISABLED: "ALREADY_DISABLED";
+    /** Cannot perform operation on revoked key */
+    readonly CANNOT_MODIFY_REVOKED: "CANNOT_MODIFY_REVOKED";
+    /** API key not found */
+    readonly KEY_NOT_FOUND: "KEY_NOT_FOUND";
+    /** Audit logging is not enabled */
+    readonly AUDIT_LOGGING_DISABLED: "AUDIT_LOGGING_DISABLED";
+    /** Storage does not support this operation */
+    readonly STORAGE_NOT_SUPPORTED: "STORAGE_NOT_SUPPORTED";
+};
+type ApiKeyErrorCode = (typeof ApiKeyErrorCode)[keyof typeof ApiKeyErrorCode];
+/**
+ * API Key error details
+ */
+type ApiKeyError = {
+    /** Error code for programmatic handling */
+    code: ApiKeyErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Optional additional error details */
+    details?: unknown;
+};
+/**
+ * Helper function to create an API key error
+ */
+declare function createApiKeyError(code: ApiKeyErrorCode, details?: unknown): ApiKeyError;
+
+/**
+ * Result of verifying an API key
+ */
+type VerifyResult = {
+    /** Whether the key is valid */
+    valid: boolean;
+    /** The API key record if valid */
+    record?: ApiKeyRecord;
+    /** Error message if invalid */
+    error?: string;
+    /** Error code for programmatic handling */
+    errorCode?: ApiKeyErrorCode;
+};
+/**
+ * Options for verifying API keys
+ */
+type VerifyOptions = {
+    /** Skip cache lookup (always query storage) */
+    skipCache?: boolean;
+    /** Override header names to look for */
+    headerNames?: string[];
+    /** Override extractBearer behavior */
+    extractBearer?: boolean;
+    /** Skip updating lastUsedAt timestamp (useful when autoTrackUsage is enabled) */
+    skipTracking?: boolean;
+};
+/**
+ * API Key Manager for creating, verifying, and managing API keys
+ *
+ * @example
+ * ```typescript
+ * const keys = createKeys({
+ *   prefix: "sk_live_",
+ *   storage: "redis",
+ *   redis: redisClient
+ * });
+ *
+ * // Create a key
+ * const { key, record } = await keys.create({
+ *   ownerId: "user_123",
+ *   name: "Production Key",
+ *   scopes: ["read", "write"]
+ * });
+ *
+ * // Verify a key
+ * const result = await keys.verify(key);
+ * if (result.valid) {
+ *   console.log("Key belongs to:", result.record?.metadata.ownerId);
+ * }
+ * ```
+ */
+declare class ApiKeyManager {
+    private readonly config;
+    private readonly storage;
+    private readonly cache?;
+    private readonly cacheTtl;
+    private readonly extractionOptions;
+    private readonly revokedKeyTtl;
+    private readonly isRedisStorage;
+    private readonly autoTrackUsage;
+    private readonly auditLogsEnabled;
+    private readonly defaultContext?;
+    constructor(config?: ConfigInput);
+    generateKey(): string;
+    hashKey(key: string): string;
+    validateKey(key: string, storedHash: string): boolean;
+    /**
+     * Extract API key from HTTP headers
+     *
+     * @param headers - HTTP headers object or Headers instance
+     * @param options - Optional extraction options
+     * @returns The extracted API key or null if not found
+     *
+     * @example
+     * ```typescript
+     * const key = keys.extractKey(req.headers);
+     * if (key) {
+     *   console.log("Found key:", key);
+     * }
+     * ```
+     */
+    extractKey(headers: Record<string, string | undefined> | Headers, options?: KeyExtractionOptions): string | null;
+    /**
+     * Check if an API key is present in HTTP headers
+     *
+     * @param headers - HTTP headers object or Headers instance
+     * @param options - Optional extraction options
+     * @returns True if an API key is found in headers
+     *
+     * @example
+     * ```typescript
+     * if (keys.hasKey(req.headers)) {
+     *   // API key is present
+     * }
+     * ```
+     */
+    hasKey(headers: Record<string, string | undefined> | Headers, options?: KeyExtractionOptions): boolean;
+    /**
+     * Verify an API key from a string or HTTP headers
+     *
+     * @param keyOrHeader - The API key string or HTTP headers object
+     * @param options - Verification options
+     * @returns Verification result with validity status and record
+     *
+     * @example
+     * ```typescript
+     * // Verify from string
+     * const result = await keys.verify("sk_live_abc123...");
+     *
+     * // Verify from headers
+     * const result = await keys.verify(req.headers);
+     *
+     * if (result.valid) {
+     *   console.log("Owner:", result.record?.metadata.ownerId);
+     * } else {
+     *   console.log("Error:", result.error);
+     * }
+     * ```
+     */
+    verify(keyOrHeader: string | Record<string, string | undefined> | Headers, options?: VerifyOptions): Promise<VerifyResult>;
+    /**
+     * Create a new API key
+     *
+     * @param metadata - Metadata for the API key (ownerId is required)
+     * @returns The generated key string and the stored record
+     *
+     * @example
+     * ```typescript
+     * const { key, record } = await keys.create({
+     *   ownerId: "user_123",
+     *   name: "Production Key",
+     *   description: "API key for production access",
+     *   scopes: ["read", "write"],
+     *   expiresAt: "2025-12-31T00:00:00.000Z",
+     *   tags: ["production", "api"]
+     * });
+     *
+     * console.log("New key:", key);
+     * console.log("Key ID:", record.id);
+     * ```
+     */
+    create(metadata: Partial<ApiKeyMetadata>, context?: ActionContext): Promise<{
+        key: string;
+        record: ApiKeyRecord;
+    }>;
+    findByHash(keyHash: string): Promise<ApiKeyRecord | null>;
+    findById(id: string): Promise<ApiKeyRecord | null>;
+    findByTags(tags: string[], ownerId?: string): Promise<ApiKeyRecord[]>;
+    findByTag(tag: string, ownerId?: string): Promise<ApiKeyRecord[]>;
+    list(ownerId: string): Promise<ApiKeyRecord[]>;
+    revoke(id: string, context?: ActionContext): Promise<void>;
+    revokeAll(ownerId: string): Promise<void>;
+    enable(id: string, context?: ActionContext): Promise<void>;
+    disable(id: string, context?: ActionContext): Promise<void>;
+    rotate(id: string, metadata?: Partial<ApiKeyMetadata>, context?: ActionContext): Promise<{
+        key: string;
+        record: ApiKeyRecord;
+        oldRecord: ApiKeyRecord;
+    }>;
+    updateLastUsed(id: string): Promise<void>;
+    /**
+     * Create an audit log entry for a key action
+     * @private
+     */
+    private logAction;
+    /**
+     * Get audit logs with optional filters
+     *
+     * @param query - Query options for filtering audit logs
+     * @returns Array of audit log entries
+     *
+     * @example
+     * ```typescript
+     * const logs = await keys.getLogs({
+     *   keyId: 'key_123',
+     *   startDate: '2025-01-01',
+     *   endDate: '2025-12-31',
+     *   limit: 100
+     * });
+     * ```
+     */
+    getLogs(query?: AuditLogQuery): Promise<AuditLog[]>;
+    /**
+     * Count audit logs matching query
+     *
+     * @param query - Query options for filtering audit logs
+     * @returns Number of matching logs
+     *
+     * @example
+     * ```typescript
+     * const count = await keys.countLogs({ action: 'created' });
+     * ```
+     */
+    countLogs(query?: AuditLogQuery): Promise<number>;
+    /**
+     * Delete audit logs matching query
+     *
+     * @param query - Query options for filtering logs to delete
+     * @returns Number of logs deleted
+     *
+     * @example
+     * ```typescript
+     * // Delete old logs
+     * const deleted = await keys.deleteLogs({
+     *   endDate: '2024-01-01'
+     * });
+     * ```
+     */
+    deleteLogs(query: AuditLogQuery): Promise<number>;
+    /**
+     * Delete all audit logs for a specific key
+     *
+     * @param keyId - The key ID to delete logs for
+     * @returns Number of logs deleted
+     *
+     * @example
+     * ```typescript
+     * const deleted = await keys.clearLogs('key_123');
+     * ```
+     */
+    clearLogs(keyId: string): Promise<number>;
+    /**
+     * Get statistics about audit logs for an owner
+     *
+     * @param ownerId - Owner ID to get stats for
+     * @returns Statistics including total count, counts by action, and last activity
+     *
+     * @example
+     * ```typescript
+     * const stats = await keys.getLogStats('user_123');
+     * console.log(`Total logs: ${stats.total}`);
+     * console.log(`Created: ${stats.byAction.created}`);
+     * ```
+     */
+    getLogStats(ownerId: string): Promise<AuditLogStats>;
+    invalidateCache(keyHash: string): Promise<void>;
+    isExpired(record: ApiKeyRecord): boolean;
+    /**
+     * Check if an API key has a specific scope
+     *
+     * @param record - The API key record
+     * @param scope - Required scope to check
+     * @param options - Optional scope check options (e.g., resource filtering)
+     * @returns True if the key has the required scope
+     *
+     * @example
+     * ```typescript
+     * const record = await storage.findById("key_id");
+     * if (keys.hasScope(record, "read")) {
+     *   // Key has read permission
+     * }
+     *
+     * // Check for resource-specific scope
+     * if (keys.hasScope(record, "write", { resource: "project:123" })) {
+     *   // Key can write to project 123
+     * }
+     * ```
+     */
+    hasScope(record: ApiKeyRecord, scope: PermissionScope, options?: ScopeCheckOptions): boolean;
+    /**
+     * Check if an API key has any of the required scopes
+     *
+     * @param record - The API key record
+     * @param requiredScopes - Array of scopes to check
+     * @param options - Optional scope check options
+     * @returns True if the key has at least one of the required scopes
+     *
+     * @example
+     * ```typescript
+     * if (keys.hasAnyScope(record, ["read", "write"])) {
+     *   // Key has read OR write permission
+     * }
+     * ```
+     */
+    hasAnyScope(record: ApiKeyRecord, requiredScopes: PermissionScope[], options?: ScopeCheckOptions): boolean;
+    /**
+     * Check if an API key has all required scopes
+     *
+     * @param record - The API key record
+     * @param requiredScopes - Array of scopes to check
+     * @param options - Optional scope check options
+     * @returns True if the key has all required scopes
+     *
+     * @example
+     * ```typescript
+     * if (keys.hasAllScopes(record, ["read", "write"])) {
+     *   // Key has read AND write permissions
+     * }
+     * ```
+     */
+    hasAllScopes(record: ApiKeyRecord, requiredScopes: PermissionScope[], options?: ScopeCheckOptions): boolean;
+    /**
+     * Verify API key from headers and return the record or null
+     * This is a convenience method that combines verify() with automatic null handling
+     */
+    verifyFromHeaders(headers: Record<string, string | undefined> | Headers, options?: VerifyOptions): Promise<ApiKeyRecord | null>;
+    /**
+     * Check if an API key has a specific scope for a resource
+     * @param record - The API key record
+     * @param resourceType - Type of resource (e.g., 'website', 'project', 'team')
+     * @param resourceId - ID of the resource
+     * @param scope - Required scope to check
+     */
+    checkResourceScope(record: ApiKeyRecord | null, resourceType: string, resourceId: string, scope: PermissionScope): boolean;
+    /**
+     * Check if an API key has any of the required scopes for a resource
+     */
+    checkResourceAnyScope(record: ApiKeyRecord | null, resourceType: string, resourceId: string, scopes: PermissionScope[]): boolean;
+    /**
+     * Check if an API key has all required scopes for a resource
+     */
+    checkResourceAllScopes(record: ApiKeyRecord | null, resourceType: string, resourceId: string, scopes: PermissionScope[]): boolean;
+}
+/**
+ * Create an API key manager instance
+ *
+ * @param config - Configuration options for key generation and storage
+ * @returns An ApiKeyManager instance for creating and verifying keys
+ *
+ * @example
+ * ```typescript
+ * // Simple in-memory setup
+ * const keys = createKeys({ prefix: "sk_" });
+ *
+ * // Redis setup with caching
+ * const keys = createKeys({
+ *   prefix: "sk_live_",
+ *   storage: "redis",
+ *   redis: redisClient,
+ *   cache: true,
+ *   cacheTtl: 300
+ * });
+ *
+ * // Custom storage adapter
+ * const keys = createKeys({
+ *   storage: myCustomStorage
+ * });
+ * ```
+ */
+declare function createKeys(config?: ConfigInput): ApiKeyManager;
+
+export { ActionContext, ApiKeyErrorCode, ApiKeyManager, ApiKeyMetadata, ApiKeyRecord, AuditLog, AuditLogQuery, AuditLogStats, ResourceBuilder, Storage, createApiKeyError, createKeys, createResourceBuilder, extractKeyFromHeaders, getExpirationTime, hasAllScopes, hasAnyScope, hasApiKey, hasScope, isExpired };
+export type { ApiKeyError, Config, ConfigInput, Permission, PermissionScope, VerifyOptions, VerifyResult };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+/*!
+ * @donotlb/keypal v0.1.0
+ * A TypeScript library for secure API key management with cryptographic hashing, expiration, scopes, and pluggable storage
+ * © 2026 "donotlb" <donotlb@gmail.com>
+ * Released under the MIT License
+ * https://github.com/donotlb/keypal#readme
+ */import{nanoid as I}from"nanoid";import{l as d,g as D}from"./shared/keypal.lTVSZWgp.mjs";import{createHash as R,timingSafeEqual as O}from"node:crypto";import{MemoryStore as T}from"./storage/memory.mjs";import{RedisStore as y}from"./storage/redis.mjs";import"./shared/keypal.C-UeOmUF.mjs";function g(s){return s?new Date(s)<=new Date:!1}function L(s){return s?new Date(s):null}const k=["authorization","x-api-key"],S="bearer ";function _(s,e){if(s instanceof Headers)return s.get(e);const t=e.toLowerCase();for(const a in s)if(a.toLowerCase()===t)return s[a]??null;return null}function N(s,e){const t=s.trim();if(!t)return null;const a=t.toLowerCase();return a==="bearer"?null:a.startsWith(S)&&e?t.slice(7).trim()||null:t}function E(s,e={}){const{headerNames:t=k,extractBearer:a=!0}=e;for(const r of t){const o=_(s,r);if(!o)continue;const n=N(o,a);if(n)return n}return null}function m(s,e={}){return E(s,e)!==null}function v(s,e,t){return s?.includes(e)?!0:(t?.resource,!1)}function x(s,e,t){return!s||s.length===0?!1:e.some(a=>s.includes(a))?!0:(t?.resource,!1)}function K(s,e,t){return!s||s.length===0?!1:e.every(a=>s.includes(a))?!0:(t?.resource,!1)}function C(s,e,t,a){return!!(s?.includes(t)||a?.resource&&e&&e[a.resource]?.includes(t))}function B(s,e,t,a){if(s&&t.some(r=>s.includes(r)))return!0;if(a?.resource&&e){const r=e[a.resource];if(r&&t.some(o=>r.includes(o)))return!0}return!1}function b(s,e,t,a){if(s&&t.every(r=>s.includes(r)))return!0;if(a?.resource&&e){const r=e[a.resource];if(!r)return!1;if(t.every(n=>r.includes(n)))return!0;const o=[...s||[],...r];return t.every(n=>o.includes(n))}return!1}class A{resources={};add(e,t,a){const r=`${e}:${t}`;if(this.resources[r]){const o=new Set(this.resources[r]);for(const n of a)o.add(n);this.resources[r]=Array.from(o)}else this.resources[r]=a;return this}addOne(e,t,a){return this.add(e,t,[a])}addMany(e,t,a){for(const r of t)this.add(e,r,a);return this}remove(e,t){const a=`${e}:${t}`;return delete this.resources[a],this}removeScopes(e,t,a){const r=`${e}:${t}`;if(this.resources[r]){const o=new Set(a);this.resources[r]=this.resources[r]?.filter(n=>!o.has(n))??[],this.resources[r]?.length===0&&delete this.resources[r]}return this}has(e,t){return`${e}:${t}`in this.resources}get(e,t){const a=`${e}:${t}`;return this.resources[a]||[]}clear(){return this.resources={},this}build(){return{...this.resources}}static from(e){const t=new A;return t.resources={...e},t}}function G(){return new A}class Y{cache=new Map;maxSize;cleanupTimer=null;constructor(e={}){this.maxSize=e.maxSize??1e4;const t=e.cleanupInterval??6e4;this.cleanupTimer=setInterval(()=>this.cleanup(),t),this.cleanupTimer.unref?.()}get(e){const t=this.cache.get(e);return t?t.expires<Date.now()?(this.cache.delete(e),null):t.value:null}set(e,t,a=60){if(this.cache.size>=this.maxSize&&!this.cache.has(e)&&(this.cleanup(),this.cache.size>=this.maxSize)){const r=this.cache.keys().next().value;r!==void 0&&this.cache.delete(r)}this.cache.set(e,{value:t,expires:Date.now()+a*1e3})}del(e){this.cache.delete(e)}clear(){this.cache.clear()}cleanup(){const e=Date.now();for(const[t,a]of this.cache)a.expires<e&&this.cache.delete(t)}dispose(){this.cleanupTimer&&(clearInterval(this.cleanupTimer),this.cleanupTimer=null)}get size(){return this.cache.size}}class ${client;constructor(e){this.client=e}async get(e){return this.client.get(e)}async set(e,t,a=60){await this.client.setex(e,a,t)}async del(e){await this.client.del(e)}}function p(s,e={}){const{algorithm:t="sha256",salt:a=""}=e,r=a?`${s}${a}`:s;return R(t).update(r).digest("hex")}function F(s,e,t={}){const a=p(s,t);return a.length!==e.length?!1:O(Buffer.from(a),Buffer.from(e))}const i={MISSING_KEY:"MISSING_KEY",INVALID_FORMAT:"INVALID_FORMAT",INVALID_KEY:"INVALID_KEY",EXPIRED:"EXPIRED",REVOKED:"REVOKED",DISABLED:"DISABLED",STORAGE_ERROR:"STORAGE_ERROR",CACHE_ERROR:"CACHE_ERROR",ALREADY_REVOKED:"ALREADY_REVOKED",ALREADY_ENABLED:"ALREADY_ENABLED",ALREADY_DISABLED:"ALREADY_DISABLED",CANNOT_MODIFY_REVOKED:"CANNOT_MODIFY_REVOKED",KEY_NOT_FOUND:"KEY_NOT_FOUND",AUDIT_LOGGING_DISABLED:"AUDIT_LOGGING_DISABLED",STORAGE_NOT_SUPPORTED:"STORAGE_NOT_SUPPORTED"},P={[i.MISSING_KEY]:"Missing API key",[i.INVALID_FORMAT]:"Invalid API key format",[i.INVALID_KEY]:"Invalid API key",[i.EXPIRED]:"API key has expired",[i.REVOKED]:"API key has been revoked",[i.DISABLED]:"API key is disabled",[i.STORAGE_ERROR]:"Storage error occurred",[i.CACHE_ERROR]:"Cache error occurred",[i.ALREADY_REVOKED]:"API key is already revoked",[i.ALREADY_ENABLED]:"API key is already enabled",[i.ALREADY_DISABLED]:"API key is already disabled",[i.CANNOT_MODIFY_REVOKED]:"Cannot modify a revoked key",[i.KEY_NOT_FOUND]:"API key not found",[i.AUDIT_LOGGING_DISABLED]:"Audit logging is not enabled",[i.STORAGE_NOT_SUPPORTED]:"Storage does not support this operation"};function c(s,e){return{code:s,message:P[s],details:e}}function l(s,e){const t=c(s,e);return{valid:!1,error:t.message,errorCode:t.code}}function U(s){if(typeof s!="object"||s===null)return!1;const e=s;return typeof e.id=="string"&&(e.expiresAt===null||typeof e.expiresAt=="string")&&(e.revokedAt===null||typeof e.revokedAt=="string")&&typeof e.enabled=="boolean"}class M{config;storage;cache;cacheTtl;extractionOptions;revokedKeyTtl;isRedisStorage;autoTrackUsage;auditLogsEnabled;defaultContext;constructor(e={}){const t=e.salt?p(e.salt,{algorithm:"sha256"}):"";if(this.config={prefix:e.prefix,length:e.length??32,algorithm:e.algorithm??"sha256",alphabet:e.alphabet,salt:t},this.revokedKeyTtl=e.revokedKeyTtl??604800,this.isRedisStorage=e.storage==="redis",this.autoTrackUsage=e.autoTrackUsage??!0,this.auditLogsEnabled=e.auditLogs??!1,this.defaultContext=e.auditContext,e.storage==="redis"){if(!e.redis)throw new Error('Redis client required when storage is "redis"');try{this.storage=new y({client:e.redis})}catch(a){throw d.error("CRITICAL: Failed to initialize Redis storage:",a),a}}else e.storage&&typeof e.storage=="object"?this.storage=e.storage:this.storage=new T;if(this.cacheTtl=e.cacheTtl??60,this.extractionOptions={headerNames:e.headerNames??["authorization","x-api-key"],extractBearer:e.extractBearer??!0},e.cache==="redis"){if(!e.redis)throw new Error("[keypal] Redis client required when cache is 'redis'");try{this.cache=new $(e.redis)}catch(a){throw d.error("CRITICAL: Failed to initialize Redis cache:",a),a}}else e.cache===!0?this.cache=new Y:e.cache&&typeof e.cache=="object"&&(this.cache=e.cache)}generateKey(){return D({prefix:this.config.prefix,length:this.config.length,alphabet:this.config.alphabet})}hashKey(e){return p(e,{algorithm:this.config.algorithm,salt:this.config.salt})}validateKey(e,t){return F(e,t,{algorithm:this.config.algorithm,salt:this.config.salt})}extractKey(e,t){const a={headerNames:t?.headerNames??this.extractionOptions.headerNames,extractBearer:t?.extractBearer??this.extractionOptions.extractBearer};return E(e,a)}hasKey(e,t){const a={headerNames:t?.headerNames??this.extractionOptions.headerNames,extractBearer:t?.extractBearer??this.extractionOptions.extractBearer};return m(e,a)}async verify(e,t={}){let a;if(typeof e=="string")a=e,e.startsWith("Bearer ")&&(a=e.slice(7).trim());else{const n={headerNames:t.headerNames??this.extractionOptions.headerNames,extractBearer:t.extractBearer??this.extractionOptions.extractBearer};a=this.extractKey(e,n)}if(!a)return l(i.MISSING_KEY);if(this.config.prefix&&!a.startsWith(this.config.prefix))return l(i.INVALID_FORMAT);const r=this.hashKey(a);if(this.cache&&!t.skipCache){const n=await this.cache.get(`apikey:${r}`);if(n)try{const h=JSON.parse(n);if(!U(h))d.error("CRITICAL: Invalid cache record shape, invalidating entry"),await this.cache.del(`apikey:${r}`);else{const u=h;if(u.expiresAt&&g(u.expiresAt))return await this.cache.del(`apikey:${r}`),l(i.EXPIRED);if(u.revokedAt)return await this.cache.del(`apikey:${r}`),l(i.REVOKED);if(u.enabled===!1)return l(i.DISABLED);const f=await this.storage.findById(u.id);return f?g(f.metadata.expiresAt)?(await this.cache.del(`apikey:${r}`),l(i.EXPIRED)):f.metadata.revokedAt?(await this.cache.del(`apikey:${r}`),l(i.REVOKED)):(this.autoTrackUsage&&!t.skipTracking&&this.updateLastUsed(f.id).catch(w=>{d.error("Failed to track usage:",w)}),{valid:!0,record:f}):(await this.cache.del(`apikey:${r}`),l(i.INVALID_KEY))}}catch(h){d.error("CRITICAL: Cache corruption detected, invalidating entry:",h),await this.cache.del(`apikey:${r}`)}}const o=await this.storage.findByHash(r);if(!o)return l(i.INVALID_KEY);if(g(o.metadata.expiresAt))return this.cache&&await this.cache.del(`apikey:${r}`),l(i.EXPIRED);if(o.metadata.revokedAt)return this.cache&&await this.cache.del(`apikey:${r}`),l(i.REVOKED);if(o.metadata.enabled===!1)return l(i.DISABLED);if(this.cache&&!t.skipCache)try{const n={id:o.id,expiresAt:o.metadata.expiresAt??null,revokedAt:o.metadata.revokedAt??null,enabled:o.metadata.enabled??!0};await this.cache.set(`apikey:${r}`,JSON.stringify(n),this.cacheTtl)}catch(n){d.error("CRITICAL: Failed to write to cache:",n)}return this.autoTrackUsage&&!t.skipTracking&&this.updateLastUsed(o.id).catch(n=>{d.error("Failed to track usage:",n)}),{valid:!0,record:o}}async create(e,t){const a=this.generateKey(),r=this.hashKey(a),o=new Date().toISOString(),n=e.tags?.map(u=>u.toLowerCase()),h={id:I(),keyHash:r,metadata:{ownerId:e.ownerId??"",name:e.name,description:e.description,scopes:e.scopes,resources:e.resources,expiresAt:e.expiresAt??null,createdAt:o,lastUsedAt:void 0,enabled:e.enabled??!0,revokedAt:null,rotatedTo:null,tags:n}};return await this.storage.save(h),await this.logAction("created",h.id,h.metadata.ownerId,{...t,metadata:{name:h.metadata.name,scopes:h.metadata.scopes,...t?.metadata}}),{key:a,record:h}}async findByHash(e){return await this.storage.findByHash(e)}async findById(e){return await this.storage.findById(e)}async findByTags(e,t){return await this.storage.findByTags(e,t)}async findByTag(e,t){return await this.storage.findByTag(e,t)}async list(e){return await this.storage.findByOwner(e)}async revoke(e,t){const a=await this.findById(e);if(!a)throw c(i.KEY_NOT_FOUND);if(a.metadata.revokedAt)throw c(i.ALREADY_REVOKED);if(await this.storage.updateMetadata(e,{revokedAt:new Date().toISOString()}),await this.logAction("revoked",e,a.metadata.ownerId,t),this.cache)try{await this.cache.del(`apikey:${a.keyHash}`)}catch(r){d.error("CRITICAL: Failed to invalidate cache on revoke:",r)}if(this.isRedisStorage&&this.revokedKeyTtl>0)try{this.storage instanceof y&&await this.storage.setTtl(e,this.revokedKeyTtl)}catch(r){d.error("Failed to set TTL on revoked key:",r)}}async revokeAll(e){const t=await this.list(e);await Promise.all(t.map(a=>this.revoke(a.id)))}async enable(e,t){const a=await this.findById(e);if(!a)throw c(i.KEY_NOT_FOUND);if(a.metadata.revokedAt)throw c(i.CANNOT_MODIFY_REVOKED);if(a.metadata.enabled)throw c(i.ALREADY_ENABLED);if(await this.storage.updateMetadata(e,{enabled:!0}),await this.logAction("enabled",e,a.metadata.ownerId,t),this.cache)try{await this.cache.del(`apikey:${a.keyHash}`)}catch(r){d.error("CRITICAL: Failed to invalidate cache on enable:",r)}}async disable(e,t){const a=await this.findById(e);if(!a)throw c(i.KEY_NOT_FOUND);if(a.metadata.revokedAt)throw c(i.CANNOT_MODIFY_REVOKED);if(!a.metadata.enabled)throw c(i.ALREADY_DISABLED);if(await this.storage.updateMetadata(e,{enabled:!1}),await this.logAction("disabled",e,a.metadata.ownerId,t),this.cache)try{await this.cache.del(`apikey:${a.keyHash}`)}catch(r){d.error("CRITICAL: Failed to invalidate cache on disable:",r)}}async rotate(e,t,a){const r=await this.findById(e);if(!r)throw c(i.KEY_NOT_FOUND);if(r.metadata.revokedAt)throw c(i.CANNOT_MODIFY_REVOKED);const{key:o,record:n}=await this.create({ownerId:r.metadata.ownerId,name:t?.name??r.metadata.name,description:t?.description??r.metadata.description,scopes:t?.scopes??r.metadata.scopes,resources:t?.resources??r.metadata.resources,expiresAt:t?.expiresAt??r.metadata.expiresAt,tags:t?.tags?t.tags.map(h=>h.toLowerCase()):r.metadata.tags});if(await this.storage.updateMetadata(e,{rotatedTo:n.id,revokedAt:new Date().toISOString()}),await this.logAction("rotated",e,r.metadata.ownerId,{...a,metadata:{rotatedTo:n.id,...a?.metadata}}),this.cache)try{await this.cache.del(`apikey:${r.keyHash}`)}catch(h){d.error("CRITICAL: Failed to invalidate cache on rotate:",h)}if(this.isRedisStorage&&this.revokedKeyTtl>0)try{this.storage instanceof y&&await this.storage.setTtl(e,this.revokedKeyTtl)}catch(h){d.error("Failed to set TTL on rotated key:",h)}return{key:o,record:n,oldRecord:r}}async updateLastUsed(e){await this.storage.updateMetadata(e,{lastUsedAt:new Date().toISOString()})}async logAction(e,t,a,r){if(!(this.auditLogsEnabled&&this.storage.saveLog))return;const o={...this.defaultContext,...r,...this.defaultContext?.metadata||r?.metadata?{metadata:{...this.defaultContext?.metadata,...r?.metadata}}:{}},n={id:I(),action:e,keyId:t,ownerId:a,timestamp:new Date().toISOString(),data:Object.keys(o).length>0?o:void 0};try{await this.storage.saveLog(n)}catch(h){d.error("Failed to save audit log:",h)}}async getLogs(e={}){if(!this.auditLogsEnabled)throw c(i.AUDIT_LOGGING_DISABLED);if(!this.storage.findLogs)throw c(i.STORAGE_NOT_SUPPORTED);return await this.storage.findLogs(e)}async countLogs(e={}){if(!this.auditLogsEnabled)throw c(i.AUDIT_LOGGING_DISABLED);if(!this.storage.countLogs)throw c(i.STORAGE_NOT_SUPPORTED);return await this.storage.countLogs(e)}async deleteLogs(e){if(!this.auditLogsEnabled)throw c(i.AUDIT_LOGGING_DISABLED);if(!this.storage.deleteLogs)throw c(i.STORAGE_NOT_SUPPORTED);return await this.storage.deleteLogs(e)}async clearLogs(e){return await this.deleteLogs({keyId:e})}async getLogStats(e){if(!this.auditLogsEnabled)throw c(i.AUDIT_LOGGING_DISABLED);if(!this.storage.getLogStats)throw c(i.STORAGE_NOT_SUPPORTED);return await this.storage.getLogStats(e)}async invalidateCache(e){if(this.cache)try{await this.cache.del(`apikey:${e}`)}catch(t){throw d.error("CRITICAL: Failed to invalidate cache:",t),t}}isExpired(e){return g(e.metadata.expiresAt)}hasScope(e,t,a){return C(e.metadata.scopes,e.metadata.resources,t,a)}hasAnyScope(e,t,a){return B(e.metadata.scopes,e.metadata.resources,t,a)}hasAllScopes(e,t,a){return b(e.metadata.scopes,e.metadata.resources,t,a)}async verifyFromHeaders(e,t){const a=await this.verify(e,t);return a.valid?a.record??null:null}checkResourceScope(e,t,a,r){return e?this.hasScope(e,r,{resource:`${t}:${a}`}):!1}checkResourceAnyScope(e,t,a,r){return e?this.hasAnyScope(e,r,{resource:`${t}:${a}`}):!1}checkResourceAllScopes(e,t,a,r){return e?this.hasAllScopes(e,r,{resource:`${t}:${a}`}):!1}}function V(s={}){return new M(s)}export{i as ApiKeyErrorCode,A as ResourceBuilder,c as createApiKeyError,V as createKeys,G as createResourceBuilder,E as extractKeyFromHeaders,L as getExpirationTime,K as hasAllScopes,x as hasAnyScope,m as hasApiKey,v as hasScope,g as isExpired};

package/dist/shared/keypal.C-UeOmUF.mjs

@@ -0,0 +1,7 @@
+/*!
+ * @donotlb/keypal v0.1.0
+ * A TypeScript library for secure API key management with cryptographic hashing, expiration, scopes, and pluggable storage
+ * © 2026 "donotlb" <donotlb@gmail.com>
+ * Released under the MIT License
+ * https://github.com/donotlb/keypal#readme
+ */const n=100;function i(c){const a={};let t=null;for(const o of c)a[o.action]=(a[o.action]||0)+1,(!t||o.timestamp>t)&&(t=o.timestamp);return{total:c.length,byAction:a,lastActivity:t}}export{n as D,i as c};