@rebasepro/server 0.28.0 → 0.28.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Plan, then confirm: a tool that changes something takes two calls.
3
+ *
4
+ * A tool that declares `confirm` (see {@link McpToolDefinition.confirm}) does
5
+ * nothing on its first call. It validates the arguments, checks what the
6
+ * real call would check, and answers a plan — what will happen, to what, and
7
+ * whether it can be undone — with a token. Only a second call carrying the
8
+ * same arguments and that token runs it.
9
+ *
10
+ * The token is bound to everything that decides what the call does:
11
+ *
12
+ * - the account (`uid`) and the connection (`clientId`) it was planned for,
13
+ * - the tool,
14
+ * - the arguments, as a hash of their canonical JSON — a call that changes
15
+ * one field between plan and confirm is refused, never run as the new one,
16
+ * - this endpoint (`aud`), so a plan made on one backend confirms nothing on
17
+ * another,
18
+ * - five minutes,
19
+ *
20
+ * and it is spent once: its `jti` is recorded on use, and a second use is
21
+ * refused ({@link McpConfirmationStore}).
22
+ *
23
+ * What this does and does not prove. It makes a destructive action
24
+ * impossible in one call, so an instruction injected into a row or a log line
25
+ * cannot trigger one outright; it pins exactly what was shown; and it puts the
26
+ * plan in the transcript, where the person sees it. It cannot prove a person
27
+ * said yes — a model can call twice. That check is the host's: a tool marked
28
+ * `destructiveHint` is one a host such as Claude asks the person about before
29
+ * it runs.
30
+ *
31
+ * The second call runs the tool from the top, so every permission it checks
32
+ * is checked again, as it is then: a demotion between the two calls refuses.
33
+ *
34
+ * @module
35
+ */
36
+ import type { JwtService } from "../auth/jwt.js";
37
+ import { type McpToolDefinition } from "./mcp-tools.js";
38
+ /** The argument the second call carries the token in. */
39
+ export declare const CONFIRM_ARGUMENT = "confirm";
40
+ /** The `purpose` of a confirmation token: never a session, never an MCP access token. */
41
+ export declare const MCP_CONFIRMATION_PURPOSE = "mcp-confirmation";
42
+ /** How long a plan can be confirmed for. Long enough to read it and say yes; not long enough to forget it. */
43
+ export declare const MCP_CONFIRMATION_TTL_SECONDS = 300;
44
+ /** What a tool's first call answers: what the second will do. */
45
+ export interface McpConfirmationPlan {
46
+ /** One sentence: the action, its target, and where (which project, which collection). */
47
+ summary: string;
48
+ /** What follows from it, one consequence per line. */
49
+ effects?: string[];
50
+ /** Whether and how it can be undone. */
51
+ reversible?: string;
52
+ /** Anything the person should see to decide — the row as it is, the change, a deployment's commit. */
53
+ details?: Record<string, unknown>;
54
+ }
55
+ /**
56
+ * Where a spent confirmation is recorded, so it is spent once across every
57
+ * replica. `consume` answers whether this was the first use.
58
+ */
59
+ export interface McpConfirmationStore {
60
+ consumeConfirmation(jti: string, expiresAt: Date): Promise<boolean>;
61
+ }
62
+ /**
63
+ * One process's memory of spent confirmations: what serves when no database
64
+ * does (tests, a store-less harness). A backend with replicas uses the
65
+ * database's, so a token spent on one replica is spent on all.
66
+ */
67
+ export declare function memoryConfirmationStore(): McpConfirmationStore;
68
+ /**
69
+ * The arguments as one string, independent of key order: objects with their
70
+ * keys sorted, at every depth. Two calls that mean the same thing hash the
71
+ * same; two that differ in any value do not.
72
+ */
73
+ export declare function canonicalArguments(value: unknown): string;
74
+ export interface ConfirmationDeps {
75
+ jwt: JwtService;
76
+ store: McpConfirmationStore;
77
+ /** This endpoint's canonical resource URI: a plan confirms on the endpoint that made it. */
78
+ audience: string;
79
+ }
80
+ /**
81
+ * The tool, taking two calls. Its schema gains the {@link CONFIRM_ARGUMENT}
82
+ * argument; its first call answers the plan, its second runs it.
83
+ */
84
+ export declare function withConfirmation(tool: McpToolDefinition, deps: ConfirmationDeps): McpToolDefinition;
@@ -32,9 +32,12 @@
32
32
  * client name is the registrant's to choose, so "“Claude” wants access"
33
33
  * can be anyone. The redirect host cannot, and the page names it.
34
34
  * 7. **Let every account that can sign in consent.** An account with a second
35
- * factor finishes here through the existing MFA routes; an account that
36
- * has only ever used Google, GitHub or an email link is told how to get a
37
- * password, rather than shown an error it cannot act on.
35
+ * factor finishes here through the existing MFA routes. Someone already
36
+ * signed in to this app's own frontend in this browser — with Google,
37
+ * GitHub, an email link or a password — consents as that account (see
38
+ * `refreshUrl`). An account with only a social sign-in and no session here
39
+ * is told how to get a password, rather than shown an error it cannot act
40
+ * on.
38
41
  * 8. **Refuse to be framed.** See {@link consentPageHeaders} — a consent screen
39
42
  * that can be iframed is a consent screen an attacker can have clicked.
40
43
  */
@@ -58,6 +61,17 @@ export interface ConsentPageParams {
58
61
  */
59
62
  mfaChallengeUrl: string;
60
63
  mfaVerifyUrl: string;
64
+ /**
65
+ * The existing `POST /auth/refresh`. When this app's own frontend keeps a
66
+ * session in this browser (the SDK's `rebase_auth` in `localStorage`, on
67
+ * this same origin), the page offers to consent as that account: on
68
+ * Allow — never before, and never without the press — it uses the
69
+ * session's access token, or renews it here when it has expired and
70
+ * hands the renewed pair back to the frontend's storage. This is how an
71
+ * account that signs in with Google or GitHub consents without a
72
+ * password: the Rebase Cloud console and its connector share an origin.
73
+ */
74
+ refreshUrl?: string;
61
75
  /**
62
76
  * Where the authorization code goes once the person allows.
63
77
  *
@@ -23,13 +23,19 @@
23
23
  * 401, and a token too narrow for the tool it names is 403 `insufficient_scope`.
24
24
  */
25
25
  import { Hono } from "hono";
26
+ import type { HonoRequest } from "hono";
26
27
  import type { AuthAdapter, CollectionConfig, DataDriver } from "@rebasepro/types";
27
28
  import type { HonoEnv } from "../api/types.js";
28
29
  import { type JwtService } from "../auth/jwt.js";
29
30
  import { type DataRateLimitConfig } from "../auth/rate-limiter.js";
31
+ import { type McpScopeVocabulary } from "./oauth-metadata.js";
32
+ import { type McpCaller, type McpToolDefinition } from "./mcp-tools.js";
33
+ import { type McpConfirmationStore } from "./confirmation.js";
30
34
  import { type McpAppsSource } from "./mcp-apps.js";
31
35
  import type { ApiKeyIdentity, ApiKeyRefusal } from "../auth/api-keys/api-key-middleware.js";
32
36
  import type { McpGrantIdentity } from "./oauth-routes.js";
37
+ /** What `initialize` tells a client about the default data tools. */
38
+ export declare const DEFAULT_MCP_INSTRUCTIONS: string;
33
39
  /**
34
40
  * The most messages one JSON-RPC batch may carry.
35
41
  *
@@ -97,6 +103,32 @@ export interface McpRoutesConfig {
97
103
  * offered. See `mcp-apps.ts`.
98
104
  */
99
105
  apps?: McpAppsSource;
106
+ /**
107
+ * The tools this endpoint serves, in place of the default data tools
108
+ * (`MCP_TOOLS`). Each still refuses an argument it does not declare, and
109
+ * is offered only to a grant holding its `requiredScope`.
110
+ */
111
+ tools?: readonly McpToolDefinition[];
112
+ /** What `initialize` tells the client. {@link DEFAULT_MCP_INSTRUCTIONS} when omitted. */
113
+ instructions?: string;
114
+ /** The scopes a grant may hold. The data vocabulary when omitted. */
115
+ vocabulary?: McpScopeVocabulary;
116
+ /**
117
+ * Where a confirmed call's token is spent (`confirmation.ts`). The OAuth
118
+ * store's table on a backend; this process's memory when omitted, which
119
+ * is single-use only within one process.
120
+ */
121
+ confirmations?: McpConfirmationStore;
122
+ /**
123
+ * Decide who a request is, in place of the OAuth token and `rk_` key
124
+ * checks. A refusal is answered 401 with its words and a bare `Bearer`
125
+ * challenge — there is no authorization server to point at. The
126
+ * platform's endpoint (`platform-mcp.ts`) accepts platform tokens this
127
+ * way, and nothing else.
128
+ */
129
+ authenticate?(request: HonoRequest): Promise<McpCaller | {
130
+ refusal: string;
131
+ }>;
100
132
  }
101
133
  /**
102
134
  * The `.well-known` documents.
@@ -22,7 +22,7 @@
22
22
  * a row the user could not write themselves.
23
23
  */
24
24
  import type { AuthAdapter, CallerCredential, CollectionConfig, DataDriver } from "@rebasepro/types";
25
- import type { McpScope } from "./oauth-metadata.js";
25
+ import type { McpConfirmationPlan } from "./confirmation.js";
26
26
  /** The identity a tool call runs as. Comes from the verified access token. */
27
27
  export interface McpCaller {
28
28
  uid: string;
@@ -48,15 +48,35 @@ export interface McpToolContext {
48
48
  */
49
49
  authAdapter?: AuthAdapter;
50
50
  }
51
+ /**
52
+ * What a host may assume about a tool, sent with it on `tools/list` (MCP's
53
+ * `ToolAnnotations`). Hints, not guarantees: a host uses them to decide
54
+ * whether to ask the person before a call — Claude asks before any tool not
55
+ * marked read-only — and the server never relies on a host honouring them.
56
+ */
57
+ export interface McpToolAnnotations {
58
+ /** It changes nothing. A host may call it without asking. */
59
+ readOnlyHint?: boolean;
60
+ /** It may overwrite or remove what exists, rather than only add. Meaningful when not read-only. */
61
+ destructiveHint?: boolean;
62
+ /** Calling it twice with the same arguments does no more than calling it once. */
63
+ idempotentHint?: boolean;
64
+ /** It reaches outside this server (the open web, a third party). */
65
+ openWorldHint?: boolean;
66
+ }
51
67
  export interface McpToolDefinition {
52
68
  name: string;
69
+ /** The tool's name for a person, where a host shows one. */
70
+ title?: string;
53
71
  description: string;
54
72
  inputSchema: Record<string, unknown>;
55
73
  /**
56
- * The scope a caller must hold — on at least one collection for the tool
57
- * to be listed, and on the collection a call names for it to run.
74
+ * The scope a caller must hold — on at least one target for the tool to
75
+ * be listed. The data tools also check it on the collection a call names.
76
+ * A scope of the vocabulary the surface issues (see `McpScopeVocabulary`).
58
77
  */
59
- requiredScope: McpScope;
78
+ requiredScope: string;
79
+ annotations?: McpToolAnnotations;
60
80
  /**
61
81
  * Whether the reply carries the result a second time, as
62
82
  * `structuredContent`. The text block always carries it — it is what a
@@ -73,6 +93,15 @@ export interface McpToolDefinition {
73
93
  ui?: {
74
94
  resourceUri: string;
75
95
  };
96
+ /**
97
+ * Make the tool take two calls (`confirmation.ts`): the first answers the
98
+ * plan this returns and a token, and changes nothing; the second, with
99
+ * the same arguments and the token, runs {@link run}. For a tool that
100
+ * changes production or reaches outward. It must check what `run` will
101
+ * check, and throw {@link McpToolError} for what `run` would refuse, so a
102
+ * plan is never offered for a call that cannot happen.
103
+ */
104
+ confirm?(args: Record<string, unknown>, ctx: McpToolContext): Promise<McpConfirmationPlan>;
76
105
  run(args: Record<string, unknown>, ctx: McpToolContext): Promise<unknown>;
77
106
  }
78
107
  /** An error whose message is safe to hand back to the model. */
@@ -81,7 +110,12 @@ export declare class McpToolError extends Error {
81
110
  /** The `ui://` resource show_collection opens. Built by `@rebasepro/mcp-apps`. */
82
111
  export declare const COLLECTION_TABLE_URI = "ui://rebase/collection-table.html";
83
112
  export declare const MCP_TOOLS: McpToolDefinition[];
113
+ /**
114
+ * The tool, refusing any argument it does not declare. Every tool `/mcp`
115
+ * serves goes through this — the default data tools and an app's own.
116
+ */
117
+ export declare function declaredArgumentsOnly(tool: McpToolDefinition): McpToolDefinition;
84
118
  /** The tools a caller holding `scopes` may see and call: each needs its scope on at least one collection. */
85
- export declare function toolsForScopes(scopes: readonly string[]): McpToolDefinition[];
119
+ export declare function toolsForScopes(scopes: readonly string[], tools?: readonly McpToolDefinition[]): McpToolDefinition[];
86
120
  /** Look up a tool by name, honouring scope — an unlisted tool is not callable. */
87
- export declare function findTool(name: string, scopes: readonly string[]): McpToolDefinition | undefined;
121
+ export declare function findTool(name: string, scopes: readonly string[], tools?: readonly McpToolDefinition[]): McpToolDefinition | undefined;
@@ -12,6 +12,28 @@ export declare const MCP_SCOPES: readonly ["data:read", "data:write", "data:dele
12
12
  export type McpScope = (typeof MCP_SCOPES)[number];
13
13
  /** The scope a client gets when it asks for nothing in particular. */
14
14
  export declare const DEFAULT_MCP_SCOPE = "data:read";
15
+ /**
16
+ * The scopes one MCP surface issues: what a client may ask for, what it gets
17
+ * when it asks for nothing, and how the consent screen words each.
18
+ *
19
+ * A backend serves the data vocabulary ({@link DATA_SCOPE_VOCABULARY}) unless
20
+ * it supplies its own tools, and with them the scopes those tools need — the
21
+ * Rebase Cloud control plane issues `project:*`. A scope outside the
22
+ * vocabulary is dropped from a request, never granted.
23
+ */
24
+ export interface McpScopeVocabulary {
25
+ /** Every scope a grant may hold, each with the line the consent screen shows for it. */
26
+ supported: readonly {
27
+ scope: string;
28
+ description: string;
29
+ }[];
30
+ /** What a client that asks for nothing gets. One of `supported`. */
31
+ defaultScope: string;
32
+ }
33
+ /** The data-plane vocabulary: `/mcp`'s own, and every backend's unless it brings its own tools. */
34
+ export declare const DATA_SCOPE_VOCABULARY: McpScopeVocabulary;
35
+ /** The scope names a vocabulary issues. */
36
+ export declare function supportedScopes(vocabulary: McpScopeVocabulary): string[];
15
37
  /**
16
38
  * A scope string as granted before `/mcp` spoke the shared vocabulary, read as
17
39
  * what it granted: `mcp:read` was every read, `mcp:write` every create, change
@@ -48,7 +70,7 @@ export interface ProtectedResourceMetadata {
48
70
  bearer_methods_supported: string[];
49
71
  resource_documentation?: string;
50
72
  }
51
- export declare function protectedResourceMetadata(publicUrl: string, mcpPath?: string): ProtectedResourceMetadata;
73
+ export declare function protectedResourceMetadata(publicUrl: string, mcpPath?: string, vocabulary?: McpScopeVocabulary): ProtectedResourceMetadata;
52
74
  export interface AuthorizationServerMetadata {
53
75
  issuer: string;
54
76
  authorization_endpoint: string;
@@ -64,7 +86,7 @@ export interface AuthorizationServerMetadata {
64
86
  authorization_response_iss_parameter_supported: boolean;
65
87
  service_documentation?: string;
66
88
  }
67
- export declare function authorizationServerMetadata(publicUrl: string, oauthBasePath: string): AuthorizationServerMetadata;
89
+ export declare function authorizationServerMetadata(publicUrl: string, oauthBasePath: string, vocabulary?: McpScopeVocabulary): AuthorizationServerMetadata;
68
90
  /**
69
91
  * Verify a PKCE code verifier against the challenge recorded at authorize time.
70
92
  *
@@ -101,7 +123,7 @@ export declare function redirectUriAllowed(candidate: string, registered: string
101
123
  * entitled to and none of the ones it invented. A collection target is kept:
102
124
  * `data:read:posts` is a narrower grant, never a wider one.
103
125
  */
104
- export declare function narrowScope(requested: string | undefined | null): string;
126
+ export declare function narrowScope(requested: string | undefined | null, vocabulary?: McpScopeVocabulary): string;
105
127
  /** A granted scope string as the list of scopes it holds. */
106
128
  export declare function scopeList(scope: string): string[];
107
129
  /**
@@ -28,6 +28,7 @@ import type { HonoEnv } from "../api/types.js";
28
28
  import { type JwtService } from "../auth/jwt.js";
29
29
  import type { AuthRepository } from "../auth/interfaces.js";
30
30
  import type { OAuthStore } from "./oauth-store.js";
31
+ import { type McpScopeVocabulary } from "./oauth-metadata.js";
31
32
  export interface OAuthRoutesConfig {
32
33
  store: OAuthStore;
33
34
  /**
@@ -49,6 +50,8 @@ export interface OAuthRoutesConfig {
49
50
  * repository, and then a grant carries the roles it was consented with.
50
51
  */
51
52
  identity?: McpGrantIdentity;
53
+ /** The scopes this server issues and how consent words them. The data vocabulary when omitted. */
54
+ vocabulary?: McpScopeVocabulary;
52
55
  }
53
56
  /**
54
57
  * The account a grant acts for, read where a grant is issued or renewed.
@@ -86,7 +89,7 @@ export declare function redirectUriProblem(uri: string): string | null;
86
89
  * they need to read here is that the client gets *their own* access and no
87
90
  * more, and which collections it reaches when the grant names some.
88
91
  */
89
- export declare function describeScopes(scope: string): {
92
+ export declare function describeScopes(scope: string, vocabulary?: McpScopeVocabulary): {
90
93
  scope: string;
91
94
  description: string;
92
95
  }[];
@@ -20,7 +20,7 @@
20
20
  */
21
21
  import type { DataDriver } from "@rebasepro/types";
22
22
  /** Every table this store owns, for the revoke sweep and for tests. */
23
- export declare const OAUTH_TABLES: readonly ["rebase.oauth_clients", "rebase.oauth_authorization_codes", "rebase.oauth_refresh_tokens", "rebase.oauth_consents"];
23
+ export declare const OAUTH_TABLES: readonly ["rebase.oauth_clients", "rebase.oauth_authorization_codes", "rebase.oauth_refresh_tokens", "rebase.oauth_consents", "rebase.mcp_confirmations"];
24
24
  /**
25
25
  * How long an authorization code lives.
26
26
  *
@@ -152,6 +152,12 @@ export interface OAuthStore {
152
152
  * than implying an instant cut-off.
153
153
  */
154
154
  revokeGrant(uid: string, clientId: string): Promise<boolean>;
155
+ /**
156
+ * Spend a tool call's confirmation (`confirmation.ts`): true the first
157
+ * time a `jti` is presented, false after. One row per confirmed call,
158
+ * kept until its token could no longer verify anyway.
159
+ */
160
+ consumeConfirmation(jti: string, expiresAt: Date): Promise<boolean>;
155
161
  }
156
162
  /** One row of the "applications you have connected" list. */
157
163
  export interface GrantSummary {
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The platform's MCP endpoint: `POST /api/admin/mcp`, for platform tokens only.
3
+ *
4
+ * The hosted Rebase connector (docs/hosted-mcp-connector.md) lets a developer
5
+ * reach their Cloud projects' data from one MCP connection. The control plane
6
+ * does not run the data tools itself: it signs a platform token for the
7
+ * person and the project (`auth/platform-token.ts`) and forwards the call
8
+ * here, where the app's own MCP tools (`mcp-tools.ts`) run it — with this
9
+ * app's collections, callbacks, auth-collection rules and RLS, at the version
10
+ * that is deployed.
11
+ *
12
+ * What it accepts: an `rpt_` token verified against the platform's public key
13
+ * and this project's audience, granted at most {@link PLATFORM_MCP_SCOPES}.
14
+ * Nothing else — no OAuth access token, no `rk_` key, no session. It serves no
15
+ * discovery documents: no third party is meant to find it.
16
+ *
17
+ * Who a call runs as: `platform:<sub>` with the `admin` role, under RLS (the
18
+ * default policies' admin arm passes; `serverContext()` does not). That is the
19
+ * reach of the identity the platform's Studio uses, and the control plane
20
+ * grants it to the same people: the project's organization owners and admins,
21
+ * with Studio switched on for the project.
22
+ *
23
+ * Independent of `REBASE_MCP_ENABLED`: that is the app owner's decision to
24
+ * hand credentials to third-party software, and turning this on hands none.
25
+ *
26
+ * @module
27
+ */
28
+ import type { Hono } from "hono";
29
+ import type { HonoEnv } from "../api/types.js";
30
+ import { type PlatformTokenConfig } from "../auth/platform-token.js";
31
+ import { type McpRoutesConfig } from "./mcp-routes.js";
32
+ /** Where it is mounted, under `basePath`. */
33
+ export declare const PLATFORM_MCP_PATH = "/admin/mcp";
34
+ export type PlatformMcpConfig = Omit<McpRoutesConfig, "authenticate" | "resolveApiKey" | "identity" | "jwt" | "tools" | "vocabulary"> & {
35
+ platformTokens: PlatformTokenConfig;
36
+ };
37
+ export declare function createPlatformMcpRoutes(config: PlatformMcpConfig): Hono<HonoEnv>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rebasepro/server",
3
- "version": "0.28.0",
3
+ "version": "0.28.2",
4
4
  "description": "Database-Agnostic Backend Core for Rebase",
5
5
  "keywords": [
6
6
  "rebase",
@@ -54,10 +54,10 @@
54
54
  "jsonwebtoken": "^9.0.3",
55
55
  "ws": "^8.21.1",
56
56
  "zod": "^4.4.3",
57
- "@rebasepro/client": "0.28.0",
58
- "@rebasepro/common": "0.28.0",
59
- "@rebasepro/types": "0.28.0",
60
- "@rebasepro/utils": "0.28.0"
57
+ "@rebasepro/client": "0.28.2",
58
+ "@rebasepro/common": "0.28.2",
59
+ "@rebasepro/utils": "0.28.2",
60
+ "@rebasepro/types": "0.28.2"
61
61
  },
62
62
  "devDependencies": {
63
63
  "@jest/globals": "^30.4.1",