@nauth-toolkit/core 0.3.1 → 0.3.2

package/dist/services/api-key.service.d.ts

@@ -4,53 +4,35 @@ import { BaseUser } from '../entities/user.entity';
 import { NAuthConfig } from '../interfaces/config.interface';
 import { NAuthLogger } from '../utils/nauth-logger';
 import { InternalAuthAuditService } from './auth-audit.service';
-import { ApiKeyResponseDTO, CreateApiKeyResponseDTO } from '../dto/api-key.dto';
-/**
- * Parameters for creating an API key.
- * The owning `userId` is always supplied by the caller (never from request bodies).
- */
-export interface CreateApiKeyParams {
-    /** Internal user ID the key authenticates as */
-    userId: number;
-    /** Optional label */
-    name?: string | null;
-    /** Expiry in days, `null` for never, or `undefined` to trigger the mandatory-expiry error */
-    expiresInDays?: number | null;
-    /** Optional IP allowlist (IPs / IPv4 CIDR ranges) */
-    allowedIps?: string[];
-    /** Whether an administrator is creating the key on behalf of the user */
-    createdByAdmin?: boolean;
-}
-/** Parameters for updating an API key's mutable fields. */
-export interface UpdateApiKeyParams {
-    userId: number;
-    keyId: string;
-    name?: string | null;
-    allowedIps?: string[];
-}
-/** Result of a successful API key validation. */
+import { CreateApiKeyDTO, UpdateApiKeyDTO, RevokeApiKeyDTO, DeleteApiKeyDTO, ApiKeyResponseDTO, CreateApiKeyResponseDTO, ListApiKeysResponseDTO, RevokeApiKeyResponseDTO, DeleteApiKeyResponseDTO } from '../dto/api-key.dto';
+import { AdminCreateApiKeyDTO, AdminUpdateApiKeyDTO, AdminManageApiKeyDTO } from '../dto/admin-api-key.dto';
+/** Result of a successful API key validation (internal auth path). */
 export interface ApiKeyValidationResult {
     /** External key identifier (UUID v4) */
     keyId: string;
-    /** Internal owning user ID */
-    userId: number;
-    /** Owning user's external identifier (UUID v4) */
+    /** Owning user's external identifier (UUID v4) — callers load the user context from this */
     sub: string;
 }
 /**
  * API Key Service
  *
- * Manages the lifecycle of API keys (create/list/update/revoke/delete) and validates
- * keys presented on requests. Keys authenticate as their owning user.
+ * Owns the full API key lifecycle and validation. Keys authenticate **as their owning user**.
+ *
+ * Identity convention (matches the rest of the toolkit):
+ * - **Self-service** methods (`createKey`, `listKeys`, `updateKey`, `revokeKey`, `deleteKey`)
+ *   act on the *currently authenticated* user, resolved from request context. They take no
+ *   user identifier.
+ * - **Admin** methods (`adminCreateKey`, `adminListKeys`, `adminUpdateKey`, `adminRevokeKey`,
+ *   `adminDeleteKey`) act on a target user identified by `sub`. Protect them with admin auth.
+ *
+ * Every public method takes a request DTO and returns a response DTO, and validates the DTO at
+ * runtime (via {@link ensureValidatedDto}) so non-NestJS callers are protected from invalid input.
  *
  * Security:
- * - Only a SHA-256 hash of the full key is stored; the plaintext is returned once at creation.
- * - Lookup uses a non-secret, indexed `lookupId`; the secret is compared in constant time.
+ * - Only a SHA-256 hash of the key is stored; the plaintext is returned once at creation.
+ * - Presented keys are hashed and looked up by that hash (indexed, unique) — the plaintext never
+ *   leaves the caller and is never compared field-by-field.
  * - Per-key IP allowlists (optional) restrict which source IPs may use a key.
- *
- * @remarks
- * This service does NOT enforce endpoint authorization. Route protection (which endpoints
- * accept API keys) is the responsibility of the framework adapter (guard/middleware).
  */
 export declare class ApiKeyService {
     private readonly apiKeyRepository;
@@ -60,49 +42,66 @@ export declare class ApiKeyService {
     private readonly auditService?;
     constructor(apiKeyRepository: Repository<BaseApiKey>, userRepository: Repository<BaseUser>, config: NAuthConfig, logger: NAuthLogger, auditService?: InternalAuthAuditService | undefined);
     /**
-     * Create a new API key.
+     * Create an API key for the currently authenticated user.
      *
-     * @param params - Creation parameters (owning userId is required)
-     * @returns The plaintext key (shown once) plus sanitized metadata
      * @throws {NAuthException} API_KEY_CREATION_DISABLED, API_KEY_LIMIT_REACHED,
      *   API_KEY_EXPIRY_REQUIRED, API_KEY_INDEFINITE_NOT_ALLOWED, API_KEY_EXPIRY_TOO_LONG,
-     *   VALIDATION_FAILED (invalid IP allowlist), USER_NOT_FOUND
+     *   VALIDATION_FAILED, FORBIDDEN (not authenticated)
+     */
+    createKey(dto: CreateApiKeyDTO): Promise<CreateApiKeyResponseDTO>;
+    /**
+     * List the current user's API keys (sanitized; never includes secrets).
      */
-    createKey(params: CreateApiKeyParams): Promise<CreateApiKeyResponseDTO>;
+    listKeys(): Promise<ListApiKeysResponseDTO>;
     /**
-     * Update a key's mutable fields (name and IP allowlist).
-     * The secret and expiry are immutable — rotate/extend by deleting and recreating.
+     * Update the current user's key (label and/or IP allowlist). Secret and expiry are immutable.
      *
-     * @throws {NAuthException} API_KEY_NOT_FOUND, VALIDATION_FAILED
+     * @throws {NAuthException} API_KEY_NOT_FOUND, VALIDATION_FAILED, FORBIDDEN
      */
-    updateKey(params: UpdateApiKeyParams): Promise<ApiKeyResponseDTO>;
+    updateKey(dto: UpdateApiKeyDTO): Promise<ApiKeyResponseDTO>;
     /**
-     * List all keys owned by a user (sanitized; never includes secrets).
+     * Revoke (soft-delete) one of the current user's keys.
+     *
+     * @throws {NAuthException} API_KEY_NOT_FOUND, FORBIDDEN
+     */
+    revokeKey(dto: RevokeApiKeyDTO): Promise<RevokeApiKeyResponseDTO>;
+    /**
+     * Permanently delete one of the current user's keys.
+     *
+     * @throws {NAuthException} API_KEY_NOT_FOUND, FORBIDDEN
+     */
+    deleteKey(dto: DeleteApiKeyDTO): Promise<DeleteApiKeyResponseDTO>;
+    /**
+     * Create an API key on behalf of a user. Bypasses `allowUserCreation`, but still enforces
+     * `maxKeysPerUser`, expiry, and IP-restriction rules.
+     *
+     * @throws {NAuthException} USER_NOT_FOUND, or any API_KEY_* creation error
+     */
+    adminCreateKey(dto: AdminCreateApiKeyDTO): Promise<CreateApiKeyResponseDTO>;
+    /**
+     * List a user's API keys (admin).
+     *
+     * @throws {NAuthException} USER_NOT_FOUND
+     */
+    adminListKeys(dto: AdminManageApiKeyDTO): Promise<ListApiKeysResponseDTO>;
+    /**
+     * Update a user's key (admin).
+     *
+     * @throws {NAuthException} USER_NOT_FOUND, API_KEY_NOT_FOUND, VALIDATION_FAILED
      */
-    listKeys(userId: number): Promise<ApiKeyResponseDTO[]>;
+    adminUpdateKey(dto: AdminUpdateApiKeyDTO): Promise<ApiKeyResponseDTO>;
     /**
-     * Revoke (soft-delete) a key. The record is retained for audit history.
+     * Revoke (soft-delete) a user's key (admin).
      *
-     * @throws {NAuthException} API_KEY_NOT_FOUND
+     * @throws {NAuthException} USER_NOT_FOUND, API_KEY_NOT_FOUND, VALIDATION_FAILED
      */
-    revokeKey(params: {
-        userId: number;
-        keyId: string;
-        reason?: string;
-    }): Promise<{
-        success: boolean;
-    }>;
+    adminRevokeKey(dto: AdminManageApiKeyDTO): Promise<RevokeApiKeyResponseDTO>;
     /**
-     * Permanently delete a key.
+     * Permanently delete a user's key (admin).
      *
-     * @throws {NAuthException} API_KEY_NOT_FOUND
+     * @throws {NAuthException} USER_NOT_FOUND, API_KEY_NOT_FOUND, VALIDATION_FAILED
      */
-    deleteKey(params: {
-        userId: number;
-        keyId: string;
-    }): Promise<{
-        success: boolean;
-    }>;
+    adminDeleteKey(dto: AdminManageApiKeyDTO): Promise<DeleteApiKeyResponseDTO>;
     /**
      * Validate a presented API key and resolve its owner.
      *
@@ -111,10 +110,45 @@ export declare class ApiKeyService {
      *
      * @param rawKey - The full plaintext key from the request header
      * @param callerIp - Source IP of the request (for IP-allowlist enforcement + usage tracking)
-     * @returns The owning user's identifiers on success
      * @throws {NAuthException} API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_IP_NOT_ALLOWED
      */
     validateKey(rawKey: string, callerIp?: string | null): Promise<ApiKeyValidationResult>;
+    /**
+     * Core key creation for a resolved user.
+     */
+    private createForUser;
+    /**
+     * List a resolved user's keys.
+     */
+    private listForUser;
+    /**
+     * Update a resolved user's key (label / IP allowlist).
+     */
+    private updateForUser;
+    /**
+     * Revoke (soft-delete) a resolved user's key.
+     */
+    private revokeForUser;
+    /**
+     * Permanently delete a resolved user's key.
+     */
+    private deleteForUser;
+    /**
+     * Resolve the currently authenticated user from request context.
+     *
+     * @throws {NAuthException} FORBIDDEN when no authenticated user is present
+     */
+    private getCurrentUserOrThrow;
+    /**
+     * Resolve an internal user id from an external sub (UUID).
+     *
+     * @throws {NAuthException} USER_NOT_FOUND
+     */
+    private resolveUserIdBySub;
+    /**
+     * Ensure a keyId is present for admin revoke/delete operations.
+     */
+    private requireKeyId;
     /**
      * Resolve the mandatory, config-bounded expiry.
      */
@@ -124,17 +158,9 @@ export declare class ApiKeyService {
      */
     private normalizeAllowedIps;
     /**
-     * Compute the SHA-256 hex hash of a full key string.
+     * Compute the SHA-256 hex hash of a key string (used for storage + indexed lookup).
      */
     private hashKey;
-    /**
-     * Constant-time comparison of two equal-length hex hashes.
-     */
-    private hashesEqual;
-    /**
-     * Extract the non-secret lookup id from a raw key of the form `prefix_lookupId.secret`.
-     */
-    private parseLookupId;
     /**
      * Update last-used metadata, throttled to avoid a write on every request.
      * Never throws — usage tracking must not block authentication.

package/dist/services/api-key.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-key.service.d.ts","sourceRoot":"","sources":["../../src/services/api-key.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAJb,gBAAgB,EAAE,UAAU,CAAC,UAAU,CAAC,EACxC,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,wBAAwB,YAAA;IAK1D;;;;;;;;OAQG;IACG,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IA8D7E;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqBvE;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAQ5D;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAkB1G;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAazF;;;;;;;;;;OAUG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmD5F;;OAEG;IACH,OAAO,CAAC,aAAa;IAqCrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsC3B;;OAEG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAgBrB;;;OAGG;YACW,WAAW;IA4BzB;;OAEG;IACH,OAAO,CAAC,UAAU;IAgBlB;;OAEG;YACW,KAAK;CAsBpB"}
+{"version":3,"file":"api-key.service.d.ts","sourceRoot":"","sources":["../../src/services/api-key.service.ts"],"names":[],"mappings":"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"}