@raybase/create 0.3.13 → 0.3.15

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.15",
4
4
  "description": "Scaffold secure internal apps powered by Raybase.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -284,8 +284,10 @@ its own. Do not build an app-side sign-up gate instead; this is the gate.
284
284
  ## Sign-In Rate Limits
285
285
 
286
286
  Raybase limits, per address and per client (`cf-connecting-ip`), asking for
287
- sign-in email (codes, magic links, password-reset links, verification links)
288
- and wrong sign-in codes. The counters are rows in the app's Durable Object
287
+ sign-in email (codes, magic links, password-reset links, verification links),
288
+ wrong sign-in codes, and wrong passwords (at `/api/auth/sign-in/email` and
289
+ Raybase's own password sign-ins, such as `/api/auth/login`, counted
290
+ together). The counters are rows in the app's Durable Object
289
291
  (`_auth_rate_limits`, keys HMAC'd under the auth secret), so every isolate
290
292
  shares them; Better Auth's own in-memory limiter stands aside on those paths.
291
293
 
@@ -293,11 +295,12 @@ shares them; Better Auth's own in-memory limiter stands aside on those paths.
293
295
  |---|---|---|
294
296
  | `emails` | 3 per 10 minutes | 20 per hour |
295
297
  | `wrongCodes` | 10 per hour | 20 per hour |
298
+ | `wrongPasswords` | 10 per hour | 20 per hour |
296
299
 
297
300
  A limited request gets `429`, `Retry-After`, and
298
301
  `{ error, message, code: "rate_limited", retryAfter }`, the same for every
299
- address whether or not it has an account or is listed. A code that signs in is
300
- not counted. Better Auth's `allowedAttempts` (three tries per code) still ends
302
+ address whether or not it has an account or is listed. A code or password that
303
+ signs in is not counted. Better Auth's `allowedAttempts` (three tries per code) still ends
301
304
  each code. Change numbers with `appConfig.auth.rateLimits` (for example
302
305
  `{ emails: { perClient: { max: 50, windowSeconds: 3600 } } }`); every limit
303
306
  stays on. Locally the limits hold too: `GET /api/auth/raybase/sign-in-limits`
@@ -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
 
@@ -96,6 +96,28 @@ For user-scoped values:
96
96
  const density = await ctx.settings.getForUser(ctx.user.id, "inboxDensity");
97
97
  ```
98
98
 
99
+ ### A person's own preferences
100
+
101
+ A user-scoped setting declared `permissions: { write: "self" }` is the
102
+ signed-in person's to set for themselves; no other setting is:
103
+
104
+ ```ts
105
+ upkeepEmails: setting.boolean({ scope: "user", default: true, label: "Emails about my apps", permissions: { write: "self" } })
106
+ ```
107
+
108
+ - `GET /api/account/settings` lists the person's own values of those settings.
109
+ - `PATCH /api/account/settings/:key` with `{ "value": ... }` sets one, validated
110
+ as an admin write is; `DELETE /api/account/settings/:key` returns it to the
111
+ default. Both are audited with `by: "self"`.
112
+ - Any other key answers 404. `permissions.roles` narrows who may set it;
113
+ `"self"` on an app- or organization-scoped setting is refused at definition.
114
+ - `ctx.settings.get(key)` in that person's requests reads what they set.
115
+
116
+ For a kind of notification a person may switch off, the app's own action can
117
+ call `setNotificationSubscription(ctx.control, { organizationId: ctx.organizationId, userId: ctx.user.id, kind, enabled: false })`:
118
+ `notifications.send` skips them for that `kind` on every channel and reports
119
+ `reason: "unsubscribed"` in `skipped`.
120
+
99
121
  Prefer reading settings at request/action execution time. Do not bake setting
100
122
  values into module scope constants.
101
123
  Module-scope reads freeze an admin override until the worker reloads and can
@@ -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,7 +1,7 @@
1
1
  // Raybase runs in the same worker as the React Router app: workers/app.ts
2
2
  // routes Raybase's own paths here (the admin panel, its API, sign-in, setup
3
3
  // and invite pages, MCP) and everything else to React Router.
4
- import { createRaybaseApp, isRaybaseAdminPanelRequestDisabled } from "@raybase/core/worker";
4
+ import { createRaybaseApp, isRaybaseAdminPanelRequestDisabled, raybaseRequestPath } from "@raybase/core/worker";
5
5
  import type { RaybaseEnv } from "@raybase/core/worker";
6
6
  import { docsModule } from "@raybase/docs";
7
7
  import { appMigrations } from "./db/migrations.gen";
@@ -34,9 +34,10 @@ export class RaybaseAIChatAgentObject extends raybase.RaybaseAIChatAgentObject {
34
34
  const raybasePathPrefixes = ["/admin", "/api", "/login", "/signup", "/setup", "/invite", "/forgot-password", "/reset-password", "/verify-email", "/mcp", "/.well-known"];
35
35
 
36
36
  export function isRaybaseRequest(url: URL): boolean {
37
- return raybasePathPrefixes.some(
38
- (prefix) => url.pathname === prefix || url.pathname.startsWith(`${prefix}/`)
39
- );
37
+ // The path as Raybase's router reads it, percent-encodings decoded, so an
38
+ // encoded "/%61pi/..." reaches Raybase (which refuses it) and not the app.
39
+ const path = raybaseRequestPath(url);
40
+ return raybasePathPrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
40
41
  }
41
42
 
42
43
  export function isDisabledRaybaseAdminRequest(request: Request): boolean {
@@ -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
  }