@xbg.solutions/utils-token-handler 1.0.0

package/lib/token-types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Token Handler Types
+ * Platform-agnostic types for token handling utilities
+ */
+import { Logger } from '@xbg/utils-logger';
+/**
+ * Normalized token payload - platform-agnostic structure
+ * This is what applications work with internally, regardless of auth provider
+ */
+export interface NormalizedToken<TCustomClaims = Record<string, any>> {
+    authUID: string;
+    userUID: string | null;
+    email: string | null;
+    emailVerified: boolean;
+    phoneNumber: string | null;
+    issuedAt: number;
+    expiresAt: number;
+    issuer: string;
+    customClaims: TCustomClaims;
+    rawClaims: Record<string, any>;
+}
+/**
+ * Token verification result
+ */
+export interface TokenVerificationResult<TCustomClaims = Record<string, any>> {
+    isValid: boolean;
+    isBlacklisted: boolean;
+    token: NormalizedToken<TCustomClaims> | null;
+    error: TokenVerificationError | null;
+}
+/**
+ * Token verification errors
+ */
+export declare enum TokenVerificationError {
+    EXPIRED = "EXPIRED",
+    INVALID_SIGNATURE = "INVALID_SIGNATURE",
+    BLACKLISTED = "BLACKLISTED",
+    MALFORMED = "MALFORMED",
+    ISSUER_MISMATCH = "ISSUER_MISMATCH",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Blacklist entry
+ */
+export interface TokenBlacklistEntry {
+    blacklistEntryUID: string;
+    tokenJTI: string;
+    authUID: string;
+    blacklistedAt: Date;
+    blacklistedBy: string | null;
+    reason: string;
+    expiresAt: Date;
+}
+/**
+ * Abstract token adapter interface
+ * All auth provider implementations must implement this
+ */
+export interface ITokenAdapter<TCustomClaims = Record<string, any>> {
+    /**
+     * Verify token with the auth provider
+     * Returns provider-specific decoded token or throws error
+     */
+    verifyToken(rawToken: string, logger: Logger): Promise<any>;
+    /**
+     * Generate unique identifier for token (for blacklist lookup)
+     * Different providers may use jti claim or hash of token
+     */
+    getTokenIdentifier(rawToken: string): Promise<string>;
+    /**
+     * Normalize provider-specific token to platform-agnostic structure
+     */
+    normalizeToken(providerToken: any, customClaimsConfig: CustomClaimsConfig<TCustomClaims>): NormalizedToken<TCustomClaims>;
+    /**
+     * Sync custom claims to auth provider
+     * Updates provider's custom claims with app data
+     */
+    syncCustomClaims(authUID: string, claims: TCustomClaims, logger: Logger): Promise<void>;
+    /**
+     * Revoke all tokens for a user at provider level (if supported)
+     * Not all providers support this - return false if unsupported
+     */
+    revokeUserTokens(authUID: string, logger: Logger): Promise<boolean>;
+    /**
+     * Map provider-specific errors to standard error types
+     */
+    mapProviderError(error: any): TokenVerificationError;
+}
+/**
+ * Configuration for custom claims extraction and validation
+ */
+export interface CustomClaimsConfig<TCustomClaims> {
+    /**
+     * Extract custom claims from provider token
+     */
+    extract: (providerToken: any) => TCustomClaims;
+    /**
+     * Validate custom claims structure (optional)
+     */
+    validate?: (claims: TCustomClaims) => boolean;
+    /**
+     * Default/fallback claims when none exist
+     */
+    defaults: Partial<TCustomClaims>;
+}
+/**
+ * Database connector interface for blacklist operations
+ */
+export interface ITokenDatabase {
+    /**
+     * Add entry to blacklist
+     */
+    addBlacklistEntry(entry: TokenBlacklistEntry): Promise<void>;
+    /**
+     * Check if token identifier is blacklisted
+     */
+    isTokenBlacklisted(tokenIdentifier: string): Promise<boolean>;
+    /**
+     * Get user's global token revocation timestamp
+     */
+    getUserRevocationTime(authUID: string): Promise<Date | null>;
+    /**
+     * Add global revocation entry for user
+     */
+    addUserRevocation(authUID: string, reason: string, blacklistedBy: string | null, expiresAt: Date): Promise<void>;
+    /**
+     * Remove expired blacklist entries
+     */
+    cleanupExpiredEntries(): Promise<number>;
+}
+/**
+ * Blacklist configuration
+ */
+export interface BlacklistConfig {
+    /**
+     * Database/collection to store blacklist entries
+     */
+    storage: {
+        database: string;
+        collection: string;
+    };
+    /**
+     * Cleanup and retention settings
+     */
+    retention: {
+        cleanupRetentionDays: number;
+        globalRevocationRetentionDays: number;
+    };
+    /**
+     * Valid blacklist reasons for this project
+     */
+    reasons: string[];
+}
+/**
+ * Provider-specific configuration
+ */
+export interface ProviderConfig {
+    type: 'firebase' | 'auth0' | 'clerk' | 'custom';
+    firebase?: {
+        projectId?: string;
+    };
+    auth0?: {
+        domain: string;
+        audience: string;
+    };
+    clerk?: {
+        secretKey: string;
+    };
+    custom?: {
+        [key: string]: any;
+    };
+}
+/**
+ * Complete token handler configuration
+ */
+export interface TokenHandlerConfig<TCustomClaims = Record<string, any>> {
+    /**
+     * Custom claims configuration
+     */
+    customClaims: CustomClaimsConfig<TCustomClaims>;
+    /**
+     * Blacklist settings
+     */
+    blacklist: BlacklistConfig;
+    /**
+     * Auth provider configuration
+     */
+    provider: ProviderConfig;
+    /**
+     * Database connector for blacklist operations
+     */
+    database: ITokenDatabase;
+}
+/**
+ * Factory function signature for creating configured token handlers
+ */
+export type TokenHandlerFactory<TCustomClaims = Record<string, any>> = (config: TokenHandlerConfig<TCustomClaims>) => ITokenHandler<TCustomClaims>;
+/**
+ * Main token handler interface
+ */
+export interface ITokenHandler<TCustomClaims = Record<string, any>> {
+    /**
+     * Verify and unpack raw token string
+     * Returns normalized token if valid, or error details if invalid
+     */
+    verifyAndUnpack(rawToken: string, logger: Logger): Promise<TokenVerificationResult<TCustomClaims>>;
+    /**
+     * Generate token identifier for blacklist lookup
+     */
+    getTokenIdentifier(rawToken: string): Promise<string>;
+    /**
+     * Sync custom claims to auth provider
+     */
+    syncCustomClaims(authUID: string, claims: TCustomClaims, logger: Logger): Promise<void>;
+    /**
+     * Revoke all tokens for a user at provider level
+     */
+    revokeUserTokens(authUID: string, logger: Logger): Promise<boolean>;
+    /**
+     * Blacklist individual token
+     */
+    blacklistToken(tokenIdentifier: string, authUID: string, reason: string, tokenExpiresAt: Date, blacklistedBy: string | null, logger: Logger): Promise<TokenBlacklistEntry>;
+    /**
+     * Blacklist all tokens for a user (global revocation)
+     */
+    blacklistAllUserTokens(authUID: string, reason: string, blacklistedBy: string | null, logger: Logger): Promise<void>;
+    /**
+     * Check if token is blacklisted
+     */
+    isTokenBlacklisted(tokenIdentifier: string, logger: Logger): Promise<boolean>;
+    /**
+     * Get user's token revocation timestamp
+     */
+    getUserTokenRevocationTime(authUID: string, logger: Logger): Promise<Date | null>;
+    /**
+     * Cleanup expired blacklist entries
+     */
+    cleanupExpiredEntries(logger: Logger): Promise<number>;
+}
+//# sourceMappingURL=token-types.d.ts.map

package/lib/token-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-types.d.ts","sourceRoot":"","sources":["../src/token-types.ts"],"names":[],"mappings":"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"}

package/lib/token-types.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Token Handler Types
+ * Platform-agnostic types for token handling utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenVerificationError = void 0;
+/**
+ * Token verification errors
+ */
+var TokenVerificationError;
+(function (TokenVerificationError) {
+    TokenVerificationError["EXPIRED"] = "EXPIRED";
+    TokenVerificationError["INVALID_SIGNATURE"] = "INVALID_SIGNATURE";
+    TokenVerificationError["BLACKLISTED"] = "BLACKLISTED";
+    TokenVerificationError["MALFORMED"] = "MALFORMED";
+    TokenVerificationError["ISSUER_MISMATCH"] = "ISSUER_MISMATCH";
+    TokenVerificationError["UNKNOWN"] = "UNKNOWN";
+})(TokenVerificationError || (exports.TokenVerificationError = TokenVerificationError = {}));
+//# sourceMappingURL=token-types.js.map

package/lib/token-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-types.js","sourceRoot":"","sources":["../src/token-types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAwCH;;GAEG;AACH,IAAY,sBAOX;AAPD,WAAY,sBAAsB;IAChC,6CAAmB,CAAA;IACnB,iEAAuC,CAAA;IACvC,qDAA2B,CAAA;IAC3B,iDAAuB,CAAA;IACvB,6DAAmC,CAAA;IACnC,6CAAmB,CAAA;AACrB,CAAC,EAPW,sBAAsB,sCAAtB,sBAAsB,QAOjC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xbg.solutions/utils-token-handler",
+  "version": "1.0.0",
+  "description": "JWT generation, verification, and blacklist management",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rm -rf lib",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@xbg/utils-logger": "^1.0.0",
+    "firebase-admin": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": "22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}