@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 +1 -1
- package/skills/raybase-auth/SKILL.md +7 -4
- package/skills/raybase-background-jobs/SKILL.md +26 -8
- package/skills/raybase-deploy/SKILL.md +20 -2
- package/skills/raybase-mcp/SKILL.md +12 -1
- package/skills/raybase-settings/SKILL.md +22 -0
- package/templates/astro-emdash/src/worker-entry.ts +5 -2
- package/templates/react-router/app/raybase.server.ts +5 -4
- package/templates/react-router/workers/app.ts +5 -3
- package/templates/tanstack-start/src/worker-entry.ts +5 -2
package/package.json
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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
|
-
-
|
|
567
|
-
`
|
|
568
|
-
|
|
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
|
-
-
|
|
702
|
-
|
|
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.
|
|
153
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
38
|
-
|
|
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
|
-
|
|
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
|
}
|