@raybase/create 0.3.12 → 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.12",
3
+ "version": "0.3.14",
4
4
  "description": "Scaffold secure internal apps powered by Raybase.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -261,6 +261,48 @@ Two client paths, both Core-owned:
261
261
  Auth refuses before Core's hook is reached. The flag only asks — a public
262
262
  signup mode is still what decides.
263
263
 
264
+ ## Sign-Up Allowlist
265
+
266
+ Where sign-up is open (`auth.signupMode` `"public"` or `"provider-only"`), a
267
+ deploy limits it to named people with `RAYBASE_SIGNUP_ALLOWLIST`: exact
268
+ addresses and `@domain` entries, comma-separated, compared ignoring case
269
+ (`toby@example.com, @example.org`). Set it on the Worker, as a secret when the
270
+ addresses are private; no code change. The app may give a default in
271
+ `appConfig.auth.signupAllowlist: ["@example.com"]`, which the variable replaces
272
+ whenever it holds an entry. An entry that is neither an address nor `@domain`
273
+ matches nothing (doctor reports it); `@example.org` does not match subdomains,
274
+ and `toby+x@example.com` is not `toby@example.com`.
275
+
276
+ With a list set, password sign-up and an outside provider's new account are
277
+ refused for an unlisted address. The refusal never says who is listed: with
278
+ email verification on, an unlisted password sign-up gets the "check your email"
279
+ answer a new address gets, and no mail; without it, the answer an address with
280
+ an account gets. Existing accounts sign in as before, and invites (and owner
281
+ setup) still admit whoever they name: an operator's invite is an admission of
282
+ its own. Do not build an app-side sign-up gate instead; this is the gate.
283
+
284
+ ## Sign-In Rate Limits
285
+
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
289
+ (`_auth_rate_limits`, keys HMAC'd under the auth secret), so every isolate
290
+ shares them; Better Auth's own in-memory limiter stands aside on those paths.
291
+
292
+ | Limit | Per address | Per client |
293
+ |---|---|---|
294
+ | `emails` | 3 per 10 minutes | 20 per hour |
295
+ | `wrongCodes` | 10 per hour | 20 per hour |
296
+
297
+ A limited request gets `429`, `Retry-After`, and
298
+ `{ 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
301
+ each code. Change numbers with `appConfig.auth.rateLimits` (for example
302
+ `{ emails: { perClient: { max: 50, windowSeconds: 3600 } } }`); every limit
303
+ stays on. Locally the limits hold too: `GET /api/auth/raybase/sign-in-limits`
304
+ shows the counters and `DELETE` clears them (local only).
305
+
264
306
  ## Runtime Sign-In Links
265
307
 
266
308
  Runtime sign-in links are a separate, email-free capability for moving the
@@ -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.
@@ -143,10 +143,30 @@ triggers, vars and secrets. It needs none of those secrets on the machine: a
143
143
  fresh clone with no `.raybase/` or `.dev.vars` builds, since the host
144
144
  supplies them at upload; `raybase deploy` still needs them locally. Each
145
145
  secret in the list has a `kind` (`random-32`, `ec-p256-jwk`,
146
- `retained-keys`, `provider-api-key` or `app-defined`). `raybase secrets
146
+ `retained-keys`, `provider-api-key`, `app-defined` or `address-list`; the last
147
+ is the optional `RAYBASE_SIGNUP_ALLOWLIST` of an app anyone may sign up to,
148
+ which limits sign-up to the people it names). `raybase secrets
147
149
  list` explains each secret and `raybase secrets new` prints fresh values, by
148
150
  kind, as JSON for `wrangler deploy --secrets-file`. `wrangler deploy` of the
149
151
  build then works on any account.
150
- The app applies its own database changes on first use. See the hosting
151
- 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.
152
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
  }