@rebasepro/server-core 0.7.0 → 0.9.0

package/{src/auth/index.ts → dist/auth/index.d.ts}

@@ -1,19 +1,12 @@
-// Auth module exports
 export * from "./interfaces";
-
-export { configureJwt, generateAccessToken, verifyAccessToken, generateRefreshToken, hashRefreshToken, getRefreshTokenExpiry, getAccessTokenExpiry } from "./jwt";
-export type { JwtConfig, AccessTokenPayload } from "./jwt";
-
+export { configureJwt, generateAccessToken, verifyAccessToken, generateRefreshToken, hashRefreshToken, getRefreshTokenExpiry, getAccessTokenExpiry, generateDownloadToken, verifyDownloadToken } from "./jwt";
+export type { JwtConfig, AccessTokenPayload, DownloadTokenPayload } from "./jwt";
 export { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
 export type { PasswordValidationResult } from "./password";
-
 export type { AuthHooks, AuthMethod, ResolvedAuthHooks } from "./auth-hooks";
 export { resolveAuthHooks } from "./auth-hooks";
-
 export { generateSecurePassword, generateSecureToken, hashToken, prepareAdminUserValues, finalizeAdminUserCreation } from "./admin-user-ops";
 export type { AdminUserContext, AdminUserPrepareResult } from "./admin-user-ops";
-
-// OAuth Providers
 export { createGoogleProvider } from "./google-oauth";
 export type { GoogleProviderConfig } from "./google-oauth";
 export { createLinkedinProvider } from "./linkedin-oauth";
@@ -27,27 +20,16 @@ export { createGitLabProvider } from "./gitlab-oauth";
 export { createBitbucketProvider } from "./bitbucket-oauth";
 export { createSlackProvider } from "./slack-oauth";
 export { createSpotifyProvider } from "./spotify-oauth";
-
-export { requireAuth, requireAdmin, optionalAuth, extractUserFromToken, createAuthMiddleware } from "./middleware";
+export { requireAuth, requireAdmin, optionalAuth, extractUserFromToken, createAuthMiddleware, queryTokenAuth, fileTokenAuth } from "./middleware";
 export type { AuthMiddlewareOptions, AuthResult } from "./middleware";
-
-
 export { createAuthRoutes } from "./routes";
-export type { AuthModuleConfig } from "./routes";
-
+export type { AuthModuleConfig, CookieAuthConfig } from "./routes";
 export { mountMagicLinkRoutes } from "./magic-link-routes";
-
 export { createResetPasswordRoute } from "./reset-password-admin";
 export type { ResetPasswordRouteConfig } from "./reset-password-admin";
-
-
 export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter, createApiKeyRateLimiter, apiKeyKeyGenerator } from "./rate-limiter";
-
-// API Keys
 export { createApiKeyStore, createApiKeyRoutes, isApiKeyToken, validateApiKey, httpMethodToOperation, isOperationAllowed } from "./api-keys";
 export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, ApiKeyStore, ApiKeyOperation } from "./api-keys";
-
-// Auth Adapters
 export { createBuiltinAuthAdapter } from "./builtin-auth-adapter";
 export type { BuiltinAuthAdapterConfig } from "./builtin-auth-adapter";
 export { createCustomAuthAdapter } from "./custom-auth-adapter";

package/{src/auth/interfaces.ts → dist/auth/interfaces.d.ts}

@@ -1,5 +1,4 @@
 import { z } from "zod";
-
 /**
  * Authentication Abstraction Interfaces
  *
@@ -7,7 +6,6 @@ import { z } from "zod";
  * Implementations can use different databases (PostgreSQL, MongoDB, etc.) to
  * store user, role, and token data.
  */
-
 /**
  * User data structure
  */
@@ -25,7 +23,6 @@ export interface UserData {
     createdAt: Date;
     updatedAt: Date;
 }
-
 /**
  * Data for creating a new user
  */
@@ -38,7 +35,6 @@ export interface CreateUserData {
     isAnonymous?: boolean;
     metadata?: Record<string, unknown>;
 }
-
 /**
  * User Identity Data (OAuth accounts linked to user)
  */
@@ -51,7 +47,6 @@ export interface UserIdentityData {
     createdAt: Date;
     updatedAt: Date;
 }
-
 /**
  * Standardized profile data returned by an OAuth provider verification payload
  */
@@ -63,21 +58,26 @@ export interface OAuthProviderProfile {
     /** Whether the OAuth provider has verified the user's email address */
     emailVerified?: boolean;
 }
-
 /**
  * Pluggable OAuth Provider integration strategy
  */
 export interface OAuthProvider<T = unknown> {
     /** The identifier of the provider (e.g. "github", "google") */
     id: string;
-
     /** Zod schema validating the expected request payload (e.g. { code: string }) */
     schema: z.ZodSchema<T>;
-
-    /** Verify external tokens/codes and return a standardized user profile */
-    verify: (payload: T) => Promise<OAuthProviderProfile | null>;
+    /**
+     * Verify external tokens/codes and return a standardized user profile.
+     *
+     * NOTE: Declared as method syntax (not arrow property) intentionally.
+     * This makes `OAuthProvider` bivariant in `T`, which is correct because
+     * each provider is self-contained — `schema` validates the request body
+     * and `verify` consumes the same `T`. Bivariance lets heterogeneous
+     * providers (`OAuthProvider<SpecificPayload>`) coexist in a single
+     * `OAuthProvider<unknown>[]` array without resorting to `any`.
+     */
+    verify(payload: T): Promise<OAuthProviderProfile | null>;
 }
-
 /**
  * Role data structure
  */
@@ -98,7 +98,6 @@ export interface RoleData {
         delete?: boolean;
     }> | null;
 }
-
 /**
  * Data for creating a new role
  */
@@ -109,7 +108,6 @@ export interface CreateRoleData {
     defaultPermissions?: RoleData["defaultPermissions"];
     collectionPermissions?: RoleData["collectionPermissions"];
 }
-
 /**
  * Refresh token info
  */
@@ -122,7 +120,6 @@ export interface RefreshTokenInfo {
     userAgent?: string | null;
     ipAddress?: string | null;
 }
-
 /**
  * Password reset token info
  */
@@ -130,7 +127,6 @@ export interface PasswordResetTokenInfo {
     userId: string;
     expiresAt: Date;
 }
-
 /**
  * Magic link token info
  */
@@ -138,11 +134,6 @@ export interface MagicLinkTokenInfo {
     userId: string;
     expiresAt: Date;
 }
-
-// =============================================================================
-// AUTH REPOSITORY INTERFACES
-// =============================================================================
-
 /**
  * Options for paginated user listing
  */
@@ -160,7 +151,6 @@ export interface ListUsersOptions {
     /** Filter by role ID */
     roleId?: string;
 }
-
 /**
  * Result of a paginated user listing
  */
@@ -171,7 +161,6 @@ export interface PaginatedUsersResult {
     limit: number;
     offset: number;
 }
-
 /**
  * Abstract user repository interface.
  * Handles all user-related database operations.
@@ -181,98 +170,82 @@ export interface UserRepository {
      * Create a new user
      */
     createUser(data: CreateUserData): Promise<UserData>;
-
     /**
      * Get a user by ID
      */
     getUserById(id: string): Promise<UserData | null>;
-
     /**
      * Get a user by email
      */
     getUserByEmail(email: string): Promise<UserData | null>;
-
     /**
      * Get a user by an OAuth identity
      */
     getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
-
     /**
      * Get all identities linked to a user
      */
     getUserIdentities(userId: string): Promise<UserIdentityData[]>;
-
     /**
      * Link a new OAuth identity to a user
      */
     linkUserIdentity(userId: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
-
     /**
      * Update a user
      */
     updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
-
     /**
      * Delete a user
      */
     deleteUser(id: string): Promise<void>;
-
     /**
      * List all users (unbounded — use listUsersPaginated for large datasets)
      */
     listUsers(): Promise<UserData[]>;
-
     /**
      * List users with server-side pagination, search, and sorting.
      */
     listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
-
     /**
      * Update user's password hash
      */
     updatePassword(id: string, passwordHash: string): Promise<void>;
-
     /**
      * Set email verification status
      */
     setEmailVerified(id: string, verified: boolean): Promise<void>;
-
     /**
      * Set email verification token
      */
     setVerificationToken(id: string, token: string | null): Promise<void>;
-
     /**
      * Find user by email verification token
      */
     getUserByVerificationToken(token: string): Promise<UserData | null>;
-
     /**
      * Get roles for a user
      */
     getUserRoles(userId: string): Promise<RoleData[]>;
-
     /**
      * Get role IDs for a user
      */
     getUserRoleIds(userId: string): Promise<string[]>;
-
     /**
      * Set roles for a user (replaces existing roles)
      */
     setUserRoles(userId: string, roleIds: string[]): Promise<void>;
-
     /**
      * Assign a specific role to a new user
      */
     assignDefaultRole(userId: string, roleId: string): Promise<void>;
-
     /**
      * Get user with their roles
      */
-    getUserWithRoles(userId: string): Promise<{ user: UserData; roles: RoleData[] } | null>;
+    getUserWithRoles(userId: string): Promise<{
+        user: UserData;
+        roles: RoleData[];
+    } | null>;
 }
-
 /**
  * Abstract role repository interface.
  * Handles all role-related database operations.
@@ -282,114 +255,85 @@ export interface RoleRepository {
      * Get a role by ID
      */
     getRoleById(id: string): Promise<RoleData | null>;
-
     /**
      * List all roles
      */
     listRoles(): Promise<RoleData[]>;
-
     /**
      * Create a new role
      */
     createRole(data: CreateRoleData): Promise<RoleData>;
-
     /**
      * Update a role
      */
     updateRole(id: string, data: Partial<Omit<RoleData, "id">>): Promise<RoleData | null>;
-
     /**
      * Delete a role
      */
     deleteRole(id: string): Promise<void>;
 }
-
 /**
  * Abstract token repository interface.
  * Handles refresh tokens and password reset tokens.
  */
 export interface TokenRepository {
-    // Refresh tokens
-
     /**
      * Create a new refresh token
      */
     createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
-
     /**
      * Find a refresh token by hash
      */
     findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
-
     /**
      * Delete a refresh token by hash
      */
     deleteRefreshToken(tokenHash: string): Promise<void>;
-
     /**
      * Delete all refresh tokens for a user
      */
     deleteAllRefreshTokensForUser(userId: string): Promise<void>;
-
     /**
      * List all refresh tokens for a user
      */
     listRefreshTokensForUser(userId: string): Promise<RefreshTokenInfo[]>;
-
     /**
      * Delete a specific refresh token by its primary key ID
      */
     deleteRefreshTokenById(id: string, userId: string): Promise<void>;
-
-    // Password reset tokens
-
     /**
      * Create a password reset token
      */
     createPasswordResetToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
-
     /**
      * Find a valid (not expired, not used) password reset token by hash
      */
     findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
-
     /**
      * Mark a password reset token as used
      */
     markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
-
     /**
      * Delete all password reset tokens for a user
      */
     deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
-
     /**
      * Clean up expired tokens
      */
     deleteExpiredTokens(): Promise<void>;
-
-    // Magic link tokens
-
     /**
      * Create a magic link token
      */
     createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
-
     /**
      * Find a valid (not expired, not used) magic link token by hash
      */
     findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
-
     /**
      * Mark a magic link token as used
      */
     markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
 }
-
-// =============================================================================
-// MFA INTERFACES
-// =============================================================================
-
 /**
  * MFA factor data structure
  */
@@ -402,7 +346,6 @@ export interface MfaFactor {
     createdAt: Date;
     updatedAt: Date;
 }
-
 /**
  * MFA challenge information
  */
@@ -413,7 +356,6 @@ export interface MfaChallengeInfo {
     verifiedAt?: Date;
     ipAddress?: string;
 }
-
 /**
  * Recovery code data structure
  */
@@ -422,7 +364,6 @@ export interface RecoveryCode {
     userId: string;
     usedAt?: Date;
 }
-
 /**
  * Abstract MFA repository interface.
  * Handles all MFA-related database operations.
@@ -432,69 +373,59 @@ export interface MfaRepository {
      * Create a new MFA factor for a user
      */
     createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
-
     /**
      * Get all MFA factors for a user
      */
     getMfaFactors(userId: string): Promise<MfaFactor[]>;
-
     /**
      * Get a specific MFA factor by ID
      */
-    getMfaFactorById(factorId: string): Promise<(MfaFactor & { secretEncrypted: string }) | null>;
-
+    getMfaFactorById(factorId: string): Promise<(MfaFactor & {
+        secretEncrypted: string;
+    }) | null>;
     /**
      * Mark an MFA factor as verified
      */
     verifyMfaFactor(factorId: string): Promise<void>;
-
     /**
      * Delete an MFA factor
      */
     deleteMfaFactor(factorId: string, userId: string): Promise<void>;
-
     /**
      * Create an MFA challenge
      */
     createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
-
     /**
      * Get an MFA challenge by ID
      */
     getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
-
     /**
      * Mark an MFA challenge as verified
      */
     verifyMfaChallenge(challengeId: string): Promise<void>;
-
     /**
      * Create recovery codes for a user
      */
     createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
-
     /**
      * Use a recovery code (mark as used)
      */
     useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
-
     /**
      * Get unused recovery code count for a user
      */
     getUnusedRecoveryCodeCount(userId: string): Promise<number>;
-
     /**
      * Delete all recovery codes for a user
      */
     deleteAllRecoveryCodes(userId: string): Promise<void>;
-
     /**
      * Check if a user has any verified MFA factors
      */
     hasVerifiedMfaFactors(userId: string): Promise<boolean>;
 }
-
 /**
  * Combined auth repository interface for convenience
  */
-export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository, MfaRepository { }
+export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository, MfaRepository {
+}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,67 @@
+export interface JwtConfig {
+    secret: string;
+    accessExpiresIn?: string;
+    refreshExpiresIn?: string;
+}
+export interface AccessTokenPayload {
+    userId: string;
+    roles: string[];
+    uid?: string;
+    /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
+    aal?: "aal1" | "aal2";
+    /** Email claim from the JWT, if present */
+    email?: string;
+    /** Display name claim from the JWT, if present */
+    displayName?: string;
+    /** Photo URL claim from the JWT, if present */
+    photoURL?: string;
+    /** Whether MFA has been verified for this session */
+    mfa_verified?: boolean;
+    /** Authentication Methods Reference — list of methods used (e.g. 'pwd', 'otp') */
+    amr?: string[];
+}
+/**
+ * Configure JWT settings - call this during initialization.
+ * Validates the secret strength to prevent deployment with default/weak secrets.
+ */
+export declare function configureJwt(config: JwtConfig): void;
+/**
+ * Generate an access token (short-lived, 1 hour by default)
+ */
+export declare function generateAccessToken(userId: string, roles: string[], aal?: "aal1" | "aal2", customClaims?: Record<string, unknown>): string;
+/**
+ * Get the expiration time of an access token in milliseconds from now
+ */
+export declare function getAccessTokenExpiryMs(): number;
+/**
+ * Get the expiration timestamp for an access token
+ */
+export declare function getAccessTokenExpiry(): number;
+/**
+ * Verify and decode an access token
+ */
+export declare function verifyAccessToken(token: string): AccessTokenPayload | null;
+/**
+ * Generate a random refresh token (long-lived, 30 days by default)
+ */
+export declare function generateRefreshToken(): string;
+/**
+ * Hash a refresh token for database storage (don't store raw tokens)
+ */
+export declare function hashRefreshToken(token: string): string;
+/**
+ * Calculate refresh token expiration date
+ */
+export declare function getRefreshTokenExpiry(): Date;
+export interface DownloadTokenPayload {
+    purpose: "file-read";
+    path: string;
+}
+/**
+ * Generate a short-lived download token scoped to a specific file path or prefix
+ */
+export declare function generateDownloadToken(path: string, expiresInSeconds?: number): string;
+/**
+ * Verify and decode a download token
+ */
+export declare function verifyDownloadToken(token: string): DownloadTokenPayload | null;

package/dist/auth/linkedin-oauth.d.ts

@@ -0,0 +1,18 @@
+import type { OAuthProvider } from "./interfaces";
+export interface LinkedinUserInfo {
+    linkedinId: string;
+    email: string;
+    displayName: string | null;
+    photoUrl: string | null;
+    emailVerified: boolean;
+}
+/**
+ * Creates a LinkedIn OAuth Provider integration
+ */
+export declare function createLinkedinProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/magic-link-routes.d.ts

@@ -0,0 +1,32 @@
+import { Hono } from "hono";
+import type { AuthModuleConfig } from "./routes";
+import type { ResolvedAuthHooks } from "./auth-hooks";
+import type { HonoEnv } from "../api/types";
+import { z } from "zod";
+import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
+/**
+ * Mount magic link routes onto the auth router.
+ *
+ * Follows the same delegation pattern as `mountMfaRoutes()` and `mountSessionRoutes()`.
+ */
+export declare function mountMagicLinkRoutes(deps: {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ResolvedAuthHooks;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    buildAuthResponse: (user: {
+        id: string;
+        email: string;
+        displayName?: string | null;
+        photoUrl?: string | null;
+        emailVerified?: boolean;
+        isAnonymous?: boolean;
+        metadata?: Record<string, unknown> | null;
+    }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
+    createSessionAndTokens: (userId: string, userAgent: string, ipAddress: string) => Promise<{
+        roleIds: string[];
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, userId: string) => Promise<AuthResponsePayload>;
+}): void;

package/dist/auth/mfa-crypto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Envelope encryption for TOTP secrets using AES-256-GCM.
+ *
+ * - Derives a 32-byte key via SHA-256 from `MFA_ENCRYPTION_KEY` or `JWT_SECRET`.
+ * - Generates a random 12-byte IV per encryption call.
+ * - Returns ciphertexts in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ *
+ * @module
+ */
+/**
+ * Encrypt a plaintext TOTP secret.
+ *
+ * @param plaintext - The Base32 TOTP secret to encrypt.
+ * @returns A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ */
+export declare function encryptTotpSecret(plaintext: string): string;
+/**
+ * Decrypt a previously encrypted TOTP secret.
+ *
+ * @param ciphertext - A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ * @returns The original Base32 TOTP secret.
+ */
+export declare function decryptTotpSecret(ciphertext: string): string;

package/dist/auth/mfa-routes.d.ts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { HonoEnv } from "../api/types";
+import type { AuthModuleConfig } from "./routes";
+import { resolveAuthHooks } from "./auth-hooks";
+import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
+export declare function mountMfaRoutes(router: Hono<HonoEnv>, config: AuthModuleConfig, ops: ReturnType<typeof resolveAuthHooks>, parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T, applyTransformHook?: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, userId: string) => Promise<AuthResponsePayload>): void;

package/dist/auth/mfa.d.ts

@@ -0,0 +1,49 @@
+/**
+ * TOTP (Time-based One-Time Password) implementation.
+ *
+ * Pure Node.js crypto implementation — no external dependencies required.
+ * Implements RFC 6238 (TOTP) and RFC 4226 (HOTP).
+ */
+/**
+ * Encode a Buffer to Base32 string (RFC 4648)
+ */
+export declare function base32Encode(buffer: Buffer): string;
+/**
+ * Decode a Base32 string to Buffer
+ */
+export declare function base32Decode(encoded: string): Buffer;
+/**
+ * Generate a TOTP value for the current time step
+ */
+export declare function generateTotp(secret: Buffer, timeStep?: number): string;
+/**
+ * Verify a TOTP token with a configurable time window
+ *
+ * @param secret - The shared secret as a Buffer
+ * @param token - The 6-digit TOTP code to verify
+ * @param window - Number of time steps to check on each side (default: 1)
+ * @returns true if the token is valid within the window
+ */
+export declare function verifyTotp(secret: Buffer, token: string, window?: number): boolean;
+/**
+ * Generate a new TOTP secret and return the setup information
+ *
+ * @param issuer - The issuer name (app name) for the QR code
+ * @param accountName - The account identifier (usually email)
+ * @returns Object with base32 secret and otpauth URI
+ */
+export declare function generateTotpSecret(issuer: string, accountName: string): {
+    secret: string;
+    uri: string;
+};
+/**
+ * Generate a set of one-time recovery codes
+ *
+ * @param count - Number of recovery codes to generate (default: 10)
+ * @returns Array of formatted recovery code strings (e.g. "A1B2C-D3E4F")
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+/**
+ * Hash a recovery code for storage
+ */
+export declare function hashRecoveryCode(code: string): string;