@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/functions/index.d.ts

@@ -67,14 +67,15 @@ export type { RebaseFunctionContext } from "./define-function.js";
  *
  * 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`.
+ * inside a request — and it resolves to the backend serving that request, so
+ * with two backends in one process each one's functions see their own. That
+ * indirection is the whole of what a host hooks — the Node server per request,
+ * an isolate host per isolate — 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 { getUser, getUserId, getRoles, hasRole, isAdmin, getScopes, hasScope, isAuthenticated, getDriver, requireDriver, getApiKey, getRequestId, getSignal, identityResolved } from "./context.js";
 export type { FunctionUser } from "./context.js";
-export { requireAuth, requireAdmin, requireRole } from "./guards.js";
+export { requireAuth, requireAdmin, requireRole, requireScope } from "./guards.js";
 export { getEnv, env, requireEnv, runtimeKey, isNodeRuntime, lazyResource } from "./runtime-env.js";
 export { waitUntil } from "./wait-until.js";
 /**

package/dist/functions/index.js

@@ -96,13 +96,15 @@ var INSTANCE_SLOT = Symbol.for("@rebasepro/server:singleton-instance");
 * A *function* that answers "which client is this call for", for hosts where
 * one answer per process is the wrong shape.
 *
-* A Node server boots once and serves every request from the same client, so
-* {@link INSTANCE_SLOT} is the whole story. An isolate-based host is different
-* in a way that matters: the environment arrives attached to the **request**,
-* not to the module, so there is nothing to publish at import time, and an
-* isolate can be reused across requests that must not share state. Such a host
-* registers a resolver — typically reading an `AsyncLocalStorage` populated per
-* request — and it is consulted first.
+* {@link INSTANCE_SLOT} is one answer per process: the default backend's. A
+* Node process can hold several backends, and the code each one runs — a
+* function, a cron job, a hook — must see that one, so the server registers a
+* resolver reading the backend scope it enters per request (an
+* `AsyncLocalStorage`, host-side, in `backend/scope.ts`). An isolate-based
+* host is different in the same way: the environment arrives attached to the
+* **request**, not to the module, so there is nothing to publish at import
+* time, and an isolate can be reused across requests that must not share
+* state. The resolver is consulted first.
 *
 * This exists now, before there is a host that needs it, because of what it
 * protects: `rebase` is a lazy Proxy, so every property access already goes
@@ -123,10 +125,13 @@ function getInstance() {
 	return global[INSTANCE_SLOT] ?? null;
 }
 /**
-* The server-side Rebase singleton.
+* The server-side Rebase client, as a module-level handle.
 *
-* Initialized automatically during server startup. Provides access to all
-* app-scoped services: **data**, **auth**, **storage**, and **email**.
+* Inside a request, cron run or job a backend serves, it is that backend's
+* client (`backend.rebase`) — so with two backends in one process, each one's
+* functions see their own. Anywhere else it is the process default's, which
+* `initializeRebaseBackend` (or `setDefaultBackend`) installs. Provides access
+* to all app-scoped services: **data**, **auth**, **storage**, and **email**.
 *
 * **Admin data plane** (`rebase.dataAsAdmin`):
 * Backed by the native DataDriver — calls go directly to the database without
@@ -185,12 +190,25 @@ var rebase = new Proxy({}, {
 		return instance[prop];
 	},
 	set(_, prop) {
-		throw new Error(`Cannot set rebase.${String(prop)} directly. The singleton is read-only. Use _initRebase() during server startup.`);
+		throw new Error(`Cannot set rebase.${String(prop)} directly. The singleton is read-only. Install a backend with setDefaultBackend(backend), or use backend.rebase.`);
 	}
 });
 //#endregion
 //#region src/functions/define-function.ts
 /**
+* The `rebase` handle, seen through the `Database` a function names.
+*
+* One object serves every function; `DB` only describes it. It resolves, per
+* call, to the backend serving the request — the same answer the imported
+* `rebase` gives. Each collection accessor on `dataAsAdmin` is resolved by
+* name at call time, so a generated `Database` adds compile-time checks and
+* changes nothing the object does — the same reason the browser client's
+* `createRebaseClient<Database>()` is one implementation for every `Database`.
+*/
+function typedSingleton() {
+	return rebase;
+}
+/**
 * Typed authoring contract for a custom backend function.
 *
 * A custom function is a file in the `functionsDir` that default-exports a
@@ -227,37 +245,39 @@ var rebase = new Proxy({}, {
 */
 function defineFunction(definition) {
 	const app = new Hono();
-	const returned = definition(app, { rebase });
+	const returned = definition(app, { rebase: typedSingleton() });
 	return returned instanceof Hono ? returned : app;
 }
 //#endregion
 //#region src/auth/admin-roles.ts
 /**
-* Which role names carry administrative privilege.
-*
-* One definition, because there used to be several and they disagreed.
-* `requireAdmin` accepted `admin` **or** `schema-admin`; the guard that refuses
-* a dangerous `defaultRole` compared against `admin` alone. So
-* `AUTH_DEFAULT_ROLE=schema-admin` passed the guard and made every public
-* registrant an administrator — and, since a `schema-admin` may edit users, one
-* of them could then grant themselves real `admin` and keep it.
-*
-* The guard and the check have to read the same list or the gap comes back, so
-* neither of them owns it.
-*
-* `schema-admin` is here deliberately: it can reach the schema editor and the
-* SQL surfaces, which is administrative by any definition that matters. If a
-* genuinely lesser role is added later, it does not belong in this list — it
-* belongs in a capability check of its own.
+* The admin role and scope matching, for code that may not import
+* `@rebasepro/types`.
+*
+* The custom-functions surface (`@rebasepro/server/functions`) must bundle for
+* a runtime with no Node built-ins and imports nothing but `hono`, so its
+* guards cannot reach the canonical definitions in `@rebasepro/types`
+* (`ADMIN_ROLE`, `hasAdminRole`, `scopeGrants`). These are the same rules,
+* restated, and `test/admin-roles.test.ts` holds them equal.
+*
+* Everything else imports the `@rebasepro/types` versions.
 */
-var ADMINISTRATIVE_ROLES = ["admin", "schema-admin"];
-/** Does this single role name carry administrative privilege? */
-function isAdministrativeRole(role) {
-	return ADMINISTRATIVE_ROLES.includes(role);
+/** The one built-in role. It holds every scope. */
+var ADMIN_ROLE_NAME = "admin";
+/** Does this list of roles include the admin role? */
+function holdsAdminRole(roles) {
+	return !!roles?.includes(ADMIN_ROLE_NAME);
 }
-/** Does any role in this list carry administrative privilege? */
-function hasAdministrativeRole(roles) {
-	return !!roles?.some(isAdministrativeRole);
+/**
+* Does a set of held scopes grant `scope`, optionally on one `target`? The
+* unqualified grant covers every target; `scope:target` covers its own.
+*/
+function heldScopesGrant(held, scope, target) {
+	for (const entry of held) {
+		if (entry === scope) return true;
+		if (target !== void 0 && entry === `${scope}:${target}`) return true;
+	}
+	return false;
 }
 //#endregion
 //#region src/functions/context.ts
@@ -310,16 +330,31 @@ function hasRole(c, ...roles) {
 	const held = new Set(getRoles(c));
 	return roles.some((role) => held.has(role));
 }
+/** Whether the caller holds the `admin` role, which holds every scope. */
+function isAdmin(c) {
+	return holdsAdminRole(getRoles(c));
+}
 /**
-* Whether the caller holds an administrative role.
+* Everything the caller may do, as `resource:action[:target]` scope strings —
+* the data plane, the app's own `auth.scopes`, and whatever their roles (or
+* their API key) hold. Empty for an anonymous request.
 *
-* 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.
+* Resolved by the framework before the handler runs; `undefined` only when no
+* Rebase auth middleware ran (see {@link identityResolved}).
 */
-function isAdmin(c) {
-	return hasAdministrativeRole(getRoles(c));
+function getScopes(c) {
+	return read(c, "scopes");
+}
+/**
+* Whether the caller holds `scope`, on `target` when one is given.
+*
+* For an app scope declared under `auth.scopes` — `project:deploy` — a
+* signed-in person always holds it, so this narrows only API keys and tokens.
+* Whether the *person* may deploy *this* project is still the handler's to
+* decide.
+*/
+function hasScope(c, scope, target) {
+	return heldScopesGrant(getScopes(c) ?? [], scope, target);
 }
 /** Whether the request carries an identity at all. */
 function isAuthenticated(c) {
@@ -376,6 +411,17 @@ function getRequestId(c) {
 	return read(c, "requestId");
 }
 /**
+* The signal aborted when this request outlasts the functions timeout and is
+* answered `504 FUNCTION_TIMEOUT`. Pass it to `fetch` and anything else that
+* takes one, so the work stops with the request instead of running on after
+* the caller was told it failed.
+*
+* Never aborts when the timeout is off, or outside the functions router.
+*/
+function getSignal(c) {
+	return read(c, "functionSignal") ?? new AbortController().signal;
+}
+/**
 * Whether a Rebase auth middleware has run on this request.
 *
 * Both middlewares populate `driver` for *every* outcome, anonymous included,
@@ -428,15 +474,14 @@ var requireAuth = async (c, next) => {
 	} }, 401);
 };
 /**
-* Reject callers without an administrative role with 403.
+* Reject callers without the `admin` 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.
+* Prefer {@link requireScope} for anything an app declares a scope for: a
+* scope can be granted to a narrower role and to a key, and `admin` cannot.
 */
 var requireAdmin = async (c, next) => {
 	if (!getUser(c)) {
@@ -483,6 +528,44 @@ function requireRole(...roles) {
 		return next();
 	};
 }
+/**
+* Reject callers who do not hold `scope` with 403.
+*
+* `scope` is a built-in scope or one the app declares under `auth.scopes` on
+* the users collection. `target` narrows it to one resource — a key holding
+* `project:deploy:p1` passes `requireScope("project:deploy", c => c.req.param("project"))`
+* for `p1` only — and may be read from the request.
+*
+* A signed-in person holds every app scope, so for a person this is no
+* authorization at all: it narrows API keys and tokens. Decide whether the
+* person may act in the handler, as you would without it.
+*
+* @example
+* ```ts
+* app.post("/deploy/:project", requireAuth, requireScope("project:deploy", c => c.req.param("project")), handler);
+* ```
+*/
+function requireScope(scope, target) {
+	return async (c, next) => {
+		if (!getUser(c)) {
+			if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);
+			return c.json({ error: {
+				message: "Authentication required",
+				code: "UNAUTHORIZED"
+			} }, 401);
+		}
+		const resolvedTarget = typeof target === "function" ? target(c) : target;
+		if (!hasScope(c, scope, resolvedTarget)) {
+			const wanted = resolvedTarget !== void 0 ? `${scope}:${resolvedTarget}` : scope;
+			return c.json({ error: {
+				message: `This credential does not hold the "${wanted}" scope.`,
+				code: "SCOPE_MISSING",
+				details: { requiredScope: wanted }
+			} }, 403);
+		}
+		return next();
+	};
+}
 //#endregion
 //#region src/functions/runtime-env.ts
 /**
@@ -632,9 +715,11 @@ function isProduction() {
 * not be undone, because the originals were gone.
 */
 var configuredLevel;
+/** Every line to stderr, when a command's stdout is its result. See {@link setLogOutput}. */
+var everyLineToStderr = false;
 function getMinLevel() {
 	if (configuredLevel) return configuredLevel;
-	const env = (hostEnv().LOG_LEVEL || "info").toLowerCase();
+	const env = (hostEnv().LOG_LEVEL || "info").trim().toLowerCase();
 	if (env in LOG_PRIORITY) return env;
 	return "info";
 }
@@ -853,13 +938,13 @@ function createLogger(rawDefaultFields = {}) {
 				...merged
 			};
 			const line = JSON.stringify(entry);
-			if (level === "error") writeLine("err", line);
+			if (level === "error" || everyLineToStderr) writeLine("err", line);
 			else writeLine("out", line);
 		} else {
 			const prefix = level === "error" ? "❌" : level === "warn" ? "⚠️" : level === "info" ? "ℹ️" : "🐛";
 			const extra = Object.keys(merged).length > 0 ? ` ${JSON.stringify(merged)}` : "";
 			const out = `${prefix} [${level.toUpperCase()}] ${safeMessage}${extra}`;
-			if (level === "error") console.error(out);
+			if (level === "error" || everyLineToStderr) console.error(out);
 			else if (level === "warn") console.warn(out);
 			else console.log(out);
 		}
@@ -950,6 +1035,8 @@ function logBackgroundFailure(c, error) {
 }
 //#endregion
 //#region src/api/errors.ts
+/** What a caller is told when the database cannot be reached. Retryable, and not about them. */
+var DATABASE_UNAVAILABLE_MESSAGE = "The database could not be reached, so this request was not served. Retry shortly; if it keeps happening, the server's database is down or unreachable from it.";
 /**
 * Standardized API error class.
 * Throw this from any route handler — the errorHandler middleware
@@ -1022,8 +1109,19 @@ var ApiError = class ApiError extends Error {
 	static serviceUnavailable(message, code = "SERVICE_UNAVAILABLE") {
 		return new ApiError(503, code, message);
 	}
+	/**
+	* `503 DATABASE_UNAVAILABLE`: the database could not be reached. What
+	* every door answers then — the data API, sign-in, the admin routes and
+	* the realtime socket — so a client sees one retryable answer, sent with
+	* `Retry-After`, rather than a permission failure or a crash.
+	*
+	* @see isDatabaseUnreachable
+	*/
+	static databaseUnavailable(message = DATABASE_UNAVAILABLE_MESSAGE) {
+		return new ApiError(503, "DATABASE_UNAVAILABLE", message);
+	}
 };
 //#endregion
-export { ApiError, defineFunction, env, getApiKey, getDriver, getEnv, getRequestId, getRoles, getUser, getUserId, hasRole, identityResolved, isAdmin, isAuthenticated, isNodeRuntime, lazyResource, rebase, requireAdmin, requireAuth, requireDriver, requireEnv, requireRole, runtimeKey, waitUntil };
+export { ApiError, defineFunction, env, getApiKey, getDriver, getEnv, getRequestId, getRoles, getScopes, getSignal, getUser, getUserId, hasRole, hasScope, identityResolved, isAdmin, isAuthenticated, isNodeRuntime, lazyResource, rebase, requireAdmin, requireAuth, requireDriver, requireEnv, requireRole, requireScope, runtimeKey, waitUntil };
 
 //# sourceMappingURL=index.js.map