@rebasepro/server 0.21.0 → 0.21.1

package/README.md

@@ -9,8 +9,8 @@ pnpm add @rebasepro/server
 ```
 
 ESM-only: `"type": "module"` with no CommonJS build, so it is loaded with
-`import`. `require()` of it resolves only on Node 22.12+, which supports
-`require(esm)`.
+`import`. It needs Node `>=22.22.0` (its `engines` floor), where `require()`
+of it resolves too: Node has supported `require(esm)` since 22.12.
 
 ## What This Package Does
 
@@ -21,7 +21,7 @@ This is the central orchestrator for any Rebase backend. It provides the framewo
 | Export | Description |
 |--------|-------------|
 | `initializeRebaseBackend(config)` | Main entry point. Wires up drivers, auth, storage, API routes, cron, and custom functions. Returns a `RebaseBackendInstance`. |
-| `rebase` | Server-side singleton (`RebaseClient`). Available after init. Admin-level access to data, auth, email, and storage. |
+| `rebase` | Server-side singleton — a `RebaseServerClient` (from `@rebasepro/types`): the client without `data`, plus `dataAsAdmin`. Available after init. Admin-scoped access to data (RLS is evaluated as the service identity, not skipped), auth, email, and storage. |
 | `loadEnv()` | Validates `process.env` against the Rebase env schema (Zod). Auto-generates dev secrets. Supports `extend` for custom vars. |
 | `serveSPA(app, config)` | Mounts SPA static-file serving + index.html fallback on a Hono app. |
 | `RebaseBackendConfig` | Config type for `initializeRebaseBackend`. |
@@ -31,43 +31,61 @@ This is the central orchestrator for any Rebase backend. It provides the framewo
 | `z` | The runtime's own Zod instance. Build `loadEnv({ extend })` schemas with this one — a schema from a second copy of zod is silently ignored. |
 | `_setRebaseMock` / `_resetRebaseMock` | Test helpers to mock the `rebase` singleton (NODE_ENV=test only). |
 
-Also re-exports all abstract interfaces (`DatabaseAdapter`, `AuthAdapter`, `DataDriver`, etc.), API types (`HonoEnv`, `ApiConfig`), auth module, email module, storage module, history module, cron module, custom functions, logging utilities, and driver registry.
+Also exports `HonoEnv`, the auth, email, storage, history and cron modules, custom functions, logging utilities, and the driver registry. The abstract driver interfaces (`DatabaseAdapter`, `AuthAdapter`, `DataDriver`, …) are not re-exported: import them from `@rebasepro/types`.
+
+`@rebasepro/server/functions` is the portable surface a function file imports — `defineFunction`, the `requireAuth`/`requireAdmin` guards, `getUser`, `rebase` and the rest. The package also ships the `rebase-server` binary, which runs a built project bundle (`rebase-server ./dist-bundle`); it is what the `rebasepro/server` image executes.
 
 ## Quick Start
 
 ```typescript
-import { serve } from "@hono/node-server";
+import { createServer } from "node:http";
+import { getRequestListener } from "@hono/node-server";
 import { Hono } from "hono";
-import { initializeRebaseBackend, loadEnv, serveSPA } from "@rebasepro/server";
+import { initializeRebaseBackend, loadEnv, serveSPA, type HonoEnv } from "@rebasepro/server";
 import { createPostgresAdapter } from "@rebasepro/server-postgres";
 
 // 1. Load and validate environment
 const env = loadEnv();
 
 // 2. Create Hono app + HTTP server
-const app = new Hono();
-const server = serve({ fetch: app.fetch, port: env.PORT });
+const app = new Hono<HonoEnv>();
+const server = createServer(getRequestListener(app.fetch));
 
 // 3. Initialize Rebase
 const backend = await initializeRebaseBackend({
   app,
   server,
-  database: createPostgresAdapter({ connection: db, schema }),
+  database: createPostgresAdapter({ connection: db, schema: { tables, enums, relations } }),
   collections: myCollections,
   auth: {
     collection: defaultUsersCollection,
     jwtSecret: env.JWT_SECRET,
     allowRegistration: env.ALLOW_REGISTRATION,
     serviceKey: env.REBASE_SERVICE_KEY,
-    google: { clientId: env.GOOGLE_CLIENT_ID },
+    google: env.GOOGLE_CLIENT_ID ? { clientId: env.GOOGLE_CLIENT_ID } : undefined,
+  },
+  storage: {
+    type: "s3",
+    bucket: env.S3_BUCKET!,
+    accessKeyId: env.S3_ACCESS_KEY_ID!,
+    secretAccessKey: env.S3_SECRET_ACCESS_KEY!,
+  },
+  // Storage is not under row-level security. In production the server refuses
+  // to boot storage without an access model: this hook (or `storagePolicies`),
+  // or `storagePublicRead: true` for a bucket that really is public.
+  storageAuthorize: async ({ key, user, operation }) => {
+    if (!user) return false;
+    const [ownerId] = key.split("/");
+    return ownerId === user.uid || operation === "read";
   },
-  storage: { type: "s3", bucket: env.S3_BUCKET },
   functionsDir: "./functions",
   cronsDir: "./crons",
 });
 
 // 4. Optionally serve a frontend SPA
 serveSPA(app, { frontendPath: "./frontend/dist" });
+
+server.listen(env.PORT);
 ```
 
 ## Related Packages

package/dist/api/errors.d.ts

@@ -109,6 +109,47 @@ export interface RebaseApiError extends Error {
     code?: string;
     details?: unknown;
 }
+/**
+ * The answer an error chose for itself, read the same way at every door.
+ *
+ * @see declaredErrorAnswer
+ */
+export interface DeclaredErrorAnswer {
+    /** The HTTP status the error carries. A socket frame has no slot for it. */
+    status: number;
+    code: string;
+    message: string;
+    details?: unknown;
+    /** See {@link ApiError.expected}: log it at debug, not warn. */
+    expected: boolean;
+}
+/**
+ * The status, code and message an error carries as its own answer — or
+ * `undefined` for an error that carries none, which is a server fault and gets
+ * masked.
+ *
+ * Two classes carry one. The server's `ApiError`, and `RebaseApiError` (or its
+ * `RebaseClientError` subclass) from `@rebasepro/types` once it has a status.
+ * The second is the browser-safe class: a `config/collections/*.ts` file is
+ * bundled into the admin SPA and cannot import this package, so it is what a
+ * collection callback throws, and what a callback refusal becomes —
+ * `callbackRefusal` returns one, and `toCallbackError` wraps anything thrown
+ * that does not already carry a status.
+ *
+ * One function because several doors turn an error into an answer: the REST
+ * error handler, the two WebSocket servers, and the Postgres realtime
+ * subscriptions. Each used to list the classes it recognised by hand. The
+ * sockets listed only `ApiError`, so a `beforeDelete` veto that REST
+ * answered as 400 `CALLBACK_REJECTED` with the author's message reached the
+ * admin panel — which writes through the socket — as `INTERNAL_ERROR`, and in
+ * production as "An unexpected error occurred".
+ *
+ * Matched by name as well as `instanceof`: a monorepo can resolve two copies of
+ * a package, and `instanceof` is false across them. Name matching is also why
+ * this file needs no runtime import of `@rebasepro/types`, which it may not
+ * have — it is in the graph of `@rebasepro/server/functions`.
+ */
+export declare function declaredErrorAnswer(error: unknown): DeclaredErrorAnswer | undefined;
 /**
  * Hono error-handling middleware (`app.onError`).
  * Converts any error into the canonical `{ error: { message, code } }` shape.

package/dist/auth/admin-user-ops.d.ts

@@ -12,7 +12,7 @@
 import type { AuthRepository } from "./interfaces.js";
 import type { EmailService, EmailConfig } from "../email/index.js";
 import type { ResolvedAuthHooks } from "./auth-hooks.js";
-import type { AuthCollectionConfig } from "@rebasepro/types";
+import type { AuthCollectionConfig, UserCreationFinalizeResult, UserCreationPrepareResult } from "@rebasepro/types";
 /**
  * Generate a cryptographically secure random password that meets strength requirements.
  *
@@ -78,3 +78,25 @@ export declare function finalizeAdminUserCreation(entity: {
     invitationSent: boolean;
     emailDeliveryFailed?: boolean;
 }>;
+/**
+ * The step after a new user's row is written: who delivers the credentials,
+ * and what the create response says about it.
+ *
+ * A create hook that ran owns delivery. What it reported is the answer: the
+ * invitation it says it sent, and the temporary password it chose, which the
+ * admin has to see because it is the one the user will be told. The framework
+ * sends nothing of its own. Without a hook, `finalize` runs: the built-in
+ * invitation, or the generated password when email is not configured or fails.
+ *
+ * Both doors that create a user call this, the auth collection's REST route
+ * and `POST /admin/users`. The second used to call `finalizeAdminUserCreation`
+ * directly and read neither `hookHandledEmail` nor `invitationSent`, so it
+ * handled a hook's password as if the framework had generated it. With email
+ * configured it sent its own invitation, a second one when the hook had sent
+ * its own, and left the password out of the response. The decision lives here
+ * so that the two doors cannot disagree about it again.
+ *
+ * The result has exactly the fields a create response carries, with absent
+ * ones left out.
+ */
+export declare function completeUserCreation(prepared: UserCreationPrepareResult, finalize?: (clearPassword: string | undefined) => Promise<UserCreationFinalizeResult>): Promise<UserCreationFinalizeResult>;

package/dist/auth/auth-hooks.d.ts

@@ -222,6 +222,10 @@ export interface AuthHooks {
     /**
      * Optional hook to customize or override the default password reset flow via the admin panel.
      * When provided, this replaces the built-in password reset token generation, hashing, and email logic.
+     *
+     * A `temporaryPassword` it returns becomes the account's password: the route hashes and writes
+     * it (the same contract as a collection's `auth.onResetPassword`), so the hook need not write it
+     * through `authRepo`. The account's existing sessions end whatever the hook returns.
      */
     onAdminResetPassword?(uid: string, ctx: {
         authRepo: AuthRepository;

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

@@ -5,6 +5,10 @@
  * 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)
+ *
+ * Whichever of them runs, the account's existing sessions end, and a
+ * `temporaryPassword` in its result becomes the account's password before the
+ * response shows it to the admin.
  */
 import { Hono } from "hono";
 import type { AuthRepository } from "./interfaces.js";

package/dist/auth/token-revocation.d.ts

@@ -3,11 +3,12 @@ import type { AccessTokenPayload } from "./jwt.js";
 /**
  * Has this access token been revoked?
  *
- * `logout`, `change-password`, `reset-password` and `DELETE /auth/sessions` all
- * stamp a `tokensValidAfter` watermark on the user. Every one of them also
- * deletes refresh-token rows, which is what made the gap easy to miss: the
- * session really is gone, and the *refresh* path really does check the
- * watermark — so signing out looked like it worked.
+ * Everything that ends every session a user holds — a password change or reset
+ * of any kind, and `DELETE /auth/sessions` — goes through
+ * {@link revokeAllSessions}, which stamps a `tokensValidAfter` watermark on the
+ * user. It also deletes refresh-token rows, which is what made the gap easy to
+ * miss: the session really is gone, and the *refresh* path really does check
+ * the watermark — so signing out looked like it worked.
  *
  * The access token was untouched. It is a bearer credential that nothing
  * consulted a database about, so it stayed valid for its full lifetime after
@@ -36,3 +37,36 @@ import type { AccessTokenPayload } from "./jwt.js";
  * failure is logged at warn so it is visible rather than silent.
  */
 export declare function isAccessTokenRevoked(authRepo: Pick<AuthRepository, "getTokensValidAfter">, payload: Pick<AccessTokenPayload, "uid" | "iat">): Promise<boolean>;
+/**
+ * End every session this user holds, on every device.
+ *
+ * Two writes, because each covers what the other cannot. Deleting the refresh
+ * rows ends the sessions that exist at this instant, and on a repository
+ * without the watermark it is the only revocation there is. The watermark
+ * voids what the delete cannot see: a refresh already in flight that inserts
+ * its rotated token a moment after the delete ran, and every access token
+ * already handed out, which {@link isAccessTokenRevoked} refuses from here on.
+ *
+ * The watermark write does not fail the caller. By the time it runs the
+ * credential has usually already changed and the rows are gone, so a 500 would
+ * tell someone their password did not change when it did. It is logged, because
+ * a failure here leaves access tokens working until they expire.
+ */
+export declare function revokeAllSessions(authRepo: Pick<AuthRepository, "deleteAllRefreshTokensForUser" | "setTokensValidAfter">, uid: string): Promise<void>;
+/**
+ * Replace a user's password and end every session they hold.
+ *
+ * The one way a password hash is written over an existing account. A new
+ * password is what someone sets when they believe the old one — or a session
+ * signed in with it — is in someone else's hands, so a password change that
+ * leaves those sessions alive does not do the thing it was done for.
+ *
+ * It used to be a pair of lines repeated after each `updatePassword`, and it
+ * reached the two self-service routes and none of the admin ones: an
+ * administrator resetting a phished account left the attacker's refresh token
+ * minting access tokens for the rest of its lifetime.
+ * `test/password-change-revokes-sessions.test.ts` holds every route that sets a
+ * password to this, and fails if anything but this function calls
+ * `updatePassword`.
+ */
+export declare function replaceUserPassword(authRepo: Pick<AuthRepository, "updatePassword" | "deleteAllRefreshTokensForUser" | "setTokensValidAfter">, uid: string, passwordHash: string): Promise<void>;