@raybase/create 0.3.19 → 0.3.21
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.
package/package.json
CHANGED
|
@@ -170,13 +170,20 @@ Expose the same action through the surfaces that need it instead of rewriting
|
|
|
170
170
|
the business rules. Worked adapter examples are in
|
|
171
171
|
[references/adapting-actions.md](references/adapting-actions.md).
|
|
172
172
|
|
|
173
|
-
- `mcpToolFromAction()`
|
|
174
|
-
`readOnlyHint` actions and `mcp:write`
|
|
175
|
-
|
|
173
|
+
- `mcpToolFromAction()` answers to `mcp:read` or `mcp:tool:<name>` for
|
|
174
|
+
`readOnlyHint` actions and to `mcp:write` or `mcp:tool:<name>` for mutating
|
|
175
|
+
ones. Pass `scopes` to require more: a token must hold every scope listed,
|
|
176
|
+
so `scopes: ["mcp:write", "acme:govern"]` is out of reach of a token that
|
|
177
|
+
holds only `mcp:write`. The tool advertises the action's `output` schema.
|
|
176
178
|
- `actionRoute()` registers the HTTP route and `serverFnFromAction()` exposes
|
|
177
179
|
the same endpoint to UI server functions.
|
|
180
|
+
- `api: { actions: [...], accessTokens: true }` lets a command-line tool or
|
|
181
|
+
another service call the same routes with `Authorization: Bearer`; see
|
|
182
|
+
Access Tokens On Action Routes below.
|
|
178
183
|
- `jobFromAction()` requires `enqueue` and `runAs`, re-evaluates policy when
|
|
179
|
-
the queue message runs, and rejects public-audience actions.
|
|
184
|
+
the queue message runs, and rejects public-audience actions. The Action's
|
|
185
|
+
`ctx.organizationId` is the organization the run is in, as on its route and
|
|
186
|
+
its connector tool, whatever `runAs` is (`"system"` included).
|
|
180
187
|
- Agents and Guide take explicit action arrays:
|
|
181
188
|
`defineAgent({ ..., actions: [...] })` and
|
|
182
189
|
`guideModule({ ..., actions: guideActions })`.
|
|
@@ -192,6 +199,52 @@ that allow-list or explicitly set `mode: "knowledge-only"` if Guide must not
|
|
|
192
199
|
perform app workflows. Register only intentional actions for each Agent or
|
|
193
200
|
Guide surface. Do not pass every app action to a model.
|
|
194
201
|
|
|
202
|
+
## Access Tokens On Action Routes
|
|
203
|
+
|
|
204
|
+
Action routes take a session cookie. To let a command-line tool or another
|
|
205
|
+
service call them, turn on access tokens beside the routes in
|
|
206
|
+
`raybase.server.ts`:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
api: {
|
|
210
|
+
actions: [actionRoute(actions.status), actionRoute(actions.setPolicy)],
|
|
211
|
+
accessTokens: true
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
It needs `mcp: { enabled: true }`, because the tokens are the app connector's
|
|
216
|
+
own: the ones `/mcp` accepts, from the authorization-code flow or a
|
|
217
|
+
`client_credentials` machine credential. It is off by default.
|
|
218
|
+
|
|
219
|
+
- A request with `Authorization: Bearer` is the token's call alone. Its
|
|
220
|
+
cookies are not read, and it skips the same-origin check a cookie needs.
|
|
221
|
+
A request without the header is a cookie request, exactly as before.
|
|
222
|
+
- A token reaches an action only when the connector offers the same action
|
|
223
|
+
as a tool (`mcpToolFromAction(actions.x)` in `mcp.tools`), and under that
|
|
224
|
+
tool's scopes. So a token does over HTTP what it does over MCP, and no
|
|
225
|
+
more. An action with a route and no tool answers a token with 403
|
|
226
|
+
(`action_not_offered`).
|
|
227
|
+
- A token call must pass the route's policy and row check and the tool's
|
|
228
|
+
(`mcpToolFromAction(action, { policy, rowAuthorization })`). Give the tool
|
|
229
|
+
the stricter policy when machine credentials should do less than people.
|
|
230
|
+
- Keep the tool `mcpToolFromAction()` made, or a `withMcpAppUi()` copy of
|
|
231
|
+
it. A copy that replaces its `handler` or `inputSchema` adds checks a
|
|
232
|
+
route can't repeat, so its action is not offered to tokens (403
|
|
233
|
+
`action_not_offered`). Put such checks in the action or its policy.
|
|
234
|
+
- A host-account grant's call runs in the grant's partition; any other
|
|
235
|
+
token runs in none, an operator's included. A token can't name a
|
|
236
|
+
partition (403 `partition_denied`).
|
|
237
|
+
- The action runs as the token's user, in the organization the request names
|
|
238
|
+
(`/o/<slug>/api/actions/<name>` on Raybase Pro), with what the tool's
|
|
239
|
+
`context` option adds. `ctx.surface` is `"http"`. A token bound to another
|
|
240
|
+
organization is refused.
|
|
241
|
+
- `ctx.auth` treats the call as it treats one over MCP: not a cookie session,
|
|
242
|
+
so `ctx.auth.signInLinks.create()` refuses.
|
|
243
|
+
- An invalid, expired or revoked token gets 401 with `WWW-Authenticate`. A
|
|
244
|
+
valid token without the tool's scopes gets 403 (`insufficient_scope`).
|
|
245
|
+
- The call is recorded on the grant (`tool.call`, with `surface: "http"`),
|
|
246
|
+
and the action's audit rows carry the grant and client.
|
|
247
|
+
|
|
195
248
|
## Audit Action Reachability
|
|
196
249
|
|
|
197
250
|
Audit every declared action after wiring adapters. For each action, identify at
|
|
@@ -14,6 +14,13 @@ export const mcpTools = [
|
|
|
14
14
|
];
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
+
A tool that must be out of reach of a token holding only `mcp:write` declares
|
|
18
|
+
what else it requires. Every scope listed is required:
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
mcpToolFromAction(actions.setPolicy, { scopes: ["mcp:write", "acme:govern"] })
|
|
22
|
+
```
|
|
23
|
+
|
|
17
24
|
HTTP route and UI server function:
|
|
18
25
|
|
|
19
26
|
```ts
|
|
@@ -30,6 +37,25 @@ export const approveRequest = serverFnFromAction(actions.approveRequest, {
|
|
|
30
37
|
});
|
|
31
38
|
```
|
|
32
39
|
|
|
40
|
+
The same route for a command-line tool, with the app connector's access
|
|
41
|
+
tokens. The action needs its tool in `mcp.tools`; the token is held to that
|
|
42
|
+
tool's scopes:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
createRaybaseApp({
|
|
46
|
+
// ...
|
|
47
|
+
mcp: { tools: mcpTools },
|
|
48
|
+
api: { actions: [approveRequestRoute], accessTokens: true }
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
curl -X POST https://app.example.com/api/actions/requests/approve \
|
|
54
|
+
-H "Authorization: Bearer $ACCESS_TOKEN" \
|
|
55
|
+
-H "Content-Type: application/json" \
|
|
56
|
+
-d '{"id":"req_123"}'
|
|
57
|
+
```
|
|
58
|
+
|
|
33
59
|
Background execution:
|
|
34
60
|
|
|
35
61
|
```ts
|
|
@@ -171,7 +171,13 @@ host's code sets `props`; a dispatcher must never copy request data into
|
|
|
171
171
|
them. `POST /__raybase/host/backup` then takes one backup and answers `200 {
|
|
172
172
|
key, bytes, date }`, `409 { error, code: "BACKUP_NOT_CONFIGURED" }` when
|
|
173
173
|
backups are off, unbound or keyless, or `503 { error, code }` when it fails;
|
|
174
|
-
without the prop the address answers as an unknown one.
|
|
174
|
+
without the prop the address answers as an unknown one. With
|
|
175
|
+
`RAYBASE_HOST_VERSION` set (the host's own name for the uploaded version, 1
|
|
176
|
+
to 128 visible ASCII characters, no spaces), every door answer echoes it
|
|
177
|
+
unchanged in the `raybase-host-version` header and as `hostVersion` in the
|
|
178
|
+
body, so a host can tell the new version's answer from that of the version
|
|
179
|
+
still serving; any other value makes every door answer `500
|
|
180
|
+
HOST_VERSION_INVALID`, and takes no backup. A host backup counts
|
|
175
181
|
toward `RAYBASE_BACKUPS_RETAIN` with the nightly and admin ones (trigger
|
|
176
182
|
`"host"`, audit `database.backup.host`). Keep `isRaybaseHostRequest(request,
|
|
177
183
|
ctx)` in the worker entry, ahead of the framework, as the templates have it;
|
|
@@ -271,16 +271,24 @@ the `io.modelcontextprotocol/ui` extension and accept
|
|
|
271
271
|
|
|
272
272
|
- App MCP scopes are `mcp:read`, `mcp:write`, and per-tool scopes such as
|
|
273
273
|
`mcp:tool:<name>`.
|
|
274
|
-
-
|
|
275
|
-
`annotations.readOnlyHint`
|
|
276
|
-
|
|
274
|
+
- A tool that declares no scopes answers to either of two: `mcp:read` (with
|
|
275
|
+
`annotations.readOnlyHint`) or `mcp:write`, or its own `mcp:tool:<name>`.
|
|
276
|
+
So a token holding `mcp:write` calls every mutating tool that declares
|
|
277
|
+
none, and a token holding only `mcp:tool:<name>` calls that one tool.
|
|
277
278
|
- Resources default to `mcp:read`.
|
|
278
|
-
-
|
|
279
|
+
- `scopes` on a tool or resource are all required: a token must hold every
|
|
280
|
+
one. `scopes: ["mcp:write", "acme:govern"]` is out of reach of a token that
|
|
281
|
+
holds only `mcp:write`. Declare them when a tool needs more than the broad
|
|
282
|
+
scope says.
|
|
283
|
+
- Raybase's generated table and search tools also answer to their table's
|
|
284
|
+
or search's scope: any one of `mcp:read`, `mcp:table:<table>:read` and
|
|
285
|
+
`mcp:tool:<name>` reaches a generated read tool.
|
|
279
286
|
- What a grant may hold depends on who grants it. A person (approving an agent
|
|
280
287
|
at consent, or registering their own key) may grant `mcp:read`, `mcp:write`
|
|
281
|
-
and scopes that only narrow them: ones
|
|
282
|
-
|
|
283
|
-
|
|
288
|
+
and scopes that only narrow them: ones found only on tools and resources
|
|
289
|
+
those two already reach, such as Raybase's `mcp:tool:<name>`. A scope a
|
|
290
|
+
tool requires beyond those two, alone (`scopes: ["acme:platform"]`) or
|
|
291
|
+
beside them (`scopes: ["mcp:write", "acme:govern"]`), hides the tool from
|
|
284
292
|
every agent a person approves; only the app's own server code grants it,
|
|
285
293
|
through a machine credential (`createMcpMachineCredential` with
|
|
286
294
|
`mcpAppConnectorScopeOptions()`, or Pro's `createRaybaseMachineCredential`).
|
|
@@ -311,9 +319,22 @@ MCP handler and a server function.
|
|
|
311
319
|
|
|
312
320
|
`mcpToolFromAction()` uses the action input schema, description, policy,
|
|
313
321
|
idempotency, and annotations, and can apply adapter `rowAuthorization()`.
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
`
|
|
322
|
+
|
|
323
|
+
- The tool advertises the action's `output` as its `outputSchema` when that
|
|
324
|
+
describes an object (the only kind MCP's `structuredContent` can be).
|
|
325
|
+
- The action's `ctx.organizationId` is the organization the call runs in, as
|
|
326
|
+
it is on the action's HTTP route.
|
|
327
|
+
- With no `scopes`, a read-only action (`annotations.readOnlyHint`) answers
|
|
328
|
+
to `mcp:read` or `mcp:tool:<name>`, and a mutating one to `mcp:write` or
|
|
329
|
+
`mcp:tool:<name>`. Pass `scopes` to require more; every one listed is
|
|
330
|
+
required:
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
mcpToolFromAction(actions.setPolicy, { scopes: ["mcp:write", "acme:govern"] })
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
The same tool decides what an access token may do on the action's HTTP route
|
|
337
|
+
when the app sets `api.accessTokens`; see the `raybase-actions` skill.
|
|
317
338
|
|
|
318
339
|
Mark destructive or irreversible actions with
|
|
319
340
|
`annotations.destructiveHint: true`, keep policy and `rowAuthorization()` tight,
|