@specific.dev/spectest 0.37.0 → 0.38.0

package/dist/browser.js

@@ -110,11 +110,13 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // comes from the HOME-scoped NSS user DB, so neither cares that playwright
 // runs a temp --user-data-dir.
 let PW_BROWSER = null;
-// The shared desktop context (default 1280×720 viewport). All desktop views
-// live here so they share one cookie jar, mirroring the old one-Chrome-
-// profile model. Mobile sessions and custom-viewport views get their own
-// contexts (viewport/DPR/UA/touch are context-scoped in playwright).
-let DESKTOP_CTX = null;
+// Every view gets its OWN context, desktop included. A context is the cookie
+// jar + storage, so one-context-per-view is what makes `close()` mean what
+// the docs promise: the browsing session is destroyed and the next
+// `ctx.browser()` starts signed out. Desktop views used to share one context
+// (mirroring the old one-Chrome-profile model), which left `close()` closing
+// the page only — cookies survived and the next session was still
+// authenticated.
 function chromiumPath() {
     return (Bun.which("chromium") ??
         Bun.which("chromium-browser") ??
@@ -129,7 +131,6 @@ async function ensurePlaywrightBrowser() {
         headless: true,
         args: CHROME_ARGV,
     });
-    DESKTOP_CTX = null; // contexts died with the old browser (if any)
     return PW_BROWSER;
 }
 /** Context options for the mobile device preset — playwright's native
@@ -150,18 +151,20 @@ function deviceContextOptions(d) {
         reducedMotion: "reduce",
     };
 }
-async function ensureDesktopContext() {
+/** Create the context one view lives in — device emulation when the view is
+ *  phone-emulated, a plain viewport otherwise. */
+async function newViewContext(width, height, device) {
     const browser = await ensurePlaywrightBrowser();
-    if (DESKTOP_CTX)
-        return DESKTOP_CTX;
-    DESKTOP_CTX = await browser.newContext({
-        viewport: { width: 1280, height: 720 },
-        // Reduced-motion for replay fidelity — see deviceContextOptions.
-        reducedMotion: "reduce",
-    });
-    DESKTOP_CTX.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-    DESKTOP_CTX.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-    return DESKTOP_CTX;
+    const context = await browser.newContext(device
+        ? deviceContextOptions(device)
+        : {
+            viewport: { width, height },
+            // Reduced-motion for replay fidelity — see deviceContextOptions.
+            reducedMotion: "reduce",
+        });
+    context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+    context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+    return context;
 }
 /**
  * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
@@ -791,32 +794,10 @@ async function spawnPage(context) {
     }
     return { page, cdp, recordingInstalled };
 }
-/** Acquire the context a view of this shape lives in. */
-async function contextFor(width, height, device) {
-    if (device) {
-        const browser = await ensurePlaywrightBrowser();
-        const context = await browser.newContext(deviceContextOptions(device));
-        context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-        context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-        return { context, ownsContext: true };
-    }
-    if (width === 1280 && height === 720) {
-        return { context: await ensureDesktopContext(), ownsContext: false };
-    }
-    const browser = await ensurePlaywrightBrowser();
-    const context = await browser.newContext({
-        viewport: { width, height },
-        // Reduced-motion for replay fidelity — see deviceContextOptions.
-        reducedMotion: "reduce",
-    });
-    context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-    context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-    return { context, ownsContext: true };
-}
-/** Create a default-desktop view for the pool. */
+/** Create a default-desktop view (plus its context) for the pool. */
 async function createView(width, height) {
-    const { context } = await contextFor(width, height, null);
-    return spawnPage(context);
+    const context = await newViewContext(width, height, null);
+    return { context, ...(await spawnPage(context)) };
 }
 /**
  * Pre-open `n` views into the pool (called by the daemon at the end of
@@ -860,8 +841,7 @@ export async function openMobileBackend(opts = {}) {
     let holder;
     if (pooled) {
         holder = {
-            context: await ensureDesktopContext(),
-            ownsContext: false,
+            context: pooled.context,
             page: pooled.page,
             cdp: pooled.cdp,
             lastTitle: "",
@@ -903,11 +883,10 @@ export async function openMobileBackend(opts = {}) {
 let SHARED_BROWSER = null;
 const SHARED_MOBILE = new Map();
 async function newHolder(width, height, device) {
-    const { context, ownsContext } = await contextFor(width, height, device);
+    const context = await newViewContext(width, height, device);
     const spawned = await spawnPage(context);
     const holder = {
         context,
-        ownsContext,
         page: spawned.page,
         cdp: spawned.cdp,
         lastTitle: "",
@@ -1406,13 +1385,13 @@ function buildBackend(holder, recorder, buildOpts) {
             catch {
                 /* already closed by the runtime */
             }
-            if (holder.ownsContext) {
-                try {
-                    await holder.context.close();
-                }
-                catch {
-                    /* context already gone (browser died) */
-                }
+            // The context, not the page, holds the cookies and storage — closing
+            // only the page would leave the next session signed in as this one.
+            try {
+                await holder.context.close();
+            }
+            catch {
+                /* context already gone (browser died) */
             }
         },
         // ── Mobile-only primitives ──────────────────────────────────────────

package/dist/daemon.js

@@ -62,6 +62,9 @@ function hostCacheGateway() {
     return _hostCacheGateway;
 }
 const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+// The bun the base snapshot installs (base.rs::BASE_SETUP_SH). The daemon
+// runs under it, and eval's dependency install shells out to it.
+const BUN_BIN = "/usr/local/bin/bun";
 // Root CA baked into the base snapshot at base-snapshot build time
 // (see base.rs::BASE_SETUP_SH). Bind-mounted into every service
 // container so apps can verify HTTPS to the daemon's fakes, and
@@ -550,6 +553,130 @@ async function ensureVolumes(svc) {
     }
     return flags;
 }
+/** Keyed by image ID, not tag: `spectest/<svc>:latest` is retagged onto
+ *  new content every rebuild, and a stale uid is silently wrong. */
+const IMAGE_ID_TABLES = new Map();
+let idProbeSeq = 0;
+/**
+ * Read an image's `/etc/passwd` and `/etc/group` so a `user`/`group` can
+ * be written as a name rather than the uid the image happens to use.
+ *
+ * Done with `docker create` + `docker cp` rather than running `id` in the
+ * image: nothing is ever started, so it works on an image with no shell
+ * (distroless) and costs no entrypoint. An image with no `/etc/passwd`
+ * (scratch) yields empty tables — only a name that isn't there fails,
+ * and a numeric id never gets this far.
+ */
+async function probeImageIdTables(tag) {
+    const users = new Map();
+    const groups = new Map();
+    const name = `spectest-idprobe-${idProbeSeq++}`;
+    const dir = path.join(WORKSPACE, ".spectest", "idprobe", name);
+    // Idempotent like runContainer: a leftover from a previous run would
+    // otherwise surface as a name conflict rather than the real problem.
+    await docker(["rm", "-f", name], 30_000);
+    // `--entrypoint` supplies the command `docker create` insists on for an
+    // image that declares neither ENTRYPOINT nor CMD. It is never executed.
+    const created = await docker(["create", "--name", name, "--entrypoint", "/spectest-idprobe", tag], 60_000);
+    if (created.code !== 0) {
+        throw new Error(`could not read the user/group tables of image ${tag}: ${created.stderr.trim()}`);
+    }
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        for (const [file, table] of [
+            ["passwd", users],
+            ["group", groups],
+        ]) {
+            const dst = path.join(dir, file);
+            const cp = await docker(["cp", `${name}:/etc/${file}`, dst], 60_000);
+            if (cp.code !== 0)
+                continue;
+            const text = await fs.readFile(dst, "utf8").catch(() => "");
+            for (const line of text.split("\n")) {
+                // name:x:id:… — field 2 is the uid in passwd, the gid in group.
+                const fields = line.split(":");
+                const id = Number(fields[2]);
+                if (fields[0] && fields.length >= 3 && Number.isInteger(id)) {
+                    table.set(fields[0], id);
+                }
+            }
+        }
+    }
+    finally {
+        await docker(["rm", "-f", name], 30_000);
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+    return { users, groups };
+}
+async function imageIdTables(tag) {
+    const insp = await docker(["image", "inspect", "--format", "{{.Id}}", tag], 30_000);
+    const key = insp.code === 0 && insp.stdout.trim() ? insp.stdout.trim() : tag;
+    let tables = IMAGE_ID_TABLES.get(key);
+    if (!tables) {
+        // Stored before the await so concurrent services on one image probe once.
+        tables = probeImageIdTables(tag);
+        IMAGE_ID_TABLES.set(key, tables);
+    }
+    return tables;
+}
+/**
+ * Resolve a declared `user`/`group` against `tag`. Numeric ids are taken
+ * as-is and never touch the image; names cost one probe per image.
+ * Returns `undefined` when neither is declared — the common case, which
+ * must stay free.
+ */
+async function resolveOwner(svc, tag, what, user, group) {
+    if (user === undefined && group === undefined)
+        return undefined;
+    const numeric = (v) => v !== undefined && /^[0-9]+$/.test(v) ? Number(v) : undefined;
+    let uid = numeric(user);
+    let gid = numeric(group);
+    const needsTables = (user !== undefined && uid === undefined) ||
+        (group !== undefined && gid === undefined);
+    if (needsTables) {
+        const tables = await imageIdTables(tag);
+        if (user !== undefined && uid === undefined) {
+            uid = tables.users.get(user);
+            if (uid === undefined) {
+                throw new Error(`service "${svc.name}": ${what} user ${JSON.stringify(user)} is not in the image's /etc/passwd — use a numeric uid`);
+            }
+        }
+        if (group !== undefined && gid === undefined) {
+            gid = tables.groups.get(group);
+            if (gid === undefined) {
+                throw new Error(`service "${svc.name}": ${what} group ${JSON.stringify(group)} is not in the image's /etc/group — use a numeric gid`);
+            }
+        }
+    }
+    // chown(2) reads -1 as "unchanged", so `user` alone keeps the group
+    // and vice versa — the same thing plain `chown` does.
+    return { uid: uid ?? -1, gid: gid ?? -1 };
+}
+/**
+ * Apply `mode` and `owner` to a staged file, before it is bind-mounted
+ * into a container that does not exist yet.
+ *
+ * The `-1` halves are resolved against the file's current owner rather
+ * than passed through: **Bun's `fs.chown` rejects `-1` with `EPERM`**
+ * (measured on Bun 1.3.14; node and chown(2) both read it as "leave this
+ * one alone"), so handing it straight to the syscall would break exactly
+ * the common cases — a `user` with no `group`, and the reverse.
+ */
+async function applyFileOwnership(file, mode, owner) {
+    if (mode)
+        await fs.chmod(file, parseInt(mode, 8));
+    if (!owner)
+        return;
+    let { uid, gid } = owner;
+    if (uid < 0 || gid < 0) {
+        const st = await fs.stat(file);
+        if (uid < 0)
+            uid = st.uid;
+        if (gid < 0)
+            gid = st.gid;
+    }
+    await fs.chown(file, uid, gid);
+}
 // Materialize `svc.files` onto the VM host and return `--volume` flags
 // bind-mounting each into the container (read-only). Single-file bind
 // mounts mean the seeded config lands in place *before the container's
@@ -557,7 +684,7 @@ async function ensureVolumes(svc) {
 // hook. Staging path mirrors ensureVolumes: a per-service dir derived
 // from the in-container path, so two files never collide and the
 // content is captured by snapshots like everything else under WORKSPACE.
-async function ensureFiles(svc) {
+async function ensureFiles(svc, tag) {
     const flags = [];
     if (!svc.files || svc.files.length === 0)
         return flags;
@@ -574,8 +701,12 @@ async function ensureFiles(svc) {
         const content = f.content.replaceAll("{{SPECTEST_SERVICE}}", svc.name);
         const host = path.join(dir, sanitizeSegment(f.path));
         await fs.writeFile(host, content);
-        if (f.mode)
-            await fs.chmod(host, parseInt(f.mode, 8));
+        // A bind mount carries this inode's mode and ownership into the
+        // container verbatim, and we write as root — so a `mode` that locks
+        // the file down needs `user`/`group` beside it to stay readable to
+        // whoever the container actually runs as.
+        const owner = await resolveOwner(svc, tag, `file ${f.path}`, f.user, f.group);
+        await applyFileOwnership(host, f.mode, owner);
         flags.push(`--volume=${host}:${f.path}:ro`);
     }
     return flags;
@@ -595,7 +726,7 @@ async function ensureFiles(svc) {
  * (~50 ms), and a stale one outliving a CA rotation would fail in a way
  * that reads as a code bug.
  */
-async function ensureCertificates(svc) {
+async function ensureCertificates(svc, tag) {
     const flags = [];
     const certs = svc.certificates ?? [];
     if (certs.length === 0)
@@ -624,11 +755,21 @@ async function ensureCertificates(svc) {
         const keyHost = path.join(dir, `${i}.key`);
         await fs.writeFile(certHost, cert);
         await fs.writeFile(keyHost, key);
-        // The key's mode has to be set on the staged file: a bind mount
-        // carries the host inode's permissions straight through, and a
-        // server that checks (postgres, ssh) refuses a lax one.
-        if (c.mode)
-            await fs.chmod(keyHost, parseInt(c.mode, 8));
+        // Mode AND ownership have to be set on the staged files: a bind
+        // mount carries the host inode's straight through, and the daemon
+        // writes as root. A server that checks (postgres, ssh) refuses a lax
+        // key, but a strict root-owned one it can't open is just as fatal —
+        // which is why `mode` alone used to force an entrypoint wrapper that
+        // re-installed the key as the right user.
+        const owner = await resolveOwner(svc, tag, `certificate ${i}`, c.user, c.group);
+        // Declaring who reads the key also says what mode it wants: the
+        // strictest one that owner can still open. Only reached when
+        // `user`/`group` is set, so no existing environment changes.
+        const keyMode = c.mode ?? (owner ? (owner.uid === -1 ? "0640" : "0600") : undefined);
+        await applyFileOwnership(keyHost, keyMode, owner);
+        // The certificate is public, but it follows the key's owner so a
+        // server that insists on owning its whole TLS directory is happy.
+        await applyFileOwnership(certHost, undefined, owner);
         flags.push(`--volume=${certHost}:${c.certPath}:ro`);
         flags.push(`--volume=${keyHost}:${c.keyPath}:ro`);
         if (c.caPath)
@@ -2313,8 +2454,8 @@ async function startRuntimeService(spec) {
         const { tag } = await prepareServiceImage(svc);
         const flags = [
             ...(await ensureVolumes(svc)),
-            ...(await ensureFiles(svc)),
-            ...(await ensureCertificates(svc)),
+            ...(await ensureFiles(svc, tag)),
+            ...(await ensureCertificates(svc, tag)),
         ];
         await runContainer(svc, tag, flags, aliases);
         await waitForReady(svc);
@@ -2618,14 +2759,16 @@ async function bootstrapInner() {
         // deps; this adds the image edge. The two compose: we run the moment
         // both are satisfied, with no whole-graph barrier between them.
         await prep.get(svc.name);
-        const flags = [
-            ...(await ensureVolumes(svc)),
-            ...(await ensureFiles(svc)),
-            ...(await ensureCertificates(svc)),
-        ];
+        // The tag is read before the mounts are staged: a `files`/
+        // `certificates` owner given by name is resolved against the image.
         const tag = tags.get(svc.name);
         if (!tag)
             throw new Error(`internal: no image tag for ${svc.name}`);
+        const flags = [
+            ...(await ensureVolumes(svc)),
+            ...(await ensureFiles(svc, tag)),
+            ...(await ensureCertificates(svc, tag)),
+        ];
         const tRun = Date.now();
         progressService(svc.name, { status: "starting", detail: undefined });
         await runContainer(svc, tag, flags);
@@ -4025,9 +4168,86 @@ function packageName(spec) {
     return spec.split("/")[0];
 }
 /**
- * Scan the snippet's imports and `bun add` anything that doesn't already
- * resolve. Skips relative paths, absolute paths, `node:`/`bun:` built-ins,
- * and HTTP(S)/file: URLs.
+ * Is this package installed? Read from the disk, and deliberately not with
+ * `Bun.resolveSync` — a resolve that misses is cached for the life of the
+ * process (see `ensureDeps`), so asking the resolver whether a package is
+ * missing is what makes it stay missing.
+ *
+ * Walks up from `APP_DIR` like a module resolver does, so a hoisted
+ * install in an ancestor `node_modules` counts.
+ */
+async function packageInstalled(pkg) {
+    let dir = APP_DIR;
+    for (;;) {
+        if (await fs.exists(path.join(dir, "node_modules", pkg, "package.json")))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+/**
+ * Resolve `spec` in a throwaway `bun` process, which starts with an empty
+ * resolver cache. Returns null if it still does not resolve — the snippet's
+ * own import then reports the real error.
+ */
+async function resolveInNewProcess(spec) {
+    const probe = `process.stdout.write(Bun.resolveSync(${JSON.stringify(spec)}, ${JSON.stringify(APP_DIR)}))`;
+    const proc = Bun.spawn([BUN_BIN, "-e", probe], {
+        cwd: APP_DIR,
+        stdout: "pipe",
+        stderr: "ignore",
+    });
+    const out = (await new Response(proc.stdout).text()).trim();
+    const code = await proc.exited;
+    if (code !== 0 || out.length === 0)
+        return null;
+    return out;
+}
+/**
+ * Replace one import specifier in the snippet — in import positions only
+ * (`from "x"`, `import "x"`, `import("x")`, `require("x")`), so a plain
+ * string that is equal to the specifier stays as it is.
+ */
+function rewriteSpecifier(code, spec, target) {
+    const escaped = spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`((?:\\bfrom|\\bimport|\\brequire)\\s*\\(?\\s*)(["'])${escaped}\\2`, "g");
+    // A callback, not a replacement string: an absolute path can contain `$`.
+    return code.replace(pattern, (_match, lead, quote) => `${lead}${quote}${target}${quote}`);
+}
+/** Point each given specifier at the module's absolute path. A specifier
+ *  that still does not resolve is left as it is, so the snippet's own
+ *  import reports the real error. */
+async function rewriteUnreachable(code, specs) {
+    let patched = code;
+    for (const spec of specs) {
+        const target = await resolveInNewProcess(spec);
+        if (target)
+            patched = rewriteSpecifier(patched, spec, target);
+    }
+    return patched;
+}
+/**
+ * Scan the snippet's imports and `bun add` anything that isn't installed.
+ * Skips relative paths, absolute paths, `node:`/`bun:` built-ins, and
+ * HTTP(S)/file: URLs. Returns the snippet to actually run, plus the packages
+ * it installed.
+ *
+ * A specifier the bare import cannot reach is **rewritten to the absolute
+ * path of the module**, because Bun caches a failed resolution for the life
+ * of the process and the daemon is long-lived: an eval that imports
+ * `otpauth` before it is installed makes every later
+ * `import * as OTPAuth from "otpauth"` keep failing with `Cannot find
+ * package 'otpauth'` — even after the install put it on the disk. Nothing
+ * clears that entry: not a later `Bun.resolveSync`, not an `onResolve`
+ * plugin, not a new directory to import from (all measured on Bun 1.3.14,
+ * where node 24 re-resolves and succeeds). The cache keeps hits the same
+ * way — a package removed mid-process still resolves — so treat resolution
+ * in this process as a snapshot taken at first ask.
+ * An absolute path never consults the cache. The path comes from a new
+ * `bun` process, so the package's own `exports` conditions apply exactly as
+ * they would for the bare specifier.
  */
 async function ensureDeps(code) {
     let scanned;
@@ -4036,9 +4256,13 @@ async function ensureDeps(code) {
     }
     catch {
         // Invalid syntax — let the import call surface the real error.
-        return [];
+        return { code, installed: [] };
     }
     const seen = new Set();
+    // Specifiers the bare import cannot reach, and the packages to install for
+    // them. A subpath (`otpauth/dist/…`) resolves to its own file, so these are
+    // deduped per specifier, not per package.
+    const unreachable = [];
     const missing = [];
     for (const imp of scanned) {
         const p = imp.path;
@@ -4051,21 +4275,32 @@ async function ensureDeps(code) {
             p.startsWith("file:")) {
             continue;
         }
+        if (seen.has(p))
+            continue;
+        seen.add(p);
         const pkg = packageName(p);
-        if (seen.has(pkg))
+        if (!(await packageInstalled(pkg))) {
+            unreachable.push(p);
+            if (!missing.includes(pkg))
+                missing.push(pkg);
             continue;
-        seen.add(pkg);
+        }
+        // Installed — but a poisoned cache entry from an earlier eval can still
+        // fail the import, so ask the resolver. This can only cache a hit.
         try {
             Bun.resolveSync(p, APP_DIR);
         }
         catch {
-            missing.push(pkg);
+            unreachable.push(p);
         }
     }
-    if (missing.length === 0)
-        return [];
+    if (unreachable.length === 0)
+        return { code, installed: [] };
+    if (missing.length === 0) {
+        return { code: await rewriteUnreachable(code, unreachable), installed: [] };
+    }
     await new Promise((resolve, reject) => {
-        execFile("/usr/local/bin/bun", ["add", ...missing], { cwd: APP_DIR, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        execFile(BUN_BIN, ["add", ...missing], { cwd: APP_DIR, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
             if (err) {
                 reject(new Error(`bun add ${missing.join(" ")} failed:\n${String(stderr).trim()}\n${String(stdout).trim()}`));
             }
@@ -4074,7 +4309,7 @@ async function ensureDeps(code) {
             }
         });
     });
-    return missing;
+    return { code: await rewriteUnreachable(code, unreachable), installed: missing };
 }
 /**
  * Turn the bare parser error an `export default` misuse produces
@@ -4271,10 +4506,14 @@ async function evalCode(code, secrets) {
     let filePath;
     let outcome;
     try {
-        installed = await ensureDeps(code);
+        // The snippet that runs can differ from the one the user sent: a
+        // freshly installed import is rewritten to an absolute path (see
+        // ensureDeps). Error messages keep using the original `code`.
+        const prepared = await ensureDeps(code);
+        installed = prepared.installed;
         await fs.mkdir(EVAL_DIR, { recursive: true });
         filePath = path.join(EVAL_DIR, `${randomUUID()}.ts`);
-        await fs.writeFile(filePath, code);
+        await fs.writeFile(filePath, prepared.code);
         const mod = (await import(pathToFileURL(filePath).href));
         outcome = { ok: true, result: safeSerialize(mod.default) };
     }

package/dist/index.d.ts

@@ -684,6 +684,18 @@ export interface FileMount {
      * file before it's bind-mounted. Defaults to the writer's umask.
      */
     mode?: string;
+    /**
+     * Owner of the staged file — a user name from the image's
+     * `/etc/passwd` (resolved against the image, so `"postgres"` works),
+     * or a numeric uid. A bind mount carries the staged file's ownership
+     * straight through, so a file written by the daemon lands as `root`:
+     * pair a restrictive `mode` with `user` or the container's own
+     * process can't read it.
+     */
+    user?: string;
+    /** Group of the staged file — a group name from the image's
+     *  `/etc/group`, or a numeric gid. */
+    group?: string;
 }
 /** PEM material returned by `ctx.certificate(hostnames)`. */
 export interface CertificateMaterial {
@@ -713,9 +725,28 @@ export interface CertificateMount {
     /**
      * Optional octal mode (e.g. `"0600"`) applied to the staged key.
      * Servers that refuse a group/world-readable key (postgres, ssh) need
-     * this; the default is the writer's umask.
+     * this. The default is the writer's umask — or, once `user`/`group`
+     * says who reads the key, the strictest mode that owner can still
+     * read (`0600`, or `0640` when only `group` is given).
      */
     mode?: string;
+    /**
+     * Owner of the staged key and certificate — a user name from the
+     * image's `/etc/passwd` (resolved against the image, so
+     * `"postgres"` works), or a numeric uid.
+     *
+     * A bind mount carries the staged file's ownership through, and the
+     * daemon writes as `root`, so a strict `mode` alone gives a
+     * non-root server a key it cannot open — postgres reports
+     * `could not access private key file`. `user` is what makes the
+     * pair work, with no entrypoint wrapper and no custom image.
+     */
+    user?: string;
+    /** Group of the staged key and certificate — a group name from the
+     *  image's `/etc/group`, or a numeric gid. Enough on its own for a
+     *  server that accepts a root-owned key readable by its group
+     *  (postgres does, at `0640`). */
+    group?: string;
 }
 export type ReadyCheck = {
     type: "tcp";

package/dist/locator.d.ts

@@ -5,7 +5,7 @@ import type { Wrapped } from "./inspect.js";
  *  Playwright's own default is 30s — far too slow-failing for tests; 5s
  *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
  *  `undefined` falls through to the context default (also set to this in
- *  browser.ts's `contextFor`). Navigations keep a longer deadline. */
+ *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
 export declare const DEFAULT_ACTION_TIMEOUT_MS = 5000;
 export interface GetByTextOptions {
     /** Whole-string, case-sensitive match instead of the default

package/dist/locator.js

@@ -26,7 +26,7 @@ import { truncateUtf8 } from "./recorder.js";
  *  Playwright's own default is 30s — far too slow-failing for tests; 5s
  *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
  *  `undefined` falls through to the context default (also set to this in
- *  browser.ts's `contextFor`). Navigations keep a longer deadline. */
+ *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
 export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
 // Brand + chain carrier. Both are `Symbol.for` keys so `JSON.stringify` drops
 // them (locators are never serialized) while runtime code can still detect a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",