@rebasepro/server-core 0.7.0 → 0.9.0

package/dist/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/auth/middleware.d.ts

@@ -0,0 +1,158 @@
+import { MiddlewareHandler, Context } from "hono";
+import { DataDriver } from "@rebasepro/types";
+import { AccessTokenPayload } from "./jwt";
+import { HonoEnv } from "../api/types";
+import type { ApiKeyStore } from "./api-keys/api-key-store";
+/**
+ * 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;
+    /**
+     * Optional per-request driver resolver for multi-data-source backends.
+     * Given the request context, returns the unscoped delegate to use (e.g.
+     * Postgres vs Mongo, picked by the request's collection data source).
+     * When omitted, `driver` is used for every request.
+     */
+    resolveDriver?: (c: Context<HonoEnv>) => 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. external auth providers) */
+    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 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;
+    /**
+     * API key store for authenticating `rk_` prefixed tokens.
+     * When set, tokens starting with `rk_` are validated against the
+     * database instead of being treated as JWTs.
+     */
+    apiKeyStore?: ApiKeyStore;
+}
+/**
+ * Hono middleware that requires a valid JWT token via Authorization header.
+ * Returns 401 if token is missing or invalid.
+ *
+ * **Security:** Tokens are only accepted via the `Authorization: Bearer`
+ * header. Query-string tokens (`?token=`) are intentionally NOT accepted
+ * here because URLs leak into access logs, proxies, Referer headers, and
+ * browser history. Use {@link queryTokenAuth} on routes that legitimately
+ * need query-string tokens (e.g. storage file serving for `<img src>`).
+ */
+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 via Authorization header.
+ * Does not return 401 if token is missing — allows anonymous access.
+ *
+ * Query-string tokens are NOT accepted here. Use {@link queryTokenAuth}
+ * on routes that need them.
+ */
+export declare const optionalAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Extract user from token - for WebSocket authentication
+ */
+export declare function extractUserFromToken(token: string): AccessTokenPayload | null;
+/**
+ * Create a configurable auth middleware that handles:
+ * 1. Token extraction (via custom validator or JWT Bearer token)
+ * 2. RLS-scoped DataDriver via withAuth()
+ * 3. Enforcement (401 when requireAuth is true and no user)
+ *
+ * **Secure by default:** `requireAuth` defaults to `true`. Anonymous
+ * access is only allowed when the developer explicitly opts out by
+ * setting `requireAuth: false`, indicating that Postgres RLS policies
+ * fully control access.
+ *
+ * **Fail-closed:** The raw unscoped driver is never placed in the
+ * request context. Every code path either scopes via `withAuth()` or
+ * rejects the request. This prevents silent RLS bypass.
+ *
+ * This is the single source of truth for HTTP auth in Rebase.
+ * Use this instead of manually parsing tokens in route handlers.
+ */
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that authenticates via a `?token=` query parameter.
+ *
+ * **Use sparingly.** Tokens in URLs leak into access logs, proxy logs,
+ * Referer headers, and browser history. This middleware exists solely for
+ * routes where the consumer cannot set HTTP headers — e.g. `<img src>`,
+ * `<a href>` for file downloads, or similar browser-native requests.
+ *
+ * Apply it **before** `requireAuth` or `optionalAuth` on the specific
+ * route that needs it. Those middlewares will see the user context this
+ * middleware sets and skip their own 401 check.
+ *
+ * @example
+ * ```ts
+ * router.get("/file/*", queryTokenAuth, readAuthMiddleware, handler);
+ * ```
+ */
+export declare const queryTokenAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Authorizes anonymous access to **public** storage objects (those under the
+ * public prefix), which are served token-less via stable, permanent URLs.
+ *
+ * Runs on the storage `/file/*` and `/metadata/*` routes, *after* the token
+ * middleware and *before* the read-auth gate. If the request is already
+ * authenticated (Bearer or scoped token), it does nothing. Otherwise, when the
+ * requested object path is public, it sets a minimal "public" principal so the
+ * downstream `requireAuth` gate lets the read through. Private paths are left
+ * untouched, so they still require a valid token.
+ */
+export declare const publicObjectAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that authenticates file-serving routes using scoped download tokens.
+ * It enforces that only scoped "file-read" tokens can access "/file/*" and "?token=" query params.
+ * Full access JWTs are explicitly rejected on "/file/*" routes, and in the "?token=" query param.
+ */
+export declare const fileTokenAuth: MiddlewareHandler<HonoEnv>;

package/dist/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/auth/rate-limiter.d.ts

@@ -0,0 +1,50 @@
+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>;
+/**
+ * Key generator for API-key-based rate limiting.
+ *
+ * Uses the API key ID (from `c.get("apiKey")`) as the rate limit key.
+ * Falls back to IP-based keying when the request is not authenticated
+ * via an API key.
+ */
+export declare function apiKeyKeyGenerator(c: Parameters<MiddlewareHandler<HonoEnv>>[0]): string;
+/**
+ * Create a rate limiter specifically for API key requests.
+ *
+ * When a request is authenticated via an API key that has a `rate_limit`
+ * configured, this limiter enforces per-key limits using the key's ID
+ * as the rate limit bucket.
+ *
+ * @param defaultLimit - Fallback limit when the key has no `rate_limit` set.
+ * @param windowMs     - Time window in milliseconds (default: 15 minutes).
+ */
+export declare function createApiKeyRateLimiter(defaultLimit?: number, windowMs?: number): MiddlewareHandler<HonoEnv>;
+export {};

package/dist/auth/reset-password-admin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Standalone admin endpoint for resetting a user's password.
+ *
+ * Hook resolution order:
+ * 1. Collection-level hook (`auth.onResetPassword` on the collection)
+ * 2. Backend-level hook (`AuthHooks.onAdminResetPassword`)
+ * 3. Built-in default (send reset email, or generate temp password)
+ */
+import { Hono } from "hono";
+import type { AuthRepository } from "./interfaces";
+import type { AuthHooks } from "./auth-hooks";
+import type { EmailService, EmailConfig } from "../email";
+import type { HonoEnv } from "../api/types";
+import type { AuthCollectionConfig } from "@rebasepro/types";
+export interface ResetPasswordRouteConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    serviceKey?: string;
+    authHooks?: AuthHooks;
+    /** The parsed auth config from the collection, if available. */
+    collectionAuthConfig?: AuthCollectionConfig;
+}
+/**
+ * Create a standalone admin route for resetting user passwords.
+ *
+ * Mounts: POST /users/:userId/reset-password
+ */
+export declare function createResetPasswordRoute(config: ResetPasswordRouteConfig): Hono<HonoEnv>;

package/dist/auth/rls-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared RLS (Row-Level Security) scoping helper.
+ *
+ * DataDrivers may implement a `withAuth()` method that returns a scoped
+ * clone of the driver with RLS policies applied for the given user.
+ * This is database-specific (e.g. Postgres SET LOCAL ROLE) and is not
+ * part of the core DataDriver interface.
+ *
+ * This module provides the shared duck-typing logic used by the
+ * adapter-aware middleware.
+ *
+ * @module
+ */
+import type { DataDriver } from "@rebasepro/types";
+/**
+ * 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
+ * (fail-closed behavior).
+ *
+ * If the driver does not support RLS, the original driver is returned.
+ *
+ * @param driver - The DataDriver to scope.
+ * @param user   - The authenticated user identity for RLS.
+ * @returns The RLS-scoped DataDriver (or the original if RLS is unsupported).
+ */
+export declare function scopeDataDriver(driver: DataDriver, user: {
+    uid: string;
+    roles?: string[];
+}): Promise<DataDriver>;

package/dist/auth/routes.d.ts

@@ -0,0 +1,66 @@
+import { Hono } from "hono";
+import type { AuthRepository, OAuthProvider } from "./interfaces";
+import type { AuthHooks } from "./auth-hooks";
+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;
+    /** Expose the authenticated email→minimal-profile lookup route (default: false). */
+    allowUserLookup?: boolean;
+    /** Default role ID to assign to new users (default: none). Must NOT be "admin". */
+    defaultRole?: string;
+    /** Optional array of OAuth providers */
+    oauthProviders?: OAuthProvider<unknown>[];
+    /** When true, blocks all self-registration regardless of `allowRegistration`. */
+    disableSelfRegistration?: boolean;
+    /**
+     * Auth hooks for customizing password hashing, credential
+     * verification, lifecycle hooks, etc.
+     */
+    authHooks?: AuthHooks;
+    /**
+     * 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>;
+    /** Enable magic link (passwordless email) login. Requires email service. */
+    enableMagicLink?: boolean;
+    /**
+     * Opt-in httpOnly cookie mode for refresh tokens.
+     *
+     * When set, the refresh token is delivered as an `httpOnly`, `Secure`,
+     * `SameSite` cookie instead of in the JSON response body. This
+     * prevents XSS from stealing the long-lived refresh token.
+     *
+     * The access token remains in the JSON body so the client can use it
+     * in `Authorization: Bearer` headers for API calls.
+     *
+     * **Requires** `credentials: "include"` on client-side fetch calls to
+     * auth endpoints, and CORS must allow credentials (no `origin: "*"`).
+     */
+    cookieAuth?: CookieAuthConfig;
+}
+/**
+ * Configuration for httpOnly refresh-token cookies.
+ */
+export interface CookieAuthConfig {
+    /** Cookie name (default: "__rb_refresh"). */
+    cookieName?: string;
+    /** Cookie domain. Omit to use the current domain. */
+    domain?: string;
+    /** Cookie path (default: "/"). */
+    path?: string;
+    /** SameSite attribute (default: "Lax"). */
+    sameSite?: "Strict" | "Lax" | "None";
+    /** Force the Secure flag. Defaults to `true` when SameSite is "None", otherwise auto-detected from the request protocol. */
+    secure?: boolean;
+}
+export declare function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv>;

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

@@ -0,0 +1,29 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { HonoEnv } from "../api/types";
+import type { AuthModuleConfig } from "./routes";
+import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
+import type { resolveAuthHooks } from "./auth-hooks";
+interface SessionRoutesConfig {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ReturnType<typeof resolveAuthHooks>;
+    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>;
+}
+export declare function mountSessionRoutes(opts: SessionRoutesConfig): void;
+export {};

package/dist/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/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/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/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/collections/loader.d.ts

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

package/dist/cron/cron-loader.d.ts

@@ -0,0 +1,18 @@
+import type { CronJobDefinition } from "@rebasepro/types";
+import { type ModuleImporter } from "../utils/dynamic-import.js";
+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, importModule?: ModuleImporter): Promise<LoadedCronJob[]>;

package/dist/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>;

package/dist/cron/cron-scheduler.d.ts

@@ -0,0 +1,106 @@
+import type { CronJobStatus, CronJobLogEntry } from "@rebasepro/types";
+import type { RebaseClient } from "@rebasepro/types";
+import type { LoadedCronJob } from "./cron-loader";
+import type { CronStore } from "./cron-store";
+/**
+ * Validates a standard 5-field cron expression structurally and semantically.
+ * Returns `{ valid: true }` or `{ valid: false, reason: string }`.
+ */
+export declare function validateCronExpression(schedule: string): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare class CronScheduler {
+    private jobs;
+    private started;
+    private store?;
+    private client?;
+    /**
+     * Set the RebaseClient instance to make it available to cron job handlers.
+     */
+    setClient(client: RebaseClient): void;
+    /**
+     * Attach a persistence store for cron logs.
+     * When set, execution logs are written to the database after each run,
+     * and counters are seeded from the database on start.
+     */
+    setStore(store: CronStore): void;
+    /**
+     * Register a batch of loaded cron jobs.
+     *
+     * If the scheduler is already started, newly registered jobs are
+     * automatically scheduled (so late-registered jobs don't sit idle).
+     *
+     * Validates the cron schedule on registration — invalid schedules
+     * are rejected with a warning and the job is NOT registered.
+     */
+    registerJobs(loadedJobs: LoadedCronJob[]): void;
+    /**
+     * Start the scheduler — begins ticking all enabled jobs.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler and clear all timers.
+     *
+     * Currently-executing handlers run to completion (they are async),
+     * but no further scheduling occurs after stop.
+     */
+    stop(): void;
+    /**
+     * List all registered jobs with their current status.
+     */
+    listJobs(): CronJobStatus[];
+    /**
+     * Get a single job status by ID.
+     */
+    getJob(id: string): CronJobStatus | undefined;
+    /**
+     * Get log entries for a job.
+     */
+    getJobLogs(id: string, limit?: number): CronJobLogEntry[];
+    /**
+     * Get log entries for a job from the database (if store is available).
+     * Falls back to in-memory logs if no store is configured.
+     */
+    getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]>;
+    /**
+     * Enable or disable a job at runtime.
+     */
+    setJobEnabled(id: string, enabled: boolean): CronJobStatus | undefined;
+    /**
+     * Manually trigger a job execution immediately.
+     *
+     * Returns `undefined` if the job doesn't exist.
+     * If the job is currently executing, returns the log entry with
+     * a `skipped: true` result rather than running concurrently.
+     */
+    triggerJob(id: string): Promise<CronJobLogEntry | undefined>;
+    /**
+     * Schedule the next execution for a job.
+     *
+     * Safety guarantees:
+     * 1. Clears any existing timer first (prevents leaked/duplicate timers)
+     * 2. Enforces a minimum delay to prevent tight loops from jitter
+     * 3. Unref's the timer so it doesn't prevent process exit
+     * 4. Re-checks enabled & started state before executing
+     * 5. Concurrency guard prevents overlapping handler executions
+     */
+    private scheduleNext;
+    /**
+     * Stop a single job's timer and clear its next run state.
+     */
+    private stopJob;
+    /**
+     * Execute a job's handler with full isolation and safety.
+     *
+     * - Sets a concurrency flag to prevent overlapping runs
+     * - Wraps handler in a timeout race
+     * - Captures all logs, errors, and results
+     * - Persists to store (non-blocking) if available
+     * - Always restores state even on catastrophic errors
+     */
+    private executeJob;
+    private toStatus;
+}

package/dist/cron/cron-store.d.ts

@@ -0,0 +1,32 @@
+import type { CronJobLogEntry } from "@rebasepro/types";
+import type { DataDriver } from "@rebasepro/types";
+/**
+ * Persistence layer for cron job execution logs.
+ *
+ * Uses the DataDriver's `admin.executeSql` capability to store logs in a
+ * `rebase.cron_logs` table. Falls back gracefully if the driver doesn't
+ * support SQL (e.g. MongoDB) — in that case, no persistence occurs.
+ */
+export interface CronStore {
+    /** Ensure the backing table exists. Called once on startup. */
+    ensureTable(): Promise<void>;
+    /** Persist a single log entry after execution. */
+    insertLog(entry: CronJobLogEntry): Promise<void>;
+    /**
+     * Fetch the most recent logs for a job.
+     * @param jobId  The job identifier
+     * @param limit  Max entries to return (default 50)
+     * @returns Logs sorted newest-first
+     */
+    fetchLogs(jobId: string, limit?: number): Promise<CronJobLogEntry[]>;
+    /**
+     * Fetch aggregate stats for all jobs (totalRuns, totalFailures, lastRunAt).
+     * Used to seed in-memory counters on startup.
+     */
+    fetchJobStats(): Promise<Map<string, {
+        totalRuns: number;
+        totalFailures: number;
+        lastRunAt?: string;
+    }>>;
+}
+export declare function createCronStore(driver: DataDriver): CronStore | undefined;