@rexezuge/tooling 0.0.0-stage → 1.0.0

package/dist/functions/pages-proxy.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The Cloudflare Pages catch-all proxy.
+ *
+ * Provenance: the `functions/[[path]].ts` shim duplicated in Durable-DAV,
+ * Mail-Meow and Edge-Git (and present in nine repos in total). Each copy is an
+ * `onRequest` handler that forwards the request to the API worker through a
+ * service binding, rewriting the three headers the worker routes on.
+ *
+ * What each source contributes:
+ *
+ * - **Durable-DAV / Edge-Git** — the core shape: set `X-Forwarded-Host`,
+ *   `X-Forwarded-Proto` and `X-Forwarded-Uri` from the original URL, forward the
+ *   body for non-GET/HEAD methods, and hand the request to `env.API_WORKER`.
+ * - **Mail-Meow** — the hop-by-hop header strip, and the decision to *always*
+ *   delete `X-Forwarded-For` before conditionally setting it from
+ *   `CF-Connecting-IP`. Setting it only when the header was present left a
+ *   caller-supplied value intact on any request that reached Pages without
+ *   `CF-Connecting-IP`, so the origin would trust an attacker-chosen client IP.
+ * - **Durable-DAV-Router** — `duplex: 'half'`, required whenever the forwarded
+ *   body is a stream. Without it this threw a `TypeError` on every non-GET
+ *   request rather than proxying it.
+ * - **Edge-Sonic** — the client-forwarding-header strip list, which additionally
+ *   removes `Forwarded`, `True-Client-IP` and `X-Real-Ip`. Edge-Sonic goes
+ *   further and *never* sets `X-Forwarded-For` at all, because its worker keys
+ *   the rate limiter on `CF-Connecting-IP` and refuses `X-Forwarded-For` on
+ *   purpose.
+ *
+ * ### The convergence decision on `X-Forwarded-For`
+ *
+ * The two families disagree, and the disagreement is about which worker is
+ * behind the binding. Mail-Meow's behaviour is kept as the default because it is
+ * the only one that preserves the client IP for the audit trail, which five repos
+ * read. A repo whose worker refuses the header — Edge-Sonic's — passes
+ * `forwardClientIp: false`, which deletes it and sets nothing. What is *not*
+ * available is the source repos' conditional `if (clientIp) set(...)`: that is
+ * the defect Mail-Meow recorded fixing, and a factory that could reintroduce it
+ * would be a factory that carries the bug forward.
+ *
+ * ### `duplex: 'half'` rides with the body
+ *
+ * Required by the Fetch spec whenever a `Request` is constructed with a **stream**
+ * body. workerd does not throw without it, which is why the line was absent from
+ * every Pages copy — and Node does, which is why `test/pages-proxy.test.ts` in
+ * Edge-Sonic could not drive the handler at all. It is spread only where a body
+ * is forwarded, because a `RequestInit` carrying `duplex` and no body is a shape
+ * no runtime documents; the cast is `as RequestInit` either way, since `duplex`
+ * is not in the DOM lib's type.
+ *
+ * The result is a handler factory, so a consumer's `functions/[[path]].ts` is a
+ * one-line re-export. Structural `Fetcher` and `PagesFunction` types are declared
+ * here rather than imported from `@cloudflare/workers-types`, so the kit stays
+ * zero-dependency and this module typechecks without the generated
+ * `worker-configuration.d.ts`.
+ */
+/**
+ * The subset of Cloudflare's `Fetcher` this proxy uses.
+ *
+ * Structural, not imported: the shim only ever calls `fetch`, and requiring
+ * `@cloudflare/workers-types` for one method would couple the kit to a generated
+ * types file that only exists inside a Wrangler project.
+ */
+export interface Fetcher {
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+/**
+ * The environment a Pages Function is invoked with.
+ */
+export interface PagesProxyEnv {
+    readonly API_WORKER: Fetcher;
+}
+/**
+ * The context Cloudflare passes to `onRequest`.
+ *
+ * Only the fields this proxy reads are declared. `params` and `waitUntil` are
+ * omitted because the catch-all does not use them — a shim that named them would
+ * be claiming a contract it does not exercise.
+ */
+export interface PagesFunctionContext {
+    readonly request: Request;
+    readonly env: PagesProxyEnv;
+}
+/**
+ * A Pages Function handler.
+ */
+export type PagesFunction = (context: PagesFunctionContext) => Promise<Response>;
+/**
+ * What `createPagesProxy` accepts.
+ */
+export interface PagesProxyOptions {
+    /**
+     * Set `X-Forwarded-For` from `CF-Connecting-IP`.
+     *
+     * Default `true` — Mail-Meow's behaviour, which five repos rely on for their
+     * audit trail. Pass `false` for a worker that refuses the header outright
+     * (Edge-Sonic's does), and the header is deleted and nothing set.
+     */
+    readonly forwardClientIp?: boolean;
+}
+/**
+ * The `onRequest` handler for `functions/[[path]].ts`.
+ *
+ * Usage — the consumer's `functions/[[path]].ts` becomes two lines:
+ *
+ * ```ts
+ * import { createPagesProxy } from '@rexezuge/tooling/functions/pages-proxy';
+ * export const onRequest = createPagesProxy();
+ * ```
+ *
+ * @param options see {@link PagesProxyOptions}. Omitted gives the family's
+ *   majority behaviour.
+ */
+export declare function createPagesProxy(options?: PagesProxyOptions): PagesFunction;
+//# sourceMappingURL=pages-proxy.d.ts.map

package/dist/functions/pages-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages-proxy.d.ts","sourceRoot":"","sources":["../../src/functions/pages-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7E;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAgCjF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,aAAa,CAuC/E"}

package/dist/functions/pages-proxy.js

@@ -0,0 +1,131 @@
+/**
+ * The Cloudflare Pages catch-all proxy.
+ *
+ * Provenance: the `functions/[[path]].ts` shim duplicated in Durable-DAV,
+ * Mail-Meow and Edge-Git (and present in nine repos in total). Each copy is an
+ * `onRequest` handler that forwards the request to the API worker through a
+ * service binding, rewriting the three headers the worker routes on.
+ *
+ * What each source contributes:
+ *
+ * - **Durable-DAV / Edge-Git** — the core shape: set `X-Forwarded-Host`,
+ *   `X-Forwarded-Proto` and `X-Forwarded-Uri` from the original URL, forward the
+ *   body for non-GET/HEAD methods, and hand the request to `env.API_WORKER`.
+ * - **Mail-Meow** — the hop-by-hop header strip, and the decision to *always*
+ *   delete `X-Forwarded-For` before conditionally setting it from
+ *   `CF-Connecting-IP`. Setting it only when the header was present left a
+ *   caller-supplied value intact on any request that reached Pages without
+ *   `CF-Connecting-IP`, so the origin would trust an attacker-chosen client IP.
+ * - **Durable-DAV-Router** — `duplex: 'half'`, required whenever the forwarded
+ *   body is a stream. Without it this threw a `TypeError` on every non-GET
+ *   request rather than proxying it.
+ * - **Edge-Sonic** — the client-forwarding-header strip list, which additionally
+ *   removes `Forwarded`, `True-Client-IP` and `X-Real-Ip`. Edge-Sonic goes
+ *   further and *never* sets `X-Forwarded-For` at all, because its worker keys
+ *   the rate limiter on `CF-Connecting-IP` and refuses `X-Forwarded-For` on
+ *   purpose.
+ *
+ * ### The convergence decision on `X-Forwarded-For`
+ *
+ * The two families disagree, and the disagreement is about which worker is
+ * behind the binding. Mail-Meow's behaviour is kept as the default because it is
+ * the only one that preserves the client IP for the audit trail, which five repos
+ * read. A repo whose worker refuses the header — Edge-Sonic's — passes
+ * `forwardClientIp: false`, which deletes it and sets nothing. What is *not*
+ * available is the source repos' conditional `if (clientIp) set(...)`: that is
+ * the defect Mail-Meow recorded fixing, and a factory that could reintroduce it
+ * would be a factory that carries the bug forward.
+ *
+ * ### `duplex: 'half'` rides with the body
+ *
+ * Required by the Fetch spec whenever a `Request` is constructed with a **stream**
+ * body. workerd does not throw without it, which is why the line was absent from
+ * every Pages copy — and Node does, which is why `test/pages-proxy.test.ts` in
+ * Edge-Sonic could not drive the handler at all. It is spread only where a body
+ * is forwarded, because a `RequestInit` carrying `duplex` and no body is a shape
+ * no runtime documents; the cast is `as RequestInit` either way, since `duplex`
+ * is not in the DOM lib's type.
+ *
+ * The result is a handler factory, so a consumer's `functions/[[path]].ts` is a
+ * one-line re-export. Structural `Fetcher` and `PagesFunction` types are declared
+ * here rather than imported from `@cloudflare/workers-types`, so the kit stays
+ * zero-dependency and this module typechecks without the generated
+ * `worker-configuration.d.ts`.
+ */
+/**
+ * Headers a *client* may have set, stripped before the request crosses the
+ * binding.
+ *
+ * These describe the connection between the client and the proxy. Forwarding
+ * them would let the origin believe the proxy's view of the client is the
+ * client's own claim about itself. The three the proxy sets itself are set from
+ * values it reads off the request, not from the client's headers.
+ */
+const CLIENT_FORWARDING_HEADERS = [
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'X-Forwarded-For',
+    'X-Forwarded-Host',
+    'X-Forwarded-Proto',
+    'X-Forwarded-Uri',
+    'Forwarded',
+    'True-Client-IP',
+    'X-Real-Ip',
+];
+/** The header Cloudflare sets with the socket's peer address. */
+const CF_CONNECTING_IP_HEADER = 'CF-Connecting-IP';
+/**
+ * The `onRequest` handler for `functions/[[path]].ts`.
+ *
+ * Usage — the consumer's `functions/[[path]].ts` becomes two lines:
+ *
+ * ```ts
+ * import { createPagesProxy } from '@rexezuge/tooling/functions/pages-proxy';
+ * export const onRequest = createPagesProxy();
+ * ```
+ *
+ * @param options see {@link PagesProxyOptions}. Omitted gives the family's
+ *   majority behaviour.
+ */
+export function createPagesProxy(options = {}) {
+    const forwardClientIp = options.forwardClientIp ?? true;
+    return async ({ request, env }) => {
+        const originalUrl = new URL(request.url);
+        const headers = new Headers(request.headers);
+        for (const header of CLIENT_FORWARDING_HEADERS)
+            headers.delete(header);
+        // Set from values read off the request rather than from the client: only the
+        // proxy knows which host it served, and a service binding hands over a
+        // rewritten URL, so the original path is what has to be carried across.
+        headers.set('X-Forwarded-Host', originalUrl.host);
+        headers.set('X-Forwarded-Proto', originalUrl.protocol.replace(':', ''));
+        headers.set('X-Forwarded-Uri', `${originalUrl.pathname}${originalUrl.search}`);
+        if (forwardClientIp) {
+            const clientIp = request.headers.get(CF_CONNECTING_IP_HEADER);
+            if (clientIp)
+                headers.set('X-Forwarded-For', clientIp);
+        }
+        // `GET`/`HEAD` carry no body, and a `Request` with one is rejected outright
+        // for those methods. The body is forwarded as a *stream*, so a large upload
+        // does not have to fit in memory on the Pages side.
+        const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+        const proxyRequest = new Request(originalUrl.href, {
+            method: request.method,
+            headers,
+            body: hasBody ? request.body : undefined,
+            // See the header: `duplex` is not in the DOM lib's `RequestInit` type, and
+            // removing the cast would mean not forwarding bodies at all, which is a
+            // worse answer than one assertion.
+            ...(hasBody && { duplex: 'half' }),
+            redirect: request.redirect,
+        });
+        return env.API_WORKER.fetch(proxyRequest);
+    };
+}
+//# sourceMappingURL=pages-proxy.js.map

package/dist/functions/pages-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages-proxy.js","sourceRoot":"","sources":["../../src/functions/pages-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAqCH;;;;;;;;GAQG;AACH,MAAM,yBAAyB,GAAsB;IACnD,YAAY;IACZ,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,IAAI;IACJ,SAAS;IACT,mBAAmB;IACnB,SAAS;IACT,iBAAiB;IACjB,kBAAkB;IAClB,mBAAmB;IACnB,iBAAiB;IACjB,WAAW;IACX,gBAAgB;IAChB,WAAW;CACZ,CAAC;AAEF,iEAAiE;AACjE,MAAM,uBAAuB,GAAG,kBAAkB,CAAC;AAgBnD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA6B,EAAE;IAC9D,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;IAExD,OAAO,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAwB,EAAqB,EAAE;QACzE,MAAM,WAAW,GAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAE9C,MAAM,OAAO,GAAY,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACtD,KAAK,MAAM,MAAM,IAAI,yBAAyB;YAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEvE,6EAA6E;QAC7E,uEAAuE;QACvE,wEAAwE;QACxE,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;QAE/E,IAAI,eAAe,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAkB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;YAC7E,IAAI,QAAQ;gBAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;QACzD,CAAC;QAED,4EAA4E;QAC5E,4EAA4E;QAC5E,oDAAoD;QACpD,MAAM,OAAO,GAAY,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC;QAE/E,MAAM,YAAY,GAAY,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE;YAC1D,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO;YACP,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YACxC,2EAA2E;YAC3E,wEAAwE;YACxE,mCAAmC;YACnC,GAAG,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ;SACZ,CAAC,CAAC;QAElB,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@rexezuge/tooling` — the tooling layer of the kit.
+ *
+ * The config factories and the test helpers are re-exported here, so a consumer has
+ * one import for everything its `*.config.mts` files and its mocks need. The
+ * scripts under `scripts/` are **not** re-exported: they resolve paths relative to
+ * the repository they run in, so they are run from disk with `tsx`, not imported.
+ * See `README.md` for the copy-in recipe and the per-script usage.
+ *
+ * The zero-dependency rule: nothing here imports another `@rexezuge/*` package. The
+ * one exception in the tree is `scripts/backup/encrypt-backup.ts`, which uses
+ * `@rexezuge/d1`'s AES-GCM so the backup and the workers share one definition of
+ * "what an encryption key looks like"; that dependency is declared on the package
+ * and is only ever resolved in the consumer's repo, where the kit is installed
+ * alongside `@rexezuge/d1`.
+ */
+export { defineRepoLintConfig } from './eslint';
+export type { RepoLintConfigOptions } from './eslint';
+export { defineUnitVitestConfig } from './vitest';
+export type { CoverageThresholds, UnitVitestConfigOptions, VitestAlias } from './vitest';
+export { defineWebVitestConfig } from './vitest-web';
+export type { WebVitestConfigOptions } from './vitest-web';
+export { defineWebViteConfig, spaShellEmbedPlugin } from './vite';
+export type { ProxyEntry, SpaShellTarget, WebViteConfigOptions } from './vite';
+export { createPagesProxy } from './functions/pages-proxy';
+export type { Fetcher, PagesFunction, PagesFunctionContext, PagesProxyEnv, PagesProxyOptions } from './functions/pages-proxy';
+export { DurableObject, RpcTarget, WorkflowEntrypoint } from './test/mocks/cloudflare-workers';
+export type { DurableObjectState, ExecutionContext } from './test/mocks/cloudflare-workers';
+export { createMigrationHelper, readMigrationFiles, splitSql } from './test/integration-migrations';
+export type { D1DatabaseLike, D1PreparedStatementLike, MigrationFile, MigrationHelper, MigrationHelperOptions, MigrationRange } from './test/integration-migrations';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAClE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAO9H,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC/F,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAE5F,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACpG,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,aAAa,EAAE,eAAe,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@rexezuge/tooling` — the tooling layer of the kit.
+ *
+ * The config factories and the test helpers are re-exported here, so a consumer has
+ * one import for everything its `*.config.mts` files and its mocks need. The
+ * scripts under `scripts/` are **not** re-exported: they resolve paths relative to
+ * the repository they run in, so they are run from disk with `tsx`, not imported.
+ * See `README.md` for the copy-in recipe and the per-script usage.
+ *
+ * The zero-dependency rule: nothing here imports another `@rexezuge/*` package. The
+ * one exception in the tree is `scripts/backup/encrypt-backup.ts`, which uses
+ * `@rexezuge/d1`'s AES-GCM so the backup and the workers share one definition of
+ * "what an encryption key looks like"; that dependency is declared on the package
+ * and is only ever resolved in the consumer's repo, where the kit is installed
+ * alongside `@rexezuge/d1`.
+ */
+export { defineRepoLintConfig } from './eslint';
+export { defineUnitVitestConfig } from './vitest';
+export { defineWebVitestConfig } from './vitest-web';
+export { defineWebViteConfig, spaShellEmbedPlugin } from './vite';
+export { createPagesProxy } from './functions/pages-proxy';
+// --- Test helpers ---------------------------------------------------------
+//
+// Aliased in a Vitest config, not imported by application code, so the mocks stay
+// where the suites can reach them.
+export { DurableObject, RpcTarget, WorkflowEntrypoint } from './test/mocks/cloudflare-workers';
+export { createMigrationHelper, readMigrationFiles, splitSql } from './test/integration-migrations';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAGlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,6EAA6E;AAC7E,EAAE;AACF,kFAAkF;AAClF,mCAAmC;AAEnC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAG/F,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/scripts/backup/d1-target.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Choosing which D1 database the backup workflow exports.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/backup/d1-target.ts`. Pure, so the
+ * empty-database guard is asserted without running Actions or touching a real
+ * account.
+ */
+/** A D1 binding as a parsed wrangler config carries one. */
+export interface D1DatabaseBinding {
+    binding?: string;
+    database_id?: string;
+    database_name?: string;
+}
+/** The resolved export target. */
+export interface D1Target {
+    /** The binding name, used for log output and as the export fallback. */
+    binding: string;
+    /** The database id, verified against Cloudflare by the caller. */
+    databaseId: string;
+    /** What `wrangler d1 export` should be pointed at. */
+    target: string;
+}
+/**
+ * Pick the export target from a parsed wrangler config.
+ *
+ * `wrangler d1 export` takes a database *name*, so `database_name` wins when
+ * present. Hand-written configs that omit it fall back to the binding name.
+ *
+ * @throws when there is no binding, or when `database_id` is still the template
+ *   placeholder — meaning the database was auto-provisioned and holds no data.
+ */
+export declare function resolveD1Target(config: {
+    d1_databases?: D1DatabaseBinding[];
+}): D1Target;
+//# sourceMappingURL=d1-target.d.ts.map

package/dist/scripts/backup/d1-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1-target.d.ts","sourceRoot":"","sources":["../../../src/scripts/backup/d1-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAA;CAAE,GAAG,QAAQ,CAiBxF"}

package/dist/scripts/backup/d1-target.js

@@ -0,0 +1,31 @@
+/**
+ * Choosing which D1 database the backup workflow exports.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/backup/d1-target.ts`. Pure, so the
+ * empty-database guard is asserted without running Actions or touching a real
+ * account.
+ */
+import { DEFAULT_UUID } from '../wrangler-config/types';
+/**
+ * Pick the export target from a parsed wrangler config.
+ *
+ * `wrangler d1 export` takes a database *name*, so `database_name` wins when
+ * present. Hand-written configs that omit it fall back to the binding name.
+ *
+ * @throws when there is no binding, or when `database_id` is still the template
+ *   placeholder — meaning the database was auto-provisioned and holds no data.
+ */
+export function resolveD1Target(config) {
+    const database = config.d1_databases?.[0];
+    const binding = database?.binding?.trim();
+    if (binding === undefined || binding === '') {
+        throw new Error('No d1_databases entry with a binding found in wrangler.jsonc.');
+    }
+    const databaseId = database?.database_id?.trim() ?? '';
+    if (databaseId === DEFAULT_UUID) {
+        throw new Error(`D1 database_id for ${binding} is still the template placeholder. The database does not exist yet, so there is nothing to back up.`);
+    }
+    const target = database?.database_name?.trim() || binding;
+    return { binding, databaseId, target };
+}
+//# sourceMappingURL=d1-target.js.map

package/dist/scripts/backup/d1-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1-target.js","sourceRoot":"","sources":["../../../src/scripts/backup/d1-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAmBxD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAA8C;IAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;IAE1C,MAAM,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,UAAU,KAAK,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,sBAAsB,OAAO,sGAAsG,CACpI,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC;IAC1D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC"}

package/dist/scripts/backup/destination-config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Destination and encryption policy for the D1 backup workflow.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/backup/destination-config.ts`.
+ * Pure and side-effect free, so the fail-closed rules are asserted without running
+ * Actions.
+ */
+/** The environment the `check-secrets` job is given, as repository secrets. */
+export interface BackupSecretEnvironment {
+    CLOUDFLARE_API_TOKEN?: string;
+    CLOUDFLARE_ACCOUNT_ID?: string;
+    BACKUP_ENCRYPTION_KEY?: string;
+    S3_ACCESS_KEY_ID?: string;
+    S3_SECRET_ACCESS_KEY?: string;
+    S3_BUCKET?: string;
+    WEBDAV_URL?: string;
+    WEBDAV_USER?: string;
+    WEBDAV_PASSWORD?: string;
+}
+/** What is configured, and why the run cannot proceed when it is not. */
+export interface DestinationConfig {
+    /** Cloudflare credentials present, so the export job can run. */
+    cloudflare: boolean;
+    /** An encryption passphrase is available. */
+    encryption: boolean;
+    /** At least one upload destination is configured. */
+    anyDestination: boolean;
+    /** The S3 destination is fully configured. */
+    s3: boolean;
+    /** The WebDAV destination is fully configured. */
+    webdav: boolean;
+    /** Human-readable reasons the run cannot proceed, empty when it can. */
+    errors: string[];
+}
+/**
+ * Decides which destinations are configured and enforces fail-closed encryption.
+ *
+ * ### Why the encryption requirement is not optional here
+ *
+ * Two independent reasons, and they have different consequences so both are stated.
+ *
+ * **The at-rest protection assumes the dump is not in hand.** Every repo in this
+ * family seals credentials with AES-256-GCM, and each one's migration notes say the
+ * same thing: *obfuscation against a D1 dump, not protection against a full worker
+ * compromise.* An unencrypted backup inverts that assumption — dump plus the
+ * Secrets Store key is a complete credential set, and the WebDAV key is read on
+ * every scan and every stream.
+ *
+ * **The dump is a listening history.** Stars, ratings, play counts, play queues and
+ * auth failures record what each user does and when, and the schema records the
+ * full topology and every file path. None of that is credential material, and all
+ * of it is nobody else's to read.
+ *
+ * `S3_REGION` is deliberately not part of the S3 gate. R2 and MinIO have no
+ * meaningful region — Cloudflare documents an R2 bucket's region as `auto`, with
+ * empty and `us-east-1` both aliasing to it — so requiring the secret would
+ * silently disable backups for anyone using such a provider. The upload script
+ * defaults `AWS_DEFAULT_REGION` to `auto` instead.
+ */
+export declare function evaluateConfig(env: BackupSecretEnvironment): DestinationConfig;
+//# sourceMappingURL=destination-config.d.ts.map

package/dist/scripts/backup/destination-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"destination-config.d.ts","sourceRoot":"","sources":["../../../src/scripts/backup/destination-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IACpB,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,EAAE,EAAE,OAAO,CAAC;IACZ,kDAAkD;IAClD,MAAM,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAOD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,uBAAuB,GAAG,iBAAiB,CAwB9E"}

package/dist/scripts/backup/destination-config.js

@@ -0,0 +1,57 @@
+/**
+ * Destination and encryption policy for the D1 backup workflow.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/backup/destination-config.ts`.
+ * Pure and side-effect free, so the fail-closed rules are asserted without running
+ * Actions.
+ */
+/** A secret counts as set only when it has non-whitespace content. */
+function isSet(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Decides which destinations are configured and enforces fail-closed encryption.
+ *
+ * ### Why the encryption requirement is not optional here
+ *
+ * Two independent reasons, and they have different consequences so both are stated.
+ *
+ * **The at-rest protection assumes the dump is not in hand.** Every repo in this
+ * family seals credentials with AES-256-GCM, and each one's migration notes say the
+ * same thing: *obfuscation against a D1 dump, not protection against a full worker
+ * compromise.* An unencrypted backup inverts that assumption — dump plus the
+ * Secrets Store key is a complete credential set, and the WebDAV key is read on
+ * every scan and every stream.
+ *
+ * **The dump is a listening history.** Stars, ratings, play counts, play queues and
+ * auth failures record what each user does and when, and the schema records the
+ * full topology and every file path. None of that is credential material, and all
+ * of it is nobody else's to read.
+ *
+ * `S3_REGION` is deliberately not part of the S3 gate. R2 and MinIO have no
+ * meaningful region — Cloudflare documents an R2 bucket's region as `auto`, with
+ * empty and `us-east-1` both aliasing to it — so requiring the secret would
+ * silently disable backups for anyone using such a provider. The upload script
+ * defaults `AWS_DEFAULT_REGION` to `auto` instead.
+ */
+export function evaluateConfig(env) {
+    const cloudflare = isSet(env.CLOUDFLARE_API_TOKEN) && isSet(env.CLOUDFLARE_ACCOUNT_ID);
+    const encryption = isSet(env.BACKUP_ENCRYPTION_KEY);
+    const s3 = isSet(env.S3_ACCESS_KEY_ID) && isSet(env.S3_SECRET_ACCESS_KEY) && isSet(env.S3_BUCKET);
+    const webdav = isSet(env.WEBDAV_URL) && isSet(env.WEBDAV_USER) && isSet(env.WEBDAV_PASSWORD);
+    const anyDestination = s3 || webdav;
+    const errors = [];
+    // Fail closed, but only once someone has opted into a destination. An
+    // unconfigured repository is a legitimate "I do not want off-site backups" state
+    // and must not turn the schedule red.
+    if (anyDestination) {
+        if (!cloudflare) {
+            errors.push('A backup destination is configured but CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID are missing.');
+        }
+        if (!encryption) {
+            errors.push('BACKUP_ENCRYPTION_KEY is required. The D1 dump holds AES-GCM-obfuscated credentials — obfuscation that, by its own design, assumes the dump is not in hand — plus every user history and the full schema topology.');
+        }
+    }
+    return { cloudflare, encryption, anyDestination, s3, webdav, errors };
+}
+//# sourceMappingURL=destination-config.js.map

package/dist/scripts/backup/destination-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destination-config.js","sourceRoot":"","sources":["../../../src/scripts/backup/destination-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+BH,sEAAsE;AACtE,SAAS,KAAK,CAAC,KAAyB;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,cAAc,CAAC,GAA4B;IACzD,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACvF,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClG,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7F,MAAM,cAAc,GAAG,EAAE,IAAI,MAAM,CAAC;IAEpC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,sEAAsE;IACtE,iFAAiF;IACjF,sCAAsC;IACtC,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,kGAAkG,CAAC,CAAC;QAClH,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CACT,oNAAoN,CACrN,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACxE,CAAC"}

package/dist/scripts/backup/encrypt-backup.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env tsx
+/**
+ * Compress and encrypt the exported D1 dump.
+ *
+ * Provenance: Edge-Sonic's `scripts/backup/encrypt-backup.ts`, converged with the
+ * AES-GCM envelope every repo in the family already uses for its secrets. This is
+ * the one backup script that ported cleanly and changed *for the better* on the way
+ * in: the source shelled out to `openssl enc -aes-256-cbc -pbkdf2`, which is a
+ * password-derived key with a KDF whose cost is a constant somebody chose once,
+ * and which is not authenticated — a flipped byte in the ciphertext is undetectable.
+ *
+ * The kit's version uses `@rexezuge/d1`'s `encryptSecret`, the same WebCrypto
+ * AES-256-GCM primitive the workers use, over a base64 32-byte key — the same key
+ * format `resolveReplicationKey` reads. One definition of "what an encryption key
+ * looks like" across the deploy path and the backup path is the point: a second
+ * implementation is how a deploy ends up generating something the worker cannot
+ * read, and here it would be how a backup ends up unreadable by the restore path.
+ *
+ * Fail-closed: without `BACKUP_ENCRYPTION_KEY` the script refuses to run and
+ * deletes nothing, so an unencrypted dump can never reach the artifact store the
+ * upload jobs read from.
+ *
+ * The passphrase is read from the environment rather than passed as an argument,
+ * because command-line arguments are visible to any process on the runner via `ps`.
+ *
+ * Emits the resulting file name as the `file` step output.
+ *
+ * Usage, from the repo root (after `wrangler d1 export … --output=backup.sql`):
+ *
+ * ```bash
+ * BACKUP_ENCRYPTION_KEY=… pnpm exec tsx scripts/backup/encrypt-backup.ts
+ * ```
+ */
+export {};
+//# sourceMappingURL=encrypt-backup.d.ts.map

package/dist/scripts/backup/encrypt-backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt-backup.d.ts","sourceRoot":"","sources":["../../../src/scripts/backup/encrypt-backup.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG"}