@raybase/create 0.3.19 → 0.3.20

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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@raybase/create",
3
- "version": "0.3.19",
3
+ "version": "0.3.20",
4
4
  "description": "Scaffold secure internal apps powered by Raybase.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -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()` uses `mcp:read` plus `mcp:tool:<name>` for
174
- `readOnlyHint` actions and `mcp:write` plus `mcp:tool:<name>` for mutating
175
- actions unless explicit scopes are supplied.
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
@@ -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
- - Read-only tools default to `mcp:read` plus `mcp:tool:<name>` when
275
- `annotations.readOnlyHint` is true.
276
- - Mutating tools default to `mcp:write` plus `mcp:tool:<name>`.
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
- - Set explicit `scopes` only when a narrower or custom grant is required.
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 every tool or resource lists beside
282
- `mcp:read` or `mcp:write`, such as Raybase's `mcp:tool:<name>`. A custom
283
- scope a tool lists alone (`scopes: ["acme:platform"]`) hides the tool from
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
- Read-only actions with `annotations.readOnlyHint` default to `mcp:read` plus
315
- `mcp:tool:<name>`; mutating actions default to `mcp:write` plus
316
- `mcp:tool:<name>`.
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,