@supacloud/lite 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.3](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.8.2...supacloud-lite-v0.8.3) (2026-08-15)
+
+
+### Bug Fixes
+
+* **lite:** detect glibc in standalone runtime ([#925](https://github.com/zuohuadong/supacloud/issues/925)) ([c18f0f6](https://github.com/zuohuadong/supacloud/commit/c18f0f6ee86e488a7c603e13416e794060f2012d))
+
+## [0.8.2](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.8.1...supacloud-lite-v0.8.2) (2026-08-15)
+
+
+### Bug Fixes
+
+* **lite:** support mirrored native postgres downloads ([#916](https://github.com/zuohuadong/supacloud/issues/916)) ([48224b7](https://github.com/zuohuadong/supacloud/commit/48224b7b067fcc56b3be8059301525cebeefb98d))
+
 ## [0.8.1](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.8.0...supacloud-lite-v0.8.1) (2026-08-15)
 
 

package/README.md

@@ -135,9 +135,16 @@ supacloud-lite version
 - `SUPACLOUD_LITE_STORAGE_DIR`
 - `SUPACLOUD_LITE_STORAGE_BACKEND`：`fs`（默认）、`memory` 或 `s3`
 - `SUPACLOUD_LITE_S3_PREFIX`：S3 对象 key 前缀，可被 `--s3-prefix` 覆盖
+- `SUPACLOUD_LITE_POSTGRES_MIRROR`：native 引擎下载 PostgreSQL 发布包时使用的 HTTPS 镜像前缀，例如 `https://ghproxy.net/`
 - `SUPACLOUD_LITE_JWT_SECRET`
 - `SUPACLOUD_LITE_VAULT_KEY`
 
+native 引擎首次运行会下载约 12 MB 的 Theseus PostgreSQL 发布包并缓存在 `~/.cache/supacloud-lite`。网络无法直连 GitHub 时，可设置镜像前缀；Lite 会把完整上游 URL 追加到该前缀，并在解压执行前继续校验固定或上游发布的 SHA-256。镜像不能包含 URL 凭据、query 或 fragment；除 loopback 测试地址外必须使用 HTTPS。
+
+```bash
+SUPACLOUD_LITE_POSTGRES_MIRROR=https://ghproxy.net/ supacloud-lite migrate --engine native
+```
+
 使用远端 S3 时，启动前设置 `SUPACLOUD_LITE_STORAGE_BACKEND=s3`，并按 Bun S3 约定提供 `S3_BUCKET`、`S3_ACCESS_KEY_ID`、`S3_SECRET_ACCESS_KEY`、`S3_ENDPOINT`、`S3_REGION` 等变量；也支持对应的 `AWS_*` 变量。CLI 不接受密钥参数，避免凭据出现在进程列表中。
 
 S3 模式下 `db reset` 会被拒绝，因为 Lite 不能把数据库元数据清理与远端对象删除做成原子操作；需要先明确处理远端 bucket/prefix，再切回本地或内存存储执行重置。
@@ -243,7 +250,7 @@ S3 模式的快照只包含数据库中的 Storage 元数据和密钥，不复
 | `supabase.storage` | 已验证核心 | 覆盖上传下载、列表、删除、TUS/RLS、远端 S3 驱动，以及 Bun.Image 的 `contain`/`fill`、格式和质量变换子集；`cover` 明确不支持 |
 | `supabase.channel()` | 已验证核心 | 自动测试覆盖 `postgres_changes`、DELETE RLS 隔离和事件快照校验；Broadcast、Presence 属于实验性兼容 |
 | `supabase.functions.invoke()` | 已验证核心 | 自动测试覆盖 Bun.build、`Deno.serve()`、公开函数和同进程重启 |
-| Supabase Queues / PGMQ | 已验证核心 | 提供 `pgmq_public` 的 `send`、`send_batch`、`read`、`pop`、`archive`、`delete` RPC；队列数据持久化在同一 PGlite 项目中 |
+| Supabase Queues / PGMQ | 已验证核心 | 提供 `pgmq_public` 的 `send`、`send_batch`、`read`、`pop`、`archive`、`delete` RPC；队列数据持久化在项目数据库（PGlite 或 native PostgreSQL）中 |
 | Edge Functions `SupaCloud.pgredis` | 已验证核心 | 提供单项目持久 KV、TTL、原子 `getset`/`getdel`；绑定只在当前函数请求内可用 |
 | Supabase migrations | 支持 | 按文件名排序，记录到 `supabase_migrations` |
 | PostgreSQL RLS | 支持 | 使用 `anon`、`authenticated`、`service_role` 数据库角色执行 |
@@ -267,7 +274,7 @@ Lite 使用 Bun 原生 bcrypt，并兼容验证常见 GoTrue bcrypt 密码散列
 
 ### 队列与 Edge 缓存
 
-Lite 在同一个 PGlite 数据库中提供 Supabase Queues 的公开 RPC façade。应用可以直接使用官方客户端的
+Lite 在项目数据库（PGlite 或 native PostgreSQL）中提供 Supabase Queues 的公开 RPC façade。应用可以直接使用官方客户端的
 `supabase.schema('pgmq_public').rpc(...)`，无需额外的队列进程：
 
 ```sql
@@ -291,6 +298,7 @@ const { data: messages } = await queues.rpc('read', {
 
 Lite 的 `pgmq` 模拟层还提供 `set_vt`，支持直接 SQL 调整可见性超时。消息按 PGMQ 语义至少投递一次；`pop` 会立即删除消息，`archive` 是确认路径。队列创建、指标、purge、设置和管理 API 不属于 Lite 的公开 RPC façade，仍需由项目 SQL 或完整 SupaCloud 控制面处理。
 队列名遵循标准版的 1-128 位小写字母、数字、下划线和短横线规则，并且必须以字母或数字开头；Lite 会安全映射超出 PostgreSQL 63-byte 标识符上限的名称，避免截断后串队。默认 Data API 暴露 `public` 和 `pgmq_public`；如果显式设置 `dbSchemas`，Lite 会严格使用该列表，需要队列 RPC 时应把 `pgmq_public` 明确加入。
+Durable workflow 的 run、step、event 和内部队列也保存在同一项目数据库中，可跨进程重启恢复；内部 workflow 队列不会通过 `pgmq_public` 暴露给 Data API 角色。
 
 Edge Function 内可使用 `globalThis.SupaCloud.pgredis`：
 
@@ -469,9 +477,16 @@ Environment variables:
 - `SUPACLOUD_LITE_STORAGE_DIR`
 - `SUPACLOUD_LITE_STORAGE_BACKEND`: `fs` (default), `memory`, or `s3`
 - `SUPACLOUD_LITE_S3_PREFIX`: S3 object key prefix, can be overridden by `--s3-prefix`
+- `SUPACLOUD_LITE_POSTGRES_MIRROR`: HTTPS prefix used to proxy native-engine PostgreSQL release downloads, for example `https://ghproxy.net/`
 - `SUPACLOUD_LITE_JWT_SECRET`
 - `SUPACLOUD_LITE_VAULT_KEY`
 
+On its first run, the native engine downloads an approximately 12 MB Theseus PostgreSQL release into `~/.cache/supacloud-lite`. If GitHub is not directly reachable, set a mirror prefix; Lite appends the complete upstream URL and still verifies the pinned or published SHA-256 before extracting or executing the archive. The mirror must not contain URL credentials, a query, or a fragment, and must use HTTPS except for loopback test endpoints.
+
+```bash
+SUPACLOUD_LITE_POSTGRES_MIRROR=https://ghproxy.net/ supacloud-lite migrate --engine native
+```
+
 When using remote S3, set `SUPACLOUD_LITE_STORAGE_BACKEND=s3` before starting, and provide variables such as `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, and `S3_REGION` according to Bun S3 conventions; the corresponding `AWS_*` variables are also supported. The CLI does not accept secret parameters to avoid credentials appearing in the process list.
 
 In S3 mode, `db reset` is rejected because Lite cannot make database metadata cleanup and remote object deletion an atomic operation; you must explicitly handle the remote bucket/prefix first, then switch back to local or memory storage to perform the reset.
@@ -577,7 +592,7 @@ In-memory databases have no persistable data, so `snapshot` and `upgrade` reject
 | `supabase.storage` | Verified core | Covers upload/download, list, delete, TUS/RLS, remote S3 driver, and a subset of Bun.Image `contain`/`fill`, format, and quality transforms; `cover` is explicitly unsupported |
 | `supabase.channel()` | Verified core | Automated tests cover `postgres_changes`, DELETE RLS isolation, and event snapshot validation; Broadcast and Presence are experimentally compatible |
 | `supabase.functions.invoke()` | Verified core | Automated tests cover Bun.build, `Deno.serve()`, public functions, and in-process restart |
-| Supabase Queues / PGMQ | Verified core | Provides `send`, `send_batch`, `read`, `pop`, `archive`, and `delete` RPCs for `pgmq_public`; queue data is persisted in the same PGlite project |
+| Supabase Queues / PGMQ | Verified core | Provides `send`, `send_batch`, `read`, `pop`, `archive`, and `delete` RPCs for `pgmq_public`; queue data is persisted in the project database (PGlite or native PostgreSQL) |
 | Edge Functions `SupaCloud.pgredis` | Verified core | Provides single-project persistent KV, TTL, and atomic `getset`/`getdel`; the binding is only available within the current function request |
 | Supabase migrations | Supported | Sorted by filename, recorded in `supabase_migrations` |
 | PostgreSQL RLS | Supported | Executed using the `anon`, `authenticated`, and `service_role` database roles |
@@ -601,7 +616,7 @@ Lite uses Bun's native bcrypt and is compatible with validating common GoTrue bc
 
 ### Queues and Edge Cache
 
-Lite provides a public RPC façade for Supabase Queues within the same PGlite database. Applications can directly use the official client's
+Lite provides a public RPC façade for Supabase Queues in the project database (PGlite or native PostgreSQL). Applications can directly use the official client's
 `supabase.schema('pgmq_public').rpc(...)` without an additional queue process:
 
 ```sql
@@ -625,6 +640,7 @@ const { data: messages } = await queues.rpc('read', {
 
 Lite's `pgmq` emulation layer also provides `set_vt`, allowing direct SQL adjustment of visibility timeouts. Messages are delivered at least once according to PGMQ semantics; `pop` deletes the message immediately, and `archive` is the acknowledgment path. Queue creation, metrics, purge, settings, and management APIs are not part of Lite's public RPC façade and must still be handled by project SQL or the full SupaCloud control plane.
 Queue names follow the standard 1-128 character lowercase letter, digit, underscore, and hyphen rule, and must start with a letter or digit; Lite safely maps names that exceed PostgreSQL's 63-byte identifier limit to avoid cross-queue collisions after truncation. The default Data API exposes `public` and `pgmq_public`; if `dbSchemas` is set explicitly, Lite uses that list strictly, and `pgmq_public` should be explicitly included when queue RPCs are needed.
+Durable workflow runs, steps, events, and the internal queue are stored in the same project database and survive process restarts. Data API roles cannot access the internal workflow queue through `pgmq_public`.
 
 Within an Edge Function, you can use `globalThis.SupaCloud.pgredis`:
 

package/dist/cli.js

@@ -8,7 +8,7 @@ import { dirname as dirname7, join as join10, resolve as resolve4 } from "path";
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.8.1",
+  version: "0.8.3",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
@@ -45,7 +45,7 @@ var package_default = {
     dev: "bun run src/cli.ts start",
     start: "bun run src/cli.ts start",
     test: "bun test --timeout 20000",
-    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts --timeout 180000",
+    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts test/qauth-workflow-matrix.test.ts --timeout 180000",
     parity: "bun run parity/harness.ts",
     "parity:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun run parity/harness.ts --engine native",
     "check:native": "bun run test:native && bun run parity:native",
@@ -10256,7 +10256,7 @@ import { tmpdir as tmpdir2 } from "os";
 import { dirname as dirname2, join as join2 } from "path";
 
 // src/runtime/node/native/engine.ts
-import { execFileSync, spawn } from "child_process";
+import { execFileSync, spawn, spawnSync } from "child_process";
 import { createHash as createHash2, randomBytes as randomBytes2 } from "crypto";
 import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "fs";
 import { writeFile } from "fs/promises";
@@ -10796,17 +10796,47 @@ function toPgArrayLiteral(array) {
 
 // src/runtime/node/native/engine.ts
 var DEFAULT_PG_VERSION = "17.7.0";
+var POSTGRES_MIRROR_URL_ERROR = "SUPACLOUD_LITE_POSTGRES_MIRROR must be an absolute HTTPS URL or a loopback HTTP URL";
 var NATIVE_POSTGRES_MAJOR = DEFAULT_PG_VERSION.split(".")[0];
+var GLIBC_DYNAMIC_LOADERS = {
+  x64: [
+    "/lib64/ld-linux-x86-64.so.2",
+    "/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2"
+  ],
+  arm64: [
+    "/lib/ld-linux-aarch64.so.1",
+    "/lib64/ld-linux-aarch64.so.1",
+    "/lib/aarch64-linux-gnu/ld-linux-aarch64.so.1"
+  ]
+};
 function isNativeEngineSupported() {
   return (process.platform === "darwin" || process.platform === "linux") && (process.arch === "arm64" || process.arch === "x64") && (process.platform !== "linux" || isGlibcLinux());
 }
 function isGlibcLinux() {
-  try {
-    const version = execFileSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-    return /glibc|gnu libc/i.test(version);
-  } catch {
-    return false;
-  }
+  const runtimeEvidence = {
+    runtimeVersion: reportedGlibcVersion(),
+    dynamicLoaderPresent: glibcDynamicLoaderPresent()
+  };
+  return isGlibcRuntime(runtimeEvidence) || isGlibcRuntime({ ...runtimeEvidence, lddVersion: lddVersion() });
+}
+function isGlibcRuntime(evidence) {
+  return Boolean(evidence.runtimeVersion?.trim()) || evidence.dynamicLoaderPresent || /glibc|gnu libc/i.test(evidence.lddVersion ?? "");
+}
+function reportedGlibcVersion() {
+  const report = process.report?.getReport();
+  const runtimeVersion = report?.header?.glibcVersionRuntime;
+  return typeof runtimeVersion === "string" ? runtimeVersion : undefined;
+}
+function glibcDynamicLoaderPresent() {
+  const loaderPaths = process.arch === "x64" ? GLIBC_DYNAMIC_LOADERS.x64 : process.arch === "arm64" ? GLIBC_DYNAMIC_LOADERS.arm64 : [];
+  return loaderPaths.some((loaderPath) => existsSync(loaderPath));
+}
+function lddVersion() {
+  const command = spawnSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (command.error || command.status !== 0)
+    return;
+  return `${command.stdout}
+${command.stderr}`.trim();
 }
 function target() {
   const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x86_64" : null;
@@ -10827,7 +10857,7 @@ var PINNED_SHA256 = {
   "postgresql-17.7.0-x86_64-apple-darwin": "0dd8c25173524bad4ae8ef6b970da1ac40f4c1f231150c416ccb8cd06feff8f2",
   "postgresql-17.7.0-aarch64-apple-darwin": "727ac08d20a704014a0d51eb3300aa0c8e292c1cf0a1c99d4f4b1002e1420220"
 };
-async function verifyTarball(tarball, key, url) {
+async function verifyTarball(tarball, key, upstreamUrl, downloadMirror) {
   const actual = createHash2("sha256").update(readFileSync(tarball)).digest("hex");
   const pinned = PINNED_SHA256[key];
   if (pinned) {
@@ -10836,7 +10866,8 @@ async function verifyTarball(tarball, key, url) {
     }
     return;
   }
-  const res = await fetchRelease(`${url}.sha256`);
+  const checksumUrl = resolvePostgresDownloadUrl(`${upstreamUrl}.sha256`, downloadMirror);
+  const res = await fetchRelease(checksumUrl);
   if (!res.ok)
     throw new Error(`could not fetch checksum for ${key}: HTTP ${res.status}`);
   const expected = (await res.text()).trim().split(/\s+/)[0].toLowerCase();
@@ -10846,13 +10877,14 @@ async function verifyTarball(tarball, key, url) {
     throw new Error(`postgres binary checksum mismatch for ${key}: expected ${expected}, got ${actual}`);
   }
 }
-async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
+async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log, downloadMirror) {
   const t = target();
   const root = cacheDir ?? join(homedir(), ".cache", "supacloud-lite");
   const dir = join(root, `postgresql-${version}-${t}`);
   if (isCompleteInstall(dir))
     return dir;
-  const url = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const upstreamUrl = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const url = resolvePostgresDownloadUrl(upstreamUrl, downloadMirror);
   mkdirSync(root, { recursive: true });
   const uniq = `${process.pid}-${randomBytes2(6).toString("hex")}`;
   const tarball = join(root, `pg-${version}-${uniq}.tar.gz`);
@@ -10865,7 +10897,7 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     if (!res.ok)
       throw new Error(`failed to download ${url}: HTTP ${res.status}`);
     await writeFile(tarball, Buffer.from(await res.arrayBuffer()));
-    await verifyTarball(tarball, `postgresql-${version}-${t}`, url);
+    await verifyTarball(tarball, `postgresql-${version}-${t}`, upstreamUrl, downloadMirror);
     mkdirSync(tmpDir, { recursive: true });
     await extractTar({ cwd: tmpDir, file: tarball, gzip: true, preserveOwner: false, strict: true, strip: 1 });
     if (!isCompleteInstall(tmpDir))
@@ -10885,6 +10917,32 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     rmSync(tmpDir, { recursive: true, force: true });
   }
 }
+function resolvePostgresDownloadUrl(upstreamUrl, downloadMirror) {
+  const mirror = postgresDownloadMirror(downloadMirror);
+  return mirror ? `${mirror.toString().replace(/\/+$/, "")}/${upstreamUrl}` : upstreamUrl;
+}
+function postgresDownloadMirror(downloadMirror) {
+  const configuredMirror = downloadMirror ?? process.env.SUPACLOUD_LITE_POSTGRES_MIRROR;
+  const mirrorText = configuredMirror?.trim();
+  if (!mirrorText)
+    return;
+  let mirror;
+  try {
+    mirror = new URL(mirrorText);
+  } catch {
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  }
+  const loopbackHttp = mirror.protocol === "http:" && (mirror.hostname === "127.0.0.1" || mirror.hostname === "localhost" || mirror.hostname === "[::1]");
+  if (mirror.protocol !== "https:" && !loopbackHttp)
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  if (mirror.username || mirror.password) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain credentials");
+  }
+  if (mirrorText.includes("?") || mirrorText.includes("#")) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain a query or fragment");
+  }
+  return mirror;
+}
 async function fetchRelease(url) {
   let lastError;
   for (let attempt = 1;attempt <= 3; attempt++) {
@@ -10917,7 +10975,7 @@ async function createNativeEngine(opts) {
   let postgres;
   let removeExitHandler;
   try {
-    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log);
+    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log, opts.downloadMirror);
     const bin = (name) => join(installDir, "bin", name);
     if (!existsSync(join(opts.dataDir, "PG_VERSION"))) {
       mkdirSync(opts.dataDir, { recursive: true });

package/dist/index.js

@@ -85,7 +85,7 @@ function randomToken(bytes = 32) {
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.8.1",
+  version: "0.8.3",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
@@ -122,7 +122,7 @@ var package_default = {
     dev: "bun run src/cli.ts start",
     start: "bun run src/cli.ts start",
     test: "bun test --timeout 20000",
-    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts --timeout 180000",
+    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts test/qauth-workflow-matrix.test.ts --timeout 180000",
     parity: "bun run parity/harness.ts",
     "parity:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun run parity/harness.ts --engine native",
     "check:native": "bun run test:native && bun run parity:native",
@@ -10269,7 +10269,7 @@ async function serveBun(backend, opts = {}) {
   };
 }
 // src/runtime/node/native/engine.ts
-import { execFileSync, spawn } from "child_process";
+import { execFileSync, spawn, spawnSync } from "child_process";
 import { createHash as createHash2, randomBytes as randomBytes2 } from "crypto";
 import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "fs";
 import { writeFile as writeFile2 } from "fs/promises";
@@ -10809,17 +10809,47 @@ function toPgArrayLiteral(array) {
 
 // src/runtime/node/native/engine.ts
 var DEFAULT_PG_VERSION = "17.7.0";
+var POSTGRES_MIRROR_URL_ERROR = "SUPACLOUD_LITE_POSTGRES_MIRROR must be an absolute HTTPS URL or a loopback HTTP URL";
 var NATIVE_POSTGRES_MAJOR = DEFAULT_PG_VERSION.split(".")[0];
+var GLIBC_DYNAMIC_LOADERS = {
+  x64: [
+    "/lib64/ld-linux-x86-64.so.2",
+    "/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2"
+  ],
+  arm64: [
+    "/lib/ld-linux-aarch64.so.1",
+    "/lib64/ld-linux-aarch64.so.1",
+    "/lib/aarch64-linux-gnu/ld-linux-aarch64.so.1"
+  ]
+};
 function isNativeEngineSupported() {
   return (process.platform === "darwin" || process.platform === "linux") && (process.arch === "arm64" || process.arch === "x64") && (process.platform !== "linux" || isGlibcLinux());
 }
 function isGlibcLinux() {
-  try {
-    const version = execFileSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-    return /glibc|gnu libc/i.test(version);
-  } catch {
-    return false;
-  }
+  const runtimeEvidence = {
+    runtimeVersion: reportedGlibcVersion(),
+    dynamicLoaderPresent: glibcDynamicLoaderPresent()
+  };
+  return isGlibcRuntime(runtimeEvidence) || isGlibcRuntime({ ...runtimeEvidence, lddVersion: lddVersion() });
+}
+function isGlibcRuntime(evidence) {
+  return Boolean(evidence.runtimeVersion?.trim()) || evidence.dynamicLoaderPresent || /glibc|gnu libc/i.test(evidence.lddVersion ?? "");
+}
+function reportedGlibcVersion() {
+  const report = process.report?.getReport();
+  const runtimeVersion = report?.header?.glibcVersionRuntime;
+  return typeof runtimeVersion === "string" ? runtimeVersion : undefined;
+}
+function glibcDynamicLoaderPresent() {
+  const loaderPaths = process.arch === "x64" ? GLIBC_DYNAMIC_LOADERS.x64 : process.arch === "arm64" ? GLIBC_DYNAMIC_LOADERS.arm64 : [];
+  return loaderPaths.some((loaderPath) => existsSync(loaderPath));
+}
+function lddVersion() {
+  const command = spawnSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (command.error || command.status !== 0)
+    return;
+  return `${command.stdout}
+${command.stderr}`.trim();
 }
 function target() {
   const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x86_64" : null;
@@ -10840,7 +10870,7 @@ var PINNED_SHA256 = {
   "postgresql-17.7.0-x86_64-apple-darwin": "0dd8c25173524bad4ae8ef6b970da1ac40f4c1f231150c416ccb8cd06feff8f2",
   "postgresql-17.7.0-aarch64-apple-darwin": "727ac08d20a704014a0d51eb3300aa0c8e292c1cf0a1c99d4f4b1002e1420220"
 };
-async function verifyTarball(tarball, key, url) {
+async function verifyTarball(tarball, key, upstreamUrl, downloadMirror) {
   const actual = createHash2("sha256").update(readFileSync(tarball)).digest("hex");
   const pinned = PINNED_SHA256[key];
   if (pinned) {
@@ -10849,7 +10879,8 @@ async function verifyTarball(tarball, key, url) {
     }
     return;
   }
-  const res = await fetchRelease(`${url}.sha256`);
+  const checksumUrl = resolvePostgresDownloadUrl(`${upstreamUrl}.sha256`, downloadMirror);
+  const res = await fetchRelease(checksumUrl);
   if (!res.ok)
     throw new Error(`could not fetch checksum for ${key}: HTTP ${res.status}`);
   const expected = (await res.text()).trim().split(/\s+/)[0].toLowerCase();
@@ -10859,13 +10890,14 @@ async function verifyTarball(tarball, key, url) {
     throw new Error(`postgres binary checksum mismatch for ${key}: expected ${expected}, got ${actual}`);
   }
 }
-async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
+async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log, downloadMirror) {
   const t = target();
   const root = cacheDir ?? join2(homedir(), ".cache", "supacloud-lite");
   const dir = join2(root, `postgresql-${version}-${t}`);
   if (isCompleteInstall(dir))
     return dir;
-  const url = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const upstreamUrl = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const url = resolvePostgresDownloadUrl(upstreamUrl, downloadMirror);
   mkdirSync(root, { recursive: true });
   const uniq = `${process.pid}-${randomBytes2(6).toString("hex")}`;
   const tarball = join2(root, `pg-${version}-${uniq}.tar.gz`);
@@ -10878,7 +10910,7 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     if (!res.ok)
       throw new Error(`failed to download ${url}: HTTP ${res.status}`);
     await writeFile2(tarball, Buffer.from(await res.arrayBuffer()));
-    await verifyTarball(tarball, `postgresql-${version}-${t}`, url);
+    await verifyTarball(tarball, `postgresql-${version}-${t}`, upstreamUrl, downloadMirror);
     mkdirSync(tmpDir, { recursive: true });
     await extractTar({ cwd: tmpDir, file: tarball, gzip: true, preserveOwner: false, strict: true, strip: 1 });
     if (!isCompleteInstall(tmpDir))
@@ -10898,6 +10930,32 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     rmSync(tmpDir, { recursive: true, force: true });
   }
 }
+function resolvePostgresDownloadUrl(upstreamUrl, downloadMirror) {
+  const mirror = postgresDownloadMirror(downloadMirror);
+  return mirror ? `${mirror.toString().replace(/\/+$/, "")}/${upstreamUrl}` : upstreamUrl;
+}
+function postgresDownloadMirror(downloadMirror) {
+  const configuredMirror = downloadMirror ?? process.env.SUPACLOUD_LITE_POSTGRES_MIRROR;
+  const mirrorText = configuredMirror?.trim();
+  if (!mirrorText)
+    return;
+  let mirror;
+  try {
+    mirror = new URL(mirrorText);
+  } catch {
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  }
+  const loopbackHttp = mirror.protocol === "http:" && (mirror.hostname === "127.0.0.1" || mirror.hostname === "localhost" || mirror.hostname === "[::1]");
+  if (mirror.protocol !== "https:" && !loopbackHttp)
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  if (mirror.username || mirror.password) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain credentials");
+  }
+  if (mirrorText.includes("?") || mirrorText.includes("#")) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain a query or fragment");
+  }
+  return mirror;
+}
 async function fetchRelease(url) {
   let lastError;
   for (let attempt = 1;attempt <= 3; attempt++) {
@@ -10930,7 +10988,7 @@ async function createNativeEngine(opts) {
   let postgres;
   let removeExitHandler;
   try {
-    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log);
+    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log, opts.downloadMirror);
     const bin = (name) => join2(installDir, "bin", name);
     if (!existsSync(join2(opts.dataDir, "PG_VERSION"))) {
       mkdirSync(opts.dataDir, { recursive: true });

package/dist/runtime/node/native/engine.d.ts

@@ -1,5 +1,10 @@
 import type { DbEngine } from '../../db/engine.js';
 export declare const NATIVE_POSTGRES_MAJOR: string;
+export interface GlibcRuntimeEvidence {
+    runtimeVersion?: string;
+    dynamicLoaderPresent: boolean;
+    lddVersion?: string;
+}
 /** Options for {@link createNativeEngine}. */
 export interface NativeEngineOptions {
     /** Postgres data directory (created + initdb'd if missing). */
@@ -10,10 +15,18 @@ export interface NativeEngineOptions {
     cacheDir?: string;
     /** sink for progress lines (download, install); no-op when omitted */
     log?: (msg: string) => void;
+    /** Optional HTTPS or loopback HTTP prefix for proxying the PostgreSQL release download. */
+    downloadMirror?: string;
 }
 export declare function isNativeEngineSupported(): boolean;
+export declare function isGlibcRuntime(evidence: GlibcRuntimeEvidence): boolean;
 /** Download + unpack Postgres binaries if not already cached (concurrency-safe). Returns the install dir. */
-export declare function ensurePostgres(version?: string, cacheDir?: string, log?: (m: string) => void): Promise<string>;
+export declare function ensurePostgres(version?: string, cacheDir?: string, log?: (m: string) => void, downloadMirror?: string): Promise<string>;
+/**
+ * Prefix a trusted GitHub release URL with an operator-selected mirror. The
+ * archive is still checked against the pinned or published SHA-256 before use.
+ */
+export declare function resolvePostgresDownloadUrl(upstreamUrl: string, downloadMirror?: string): string;
 /**
  * Boot the embedded Postgres child (initdb on first run) and return a {@link DbEngine}
  * backed by two wire connections: one for queries/transactions (serialized by a mutex),

package/dist/runtime/node/native/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/runtime/node/native/engine.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAKlD,eAAO,MAAM,qBAAqB,QAAoC,CAAA;AAEtE,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5B;AAED,wBAAgB,uBAAuB,IAAI,OAAO,CAIjD;AA4DD,6GAA6G;AAC7G,wBAAsB,cAAc,CAAC,OAAO,SAAqB,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ChI;AA4BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiFrF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/runtime/node/native/engine.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAOlD,eAAO,MAAM,qBAAqB,QAAoC,CAAA;AActE,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,uBAAuB,IAAI,OAAO,CAIjD;AAUD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAItE;AAuED,6GAA6G;AAC7G,wBAAsB,cAAc,CAClC,OAAO,SAAqB,EAC5B,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,CAAC,CA4CjB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/F;AAkDD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiFrF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/lite",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   "type": "module",
   "license": "Apache-2.0",
@@ -37,7 +37,7 @@
     "dev": "bun run src/cli.ts start",
     "start": "bun run src/cli.ts start",
     "test": "bun test --timeout 20000",
-    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts --timeout 180000",
+    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts test/qauth-workflow-matrix.test.ts --timeout 180000",
     "parity": "bun run parity/harness.ts",
     "parity:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun run parity/harness.ts --engine native",
     "check:native": "bun run test:native && bun run parity:native",