@raybase/create 0.3.13 → 0.3.14

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.13",
3
+ "version": "0.3.14",
4
4
  "description": "Scaffold secure internal apps powered by Raybase.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -351,6 +351,12 @@ Repeatable handlers must be safe when they run late or more than once:
351
351
  operational rhythms.
352
352
  - Use the Jobs admin UI to verify last run, next run, failures, retry/cancel,
353
353
  and schedule visibility before handing off.
354
+ - Each failed attempt, and each run that ends failed without one (its lease
355
+ expired, or it was denied), also logs `console.error("raybase.job.failed",
356
+ { job, runId, attempt, maxAttempts, retry })` for the Worker's logs and a
357
+ host's tail events. It never includes the input; set
358
+ `appConfig.jobs.logFailureMessages: true` only if the error messages hold
359
+ nothing private, since that adds them as `error`.
354
360
 
355
361
  ## Local Development
356
362
 
@@ -545,8 +551,7 @@ export const jobs = {
545
551
  one when the parent can run more than once.
546
552
  - Add a fan-out with `enqueueMany(batchId, job, items)`, where each item is
547
553
  `{ input, idempotencyKey?, delay? }`, what `enqueue` takes for one child.
548
- Every input is validated and the child job's `enqueue` policy checked
549
- before anything is written. Each chunk of 100 is then written in one data
554
+ Every input is validated before anything is written. Each chunk of 100 is then written in one data
550
555
  Durable Object transaction, with its runs, enqueue events and audit rows,
551
556
  and sent in one queue batch send. The call returns the runs in item order.
552
557
  `enqueue` in a loop costs a Durable Object call and a queue send per
@@ -563,9 +568,9 @@ export const jobs = {
563
568
  - Batches do not nest: `batches.create` inside a batch child throws, because
564
569
  the outer batch would not wait for it. Chain stages from the continuation,
565
570
  as above.
566
- - `create` checks the continuation jobs' `enqueue` policies; `enqueue` and
567
- `enqueueMany` check the child job's. `get` and `children` use the `onComplete` job's `view`
568
- policy, `seal` its `enqueue`, and `cancel` its `cancel` policy.
571
+ - A batch is the app's own code's: `create`, `enqueue`, `enqueueMany`,
572
+ `seal`, `cancel`, `get` and `children` check that the jobs are registered,
573
+ not their route policies.
569
574
  - An operator retry of a continuation keeps `ctx.batch`; a retried child runs
570
575
  on its own and does not rejoin the batch.
571
576
  - `/admin` Jobs shows each batch's progress, runs, and continuation run.
@@ -691,6 +696,17 @@ job alone can occupy every invocation) and when the consumer sets no
691
696
 
692
697
  ## Policy Traps
693
698
 
699
+ - A job's policies say what a person may do over the jobs route, and nothing
700
+ else. `enqueue` is who may `POST /api/jobs/:name`, `view` who may read its
701
+ runs there (`enqueue` when omitted), and `cancel` who may
702
+ `POST /api/jobs/runs/:id/cancel`: operators only when omitted, never the
703
+ `enqueue` policy. An operator may always cancel from `/admin`.
704
+ - The app's own code (`ctx.jobs` in an action, route, tool, agent or job, and
705
+ `enqueueRaybaseJob`) books, schedules, reads and cancels without them: a
706
+ member's press may book a job whose `enqueue` is `denyAll`, and take its
707
+ schedule back, while that member can neither enqueue it over the route nor
708
+ cancel its runs. Guard who may press in the action's own `policy`.
709
+
694
710
  - Scheduled and system jobs run as service principals. Service principals never
695
711
  satisfy `role()` or `owns()`. Gate scheduled work with
696
712
  `anyOf(role(appRoles, "operations"), fromService("scheduler"))`.
@@ -698,9 +714,11 @@ job alone can occupy every invocation) and when the consumer sets no
698
714
  core it compares to `user.id`; in Pro it compares to membership id.
699
715
  - `runAs` is only `"actor"`, `"system"`, or `{ userRef: "inputField" }`.
700
716
  `userRef` must point to a string in the job input or enqueue fails.
701
- - Policies are re-evaluated when the queue message runs. If the actor is
702
- disabled or no longer passes policy, the run is marked denied and the handler
703
- does not run.
717
+ - A run is re-checked when the queue message runs. If the actor is disabled,
718
+ or a run the jobs route admitted no longer passes `enqueue`, the run is
719
+ marked denied and the handler does not run. A run the app's own code booked
720
+ (`admittedBy: "app"`) needs only its actor and `runAs` still present; a
721
+ schedule whose person is gone is cancelled when it falls due.
704
722
  - Cancellation does not interrupt JavaScript. Handlers must check `ctx.signal`
705
723
  at natural boundaries and return early.
706
724
  - `mode: "workflow"` is not enabled in this Raybase version. Do not set it.
@@ -149,6 +149,24 @@ which limits sign-up to the people it names). `raybase secrets
149
149
  list` explains each secret and `raybase secrets new` prints fresh values, by
150
150
  kind, as JSON for `wrangler deploy --secrets-file`. `wrangler deploy` of the
151
151
  build then works on any account.
152
- The app applies its own database changes on first use. See the hosting
153
- guide (`docs/hosting.md` on the Raybase site) for the full contract.
152
+ The app applies its own database changes on first use.
153
+
154
+ A host that runs the app reaches it as itself, with no admin session, through
155
+ `fetch` with `props: { raybaseHost: true }` on the request's ExecutionContext
156
+ (`env.DISPATCHER.get(app, { props: { raybaseHost: true } })` from a Workers
157
+ for Platforms dispatcher, or `props` in a service binding's config). Only the
158
+ host's code sets `props`; a dispatcher must never copy request data into
159
+ them. `POST /__raybase/host/backup` then takes one backup and answers `200 {
160
+ key, bytes, date }`, `409 { error, code: "BACKUP_NOT_CONFIGURED" }` when
161
+ backups are off, unbound or keyless, or `503 { error, code }` when it fails;
162
+ without the prop the address answers as an unknown one. A host backup counts
163
+ toward `RAYBASE_BACKUPS_RETAIN` with the nightly and admin ones (trigger
164
+ `"host"`, audit `database.backup.host`). Keep `isRaybaseHostRequest(request,
165
+ ctx)` in the worker entry, ahead of the framework, as the templates have it;
166
+ `raybase doctor` warns (`host-routing`) when it is missing. Each failed job
167
+ attempt, and each run that ends failed without one (lease expired, denied),
168
+ logs `console.error("raybase.job.failed", { job, runId, attempt, maxAttempts,
169
+ retry })`, never with the input, and with the error's message only under
170
+ `appConfig.jobs.logFailureMessages: true`. See the
171
+ hosting guide (`docs/hosting.md` on the Raybase site) for the full contract.
154
172
 
@@ -134,7 +134,8 @@ OAuth registration mode.
134
134
  Browser-less clients (CLIs on remote machines, CI, bring-your-own agents) use
135
135
  the `client_credentials` grant. A signed-in user registers a confidential
136
136
  client at `/api/auth/oauth/register` with `grant_types: ["client_credentials"]`
137
- and the `scope` it may hold; the one-time `client_secret` in the response is
137
+ and the `scope` it may hold (what a person may grant; see Scopes); the
138
+ one-time `client_secret` in the response is
138
139
  the only time the secret is shown. The client mints access tokens with
139
140
  `grant_type=client_credentials` and HTTP Basic (`client_secret_basic`, the
140
141
  default) or form (`client_secret_post`) authentication, may narrow but never
@@ -261,6 +262,16 @@ the `io.modelcontextprotocol/ui` extension and accept
261
262
  - Mutating tools default to `mcp:write` plus `mcp:tool:<name>`.
262
263
  - Resources default to `mcp:read`.
263
264
  - Set explicit `scopes` only when a narrower or custom grant is required.
265
+ - What a grant may hold depends on who grants it. A person (approving an agent
266
+ at consent, or registering their own key) may grant `mcp:read`, `mcp:write`
267
+ and scopes that only narrow them: ones every tool or resource lists beside
268
+ `mcp:read` or `mcp:write`, such as Raybase's `mcp:tool:<name>`. A custom
269
+ scope a tool lists alone (`scopes: ["acme:platform"]`) hides the tool from
270
+ every agent a person approves; only the app's own server code grants it,
271
+ through a machine credential (`createMcpMachineCredential` with
272
+ `mcpAppConnectorScopeOptions()`, or Pro's `createRaybaseMachineCredential`).
273
+ Registration, consent and the token endpoint answer any other scope with
274
+ `invalid_scope`.
264
275
  - Operator scopes must stay on Operator MCP. App MCP grants must never request
265
276
  `operator:*` scopes.
266
277
 
@@ -1,5 +1,5 @@
1
1
  import serverEntry from "@tanstack/react-start/server-entry";
2
- import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
2
+ import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, isRaybaseHostRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
3
3
  import { appConfig } from "./raybase.config";
4
4
  import { raybaseHandler } from "./raybase.server";
5
5
 
@@ -11,7 +11,10 @@ export default {
11
11
  if (isRaybaseAdminPanelRequestDisabled(request, appConfig)) return new Response("Not Found", { status: 404 });
12
12
  // The connector (/mcp) and the discovery documents under /.well-known are
13
13
  // Raybase's; the app's own routes never see them.
14
- if (isRaybaseConnectorRequest(request, appConfig)) {
14
+ // So are the host's own requests (/__raybase/host/*, with
15
+ // ctx.props.raybaseHost set by the host's code); without that prop the
16
+ // address is the app's like any other.
17
+ if (isRaybaseConnectorRequest(request, appConfig) || isRaybaseHostRequest(request, ctx)) {
15
18
  if (!raybaseHandler.fetch) throw new Error("Raybase handler is not fetch-compatible");
16
19
  return raybaseHandler.fetch(request as never, env as never, ctx as never);
17
20
  }
@@ -1,5 +1,5 @@
1
1
  import { createRequestHandler } from "react-router";
2
- import { withRaybaseLocalDevChrome } from "@raybase/core/worker";
2
+ import { isRaybaseHostRequest, withRaybaseLocalDevChrome } from "@raybase/core/worker";
3
3
  import { appConfig, handleRaybaseRequest, isDisabledRaybaseAdminRequest, isRaybaseRequest, raybaseHandler } from "../app/raybase.server";
4
4
 
5
5
  // Singleton Raybase SQLite Durable Object (bound as RAYBASE_DATA in wrangler.jsonc).
@@ -25,9 +25,11 @@ export default {
25
25
  if (isDisabledRaybaseAdminRequest(request)) return new Response("Not Found", { status: 404 });
26
26
  // Raybase (admin panel, auth pages, data API, MCP) and the React Router
27
27
  // app share this worker; Raybase owns its path prefixes, React Router
28
- // takes the rest.
28
+ // takes the rest. The host's own requests (/__raybase/host/*, with
29
+ // ctx.props.raybaseHost set by the host's code) are Raybase's too;
30
+ // without that prop the address is React Router's like any other.
29
31
  const url = new URL(request.url);
30
- if (isRaybaseRequest(url)) return handleRaybaseRequest(request, env, ctx);
32
+ if (isRaybaseRequest(url) || isRaybaseHostRequest(request, ctx)) return handleRaybaseRequest(request, env, ctx);
31
33
  const response = await requestHandler(request, { cloudflare: { env, ctx } });
32
34
  // Adds Raybase's local dev chrome (persona switcher) to app pages in
33
35
  // local development; a no-op everywhere else.
@@ -1,5 +1,5 @@
1
1
  import serverEntry from "@tanstack/react-start/server-entry";
2
- import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
2
+ import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, isRaybaseHostRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
3
3
  import { appConfig } from "./raybase.config";
4
4
  import { raybaseHandler } from "./raybase.server";
5
5
 
@@ -11,7 +11,10 @@ export default {
11
11
  if (isRaybaseAdminPanelRequestDisabled(request, appConfig)) return new Response("Not Found", { status: 404 });
12
12
  // The connector (/mcp) and its discovery documents (/.well-known/oauth-*)
13
13
  // are Raybase's; the app's own routes never see them.
14
- if (isRaybaseConnectorRequest(request, appConfig)) {
14
+ // So are the host's own requests (/__raybase/host/*, with
15
+ // ctx.props.raybaseHost set by the host's code); without that prop the
16
+ // address is the app's like any other.
17
+ if (isRaybaseConnectorRequest(request, appConfig) || isRaybaseHostRequest(request, ctx)) {
15
18
  if (!raybaseHandler.fetch) throw new Error("Raybase handler is not fetch-compatible");
16
19
  return raybaseHandler.fetch(request as never, env as never, ctx as never);
17
20
  }