@rebasepro/server 0.13.1-canary.gf57a27e → 0.14.0

package/dist/services/outbound-url-guard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Refusal to send a request to a destination the guard does not allow.
+ *
+ * Distinct from a network error on purpose: a blocked destination is
+ * *terminal* — retrying it re-runs the same refusal — while an `ENOTFOUND`
+ * or a refused connection is worth another attempt.
+ */
+export declare class BlockedUrlError extends Error {
+    constructor(message: string);
+}
+export interface OutboundUrlGuardOptions {
+    /**
+     * Send to destinations that resolve to loopback, link-local, private or
+     * otherwise non-public addresses. Off by default, and turning it on
+     * re-opens SSRF: any caller who can choose the URL can then reach the
+     * pod's own metadata endpoint, the cluster API server and the database.
+     * Only for a genuinely local receiver (a sidecar, a dev tunnel).
+     */
+    allowPrivateNetworks?: boolean;
+    /**
+     * Hostname resolver. Defaults to `dns.lookup(host, { all: true })`.
+     * Injected by tests so a unit suite never touches a resolver.
+     */
+    lookup?: (hostname: string) => Promise<string[]>;
+}
+/**
+ * Why this address must not be a webhook destination, or `null` if it is an
+ * ordinary public address. Exported for tests and for anyone else adding an
+ * outbound call whose destination comes from data.
+ */
+export declare function blockedAddressReason(address: string): string | null;
+/**
+ * Resolve and validate a destination before anything connects to it.
+ *
+ * Three checks, in order, because each is cheaper than the next: the scheme,
+ * the hostname, then every address the hostname resolves to. *Every* address —
+ * a name that answers with one public and one private record is a rebinding
+ * attempt, and taking the first record would let it through.
+ *
+ * Known limit: this is validate-then-fetch. Between the lookup here and the
+ * connection the runtime makes there is a second resolution this code does not
+ * see, so a TTL-0 name that flips between answers can still land on a blocked
+ * address. Closing that needs the socket pinned to the address checked here,
+ * which Node's global `fetch` does not expose without an undici dispatcher.
+ * The redirect policy in {@link WebhookDispatcher} closes the much wider
+ * version of the same hole — a receiver that simply *points* at the internal
+ * address.
+ *
+ * @throws BlockedUrlError when the destination is not allowed. DNS failures
+ * are rethrown as they are, so callers can tell "never send this" from
+ * "could not send this right now".
+ */
+export declare function assertAllowedOutboundUrl(rawUrl: string, options?: OutboundUrlGuardOptions): Promise<URL>;

package/dist/services/routed-realtime-service.d.ts

@@ -15,6 +15,13 @@ interface ClientMessage {
 export interface WsRealtimeService extends RealtimeProvider {
     addClient(clientId: string, ws: unknown): void;
     handleClientMessage(clientId: string, message: ClientMessage, authContext?: unknown): Promise<void> | void;
+    /**
+     * Whether this provider actually implements channels, presence and
+     * broadcast. Declared by the provider rather than inferred, because the
+     * alternative — assuming the default one does — is how these frames came to
+     * be handed to an engine whose message switch drops them without a word.
+     */
+    supportsChannels?: boolean;
 }
 export interface RoutedRealtimeOptions {
     /** Per-engine realtime providers, keyed by data-source key. */
@@ -34,8 +41,9 @@ export interface RoutedRealtimeOptions {
  * - `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).
+ * - channel / presence / broadcast → the first provider that declares
+ *   `supportsChannels` (these are global pub/sub, not bound to an engine — but
+ *   they are not implemented by every engine either).
  * - `addClient` and lifecycle (`onServerReady`/`destroy`/`stopListening`) →
  *   all providers (each registers its own ws close handler for cleanup).
  */

package/dist/services/webhook-service.d.ts

@@ -16,14 +16,89 @@ export interface WebhookDeliveryResult {
     success: boolean;
     attemptNumber: number;
 }
+export interface WebhookDispatcherOptions {
+    /**
+     * Deliver to destinations that resolve to loopback, link-local or private
+     * addresses. Off by default. Turning it on re-opens SSRF: anyone who can
+     * choose a webhook URL can then reach the pod's metadata endpoint, the
+     * cluster API server and the database — and read the first 1000 bytes of
+     * the answer back out of `responseBody`. Only for a receiver you run
+     * yourself on the same host or network.
+     */
+    allowPrivateNetworks?: boolean;
+    /**
+     * Deadline for one attempt, covering the response body as well as the
+     * headers. Defaults to 10s.
+     */
+    timeoutMs?: number;
+    /**
+     * Called with the final result of every delivery, including the ones
+     * started by {@link WebhookDispatcher.enqueueEntityChange} — which return
+     * nothing to their caller, so this is the only place their failures
+     * surface.
+     */
+    onDelivery?: (result: WebhookDeliveryResult) => void;
+    /**
+     * Hostname resolver used by the destination guard. Defaults to
+     * `dns.lookup`; injected by tests so a unit suite never asks a resolver.
+     */
+    lookup?: (hostname: string) => Promise<string[]>;
+}
 export declare class WebhookDispatcher {
     private webhooks;
     private maxRetries;
     private retryDelays;
+    private readonly options;
+    private readonly timeoutMs;
+    private queue;
+    private draining;
+    constructor(options?: WebhookDispatcherOptions);
     /** Register webhooks to watch */
     setWebhooks(webhooks: WebhookConfig[]): void;
-    /** Called when a entity changes — checks if any webhook matches */
+    /**
+     * Called when a entity changes — checks if any webhook matches, and awaits
+     * every delivery, retries included.
+     *
+     * **Do not await this inside a collection callback.** `afterSave` and
+     * `afterDelete` run inside the write's Postgres transaction, so awaiting a
+     * delivery here holds a pooled connection and the row's locks for as long
+     * as the receiver takes to answer — up to ~36s across three attempts, per
+     * matching webhook. Use {@link enqueueEntityChange} there; this method is
+     * for a custom function or a job that wants the results.
+     */
     onEntityChange(table: string, event: "INSERT" | "UPDATE" | "DELETE", id: string, entity: Record<string, unknown> | null, previousEntity?: Record<string, unknown> | null): Promise<WebhookDeliveryResult[]>;
+    /**
+     * Queue the same deliveries and return immediately.
+     *
+     * This is the form a collection callback wants. `afterSave` is awaited
+     * *inside* the transaction that wrote the row, so anything it awaits is
+     * transaction time; queueing hands the HTTP to a drain loop that runs
+     * after the callback returns, and the transaction commits without waiting
+     * for a third party. It also means a receiver that is down can no longer
+     * fail the customer's write.
+     *
+     * The cost, stated plainly: the queue is in-process and in-memory. A crash
+     * or a deploy between the enqueue and the delivery drops the event, and a
+     * receiver may see the notification a few milliseconds before the row it
+     * describes is committed. Use {@link flush} on shutdown, and
+     * `onDelivery` to record failures.
+     */
+    enqueueEntityChange(table: string, event: "INSERT" | "UPDATE" | "DELETE", id: string, entity: Record<string, unknown> | null, previousEntity?: Record<string, unknown> | null): void;
+    /**
+     * Wait for every queued delivery to finish. For graceful shutdown, and for
+     * tests that need to observe what {@link enqueueEntityChange} sent.
+     */
+    flush(): Promise<void>;
+    private startDraining;
+    private drainQueue;
+    /** The payload each matching webhook gets for this change. */
+    private buildDeliveries;
     private deliverWithRetry;
     private deliver;
+    /**
+     * Read at most {@link MAX_RESPONSE_BYTES} of the response and cancel the
+     * rest, so a receiver cannot buffer a 10 GB body into the pod before the
+     * caller truncates it to 1000 characters.
+     */
+    private readCappedBody;
 }

package/dist/singleton.d.ts

@@ -22,14 +22,30 @@ export declare function _resetRebaseMock(): void;
  * **Admin data plane** (`rebase.dataAsAdmin`):
  * Backed by the native DataDriver — calls go directly to the database without
  * JSON serialization, HTTP dispatch, or middleware overhead. The driver is
- * scoped as `{ uid: "service", roles: ["admin"] }`, so **every read and write
- * bypasses row-level-security policies**. No `REBASE_SERVICE_KEY` is required.
+ * scoped once as `{ uid: "service", roles: ["admin"] }` (`SERVICE_IDENTITY`),
+ * which makes it **admin-scoped, not RLS-bypassing**: every read and write runs
+ * in a transaction that has done `SET LOCAL ROLE rebase_user` with
+ * `app.uid = 'service'`, and policies are evaluated against that. No
+ * `REBASE_SERVICE_KEY` is required.
  *
- * ⚠️ Because it bypasses RLS, `rebase.dataAsAdmin` is for trusted background
- * work (cron jobs, migrations, service tasks) — **not** for serving user-facing
- * data. Inside a request handler, run user-scoped queries through the
- * request-scoped driver (`c.var.driver`), which carries the caller's identity
- * so RLS applies.
+ * It clears the default policies through their `rolesOverlap(['admin'])` arm —
+ * which is why the difference rarely shows. It shows when you write your own:
+ *
+ * - `policy.serverContext()` compiles to `auth.uid() IS NULL` and is therefore
+ *   **false** for this accessor. A collection with `disableDefaultPolicies:
+ *   true` whose rule is `serverContext()` denies these writes (`42501`) and
+ *   returns zero rows — HTTP 200, empty — for these reads.
+ * - Its reach equals an `admin`-roled application user's reach. It is not a
+ *   private door.
+ *
+ * `rebase.sql()` *is* an unconditional bypass — it runs on the owner connection
+ * and never goes through `withAuth`. Of the two accessors on this object, the
+ * quieter one is the more privileged.
+ *
+ * ⚠️ `rebase.dataAsAdmin` is for trusted background work (cron jobs,
+ * migrations, service tasks) — **not** for serving user-facing data. Inside a
+ * request handler, run user-scoped queries through the request-scoped driver
+ * (`c.var.driver`), which carries the caller's identity.
  *
  * `rebase.data` is **gone from the type**: `RebaseServerClient` omits it, so the
  * admin-scoped accessor has exactly one name and the privilege is visible at the
@@ -45,7 +61,8 @@ export declare function _resetRebaseMock(): void;
  * ```typescript
  * import { rebase } from "@rebasepro/server";
  *
- * // In a cron job, hook, or trusted service file (admin scope, bypasses RLS):
+ * // In a cron job, hook, or trusted service file (admin scope, RLS evaluated
+ * // as `{ uid: "service", roles: ["admin"] }`):
  * await rebase.email.send({ to: "admin@co.com", subject: "Alert", html: "<p>Hi</p>" });
  * const jobs = await rebase.dataAsAdmin.jobs.find({ limit: 10 });
  * ```