@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
|
@@ -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 {
|
|
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
|
|
102
|
-
|
|
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" | "
|
|
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
|
|
122
|
+
/** Why dev cannot be chosen; undefined when it can. */
|
|
155
123
|
unavailable?: string;
|
|
156
124
|
};
|
|
157
|
-
/** Structurally identical to `
|
|
158
|
-
type
|
|
159
|
-
state: "ready" | "
|
|
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
|
-
|
|
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
|
|
141
|
+
type DevUpstream = {
|
|
176
142
|
baseUrl: string;
|
|
177
143
|
fetch: (request: Request) => Promise<Response>;
|
|
178
144
|
rewriteAuth: (request: Request) => Request;
|
|
179
145
|
};
|
|
180
|
-
type
|
|
181
|
-
/** For createRuntime({ upstream }): baseUrl `${proxy}/${id}`, fetch
|
|
182
|
-
upstream(id: string):
|
|
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
|
|
150
|
+
controls(services: readonly DevServiceSpec[]): SystemServicesLike;
|
|
185
151
|
};
|
|
186
|
-
type
|
|
187
|
-
type
|
|
188
|
-
/** Absolute, or relative to location.origin (e.g. "/
|
|
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
|
|
191
|
-
storage?:
|
|
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
|
|
196
|
-
readonly
|
|
197
|
-
readonly modes: "mockingbird.sandbox.modes";
|
|
161
|
+
declare const DEV_STORAGE_KEYS: {
|
|
162
|
+
readonly modes: "mockingbird.dev.modes";
|
|
198
163
|
};
|
|
199
|
-
declare const
|
|
200
|
-
readonly none: "No
|
|
201
|
-
readonly
|
|
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
|
|
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 {
|
|
234
|
-
export type { CloudflarePreview,
|
|
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 };
|