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

package/dist/server-core/src/auth/interfaces.d.ts

@@ -0,0 +1,309 @@
+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;
+}
+/**
+ * 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 {
+    /**
+     * 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>;
+    /**
+     * 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/dist/server-core/src/auth/jwt.d.ts

@@ -0,0 +1,43 @@
+export interface JwtConfig {
+    secret: string;
+    accessExpiresIn?: string;
+    refreshExpiresIn?: string;
+}
+export interface AccessTokenPayload {
+    userId: string;
+    roles: string[];
+    uid?: 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[]): 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;

package/dist/server-core/src/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/server-core/src/auth/microsoft-oauth.d.ts

@@ -0,0 +1,16 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * 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 declare 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;
+}>;

package/dist/server-core/src/auth/middleware.d.ts

@@ -0,0 +1,81 @@
+import { MiddlewareHandler, Context } from "hono";
+import { DataDriver } from "@rebasepro/types";
+import { 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.
+     *
+     * **Defaults to `true` (secure by default).** Set to `false` only for
+     * intentionally public endpoints where access control is fully delegated
+     * to Postgres Row-Level Security policies.
+     */
+    requireAuth?: boolean;
+    /** Optional custom validator (for non-JWT auth, e.g. Firebase Auth) */
+    validator?: (c: Context<HonoEnv>) => Promise<AuthResult>;
+    /**
+     * A static secret key for server-to-server / script authentication.
+     *
+     * When a request sends `Authorization: Bearer <key>` and the key matches
+     * this value, the request is granted admin-level access (uid: `service`,
+     * roles: `["admin"]`) **without** JWT verification. The driver is scoped
+     * via `withAuth()` with the service identity.
+     *
+     * This is the Rebase equivalent of a Firebase Service Account key.
+     * Set via `REBASE_SERVICE_KEY` in `.env` and pass through the backend config.
+     *
+     * **Security:** The comparison uses constant-time equality to prevent
+     * timing attacks. The key must be at least 32 characters.
+     */
+    serviceKey?: string;
+}
+/**
+ * Hono middleware that requires a valid JWT token
+ * Returns 401 if token is missing or invalid
+ */
+export declare const requireAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Factory that creates a requireAuth middleware with optional service key support.
+ *
+ * When `serviceKey` is provided, the middleware will check if the Bearer token
+ * matches the service key using constant-time comparison. If it matches, the
+ * request is authenticated as a service user with admin privileges.
+ *
+ * This allows admin routes (which use standalone requireAuth + requireAdmin)
+ * to be accessed via service keys for scripts and server-to-server calls.
+ */
+export declare function createRequireAuth(options?: {
+    serviceKey?: string;
+}): MiddlewareHandler<HonoEnv>;
+/**
+ * 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 declare const requireAdmin: MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that optionally extracts user from JWT
+ * Does not return 401 if token is missing - allows anonymous access
+ */
+export declare const optionalAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Extract user from token - for WebSocket authentication
+ */
+export declare function extractUserFromToken(token: string): AccessTokenPayload | null;
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv>;

package/dist/server-core/src/auth/password.d.ts

@@ -0,0 +1,22 @@
+export interface PasswordValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Password requirements:
+ * - Minimum 8 characters
+ * - At least 1 uppercase letter
+ * - At least 1 lowercase letter
+ * - At least 1 number
+ */
+export declare function validatePasswordStrength(password: string): PasswordValidationResult;
+/**
+ * Hash a password using Node's built-in scrypt
+ * Returns format: salt:hash (both hex encoded)
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify a password against a scrypt hash
+ * Expects format: salt:hash (both hex encoded)
+ */
+export declare function verifyPassword(password: string, storedHash: string): Promise<boolean>;

package/dist/server-core/src/auth/rate-limiter.d.ts

@@ -0,0 +1,31 @@
+import { MiddlewareHandler } from "hono";
+import { HonoEnv } from "../api/types";
+interface RateLimiterOptions {
+    /** Time window in milliseconds (default: 15 minutes) */
+    windowMs?: number;
+    /** Maximum requests per window (default: 100) */
+    limit?: number;
+    /** Key generator function. Defaults to IP-based keying. */
+    keyGenerator?: (c: Parameters<MiddlewareHandler<HonoEnv>>[0]) => string;
+    /** Custom message for rate limit responses */
+    message?: string;
+}
+/**
+ * Create a rate-limiting middleware.
+ *
+ * Uses a sliding window algorithm: only timestamps within the last
+ * `windowMs` milliseconds are counted. Old entries are garbage-collected
+ * every `windowMs` to prevent unbounded memory growth.
+ */
+export declare function createRateLimiter(options?: RateLimiterOptions): MiddlewareHandler<HonoEnv>;
+/**
+ * Pre-configured rate limiter for general auth endpoints (login, register).
+ * 200 requests per 15 minutes per IP.
+ */
+export declare const defaultAuthLimiter: MiddlewareHandler<HonoEnv>;
+/**
+ * Pre-configured strict rate limiter for sensitive endpoints (password reset, verification).
+ * 50 requests per 15 minutes per IP.
+ */
+export declare const strictAuthLimiter: MiddlewareHandler<HonoEnv>;
+export {};

package/dist/server-core/src/auth/routes.d.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+import type { AuthRepository, OAuthProvider } from "./interfaces";
+import { EmailService, EmailConfig } from "../email";
+import { HonoEnv } from "../api/types";
+/**
+ * Shared configuration for auth and admin route factories.
+ */
+export interface AuthModuleConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    /** Allow new user registration (default: false). */
+    allowRegistration?: boolean;
+    /** Default role ID to assign to new users (default: none). Must NOT be "admin". */
+    defaultRole?: string;
+    /** Optional array of OAuth providers */
+    oauthProviders?: OAuthProvider[];
+    /** When true, blocks all self-registration regardless of `allowRegistration`. */
+    disableSelfRegistration?: boolean;
+    /**
+     * Callback that checks if bootstrap has already been completed.
+     * Used by GET /auth/config to report `needsSetup` status.
+     * When not provided, falls back to checking if any users exist.
+     */
+    isBootstrapCompleted?: () => Promise<boolean>;
+}
+export declare function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv>;

package/dist/server-core/src/auth/slack-oauth.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Slack OAuth Provider integration (OAuth 2.0 / "Sign in with Slack").
+ * Uses the OpenID Connect flow with the "openid,email,profile" scopes.
+ */
+export declare function createSlackProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/server-core/src/auth/spotify-oauth.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Spotify OAuth Provider integration.
+ * Uses the authorization code flow with the "user-read-email" scope.
+ */
+export declare function createSpotifyProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/server-core/src/auth/twitter-oauth.d.ts

@@ -0,0 +1,18 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Twitter/X OAuth 2.0 Provider integration.
+ *
+ * Uses OAuth 2.0 with PKCE (authorization code flow). The frontend must include
+ * the PKCE `code_verifier` when sending the authorization code.
+ *
+ * Twitter API v2 requires the "tweet.read" and "users.read" scopes at minimum,
+ * plus "offline.access" if refresh tokens are needed on Twitter's side.
+ */
+export declare function createTwitterProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}>;

package/dist/server-core/src/collections/BackendCollectionRegistry.d.ts

@@ -0,0 +1,13 @@
+import { CollectionRegistry } from "@rebasepro/common";
+import { CollectionRegistryInterface } from "../db/interfaces";
+/**
+ * Backend-agnostic collection registry.
+ * Satisfies CollectionRegistryInterface through inheritance from CollectionRegistry.
+ */
+export declare class BackendCollectionRegistry extends CollectionRegistry implements CollectionRegistryInterface {
+    /**
+     * Get the available relation keys for a given collection path.
+     * Maps from the collection's relation property names to the relation names.
+     */
+    getRelationKeysForCollection(collectionPath: string): string[];
+}

package/dist/server-core/src/collections/loader.d.ts

@@ -0,0 +1,5 @@
+import { EntityCollection } from "@rebasepro/types";
+/**
+ * Asynchronously load collection files from a directory for backend initialization
+ */
+export declare function loadCollectionsFromDirectory(directory: string): Promise<EntityCollection[]>;

package/dist/server-core/src/cron/cron-loader.d.ts

@@ -0,0 +1,17 @@
+import type { CronJobDefinition } from "@rebasepro/types";
+export interface LoadedCronJob {
+    /** Job ID derived from filename (e.g. "cleanup-sessions"). */
+    id: string;
+    /** The full definition. */
+    definition: CronJobDefinition;
+}
+/**
+ * Auto-discover cron job files from a directory.
+ *
+ * Each file should default-export a `CronJobDefinition`.
+ * The filename (without extension) becomes the job ID:
+ *   `crons/cleanup-sessions.ts` → id = "cleanup-sessions"
+ *
+ * Follows the same discovery pattern as `loadFunctionsFromDirectory`.
+ */
+export declare function loadCronJobsFromDirectory(directory: string): Promise<LoadedCronJob[]>;

package/dist/server-core/src/cron/cron-routes.d.ts

@@ -0,0 +1,14 @@
+import { Hono } from "hono";
+import type { HonoEnv } from "../api/types";
+import type { CronScheduler } from "./cron-scheduler";
+/**
+ * Create admin REST routes for managing cron jobs.
+ *
+ * Routes:
+ *   GET    /          → list all cron jobs
+ *   GET    /:id       → get a single job's status
+ *   POST   /:id/trigger → manually trigger a job
+ *   GET    /:id/logs  → get execution logs for a job
+ *   PUT    /:id       → update job (enable/disable)
+ */
+export declare function createCronRoutes(scheduler: CronScheduler): Hono<HonoEnv>;