@crvouga/mockingbird-preview 0.0.1 → 0.1.0

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/README.md CHANGED
@@ -86,15 +86,16 @@ The application must honor the boot/request AbortSignals to terminate work it st
86
86
  listener is loopback on an ephemeral port. Responses are always `Cache-Control: no-store` to
87
87
  avoid browser worker-asset cache failures. Stream errors destroy the response instead of
88
88
  creating a successful EOF. Call the returned `close()` to release the listener.
89
- - `createSandboxProxy({ providers, env, accessKey?, basePath?, allowOrigins?, fetch? })`, from the
90
- `/sandbox-proxy` export (also re-exported from the package root), is the sandbox proxy's Fetch
91
- handler; `sandboxProxyWorker(options)` wraps it as a Cloudflare Worker `{ fetch(request, env) }`.
92
- `sandboxProviders` holds the Stripe, Junction, Resend, Slack, Twilio and FCM providers;
93
- `SANDBOX_KEY_HEADER` names the access-key header and `safeEqual(a, b)` is the constant-time
94
- comparison it uses. See [Sandbox mode](#sandbox-mode).
95
- - `createSandbox({ proxyUrl?, storage?, fetch? })` is the browser side: `upstream(id)` for an
89
+ - `createDevProxy({ providers, env, allow, basePath?, allowOrigins?, trustNonBrowser?, fetch? })`, from
90
+ the `/dev-proxy` export (also re-exported from the package root), is the dev proxy's Fetch
91
+ handler; `devProxyWorker(options)` wraps it as a Cloudflare Worker `{ fetch(request, env) }`.
92
+ `allow` is required: an anchored pattern per env value a provider reads, checked default-deny.
93
+ `devProviders` holds the Stripe, Junction, Resend, Slack, Twilio and FCM providers;
94
+ `NON_PROD_PATTERNS` the vendor formats that by themselves prove a non-production credential;
95
+ and `devBaseUrlName(id)` the `<ID>_BASE_URL` override name. See [Dev resources](#dev-resources).
96
+ - `createDevResources({ proxyUrl?, storage?, fetch? })` is the browser side: `upstream(id)` for an
96
97
  emulator's `createRuntime({ upstream })` and `controls(services)` for the System screen.
97
- `SANDBOX_MESSAGES` holds its status sentences and `SANDBOX_STORAGE_KEYS` its storage keys.
98
+ `DEV_MESSAGES` holds its status sentences and `DEV_STORAGE_KEYS` its storage keys.
98
99
 
99
100
  ## Cookies, redirects and trust
100
101
 
@@ -125,87 +126,139 @@ Cloudflare protocol references:
125
126
  [asset upload documentation](https://developers.cloudflare.com/workers/static-assets/direct-upload/),
126
127
  [Worker Previews](https://developers.cloudflare.com/workers/previews/).
127
128
 
128
- ## Sandbox mode
129
+ ## Dev resources
129
130
 
130
- A preview runs every third-party service as an in-browser emulator. Sandbox mode lets a viewer
131
- flip one service at a time from **Emulated** to **Sandbox**: that emulator's runtime switches to
132
- forward mode (`PUT /__admin/upstream {"mode":"forward"}`) and sends the app's API calls to the
133
- vendor's real sandbox or test account. The browser never holds a vendor secret. A small Fetch
134
- handler, the **sandbox proxy** (`@crvouga/mockingbird-preview/sandbox-proxy`), sits next to the
135
- static preview, holds the secrets in its environment and attaches them per request.
131
+ A preview runs every third-party service as an in-browser emulator. Dev resources let a viewer
132
+ flip one service at a time from **Emulated** to **Dev**: that emulator's runtime switches to
133
+ forward mode (`PUT /__admin/upstream {"mode":"forward"}`) and sends the app's API calls to a real
134
+ **non-production** resource the app's dev instance uses: a Stripe account in test mode,
135
+ Junction's sandbox, a dev Resend account, a dev Slack workspace, a self-hosted dev instance. The
136
+ browser never holds a credential. A small Fetch handler, the **dev proxy**
137
+ (`@crvouga/mockingbird-preview/dev-proxy`), sits next to the static preview, holds the secrets in
138
+ its environment and attaches them per request, and only after checking that every one of them is
139
+ allowed. It is mounted on the dev app's own origin and trusts that app: there is no access key,
140
+ and the client never handles a credential.
136
141
 
137
142
  ```mermaid
138
143
  sequenceDiagram
139
144
  participant App as App code (browser)
140
145
  participant Emu as Emulator runtime (browser)
141
- participant Proxy as Sandbox proxy (Worker / server)
142
- participant Vendor as Vendor sandbox
146
+ participant Proxy as Dev proxy (Worker / server)
147
+ participant Vendor as Non-prod resource (e.g. Stripe test mode)
143
148
  App->>Emu: POST /v1/customers (Authorization: Bearer sk_test_fake)
144
- Note over Emu: mode = forward (System screen chose "Sandbox")
145
- Emu->>Proxy: POST /__sandbox/stripe/v1/customers<br/>x-mockingbird-sandbox-key: viewer key<br/>(Authorization dropped)
146
- Note over Proxy: check access key (constant time)<br/>check STRIPE_SECRET_KEY is sk_test_/rk_test_<br/>strip cookie, origin, x-mockingbird-*, ...
149
+ Note over Emu: mode = forward (System screen chose "Dev")
150
+ Emu->>Proxy: POST /__dev/stripe/v1/customers<br/>Sec-Fetch-Site: same-origin<br/>(Authorization dropped)
151
+ Note over Proxy: same origin? else 403 cross_origin<br/>STRIPE_SECRET_KEY must match allow (sk_test_/rk_test_)<br/>and not deny (sk_live_/rk_live_), else 403<br/>strip cookie, origin, x-mockingbird-*, ...
147
152
  Proxy->>Vendor: POST https://api.stripe.com/v1/customers<br/>Authorization: Bearer STRIPE_SECRET_KEY
148
153
  Vendor-->>Proxy: 200 {"id": "cus_..."}
149
154
  Proxy-->>Emu: 200 (set-cookie dropped, secrets redacted)
150
155
  Emu-->>App: 200 {"id": "cus_..."}
151
156
  ```
152
157
 
153
- ### Providers
154
-
155
- `sandboxProviders` holds the vendors the proxy knows; pass the ones you want to offer.
156
-
157
- | id | Sandbox host | Env secrets | Live-key guard | Notes and limitations |
158
+ ### Safety model: default deny
159
+
160
+ Nothing is reachable until you say, in code, what a non-production value looks like.
161
+
162
+ - **`allow` is required.** For every env value a provider reads (its secrets, its identifiers and
163
+ any `<ID>_BASE_URL` override) `allow` names the pattern it must match. A provider with an env
164
+ value that has no entry, or does not match it, is **blocked**: the manifest reports why and
165
+ every relay answers `403 { "error": { "code": "not_allowed", "message" } }` without sending
166
+ anything. Patterns must be anchored (`/^…$/`, no `m` flag) or `createDevProxy()` /
167
+ `devProxyWorker()` throws; each is matched against the whole value. They live in code so they
168
+ are reviewed, never in the environment.
169
+ - **Known production formats always lose.** A provider can declare `deny` patterns that win over
170
+ `allow`: Stripe refuses `sk_live_` and `rk_live_` keys even under `allow: { STRIPE_SECRET_KEY: /^.+$/ }`.
171
+ - **`NON_PROD_PATTERNS`** holds the vendor formats that by themselves prove a non-production
172
+ credential (`STRIPE_SECRET_KEY: /^(sk|rk)_test_[A-Za-z0-9]+$/`,
173
+ `JUNCTION_API_KEY: /^sk_(us|eu)_[A-Za-z0-9_-]+$/`). Resend, Slack, Twilio and FCM credentials
174
+ look the same in production and development, so there is no entry for them: pin an identifier
175
+ (`TWILIO_ACCOUNT_SID: /^AC0123…$/`, `FCM_PROJECT_ID: /^my-app-dev$/`) or write a pattern that
176
+ only your dev credential matches.
177
+ - **Reasons never echo values.** `blocked` reads "No allow-list pattern for RESEND_API_KEY",
178
+ "STRIPE_SECRET_KEY does not match its allow-list pattern" or "STRIPE_SECRET_KEY is a production
179
+ credential"; the System screen shows it as the service's reason.
180
+ - **Base URL overrides are allow-listed too.** Each provider has a default host. An env value
181
+ `<ID>_BASE_URL` (`RESEND_BASE_URL`, `JUNCTION_BASE_URL`, ...; `devBaseUrlName(id)`) replaces it
182
+ only when `allow` has a matching entry for that name and the value is an `https:` URL without
183
+ query or credentials; a path prefix is kept. Otherwise the provider is blocked. This is how a
184
+ self-hosted dev instance is reached.
185
+
186
+ | id | Reaches by default | Secrets | Identifiers | `allow` entry |
158
187
  | --- | --- | --- | --- | --- |
159
- | `stripe` | `api.stripe.com` | `STRIPE_SECRET_KEY` | must start `sk_test_` or `rk_test_` | Only `/v1/*`. Prices, products, coupons and webhook endpoints the app names must exist in the test account. |
160
- | `junction` | `api.sandbox.tryvital.io` (`api.sandbox.eu.tryvital.io` for `sk_eu_` keys) | `JUNCTION_API_KEY` | must start `sk_us_` or `sk_eu_` | Only `/v<n>/*`, sent as `x-vital-api-key`. Lab test ids and users must exist in the sandbox team. |
161
- | `resend` | `api.resend.com` | `RESEND_API_KEY` | none (Resend keys have no test prefix) | Real email is sent: use a sending domain and recipients you own. |
162
- | `slack` | `slack.com` | `SLACK_BOT_TOKEN` | none | Only `/api/*`. Channels and users must exist in the workspace the bot is in. |
163
- | `twilio` | `api.twilio.com`, `verify.twilio.com`, `lookups.twilio.com`, `messaging.twilio.com` (by path) | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` | none (use test credentials or a trial account) | Any `/Accounts/<sid>/` is rewritten to the real SID. Sender numbers, Messaging Service SIDs and Verify Service SIDs must exist in that account. `/v1/Services` always goes to Messaging, so Conversations' `/v1/Services` is ambiguous and not reachable. |
164
- | `fcm` | `fcm.googleapis.com` | `FCM_ACCESS_TOKEN`, `FCM_PROJECT_ID` | none | Only `POST /v1/projects/*/messages:send`; the project id is rewritten to `FCM_PROJECT_ID`. The access token is a short-lived OAuth token (about an hour): refresh it out of band. |
188
+ | `stripe` | `api.stripe.com` (`/v1/*`) | `STRIPE_SECRET_KEY` | | `NON_PROD_PATTERNS` (test-mode keys; live keys are denied) |
189
+ | `junction` | Junction's sandbox `api.sandbox.tryvital.io` (`api.sandbox.eu.tryvital.io` for `sk_eu_` keys; `/v<n>/*`) | `JUNCTION_API_KEY` | | `NON_PROD_PATTERNS` |
190
+ | `resend` | `api.resend.com` | `RESEND_API_KEY` | | pin your dev key, or reach a dev instance via `RESEND_BASE_URL` |
191
+ | `slack` | `slack.com` (`/api/*`) | `SLACK_BOT_TOKEN` | | pin your dev workspace's bot token |
192
+ | `twilio` | `api.twilio.com`, `verify.twilio.com`, `lookups.twilio.com`, `messaging.twilio.com` (by path) | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` | `TWILIO_ACCOUNT_SID` | pin an identifier: `TWILIO_ACCOUNT_SID` (test credentials or a dev subaccount) |
193
+ | `fcm` | `fcm.googleapis.com` (`POST /v1/projects/*/messages:send`) | `FCM_ACCESS_TOKEN`, `FCM_PROJECT_ID` | `FCM_PROJECT_ID` | pin an identifier: `FCM_PROJECT_ID` (your dev project) |
194
+
195
+ Every value in the Secrets column needs an `allow` entry, including the token next to a pinned
196
+ identifier (a loose `/^.+$/` is fine there: the pin is what proves non-prod).
197
+
198
+ Provider notes: Stripe prices, products, coupons and webhook endpoints the app names must exist in
199
+ the test-mode account. Junction lab test ids and users must exist in Junction's sandbox team; a
200
+ `JUNCTION_BASE_URL` override replaces the EU host switch. Resend really sends email: use a sending
201
+ domain and recipients you own. Slack channels and users must exist in the bot's workspace. Twilio
202
+ rewrites any `/Accounts/<sid>/` to the configured SID; sender numbers and Messaging / Verify
203
+ Service SIDs must exist in that account; `/v1/Services` always goes to Messaging, so Conversations'
204
+ `/v1/Services` is not reachable; a `TWILIO_BASE_URL` override replaces only the default API host
205
+ (`/2010-04-01/*`), Verify, Lookups and Messaging keep their vendor hosts. FCM rewrites the project
206
+ id to `FCM_PROJECT_ID`; the access token is a short-lived OAuth token (about an hour), refresh it
207
+ out of band.
165
208
 
166
209
  For every provider: vendor webhooks are **not** relayed back to the browser emulator, and
167
210
  forwarded responses are relayed as-is (emulators with a forwarded-response hook, such as Resend,
168
- FCM and Twilio, record a receipt; Stripe and Junction do not mirror sandbox objects into their
211
+ FCM and Twilio, record a receipt; Stripe and Junction do not mirror remote objects into their
169
212
  state). A path a provider does not map answers `501`.
170
213
 
171
- ### Security model
172
-
173
- - **Fails closed.** Without `SANDBOX_PROXY_TOKEN` (or the env name passed as `accessKey`) the
174
- manifest reports `access: "disabled"` and every relay answers `503`. A caller must send that
175
- value in `x-mockingbird-sandbox-key`; it is compared in constant time, and a wrong or missing
176
- key gets `401`. Only a caller with the key learns which providers are configured.
177
- - **Allowlisted hosts only.** Each provider builds the vendor URL on a fixed origin from the
178
- path; a crafted path cannot change the host, and unmapped paths answer `501`. Redirects are
179
- returned, never followed.
214
+ ### Trust and transport
215
+
216
+ - **Same-origin only.** The proxy answers a request only when the browser marks it
217
+ `Sec-Fetch-Site: same-origin` and its `Origin`, when sent, is the proxy's own origin (or listed
218
+ in `allowOrigins`, which also turns on CORS for exactly those origins). Cross-site, same-site and
219
+ navigation requests, and a foreign `Origin`, get `403 { "error": { "code": "cross_origin" } }`
220
+ with nothing sent. A request without `Sec-Fetch-Site` (curl, a server, a test) is refused too
221
+ unless the proxy is built with `trustNonBrowser: true`.
222
+ - **Who can open the preview is the preview host's job.** Anyone who can load the page can use its
223
+ dev resources, so restrict the preview itself, e.g. with
224
+ [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) in front
225
+ of the Worker. The allow-list above is what keeps those resources non-production.
226
+ - **Fixed hosts only.** Each provider builds the URL on its fixed (or allow-listed override)
227
+ base from the path; a crafted path cannot change the host, and unmapped paths answer `501`.
228
+ Redirects are returned, never followed.
180
229
  - **Secrets never reach the browser.** The proxy drops the caller's `authorization`, `cookie`,
181
230
  `origin`, `referer`, `x-mockingbird-*`, `cf-*`, `x-forwarded-*` and `forwarded` headers,
182
231
  attaches the credential itself, drops `set-cookie` from the answer, and redacts every secret
183
232
  value from its own errors and from text responses (account identifiers such as the Twilio
184
233
  Account SID stay). Errors are `{ "error": { "code", "message" } }`.
185
- - **A live key is refused.** `check` rejects Stripe live keys and Junction production keys before
186
- anything is sent (`503`, and the System screen shows why).
187
- - **Access key per viewer.** The browser keeps the access key and chosen modes in its own
188
- `localStorage`; share the key only with people who may spend the sandbox accounts. CORS is off
189
- unless `allowOrigins` lists the page's origin; mounting the proxy on the page's own origin (as
190
- below) needs none.
234
+ - **Modes per viewer.** The browser keeps only the chosen modes in its own `localStorage`.
191
235
 
192
236
  ### Mounting the proxy
193
237
 
194
238
  A Cloudflare Worker that serves the static preview and the proxy on one origin (set the secrets
195
- with `wrangler secret put SANDBOX_PROXY_TOKEN`, `wrangler secret put STRIPE_SECRET_KEY`, ...):
239
+ with `wrangler secret put STRIPE_SECRET_KEY`, ...):
196
240
 
197
241
  ```ts
198
- import { sandboxProviders, sandboxProxyWorker } from "@crvouga/mockingbird-preview/sandbox-proxy"
199
-
200
- const proxy = sandboxProxyWorker({
201
- basePath: "/__sandbox",
202
- providers: Object.values(sandboxProviders),
242
+ import {
243
+ devProviders,
244
+ devProxyWorker,
245
+ NON_PROD_PATTERNS,
246
+ } from "@crvouga/mockingbird-preview/dev-proxy"
247
+
248
+ const proxy = devProxyWorker({
249
+ basePath: "/__dev",
250
+ providers: [devProviders.stripe, devProviders.junction, devProviders.twilio],
251
+ allow: {
252
+ ...NON_PROD_PATTERNS,
253
+ TWILIO_ACCOUNT_SID: /^AC_YOUR_DEV_ACCOUNT_SID$/, // the dev account, pinned
254
+ TWILIO_AUTH_TOKEN: /^[0-9a-f]{32}$/,
255
+ },
203
256
  })
204
257
 
205
258
  export default {
206
259
  fetch(request: Request, env: Record<string, string | undefined> & { ASSETS: { fetch(request: Request): Promise<Response> } }) {
207
260
  const { pathname } = new URL(request.url)
208
- if (pathname === "/__sandbox" || pathname.startsWith("/__sandbox/")) {
261
+ if (pathname === "/__dev" || pathname.startsWith("/__dev/")) {
209
262
  const { ASSETS: _assets, ...secrets } = env
210
263
  return proxy.fetch(request, secrets)
211
264
  }
@@ -215,67 +268,71 @@ export default {
215
268
  ```
216
269
 
217
270
  A Bun server (Node 18+ and Deno work the same with any Fetch-handler server), secrets from
218
- `.env.local` / the process environment:
271
+ `.env.local` / the process environment, reaching a self-hosted dev Resend-compatible instance:
219
272
 
220
273
  ```ts
221
- import { createSandboxProxy, sandboxProviders } from "@crvouga/mockingbird-preview/sandbox-proxy"
274
+ import { createDevProxy, devProviders, NON_PROD_PATTERNS } from "@crvouga/mockingbird-preview/dev-proxy"
222
275
 
223
- const sandbox = createSandboxProxy({
224
- basePath: "/__sandbox",
225
- providers: [sandboxProviders.stripe, sandboxProviders.resend],
276
+ const dev = createDevProxy({
277
+ basePath: "/__dev",
278
+ providers: [devProviders.stripe, devProviders.resend],
226
279
  env: process.env,
227
- allowOrigins: ["http://localhost:5173"], // only when the page is on another origin
280
+ allow: {
281
+ ...NON_PROD_PATTERNS,
282
+ RESEND_API_KEY: /^re_dev_[A-Za-z0-9_]+$/,
283
+ RESEND_BASE_URL: /^https:\/\/mail\.dev\.example\.com$/,
284
+ },
285
+ allowOrigins: ["http://localhost:5173"], // only when the page is served from another origin
228
286
  })
229
287
 
230
288
  Bun.serve({
231
289
  port: 8787,
232
290
  fetch: (request) =>
233
- new URL(request.url).pathname.startsWith("/__sandbox")
234
- ? sandbox(request)
291
+ new URL(request.url).pathname.startsWith("/__dev")
292
+ ? dev(request)
235
293
  : new Response("Not found", { status: 404 }),
236
294
  })
237
295
  ```
238
296
 
239
- `GET /__sandbox/` answers the manifest:
240
- `{ access: "granted" | "denied" | "disabled", providers: [{ id, label, configured, missing, error? }] }`.
297
+ `GET /__dev/` answers the manifest:
298
+ `{ providers: [{ id, label, configured, missing, blocked? }] }`.
241
299
 
242
300
  ### Browser wiring
243
301
 
244
302
  ```ts
245
- import { createSandbox } from "@crvouga/mockingbird-preview"
303
+ import { createDevResources } from "@crvouga/mockingbird-preview"
246
304
  import { createRuntime as createStripe } from "@crvouga/mockingbird-service-stripe"
247
305
  import { createRuntime as createResend } from "@crvouga/mockingbird-service-resend"
248
306
 
249
- const sandbox = createSandbox({ proxyUrl: "/__sandbox" }) // omit proxyUrl: sandbox not offered
307
+ const dev = createDevResources({ proxyUrl: "/__dev" }) // omit proxyUrl: dev resources not offered
250
308
 
251
- // Each emulator forwards through the proxy when switched to Sandbox; it boots emulated.
252
- const stripe = createStripe({ upstream: sandbox.upstream("stripe") })
253
- const resend = createResend({ upstream: sandbox.upstream("resend") })
309
+ // Each emulator forwards through the proxy when switched to Dev; it boots emulated.
310
+ const stripe = createStripe({ upstream: dev.upstream("stripe") })
311
+ const resend = createResend({ upstream: dev.upstream("resend") })
254
312
 
255
313
  // The System screen's service list (`mountSystemHarness(host, surfaces, { services })`).
256
- const services = sandbox.controls([
314
+ const services = dev.controls([
257
315
  { id: "stripe", label: "Stripe", category: "Payments", admin: (r) => stripe.fetch(r) },
258
316
  { id: "resend", label: "Resend", category: "Email", admin: (r) => resend.fetch(r) },
259
317
  {
260
318
  id: "keycloak",
261
319
  label: "Keycloak",
262
320
  admin: async () => Response.json({ mode: "emulated" }),
263
- unsupported: "Runs in this browser; there is no vendor sandbox",
321
+ unsupported: "Runs in this browser; there is no remote dev resource",
264
322
  },
265
323
  ])
266
324
 
267
- await services.setAccessKey("the key the proxy's SANDBOX_PROXY_TOKEN holds")
268
- await services.setMode("stripe", "sandbox") // throws a readable reason when unavailable
269
- const { sandbox: status, services: rows } = await services.list()
325
+ await services.setMode("stripe", "dev") // throws a readable reason when unavailable
326
+ const { dev: status, services: rows } = await services.list()
270
327
  ```
271
328
 
272
- `upstream(id)` gives `{ baseUrl: "<proxy>/<id>", fetch, rewriteAuth }`: `fetch` adds the stored
273
- access key, `rewriteAuth` drops the app's fake `authorization`. `controls()` reads each
329
+ `upstream(id)` gives `{ baseUrl: "<proxy>/<id>", fetch, rewriteAuth }`: `fetch` sends the request
330
+ to the proxy as-is (the browser adds `Sec-Fetch-Site`), `rewriteAuth` drops the app's fake
331
+ `authorization` and any cookie. `controls()` reads each
274
332
  emulator's mode from `GET /__admin/upstream`, and its `unavailable` reason follows this order:
275
- the spec's `unsupported`, no proxy configured, proxy unreachable, proxy without
276
- `SANDBOX_PROXY_TOKEN`, access key missing or wrong, provider secrets missing, the provider's
277
- `check` error. Chosen modes persist per viewer; because emulator state resets on reload, the first
278
- `list()` re-applies stored Sandbox choices that are still available.
333
+ the spec's `unsupported`, no proxy configured, proxy unreachable or refusing the page
334
+ (`cross_origin`), provider secrets missing, the provider's `blocked` reason. Chosen modes persist per viewer; because emulator state resets on reload, the
335
+ first `list()` re-applies stored Dev choices that are still available.
279
336
 
280
337
  ## Validation
281
338