hammerkit 1.26.0 → 1.27.0-next.2

package/dist/server/sandbox-storage.js

@@ -0,0 +1,462 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostSandboxStorage = exports.SandboxPushFailed = exports.SandboxPushConflict = void 0;
+const crypto_1 = require("crypto");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const git_checkout_1 = require("./git-checkout");
+const sandbox_files_1 = require("./sandbox-files");
+// how many directories the walk reads at once, and how many entries of one it looks at at once
+const WALK_DIRECTORIES = 16;
+const WALK_ENTRIES = 256;
+class SandboxPushConflict extends Error {
+}
+exports.SandboxPushConflict = SandboxPushConflict;
+// A push that failed after its commit was written: the remote may have taken it anyway (a
+// timeout after it answered), which the caller checks against the branch.
+class SandboxPushFailed extends Error {
+    constructor(commit, cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.commit = commit;
+        this.cause = cause;
+    }
+}
+exports.SandboxPushFailed = SandboxPushFailed;
+// the commit a sandbox pushed last, in its own git data
+const PUSHED_REF = 'refs/hammerkit/pushed';
+/**
+ * Sandboxes as directories below `directory`, one per sandbox: `files` is the checkout the
+ * tasks work on, `git` its git data. The git data is kept outside of the files on purpose:
+ * tasks write to the files, and a `.git/config` or a hook they wrote would be read by the
+ * git of the server, which runs as the server's user. Every git command names its git
+ * directory and work tree, and runs without hooks or a file system monitor.
+ */
+class HostSandboxStorage {
+    constructor(directory, 
+    // the environment of git when it reads a sandbox: the variables runs see
+    env, 
+    // what containers left of a sandbox, when runs on it use containers
+    containers) {
+        this.directory = directory;
+        this.env = env;
+        this.containers = containers;
+        // one git command or walk at a time per sandbox: the objects `state` writes are pruned
+        // again, which must not meet another command that still needs them
+        this.queues = new Map();
+        // the sandboxes walked since a run last wrote to them, with the links the walk found: only
+        // a run's tasks write to a sandbox, between its `attach` and the `usage` it ends with, so
+        // until the next attach a `state` needs no walk. The edits of the file API write readable
+        // files and never a link, so a walk still holds after them: a link it found that an edit
+        // replaced is no link any more, and is added as the file it is.
+        this.walked = new Map();
+        // the sandboxes a run attached and that were not measured since, and how often each was
+        // attached: a walk while a run may write, or that a run attached during, is not reused
+        this.attached = new Set();
+        this.attaches = new Map();
+    }
+    exclusive(id, fn) {
+        const previous = this.queues.get(id) ?? Promise.resolve();
+        const next = previous.then(fn, fn);
+        const settled = next.catch(() => undefined);
+        this.queues.set(id, settled);
+        settled.then(() => {
+            if (this.queues.get(id) === settled) {
+                this.queues.delete(id);
+            }
+        });
+        return next;
+    }
+    root(id) {
+        return (0, path_1.join)(this.directory, id);
+    }
+    workTree(id) {
+        return (0, path_1.join)(this.root(id), 'files');
+    }
+    async git(id, args, env, signal, action, options = {}) {
+        const root = this.root(id);
+        return (0, git_checkout_1.git)([
+            `--git-dir=${(0, path_1.join)(root, 'git')}`,
+            `--work-tree=${this.workTree(id)}`,
+            '-c',
+            `core.hooksPath=${(0, path_1.join)(root, 'no-hooks')}`,
+            '-c',
+            'core.fsmonitor=false',
+            // files as committed, on every system: a checkout with the machine's line endings
+            // and a read without its config would see every file changed (Git for Windows)
+            '-c',
+            'core.autocrlf=false',
+            '-c',
+            'advice.detachedHead=false',
+            '-c',
+            'advice.addEmbeddedRepo=false',
+            ...args,
+        ], env, signal, `sandbox ${id}`, action, options);
+    }
+    // The environment of git when it reads the sandbox, without an index of its own.
+    readEnv(extra = {}) {
+        const env = {};
+        for (const [key, value] of Object.entries(this.env)) {
+            if (value !== undefined && key !== 'GIT_INDEX_FILE') {
+                env[key] = value;
+            }
+        }
+        // reading the files needs no configuration of the server's: a filter or attributes the
+        // machine's git config names would run on files a task wrote
+        env.GIT_CONFIG_NOSYSTEM = '1';
+        // a file that is never there, which git reads as empty: Git for Windows refuses `\\.\nul`
+        env.GIT_CONFIG_GLOBAL = (0, path_1.join)(this.directory, 'no-git-config');
+        return { ...env, ...extra };
+    }
+    // `fn` with a copy of the sandbox's index that holds the files as they are (`addFiles`), so
+    // neither the index nor the files change, and what it wrote to the git data is pruned again.
+    // Files a task made unreadable are made readable first: git would leave them out and call
+    // them unchanged. Holds the sandbox. No walk when nothing wrote since the last one.
+    withIndex(id, signal, fn) {
+        return this.exclusive(id, async () => {
+            const links = this.walked.get(id) ?? (await this.walkOnce(id)).links;
+            try {
+                return await this.indexed(id, signal, links, fn);
+            }
+            finally {
+                await this.prune(id);
+            }
+        });
+    }
+    // a copy of the index that holds the files as they are (`addFiles`)
+    async indexed(id, signal, links, fn) {
+        const root = this.root(id);
+        const index = (0, path_1.join)(root, `index-${(0, crypto_1.randomBytes)(6).toString('hex')}`);
+        try {
+            const original = (0, path_1.join)(root, 'git', 'index');
+            await (0, promises_1.copyFile)(original, index).then(
+            // with the time of the index: git takes a file changed in the same second as it was
+            // written for changed only when the index is no newer than the file (racy git)
+            async () => {
+                const stats = await (0, promises_1.stat)(original);
+                await (0, promises_1.utimes)(index, stats.atime, stats.mtime);
+            }, () => undefined);
+            const env = this.readEnv({ GIT_INDEX_FILE: index });
+            await this.addFiles(id, env, signal, links);
+            return await fn((args, action, options = {}) => this.git(id, args, { ...env, ...options.env }, signal, action, { maxBuffer: options.maxBuffer }));
+        }
+        finally {
+            await (0, promises_1.rm)(index, { force: true });
+        }
+    }
+    // the sandbox's own index, HEAD and refs keep what they need
+    async prune(id) {
+        await this.git(id, ['prune', '--expire=now'], this.readEnv(), AbortSignal.timeout(60000), 'read').catch(() => undefined);
+    }
+    // `maxChangesBytes` is for tests, which make changes larger than it without writing 64 MiB
+    files({ id }, maxChangesBytes) {
+        return this.filesOf(id, (fn) => this.withIndex(id, AbortSignal.timeout(5 * 60 * 1000), fn), maxChangesBytes);
+    }
+    filesOf(id, withIndex, maxChangesBytes) {
+        const timeout = () => AbortSignal.timeout(5 * 60 * 1000);
+        return new sandbox_files_1.HostSandboxFiles(this.workTree(id), {
+            run: (args, action, options = {}) => this.git(id, args, this.readEnv(options.env), timeout(), action, { maxBuffer: options.maxBuffer }),
+            withIndex,
+        }, this.env, maxChangesBytes);
+    }
+    async create({ id }, fetch) {
+        const root = this.root(id);
+        // the sandboxes are their owners', nobody else on the machine reads them
+        await (0, promises_1.mkdir)(this.directory, { recursive: true, mode: 0o700 });
+        await (0, promises_1.mkdir)(this.workTree(id), { recursive: true });
+        try {
+            await (0, git_checkout_1.git)(['init', '--quiet', '--bare', (0, path_1.join)(root, 'git')], fetch.env, fetch.signal, `sandbox ${id}`, 'create');
+            return await this.checkout(id, fetch, true);
+        }
+        catch (e) {
+            await this.removeId(id);
+            throw e;
+        }
+    }
+    async fetch({ id }, fetch) {
+        return this.exclusive(id, () => this.checkout(id, fetch, false));
+    }
+    async checkout(id, fetch, force) {
+        if (!(0, git_checkout_1.isValidRef)(fetch.ref)) {
+            throw new Error(`${JSON.stringify(fetch.ref.slice(0, 80))} is not a branch`);
+        }
+        this.walked.delete(id);
+        // the branch by its full name: a tag of the same name is never taken
+        await this.git(id, ['fetch', '--quiet', '--depth', '1', '--', fetch.url, `refs/heads/${fetch.ref}`], fetch.env, fetch.signal, 'fetch');
+        await this.git(id, ['checkout', '--quiet', ...(force ? ['--force'] : []), 'FETCH_HEAD'], fetch.env, fetch.signal, 'check out');
+        return (await this.git(id, ['rev-parse', 'HEAD'], fetch.env, fetch.signal, 'read')).trim();
+    }
+    // One hold of the sandbox from the commit to the push: a prune in between would remove the
+    // commit. A ref keeps the commit until the sandbox is moved to it, also when the push
+    // failed late and the remote has it after all.
+    async push({ id }, push) {
+        return this.exclusive(id, async () => {
+            const links = this.walked.get(id) ?? (await this.walkOnce(id)).links;
+            try {
+                return await this.commitAndPush(id, push, links);
+            }
+            finally {
+                await this.prune(id);
+            }
+        });
+    }
+    // Commits the changes for a push from elsewhere (the server, for the pod of a sandbox on a
+    // cluster), and keeps the commit as the push does until the sandbox is moved to it.
+    async commit({ id }, author, signal) {
+        return this.exclusive(id, async () => {
+            const links = this.walked.get(id) ?? (await this.walkOnce(id)).links;
+            try {
+                return await this.keptCommit(id, author, signal, links);
+            }
+            finally {
+                await this.prune(id);
+            }
+        });
+    }
+    async keptCommit(id, author, signal, links) {
+        const commit = await this.filesOf(id, (fn) => this.indexed(id, signal, links, fn)).commit(author);
+        if (commit) {
+            await this.git(id, ['update-ref', PUSHED_REF, commit], this.readEnv(), signal, 'push');
+        }
+        return commit;
+    }
+    async commitAndPush(id, push, links) {
+        const commit = await this.keptCommit(id, push.author, push.signal, links);
+        if (!commit) {
+            return undefined;
+        }
+        const run = (args, action, env = this.readEnv()) => this.git(id, args, env, push.signal, action);
+        // a branch this sandbox pushed before only moves forward: the sandbox is at what it
+        // pushed last, or it was moved since and its changes are on another commit
+        if (push.expect) {
+            const ancestor = await run(['merge-base', '--is-ancestor', push.expect, commit], 'read').then(() => true, () => false);
+            if (!ancestor) {
+                throw new SandboxPushConflict(`${push.branch} is at ${push.expect}, which the sandbox is no longer on: push to a new branch`);
+            }
+        }
+        // the lease makes the remote refuse when the branch moved since it was read, and when
+        // somebody created it meanwhile
+        let printed;
+        try {
+            printed = await this.git(id, [
+                'push',
+                // a ref the remote refuses is a line with the reason (a GitHub App without the
+                // workflows permission, a ruleset), where git's last line only says it failed
+                '--porcelain',
+                '--no-verify',
+                `--force-with-lease=refs/heads/${push.branch}:${push.expect ?? ''}`,
+                '--',
+                push.url,
+                `${commit}:refs/heads/${push.branch}`,
+            ], 
+            // the write credential is in the environment of this one git process, which is
+            // that environment alone: nothing of the server's own git configuration
+            push.env, push.signal, 'push', { exitCodes: [1] });
+        }
+        catch (e) {
+            throw new SandboxPushFailed(commit, e);
+        }
+        // `<flag>\t<from>:<to>\t<summary>`; `!` is a refused ref
+        const line = printed
+            .split('\n')
+            .map((printedLine) => printedLine.split('\t'))
+            .find((fields) => fields.length >= 3 && fields[1].endsWith(`:refs/heads/${push.branch}`));
+        if (!line || line[0] === '!') {
+            const reason = line ? line.slice(2).join(' ') : printed.trim() || 'git printed nothing';
+            throw new SandboxPushFailed(commit, new Error(`the remote refused the push to ${push.branch}: ${reason}`));
+        }
+        return commit;
+    }
+    async moveTo({ id }, commit) {
+        if (!/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(commit)) {
+            throw new Error(`${JSON.stringify(commit.slice(0, 80))} is not a commit`);
+        }
+        await this.exclusive(id, () => this.git(id, ['reset', '--quiet', commit], this.readEnv(), AbortSignal.timeout(5 * 60 * 1000), 'move'));
+    }
+    // The tree is written with an index of its own, so neither the sandbox's index nor its
+    // files change, and what it wrote to the git data is pruned again. Files a task made
+    // unreadable are made readable first: git would leave them out and call the sandbox
+    // clean.
+    async state({ id }, signal = AbortSignal.timeout(5 * 60 * 1000)) {
+        return this.withIndex(id, signal, async (run) => {
+            const tree = (await run(['write-tree'], 'read')).trim();
+            const [commit, base] = (await run(['rev-parse', 'HEAD', 'HEAD^{tree}'], 'read')).trim().split('\n');
+            return { commit, tree, clean: tree === base };
+        });
+    }
+    // Adds the files as they are to the index of `env`. A link is written as a link and never
+    // walked: Git for Windows takes a junction for a directory, and would read what a
+    // `mklink /J x C:\` of a task points to.
+    async addFiles(id, env, signal, links) {
+        const written = await this.unignoredLinks(id, links, env, signal);
+        const pathspecs = ['.', ...written.map((link) => `:(top,exclude,literal)${link.path}`)];
+        await this.git(id, ['add', '--all', '--pathspec-from-file=-', '--pathspec-file-nul'], env, signal, 'read', {
+            input: pathspecs.map((pathspec) => `${pathspec}\0`).join(''),
+        });
+        if (written.length > 0) {
+            const entries = [];
+            for (const link of written) {
+                const blob = await this.git(id, ['hash-object', '-w', '--stdin'], env, signal, 'read', { input: link.target });
+                entries.push(`120000 ${blob.trim()}\t${link.path}\0`);
+            }
+            await this.git(id, ['update-index', '-z', '--add', '--replace', '--index-info'], env, signal, 'read', {
+                input: entries.join(''),
+            });
+        }
+    }
+    // the links of the files that are still links and that git does not ignore, by their path
+    // in the files ('/'-separated) and their target
+    async unignoredLinks(id, paths, env, signal) {
+        const files = this.workTree(id);
+        const links = [];
+        for (const path of paths) {
+            if (!path.startsWith(files + path_1.sep) || !(await (0, promises_1.lstat)(path).catch(() => undefined))?.isSymbolicLink()) {
+                continue;
+            }
+            links.push({ path: (0, path_1.relative)(files, path).split(path_1.sep).join('/'), target: await (0, promises_1.readlink)(path, 'buffer') });
+        }
+        if (links.length === 0) {
+            return [];
+        }
+        const ignored = await this.git(id, ['check-ignore', '-z', '--stdin'], env, signal, 'read', {
+            input: links.map((link) => `${link.path}\0`).join(''),
+            exitCodes: [1],
+        });
+        const skip = new Set(ignored.split('\0'));
+        return links.filter((link) => !skip.has(link.path));
+    }
+    // the run works in the sandbox itself
+    async attach({ id }) {
+        const files = this.workTree(id);
+        const stats = await (0, promises_1.lstat)(files).catch(() => undefined);
+        if (!stats?.isDirectory()) {
+            throw new Error(`the sandbox ${id} has no files on this server`);
+        }
+        // the run's tasks write from now on
+        this.walked.delete(id);
+        this.attached.add(id);
+        this.attaches.set(id, (this.attaches.get(id) ?? 0) + 1);
+        return { directory: files };
+    }
+    // What a task wrote is counted whatever it did to the modes, and with the volumes of its
+    // outputs. Symbolic links are counted, not followed: a link a task made points anywhere.
+    async usage({ id }) {
+        return this.exclusive(id, async () => {
+            // after a run: its tasks are done
+            this.attached.delete(id);
+            const { bytes } = await this.walkOnce(id);
+            return bytes + ((await this.containers?.volumeBytes(this.workTree(id)).catch(() => 0)) ?? 0);
+        });
+    }
+    async remove({ id }) {
+        await this.removeId(id);
+    }
+    async removeId(id) {
+        await this.exclusive(id, async () => {
+            this.walked.delete(id);
+            this.attached.delete(id);
+            this.attaches.delete(id);
+            await this.reclaim(id).catch(() => undefined);
+            await (0, promises_1.rm)(this.root(id), { recursive: true, force: true, maxRetries: 3 });
+            // without docker there is nothing to remove now; volumes stay labelled with the files
+            await this.containers?.removeVolumes(this.workTree(id)).catch(() => undefined);
+        });
+    }
+    // Walks the sandbox, and keeps the walk for the next `state` when no run wrote meanwhile.
+    async walkOnce(id) {
+        const attaches = this.attaches.get(id);
+        const walk = await this.reclaim(id);
+        if (!this.attached.has(id) && this.attaches.get(id) === attaches) {
+            this.walked.set(id, walk.links);
+        }
+        return walk;
+    }
+    // Walks the sandbox, makes every directory and file the server's user can read and write
+    // (a task runs as that user and may have taken its own permissions away) and answers the
+    // bytes. What a container left as another user is given back through a container first.
+    async reclaim(id) {
+        try {
+            return await this.walk(this.root(id));
+        }
+        catch (e) {
+            const code = e.code;
+            if (!this.containers || (code !== 'EPERM' && code !== 'EACCES')) {
+                throw e;
+            }
+            await this.containers.reclaim(this.root(id));
+            return await this.walk(this.root(id));
+        }
+    }
+    // Directories a few at a time and the entries of each together: a `node_modules` holds
+    // tens of thousands of files, and one at a time took seconds for every run.
+    async walk(root) {
+        let bytes = 0;
+        const links = [];
+        let pending = [root];
+        while (pending.length > 0) {
+            const directories = pending.slice(0, WALK_DIRECTORIES);
+            pending = pending.slice(WALK_DIRECTORIES);
+            for (const found of await Promise.all(directories.map((directory) => this.walkDirectory(directory, root)))) {
+                bytes += found.bytes;
+                links.push(...found.links);
+                pending.push(...found.directories);
+            }
+        }
+        return { bytes, links };
+    }
+    async walkDirectory(current, root) {
+        await ensureMode(current, 0o700);
+        const entries = await (0, promises_1.readdir)(current, { withFileTypes: true }).catch((e) => {
+            if (e.code === 'ENOENT' && current !== root) {
+                return [];
+            }
+            throw e;
+        });
+        const directories = [];
+        const links = [];
+        let bytes = 0;
+        for (let start = 0; start < entries.length; start += WALK_ENTRIES) {
+            const sizes = await Promise.all(entries.slice(start, start + WALK_ENTRIES).map(async (entry) => {
+                const path = (0, path_1.join)(current, entry.name);
+                if (entry.isDirectory()) {
+                    directories.push(path);
+                    return 0;
+                }
+                if (entry.isSymbolicLink()) {
+                    links.push(path);
+                }
+                // one lstat for the mode and the size; a link is counted, not followed
+                return (await ensureMode(path, entry.isFile() ? 0o600 : 0))?.size ?? 0;
+            }));
+            bytes += sizes.reduce((sum, size) => sum + size, 0);
+        }
+        return { bytes, directories, links };
+    }
+    async list() {
+        // only a server that never kept a sandbox has no directory; any other error is one
+        const entries = await (0, promises_1.readdir)(this.directory, { withFileTypes: true }).catch((e) => {
+            if (e.code === 'ENOENT') {
+                return [];
+            }
+            throw e;
+        });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => ({ id: entry.name, remove: () => this.removeId(entry.name) }));
+    }
+}
+exports.HostSandboxStorage = HostSandboxStorage;
+// adds the bits of the owner a path lacks and answers what it found; a path that is gone
+// since it was listed is fine
+async function ensureMode(path, bits) {
+    const stats = await (0, promises_1.lstat)(path).catch((e) => {
+        if (e.code === 'ENOENT') {
+            return undefined;
+        }
+        throw e;
+    });
+    if (stats && (stats.mode & bits) !== bits) {
+        await (0, promises_1.chmod)(path, (stats.mode & 0o7777) | bits);
+    }
+    return stats;
+}
+//# sourceMappingURL=sandbox-storage.js.map

package/dist/server/sandboxes-api.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.author = exports.handleSandboxes = void 0;
+const zod_1 = require("zod");
+const http_1 = require("./http");
+const policy_1 = require("./policy");
+const repo_1 = require("./repo");
+const runs_1 = require("./runs");
+const sandbox_files_api_1 = require("./sandbox-files-api");
+const sandboxes_1 = require("./sandboxes");
+const refSchema = zod_1.z.string().min(1).max(200);
+const createSchema = zod_1.z
+    .object({
+    // `host/path`, as a ref run names it
+    repo: zod_1.z.string().transform((value, ctx) => {
+        const repo = (0, repo_1.normalizeRepo)(value);
+        if (!repo) {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'expected a repository like github.com/corp/payments' });
+            return zod_1.z.NEVER;
+        }
+        return repo;
+    }),
+    // a branch: a sandbox never starts from a tag or a commit
+    ref: refSchema,
+})
+    .strict();
+const fetchSchema = zod_1.z.object({ ref: refSchema }).strict();
+// trailers by which a person attests a commit, which a caller could otherwise put in another
+// person's name
+const ATTESTATION = /^\s*(signed-off-by|reviewed-by|acked-by|tested-by)\s*:/im;
+const pushSchema = zod_1.z
+    .object({
+    branch: refSchema,
+    // the message of the commit, as `git commit -m` takes it; it can not sign off for, or
+    // claim the review of, anybody
+    message: zod_1.z
+        .string()
+        .trim()
+        .min(1)
+        .max(10000)
+        .refine((message) => !ATTESTATION.test(message), 'the message may not carry Signed-off-by, Reviewed-by, Acked-by or Tested-by: the server pushes as the caller'),
+})
+    .strict();
+/**
+ * The sandboxes of a caller: checkouts on the server that runs work on.
+ *
+ *   POST   /v1/sandboxes              { repo, ref }  fetch a branch into a new sandbox
+ *   GET    /v1/sandboxes              the caller's sandboxes, their limits and usage
+ *   GET    /v1/sandboxes/<id>         one sandbox
+ *   DELETE /v1/sandboxes/<id>         cancel its runs and remove it
+ *   POST   /v1/sandboxes/<id>/fetch   { ref }  move a sandbox without changes to a branch's commit
+ *   POST   /v1/sandboxes/<id>/push    { branch, message }  commit the changes and push them
+ *   ...    /v1/sandboxes/<id>/tree, files/<path>, search, edits, changes: its files, see
+ *          `handleSandboxFiles`
+ *
+ * A sandbox is its owner's: anybody else gets `404`.
+ */
+async function handleSandboxes(config, sandboxes, repos, log, principal, req, res, url) {
+    const match = /^\/v1\/sandboxes(?:\/([^/]+)(?:\/(fetch|push|tree|search|edits|changes)|\/(files)\/(.+))?)?$/.exec(url.pathname);
+    if (!match) {
+        return false;
+    }
+    const [, id, named, files, encodedPath] = match;
+    const action = named ?? files;
+    const method = req.method;
+    const who = `iss=${principal.iss} sub=${principal.sub}`;
+    try {
+        if (!id) {
+            if (method === 'GET') {
+                const limits = sandboxes.limits;
+                (0, http_1.send)(res, 200, {
+                    sandboxes: sandboxes.list(principal).map((sandbox) => view(sandboxes, sandbox)),
+                    limits: { count: limits.count, bytes: limits.bytes },
+                    used: sandboxes.usage(principal),
+                });
+            }
+            else if (method === 'POST') {
+                const body = parse(createSchema, await (0, http_1.readJson)(req));
+                const refused = (0, policy_1.decideSandbox)((0, policy_1.getGrant)(config.entitlements, principal), body.repo, body.ref, (repo) => repos.readable(repo));
+                if (refused) {
+                    log(`refuse sandbox ${who} repo=${body.repo}: ${refused.error}`);
+                    (0, http_1.send)(res, refused.status, { error: refused.error });
+                    return true;
+                }
+                const sandbox = await sandboxes.create(principal, body.repo, body.ref);
+                log(`sandbox create ${sandbox.id} ${who} repo=${sandbox.repo} commit=${sandbox.commit} bytes=${sandbox.bytes}`);
+                (0, http_1.send)(res, 201, view(sandboxes, sandbox));
+            }
+            else {
+                (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'GET, POST' });
+            }
+            return true;
+        }
+        const sandbox = runs_1.SANDBOX_ID_PATTERN.test(id) ? sandboxes.get(principal, id) : undefined;
+        if (!sandbox) {
+            (0, http_1.send)(res, 404, { error: 'not found' });
+            return true;
+        }
+        if (action && action !== 'fetch' && action !== 'push') {
+            // the caller may have lost the repository, or the sandbox's branch, since they created it
+            const refused = (0, policy_1.decideSandbox)((0, policy_1.getGrant)(config.entitlements, principal), sandbox.repo, sandbox.ref, (repo) => repos.readable(repo));
+            if (refused) {
+                log(`refuse sandbox ${action} ${id} ${who}: ${refused.error}`);
+                (0, http_1.send)(res, refused.status, { error: refused.error });
+                return true;
+            }
+            let path;
+            try {
+                path = encodedPath === undefined ? undefined : decodeURIComponent(encodedPath);
+            }
+            catch {
+                (0, http_1.send)(res, 400, { error: 'the path is not valid percent-encoding' });
+                return true;
+            }
+            await (0, sandbox_files_api_1.handleSandboxFiles)(sandboxes, log, principal, sandbox, action, path, req, res, url);
+            return true;
+        }
+        if (action === 'fetch' || action === 'push') {
+            if (method !== 'POST') {
+                (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'POST' });
+                return true;
+            }
+            const body = action === 'fetch' ? parse(fetchSchema, await (0, http_1.readJson)(req)) : parse(pushSchema, await (0, http_1.readJson)(req));
+            // the caller may have lost the repository or the sandbox's branch since they created the
+            // sandbox, and a fetch needs the new branch
+            const grant = (0, policy_1.getGrant)(config.entitlements, principal);
+            const refused = (0, policy_1.decideSandbox)(grant, sandbox.repo, 'ref' in body ? body.ref : sandbox.ref, (repo) => repos.readable(repo));
+            if (refused) {
+                log(`refuse sandbox ${action} ${id} ${who}: ${refused.error}`);
+                (0, http_1.send)(res, refused.status, { error: refused.error });
+                return true;
+            }
+            if ('branch' in body) {
+                const pushed = await sandboxes.push(principal, id, body.branch, { ...author(principal), message: body.message }, (0, policy_1.sandboxPushBranches)(grant, sandbox.repo));
+                log(`sandbox push ${id} ${who} branch=${body.branch} commit=${pushed.commit}`);
+                (0, http_1.send)(res, 200, { branch: body.branch, commit: pushed.commit, sandbox: view(sandboxes, pushed) });
+                return true;
+            }
+            const fetched = await sandboxes.fetch(principal, id, body.ref);
+            log(`sandbox fetch ${id} ${who} ref=${body.ref} commit=${fetched.commit}`);
+            (0, http_1.send)(res, 200, view(sandboxes, fetched));
+        }
+        else if (method === 'GET') {
+            (0, http_1.send)(res, 200, view(sandboxes, sandbox));
+        }
+        else if (method === 'DELETE') {
+            // a caller who lost the entitlement can still delete what they keep
+            const removed = await sandboxes.remove(principal, id);
+            log(`sandbox delete ${id} ${who} found=${removed}`);
+            removed ? (0, http_1.send)(res, 200, { deleted: id }) : (0, http_1.send)(res, 404, { error: 'not found' });
+        }
+        else {
+            (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'GET, DELETE' });
+        }
+    }
+    catch (e) {
+        if (e instanceof sandboxes_1.SandboxError) {
+            log(`refuse sandbox ${id ?? 'create'} ${who}: ${e.message}`);
+            (0, http_1.send)(res, e.status, { error: e.message });
+            return true;
+        }
+        throw e;
+    }
+    return true;
+}
+exports.handleSandboxes = handleSandboxes;
+function parse(schema, body) {
+    const parsed = schema.safeParse(body);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new sandboxes_1.SandboxError(400, `${issue.path.join('.') || 'request'}: ${issue.message}`);
+    }
+    return parsed.data;
+}
+/**
+ * Who the commit of a push is by: the caller, as their token names them (`name` and
+ * `email`, unless the issuer says the address is not verified), else by their subject at the
+ * host of their issuer. Never what the request says, so a commit can not claim to be
+ * somebody else's.
+ */
+function author(principal) {
+    const clean = (value) => (value ?? '')
+        .replace(/[<>\0\r\n]/g, '')
+        .trim()
+        .slice(0, 200);
+    const name = clean(principal.claims.name) || clean(principal.claims.preferred_username) || clean(principal.sub);
+    // an address the issuer says it did not verify is whatever the caller typed in
+    const claimed = principal.emailVerified === false ? '' : clean(principal.claims.email);
+    if (/^[^\s@]+@[^\s@]+$/.test(claimed)) {
+        return { name, email: claimed };
+    }
+    let host = 'hammerkit';
+    try {
+        host = new URL(principal.iss).hostname || host;
+    }
+    catch {
+        // an issuer that is not a URL keeps the default
+    }
+    const local = principal.sub.replace(/[^A-Za-z0-9._+-]/g, '-').slice(0, 64) || 'sandbox';
+    return { name, email: `${local}@${host}` };
+}
+exports.author = author;
+// What the owner sees: everything but the owner, and the run that holds it.
+function view(sandboxes, sandbox) {
+    const { owner, ...visible } = sandbox;
+    void owner;
+    const run = sandboxes.holder(sandbox.id);
+    return { ...visible, busy: run !== undefined, run: run ?? null };
+}
+//# sourceMappingURL=sandboxes-api.js.map