@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/mcp/mcp-tools.d.ts

@@ -16,16 +16,19 @@
  *  - A write can fail with a permission error the tool cannot explain in
  *    detail, because the policy that refused it is not visible from here.
  *
- * `mcp:write` gates whether the mutating tools are *offered* at all. It is a
- * second lock, not the main one — a `mcp:write` token still cannot write a row
- * the user could not write themselves.
+ * The scopes gate which tools are *offered* and which collections each
+ * reaches — `data:write:posts` offers the write tools for `posts` alone. That
+ * is a second lock, not the main one: a `data:write` token still cannot write
+ * a row the user could not write themselves.
  */
 import type { AuthAdapter, CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { McpScope } from "./oauth-metadata.js";
 /** The identity a tool call runs as. Comes from the verified access token. */
 export interface McpCaller {
     uid: string;
     roles: string[];
-    scope: string;
+    /** The scopes granted to this connection — `data:read`, `data:write:posts`, … */
+    scopes: string[];
     clientId: string;
 }
 export interface McpToolContext {
@@ -43,15 +46,26 @@ export interface McpToolDefinition {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
-    /** The scope a caller must hold for this tool to be listed or callable. */
-    requiredScope: "mcp:read" | "mcp:write";
+    /**
+     * The scope a caller must hold — on at least one collection for the tool
+     * to be listed, and on the collection a call names for it to run.
+     */
+    requiredScope: McpScope;
+    /**
+     * Whether the reply carries the result a second time, as
+     * `structuredContent`. The text block always carries it — it is what a
+     * model reads. A result a program consumes (rows, a count, a write's
+     * outcome) also goes out as typed data; one only a model reads does not,
+     * so the reply is not twice its size. Defaults to true.
+     */
+    structuredContent?: boolean;
     run(args: Record<string, unknown>, ctx: McpToolContext): Promise<unknown>;
 }
 /** An error whose message is safe to hand back to the model. */
 export declare class McpToolError extends Error {
 }
 export declare const MCP_TOOLS: McpToolDefinition[];
-/** The tools a caller holding `scope` may see and call. */
-export declare function toolsForScope(scope: string): McpToolDefinition[];
+/** The tools a caller holding `scopes` may see and call: each needs its scope on at least one collection. */
+export declare function toolsForScopes(scopes: readonly string[]): McpToolDefinition[];
 /** Look up a tool by name, honouring scope — an unlisted tool is not callable. */
-export declare function findTool(name: string, scope: string): McpToolDefinition | undefined;
+export declare function findTool(name: string, scopes: readonly string[]): McpToolDefinition | undefined;

package/dist/mcp/oauth-metadata.d.ts

@@ -1,20 +1,24 @@
 /**
- * What a token may do at `/mcp`.
+ * What a token may do at `/mcp`: the data-plane scopes its tools need, in the
+ * vocabulary every other credential uses — `data:read`, `data:write`,
+ * `data:delete` — each narrowable to one collection (`data:read:posts`).
  *
- * Two, and no more. RFC 9728 asks `scopes_supported` to be the minimal set that
- * makes the resource usable, and the MCP specification's scope-minimization
- * guidance points the same way: a client that only needs to read should be able
- * to ask for exactly that, and a consent screen listing eleven fine-grained
- * permissions is one nobody reads.
- *
- * They are not a substitute for RLS. A `mcp:read` token still reads through the
- * user's own policies — the scope decides whether the tool exists for this
- * session, the database decides which rows come back.
+ * They are not a substitute for RLS. A `data:read` token still reads through
+ * the user's own policies — the scope decides whether a tool exists for this
+ * session and which collections it reaches; the database decides which rows
+ * come back.
  */
-export declare const MCP_SCOPES: readonly ["mcp:read", "mcp:write"];
+export declare const MCP_SCOPES: readonly ["data:read", "data:write", "data:delete"];
 export type McpScope = (typeof MCP_SCOPES)[number];
 /** The scope a client gets when it asks for nothing in particular. */
-export declare const DEFAULT_MCP_SCOPE = "mcp:read";
+export declare const DEFAULT_MCP_SCOPE = "data:read";
+/**
+ * A scope string as granted before `/mcp` spoke the shared vocabulary, read as
+ * what it granted: `mcp:read` was every read, `mcp:write` every create, change
+ * and delete. Applied to stored refresh grants and to access tokens still in
+ * flight, so a connection made before the change keeps exactly its reach.
+ */
+export declare function upgradeStoredMcpScope(scope: string): string;
 /**
  * The canonical resource identifier for this server's MCP endpoint.
  *
@@ -93,12 +97,13 @@ export declare function redirectUriAllowed(candidate: string, registered: string
  *
  * An unknown scope is dropped rather than refused. RFC 6749 §3.3 allows either,
  * and dropping is what keeps a client that asks for `openid profile email` out
- * of habit from failing to connect at all — it gets the MCP scopes it is
- * entitled to and none of the ones it invented.
+ * of habit from failing to connect at all — it gets the data scopes it is
+ * entitled to and none of the ones it invented. A collection target is kept:
+ * `data:read:posts` is a narrower grant, never a wider one.
  */
 export declare function narrowScope(requested: string | undefined | null): string;
-/** Does a granted scope string carry this permission? */
-export declare function scopeAllows(scope: string, needed: McpScope): boolean;
+/** A granted scope string as the list of scopes it holds. */
+export declare function scopeList(scope: string): string[];
 /**
  * The `WWW-Authenticate` value for an unauthenticated request.
  *

package/dist/mcp/oauth-routes.d.ts

@@ -25,10 +25,17 @@
  */
 import { Hono } from "hono";
 import type { HonoEnv } from "../api/types.js";
+import { type JwtService } from "../auth/jwt.js";
 import type { AuthRepository } from "../auth/interfaces.js";
 import type { OAuthStore } from "./oauth-store.js";
 export interface OAuthRoutesConfig {
     store: OAuthStore;
+    /**
+     * The backend this authorization server issues for: its key signs the
+     * MCP access tokens and the authorize-request token, and verifies the
+     * person's session at consent. The process default when omitted.
+     */
+    jwt?: JwtService;
     /** The externally reachable origin of this deployment. */
     publicUrl: string;
     /** Where `/mcp` is mounted, e.g. `/mcp`. */
@@ -72,7 +79,13 @@ export declare function createOAuthRoutes(config: OAuthRoutesConfig): Hono<HonoE
  * means a stored row is never itself the hazard.
  */
 export declare function redirectUriProblem(uri: string): string | null;
-/** Human-readable consent lines, one per granted scope. */
+/**
+ * Human-readable consent lines, one per granted scope.
+ *
+ * Worded for the person consenting, not taken from the scope catalogue: what
+ * they need to read here is that the client gets *their own* access and no
+ * more, and which collections it reaches when the grant names some.
+ */
 export declare function describeScopes(scope: string): {
     scope: string;
     description: string;

package/dist/metrics/index.d.ts

@@ -31,11 +31,24 @@ export type MetricSurface = "data" | "auth" | "storage" | "functions" | "admin"
  | "other";
 /** Whether a path is the platform looking in, rather than a request served. */
 export declare function isUncountedPath(pathname: string): boolean;
+/**
+ * How long a query waited for a pooled database connection, in milliseconds —
+ * opening one included, when the pool had to. Labelled by data source. See
+ * `pool-wait.ts`, which records it, and why it matters there.
+ */
+export declare const DB_POOL_WAIT_METRIC = "rebase_db_pool_wait_ms";
+/**
+ * Buckets for {@link DB_POOL_WAIT_METRIC}. A checkout from a pool with an idle
+ * connection takes well under a millisecond, so the low end is finer than a
+ * request's: the interesting number is how much of the tail is above zero.
+ */
+export declare const POOL_WAIT_BUCKETS_MS: number[];
 export declare class MetricsRegistry {
     private requests;
     private latency;
     private gauges;
     private counters;
+    private histograms;
     readonly startedAt: number;
     private static labelKey;
     private static parseLabels;
@@ -51,6 +64,11 @@ export declare class MetricsRegistry {
     recordRequest(labels: Record<string, string>, durationMs: number): void;
     incrementCounter(name: string, labels?: Record<string, string>, by?: number): void;
     setGauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record one observation in a named histogram. `buckets` are its upper
+     * bounds, fixed by the first observation of the series.
+     */
+    observe(name: string, value: number, labels?: Record<string, string>, buckets?: readonly number[]): void;
     /** Prometheus escaping: backslash, quote and newline, in that order. */
     private static formatLabels;
     /** Group `name -> [[labelKey, value]]` for one-HELP-per-metric rendering. */

package/dist/metrics/pool-wait.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How long queries wait for a pooled database connection.
+ *
+ * A write holds its connection — and its transaction, and the locks it has
+ * taken — for as long as its callbacks run: `beforeSave` runs after the
+ * transaction has begun, `afterSave` before it commits. Callbacks that await
+ * something slow therefore take connections out of the pool for that long, and
+ * once enough of them run at once every other request queues for one. Measured
+ * with the default pool of 20: 25 concurrent saves whose `beforeSave` awaited
+ * 300 ms made an unrelated one-row read wait 290 ms for a connection.
+ *
+ * Nothing else shows that queue. Request latency rises, but so it does for a
+ * slow query; this histogram says how much of a request was spent waiting for
+ * a connection at all. Near zero is a healthy pool.
+ *
+ * @module
+ */
+import { type MetricsRegistry } from "./index.js";
+/** `pg.Pool`'s callback form of `connect`, which `pool.query` uses internally. */
+type ConnectCallback = (err: Error | undefined, client: unknown, done: (release?: unknown) => void) => void;
+/**
+ * `connect` as a `pg.Pool` has it: a promise without a callback, the callback
+ * with one. Both are timed — transactions check out with the first,
+ * `pool.query` with the second.
+ */
+export type PoolConnect = (callback?: ConnectCallback) => Promise<unknown> | void;
+/**
+ * Time every checkout from `pool`, from the call to the moment a connection is
+ * handed over, and report it to `record` in milliseconds. A failed checkout is
+ * not recorded: it is an error, not a wait.
+ *
+ * Wraps `connect` on this pool object only. `false` when the pool has no
+ * `connect` to time (a driver that is not pool-based) or is timed already.
+ */
+export declare function timePoolCheckouts(pool: {
+    connect?: PoolConnect;
+}, record: (waitMs: number) => void): boolean;
+/**
+ * Time the checkouts of every pool-based data source into `registry`'s
+ * {@link DB_POOL_WAIT_METRIC} histogram, labelled by the source's key.
+ */
+export declare function recordPoolWaits(registry: MetricsRegistry, sources: readonly {
+    key: string;
+    connection: {
+        pool?: {
+            connect?: PoolConnect;
+        };
+    };
+}[]): void;
+export {};