@focura/auth-core 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @focura/auth-core
 
-Production-ready authentication core for Express.js backends.
+Production-ready authentication engine for Node.js backends.
 
 ## Features
 
@@ -19,19 +19,19 @@ Production-ready authentication core for Express.js backends.
 ## Installation
 
 ```bash
-npm install @focura/auth-core express ioredis
-npm install -D @types/express
+npm install @focura/auth-core ioredis
 ```
 
 ## Quick Start
 
 ```typescript
-import { MiddlewareFactory, AccountLockout, SessionManager } from "@focura/auth-core";
+import { AuthService } from "@focura/auth-core";
 import Redis from "ioredis";
+import fs from "fs";
 
 const redis = new Redis(process.env.REDIS_URL!);
 
-const auth = new MiddlewareFactory({
+const auth = new AuthService({
   redis,
   userStore: {
     findById: (id) => prisma.user.findUnique({ where: { id } }),
@@ -39,34 +39,147 @@ const auth = new MiddlewareFactory({
     update: (id, data) => prisma.user.update({ where: { id }, data }),
     updateEmailVerified: (id, date) => prisma.user.update({ where: { id }, data: { emailVerified: date } }),
   },
-  hmacSecret: process.env.NEXTAUTH_SECRET!,
+  hmacSecret: process.env.AUTH_SECRET!,
   jwt: {
     privateKey: fs.readFileSync("keys/private.pem", "utf8"),
     publicKey: fs.readFileSync("keys/public.pem", "utf8"),
   },
-  cache: {
-    get: (key) => redis.get(key).then(JSON.parse),
-    set: (key, val, ttl) => redis.setex(key, ttl!, JSON.stringify(val)),
-    delete: (key) => redis.del(key),
-  },
-  auditLogger: {
-    log: (event, data) => prisma.auditLog.create({ data: { event, ...data } }),
-  },
 });
+```
 
-// Auth routes
-app.post("/api/v1/auth/exchange", auth.createExchangeHandler());
-app.post("/api/v1/auth/refresh", auth.createRefreshHandler());
-app.post("/api/v1/auth/logout", auth.createLogoutHandler());
+## High-Level API
 
-// Protected routes
-app.get("/api/v1/profile", auth.createAuthenticateMiddleware(), (req, res) => {
-  res.json({ user: req.user });
+### Token Exchange
+
+Exchange a HMAC-signed proof for JWT tokens:
+
+```typescript
+const tokens = await auth.exchange({
+  userId: user.id,
+  email: user.email,
+  role: user.role,
+  sessionId: crypto.randomUUID(),
+  timestamp: Date.now(),
+  signature: hmacSignature,
 });
 
-app.get("/api/v1/admin", auth.createAuthenticateMiddleware(), auth.createAuthorizeMiddleware("ADMIN"), (req, res) => {
-  res.json({ admin: true });
+// tokens.accessToken, tokens.refreshToken, tokens.sseToken, tokens.sessionId
+```
+
+### Verify Token
+
+Verify an access token and load the user:
+
+```typescript
+const { user, payload } = await auth.verifyToken({
+  token: accessToken,
+  ipAddress: "192.168.1.1",
+  userAgent: "Mozilla/5.0...",
 });
+
+// payload.id, payload.email, payload.role, payload.jti, payload.sessionId
+```
+
+### Refresh Tokens
+
+Rotate refresh tokens atomically:
+
+```typescript
+const newTokens = await auth.refresh({
+  refreshToken: currentRefreshToken,
+});
+
+// newTokens.accessToken, newTokens.refreshToken, newTokens.sseToken
+```
+
+### Logout
+
+```typescript
+// Single session
+await auth.logout({
+  userId: user.id,
+  sessionId: sessionId,
+  accessTokenJti: jti,
+  accessToken: token,
+});
+
+// All sessions
+await auth.logout({
+  userId: user.id,
+  sessionId: sessionId,
+  logoutAll: true,
+});
+```
+
+### Two-Factor Authentication
+
+```typescript
+// Setup — generate secret + URI for QR code
+const { secret, uri } = auth.generateTwoFactor();
+// Display uri as QR code to user, store secret in database
+
+// Verify TOTP code
+const valid = await auth.verifyTwoFactor({ token: "123456", secret });
+```
+
+### Session Management
+
+```typescript
+// List active sessions
+const sessions = await auth.getActiveSessions(userId);
+
+// Revoke a specific session
+await auth.revokeSession(userId, sessionId);
+```
+
+### Account Lockout
+
+```typescript
+// Record failed login attempt
+const result = await auth.recordLoginFailure(email);
+if (result.locked) {
+  console.log(`Account locked until ${result.unlocksAt}`);
+}
+
+// Clear failures on successful login
+await auth.clearLoginFailures(email);
+
+// Check if account is locked
+const status = await auth.isAccountLocked(email);
+```
+
+### Audit Logging
+
+```typescript
+auth.log("WORKSPACE_CREATED", { userId, workspaceId });
+```
+
+## Express Integration
+
+For Express.js applications, use `MiddlewareFactory` for HTTP middleware:
+
+```typescript
+import { MiddlewareFactory } from "@focura/auth-core";
+
+const factory = new MiddlewareFactory(config);
+
+// Auth routes
+app.post("/api/v1/auth/exchange", factory.createExchangeHandler());
+app.post("/api/v1/auth/refresh", factory.createRefreshHandler());
+app.post("/api/v1/auth/logout", factory.createLogoutHandler());
+
+// Protected routes
+app.get("/api/v1/profile",
+  factory.createAuthenticateMiddleware(),
+  (req, res) => { res.json({ user: req.user }); }
+);
+
+// Role-based access
+app.get("/api/v1/admin",
+  factory.createAuthenticateMiddleware(),
+  factory.createAuthorizeMiddleware("ADMIN"),
+  (req, res) => { res.json({ admin: true }); }
+);
 ```
 
 ## Adapters
@@ -79,8 +192,7 @@ Works with ioredis or any compatible client:
 import Redis from "ioredis";
 const redis = new Redis(process.env.REDIS_URL);
 
-// Pass directly — ioredis satisfies the RedisAdapter interface
-const auth = new MiddlewareFactory({ redis, ... });
+const auth = new AuthService({ redis, ... });
 ```
 
 ### UserStore
@@ -133,6 +245,34 @@ openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
 openssl rsa -in private.pem -pubout -out public.pem
 ```
 
+## API Hierarchy
+
+### Primary API (Recommended)
+
+```typescript
+import { AuthService } from "@focura/auth-core";
+```
+
+The `AuthService` class provides high-level, framework-agnostic authentication operations.
+
+### Extension API
+
+Interfaces for integrating your infrastructure:
+
+```typescript
+import type { UserStore, RedisAdapter, CacheAdapter, AuditLogger } from "@focura/auth-core";
+```
+
+### Advanced API
+
+Low-level classes for custom integrations:
+
+```typescript
+import { TokenManager, SessionManager, TotpManager, AccountLockout } from "@focura/auth-core";
+```
+
+These are available but not required for normal application development.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -165,6 +165,54 @@ interface SessionMetadata {
 type AuditEventType = "LOGIN_SUCCESS" | "LOGIN_FAILED" | "LOGIN_BLOCKED" | "LOGOUT" | "LOGOUT_ALL_DEVICES" | "TOKEN_REFRESHED" | "TOKEN_REVOKED" | "TOKEN_EXPIRED" | "TOKEN_VERSION_MISMATCH" | "TOKEN_REPLAY_DETECTED" | "EXCHANGE_SUCCESS" | "EXCHANGE_FAILED" | "SSE_CONNECTED" | "SSE_DISCONNECTED" | "ACCOUNT_LOCKED" | "TOTP_VERIFIED" | "TOTP_FAILED" | "PERMISSION_DENIED" | "EMAIL_NOT_VERIFIED" | "SESSION_BOUND" | "SESSION_REBOUND" | "SESSION_HIJACK_DETECTED" | "SESSION_TIMEOUT" | "SESSION_REVOKED" | "SESSIONS_REVOKED" | "MAX_SESSIONS_REACHED" | "DEVICE_MISMATCH" | "SUSPICIOUS_IP_CHANGE" | "CSRF_VALIDATION_FAILED" | "UNAUTHORIZED_ACCESS" | "RATE_LIMIT_EXCEEDED" | "MALWARE_DETECTED" | "SUSPICIOUS_ACTIVITY" | "DATA_EXPORT" | "DATA_DELETION" | "SENSITIVE_DATA_ACCESS" | "WORKSPACE_CREATED" | "WORKSPACE_DELETED" | "MEMBER_ADDED" | "MEMBER_REMOVED" | "ROLE_CHANGED" | "SUBSCRIPTION_CREATED" | "SUBSCRIPTION_CANCELLED" | "PAYMENT_FAILED";
 type AuditSeverity = "info" | "warn" | "critical";
 
+declare const DEFAULTS: {
+    readonly keyPrefix: "focura:";
+    readonly issuer: "focura-app";
+    readonly audience: "focura-backend";
+    readonly accessTokenExpiry: "15m";
+    readonly refreshTokenExpiry: "7d";
+    readonly sseTokenExpiry: "30s";
+    readonly currentVersion: 1;
+    readonly maxConcurrentSessions: 5;
+    readonly sessionMetadataTtl: number;
+    readonly lockoutMaxFailures: 10;
+    readonly lockoutSeconds: number;
+    readonly lockoutWindowSeconds: number;
+    readonly refreshLockTtlSeconds: 45;
+    readonly refreshDedupeTtlSeconds: 30;
+    readonly revokedSessionTtl: number;
+    readonly inactivityTimeout: number;
+    readonly absoluteTimeout: number;
+};
+declare function resolveConfig(raw: AuthCoreConfig): {
+    keyPrefix: string;
+    issuer: string;
+    audience: string;
+    accessTokenExpiry: string;
+    refreshTokenExpiry: string;
+    sseTokenExpiry: string;
+    currentVersion: number;
+    maxConcurrentSessions: number;
+    sessionMetadataTtl: number;
+    lockoutMaxFailures: number;
+    lockoutSeconds: number;
+    lockoutWindowSeconds: number;
+    inactivityTimeout: number;
+    absoluteTimeout: number;
+    redis: RedisAdapter;
+    userStore: UserStore;
+    hmacSecret: string;
+    jwt: TokenConfig;
+    cache?: CacheAdapter;
+    auditLogger?: AuditLogger;
+    observability?: ObservabilitySink;
+    errors?: ErrorFactory;
+    lockout?: LockoutConfig;
+    session?: SessionConfig;
+};
+type ResolvedConfig = ReturnType<typeof resolveConfig>;
+declare const AUDIT_SEVERITY: Record<AuditEventType, AuditSeverity>;
+
 declare class TokenManager {
     private readonly privateKey;
     private readonly publicKey;
@@ -228,16 +276,6 @@ declare class TokenRevocation {
     isSessionRevoked(sessionId: string): Promise<boolean>;
 }
 
-declare class RefreshLock {
-    private readonly redis;
-    private readonly prefix;
-    constructor(redis: RedisAdapter, prefix?: string);
-    private lockKey;
-    acquire(sessionId: string): Promise<boolean>;
-    release(sessionId: string): Promise<void>;
-    isLocked(sessionId: string): Promise<boolean>;
-}
-
 declare class SessionManager {
     private readonly redis;
     private readonly tokenRevocation;
@@ -261,40 +299,6 @@ declare class SessionManager {
     }>>;
 }
 
-declare function looksLikeServerToServerUA(userAgent: string): boolean;
-declare function looksLikeServerToServerRequest(req: {
-    headers: Record<string, string | string[] | undefined>;
-}): boolean;
-declare function normalizeUserAgent(userAgent: string): string;
-declare function generateDeviceFingerprint(req: {
-    headers: Record<string, string | string[] | undefined>;
-}): string;
-declare function getClientIp(req: {
-    ip?: string;
-    headers: Record<string, string | string[] | undefined>;
-    socket?: {
-        remoteAddress?: string;
-    };
-}): string;
-declare function createSessionMetadata(req: {
-    ip?: string;
-    headers: Record<string, string | string[] | undefined>;
-    socket?: {
-        remoteAddress?: string;
-    };
-}): SessionMetadata;
-declare function isPrivateIp(ip: string): boolean;
-declare function validateSessionBinding(req: {
-    headers: Record<string, string | string[] | undefined>;
-    ip?: string;
-    socket?: {
-        remoteAddress?: string;
-    };
-}, storedMetadata: SessionMetadata): {
-    valid: boolean;
-    reason?: string;
-};
-
 declare class AccountLockout {
     private readonly redis;
     private readonly maxFailures;
@@ -333,6 +337,139 @@ declare class TotpManager {
     verify(token: string, secret: string): Promise<boolean>;
 }
 
+interface ExchangeInput {
+    userId: string;
+    email: string;
+    role: string;
+    sessionId?: string;
+    timestamp: number;
+    signature: string;
+}
+interface ExchangeResult extends TokenPair {
+    sseToken: string;
+    sessionId: string;
+}
+interface VerifyTokenInput {
+    token: string;
+    ipAddress?: string;
+    userAgent?: string;
+}
+interface VerifyTokenResult {
+    user: User;
+    payload: {
+        id: string;
+        email: string;
+        role: string;
+        jti: string;
+        sessionId?: string;
+    };
+}
+interface RefreshInput {
+    refreshToken: string;
+}
+interface RefreshResult extends TokenPair {
+    sseToken: string;
+}
+interface LogoutInput {
+    accessToken?: string;
+    accessTokenJti?: string;
+    userId?: string;
+    sessionId?: string;
+    logoutAll?: boolean;
+}
+interface TwoFactorSetupResult {
+    secret: string;
+    uri: string;
+}
+interface TwoFactorVerifyInput {
+    token: string;
+    secret: string;
+}
+declare class AuthService {
+    readonly tokenManager: TokenManager;
+    readonly tokenRevocation: TokenRevocation;
+    readonly sessionManager: SessionManager;
+    readonly accountLockout: AccountLockout;
+    readonly totpManager: TotpManager;
+    readonly audit: AuditLog;
+    readonly errors: ErrorFactory;
+    private readonly config;
+    private readonly userStore;
+    constructor(rawConfig: AuthCoreConfig);
+    getConfig(): ResolvedConfig;
+    getRedis(): AuthCoreConfig["redis"];
+    exchange(input: ExchangeInput): Promise<ExchangeResult>;
+    verifyToken(input: VerifyTokenInput): Promise<VerifyTokenResult>;
+    refresh(input: RefreshInput): Promise<RefreshResult>;
+    logout(input: LogoutInput): Promise<void>;
+    getActiveSessions(userId: string): Promise<{
+        sessionId: string;
+        deviceInfo: string;
+        ipAddress?: string;
+        lastActivity: string;
+        createdAt: string;
+    }[]>;
+    revokeSession(userId: string, sessionId: string): Promise<void>;
+    generateTwoFactor(): TwoFactorSetupResult;
+    createTwoFactorUri(secret: string, email: string): string;
+    verifyTwoFactor(input: TwoFactorVerifyInput): Promise<boolean>;
+    recordLoginFailure(email: string): Promise<{
+        locked: boolean;
+        unlocksAt?: Date;
+        attempts: number;
+    }>;
+    clearLoginFailures(email: string): Promise<void>;
+    isAccountLocked(email: string): Promise<{
+        locked: boolean;
+        unlocksAt?: Date;
+    }>;
+    log(event: AuditEventType, data: Record<string, unknown>): void;
+}
+
+declare class RefreshLock {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisAdapter, prefix?: string);
+    private lockKey;
+    acquire(sessionId: string): Promise<boolean>;
+    release(sessionId: string): Promise<void>;
+    isLocked(sessionId: string): Promise<boolean>;
+}
+
+declare function looksLikeServerToServerUA(userAgent: string): boolean;
+declare function looksLikeServerToServerRequest(req: {
+    headers: Record<string, string | string[] | undefined>;
+}): boolean;
+declare function normalizeUserAgent(userAgent: string): string;
+declare function generateDeviceFingerprint(req: {
+    headers: Record<string, string | string[] | undefined>;
+}): string;
+declare function getClientIp(req: {
+    ip?: string;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}): string;
+declare function createSessionMetadata(req: {
+    ip?: string;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}): SessionMetadata;
+declare function isPrivateIp(ip: string): boolean;
+declare function validateSessionBinding(req: {
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}, storedMetadata: SessionMetadata): {
+    valid: boolean;
+    reason?: string;
+};
+
 declare class SessionTimeoutManager implements SessionLifecycle {
     private readonly redis;
     private readonly inactivityTimeout;
@@ -352,54 +489,6 @@ declare class SessionTimeoutManager implements SessionLifecycle {
     updateActivity(sessionId: string): Promise<boolean>;
 }
 
-declare const DEFAULTS: {
-    readonly keyPrefix: "focura:";
-    readonly issuer: "focura-app";
-    readonly audience: "focura-backend";
-    readonly accessTokenExpiry: "15m";
-    readonly refreshTokenExpiry: "7d";
-    readonly sseTokenExpiry: "30s";
-    readonly currentVersion: 1;
-    readonly maxConcurrentSessions: 5;
-    readonly sessionMetadataTtl: number;
-    readonly lockoutMaxFailures: 10;
-    readonly lockoutSeconds: number;
-    readonly lockoutWindowSeconds: number;
-    readonly refreshLockTtlSeconds: 45;
-    readonly refreshDedupeTtlSeconds: 30;
-    readonly revokedSessionTtl: number;
-    readonly inactivityTimeout: number;
-    readonly absoluteTimeout: number;
-};
-declare function resolveConfig(raw: AuthCoreConfig): {
-    keyPrefix: string;
-    issuer: string;
-    audience: string;
-    accessTokenExpiry: string;
-    refreshTokenExpiry: string;
-    sseTokenExpiry: string;
-    currentVersion: number;
-    maxConcurrentSessions: number;
-    sessionMetadataTtl: number;
-    lockoutMaxFailures: number;
-    lockoutSeconds: number;
-    lockoutWindowSeconds: number;
-    inactivityTimeout: number;
-    absoluteTimeout: number;
-    redis: RedisAdapter;
-    userStore: UserStore;
-    hmacSecret: string;
-    jwt: TokenConfig;
-    cache?: CacheAdapter;
-    auditLogger?: AuditLogger;
-    observability?: ObservabilitySink;
-    errors?: ErrorFactory;
-    lockout?: LockoutConfig;
-    session?: SessionConfig;
-};
-type ResolvedConfig = ReturnType<typeof resolveConfig>;
-declare const AUDIT_SEVERITY: Record<AuditEventType, AuditSeverity>;
-
 interface AuthRequest {
     user?: {
         id: string;
@@ -590,4 +679,4 @@ declare class ValidationError extends Error {
 
 declare const defaultErrors: ErrorFactory;
 
-export { AUDIT_SEVERITY, AccountBannedError, AccountLockout, type AuditEventType, AuditLog, type AuditLogger, type AuditSeverity, type AuthCoreConfig, type AuthRequest, BadRequestError, type CacheAdapter, DEFAULTS, type DeviceFingerprint, EmailNotVerifiedError, type ErrorFactory, ForbiddenError, InvalidTokenError, type LockoutConfig, MiddlewareFactory, type ObservabilitySink, type RateLimiterFactory, type RedisAdapter, type RedisPipeline, RefreshLock, type ResolvedConfig, type SessionConfig, SessionHijackError, type SessionLifecycle, SessionManager, type SessionMetadata, SessionTimeoutManager, type TokenConfig, TokenExpiredError, TokenManager, type TokenPair, type TokenPayload, TokenRevocation, TokenRevokedError, TotpManager, UnauthorizedError, type User, type UserStore, ValidationError, type ZodSchema, createSessionMetadata, defaultErrors, exchangeSchema, generateDeviceFingerprint, getClientIp, isPrivateIp, logoutSchema, looksLikeServerToServerRequest, looksLikeServerToServerUA, normalizeUserAgent, refreshSchema, resolveConfig, validateSessionBinding };
+export { AUDIT_SEVERITY, AccountBannedError, AccountLockout, type AuditEventType, AuditLog, type AuditLogger, type AuditSeverity, type AuthCoreConfig, type RefreshResult as AuthRefreshResult, type AuthRequest, AuthService, BadRequestError, type CacheAdapter, DEFAULTS, type DeviceFingerprint, EmailNotVerifiedError, type ErrorFactory, type ExchangeInput, type ExchangeResult, ForbiddenError, InvalidTokenError, type LockoutConfig, type LogoutInput, MiddlewareFactory, type ObservabilitySink, type RateLimiterFactory, type RedisAdapter, type RedisPipeline, type RefreshInput, RefreshLock, type ResolvedConfig, type SessionConfig, SessionHijackError, type SessionLifecycle, SessionManager, type SessionMetadata, SessionTimeoutManager, type TokenConfig, TokenExpiredError, TokenManager, type TokenPair, type TokenPayload, TokenRevocation, TokenRevokedError, TotpManager, type TwoFactorSetupResult, type TwoFactorVerifyInput, UnauthorizedError, type User, type UserStore, ValidationError, type VerifyTokenInput, type VerifyTokenResult, type ZodSchema, createSessionMetadata, defaultErrors, exchangeSchema, generateDeviceFingerprint, getClientIp, isPrivateIp, logoutSchema, looksLikeServerToServerRequest, looksLikeServerToServerUA, normalizeUserAgent, refreshSchema, resolveConfig, validateSessionBinding };