@rebasepro/server-core 0.0.1-canary.4d4fb3e

package/src/auth/interfaces.ts

@@ -0,0 +1,316 @@
+/**
+ * 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;
+    provider: string;
+    googleId?: 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;
+    provider?: string;
+    googleId?: string;
+    emailVerified?: boolean;
+}
+
+/**
+ * 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";
+}
+
+/**
+ * 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 Google ID
+     */
+    getUserByGoogleId(googleId: string): Promise<UserData | null>;
+
+    /**
+     * 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,164 @@
+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[];
+}
+
+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",
+        "change-me",
+        "changeme",
+        "password",
+        "test"
+    ]);
+
+    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 jwt.JwtPayload & AccessTokenPayload;
+        return {
+            userId: decoded.userId,
+            roles: decoded.roles
+        };
+    } catch (error) {
+        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/middleware.ts

@@ -0,0 +1,235 @@
+import { MiddlewareHandler, Context } from "hono";
+import { DataDriver } from "@rebasepro/types";
+import { verifyAccessToken, AccessTokenPayload } from "./jwt";
+import { HonoEnv } from "../api/types";
+
+/**
+ * Result from a custom auth validator.
+ * - `false`/`null`/`undefined` = not authenticated
+ * - `true` = authenticated as default user
+ * - object with `userId` or `uid` = authenticated with user info
+ */
+export type AuthResult = boolean | null | undefined | { userId?: string; uid?: string; roles?: string[]; [key: string]: unknown };
+
+/**
+ * Options for creating an auth middleware via createAuthMiddleware()
+ */
+export interface AuthMiddlewareOptions {
+    /** DataDriver to scope via withAuth() for RLS */
+    driver: DataDriver;
+    /** If true, return 401 when no valid token is present (default: false) */
+    requireAuth?: boolean;
+    /** Optional custom validator (for non-JWT auth, e.g. Firebase Auth) */
+    validator?: (c: Context<HonoEnv>) => Promise<AuthResult>;
+}
+
+/**
+ * Express middleware that requires a valid JWT token
+ * Returns 401 if token is missing or invalid
+ */
+export const requireAuth: MiddlewareHandler<HonoEnv> = async (
+    c,
+    next
+) => {
+    const authHeader = c.req.header("authorization");
+    const queryToken = c.req.query("token");
+    const hasBearer = authHeader && authHeader.startsWith("Bearer ");
+
+    if (!hasBearer && !queryToken) {
+        return c.json({
+            error: {
+                message: "Authorization header or token query parameter missing or invalid",
+                code: "UNAUTHORIZED"
+            }
+        }, 401);
+    }
+
+    const token = hasBearer ? authHeader!.substring(7) : queryToken!;
+    const payload = verifyAccessToken(token);
+
+    if (!payload) {
+        return c.json({
+            error: {
+                message: "Invalid or expired token",
+                code: "UNAUTHORIZED"
+            }
+        }, 401);
+    }
+
+    c.set("user", payload);
+    return next();
+};
+
+/**
+ * Middleware that requires the user to have an admin or schema-admin role.
+ * Must be used AFTER requireAuth or on a route where user is guaranteed.
+ */
+export const requireAdmin: MiddlewareHandler<HonoEnv> = async (
+    c,
+    next
+) => {
+    const user = c.get("user");
+    if (!user) {
+        return c.json({
+            error: {
+                message: "User not authenticated. requireAuth middleware is missing?",
+                code: "UNAUTHORIZED"
+            }
+        }, 401);
+    }
+
+    const roles = (typeof user === "object" && user !== null && "roles" in user) ? (user.roles || []) : [];
+    const isAdmin = roles.some((role: string) => {
+        return role === "admin" || role === "schema-admin";
+    });
+
+    if (!isAdmin) {
+        return c.json({
+            error: {
+                message: "Admin privileges required for this operation",
+                code: "FORBIDDEN"
+            }
+        }, 403);
+    }
+
+    return next();
+};
+
+
+/**
+ * Middleware that optionally extracts user from JWT
+ * Does not return 401 if token is missing - allows anonymous access
+ */
+export const optionalAuth: MiddlewareHandler<HonoEnv> = async (
+    c,
+    next
+) => {
+    const authHeader = c.req.header("authorization");
+    const queryToken = c.req.query("token");
+    const hasBearer = authHeader && authHeader.startsWith("Bearer ");
+
+    if (hasBearer || queryToken) {
+        const token = hasBearer ? authHeader!.substring(7) : queryToken!;
+        const payload = verifyAccessToken(token);
+        if (payload) {
+            c.set("user", payload);
+        }
+    }
+
+    return next();
+};
+
+/**
+ * Extract user from token - for WebSocket authentication
+ */
+export function extractUserFromToken(token: string): AccessTokenPayload | null {
+    return verifyAccessToken(token);
+}
+
+/**
+ * Helper to scope a DataDriver via withAuth() for RLS.
+ * SECURITY: If withAuth() is available but fails, the error is re-thrown
+ * so the request is denied rather than proceeding with unscoped access.
+ */
+async function scopeDataDriver(
+    driver: DataDriver,
+    user: { uid: string; roles?: string[] }
+): Promise<DataDriver> {
+    if ("withAuth" in driver && typeof (driver as Record<string, unknown>).withAuth === "function") {
+        // Fail closed — do NOT catch and swallow errors here.
+        // If RLS scoping fails the request must be rejected.
+        return await (driver as unknown as { withAuth: (user: Record<string, unknown>) => Promise<DataDriver> }).withAuth(user);
+    }
+    return driver;
+}
+
+/**
+ * Create a configurable auth middleware that handles:
+ * 1. Token extraction (via custom validator or JWT Bearer token)
+ * 2. RLS-scoped DataDriver via withAuth()
+ * 3. Optional enforcement (401 when requireAuth is true and no user)
+ *
+ * This is the single source of truth for HTTP auth in Rebase.
+ * Use this instead of manually parsing tokens in route handlers.
+ */
+export function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv> {
+    const { driver, requireAuth: enforceAuth = false, validator } = options;
+
+    return async (c, next) => {
+        if (validator) {
+            // Custom validator path (e.g., Firebase Auth, API keys)
+            try {
+                const authResult = await validator(c);
+                if (authResult && typeof authResult === "object") {
+                    const id = ("userId" in authResult ? authResult.userId : undefined)
+                        || ("uid" in authResult ? authResult.uid : undefined);
+                    if (id) {
+                        const roles = authResult.roles || [];
+                        c.set("user", { userId: id, roles });
+                        const user = { uid: id, roles, ...authResult };
+                        c.set("driver", await scopeDataDriver(driver, user));
+                    } else {
+                        c.set("driver", driver);
+                    }
+                } else if (authResult === true) {
+                    c.set("user", { userId: "default", roles: [] });
+                    c.set("driver", driver);
+                } else {
+                    // Not authenticated - inject anon scope explicitly
+                    try {
+                        c.set("driver", await scopeDataDriver(driver, { uid: "anon", roles: ["anon"] }));
+                    } catch (error) {
+                        c.set("driver", driver);
+                    }
+                }
+            } catch (error) {
+                return c.json({ error: { message: "Unauthorized", code: "UNAUTHORIZED" } }, 401);
+            }
+        } else {
+            // Default JWT path
+            try {
+                const authHeader = c.req.header("authorization");
+                const queryToken = c.req.query("token");
+                const hasBearer = authHeader && authHeader.startsWith("Bearer ");
+                
+                if (hasBearer || queryToken) {
+                    const token = hasBearer ? authHeader!.substring(7) : queryToken!;
+                    const payload = extractUserFromToken(token);
+
+                    if (payload) {
+                        c.set("user", payload);
+                        const user = { uid: payload.userId, roles: payload.roles };
+                        c.set("driver", await scopeDataDriver(driver, user));
+                    } else {
+                        console.error("[AUTH] Token payload empty or invalid (length: " + token.length + ")");
+                        c.set("driver", driver);
+                    }
+                } else {
+                    // Try to inject anon scope to allow RLS policies to match against public connections
+                    try {
+                        c.set("driver", await scopeDataDriver(driver, { uid: "anon", roles: ["anon"] }));
+                    } catch (error) {
+                        console.error("[AUTH] Error scoping default anon driver", error);
+                        c.set("driver", driver);
+                    }
+                }
+            } catch (error) {
+                console.error("Default auth validation error", error);
+                
+                // Fallback to anon scope
+                try {
+                    c.set("driver", await scopeDataDriver(driver, { uid: "anon", roles: ["anon"] }));
+                } catch (anonError) {
+                    c.set("driver", driver);
+                }
+            }
+        }
+
+        if (enforceAuth && !c.get("user")) {
+            console.error("[AUTH] Rejecting with 401. Path:", c.req.path);
+            return c.json({ error: { message: "Unauthorized: Invalid or missing token", code: "UNAUTHORIZED" } }, 401);
+        }
+
+        return next();
+    };
+}