@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.
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Dev proxy: a Fetch handler that relays an emulator's forwarded requests to a real
3
+ * **non-production** resource (Stripe test mode, Junction's sandbox, a dev Resend account, a
4
+ * self-hosted dev instance) and attaches the credentials there, so secrets never reach the browser.
5
+ *
6
+ * Default deny: a provider is reachable only when every env value it reads matches an anchored
7
+ * allow-list pattern the consumer writes in code (`allow`), and none matches a known production
8
+ * format the provider declares (`deny`).
9
+ *
10
+ * Trust: the proxy is mounted on the dev app's own origin and trusts that app. It answers only
11
+ * same-origin browser requests (`Sec-Fetch-Site: same-origin`, and an `Origin`, when sent, equal to
12
+ * its own or listed in `allowOrigins`). Credentials are attached here and never reach the client.
13
+ *
14
+ * Portable: Fetch API only. Runs in Cloudflare Workers, Bun, Node 18+ and Deno.
15
+ */
16
+ type DevEnv = Record<string, string | undefined>;
17
+ /** How one vendor is reached and which secrets it needs. */
18
+ type DevProvider = {
19
+ /** Path segment the proxy serves it under, e.g. "stripe". */
20
+ id: string;
21
+ /** Display name, e.g. "Stripe". */
22
+ label: string;
23
+ /** Env names that must all be set, e.g. ["STRIPE_SECRET_KEY"]. Each needs an `allow` entry. */
24
+ secrets: readonly string[];
25
+ /**
26
+ * Env names among `secrets` that identify an account rather than authenticate it (a Twilio
27
+ * Account SID, an FCM project id). They are allow-checked like every secret, and never redacted
28
+ * from vendor responses, where they legitimately appear; every other secret is.
29
+ */
30
+ identifiers?: readonly string[];
31
+ /**
32
+ * Known **production** formats per env name, refused even when `allow` matches
33
+ * (Stripe: `^(sk|rk)_live_`).
34
+ */
35
+ deny?: Readonly<Record<string, RegExp>>;
36
+ /**
37
+ * Default origin of the non-prod-capable vendor host, e.g. "https://api.stripe.com". An env value
38
+ * `<ID>_BASE_URL` (see `devBaseUrlName`) replaces it, but only when `allow` has a matching entry
39
+ * for that name.
40
+ */
41
+ baseUrl: string;
42
+ /** Methods the proxy relays; any other is refused with 501. Default: every method. */
43
+ methods?: readonly string[];
44
+ /**
45
+ * Map the incoming path (after /<id>) to the real URL, or undefined to refuse (501). `base` is
46
+ * `baseUrl` or the allow-listed override; build the URL with it.
47
+ */
48
+ target(path: string, search: string, base: string): URL | undefined;
49
+ /** Attach credentials (and any id rewrites) to the outgoing request. */
50
+ authorize(request: Request, env: DevEnv): Request | Promise<Request>;
51
+ };
52
+ type DevProxyOptions = {
53
+ providers: readonly DevProvider[];
54
+ /** Secrets source: a Worker's env, process.env, Bun.env. Read per request. */
55
+ env: DevEnv | ((request: Request) => DevEnv);
56
+ /**
57
+ * REQUIRED. For every env value a provider reads (its `secrets` and `identifiers`, and any
58
+ * `<ID>_BASE_URL` override), the pattern it must match. Missing entry => that provider is
59
+ * unavailable. A pattern that is not anchored (source must start with `^` and end with `$`)
60
+ * throws at createDevProxy() time. Patterns live in code so they are reviewed, never in env.
61
+ */
62
+ allow: Readonly<Record<string, RegExp>>;
63
+ /** Path prefix the handler is mounted under. Default "" ; the lab uses "/__dev". */
64
+ basePath?: string;
65
+ /**
66
+ * Other origins trusted like the proxy's own, with CORS (exact strings or RegExp). Default: none
67
+ * (same-origin only). Use it when the page is served from another origin, e.g. a dev server.
68
+ */
69
+ allowOrigins?: readonly (string | RegExp)[];
70
+ /**
71
+ * Also accept requests without `Sec-Fetch-Site` (non-browser clients: tests, server-side
72
+ * callers). Default false: such requests are refused like cross-site ones.
73
+ */
74
+ trustNonBrowser?: boolean;
75
+ /** Outgoing fetch. Default globalThis.fetch. Injected in tests. */
76
+ fetch?: (request: Request) => Promise<Response>;
77
+ };
78
+ type DevManifest = {
79
+ providers: {
80
+ id: string;
81
+ label: string;
82
+ configured: boolean;
83
+ missing: string[];
84
+ /** Why the safety checks refuse this provider. Names env vars only, never their values. */
85
+ blocked?: string;
86
+ }[];
87
+ };
88
+ /**
89
+ * Vendor credential formats that by themselves prove a non-production resource. Spread them into
90
+ * `allow`. Vendors whose formats cannot tell prod from dev (Resend, Slack, Twilio, FCM) have no
91
+ * entry: pin an identifier instead (`TWILIO_ACCOUNT_SID: /^AC0123…$/`, `FCM_PROJECT_ID:
92
+ * /^my-app-dev$/`) or write a pattern of your own.
93
+ */
94
+ declare const NON_PROD_PATTERNS: {
95
+ readonly STRIPE_SECRET_KEY: RegExp;
96
+ readonly JUNCTION_API_KEY: RegExp;
97
+ };
98
+ /** The env name that overrides a provider's base URL: `resend` -> `RESEND_BASE_URL`. */
99
+ declare const devBaseUrlName: (id: string) => string;
100
+ /** The vendors the lab knows how to reach. Pass the ones you want to `createDevProxy`. */
101
+ declare const devProviders: {
102
+ stripe: {
103
+ id: string;
104
+ label: string;
105
+ secrets: string[];
106
+ deny: {
107
+ STRIPE_SECRET_KEY: RegExp;
108
+ };
109
+ baseUrl: string;
110
+ target: (path: string, search: string, base: string) => URL | undefined;
111
+ authorize: (request: Request, env: DevEnv) => Request;
112
+ };
113
+ junction: {
114
+ id: string;
115
+ label: string;
116
+ secrets: string[];
117
+ baseUrl: string;
118
+ target: (path: string, search: string, base: string) => URL | undefined;
119
+ authorize: (request: Request, env: DevEnv) => Request;
120
+ };
121
+ resend: {
122
+ id: string;
123
+ label: string;
124
+ secrets: string[];
125
+ baseUrl: string;
126
+ target: (path: string, search: string, base: string) => URL;
127
+ authorize: (request: Request, env: DevEnv) => Request;
128
+ };
129
+ slack: {
130
+ id: string;
131
+ label: string;
132
+ secrets: string[];
133
+ baseUrl: string;
134
+ target: (path: string, search: string, base: string) => URL | undefined;
135
+ authorize: (request: Request, env: DevEnv) => Request;
136
+ };
137
+ twilio: {
138
+ id: string;
139
+ label: string;
140
+ secrets: string[];
141
+ identifiers: string[];
142
+ baseUrl: string;
143
+ target: (path: string, search: string, base: string) => URL | undefined;
144
+ authorize: (request: Request, env: DevEnv) => Request;
145
+ };
146
+ fcm: {
147
+ id: string;
148
+ label: string;
149
+ secrets: string[];
150
+ identifiers: string[];
151
+ methods: string[];
152
+ baseUrl: string;
153
+ target: (path: string, search: string, base: string) => URL | undefined;
154
+ authorize: (request: Request, env: DevEnv) => Request;
155
+ };
156
+ };
157
+ /**
158
+ * The dev proxy's Fetch handler. `GET <basePath>/` is the manifest; `<basePath>/<id>/...` relays
159
+ * to that provider's dev resource. Fails closed: a request that is not same-origin (see
160
+ * `allowOrigins`, `trustNonBrowser`) answers 403 `cross_origin`, and a provider whose env values are
161
+ * not all allow-listed (or match a production format) answers 403 `not_allowed`; neither sends
162
+ * anything.
163
+ * Throws when `allow` is missing or holds an unanchored pattern.
164
+ */
165
+ declare const createDevProxy: (options: DevProxyOptions) => ((request: Request) => Promise<Response>);
166
+ /**
167
+ * A Cloudflare Worker:
168
+ * `export default devProxyWorker({ basePath: "/__dev", providers, allow })`.
169
+ * Options are validated once, here; secrets are read from the Worker env per call.
170
+ */
171
+ declare const devProxyWorker: (options: Omit<DevProxyOptions, "env">) => {
172
+ fetch(request: Request, env: DevEnv): Promise<Response>;
173
+ };
174
+
175
+ export { NON_PROD_PATTERNS, createDevProxy, devBaseUrlName, devProviders, devProxyWorker };
176
+ export type { DevEnv, DevManifest, DevProvider, DevProxyOptions };
@@ -0,0 +1,15 @@
1
+ import {
2
+ NON_PROD_PATTERNS,
3
+ createDevProxy,
4
+ devBaseUrlName,
5
+ devProviders,
6
+ devProxyWorker
7
+ } from "./chunk-WAMTSUKW.js";
8
+ export {
9
+ NON_PROD_PATTERNS,
10
+ createDevProxy,
11
+ devBaseUrlName,
12
+ devProviders,
13
+ devProxyWorker
14
+ };
15
+ //# sourceMappingURL=dev-proxy.js.map
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { P as PreviewFetch, a as PreviewPort } from './types-CQYnWD6z.js';
2
2
  export { c as createPreviewClient, s as servePreviewPort } from './types-CQYnWD6z.js';
3
- export { SANDBOX_KEY_HEADER, SandboxAccess, SandboxEnv, SandboxManifest, SandboxProvider, SandboxProxyOptions, createSandboxProxy, safeEqual, sandboxProviders, sandboxProxyWorker } from './sandbox-proxy.js';
3
+ export { DevEnv, DevManifest, DevProvider, DevProxyOptions, NON_PROD_PATTERNS, createDevProxy, devBaseUrlName, devProviders, devProxyWorker } from './dev-proxy.js';
4
4
 
5
5
  type PreviewDownload = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
6
6
  type PreviewArtifact = {
@@ -98,40 +98,8 @@ declare function createCloudflarePreviews(options: {
98
98
  remove: (name: string) => Promise<void>;
99
99
  };
100
100
 
101
- type PreviewSystem = {
102
- fetch: PreviewFetch;
103
- dispose?: () => void | Promise<void>;
104
- };
105
- type PreviewHostStatus = {
106
- state: "starting" | "ready" | "failed" | "disposed";
107
- generation: number;
108
- artifact: string;
109
- clients: number;
110
- };
111
- /** Boot and reset are serialized. Each connection owns its requests, never the shared system. */
112
- declare function createPreviewHost(options: {
113
- artifact: string;
114
- boot: (context: {
115
- generation: number;
116
- signal: AbortSignal;
117
- }) => PreviewSystem | Promise<PreviewSystem>;
118
- allow?: (url: URL) => boolean;
119
- }): {
120
- connect: (port: PreviewPort) => () => void;
121
- fetch: PreviewFetch;
122
- reset: () => Promise<void>;
123
- dispose: () => Promise<void>;
124
- status: () => PreviewHostStatus;
125
- ready: () => Promise<void>;
126
- };
127
- declare function sharedPreviewWorkerName(identity: {
128
- application: string;
129
- artifact: string;
130
- generation: number;
131
- }): string;
132
-
133
- type SandboxMode = "emulated" | "sandbox";
134
- type SandboxServiceSpec = {
101
+ type DevMode = "emulated" | "dev";
102
+ type DevServiceSpec = {
135
103
  /** Provider id at the proxy, e.g. "stripe". */
136
104
  id: string;
137
105
  /** "Stripe" */
@@ -144,19 +112,19 @@ type SandboxServiceSpec = {
144
112
  unsupported?: string;
145
113
  };
146
114
  /** Structurally identical to `SystemServiceMode` in `@crvouga/mockingbird-ui`. */
147
- type SystemServiceModeLike = "emulated" | "sandbox";
115
+ type SystemServiceModeLike = "emulated" | "dev";
148
116
  /** Structurally identical to `SystemService` in `@crvouga/mockingbird-ui`. */
149
117
  type SystemServiceLike = {
150
118
  id: string;
151
119
  label: string;
152
120
  category?: string;
153
121
  mode: SystemServiceModeLike;
154
- /** Why sandbox cannot be chosen; undefined when it can. */
122
+ /** Why dev cannot be chosen; undefined when it can. */
155
123
  unavailable?: string;
156
124
  };
157
- /** Structurally identical to `SystemSandboxStatus` in `@crvouga/mockingbird-ui`. */
158
- type SystemSandboxStatusLike = {
159
- state: "ready" | "locked" | "off" | "unreachable" | "none";
125
+ /** Structurally identical to `SystemDevStatus` in `@crvouga/mockingbird-ui`. */
126
+ type SystemDevStatusLike = {
127
+ state: "ready" | "unreachable" | "none";
160
128
  /** One sentence shown in the access panel. */
161
129
  message: string;
162
130
  /** The proxy URL, displayed. */
@@ -165,44 +133,71 @@ type SystemSandboxStatusLike = {
165
133
  /** Structurally identical to `SystemServices` in `@crvouga/mockingbird-ui`. */
166
134
  type SystemServicesLike = {
167
135
  list(): Promise<{
168
- sandbox: SystemSandboxStatusLike;
136
+ dev: SystemDevStatusLike;
169
137
  services: readonly SystemServiceLike[];
170
138
  }>;
171
139
  setMode(id: string, mode: SystemServiceModeLike): Promise<void>;
172
- setAccessKey(key: string | null): Promise<void>;
173
- hasAccessKey(): boolean;
174
140
  };
175
- type SandboxUpstream = {
141
+ type DevUpstream = {
176
142
  baseUrl: string;
177
143
  fetch: (request: Request) => Promise<Response>;
178
144
  rewriteAuth: (request: Request) => Request;
179
145
  };
180
- type Sandbox = {
181
- /** For createRuntime({ upstream }): baseUrl `${proxy}/${id}`, fetch adds SANDBOX_KEY_HEADER, rewriteAuth drops authorization. */
182
- upstream(id: string): SandboxUpstream;
146
+ type DevResources = {
147
+ /** For createRuntime({ upstream }): baseUrl `${proxy}/${id}`, fetch goes to the proxy as-is, rewriteAuth drops authorization and cookies. */
148
+ upstream(id: string): DevUpstream;
183
149
  /** The SystemServices provider the UI harness takes. */
184
- controls(services: readonly SandboxServiceSpec[]): SystemServicesLike;
150
+ controls(services: readonly DevServiceSpec[]): SystemServicesLike;
185
151
  };
186
- type SandboxStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
187
- type SandboxOptions = {
188
- /** Absolute, or relative to location.origin (e.g. "/__sandbox"). Undefined = sandbox not offered. */
152
+ type DevStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
153
+ type DevResourcesOptions = {
154
+ /** Absolute, or relative to location.origin (e.g. "/__dev"). Undefined = dev resources not offered. */
189
155
  proxyUrl?: string;
190
- /** Per-viewer storage for the access key and chosen modes. Default: localStorage, try/catch wrapped. */
191
- storage?: SandboxStorage;
156
+ /** Per-viewer storage for the chosen modes. Default: localStorage, try/catch wrapped. */
157
+ storage?: DevStorage;
192
158
  fetch?: (request: Request) => Promise<Response>;
193
159
  };
194
160
  /** Storage keys (per origin). */
195
- declare const SANDBOX_STORAGE_KEYS: {
196
- readonly accessKey: "mockingbird.sandbox.access-key";
197
- readonly modes: "mockingbird.sandbox.modes";
161
+ declare const DEV_STORAGE_KEYS: {
162
+ readonly modes: "mockingbird.dev.modes";
198
163
  };
199
- declare const SANDBOX_MESSAGES: {
200
- readonly none: "No sandbox proxy is configured for this preview";
201
- readonly off: "The proxy has no SANDBOX_PROXY_TOKEN, so sandbox mode is off";
202
- readonly locked: "Enter the sandbox access key";
203
- readonly ready: "Sandbox access is granted: switch a service to send its requests to the vendor's sandbox";
164
+ declare const DEV_MESSAGES: {
165
+ readonly none: "No dev proxy is configured for this preview";
166
+ readonly ready: "Dev resources are available: switch a service to send its requests to its dev resource";
204
167
  };
205
- declare const createSandbox: (options?: SandboxOptions) => Sandbox;
168
+ declare const createDevResources: (options?: DevResourcesOptions) => DevResources;
169
+
170
+ type PreviewSystem = {
171
+ fetch: PreviewFetch;
172
+ dispose?: () => void | Promise<void>;
173
+ };
174
+ type PreviewHostStatus = {
175
+ state: "starting" | "ready" | "failed" | "disposed";
176
+ generation: number;
177
+ artifact: string;
178
+ clients: number;
179
+ };
180
+ /** Boot and reset are serialized. Each connection owns its requests, never the shared system. */
181
+ declare function createPreviewHost(options: {
182
+ artifact: string;
183
+ boot: (context: {
184
+ generation: number;
185
+ signal: AbortSignal;
186
+ }) => PreviewSystem | Promise<PreviewSystem>;
187
+ allow?: (url: URL) => boolean;
188
+ }): {
189
+ connect: (port: PreviewPort) => () => void;
190
+ fetch: PreviewFetch;
191
+ reset: () => Promise<void>;
192
+ dispose: () => Promise<void>;
193
+ status: () => PreviewHostStatus;
194
+ ready: () => Promise<void>;
195
+ };
196
+ declare function sharedPreviewWorkerName(identity: {
197
+ application: string;
198
+ artifact: string;
199
+ generation: number;
200
+ }): string;
206
201
 
207
202
  declare function connectSharedPreviewWorker(url: string | URL, options: {
208
203
  application: string;
@@ -230,5 +225,5 @@ type WorkerScope = {
230
225
  /** Installs shared-worker connect events or dedicated-worker transferred-port handshakes. */
231
226
  declare function installPreviewWorkerHost(host: ReturnType<typeof createPreviewHost>, scope: WorkerScope): () => Promise<void>;
232
227
 
233
- export { PreviewFetch, PreviewPort, SANDBOX_MESSAGES, SANDBOX_STORAGE_KEYS, connectDedicatedPreviewWorker, connectSharedPreviewWorker, createCloudflarePreviews, createPreviewArtifact, createPreviewHost, createSandbox, digestPreviewBytes, installPreviewWorkerHost, loadPreviewArtifact, parsePreviewArtifact, planPreviewSweep, selectPreviewAction, sharedPreviewWorkerName };
234
- export type { CloudflarePreview, LegacyPreviewArtifact, ManagedPreview, PreviewArtifact, PreviewAssetFile, PreviewDownload, PreviewHostStatus, PreviewSystem, PullRequestFacts, Sandbox, SandboxMode, SandboxOptions, SandboxServiceSpec, SandboxStorage, SandboxUpstream, SystemSandboxStatusLike, SystemServiceLike, SystemServiceModeLike, SystemServicesLike };
228
+ export { DEV_MESSAGES, DEV_STORAGE_KEYS, PreviewFetch, PreviewPort, connectDedicatedPreviewWorker, connectSharedPreviewWorker, createCloudflarePreviews, createDevResources, createPreviewArtifact, createPreviewHost, digestPreviewBytes, installPreviewWorkerHost, loadPreviewArtifact, parsePreviewArtifact, planPreviewSweep, selectPreviewAction, sharedPreviewWorkerName };
229
+ export type { CloudflarePreview, DevMode, DevResources, DevResourcesOptions, DevServiceSpec, DevStorage, DevUpstream, LegacyPreviewArtifact, ManagedPreview, PreviewArtifact, PreviewAssetFile, PreviewDownload, PreviewHostStatus, PreviewSystem, PullRequestFacts, SystemDevStatusLike, SystemServiceLike, SystemServiceModeLike, SystemServicesLike };