@rebasepro/server 0.16.0 → 0.16.1-canary.g701140a

package/dist/functions/context.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Reading the request context from inside a custom function.
+ *
+ * The functions router resolves the caller's identity before any handler runs
+ * and leaves the result on the Hono context. Getting it back out used to be the
+ * user's problem, and the shape made that worse than it sounds: `HonoEnv`
+ * types `user` as `AuthResult`, a union that includes `boolean`, `null` and an
+ * index signature, because the same slot is filled by four different middlewares
+ * — JWT, service key, API key, and a user-supplied validator that may return
+ * `true`. Every example in the documentation therefore opened with
+ *
+ *     const user = c.get("user") as { uid: string; roles?: string[] } | undefined;
+ *
+ * and an assertion in a security-relevant position is exactly the kind of line
+ * that gets copied once and then never re-examined. It is also wrong in one
+ * case that occurs in practice: a custom validator returning `true` stores
+ * `{ uid: "default", roles: [] }`, which the assertion above types as having a
+ * `uid` — true here, but nothing checks it.
+ *
+ * These accessors do the narrowing once, in the framework, where it can be
+ * tested. They are also **runtime-neutral by construction** — no crypto, no
+ * token parsing, no I/O, nothing but property reads on an object another
+ * middleware already populated. That is what lets them live in
+ * `@rebasepro/server/functions` and run unchanged on a host that has no Node
+ * built-ins.
+ *
+ * @module
+ */
+import type { Context } from "hono";
+import type { DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import type { ApiKeyMasked } from "../auth/api-keys/api-key-types.js";
+/**
+ * The caller, as a custom function sees them.
+ *
+ * A narrowed view of whatever the auth middleware resolved: `uid` and `roles`
+ * are guaranteed, and the index signature keeps any extra claims the token or
+ * the adapter carried (`email`, `org_id`, anything a custom validator added)
+ * reachable without a cast.
+ */
+export interface FunctionUser {
+    /** Stable id of the caller. `"service"` for service-key and API-key callers. */
+    uid: string;
+    /** Roles as resolved for this request. Never `undefined` — an empty array instead. */
+    roles: string[];
+    /** Present when the identity carried one. Not every auth method does. */
+    email?: string;
+    /** Any further claim the token, adapter or validator supplied. */
+    [claim: string]: unknown;
+}
+/** Anything with a Hono-style `.get`, so these work on any `Context` shape. */
+type CtxLike = Context<HonoEnv> | Context;
+/**
+ * The authenticated caller, or `undefined` for an anonymous request.
+ *
+ * **`undefined` is not a permission decision.** The functions router mounts its
+ * auth middleware with `requireAuth: false` on purpose — a webhook receiver has
+ * no token to send — so an anonymous caller reaches the handler and reads
+ * `undefined` here while the handler runs on regardless. Use {@link requireAuth}
+ * (or a `!user` branch that returns 401) to make it a decision.
+ *
+ * A caller who presented a *bad* token never gets this far: both auth
+ * middlewares reject an unverifiable token with 401 before the router is
+ * reached, precisely so an expired session cannot be silently downgraded to an
+ * anonymous one.
+ */
+export declare function getUser(c: CtxLike): FunctionUser | undefined;
+/** The caller's id, or `undefined` when nobody is signed in. */
+export declare function getUserId(c: CtxLike): string | undefined;
+/** The caller's roles. Empty for an anonymous request — never `undefined`. */
+export declare function getRoles(c: CtxLike): string[];
+/**
+ * Whether the caller holds **any** of the named roles.
+ *
+ * Any rather than all, because that is what a route guard means by a list of
+ * roles; require several by calling this more than once.
+ */
+export declare function hasRole(c: CtxLike, ...roles: string[]): boolean;
+/**
+ * Whether the caller holds an administrative role.
+ *
+ * Delegates to the single definition in `auth/admin-roles.ts` — which is
+ * `admin` **or** `schema-admin` — rather than comparing against `"admin"`.
+ * Those two lists disagreed once, and the gap made every public registrant an
+ * administrator; see that file.
+ */
+export declare function isAdmin(c: CtxLike): boolean;
+/** Whether the request carries an identity at all. */
+export declare function isAuthenticated(c: CtxLike): boolean;
+/**
+ * The request-scoped data driver: reads and writes run as **the caller**, with
+ * your row-level security policies evaluated against their identity.
+ *
+ * This is the accessor to reach for when a function serves user-facing data.
+ * `rebase.dataAsAdmin` is the other one, and it is not the same thing — it runs
+ * as `{ uid: "service", roles: ["admin"] }` for every caller alike, which is
+ * correct for trusted background work and wrong for a request.
+ *
+ * `undefined` only when no Rebase auth middleware ran (see
+ * {@link identityResolved}); inside a function mounted by the framework it is
+ * always present, anonymous requests included — they get an anon-scoped driver
+ * so policies still have an identity to evaluate.
+ */
+export declare function getDriver(c: CtxLike): DataDriver | undefined;
+/**
+ * {@link getDriver}, but throws instead of handing back `undefined`.
+ *
+ * For the common case where a handler cannot proceed without it and would
+ * otherwise write `c.get("driver")!` — an assertion that turns a wiring problem
+ * into `Cannot read properties of undefined (reading 'fetchCollection')` twenty
+ * lines away from the cause.
+ */
+export declare function requireDriver(c: CtxLike): DataDriver;
+/**
+ * The API key this request authenticated with, masked, or `undefined` when it
+ * did not use one.
+ *
+ * Useful for attribution and for per-key behaviour. The permission check itself
+ * has already happened — reaching a handler means the key was allowed to.
+ */
+export declare function getApiKey(c: CtxLike): ApiKeyMasked | undefined;
+/**
+ * The correlation id for this request — generated, or taken from an inbound
+ * `X-Request-ID`.
+ *
+ * Log it. It is the only thing that ties a line written inside a function to
+ * the framework's own lines for the same request.
+ */
+export declare function getRequestId(c: CtxLike): string | undefined;
+/**
+ * Whether a Rebase auth middleware has run on this request.
+ *
+ * Both middlewares populate `driver` for *every* outcome, anonymous included,
+ * and populate `user` whenever there is one. So "neither is set" does not mean
+ * "anonymous" — it means nothing resolved the identity, and treating that as
+ * anonymous is the dangerous reading. The guards use this to tell a genuinely
+ * anonymous caller (401) from a misconfigured mount (500), because answering
+ * 401 to the second sends whoever is debugging it to look at the token.
+ */
+export declare function identityResolved(c: CtxLike): boolean;
+export {};

package/dist/functions/define-function.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import type { RebaseServerClient } from "@rebasepro/types";
-import type { HonoEnv } from "../api/types";
+import type { HonoEnv } from "../api/types.js";
 /**
  * Typed context injected into a function authored with {@link defineFunction}.
  *

package/dist/functions/function-routes.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
-import { HonoEnv } from "../api/types";
-import { LoadedFunction } from "./function-loader";
+import { HonoEnv } from "../api/types.js";
+import { LoadedFunction } from "./function-loader.js";
 /**
  * Mount all loaded function routes under a single Hono router.
  *

package/dist/functions/guards.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Route guards for custom functions.
+ *
+ * These decide access from the identity the platform already resolved. They do
+ * **not** verify tokens, and that division is the point rather than a
+ * limitation:
+ *
+ * - Verifying a token needs a signing key, constant-time comparison and a
+ *   revocation lookup. That is host work, it belongs to the process that holds
+ *   the secret, and it is the part of the stack that cannot be made
+ *   runtime-neutral without rewriting it against WebCrypto.
+ * - Deciding whether *this* caller may call *this* route is application work.
+ *   It needs nothing but the resolved identity, so it costs nothing to make it
+ *   portable — and it is the half that lives in user code.
+ *
+ * Splitting there is what lets a function file compile and run unchanged on a
+ * host with no Node built-ins, and it is why these live in
+ * `@rebasepro/server/functions` while `verifyAccessToken` does not.
+ *
+ * **Inside the functions router these are equivalent to the guards exported
+ * from the package root.** Both auth middlewares resolve the identity before
+ * any handler runs: a valid credential populates `user`, an invalid one is
+ * rejected with 401 by the middleware itself, and a missing one leaves `user`
+ * unset. So the root `requireAuth`'s token-parsing branch is unreachable from a
+ * function, and removing it changes no outcome. The one difference is a handler
+ * mounted **outside** the framework's router, where no middleware ran: the root
+ * guard would parse the `Authorization` header itself, and these refuse the
+ * request with a 500 that names the wiring problem. Fail-closed, and legible.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from "hono";
+import type { HonoEnv } from "../api/types.js";
+/**
+ * Reject anonymous callers with 401.
+ *
+ * Put it in the route's own middleware slot rather than `app.use("/*", …)`:
+ * `use()` covers only the routes declared *below* it, so a route appended later
+ * — by you, months from now, at the bottom of the file — is silently
+ * unprotected. The per-route form cannot drift that way.
+ *
+ * @example
+ * ```ts
+ * app.post("/", requireAuth, async (c) => {
+ *     const user = getUser(c)!;  // guaranteed by the guard
+ *     return c.json({ uid: user.uid });
+ * });
+ * ```
+ */
+export declare const requireAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Reject callers without an administrative role with 403.
+ *
+ * Must come **after** {@link requireAuth}: on its own it answers 401 for an
+ * anonymous caller, which is right, but pairing them keeps the two failures
+ * distinguishable — 401 "who are you", 403 "not you".
+ *
+ * Administrative means `admin` or `schema-admin`, from the single list in
+ * `auth/admin-roles.ts`. Do not compare against `"admin"` by hand; that is the
+ * divergence that list exists to prevent.
+ */
+export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
+/**
+ * Reject callers holding none of the named roles with 403.
+ *
+ * Any of them, not all — require several by chaining the guard twice. Naming no
+ * role at all is a programming error and throws at module load rather than at
+ * request time, because `requireRole()` with an empty list would otherwise read
+ * as a guard while admitting everyone.
+ *
+ * @example
+ * ```ts
+ * app.post("/publish", requireAuth, requireRole("editor", "admin"), handler);
+ * ```
+ */
+export declare function requireRole(...roles: string[]): MiddlewareHandler<HonoEnv>;

package/dist/functions/index.d.ts

@@ -1,5 +1,96 @@
-export { loadFunctionsFromDirectory } from "./function-loader";
-export type { LoadedFunction } from "./function-loader";
-export { createFunctionRoutes } from "./function-routes";
-export { defineFunction } from "./define-function";
-export type { RebaseFunctionContext } from "./define-function";
+/**
+ * `@rebasepro/server/functions` — the portable authoring surface.
+ *
+ * Everything a custom function needs, and nothing that ties it to one runtime.
+ * Import from here rather than from `@rebasepro/server`:
+ *
+ * ```ts
+ * import { defineFunction, requireAuth, getUser, rebase } from "@rebasepro/server/functions";
+ * ```
+ *
+ * ## Why this entry point exists
+ *
+ * `@rebasepro/server` is a single barrel over the whole framework: the boot
+ * sequence, the collection loader, the backup routes, the SPA server, the
+ * WebSocket layer. Importing one name from it pulls `@hono/node-server`, `ws`,
+ * `jsonwebtoken`, Drizzle and a dozen modules that open files. On Node that
+ * costs a little start-up time and nothing else, which is why it stood for as
+ * long as it did. On a host without Node built-ins it does not resolve at all —
+ * so with only that entry point, *no* custom function could ever run anywhere
+ * but Node, no matter how portable the function's own code was.
+ *
+ * That is not a limitation you can lift later. `import { defineFunction } from
+ * "@rebasepro/server"` is the line in every function file, every template and
+ * every documentation page; changing it afterwards is a breaking change for
+ * everyone who has written one. The entry point has to exist before the code
+ * that would depend on it does.
+ *
+ * ## What "portable" means here, precisely
+ *
+ * Every module reachable from this file:
+ *
+ * - imports no Node built-in, directly or transitively;
+ * - imports no package that needs one (`@hono/node-server`, `ws`,
+ *   `jsonwebtoken`, `drizzle-orm`, `pg`, …);
+ * - touches no host global — `process`, `Buffer`, `__dirname` — at module
+ *   scope, so the module *evaluates* on a runtime that has none.
+ *
+ * `portability.test.ts` walks this graph on every run and fails naming the
+ * import chain that broke it. The rule is not a convention; it is a test.
+ *
+ * ## What is deliberately not here
+ *
+ * - **`rebase.sql()`** — reachable through `rebase`, and Node-only in practice:
+ *   it runs on the database owner connection over a TCP socket. It is left on
+ *   the object rather than hidden because there is nothing wrong with using it
+ *   on a Node deployment; see its docblock, and `runtimeKey()` if a function
+ *   needs to degrade rather than fail.
+ * - **Token verification.** Deciding whether a caller is who they say needs the
+ *   signing key and belongs to the host; deciding whether *this* caller may
+ *   call *this* route needs only the resolved identity and belongs here. That
+ *   is why `requireAuth` below carries no crypto — see `./guards.ts`.
+ * - **The loader, the router, the proxy, the timeout middleware.** Host
+ *   machinery. It lives in `./internal.ts`.
+ *
+ * @module
+ */
+export { defineFunction } from "./define-function.js";
+export type { RebaseFunctionContext } from "./define-function.js";
+/**
+ * The app-scoped Rebase client: `dataAsAdmin`, `auth`, `storage`, `email`,
+ * `sql`.
+ *
+ * Re-exported here — the same object the package root exports, not a copy —
+ * because it is the one piece of the framework a function reaches for at
+ * runtime, and requiring a second import from the Node-only barrel to get it
+ * would defeat the entry point.
+ *
+ * It is safe to hold at module scope, unlike a configuration value, because it
+ * is a lazy Proxy: nothing is resolved until a property is read, which happens
+ * inside a request. That indirection is also the whole of what a future
+ * isolate-based host has to hook — see `_setRebaseResolver` in
+ * `../singleton.ts`.
+ */
+export { rebase } from "../singleton.js";
+export { getUser, getUserId, getRoles, hasRole, isAdmin, isAuthenticated, getDriver, requireDriver, getApiKey, getRequestId, identityResolved } from "./context.js";
+export type { FunctionUser } from "./context.js";
+export { requireAuth, requireAdmin, requireRole } from "./guards.js";
+export { getEnv, env, requireEnv, runtimeKey, isNodeRuntime, lazyResource } from "./runtime-env.js";
+export { waitUntil } from "./wait-until.js";
+/**
+ * The Hono environment a Rebase function runs in: `c.get("user")`,
+ * `c.get("driver")`, `c.get("apiKey")` and `c.get("requestId")` are typed
+ * through it.
+ *
+ * `defineFunction` applies it for you. Declare it explicitly only when building
+ * the Hono app by hand: `new Hono<HonoEnv>()`.
+ */
+export type { HonoEnv, ApiResponse } from "../api/types.js";
+/**
+ * Throw this to answer with a specific status.
+ *
+ * The functions router installs the framework's error handler, so an `ApiError`
+ * thrown anywhere inside a handler becomes the status and body it names,
+ * whereas any other throw becomes a 500 with its detail withheld.
+ */
+export { ApiError } from "../api/errors.js";