@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 +137 -80
- package/dist/{chunk-CFLI52WY.js → chunk-WAMTSUKW.js} +146 -108
- package/dist/chunk-WAMTSUKW.js.map +7 -0
- package/dist/dev-proxy.d.ts +176 -0
- package/dist/dev-proxy.js +15 -0
- package/dist/index.d.ts +59 -64
- package/dist/index.js +152 -162
- package/dist/index.js.map +4 -4
- package/package.json +5 -5
- package/dist/chunk-CFLI52WY.js.map +0 -7
- package/dist/sandbox-proxy.d.ts +0 -121
- package/dist/sandbox-proxy.js +0 -15
- /package/dist/{sandbox-proxy.js.map → dev-proxy.js.map} +0 -0
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
|
-
- `
|
|
90
|
-
`/
|
|
91
|
-
handler; `
|
|
92
|
-
`
|
|
93
|
-
`
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
`
|
|
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
|
-
##
|
|
129
|
+
## Dev resources
|
|
129
130
|
|
|
130
|
-
A preview runs every third-party service as an in-browser emulator.
|
|
131
|
-
flip one service at a time from **Emulated** to **
|
|
132
|
-
forward mode (`PUT /__admin/upstream {"mode":"forward"}`) and sends the app's API calls to
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
|
142
|
-
participant Vendor as
|
|
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 "
|
|
145
|
-
Emu->>Proxy: POST /
|
|
146
|
-
Note over Proxy:
|
|
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
|
-
###
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
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` |
|
|
160
|
-
| `junction` | `api.sandbox.tryvital.io` (`api.sandbox.eu.tryvital.io` for `sk_eu_` keys) | `JUNCTION_API_KEY` |
|
|
161
|
-
| `resend` | `api.resend.com` | `RESEND_API_KEY` |
|
|
162
|
-
| `slack` | `slack.com` | `SLACK_BOT_TOKEN` |
|
|
163
|
-
| `twilio` | `api.twilio.com`, `verify.twilio.com`, `lookups.twilio.com`, `messaging.twilio.com` (by path) | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` |
|
|
164
|
-
| `fcm` | `fcm.googleapis.com`
|
|
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
|
|
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
|
-
###
|
|
172
|
-
|
|
173
|
-
- **
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
- **
|
|
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
|
|
239
|
+
with `wrangler secret put STRIPE_SECRET_KEY`, ...):
|
|
196
240
|
|
|
197
241
|
```ts
|
|
198
|
-
import {
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
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 === "/
|
|
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 {
|
|
274
|
+
import { createDevProxy, devProviders, NON_PROD_PATTERNS } from "@crvouga/mockingbird-preview/dev-proxy"
|
|
222
275
|
|
|
223
|
-
const
|
|
224
|
-
basePath: "/
|
|
225
|
-
providers: [
|
|
276
|
+
const dev = createDevProxy({
|
|
277
|
+
basePath: "/__dev",
|
|
278
|
+
providers: [devProviders.stripe, devProviders.resend],
|
|
226
279
|
env: process.env,
|
|
227
|
-
|
|
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("/
|
|
234
|
-
?
|
|
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 /
|
|
240
|
-
`{
|
|
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 {
|
|
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
|
|
307
|
+
const dev = createDevResources({ proxyUrl: "/__dev" }) // omit proxyUrl: dev resources not offered
|
|
250
308
|
|
|
251
|
-
// Each emulator forwards through the proxy when switched to
|
|
252
|
-
const stripe = createStripe({ upstream:
|
|
253
|
-
const resend = createResend({ upstream:
|
|
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 =
|
|
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
|
|
321
|
+
unsupported: "Runs in this browser; there is no remote dev resource",
|
|
264
322
|
},
|
|
265
323
|
])
|
|
266
324
|
|
|
267
|
-
await services.
|
|
268
|
-
|
|
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`
|
|
273
|
-
|
|
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
|
|
276
|
-
`
|
|
277
|
-
`
|
|
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
|
|