@rebasepro/server 0.22.0 → 0.24.0

package/dist/{function-routes-Chet4-lB.js → function-routes-CaNG4waN.js}

@@ -3,9 +3,28 @@ import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
 import { n as __exportAll } from "./rolldown-runtime-dW7B1o5h.js";
-import { t as ApiError } from "./errors-DWsX4yTd.js";
-import { n as hasAdministrativeRole } from "./admin-roles-vYdp_Pil.js";
+import { t as ApiError } from "./errors-D6_y86c5.js";
 import { Hono } from "hono";
+//#region src/auth/admin-roles.ts
+/**
+* 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.
+*/
+/** 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);
+}
+//#endregion
 //#region src/functions/context.ts
 function read(c, key) {
 	return c.get(key);
@@ -56,16 +75,9 @@ function hasRole(c, ...roles) {
 	const held = new Set(getRoles(c));
 	return roles.some((role) => held.has(role));
 }
-/**
-* 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.
-*/
+/** Whether the caller holds the `admin` role, which holds every scope. */
 function isAdmin(c) {
-	return hasAdministrativeRole(getRoles(c));
+	return holdsAdminRole(getRoles(c));
 }
 /** Whether the request carries an identity at all. */
 function isAuthenticated(c) {
@@ -264,4 +276,4 @@ function createFunctionRoutes(functions, problems = [], mountPath = "/functions"
 //#endregion
 export { getDriver as a, getUser as c, identityResolved as d, isAdmin as f, getApiKey as i, getUserId as l, requireDriver as m, function_routes_exports as n, getRequestId as o, isAuthenticated as p, requireRole as r, getRoles as s, createFunctionRoutes as t, hasRole as u };
 
-//# sourceMappingURL=function-routes-Chet4-lB.js.map
+//# sourceMappingURL=function-routes-CaNG4waN.js.map

package/dist/function-routes-CaNG4waN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-routes-CaNG4waN.js","names":[],"sources":["../src/auth/admin-roles.ts","../src/functions/context.ts","../src/functions/guards.ts","../src/functions/function-routes.ts"],"sourcesContent":["/**\n * The admin role and scope matching, for code that may not import\n * `@rebasepro/types`.\n *\n * The custom-functions surface (`@rebasepro/server/functions`) must bundle for\n * a runtime with no Node built-ins and imports nothing but `hono`, so its\n * guards cannot reach the canonical definitions in `@rebasepro/types`\n * (`ADMIN_ROLE`, `hasAdminRole`, `scopeGrants`). These are the same rules,\n * restated, and `test/admin-roles.test.ts` holds them equal.\n *\n * Everything else imports the `@rebasepro/types` versions.\n */\n\n/** The one built-in role. It holds every scope. */\nexport const ADMIN_ROLE_NAME = \"admin\";\n\n/** Does this list of roles include the admin role? */\nexport function holdsAdminRole(roles: readonly string[] | null | undefined): boolean {\n    return !!roles?.includes(ADMIN_ROLE_NAME);\n}\n\n/**\n * Does a set of held scopes grant `scope`, optionally on one `target`? The\n * unqualified grant covers every target; `scope:target` covers its own.\n */\nexport function heldScopesGrant(held: readonly string[], scope: string, target?: string): boolean {\n    for (const entry of held) {\n        if (entry === scope) return true;\n        if (target !== undefined && entry === `${scope}:${target}`) return true;\n    }\n    return false;\n}\n","/**\n * Reading the request context from inside a custom function.\n *\n * The functions router resolves the caller's identity before any handler runs\n * and leaves the result on the Hono context. Getting it back out used to be the\n * user's problem, and the shape made that worse than it sounds: `HonoEnv`\n * types `user` as `AuthResult`, a union that includes `boolean`, `null` and an\n * index signature, because the same slot is filled by four different middlewares\n * — JWT, service key, API key, and a user-supplied validator that may return\n * `true`. Every example in the documentation therefore opened with\n *\n *     const user = c.get(\"user\") as { uid: string; roles?: string[] } | undefined;\n *\n * and an assertion in a security-relevant position is exactly the kind of line\n * that gets copied once and then never re-examined. It is also wrong in one\n * case that occurs in practice: a custom validator returning `true` stores\n * `{ uid: \"default\", roles: [] }`, which the assertion above types as having a\n * `uid` — true here, but nothing checks it.\n *\n * These accessors do the narrowing once, in the framework, where it can be\n * tested. They are also **runtime-neutral by construction** — no crypto, no\n * token parsing, no I/O, nothing but property reads on an object another\n * middleware already populated. That is what lets them live in\n * `@rebasepro/server/functions` and run unchanged on a host that has no Node\n * built-ins.\n *\n * @module\n */\nimport type { Context } from \"hono\";\nimport type { DataDriver } from \"@rebasepro/types\";\nimport type { HonoEnv } from \"../api/types\";\nimport type { ApiKeyMasked } from \"../auth/api-keys/api-key-types\";\nimport { heldScopesGrant, holdsAdminRole } from \"../auth/admin-roles\";\n\n/**\n * The caller, as a custom function sees them.\n *\n * A narrowed view of whatever the auth middleware resolved: `uid` and `roles`\n * are guaranteed, and the index signature keeps any extra claims the token or\n * the adapter carried (`email`, `org_id`, anything a custom validator added)\n * reachable without a cast.\n */\nexport interface FunctionUser {\n    /** Stable id of the caller. `\"service\"` for service-key and API-key callers. */\n    uid: string;\n    /** Roles as resolved for this request. Never `undefined` — an empty array instead. */\n    roles: string[];\n    /** Present when the identity carried one. Not every auth method does. */\n    email?: string;\n    /** Any further claim the token, adapter or validator supplied. */\n    [claim: string]: unknown;\n}\n\n/** Anything with a Hono-style `.get`, so these work on any `Context` shape. */\ntype CtxLike = Context<HonoEnv> | Context;\n\nfunction read<K extends keyof HonoEnv[\"Variables\"]>(\n    c: CtxLike,\n    key: K\n): HonoEnv[\"Variables\"][K] | undefined {\n    // `c.get` is typed against the app's own Env, which a handler mounted\n    // through `app.route()` may have declared more loosely. The cast is\n    // confined to this one function rather than repeated at every call site.\n    return (c as Context<HonoEnv>).get(key);\n}\n\n/**\n * The authenticated caller, or `undefined` for an anonymous request.\n *\n * **`undefined` is not a permission decision.** The functions router mounts its\n * auth middleware with `requireAuth: false` on purpose — a webhook receiver has\n * no token to send — so an anonymous caller reaches the handler and reads\n * `undefined` here while the handler runs on regardless. Use {@link requireAuth}\n * (or a `!user` branch that returns 401) to make it a decision.\n *\n * A caller who presented a *bad* token never gets this far: both auth\n * middlewares reject an unverifiable token with 401 before the router is\n * reached, precisely so an expired session cannot be silently downgraded to an\n * anonymous one.\n */\nexport function getUser(c: CtxLike): FunctionUser | undefined {\n    const raw = read(c, \"user\");\n    if (!raw || typeof raw !== \"object\") return undefined;\n\n    const record = raw as Record<string, unknown>;\n    const uid = typeof record.uid === \"string\" ? record.uid : undefined;\n    if (uid === undefined) return undefined;\n\n    const roles = Array.isArray(record.roles)\n        ? record.roles.filter((role): role is string => typeof role === \"string\")\n        : [];\n\n    return { ...record,\n        uid,\n        roles } as FunctionUser;\n}\n\n/** The caller's id, or `undefined` when nobody is signed in. */\nexport function getUserId(c: CtxLike): string | undefined {\n    return getUser(c)?.uid;\n}\n\n/** The caller's roles. Empty for an anonymous request — never `undefined`. */\nexport function getRoles(c: CtxLike): string[] {\n    return getUser(c)?.roles ?? [];\n}\n\n/**\n * Whether the caller holds **any** of the named roles.\n *\n * Any rather than all, because that is what a route guard means by a list of\n * roles; require several by calling this more than once.\n */\nexport function hasRole(c: CtxLike, ...roles: string[]): boolean {\n    if (roles.length === 0) return false;\n    const held = new Set(getRoles(c));\n    return roles.some(role => held.has(role));\n}\n\n/** Whether the caller holds the `admin` role, which holds every scope. */\nexport function isAdmin(c: CtxLike): boolean {\n    return holdsAdminRole(getRoles(c));\n}\n\n/**\n * Everything the caller may do, as `resource:action[:target]` scope strings —\n * the data plane, the app's own `auth.scopes`, and whatever their roles (or\n * their API key) hold. Empty for an anonymous request.\n *\n * Resolved by the framework before the handler runs; `undefined` only when no\n * Rebase auth middleware ran (see {@link identityResolved}).\n */\nexport function getScopes(c: CtxLike): string[] | undefined {\n    return read(c, \"scopes\");\n}\n\n/**\n * Whether the caller holds `scope`, on `target` when one is given.\n *\n * For an app scope declared under `auth.scopes` — `project:deploy` — a\n * signed-in person always holds it, so this narrows only API keys and tokens.\n * Whether the *person* may deploy *this* project is still the handler's to\n * decide.\n */\nexport function hasScope(c: CtxLike, scope: string, target?: string): boolean {\n    return heldScopesGrant(getScopes(c) ?? [], scope, target);\n}\n\n/** Whether the request carries an identity at all. */\nexport function isAuthenticated(c: CtxLike): boolean {\n    return getUser(c) !== undefined;\n}\n\n/**\n * The request-scoped data driver: reads and writes run as **the caller**, with\n * your row-level security policies evaluated against their identity.\n *\n * This is the accessor to reach for when a function serves user-facing data.\n * `rebase.dataAsAdmin` is the other one, and it is not the same thing — it runs\n * as `{ uid: \"service\", roles: [\"admin\"] }` for every caller alike, which is\n * correct for trusted background work and wrong for a request.\n *\n * `undefined` only when no Rebase auth middleware ran (see\n * {@link identityResolved}); inside a function mounted by the framework it is\n * always present, anonymous requests included — they get an anon-scoped driver\n * so policies still have an identity to evaluate.\n */\nexport function getDriver(c: CtxLike): DataDriver | undefined {\n    return read(c, \"driver\");\n}\n\n/**\n * {@link getDriver}, but throws instead of handing back `undefined`.\n *\n * For the common case where a handler cannot proceed without it and would\n * otherwise write `c.get(\"driver\")!` — an assertion that turns a wiring problem\n * into `Cannot read properties of undefined (reading 'fetchCollection')` twenty\n * lines away from the cause.\n */\nexport function requireDriver(c: CtxLike): DataDriver {\n    const driver = getDriver(c);\n    if (!driver) {\n        throw new Error(\n            \"No request-scoped driver on this context. A Rebase auth middleware \" +\n            \"populates it before any custom function runs, so this means the handler \" +\n            \"was mounted outside the functions router — e.g. added to your own Hono \" +\n            \"app directly. Mount it from the functions directory, or use \" +\n            \"`rebase.dataAsAdmin` if the work is genuinely service-scoped.\"\n        );\n    }\n    return driver;\n}\n\n/**\n * The API key this request authenticated with, masked, or `undefined` when it\n * did not use one.\n *\n * Useful for attribution and for per-key behaviour. The permission check itself\n * has already happened — reaching a handler means the key was allowed to.\n */\nexport function getApiKey(c: CtxLike): ApiKeyMasked | undefined {\n    return read(c, \"apiKey\");\n}\n\n/**\n * The correlation id for this request — generated, or taken from an inbound\n * `X-Request-ID`.\n *\n * Log it. It is the only thing that ties a line written inside a function to\n * the framework's own lines for the same request.\n */\nexport function getRequestId(c: CtxLike): string | undefined {\n    return read(c, \"requestId\");\n}\n\n/**\n * Whether a Rebase auth middleware has run on this request.\n *\n * Both middlewares populate `driver` for *every* outcome, anonymous included,\n * and populate `user` whenever there is one. So \"neither is set\" does not mean\n * \"anonymous\" — it means nothing resolved the identity, and treating that as\n * anonymous is the dangerous reading. The guards use this to tell a genuinely\n * anonymous caller (401) from a misconfigured mount (500), because answering\n * 401 to the second sends whoever is debugging it to look at the token.\n */\nexport function identityResolved(c: CtxLike): boolean {\n    return read(c, \"user\") !== undefined || read(c, \"driver\") !== undefined;\n}\n","/**\n * Route guards for custom functions.\n *\n * These decide access from the identity the platform already resolved. They do\n * **not** verify tokens, and that division is the point rather than a\n * limitation:\n *\n * - Verifying a token needs a signing key, constant-time comparison and a\n *   revocation lookup. That is host work, it belongs to the process that holds\n *   the secret, and it is the part of the stack that cannot be made\n *   runtime-neutral without rewriting it against WebCrypto.\n * - Deciding whether *this* caller may call *this* route is application work.\n *   It needs nothing but the resolved identity, so it costs nothing to make it\n *   portable — and it is the half that lives in user code.\n *\n * Splitting there is what lets a function file compile and run unchanged on a\n * host with no Node built-ins, and it is why these live in\n * `@rebasepro/server/functions` while `verifyAccessToken` does not.\n *\n * **Inside the functions router these are equivalent to the guards exported\n * from the package root.** Both auth middlewares resolve the identity before\n * any handler runs: a valid credential populates `user`, an invalid one is\n * rejected with 401 by the middleware itself, and a missing one leaves `user`\n * unset. So the root `requireAuth`'s token-parsing branch is unreachable from a\n * function, and removing it changes no outcome. The one difference is a handler\n * mounted **outside** the framework's router, where no middleware ran: the root\n * guard would parse the `Authorization` header itself, and these refuse the\n * request with a 500 that names the wiring problem. Fail-closed, and legible.\n *\n * @module\n */\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport type { HonoEnv } from \"../api/types\";\nimport { getUser, isAdmin, getRoles, identityResolved, hasScope } from \"./context\";\n\n/**\n * The answer to \"a guard ran, but no middleware had resolved anything\".\n *\n * Deliberately a 500 and not a 401. A 401 tells the caller their credential is\n * the problem, and here the caller's credential was never looked at — sending\n * them to check their token is sending them to the one place the answer is not.\n */\nfunction unresolvedIdentity(): { error: { message: string; code: string } } {\n    return {\n        error: {\n            message:\n                \"This route's identity was never resolved: no Rebase auth middleware ran \" +\n                \"before the guard. A function loaded from the functions directory always \" +\n                \"has one. This usually means the Hono app was mounted onto your own \" +\n                \"server directly, bypassing the functions router.\",\n            code: \"AUTH_MIDDLEWARE_MISSING\"\n        }\n    };\n}\n\n/**\n * Reject anonymous callers with 401.\n *\n * Put it in the route's own middleware slot rather than `app.use(\"/*\", …)`:\n * `use()` covers only the routes declared *below* it, so a route appended later\n * — by you, months from now, at the bottom of the file — is silently\n * unprotected. The per-route form cannot drift that way.\n *\n * @example\n * ```ts\n * app.post(\"/\", requireAuth, async (c) => {\n *     const user = getUser(c)!;  // guaranteed by the guard\n *     return c.json({ uid: user.uid });\n * });\n * ```\n */\nexport const requireAuth: MiddlewareHandler<HonoEnv> = async (c, next) => {\n    if (getUser(c)) return next();\n    if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n\n    return c.json({\n        error: {\n            message: \"Authentication required\",\n            code: \"UNAUTHORIZED\"\n        }\n    }, 401);\n};\n\n/**\n * Reject callers without the `admin` role with 403.\n *\n * Must come **after** {@link requireAuth}: on its own it answers 401 for an\n * anonymous caller, which is right, but pairing them keeps the two failures\n * distinguishable — 401 \"who are you\", 403 \"not you\".\n *\n * Prefer {@link requireScope} for anything an app declares a scope for: a\n * scope can be granted to a narrower role and to a key, and `admin` cannot.\n */\nexport const requireAdmin: MiddlewareHandler<HonoEnv> = async (c, next) => {\n    const user = getUser(c);\n    if (!user) {\n        if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n        return c.json({\n            error: {\n                message: \"Authentication required\",\n                code: \"UNAUTHORIZED\"\n            }\n        }, 401);\n    }\n\n    if (!isAdmin(c)) {\n        return c.json({\n            error: {\n                message: \"Admin privileges required for this operation\",\n                code: \"FORBIDDEN\"\n            }\n        }, 403);\n    }\n\n    return next();\n};\n\n/**\n * Reject callers holding none of the named roles with 403.\n *\n * Any of them, not all — require several by chaining the guard twice. Naming no\n * role at all is a programming error and throws at module load rather than at\n * request time, because `requireRole()` with an empty list would otherwise read\n * as a guard while admitting everyone.\n *\n * @example\n * ```ts\n * app.post(\"/publish\", requireAuth, requireRole(\"editor\", \"admin\"), handler);\n * ```\n */\nexport function requireRole(...roles: string[]): MiddlewareHandler<HonoEnv> {\n    if (roles.length === 0) {\n        throw new Error(\n            \"requireRole() needs at least one role. An empty list would admit every \" +\n            \"signed-in caller while reading as a restriction.\"\n        );\n    }\n\n    const allowed = new Set(roles);\n    return async (c, next) => {\n        const user = getUser(c);\n        if (!user) {\n            if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n            return c.json({\n                error: {\n                    message: \"Authentication required\",\n                    code: \"UNAUTHORIZED\"\n                }\n            }, 401);\n        }\n\n        if (!getRoles(c).some(role => allowed.has(role))) {\n            return c.json({\n                error: {\n                    message: `This operation requires one of these roles: ${roles.join(\", \")}`,\n                    code: \"FORBIDDEN\"\n                }\n            }, 403);\n        }\n\n        return next();\n    };\n}\n\n/**\n * Reject callers who do not hold `scope` with 403.\n *\n * `scope` is a built-in scope or one the app declares under `auth.scopes` on\n * the users collection. `target` narrows it to one resource — a key holding\n * `project:deploy:p1` passes `requireScope(\"project:deploy\", c => c.req.param(\"project\"))`\n * for `p1` only — and may be read from the request.\n *\n * A signed-in person holds every app scope, so for a person this is no\n * authorization at all: it narrows API keys and tokens. Decide whether the\n * person may act in the handler, as you would without it.\n *\n * @example\n * ```ts\n * app.post(\"/deploy/:project\", requireAuth, requireScope(\"project:deploy\", c => c.req.param(\"project\")), handler);\n * ```\n */\nexport function requireScope(\n    scope: string,\n    target?: string | ((c: Context<HonoEnv>) => string | undefined)\n): MiddlewareHandler<HonoEnv> {\n    return async (c, next) => {\n        if (!getUser(c)) {\n            if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n            return c.json({\n                error: {\n                    message: \"Authentication required\",\n                    code: \"UNAUTHORIZED\"\n                }\n            }, 401);\n        }\n        const resolvedTarget = typeof target === \"function\" ? target(c) : target;\n        if (!hasScope(c, scope, resolvedTarget)) {\n            const wanted = resolvedTarget !== undefined ? `${scope}:${resolvedTarget}` : scope;\n            return c.json({\n                error: {\n                    message: `This credential does not hold the \"${wanted}\" scope.`,\n                    code: \"SCOPE_MISSING\",\n                    details: { requiredScope: wanted }\n                }\n            }, 403);\n        }\n        return next();\n    };\n}\n","import { Hono } from \"hono\";\nimport { HonoEnv } from \"../api/types\";\nimport { ApiError } from \"../api/errors\";\nimport { LoadedFunction } from \"./function-loader\";\nimport { requireAuth } from \"./guards\";\n\n/** The file a loader problem names, without its extension: `broken.ts (threw: …)` → `broken`. */\nfunction problemName(problem: string): string {\n    return problem.split(\" \")[0].replace(/\\/$/, \"\").replace(/\\.[cm]?[jt]s$/, \"\");\n}\n\n/**\n * Mount all loaded function routes under a single Hono router.\n *\n * Each function is mounted at `/<function-name>`, preserving\n * whatever HTTP methods and middleware the Hono sub-app defines.\n *\n * @param functions What loaded. May be empty — the router still mounts, so\n *   \"no functions are served\" answers 200 with an empty list instead of 404.\n * @param problems The files the loader saw and could not serve, as\n *   `\"<file> (<reason>)\"`. The listing reports a count and a pointer to the log,\n *   not the reasons: those carry import errors, and the listing is one guard\n *   away from anyone. The unmatched-route handler uses the *names* to answer the\n *   one question a 404 on a function nobody can find should answer — \"there is a\n *   file for this and it did not load\" — which is the difference between a typo\n *   and a broken deploy, and the loader was the only thing that knew.\n */\nexport function createFunctionRoutes(\n    functions: LoadedFunction[],\n    problems: string[] = [],\n    /**\n     * Where this router is mounted, so the listing can report a path a caller\n     * can actually request. It used to hardcode `/functions/<name>`, which is\n     * wrong under every `basePath` including the default `/api`.\n     */\n    mountPath = \"/functions\"\n): Hono<HonoEnv> {\n    const router = new Hono<HonoEnv>();\n    const skipped = problems.length;\n\n    // Listing endpoint: GET / → list available functions.\n    //\n    // Functions themselves stay anonymous-callable by default — a webhook\n    // receiver has to be — but the index of them does not: it is an inventory\n    // of every custom endpoint, for whoever asks. `requireAuth` admits any\n    // resolved identity (a signed-in user, an API key, the service key), so\n    // `rebase doctor` and `rebase cloud debug` keep their answer; the latter\n    // already reads a 401 here as \"mounted\".\n    router.get(\"/\", requireAuth, (c) => {\n        return c.json({\n            functions: functions.map((fn) => ({\n                name: fn.name,\n                endpoint: `${mountPath}/${fn.name}`\n            })),\n            ...(skipped > 0 && {\n                skipped,\n                note: `${skipped} function file(s) failed to load and are NOT served — see the server log for the reason.`\n            })\n        });\n    });\n\n    for (const fn of functions) {\n        router.route(`/${fn.name}`, fn.app);\n    }\n\n    // A name that matches nothing, answered in the envelope.\n    //\n    // Registered last so every real route wins it. Without it, a typo'd\n    // function name — the single most likely 404 a developer meets on this\n    // surface — fell through to Hono's default `404 Not Found` as `text/plain`,\n    // and through the SDK arrived as `RebaseApiError { code: undefined }`, so\n    // the documented `e.code === \"FUNCTION_NOT_FOUND\"` branch never ran.\n    //\n    // What the message may say depends on who is asking. The mounted names are\n    // an inventory of every custom endpoint, which is exactly what the listing\n    // above requires an identity to see — so an anonymous caller is told their\n    // name is unknown and nothing more, and a resolved caller gets the list\n    // that turns the 404 into a fix.\n    const mounted = new Set(functions.map(fn => fn.name));\n    const failedToLoad = new Map(problems.map(p => [problemName(p), p.split(\" \")[0]]));\n\n    router.all(\"/:name{.*}\", (c): never => {\n        const requested = (c.req.param(\"name\") ?? \"\").split(\"/\").filter(Boolean);\n        const name = requested[0] ?? \"\";\n        const rest = requested.slice(1).join(\"/\");\n        const identified = Boolean(c.get(\"user\"));\n\n        const refuse = (message: string): never => {\n            throw new ApiError(404, \"FUNCTION_NOT_FOUND\", message, { function: name }, true);\n        };\n\n        if (!name) {\n            refuse(`No function in the request path. Expected ${mountPath}/<function>.`);\n        }\n        if (mounted.has(name)) {\n            refuse(\n                `The function '${name}' is served, and has no ${c.req.method} route at '/${rest}'. ` +\n                \"The path after the function name is routed by the function's own Hono app.\"\n            );\n        }\n        const file = failedToLoad.get(name);\n        if (file) {\n            refuse(\n                `The function '${name}' is not served: '${file}' failed to load. ` +\n                \"The server log records why, at boot.\"\n            );\n        }\n        return refuse(\n            `No function named '${name}' on this backend.` +\n            (identified\n                ? (mounted.size > 0\n                    ? ` This backend serves: ${[...mounted].sort().join(\", \")}.`\n                    : \" This backend serves no functions.\")\n                : \"\") +\n            (skipped > 0 && identified\n                ? ` ${skipped} function file(s) failed to load and are not served — see the server log.`\n                : \"\")\n        );\n    });\n\n    return router;\n}\n"],"mappings":"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"}

package/dist/functions/context.d.ts

@@ -76,15 +76,26 @@ export declare function getRoles(c: CtxLike): string[];
  * roles; require several by calling this more than once.
  */
 export declare function hasRole(c: CtxLike, ...roles: string[]): boolean;
+/** Whether the caller holds the `admin` role, which holds every scope. */
+export declare function isAdmin(c: CtxLike): boolean;
 /**
- * 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}).
  */
-export declare function isAdmin(c: CtxLike): boolean;
+export declare function getScopes(c: CtxLike): string[] | undefined;
+/**
+ * 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.
+ */
+export declare function hasScope(c: CtxLike, scope: string, target?: string): boolean;
 /** Whether the request carries an identity at all. */
 export declare function isAuthenticated(c: CtxLike): boolean;
 /**

package/dist/functions/guards.d.ts

@@ -29,7 +29,7 @@
  *
  * @module
  */
-import type { MiddlewareHandler } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
 import type { HonoEnv } from "../api/types.js";
 /**
  * Reject anonymous callers with 401.
@@ -49,15 +49,14 @@ import type { HonoEnv } from "../api/types.js";
  */
 export declare const requireAuth: MiddlewareHandler<HonoEnv>;
 /**
- * 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.
  */
 export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
 /**
@@ -74,3 +73,21 @@ export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
  * ```
  */
 export declare function requireRole(...roles: string[]): MiddlewareHandler<HonoEnv>;
+/**
+ * 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);
+ * ```
+ */
+export declare function requireScope(scope: string, target?: string | ((c: Context<HonoEnv>) => string | undefined)): MiddlewareHandler<HonoEnv>;

package/dist/functions/index.d.ts

@@ -72,9 +72,9 @@ export type { RebaseFunctionContext } from "./define-function.js";
  * `../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, 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

@@ -233,31 +233,33 @@ function defineFunction(definition) {
 //#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 +312,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) {
@@ -428,15 +445,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 +499,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
 /**
@@ -634,7 +688,7 @@ function isProduction() {
 var configuredLevel;
 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";
 }
@@ -1024,6 +1078,6 @@ var ApiError = class ApiError extends Error {
 	}
 };
 //#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, getUser, getUserId, hasRole, hasScope, identityResolved, isAdmin, isAuthenticated, isNodeRuntime, lazyResource, rebase, requireAdmin, requireAuth, requireDriver, requireEnv, requireRole, requireScope, runtimeKey, waitUntil };
 
 //# sourceMappingURL=index.js.map