@rebasepro/server-core 0.6.1 → 0.7.0

package/src/auth/twitter-oauth.ts

@@ -84,6 +84,7 @@ export function createTwitterProvider(config: { clientId: string; clientSecret:
                 // generate a placeholder email — the user can update it later.
                 // For apps with elevated access, fetch from v1.1 endpoint.
                 let email: string | null = null;
+                let emailVerified = false;
                 try {
                     const emailResponse = await fetch(
                         "https://api.twitter.com/1.1/account/verify_credentials.json?include_email=true",
@@ -94,6 +95,9 @@ export function createTwitterProvider(config: { clientId: string; clientSecret:
                     if (emailResponse.ok) {
                         const emailData = await emailResponse.json() as { email?: string };
                         email = emailData.email || null;
+                        if (email) {
+                            emailVerified = true;
+                        }
                     }
                 } catch {
                     // Elevated access not available — fall through
@@ -104,13 +108,16 @@ export function createTwitterProvider(config: { clientId: string; clientSecret:
                     // This allows the account to be created and linked; the user should
                     // update their email through the profile settings.
                     email = `${profileData.id}@twitter.placeholder.rebase`;
+                    // Placeholder emails are NOT verified — prevents auto-linking to existing accounts
+                    emailVerified = false;
                 }
 
                 return {
                     providerId: profileData.id,
                     email,
                     displayName: profileData.name || profileData.username || null,
-                    photoUrl: profileData.profile_image_url?.replace("_normal", "_400x400") || null
+                    photoUrl: profileData.profile_image_url?.replace("_normal", "_400x400") || null,
+                    emailVerified
                 };
             } catch (error) {
                 logger.error("Twitter OAuth error", { error: error });

package/src/cron/cron-store.ts

@@ -43,7 +43,8 @@ export function createCronStore(driver: DataDriver): CronStore | undefined {
         return undefined;
     }
 
-    const exec = admin.executeSql.bind(admin);
+    const exec = (sqlText: string, options?: { params?: unknown[] }) =>
+        admin.executeSql(sqlText, options?.params ? { params: options.params } : undefined);
 
     return {
         async ensureTable(): Promise<void> {
@@ -80,22 +81,22 @@ export function createCronStore(driver: DataDriver): CronStore | undefined {
             try {
                 const resultJson = entry.result !== undefined ? JSON.stringify(entry.result) : null;
                 const logsJson = entry.logs.length > 0 ? JSON.stringify(entry.logs) : null;
-                const errorEscaped = entry.error ? entry.error.replace(/'/g, "''") : null;
 
-                await exec(`
-                    INSERT INTO ${TABLE} (job_id, started_at, finished_at, duration_ms, success, error, result, logs, manual)
-                    VALUES (
-                        '${entry.jobId}',
-                        '${entry.startedAt}',
-                        '${entry.finishedAt}',
-                        ${entry.durationMs},
-                        ${entry.success},
-                        ${errorEscaped ? `'${errorEscaped}'` : "NULL"},
-                        ${resultJson ? `'${resultJson.replace(/'/g, "''")}'::jsonb` : "NULL"},
-                        ${logsJson ? `'${logsJson.replace(/'/g, "''")}'::jsonb` : "NULL"},
-                        ${entry.manual}
-                    )
-                `);
+                await exec(
+                    `INSERT INTO ${TABLE} (job_id, started_at, finished_at, duration_ms, success, error, result, logs, manual)
+                     VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8::jsonb, $9)`,
+                    { params: [
+                        entry.jobId,
+                        entry.startedAt,
+                        entry.finishedAt,
+                        entry.durationMs,
+                        entry.success,
+                        entry.error || null,
+                        resultJson,
+                        logsJson,
+                        entry.manual
+                    ]}
+                );
             } catch (err) {
                 // Non-blocking — log persistence should never crash the scheduler
                 logger.error(`[cron-store] Failed to persist log for "${entry.jobId}"`, { error: err });
@@ -104,13 +105,14 @@ export function createCronStore(driver: DataDriver): CronStore | undefined {
 
         async fetchLogs(jobId: string, limit = 50): Promise<CronJobLogEntry[]> {
             try {
-                const rows = await exec(`
-                    SELECT job_id, started_at, finished_at, duration_ms, success, error, result, logs, manual
-                    FROM ${TABLE}
-                    WHERE job_id = '${jobId}'
-                    ORDER BY started_at DESC
-                    LIMIT ${limit}
-                `);
+                const rows = await exec(
+                    `SELECT job_id, started_at, finished_at, duration_ms, success, error, result, logs, manual
+                     FROM ${TABLE}
+                     WHERE job_id = $1
+                     ORDER BY started_at DESC
+                     LIMIT $2`,
+                    { params: [jobId, limit] }
+                );
 
                 return rows.map(rowToLogEntry);
             } catch (err) {

package/src/email/index.ts

@@ -10,9 +10,10 @@ export type {
     PasswordResetTemplateFunction,
     EmailVerificationTemplateFunction,
     UserInvitationTemplateFunction,
-    WelcomeEmailTemplateFunction
+    WelcomeEmailTemplateFunction,
+    MagicLinkTemplateFunction
 } from "./types";
 
 export { SMTPEmailService, createEmailService } from "./smtp-email-service";
 
-export { getPasswordResetTemplate, getEmailVerificationTemplate, getUserInvitationTemplate, getWelcomeEmailTemplate } from "./templates";
+export { getPasswordResetTemplate, getEmailVerificationTemplate, getUserInvitationTemplate, getWelcomeEmailTemplate, getMagicLinkTemplate } from "./templates";

package/src/email/templates.ts

@@ -386,3 +386,85 @@ Si tienes alguna pregunta, no dudes en contactarnos respondiendo a este correo.
 html,
 text };
 }
+
+/**
+ * Default magic link email template
+ */
+export function getMagicLinkTemplate(
+    magicLinkUrl: string,
+    user: TemplateUser,
+    appName = "Rebase"
+): { subject: string; html: string; text: string } {
+    const greeting = getGreeting(user);
+
+    const subject = `Sign in to ${appName}`;
+
+    const html = `
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${subject}</title>
+</head>
+<body style="margin: 0; padding: 0; background-color: #f8fafc;">
+    <div style="${styles.container}">
+        <div style="${styles.card}">
+            <h1 style="${styles.heading}">Sign In to ${appName}</h1>
+            
+            <p style="${styles.paragraph}">
+                Hi ${greeting},
+            </p>
+            
+            <p style="${styles.paragraph}">
+                We received a request to sign in to your ${appName} account. 
+                Click the button below to log in:
+            </p>
+            
+            <div style="text-align: center;">
+                <a href="${magicLinkUrl}" style="${styles.button}">Sign In</a>
+            </div>
+            
+            <p style="${styles.paragraph}">
+                Or copy and paste this link into your browser:
+            </p>
+            <p style="color: #3b82f6; word-break: break-all; font-size: 14px;">
+                ${magicLinkUrl}
+            </p>
+            
+            <div style="${styles.warning}">
+                ⏰ This link will expire in 15 minutes for security reasons and can only be used once.
+            </div>
+            
+            <div style="${styles.footer}">
+                <p style="margin: 0;">
+                    If you didn't request this sign-in link, you can safely ignore this email. 
+                    No action is needed.
+                </p>
+            </div>
+        </div>
+    </div>
+</body>
+</html>
+    `.trim();
+
+    const text = `
+Sign In to ${appName}
+
+Hi ${greeting},
+
+We received a request to sign in to your ${appName} account.
+
+Click this link to log in:
+${magicLinkUrl}
+
+This link will expire in 15 minutes for security reasons and can only be used once.
+
+If you didn't request this sign-in link, you can safely ignore this email.
+No action is needed.
+    `.trim();
+
+    return { subject,
+html,
+text };
+}

package/src/email/types.ts

@@ -57,6 +57,14 @@ export type WelcomeEmailTemplateFunction = (
     appName: string
 ) => { subject: string; html: string; text?: string };
 
+/**
+ * Template function for magic link emails
+ */
+export type MagicLinkTemplateFunction = (
+    magicLinkUrl: string,
+    user: { email: string; displayName?: string | null }
+) => { subject: string; html: string; text?: string };
+
 /**
  * Complete email configuration
  */
@@ -89,6 +97,13 @@ export interface EmailConfig {
      */
     verifyEmailUrl?: string;
 
+    /**
+     * Base URL for magic link login (e.g., "https://myapp.com")
+     * The magic link will be: {baseUrl}/auth/magic-link?token={token}
+     * Falls back to `resetPasswordUrl` if not set.
+     */
+    magicLinkUrl?: string;
+
     /**
      * Application name to use in email templates
      */
@@ -102,5 +117,6 @@ export interface EmailConfig {
         emailVerification?: EmailVerificationTemplateFunction;
         userInvitation?: UserInvitationTemplateFunction;
         welcomeEmail?: WelcomeEmailTemplateFunction;
+        magicLink?: MagicLinkTemplateFunction;
     };
 }

package/src/init.ts

@@ -5,6 +5,7 @@ import {
     BootstrappedAuth,
     DatabaseAdapter,
     DataDriver,
+    DataSourceDefinition,
     EntityCollection,
     HealthCheckResult,
     InitializedDriver,
@@ -13,9 +14,11 @@ import {
     RealtimeProvider,
     SecurityRule
 } from "@rebasepro/types";
+import { createDataSourceRegistry, resolveDataSource } from "@rebasepro/common";
 import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
 import { loadCollectionsFromDirectory } from "./collections/loader";
 import { DEFAULT_DRIVER_ID, DefaultDriverRegistry, DriverRegistry } from "./services/driver-registry";
+import { createRoutedRealtimeService } from "./services/routed-realtime-service";
 import { Server } from "http";
 
 import { RestApiGenerator } from "./api/rest/api-generator";
@@ -123,6 +126,12 @@ export interface RebaseAuthConfig {
      */
     hooks?: AuthHooks;
 
+    /**
+     * Enable magic link (passwordless email) authentication.
+     * Requires email to be configured.
+     */
+    magicLink?: boolean;
+
     [key: string]: unknown;
 }
 
@@ -133,6 +142,16 @@ export interface RebaseBackendConfig {
     app: Hono<HonoEnv>;
     basePath?: string;
 
+    /**
+     * Declared data sources, shared with the frontend `<Rebase dataSources>`.
+     *
+     * Used to resolve each collection's engine (capabilities) and transport.
+     * Collections on a `direct`/`custom` transport are client-only: the backend
+     * still owns their schema/registry but does **not** generate server data
+     * routes for them. Server-mediated sources (the default) need no entry.
+     */
+    dataSources?: DataSourceDefinition[];
+
     /**
      * Database bootstrappers.
      */
@@ -313,6 +332,11 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     configureMiddlewares(config.app, basePath, isProduction, config);
 
     const collectionRegistry = new BackendCollectionRegistry();
+    // Declared data sources — drives engine resolution (capabilities) and the
+    // server-vs-direct transport distinction. Set before collections register
+    // so normalization can resolve each collection's engine.
+    const dataSourceRegistry = createDataSourceRegistry(config.dataSources);
+    collectionRegistry.setDataSources(dataSourceRegistry);
     let activeCollections = config.collections || [];
     if (config.collectionsDir && activeCollections.length === 0) {
         activeCollections = await loadCollectionsFromDirectory(config.collectionsDir);
@@ -401,6 +425,56 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     const defaultBootstrapper = bootstrappers.find(b => b.id === defaultDriverId || b.type === defaultDriverId) || bootstrappers[0];
     const defaultRealtimeService = defaultDriverResult.realtimeProvider;
 
+    // Resolve a collection path (e.g. "products", "authors/1/posts") to its
+    // data-source key — shared by the data-driver router and the realtime
+    // router. Falls back to the default key for unknown paths.
+    const keyForCollectionPath = (collectionPath: string): string => {
+        const slug = collectionPath.replace(/^\/+/, "").split("/")[0]?.split("?")[0];
+        if (!slug) return DEFAULT_DRIVER_ID;
+        const collection = collectionRegistry.get(slug) ?? collectionRegistry.getCollectionByPath(slug);
+        if (!collection) return DEFAULT_DRIVER_ID;
+        return resolveDataSource(collection, dataSourceRegistry).key;
+    };
+
+    // ── Data-source misconfiguration check ────────────────────────────────
+    // A server-transport collection whose resolved data-source key has no
+    // registered driver delegate would silently fall back to the default
+    // driver — i.e. land in the wrong database. Warn loudly so this surfaces
+    // at boot rather than as mysterious data going to the wrong engine.
+    {
+        const unresolved = new Map<string, string[]>();
+        const nonRlsEngines = new Set<string>();
+        for (const collection of activeCollections) {
+            const ds = resolveDataSource(collection, dataSourceRegistry);
+            if (ds.transport !== "server") continue; // direct/custom are client-only
+            // Server engines without row-level security enforce authorization
+            // only at the application layer — surface this so it isn't a
+            // silent assumption. (The default Postgres engine supports RLS.)
+            if (!ds.capabilities.supportsRLS) nonRlsEngines.add(ds.engine);
+            if (ds.key === DEFAULT_DRIVER_ID) continue; // always maps to the default
+            if (!driverRegistry.has(ds.key)) {
+                const slugs = unresolved.get(ds.key) ?? [];
+                slugs.push(collection.slug ?? collection.name ?? "?");
+                unresolved.set(ds.key, slugs);
+            }
+        }
+        for (const [key, slugs] of unresolved) {
+            logger.warn(
+                `[DataSource] No driver registered for data source "${key}" ` +
+                `(used by: ${slugs.join(", ")}). These collections will fall back to the ` +
+                `default driver "${defaultDriverId}" — register a bootstrapper with this id, ` +
+                `or mark the data source as a direct/custom transport in \`dataSources\`.`
+            );
+        }
+        for (const engine of nonRlsEngines) {
+            logger.warn(
+                `[DataSource] Engine "${engine}" does not support row-level security; ` +
+                `authorization for its collections is enforced only at the application layer ` +
+                `(authentication still applies). Ensure app-level checks or engine-native rules are in place.`
+            );
+        }
+    }
+
     // 2. Initialize Auth & History via the default driver's bootstrapper
     let authConfigResult: BootstrappedAuth | undefined = undefined;
     let serviceKey: string | undefined;
@@ -439,6 +513,23 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 }
             }
 
+            // The built-in auth subsystem (users, sessions, repository) is
+            // bootstrapped on the DEFAULT driver. If the auth collection is
+            // routed to a non-default data source, login would read/write the
+            // default engine while the collection's data views hit another —
+            // a split-brain user store. Warn loudly.
+            if (safeAuthConfig.collection) {
+                const authDs = resolveDataSource(safeAuthConfig.collection, dataSourceRegistry);
+                if (authDs.key !== DEFAULT_DRIVER_ID) {
+                    logger.warn(
+                        `[Auth] The auth collection "${safeAuthConfig.collection.slug}" is on data source ` +
+                        `"${authDs.key}", but the built-in auth system always uses the default data source. ` +
+                        `Move the auth collection to the default data source, or replace auth with an AuthAdapter ` +
+                        `that manages users in "${authDs.key}".`
+                    );
+                }
+            }
+
             // Extract the collection-level auth config (if `auth` is an object, not just `true`)
             const collectionAuth = safeAuthConfig.collection ? safeAuthConfig.collection.auth : undefined;
             const collectionAuthConfig = (typeof collectionAuth === "object" && collectionAuth !== null) ? collectionAuth : undefined;
@@ -561,7 +652,8 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 oauthProviders,
                 serviceKey,
                 authHooks: safeAuthConfig.hooks,
-                collectionAuthConfig
+                collectionAuthConfig,
+                enableMagicLink: safeAuthConfig.magicLink ?? false
             });
         }
 
@@ -668,18 +760,39 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             );
         }
 
+        // Multi-data-source routing: when more than one database engine is
+        // registered (e.g. Postgres + MongoDB in one instance), resolve the
+        // delegate per request from the request's collection data source. The
+        // auth middleware then scopes that delegate (RLS for Postgres, no-op
+        // for engines without `withAuth()`) into the request context. For a
+        // single-engine backend this is omitted — behaviour is unchanged.
+        const dataPathMarker = `${basePath}/data/`;
+        const resolveRequestDriver = (reqPath: string): DataDriver => {
+            const i = reqPath.indexOf(dataPathMarker);
+            const collectionPath = i >= 0 ? reqPath.slice(i + dataPathMarker.length) : reqPath;
+            const key = keyForCollectionPath(collectionPath);
+            // Use the authoritative default for the default key; otherwise the
+            // named delegate, falling back to default if it isn't registered.
+            if (!key || key === DEFAULT_DRIVER_ID) return defaultDriver;
+            return driverRegistry.get(key) ?? defaultDriver;
+        };
+        const multiEngine = bootstrappers.length > 1;
+        const resolveDriver = multiEngine ? ((c: { req: { path: string } }) => resolveRequestDriver(c.req.path)) : undefined;
+
         // Use adapter middleware when an AuthAdapter is available,
         // falling back to the built-in JWT middleware otherwise.
         if (authAdapter) {
             dataRouter.use("/*", createAdapterAuthMiddleware({
                 adapter: authAdapter,
                 driver: defaultDriver,
+                resolveDriver,
                 requireAuth: dataRequireAuth,
                 apiKeyStore
             }));
         } else {
             dataRouter.use("/*", createAuthMiddleware({
                 driver: defaultDriver,
+                resolveDriver,
                 requireAuth: dataRequireAuth,
                 serviceKey,
                 apiKeyStore
@@ -702,8 +815,15 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             dataRouter.route("/", historyRoutes);
         }
 
+        // Only generate server data routes for server-mediated collections.
+        // Collections on a direct/custom transport are client-only — the
+        // backend must not expose a (mis-engined) endpoint for them.
+        const serverCollections = activeCollections.filter(
+            (collection) => resolveDataSource(collection, dataSourceRegistry).transport === "server"
+        );
+
         const restGenerator = new RestApiGenerator(
-            activeCollections,
+            serverCollections,
             defaultDriver,
             config.hooks?.data,
             authAdapter
@@ -876,8 +996,20 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         }
     }
 
-    if (defaultBootstrapper.initializeWebsockets && defaultRealtimeService) {
-        await defaultBootstrapper.initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
+    // With multiple realtime-capable engines, route subscriptions to the
+    // provider owning each collection (the realtime counterpart of the data
+    // router). The single WebSocket server is driven by this composite.
+    // Single-engine setups use the default provider unchanged.
+    const effectiveRealtimeService: RealtimeProvider = Object.keys(realtimeServices).length > 1
+        ? createRoutedRealtimeService({
+            providers: realtimeServices,
+            defaultKey: defaultDriverId,
+            resolveKey: keyForCollectionPath
+        })
+        : defaultRealtimeService as RealtimeProvider;
+
+    if (defaultBootstrapper.initializeWebsockets && effectiveRealtimeService) {
+        await defaultBootstrapper.initializeWebsockets(config.server, effectiveRealtimeService, defaultDriver, config.auth, authAdapter);
     }
 
     logger.info("Rebase Backend Initialized");
@@ -896,7 +1028,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         driverRegistry,
         driver: defaultDriver,
         realtimeServices,
-        realtimeService: defaultRealtimeService as RealtimeProvider,
+        realtimeService: effectiveRealtimeService,
         auth: authConfigResult,
         history: historyConfigResult,
         storageRegistry,

package/src/services/routed-realtime-service.ts

@@ -0,0 +1,113 @@
+import { RealtimeProvider, Entity } from "@rebasepro/types";
+
+/**
+ * A realtime client message as forwarded by the WebSocket server.
+ */
+interface ClientMessage {
+    type: string;
+    payload?: Record<string, unknown>;
+    subscriptionId?: string;
+}
+
+/**
+ * The concrete realtime service surface the WebSocket server drives — the
+ * typed {@link RealtimeProvider} plus the client-connection methods that
+ * every engine's realtime service implements.
+ */
+export interface WsRealtimeService extends RealtimeProvider {
+    addClient(clientId: string, ws: unknown): void;
+    handleClientMessage(clientId: string, message: ClientMessage, authContext?: unknown): Promise<void> | void;
+}
+
+/** Channel/presence/broadcast messages are engine-agnostic pub/sub. */
+const CHANNEL_MESSAGE_TYPES = new Set([
+    "join_channel", "leave_channel", "broadcast",
+    "presence_track", "presence_untrack", "presence_state"
+]);
+
+export interface RoutedRealtimeOptions {
+    /** Per-engine realtime providers, keyed by data-source key. */
+    providers: Record<string, RealtimeProvider>;
+    /** Key of the default provider (handles channels/presence/broadcast). */
+    defaultKey: string;
+    /** Resolve a collection path to its data-source key. */
+    resolveKey: (collectionPath: string) => string;
+}
+
+/**
+ * Compose multiple per-engine {@link RealtimeProvider}s into one that routes
+ * each subscription to the provider owning the subscribed collection — the
+ * realtime counterpart of `buildRoutedRebaseData`.
+ *
+ * The WebSocket server stays single and engine-agnostic; this composite is
+ * passed in its place. Routing rules:
+ * - `subscribe_collection` / `subscribe_entity` → the provider for the
+ *   collection's data source (by `payload.path`).
+ * - `unsubscribe` → forwarded to all providers (a no-op on non-owners).
+ * - channel / presence / broadcast → the default provider (these are global
+ *   pub/sub, not bound to an engine).
+ * - `addClient` and lifecycle (`onServerReady`/`destroy`/`stopListening`) →
+ *   all providers (each registers its own ws close handler for cleanup).
+ */
+export function createRoutedRealtimeService(opts: RoutedRealtimeOptions): WsRealtimeService {
+    const { providers, defaultKey, resolveKey } = opts;
+
+    const asWs = (p: RealtimeProvider): WsRealtimeService => p as unknown as WsRealtimeService;
+    const all = (): WsRealtimeService[] => Object.values(providers).map(asWs);
+    const fallback = (): WsRealtimeService => asWs(providers[defaultKey] ?? Object.values(providers)[0]);
+    const forPath = (path?: string): WsRealtimeService => {
+        if (!path) return fallback();
+        const key = resolveKey(path);
+        return asWs(providers[key] ?? providers[defaultKey] ?? Object.values(providers)[0]);
+    };
+
+    return {
+        addClient(clientId, ws) {
+            for (const p of all()) p.addClient?.(clientId, ws);
+        },
+
+        async handleClientMessage(clientId, message, authContext) {
+            const { type } = message;
+            if (type === "subscribe_collection" || type === "subscribe_entity") {
+                await forPath(message.payload?.path as string | undefined)
+                    .handleClientMessage(clientId, message, authContext);
+                return;
+            }
+            if (type === "unsubscribe") {
+                // The owning provider acts; others no-op on an unknown id.
+                await Promise.all(all().map((p) => p.handleClientMessage(clientId, message, authContext)));
+                return;
+            }
+            // Channels/presence/broadcast (and anything else) → default provider.
+            await fallback().handleClientMessage(clientId, message, authContext);
+        },
+
+        subscribeToCollection(subscriptionId, config, callback) {
+            forPath((config as { path?: string }).path).subscribeToCollection(subscriptionId, config, callback);
+        },
+
+        subscribeToEntity(subscriptionId, config, callback) {
+            forPath((config as { path?: string }).path).subscribeToEntity(subscriptionId, config, callback);
+        },
+
+        unsubscribe(subscriptionId) {
+            for (const p of all()) p.unsubscribe(subscriptionId);
+        },
+
+        async notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string) {
+            await forPath(path).notifyEntityUpdate(path, entityId, entity, databaseId);
+        },
+
+        onServerReady(serverInfo) {
+            for (const p of all()) p.onServerReady?.(serverInfo);
+        },
+
+        async destroy() {
+            await Promise.all(all().map((p) => p.destroy?.()));
+        },
+
+        async stopListening() {
+            await Promise.all(all().map((p) => p.stopListening?.()));
+        }
+    };
+}

package/src/utils/dev-port.ts

@@ -37,6 +37,8 @@ export function listenWithPortRetry(
         maxAttempts?: number;
         /** Absolute path to write the resolved port file into.  Defaults to `process.cwd()`. */
         portFileDir?: string;
+        /** Service key to include in the state file for MCP server auto-discovery. */
+        serviceKey?: string;
     }
 ): Promise<number> {
     const host = options?.host ?? "0.0.0.0";
@@ -122,7 +124,7 @@ export function listenWithPortRetry(
 
                     // Write .rebase/state.json so external scripts can discover
                     // the running server port, URL, etc.
-                    writeStateFile(portFileDir, port);
+                    writeStateFile(portFileDir, port, options?.serviceKey);
                 }
 
                 resolve(port);
@@ -159,10 +161,11 @@ export function cleanupDevPortFile(dir: string): void {
  * Write `.rebase/state.json` with runtime info for external scripts.
  *
  * Scripts can read this file to discover:
- * - `port`      — the actual port the backend is listening on
- * - `baseUrl`   — full URL including protocol and port
- * - `pid`       — the backend process ID
- * - `startedAt` — ISO timestamp of when the server started
+ * - `port`       — the actual port the backend is listening on
+ * - `baseUrl`    — full URL including protocol and port
+ * - `pid`        — the backend process ID
+ * - `startedAt`  — ISO timestamp of when the server started
+ * - `serviceKey` — (dev only) the REBASE_SERVICE_KEY for MCP auto-discovery
  *
  * @example Reading from a script:
  * ```ts
@@ -170,19 +173,22 @@ export function cleanupDevPortFile(dir: string): void {
  * const apiUrl = state.baseUrl; // "http://localhost:3519"
  * ```
  */
-function writeStateFile(projectRoot: string, port: number): void {
+function writeStateFile(projectRoot: string, port: number, serviceKey?: string): void {
     try {
         const rebaseDir = path.join(projectRoot, ".rebase");
         if (!fs.existsSync(rebaseDir)) {
             fs.mkdirSync(rebaseDir, { recursive: true });
         }
         const stateFile = path.join(rebaseDir, "state.json");
-        const state = {
+        const state: Record<string, unknown> = {
             port,
             baseUrl: `http://localhost:${port}`,
             pid: process.pid,
             startedAt: new Date().toISOString()
         };
+        if (serviceKey) {
+            state.serviceKey = serviceKey;
+        }
         fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), "utf-8");
     } catch {
         // Non-fatal