@sema-agent/connectors 0.5.0 → 0.7.0

package/dist/pinned-upstream.js

@@ -1,16 +1,18 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
-import { chmodSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { chmodSync, closeSync, constants, createReadStream, fchmodSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, renameSync, rmSync } from 'node:fs';
 import { get as httpsGet } from 'node:https';
 import { constants as osConstants } from 'node:os';
 import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { fileURLToPath } from 'node:url';
 import { cliOutput, listed } from './cli-kit.js';
 import { given } from './config-dir.js';
 import { CONNECTOR_NAME } from './connector-name.js';
-import { entryOf } from './release-archive.js';
+import { archiveEntry, formatOf, treeListing, treeProblem, unpackTree } from './release-archive.js';
 import { HANDLE_NAME, openFileSecrets } from './secrets.js';
-import { writeAll } from './write-all.js';
+import { writeAll, writeAllStream } from './write-all.js';
 const CONNECTOR_DIR = 'CONNECTOR_DIR';
 const BIN_DIR = 'bin';
 const DIRECTORY_MODE = 0o700;
@@ -22,12 +24,16 @@ const REDIRECT_LIMIT = 5;
 const SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
 const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/;
 const PLATFORM = /^[a-z0-9]+-[a-z0-9]+$/;
+const EVERY_PLATFORM = '*';
 const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SEGMENT = /^[A-Za-z0-9@][A-Za-z0-9@._-]*$/;
 const SHA256 = /^[0-9a-f]{64}$/;
 const platformKey = () => `${process.platform}-${process.arch}`;
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const keysAre = (v, keys) => Object.keys(v).sort().join('\0') === [...keys].sort().join('\0');
-const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const isPath = (v) => typeof v === 'string' && v.split('/').every((s) => SEGMENT.test(s));
+const isUnpack = (v) => isObject(v) && ((keysAre(v, ['entry']) && typeof v.entry === 'string' && FILE.test(v.entry)) || (keysAre(v, ['directory', 'to']) && typeof v.directory === 'string' && FILE.test(v.directory) && isPath(v.to)));
+const topOf = (u) => ('entry' in u ? u.entry : u.to.split('/')[0]);
 const below = (dir, file) => {
     if (!isAbsolute(file))
         return false;
@@ -60,7 +66,88 @@ function regularFile(path) {
         closeSync(fd);
     }
 }
-function fetchHttps(url, redirects) {
+function sha256Of(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return null;
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return null;
+        const hash = createHash('sha256');
+        const piece = Buffer.alloc(1024 * 1024);
+        for (let n; (n = readSync(fd, piece, 0, piece.length, null)) > 0;)
+            hash.update(piece.subarray(0, n));
+        return hash.digest('hex');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function treeDiffers(root, listed) {
+    const seen = new Set();
+    const visit = (rel) => {
+        let names;
+        try {
+            names = readdirSync(rel === '' ? root : join(root, rel));
+        }
+        catch {
+            return rel === '' ? '.' : rel;
+        }
+        for (const name of names) {
+            const path = rel === '' ? name : `${rel}/${name}`;
+            const want = listed.get(path);
+            if (want === undefined)
+                return path;
+            seen.add(path);
+            let st;
+            try {
+                st = lstatSync(join(root, path));
+            }
+            catch {
+                return path;
+            }
+            const kind = st.isSymbolicLink() ? 'link' : st.isDirectory() ? 'directory' : st.isFile() ? 'file' : 'other';
+            if (kind !== want.kind)
+                return path;
+            if (kind === 'file' && (st.size !== want.size || (st.mode & 0o777) !== want.mode))
+                return path;
+            if (kind === 'link' && readlinkSync(join(root, path)) !== want.link)
+                return path;
+            if (kind === 'directory') {
+                const deeper = visit(path);
+                if (deeper !== null)
+                    return deeper;
+            }
+        }
+        return null;
+    };
+    const first = visit('');
+    if (first !== null)
+        return first;
+    for (const path of listed.keys())
+        if (!seen.has(path))
+            return path;
+    return null;
+}
+class Hashed extends Transform {
+    hash = createHash('sha256');
+    size = 0;
+    _transform(chunk, _encoding, done) {
+        this.size += chunk.length;
+        if (this.size > DOWNLOAD_LIMIT)
+            return done(new Error(`the archive is larger than ${DOWNLOAD_LIMIT} bytes`));
+        this.hash.update(chunk);
+        done(null, chunk);
+    }
+}
+function fetchHttps(url, redirects, dest) {
     return new Promise((resolve) => {
         let settled = false;
         const done = (r) => {
@@ -85,45 +172,67 @@ function fetchHttps(url, redirects) {
                     return done({ ok: false, problem: `the download was redirected more than ${REDIRECT_LIMIT} times` });
                 if (next.protocol !== 'https:' || next.username !== '' || next.password !== '')
                     return done({ ok: false, problem: 'the download was redirected away from https' });
-                return void fetchHttps(next, redirects - 1).then(done);
+                return void fetchHttps(next, redirects - 1, dest).then(done);
             }
             if (status !== 200) {
                 res.resume();
                 return done({ ok: false, problem: `the download answered HTTP ${status}` });
             }
-            const parts = [];
-            let size = 0;
-            res.on('data', (d) => {
-                size += d.length;
-                if (size > DOWNLOAD_LIMIT) {
-                    req.destroy();
-                    done({ ok: false, problem: `the archive is larger than ${DOWNLOAD_LIMIT} bytes` });
-                }
-                else
-                    parts.push(d);
+            const hashed = new Hashed();
+            let out;
+            try {
+                out = openSync(dest, 'wx', 0o600);
+            }
+            catch (e) {
+                res.resume();
+                return done({ ok: false, problem: `the download could not be written (${e.code ?? 'unknown error'})` });
+            }
+            pipeline(res, hashed, writeAllStream(out)).then(() => {
+                closeSync(out);
+                done({ ok: true, sha256: hashed.hash.digest('hex') });
+            }, (e) => {
+                closeSync(out);
+                req.destroy();
+                done({ ok: false, problem: hashed.size > DOWNLOAD_LIMIT ? `the archive is larger than ${DOWNLOAD_LIMIT} bytes` : `the download broke off (${e.message})` });
             });
-            res.on('end', () => done({ ok: true, bytes: Buffer.concat(parts) }));
-            res.on('error', () => done({ ok: false, problem: 'the download broke off' }));
         });
         req.setTimeout(DOWNLOAD_IDLE_MS, () => req.destroy(new Error(`no data for ${DOWNLOAD_IDLE_MS / 1000} s`)));
         req.on('error', (e) => done({ ok: false, problem: `the download failed (${e.message})` }));
     });
 }
-async function fetchArchive(url) {
+async function fetchArchive(url, dest) {
     if (url.protocol === 'https:')
-        return fetchHttps(url, REDIRECT_LIMIT);
+        return fetchHttps(url, REDIRECT_LIMIT, dest);
     const path = fileURLToPath(url);
+    let fd;
     try {
-        const st = statSync(path);
+        fd = openSync(path, 'r');
+    }
+    catch {
+        return { ok: false, problem: `${path} cannot be read` };
+    }
+    try {
+        const st = fstatSync(fd);
         if (!st.isFile())
             return { ok: false, problem: `${path} is not a file` };
         if (st.size > DOWNLOAD_LIMIT)
             return { ok: false, problem: `the archive is larger than ${DOWNLOAD_LIMIT} bytes` };
-        return { ok: true, bytes: readFileSync(path) };
+        const hashed = new Hashed();
+        const out = openSync(dest, 'wx', 0o600);
+        try {
+            await pipeline(createReadStream('', { fd, autoClose: false }), hashed, writeAllStream(out));
+        }
+        finally {
+            closeSync(out);
+        }
+        return { ok: true, sha256: hashed.hash.digest('hex') };
     }
     catch {
         return { ok: false, problem: `${path} cannot be read` };
     }
+    finally {
+        closeSync(fd);
+    }
 }
 export function pinnedUpstream(options) {
     const { connector, upstream, lockFile } = options ?? {};
@@ -136,12 +245,16 @@ export function pinnedUpstream(options) {
     const handles = options.handles;
     if (!Array.isArray(handles) || !handles.every((h) => typeof h === 'string' && HANDLE_NAME.test(h)) || new Set(handles).size !== handles.length)
         throw new Error('handles must list handle names, each once');
+    const optionalHandles = options.optionalHandles ?? [];
+    if (!Array.isArray(optionalHandles) || !optionalHandles.every((h) => typeof h === 'string' && HANDLE_NAME.test(h)))
+        throw new Error('optionalHandles must list handle names');
+    const allHandles = [...handles, ...optionalHandles];
+    if (new Set(allHandles).size !== allHandles.length)
+        throw new Error('handles and optionalHandles must list handle names, each once');
     const { program, say, complain } = cliOutput(connector);
-    const fileVars = handles.map((h) => `${h}_FILE`);
-    const binaryOf = (connectorDir) => join(connectorDir, BIN_DIR, upstream);
+    const fileVars = allHandles.map((h) => `${h}_FILE`);
     function pinnedBuild() {
         const refuse = (problem) => ({ ok: false, problem: `binaries.lock.json ${problem}` });
-        const isBuild = (v) => isObject(v) && keysAre(v, ['file', 'sha256']) && typeof v.file === 'string' && FILE.test(v.file) && v.file !== upstream && typeof v.sha256 === 'string' && SHA256.test(v.sha256);
         let doc;
         try {
             doc = JSON.parse(readFileSync(lockFile, 'utf8'));
@@ -152,25 +265,48 @@ export function pinnedUpstream(options) {
         if (!isObject(doc) || !keysAre(doc, [upstream]))
             return refuse(`must hold exactly one entry, "${upstream}"`);
         const entry = doc[upstream];
-        if (!isObject(entry) || !keysAre(entry, ['version', 'source', 'platforms']))
-            return refuse('must give exactly version, source and platforms');
-        const { version, source, platforms } = entry;
+        if (!isObject(entry) || !keysAre(entry, ['version', 'archives', 'program']))
+            return refuse('must give exactly version, archives and program');
+        const { version, archives, program: prog } = entry;
         if (typeof version !== 'string' || !VERSION.test(version))
             return refuse('must give the version as <major>.<minor>.<patch>');
-        if (typeof source !== 'string' || !source.includes('{file}'))
-            return refuse('must give the source as a URL template naming {file}');
-        if (!isObject(platforms) || !Object.entries(platforms).every(([k, v]) => PLATFORM.test(k) && isBuild(v)))
-            return refuse('must map each platform to {"file": <archive name>, "sha256": <64 hex digits>}');
+        const isArchive = (v) => isObject(v) &&
+            keysAre(v, ['platform', 'file', 'source', 'sha256', 'unpack']) &&
+            typeof v.platform === 'string' &&
+            (v.platform === EVERY_PLATFORM || PLATFORM.test(v.platform)) &&
+            typeof v.file === 'string' &&
+            FILE.test(v.file) &&
+            formatOf(v.file) !== null &&
+            typeof v.source === 'string' &&
+            typeof v.sha256 === 'string' &&
+            SHA256.test(v.sha256) &&
+            isUnpack(v.unpack);
+        if (!Array.isArray(archives) || archives.length === 0 || !archives.every(isArchive))
+            return refuse('must list archives, each {"platform": <platform> or "*", "file": <name ending in .tar.gz, .tgz or .zip>, "source": <URL template>, "sha256": <64 hex digits>, "unpack": {"entry": <name>} or {"directory": <name>, "to": <path>}}');
+        if (!isObject(prog) || !((keysAre(prog, ['binary']) && isPath(prog.binary)) || (keysAre(prog, ['node']) && isPath(prog.node))))
+            return refuse('must give the program as {"binary": <path>} or {"node": <path>}');
         const key = platformKey();
-        const build = Object.hasOwn(platforms, key) ? platforms[key] : undefined;
-        if (!isBuild(build))
+        const all = archives.map((a) => ({ ...a, format: formatOf(a.file) }));
+        if (!all.some((a) => a.platform === key))
             return refuse(`pins no ${upstream} build for ${key}`);
-        return { ok: true, lock: { version, source, platforms: platforms }, build };
+        const mine = all.filter((a) => a.platform === key || a.platform === EVERY_PLATFORM);
+        const tops = mine.map((a) => topOf(a.unpack));
+        const places = [...mine.map((a) => a.file), ...mine.filter((a) => 'entry' in a.unpack).map((a) => a.unpack.entry)];
+        const trees = mine.flatMap((a) => ('to' in a.unpack ? [a.unpack.to] : []));
+        const overlap = trees.some((t, i) => trees.some((u, j) => i !== j && (t === u || t.startsWith(`${u}/`)))) || places.some((p, i) => places.indexOf(p) !== i) || mine.some((a) => trees.some((t) => t.split('/')[0] === a.file)) || mine.some((a) => 'entry' in a.unpack && trees.some((t) => t.split('/')[0] === topOf(a.unpack)));
+        if (overlap || tops.length !== mine.length)
+            return refuse(`gives two archives for ${key} the same place in the bin directory`);
+        const kind = 'binary' in prog ? 'binary' : 'node';
+        const path = (kind === 'binary' ? prog.binary : prog.node);
+        const provides = mine.filter((a) => ('entry' in a.unpack ? a.unpack.entry === path : path.startsWith(`${a.unpack.to}/`)));
+        if (provides.length !== 1)
+            return refuse(`does not unpack the program ${path} from exactly one archive for ${key}`);
+        return { ok: true, build: { version, archives: mine, program: { kind, path } } };
     }
-    function sourceOf(lock, build) {
+    function sourceOf(build, archive) {
         let url;
         try {
-            url = new URL(lock.source.replaceAll('{version}', lock.version).replaceAll('{file}', build.file));
+            url = new URL(archive.source.replaceAll('{version}', build.version).replaceAll('{file}', archive.file));
         }
         catch {
             return { ok: false, problem: 'the source in binaries.lock.json is not a URL' };
@@ -181,6 +317,11 @@ export function pinnedUpstream(options) {
             return { ok: true, url };
         return { ok: false, problem: 'the source in binaries.lock.json must be an https or file URL (an https URL without credentials)' };
     }
+    function programSource(build) {
+        const { path } = build.program;
+        const archive = build.archives.find((a) => ('entry' in a.unpack ? a.unpack.entry === path : path.startsWith(`${a.unpack.to}/`)));
+        return { archive, name: 'entry' in archive.unpack ? archive.unpack.entry : `${archive.unpack.directory}/${path.slice(archive.unpack.to.length + 1)}` };
+    }
     function installedProblem(connectorDir, build) {
         const dir = join(connectorDir, BIN_DIR);
         let st;
@@ -192,21 +333,52 @@ export function pinnedUpstream(options) {
         }
         if (!st.isDirectory() || (st.mode & 0o777) !== DIRECTORY_MODE)
             return 'the bin directory of the connector is not a 0700 directory';
-        const archive = regularFile(join(dir, build.file));
-        if (archive === null)
-            return `${upstream} is not installed (the pinned archive is not there)`;
-        if (sha256(archive) !== build.sha256)
-            return 'the archive there is not the one binaries.lock.json pins';
-        const entry = entryOf(archive, upstream);
-        if (!entry.ok)
-            return `the pinned archive ${entry.problem}`;
-        const binary = binaryOf(connectorDir);
-        const bytes = regularFile(binary);
-        if (bytes === null || !bytes.equals(entry.bytes))
-            return `${upstream} there is not the entry of the pinned archive`;
-        if ((lstatSync(binary).mode & 0o777) !== BINARY_MODE)
-            return `${upstream} there is not mode 0755`;
-        return null;
+        const sameAs = (archive, name, file, executable) => {
+            const entry = archiveEntry(join(dir, archive.file), archive.format, name);
+            if (!entry.ok)
+                return `the pinned archive ${entry.problem}`;
+            const path = join(dir, file);
+            const bytes = regularFile(path);
+            if (bytes === null || !bytes.equals(entry.bytes))
+                return `${file} there is not the entry of the pinned archive`;
+            if (executable && (lstatSync(path).mode & 0o777) !== BINARY_MODE)
+                return `${file} there is not mode 0755`;
+            return null;
+        };
+        for (const archive of build.archives) {
+            const hash = sha256Of(join(dir, archive.file));
+            if (hash === null)
+                return `${upstream} is not installed (the pinned archive is not there)`;
+            if (hash !== archive.sha256)
+                return 'the archive there is not the one binaries.lock.json pins';
+            if ('entry' in archive.unpack) {
+                const problem = sameAs(archive, archive.unpack.entry, archive.unpack.entry, true);
+                if (problem !== null)
+                    return problem;
+                continue;
+            }
+            let tree;
+            try {
+                tree = lstatSync(join(dir, archive.unpack.to));
+            }
+            catch {
+                tree = null;
+            }
+            if (tree === null || !tree.isDirectory())
+                return `${upstream} is not installed (${archive.unpack.to} is not there)`;
+            const listing = treeListing(join(dir, archive.file), archive.format, archive.unpack.directory);
+            if (!listing.ok)
+                return `the pinned archive ${listing.problem}`;
+            const differs = treeDiffers(join(dir, archive.unpack.to), listing.paths);
+            if (differs !== null)
+                return `${archive.unpack.to}/${differs} there is not as the pinned archive gives it`;
+        }
+        const { archive, name } = programSource(build);
+        return 'entry' in archive.unpack ? null : sameAs(archive, name, build.program.path, build.program.kind === 'binary');
+    }
+    function commit(tmp, path, mode) {
+        chmodSync(tmp, mode);
+        renameSync(tmp, path);
     }
     function writeAtomically(path, bytes, mode) {
         const tmp = join(dirname(path), `.${upstream}.${randomBytes(6).toString('hex')}.tmp`);
@@ -226,13 +398,52 @@ export function pinnedUpstream(options) {
             throw e;
         }
     }
+    async function placeTree(binDir, archive, from) {
+        const target = join(binDir, archive.unpack.to);
+        const parent = dirname(target);
+        mkdirSync(parent, { recursive: true, mode: 0o755 });
+        for (let p = parent; p !== binDir; p = dirname(p))
+            if (!lstatSync(p).isDirectory())
+                throw new Error(`${relative(binDir, p)} in the bin directory is not a directory`);
+        const tmp = mkdtempSync(join(binDir, `.${upstream}.unpack-`));
+        const old = join(binDir, `.${upstream}.old-${randomBytes(6).toString('hex')}`);
+        try {
+            const problem = await unpackTree(from, archive.format, archive.unpack.directory, tmp);
+            if (problem !== null)
+                throw new Error(`the pinned archive ${archive.file} ${problem}`);
+            chmodSync(tmp, 0o755);
+            let had = true;
+            try {
+                renameSync(target, old);
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+                had = false;
+            }
+            try {
+                renameSync(tmp, target);
+            }
+            catch (e) {
+                if (had)
+                    renameSync(old, target);
+                throw e;
+            }
+            if (had)
+                rmSync(old, { recursive: true, force: true });
+        }
+        catch (e) {
+            rmSync(tmp, { recursive: true, force: true });
+            throw e;
+        }
+    }
     async function install(configDir) {
         const pinned = pinnedBuild();
         if (!pinned.ok) {
             complain(`${pinned.problem}; nothing was installed`);
             return 1;
         }
-        const { lock, build } = pinned;
+        const { build } = pinned;
         const secrets = openFileSecrets({ configDir, connector });
         const before = secrets.list();
         if (!before.ok) {
@@ -242,29 +453,23 @@ export function pinnedUpstream(options) {
         const connectorDir = secrets.directory;
         const binDir = join(connectorDir, BIN_DIR);
         if (installedProblem(connectorDir, build) === null) {
-            say(`${upstream} ${lock.version} is already installed in ${binDir}; nothing changed`);
+            say(`${upstream} ${build.version} is already installed in ${binDir}; nothing changed`);
             return 0;
         }
-        const source = sourceOf(lock, build);
-        if (!source.ok) {
-            complain(`${source.problem}; nothing was installed`);
-            return 1;
-        }
-        const fetched = await fetchArchive(source.url);
-        if (!fetched.ok) {
-            complain(`${build.file} could not be fetched: ${fetched.problem}; nothing was installed`);
-            return 1;
-        }
-        const actual = sha256(fetched.bytes);
-        if (actual !== build.sha256) {
-            complain(`the fetched ${build.file} does not match binaries.lock.json (sha256 ${actual}, pinned ${build.sha256}); nothing was installed`);
-            return 1;
-        }
-        const entry = entryOf(fetched.bytes, upstream);
-        if (!entry.ok) {
-            complain(`the pinned archive ${build.file} ${entry.problem}; nothing was installed`);
-            return 1;
+        const sources = [];
+        for (const archive of build.archives) {
+            const source = sourceOf(build, archive);
+            if (!source.ok) {
+                complain(`${source.problem}; nothing was installed`);
+                return 1;
+            }
+            sources.push(source.url);
         }
+        const temps = [];
+        const dropTemps = () => {
+            for (const t of temps)
+                rmSync(t, { force: true });
+        };
         try {
             mkdirSync(binDir, { recursive: true, mode: DIRECTORY_MODE });
             const after = secrets.list();
@@ -274,24 +479,74 @@ export function pinnedUpstream(options) {
             if (!st.isDirectory())
                 throw new Error('the bin directory of the connector is not a directory');
             chmodSync(binDir, DIRECTORY_MODE);
-            writeAtomically(join(binDir, build.file), fetched.bytes, ARCHIVE_MODE);
-            writeAtomically(binaryOf(connectorDir), entry.bytes, BINARY_MODE);
         }
         catch (e) {
             complain(`${upstream} was not installed: ${e instanceof Error ? e.message : 'unknown error'}`);
             return 1;
         }
+        for (const [i, archive] of build.archives.entries()) {
+            const tmp = join(binDir, `.${upstream}.${randomBytes(6).toString('hex')}.download`);
+            temps.push(tmp);
+            const fetched = await fetchArchive(sources[i], tmp);
+            if (!fetched.ok) {
+                dropTemps();
+                complain(`${archive.file} could not be fetched: ${fetched.problem}; nothing was installed`);
+                return 1;
+            }
+            if (fetched.sha256 !== archive.sha256) {
+                dropTemps();
+                complain(`the fetched ${archive.file} does not match binaries.lock.json (sha256 ${fetched.sha256}, pinned ${archive.sha256}); nothing was installed`);
+                return 1;
+            }
+            const problem = 'entry' in archive.unpack ? (() => {
+                const e = archiveEntry(tmp, archive.format, archive.unpack.entry);
+                return e.ok ? null : e.problem;
+            })() : treeProblem(tmp, archive.format, archive.unpack.directory);
+            if (problem !== null) {
+                dropTemps();
+                complain(`the pinned archive ${archive.file} ${problem}; nothing was installed`);
+                return 1;
+            }
+        }
+        {
+            const { archive, name } = programSource(build);
+            const entry = archiveEntry(temps[build.archives.indexOf(archive)], archive.format, name);
+            if (!entry.ok) {
+                dropTemps();
+                complain(`the pinned archive ${archive.file} ${entry.problem}; nothing was installed`);
+                return 1;
+            }
+        }
+        try {
+            for (const [i, archive] of build.archives.entries()) {
+                const tmp = temps[i];
+                if ('entry' in archive.unpack) {
+                    const e = archiveEntry(tmp, archive.format, archive.unpack.entry);
+                    if (!e.ok)
+                        throw new Error(`the pinned archive ${archive.file} ${e.problem}`);
+                    writeAtomically(join(binDir, archive.unpack.entry), e.bytes, BINARY_MODE);
+                }
+                else
+                    await placeTree(binDir, archive, tmp);
+                commit(tmp, join(binDir, archive.file), ARCHIVE_MODE);
+            }
+        }
+        catch (e) {
+            dropTemps();
+            complain(`${upstream} was not installed: ${e instanceof Error ? e.message : 'unknown error'}`);
+            return 1;
+        }
         const problem = installedProblem(connectorDir, build);
         if (problem !== null) {
             complain(`${upstream} was written but does not read back as the pinned build: ${problem}`);
             return 1;
         }
-        say(`installed ${upstream} ${lock.version} (${build.file}, sha256 ${build.sha256}) in ${binDir}`);
+        say(`installed ${upstream} ${build.version} (${build.archives.map((a) => `${a.file}, sha256 ${a.sha256}`).join('; ')}) in ${binDir}`);
         return 0;
     }
-    function run(binary, args, env) {
+    function run(command, args, env) {
         return new Promise((resolve) => {
-            const child = spawn(binary, [...args], { stdio: 'inherit', env });
+            const child = spawn(command, [...args], { stdio: 'inherit', env });
             const forwarders = SIGNALS.map((signal) => [signal, () => void child.kill(signal)]);
             for (const [signal, forward] of forwarders)
                 process.on(signal, forward);
@@ -320,11 +575,14 @@ export function pinnedUpstream(options) {
         const connectorDir = env[CONNECTOR_DIR];
         if (!given(connectorDir) || !isAbsolute(connectorDir))
             return refuse(`${CONNECTOR_DIR} does not name the connector's directory: start the connector with sema-connector run ${connector}`);
-        const paths = fileVars.map((v) => env[v]);
-        if (!paths.every(given))
+        const requiredPaths = handles.map((h) => env[`${h}_FILE`]);
+        if (!requiredPaths.every(given))
             return refuse(`connector ${connector} has no ${listed(handles)} ${handles.length === 1 ? 'handle' : 'handles'} to start ${upstream} with: store ${handles.length === 1 ? 'it' : 'them'} with ${program} auth`);
-        if (!paths.every((p) => below(connectorDir, p) && isRegularFile(p)))
-            return refuse(`${listed(fileVars)} must name files in the connector's directory (${CONNECTOR_DIR}), as the launcher hands ${handles.length === 1 ? 'it' : 'them'}: start the connector with sema-connector run ${connector}`);
+        const presentHandles = [...handles, ...optionalHandles.filter((h) => given(env[`${h}_FILE`]))];
+        const presentVars = presentHandles.map((h) => `${h}_FILE`);
+        const presentPaths = presentVars.map((v) => env[v]);
+        if (!presentPaths.every((p) => given(p) && below(connectorDir, p) && isRegularFile(p)))
+            return refuse(`${listed(presentVars)} must name files in the connector's directory (${CONNECTOR_DIR}), as the launcher hands ${presentHandles.length === 1 ? 'it' : 'them'}: start the connector with sema-connector run ${connector}`);
         const pinned = pinnedBuild();
         if (!pinned.ok)
             return refuse(pinned.problem);
@@ -335,12 +593,15 @@ export function pinnedUpstream(options) {
         for (const [k, v] of Object.entries(env))
             if (v !== undefined && k !== CONNECTOR_DIR && !fileVars.includes(k))
                 own[k] = v;
-        const binary = binaryOf(connectorDir);
+        const binDir = join(connectorDir, BIN_DIR);
+        const path = join(binDir, pinned.build.program.path);
+        const [command, first] = pinned.build.program.kind === 'node' ? [process.execPath, [path]] : [path, []];
         return {
             ok: true,
             connectorDir,
-            files: Object.fromEntries(handles.map((h, i) => [h, paths[i]])),
-            run: (args, extra) => run(binary, args, { ...own, ...extra }),
+            binDir,
+            files: Object.fromEntries(presentHandles.map((h, i) => [h, presentPaths[i]])),
+            run: (args, extra) => run(command, [...first, ...args], { ...own, ...extra }),
         };
     }
     return { install, start };

package/dist/principal.d.ts

@@ -41,7 +41,7 @@ export type PrincipalResult = {
 export interface PrincipalResolver {
     resolve(request: RequestContext): PrincipalResult;
 }
-export declare function standaloneResolver(): PrincipalResolver;
+export declare function standaloneResolver(policy?: readonly string[] | null): PrincipalResolver;
 export declare function hostedResolver(options: {
     readonly issuer: string;
     readonly audience: string;

package/dist/principal.js

@@ -95,8 +95,11 @@ export function verifyAssertion(compactJws, options) {
     return { ok: true, principal: { kind: 'assertion', sub, space, scope: scope.split(' ') } };
 }
 const ANONYMOUS = Object.freeze({ kind: 'anonymous', scope: Object.freeze(['tool:*']) });
-export function standaloneResolver() {
-    return { resolve: () => ({ ok: true, principal: ANONYMOUS }) };
+export function standaloneResolver(policy) {
+    if (policy === null || policy === undefined)
+        return { resolve: () => ({ ok: true, principal: ANONYMOUS }) };
+    const principal = Object.freeze({ kind: 'anonymous', scope: Object.freeze(policy.map((name) => `tool:${name}`)) });
+    return { resolve: () => ({ ok: true, principal }) };
 }
 export function hostedResolver(options) {
     if (typeof options?.issuer !== 'string' || options.issuer === '' || typeof options.audience !== 'string' || options.audience === '') {

package/dist/release-archive.d.ts

@@ -1,3 +1,5 @@
+export declare const UNPACKED_LIMIT: number;
+export type ArchiveFormat = 'tar.gz' | 'zip';
 export type Entry = {
     readonly ok: true;
     readonly bytes: Buffer;
@@ -5,4 +7,24 @@ export type Entry = {
     readonly ok: false;
     readonly problem: string;
 };
+type Problem = string | null;
+export declare const formatOf: (file: string) => ArchiveFormat | null;
 export declare function entryOf(archive: Buffer, wanted: string): Entry;
+export declare function archiveEntry(path: string, format: ArchiveFormat, wanted: string): Entry;
+export declare function unpackTree(path: string, format: ArchiveFormat, top: string, dest: string): Promise<Problem>;
+export declare function treeProblem(path: string, format: ArchiveFormat, top: string): Problem;
+export interface Listed {
+    readonly kind: 'file' | 'directory' | 'link';
+    readonly mode: number;
+    readonly size: number;
+    readonly link?: string;
+}
+export type Listing = {
+    readonly ok: true;
+    readonly paths: ReadonlyMap<string, Listed>;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function treeListing(path: string, format: ArchiveFormat, top: string): Listing;
+export {};