@donotlb/keypal 0.1.0

package/dist/shared/keypal.kItV-5pB.d.mts

@@ -0,0 +1,194 @@
+import { Static, Type } from 'typebox';
+
+/**
+ * Metadata associated with an API key
+ */
+declare const ApiKeyMetadataSchema: Type.TObject<{
+    /** Unique identifier for the key owner */
+    ownerId: Type.TString;
+    /** Optional human-readable name for the key */
+    name: Type.TOptional<Type.TString>;
+    /** Optional description of what this key is used for */
+    description: Type.TOptional<Type.TString>;
+    /** Scopes/permissions associated with this key */
+    scopes: Type.TOptional<Type.TArray<Type.TString>>;
+    /** Resource-specific scopes (e.g., { "website:123": ["read"], "project:456": ["write"] }) */
+    resources: Type.TOptional<Type.TRecord<"^.*$", Type.TArray<Type.TString>>>;
+    /** ISO timestamp when the key expires (null if never expires) */
+    expiresAt: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    /** ISO timestamp when the key was created */
+    createdAt: Type.TOptional<Type.TString>;
+    /** ISO timestamp when the key was last used */
+    lastUsedAt: Type.TOptional<Type.TString>;
+    /** Whether the key is enabled (default: true) */
+    enabled: Type.TOptional<Type.TBoolean>;
+    /** ISO timestamp when the key was revoked (null if not revoked) */
+    revokedAt: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    /** ID of the key this was rotated to (for key rotation) */
+    rotatedTo: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    tags: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+type ApiKeyMetadata = Static<typeof ApiKeyMetadataSchema>;
+/**
+ * Complete API key record stored in the database
+ */
+type ApiKeyRecord = {
+    /** Hashed version of the API key */
+    keyHash: string;
+    /** Unique identifier for this key record */
+    id: string;
+    /** Metadata associated with the key */
+    metadata: ApiKeyMetadata;
+};
+/**
+ * Input for creating an API key
+ */
+type CreateApiKeyInput = {
+    /** Optional custom prefix */
+    prefix?: string;
+    /** Optional custom length */
+    length?: number;
+    /** Metadata to associate with the key */
+    metadata: Partial<ApiKeyMetadata>;
+};
+
+/**
+ * Audit log action types
+ */
+type AuditAction = "created" | "revoked" | "rotated" | "enabled" | "disabled";
+/**
+ * Context for who performed an action
+ */
+type ActionContext = {
+    /** User ID who performed the action */
+    userId?: string;
+    /** IP address of the requester */
+    ip?: string;
+    /** User agent of the requester */
+    userAgent?: string;
+    /** Custom metadata about the action */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Audit log entry
+ */
+type AuditLog = {
+    /** Unique identifier for this log entry */
+    id: string;
+    /** The action that was performed */
+    action: AuditAction;
+    /** ID of the API key */
+    keyId: string;
+    /** ID of the key owner */
+    ownerId: string;
+    /** ISO timestamp when the action occurred */
+    timestamp: string;
+    /** Optional additional data about the action */
+    data?: Record<string, unknown>;
+};
+/**
+ * Options for querying audit logs
+ */
+type AuditLogQuery = {
+    /** Filter by key ID */
+    keyId?: string;
+    /** Filter by owner ID */
+    ownerId?: string;
+    /** Filter by action */
+    action?: AuditAction;
+    /** Filter by start date (ISO timestamp) */
+    startDate?: string;
+    /** Filter by end date (ISO timestamp) */
+    endDate?: string;
+    /** Maximum number of results to return (default: 100) */
+    limit?: number;
+    /** Offset for pagination (default: 0) */
+    offset?: number;
+};
+/**
+ * Statistics about audit logs
+ */
+type AuditLogStats = {
+    /** Total number of logs */
+    total: number;
+    /** Count by action type */
+    byAction: Partial<Record<AuditAction, number>>;
+    /** ISO timestamp of last activity */
+    lastActivity: string | null;
+};
+
+/**
+ * Storage interface for persisting API keys
+ */
+type Storage = {
+    /**
+     * Save an API key record to storage
+     */
+    save(record: ApiKeyRecord): Promise<void>;
+    /**
+     * Find an API key record by its hash
+     */
+    findByHash(keyHash: string): Promise<ApiKeyRecord | null>;
+    /**
+     * Find an API key record by ID
+     */
+    findById(id: string): Promise<ApiKeyRecord | null>;
+    /**
+     * Find all API keys for a specific owner
+     */
+    findByOwner(ownerId: string): Promise<ApiKeyRecord[]>;
+    /**
+     * Find all API keys by tags and optionally by owner
+     * @param tags - Tags to search for
+     * @param ownerId - Optional owner ID to filter results
+     */
+    findByTags(tags: string[], ownerId?: string): Promise<ApiKeyRecord[]>;
+    /**
+     * Find all API keys by tag and optionally by owner
+     * @param tag - Tag to search for
+     * @param ownerId - Optional owner ID to filter results
+     */
+    findByTag(tag: string, ownerId?: string): Promise<ApiKeyRecord[]>;
+    /**
+     * Update metadata for an existing key
+     */
+    updateMetadata(id: string, metadata: Partial<ApiKeyMetadata>): Promise<void>;
+    /**
+     * Delete an API key record
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all keys for a specific owner
+     */
+    deleteByOwner(ownerId: string): Promise<void>;
+    /**
+     * Save an audit log entry (optional, only if audit logging is enabled)
+     */
+    saveLog?(log: AuditLog): Promise<void>;
+    /**
+     * Query audit logs (optional, only if audit logging is enabled)
+     */
+    findLogs?(query: AuditLogQuery): Promise<AuditLog[]>;
+    /**
+     * Count audit logs matching query (optional, only if audit logging is enabled)
+     */
+    countLogs?(query: AuditLogQuery): Promise<number>;
+    /**
+     * Delete audit logs matching query (optional, only if audit logging is enabled)
+     * @returns Number of logs deleted
+     */
+    deleteLogs?(query: AuditLogQuery): Promise<number>;
+    /**
+     * Get statistics about audit logs (optional, only if audit logging is enabled)
+     */
+    getLogStats?(ownerId: string): Promise<AuditLogStats>;
+};
+/**
+ * Options for storage operations
+ */
+type StorageOptions = {
+    /** Optional TTL (time to live) in seconds */
+    ttl?: number;
+};
+
+export type { ActionContext as A, CreateApiKeyInput as C, Storage as S, ApiKeyRecord as a, ApiKeyMetadata as b, AuditLogQuery as c, AuditLog as d, AuditLogStats as e, AuditAction as f, StorageOptions as g };

package/dist/shared/keypal.kItV-5pB.d.ts

@@ -0,0 +1,194 @@
+import { Static, Type } from 'typebox';
+
+/**
+ * Metadata associated with an API key
+ */
+declare const ApiKeyMetadataSchema: Type.TObject<{
+    /** Unique identifier for the key owner */
+    ownerId: Type.TString;
+    /** Optional human-readable name for the key */
+    name: Type.TOptional<Type.TString>;
+    /** Optional description of what this key is used for */
+    description: Type.TOptional<Type.TString>;
+    /** Scopes/permissions associated with this key */
+    scopes: Type.TOptional<Type.TArray<Type.TString>>;
+    /** Resource-specific scopes (e.g., { "website:123": ["read"], "project:456": ["write"] }) */
+    resources: Type.TOptional<Type.TRecord<"^.*$", Type.TArray<Type.TString>>>;
+    /** ISO timestamp when the key expires (null if never expires) */
+    expiresAt: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    /** ISO timestamp when the key was created */
+    createdAt: Type.TOptional<Type.TString>;
+    /** ISO timestamp when the key was last used */
+    lastUsedAt: Type.TOptional<Type.TString>;
+    /** Whether the key is enabled (default: true) */
+    enabled: Type.TOptional<Type.TBoolean>;
+    /** ISO timestamp when the key was revoked (null if not revoked) */
+    revokedAt: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    /** ID of the key this was rotated to (for key rotation) */
+    rotatedTo: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    tags: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+type ApiKeyMetadata = Static<typeof ApiKeyMetadataSchema>;
+/**
+ * Complete API key record stored in the database
+ */
+type ApiKeyRecord = {
+    /** Hashed version of the API key */
+    keyHash: string;
+    /** Unique identifier for this key record */
+    id: string;
+    /** Metadata associated with the key */
+    metadata: ApiKeyMetadata;
+};
+/**
+ * Input for creating an API key
+ */
+type CreateApiKeyInput = {
+    /** Optional custom prefix */
+    prefix?: string;
+    /** Optional custom length */
+    length?: number;
+    /** Metadata to associate with the key */
+    metadata: Partial<ApiKeyMetadata>;
+};
+
+/**
+ * Audit log action types
+ */
+type AuditAction = "created" | "revoked" | "rotated" | "enabled" | "disabled";
+/**
+ * Context for who performed an action
+ */
+type ActionContext = {
+    /** User ID who performed the action */
+    userId?: string;
+    /** IP address of the requester */
+    ip?: string;
+    /** User agent of the requester */
+    userAgent?: string;
+    /** Custom metadata about the action */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Audit log entry
+ */
+type AuditLog = {
+    /** Unique identifier for this log entry */
+    id: string;
+    /** The action that was performed */
+    action: AuditAction;
+    /** ID of the API key */
+    keyId: string;
+    /** ID of the key owner */
+    ownerId: string;
+    /** ISO timestamp when the action occurred */
+    timestamp: string;
+    /** Optional additional data about the action */
+    data?: Record<string, unknown>;
+};
+/**
+ * Options for querying audit logs
+ */
+type AuditLogQuery = {
+    /** Filter by key ID */
+    keyId?: string;
+    /** Filter by owner ID */
+    ownerId?: string;
+    /** Filter by action */
+    action?: AuditAction;
+    /** Filter by start date (ISO timestamp) */
+    startDate?: string;
+    /** Filter by end date (ISO timestamp) */
+    endDate?: string;
+    /** Maximum number of results to return (default: 100) */
+    limit?: number;
+    /** Offset for pagination (default: 0) */
+    offset?: number;
+};
+/**
+ * Statistics about audit logs
+ */
+type AuditLogStats = {
+    /** Total number of logs */
+    total: number;
+    /** Count by action type */
+    byAction: Partial<Record<AuditAction, number>>;
+    /** ISO timestamp of last activity */
+    lastActivity: string | null;
+};
+
+/**
+ * Storage interface for persisting API keys
+ */
+type Storage = {
+    /**
+     * Save an API key record to storage
+     */
+    save(record: ApiKeyRecord): Promise<void>;
+    /**
+     * Find an API key record by its hash
+     */
+    findByHash(keyHash: string): Promise<ApiKeyRecord | null>;
+    /**
+     * Find an API key record by ID
+     */
+    findById(id: string): Promise<ApiKeyRecord | null>;
+    /**
+     * Find all API keys for a specific owner
+     */
+    findByOwner(ownerId: string): Promise<ApiKeyRecord[]>;
+    /**
+     * Find all API keys by tags and optionally by owner
+     * @param tags - Tags to search for
+     * @param ownerId - Optional owner ID to filter results
+     */
+    findByTags(tags: string[], ownerId?: string): Promise<ApiKeyRecord[]>;
+    /**
+     * Find all API keys by tag and optionally by owner
+     * @param tag - Tag to search for
+     * @param ownerId - Optional owner ID to filter results
+     */
+    findByTag(tag: string, ownerId?: string): Promise<ApiKeyRecord[]>;
+    /**
+     * Update metadata for an existing key
+     */
+    updateMetadata(id: string, metadata: Partial<ApiKeyMetadata>): Promise<void>;
+    /**
+     * Delete an API key record
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all keys for a specific owner
+     */
+    deleteByOwner(ownerId: string): Promise<void>;
+    /**
+     * Save an audit log entry (optional, only if audit logging is enabled)
+     */
+    saveLog?(log: AuditLog): Promise<void>;
+    /**
+     * Query audit logs (optional, only if audit logging is enabled)
+     */
+    findLogs?(query: AuditLogQuery): Promise<AuditLog[]>;
+    /**
+     * Count audit logs matching query (optional, only if audit logging is enabled)
+     */
+    countLogs?(query: AuditLogQuery): Promise<number>;
+    /**
+     * Delete audit logs matching query (optional, only if audit logging is enabled)
+     * @returns Number of logs deleted
+     */
+    deleteLogs?(query: AuditLogQuery): Promise<number>;
+    /**
+     * Get statistics about audit logs (optional, only if audit logging is enabled)
+     */
+    getLogStats?(ownerId: string): Promise<AuditLogStats>;
+};
+/**
+ * Options for storage operations
+ */
+type StorageOptions = {
+    /** Optional TTL (time to live) in seconds */
+    ttl?: number;
+};
+
+export type { ActionContext as A, CreateApiKeyInput as C, Storage as S, ApiKeyRecord as a, ApiKeyMetadata as b, AuditLogQuery as c, AuditLog as d, AuditLogStats as e, AuditAction as f, StorageOptions as g };

package/dist/shared/keypal.lTVSZWgp.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{customAlphabet as n}from"nanoid";const i="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",l=32,a=n(i,l);function f(o={}){const{prefix:e="",length:r=32,alphabet:s=i}=o,t=r===l&&s===i?a():n(s,r)();return e?`${e}${t}`:t}class h{level;prefix;silent;constructor(e={}){this.level=e.level??"info",this.prefix=e.prefix??"",this.silent=e.silent??!1}shouldLog(e){if(this.silent)return!1;const r=["debug","info","warn","error"],s=r.indexOf(this.level);return r.indexOf(e)>=s}formatMessage(e,r){const s=this.prefix?`[${this.prefix}]`:"",t=e.toUpperCase();return`${s} ${t}: ${r}`}debug(e,...r){this.shouldLog("debug")&&console.debug(this.formatMessage("debug",e),...r)}info(e,...r){this.shouldLog("info")&&console.info(this.formatMessage("info",e),...r)}warn(e,...r){this.shouldLog("warn")&&console.warn(this.formatMessage("warn",e),...r)}error(e,...r){this.shouldLog("error")&&console.error(this.formatMessage("error",e),...r)}}function g(o){return new h(o)}const u=g({prefix:"keypal"});export{f as g,u as l};

package/dist/storage/drizzle.d.mts

@@ -0,0 +1,192 @@
+import { S as Storage, a as ApiKeyRecord, b as ApiKeyMetadata, d as AuditLog, c as AuditLogQuery, e as AuditLogStats } from '../shared/keypal.kItV-5pB.mjs';
+import 'typebox';
+
+/**
+ * Column mapping for API keys table
+ */
+type ApiKeyColumnMapping = {
+    /** Column name for the key ID (default: 'id') */
+    id?: string;
+    /** Column name for the hashed key (default: 'keyHash') */
+    keyHash?: string;
+    /** Column name for the metadata (default: 'metadata') */
+    metadata?: string;
+    /** Custom columns mapping for metadata fields */
+    metadataColumns?: {
+        ownerId?: string;
+        name?: string;
+        description?: string;
+        scopes?: string;
+        resources?: string;
+        rateLimit?: string;
+        expiresAt?: string;
+        revokedAt?: string;
+        lastUsedAt?: string;
+        createdAt?: string;
+        tags?: string;
+        allowedIps?: string;
+        allowedOrigins?: string;
+        [key: string]: string | undefined;
+    };
+};
+/**
+ * Column mapping for audit logs table
+ */
+type AuditLogColumnMapping = {
+    id?: string;
+    keyId?: string;
+    ownerId?: string;
+    action?: string;
+    timestamp?: string;
+    data?: string;
+};
+/**
+ * Schema configuration for both tables
+ */
+type SchemaConfig = {
+    /** Table name for API keys (default: 'apikey' or 'apikeys') */
+    apiKeyTable?: string;
+    /** Column mappings for API keys table */
+    apiKeyColumns?: ApiKeyColumnMapping;
+    /** Table name for audit logs (default: 'auditlog' or 'auditlogs') */
+    auditLogTable?: string;
+    /** Column mappings for audit logs table */
+    auditLogColumns?: AuditLogColumnMapping;
+    /** Whether to use flattened schema (metadata as separate columns) */
+    flattenMetadata?: boolean;
+};
+
+/**
+ * Generic database interface for Drizzle
+ * Supports any Drizzle database type (PostgreSQL, MySQL, SQLite)
+ */
+interface DrizzleDB {
+    [key: string]: any;
+}
+/**
+ * Generic table interface for Drizzle
+ */
+interface DrizzleTable {
+    [key: string]: any;
+}
+/**
+ * Configuration for Drizzle adapter
+ */
+interface DrizzleAdapterConfig {
+    /**
+     * The Drizzle database instance
+     * Supports PostgreSQL, MySQL, and SQLite
+     */
+    db: DrizzleDB;
+    /**
+     * The table for API keys
+     */
+    table: DrizzleTable;
+    /**
+     * The database provider
+     * Used for provider-specific optimizations
+     */
+    provider?: "pg" | "mysql" | "sqlite";
+    /**
+     * Schema configuration for custom column names and flattened metadata
+     */
+    schema?: SchemaConfig;
+    /**
+     * Optional table for audit logs
+     */
+    auditLogTable?: DrizzleTable;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debugLogs?: boolean;
+}
+/**
+ * Create a Drizzle storage adapter for API keys
+ *
+ * **Supports:**
+ * - PostgreSQL, MySQL, and SQLite
+ * - Custom column names
+ * - Custom table names
+ * - Flattened metadata schema
+ * - JSON/JSONB columns
+ * - Audit logging
+ *
+ * **Required Table Columns (default schema):**
+ * - `id`: TEXT PRIMARY KEY
+ * - `keyHash`: TEXT
+ * - `metadata`: JSONB (or TEXT for MySQL/SQLite)
+ *
+ * @example
+ * ```typescript
+ * // Default schema (PostgreSQL)
+ * import { createDrizzleStore } from 'keypal/drizzle';
+ * import { apikey } from 'keypal/drizzle/schema';
+ * const store = createDrizzleStore({ db, table: apikey, provider: 'pg' });
+ *
+ * // MySQL with custom column names
+ * const store = createDrizzleStore({
+ *   db,
+ *   table: customTable,
+ *   provider: 'mysql',
+ *   schema: {
+ *     apiKeyColumns: {
+ *       id: 'key_id',
+ *       keyHash: 'key_hash',
+ *       metadata: 'key_metadata'
+ *     }
+ *   }
+ * });
+ *
+ * // SQLite with flattened metadata
+ * const store = createDrizzleStore({
+ *   db,
+ *   table: flatTable,
+ *   provider: 'sqlite',
+ *   schema: {
+ *     flattenMetadata: true,
+ *     apiKeyColumns: {
+ *       metadataColumns: {
+ *         ownerId: 'owner_id',
+ *         name: 'key_name',
+ *         scopes: 'key_scopes'
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function createDrizzleStore(options: DrizzleAdapterConfig): Storage;
+/**
+ * Storage adapter class for Drizzle ORM
+ *
+ * @example
+ * ```typescript
+ * const store = new DrizzleStore({ db, table: apikey, provider: 'pg' });
+ * ```
+ */
+declare class DrizzleStore implements Storage {
+    private readonly storage;
+    constructor(options: DrizzleAdapterConfig);
+    save: (record: ApiKeyRecord) => Promise<void>;
+    findByHash: (keyHash: string) => Promise<ApiKeyRecord | null>;
+    findById: (id: string) => Promise<ApiKeyRecord | null>;
+    findByOwner: (ownerId: string) => Promise<ApiKeyRecord[]>;
+    findByTags: (tags: string[], ownerId?: string) => Promise<ApiKeyRecord[]>;
+    findByTag: (tag: string, ownerId?: string) => Promise<ApiKeyRecord[]>;
+    updateMetadata: (id: string, metadata: Partial<ApiKeyMetadata>) => Promise<void>;
+    delete: (id: string) => Promise<void>;
+    deleteByOwner: (ownerId: string) => Promise<void>;
+    saveLog: (log: AuditLog) => Promise<void>;
+    findLogs: (query: AuditLogQuery) => Promise<AuditLog[]>;
+    countLogs: (query: AuditLogQuery) => Promise<number>;
+    deleteLogs: (query: AuditLogQuery) => Promise<number>;
+    getLogStats: (ownerId: string) => Promise<AuditLogStats> | Promise<{
+        total: number;
+        byAction: {};
+        lastActivity: null;
+    }>;
+}
+
+export { DrizzleStore, createDrizzleStore };
+export type { DrizzleAdapterConfig, DrizzleDB, DrizzleTable };