@rebasepro/server-core 0.0.1-canary.09e5ec5

package/src/auth/interfaces.ts

@@ -0,0 +1,363 @@
+import { z } from "zod";
+
+/**
+ * Authentication Abstraction Interfaces
+ *
+ * These interfaces define the contracts for authentication-related operations.
+ * Implementations can use different databases (PostgreSQL, MongoDB, etc.) to
+ * store user, role, and token data.
+ */
+
+/**
+ * User data structure
+ */
+export interface UserData {
+    id: string;
+    email: string;
+    passwordHash?: string | null;
+    displayName?: string | null;
+    photoUrl?: string | null;
+    emailVerified: boolean;
+    emailVerificationToken?: string | null;
+    emailVerificationSentAt?: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * Data for creating a new user
+ */
+export interface CreateUserData {
+    email: string;
+    passwordHash?: string;
+    displayName?: string;
+    photoUrl?: string;
+    emailVerified?: boolean;
+}
+
+/**
+ * User Identity Data (OAuth accounts linked to user)
+ */
+export interface UserIdentityData {
+    id: string;
+    userId: string;
+    provider: string;
+    providerId: string;
+    profileData?: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * Standardized profile data returned by an OAuth provider verification payload
+ */
+export interface OAuthProviderProfile {
+    providerId: string;
+    email: string;
+    displayName?: string | null;
+    photoUrl?: string | null;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Role data structure
+ */
+export interface RoleData {
+    id: string;
+    name: string;
+    isAdmin: boolean;
+    defaultPermissions: {
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    } | null;
+    collectionPermissions: Record<string, {
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    }> | null;
+    config: Record<string, unknown> | null;
+}
+
+/**
+ * Data for creating a new role
+ */
+export interface CreateRoleData {
+    id: string;
+    name: string;
+    isAdmin?: boolean;
+    defaultPermissions?: RoleData["defaultPermissions"];
+    collectionPermissions?: RoleData["collectionPermissions"];
+    config?: RoleData["config"];
+}
+
+/**
+ * Refresh token info
+ */
+export interface RefreshTokenInfo {
+    id: string;
+    userId: string;
+    tokenHash: string;
+    expiresAt: Date;
+    createdAt: Date;
+    userAgent?: string | null;
+    ipAddress?: string | null;
+}
+
+/**
+ * Password reset token info
+ */
+export interface PasswordResetTokenInfo {
+    userId: string;
+    expiresAt: Date;
+}
+
+// =============================================================================
+// AUTH REPOSITORY INTERFACES
+// =============================================================================
+
+/**
+ * Options for paginated user listing
+ */
+export interface ListUsersOptions {
+    /** Max results per page (default 25) */
+    limit?: number;
+    /** Number of results to skip (default 0) */
+    offset?: number;
+    /** Search term — matches against email and displayName (case-insensitive) */
+    search?: string;
+    /** Field to sort by (default "createdAt") */
+    orderBy?: string;
+    /** Sort direction (default "desc") */
+    orderDir?: "asc" | "desc";
+    /** Filter by role ID */
+    roleId?: string;
+}
+
+/**
+ * Result of a paginated user listing
+ */
+export interface PaginatedUsersResult {
+    users: UserData[];
+    /** Total number of users matching the filters (ignoring limit/offset) */
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Abstract user repository interface.
+ * Handles all user-related database operations.
+ */
+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>;
+}
+
+/**
+ * Abstract role repository interface.
+ * Handles all role-related database operations.
+ */
+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>;
+}
+
+/**
+ * Combined auth repository interface for convenience
+ */
+export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository { }

package/src/auth/jwt.ts

@@ -0,0 +1,181 @@
+import jwt from "jsonwebtoken";
+import { createHash, randomBytes } from "crypto";
+
+export interface JwtConfig {
+    secret: string;
+    accessExpiresIn?: string;
+    refreshExpiresIn?: string;
+}
+
+export interface AccessTokenPayload {
+    userId: string;
+    roles: string[];
+    uid?: string;
+}
+
+let jwtConfig: JwtConfig = {
+    secret: "",
+    accessExpiresIn: "1h",
+    refreshExpiresIn: "30d"
+};
+
+/**
+ * Configure JWT settings - call this during initialization.
+ * Validates the secret strength to prevent deployment with default/weak secrets.
+ */
+export function configureJwt(config: JwtConfig): void {
+    // Reject obviously weak/default secrets
+    const weakSecrets = new Set([
+        "secret",
+        "jwt-secret",
+        "jwt_secret",
+        "your-secret",
+        "your-super-secret-jwt-key-change-in-production",
+        "super-secret-jwt-key-change-in-production",
+        "change-me",
+        "changeme",
+        "password",
+        "test",
+        "mysecret",
+        "my-secret",
+        "my_secret",
+        "example-secret",
+        "please-change-me",
+        "replace-this-with-a-real-secret",
+        "default-secret"
+    ]);
+
+    if (!config.secret || config.secret.length < 32) {
+        throw new Error(
+            "JWT secret is too short. Must be at least 32 characters. " +
+            "Generate one with: node -e \"console.log(require('crypto').randomBytes(48).toString('base64'))\""
+        );
+    }
+
+    if (weakSecrets.has(config.secret.toLowerCase())) {
+        throw new Error(
+            "JWT secret is a known default/weak value. Please use a strong, randomly generated secret. " +
+            "Generate one with: node -e \"console.log(require('crypto').randomBytes(48).toString('base64'))\""
+        );
+    }
+
+    jwtConfig = {
+        ...jwtConfig,
+        ...config
+    };
+}
+
+/**
+ * Generate an access token (short-lived, 1 hour by default)
+ */
+export function generateAccessToken(userId: string, roles: string[]): string {
+    if (!jwtConfig.secret) {
+        throw new Error("JWT secret not configured. Call configureJwt() first.");
+    }
+
+    const payload: AccessTokenPayload = { userId,
+roles };
+
+    return jwt.sign(payload, jwtConfig.secret, {
+        expiresIn: jwtConfig.accessExpiresIn as jwt.SignOptions["expiresIn"],
+        algorithm: "HS256"
+    });
+}
+
+/**
+ * Get the expiration time of an access token in milliseconds from now
+ */
+export function getAccessTokenExpiryMs(): number {
+    const duration = jwtConfig.accessExpiresIn || "1h";
+    const match = duration.match(/^(\d+)([dhms])$/);
+
+    if (!match) {
+        // Default to 1 hour
+        return 60 * 60 * 1000;
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    switch (unit) {
+        case "d": return value * 24 * 60 * 60 * 1000;
+        case "h": return value * 60 * 60 * 1000;
+        case "m": return value * 60 * 1000;
+        case "s": return value * 1000;
+        default: return 60 * 60 * 1000;
+    }
+}
+
+/**
+ * Get the expiration timestamp for an access token
+ */
+export function getAccessTokenExpiry(): number {
+    return Date.now() + getAccessTokenExpiryMs();
+}
+
+/**
+ * Verify and decode an access token
+ */
+export function verifyAccessToken(token: string): AccessTokenPayload | null {
+    if (!jwtConfig.secret) {
+        throw new Error("JWT secret not configured. Call configureJwt() first.");
+    }
+
+    try {
+        const decoded = jwt.verify(token, jwtConfig.secret, { algorithms: ["HS256"] }) as { userId?: string; uid?: string; sub?: string; roles?: string[] };
+        const id = decoded.userId || decoded.uid || decoded.sub;
+        if (!id) {
+            console.error("[JWT] Verification failed: missing id in payload", decoded);
+            return null;
+        }
+
+        return {
+            userId: id,
+            roles: decoded.roles || []
+        };
+    } catch (error) {
+        console.error("[JWT] Verification failed:", error, "Token start:", token.substring(0, 15));
+        return null;
+    }
+}
+
+/**
+ * Generate a random refresh token (long-lived, 30 days by default)
+ */
+export function generateRefreshToken(): string {
+    return randomBytes(40).toString("hex");
+}
+
+/**
+ * Hash a refresh token for database storage (don't store raw tokens)
+ */
+export function hashRefreshToken(token: string): string {
+    return createHash("sha256").update(token).digest("hex");
+}
+
+/**
+ * Calculate refresh token expiration date
+ */
+export function getRefreshTokenExpiry(): Date {
+    const duration = jwtConfig.refreshExpiresIn || "30d";
+    const match = duration.match(/^(\d+)([dhms])$/);
+
+    if (!match) {
+        // Default to 30 days
+        return new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    let ms: number;
+    switch (unit) {
+        case "d": ms = value * 24 * 60 * 60 * 1000; break;
+        case "h": ms = value * 60 * 60 * 1000; break;
+        case "m": ms = value * 60 * 1000; break;
+        case "s": ms = value * 1000; break;
+        default: ms = 30 * 24 * 60 * 60 * 1000;
+    }
+
+    return new Date(Date.now() + ms);
+}

package/src/auth/linkedin-oauth.ts

@@ -0,0 +1,81 @@
+import type { OAuthProvider, OAuthProviderProfile } from "./interfaces";
+import { z } from "zod";
+
+export interface LinkedinUserInfo {
+    linkedinId: string;
+    email: string;
+    displayName: string | null;
+    photoUrl: string | null;
+    emailVerified: boolean;
+}
+
+/**
+ * Creates a LinkedIn OAuth Provider integration
+ */
+export function createLinkedinProvider(config: { clientId: string, clientSecret: string }): OAuthProvider<{ code: string; redirectUri: string }> {
+    return {
+        id: "linkedin",
+        schema: z.object({
+            code: z.string().min(1, "Auth code is required"),
+            redirectUri: z.string().url("Valid redirect URI is required")
+        }),
+        verify: async (payload: { code: string; redirectUri: string }): Promise<OAuthProviderProfile | null> => {
+            try {
+                // Exchange code for access token
+                const tokenResponse = await fetch("https://www.linkedin.com/oauth/v2/accessToken", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/x-www-form-urlencoded"
+                    },
+                    body: new URLSearchParams({
+                        grant_type: "authorization_code",
+                        code: payload.code,
+                        redirect_uri: payload.redirectUri,
+                        client_id: config.clientId,
+                        client_secret: config.clientSecret
+                    })
+                });
+
+                if (!tokenResponse.ok) {
+                    const errBody = await tokenResponse.text();
+                    console.error("Failed to get LinkedIn access token:", errBody);
+                    return null;
+                }
+
+                const tokenData = await tokenResponse.json() as { access_token: string; id_token?: string };
+                const accessToken = tokenData.access_token;
+
+                // Fetch User Info using OIDC userinfo endpoint
+                const profileResponse = await fetch("https://api.linkedin.com/v2/userinfo", {
+                    headers: {
+                        "Authorization": `Bearer ${accessToken}`
+                    }
+                });
+
+                if (!profileResponse.ok) {
+                    const errBody = await profileResponse.text();
+                    console.error("Failed to get LinkedIn user info:", errBody);
+                    return null;
+                }
+
+                const profileData = await profileResponse.json() as {
+                    sub: string;
+                    email: string;
+                    name?: string;
+                    picture?: string;
+                    email_verified?: boolean;
+                };
+
+                return {
+                    providerId: profileData.sub,
+                    email: profileData.email,
+                    displayName: profileData.name || null,
+                    photoUrl: profileData.picture || null
+                };
+            } catch (error) {
+                console.error("LinkedIn OAuth error:", error);
+                return null;
+            }
+        }
+    };
+}

package/src/auth/microsoft-oauth.ts

@@ -0,0 +1,88 @@
+import type { OAuthProvider, OAuthProviderProfile } from "./interfaces";
+import { z } from "zod";
+
+/**
+ * Creates a Microsoft / Entra ID (Azure AD) OAuth Provider integration.
+ *
+ * Supports both personal Microsoft accounts and work/school (Azure AD) accounts
+ * via the "common" tenant endpoint. Uses the authorization code flow.
+ */
+export function createMicrosoftProvider(config: {
+    clientId: string;
+    clientSecret: string;
+    /** Tenant ID. Defaults to "common" which allows both personal and organizational accounts. */
+    tenantId?: string;
+}): OAuthProvider<{ code: string; redirectUri: string }> {
+    const tenantId = config.tenantId || "common";
+
+    return {
+        id: "microsoft",
+        schema: z.object({
+            code: z.string().min(1, "Auth code is required"),
+            redirectUri: z.string().url("Valid redirect URI is required")
+        }),
+        verify: async (payload: { code: string; redirectUri: string }): Promise<OAuthProviderProfile | null> => {
+            try {
+                // Exchange code for access token
+                const tokenResponse = await fetch(
+                    `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`,
+                    {
+                        method: "POST",
+                        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                        body: new URLSearchParams({
+                            client_id: config.clientId,
+                            client_secret: config.clientSecret,
+                            code: payload.code,
+                            redirect_uri: payload.redirectUri,
+                            grant_type: "authorization_code",
+                            scope: "openid profile email User.Read"
+                        })
+                    }
+                );
+
+                if (!tokenResponse.ok) {
+                    console.error("Failed to get Microsoft access token:", await tokenResponse.text());
+                    return null;
+                }
+
+                const tokenData = await tokenResponse.json() as { access_token: string };
+                const accessToken = tokenData.access_token;
+
+                // Fetch user profile from Microsoft Graph
+                const profileResponse = await fetch("https://graph.microsoft.com/v1.0/me", {
+                    headers: { "Authorization": `Bearer ${accessToken}` }
+                });
+
+                if (!profileResponse.ok) {
+                    console.error("Failed to get Microsoft user info:", await profileResponse.text());
+                    return null;
+                }
+
+                const profileData = await profileResponse.json() as {
+                    id: string;
+                    displayName?: string | null;
+                    mail?: string | null;
+                    userPrincipalName?: string | null;
+                };
+
+                const email = profileData.mail || profileData.userPrincipalName;
+                if (!email) {
+                    console.error("Microsoft user has no email");
+                    return null;
+                }
+
+                // Attempt to fetch profile photo URL (Graph returns binary, not a URL).
+                // We skip this and let the frontend use the Microsoft Graph photo endpoint.
+                return {
+                    providerId: profileData.id,
+                    email,
+                    displayName: profileData.displayName || null,
+                    photoUrl: null
+                };
+            } catch (error) {
+                console.error("Microsoft OAuth error:", error);
+                return null;
+            }
+        }
+    };
+}