@magland/mochi 0.3.1 → 0.4.0

package/dist/api/backup.js

@@ -33,17 +33,22 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECRET_FILES = exports.ROOT_FILES = void 0;
+exports.registerBackupRoutes = registerBackupRoutes;
 exports.registerBackupApi = registerBackupApi;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const egress_1 = require("../egress");
 const git_1 = require("../git");
+const githubauth_1 = require("../githubauth");
 const limit_1 = require("../limit");
 const layout_1 = require("../layout");
 const ops_1 = require("../ops");
 const perms_1 = require("../perms");
 const scan_1 = require("../scan");
 const lfsstore_1 = require("../lfsstore");
+const naming_1 = require("../naming");
 const auth_1 = require("./auth");
 // The two routes a backup needs, and nothing else.
 //
@@ -63,20 +68,40 @@ const auth_1 = require("./auth");
 //
 // See docs/backup.md for the client's half and for what a backup does not
 // promise.
-/** The state files at the vault root. Nothing else there belongs to a vault. */
-const ROOT_FILES = ['vault.json', 'config.json', 'runners.json', 'redirects.json', '.secret'];
+/**
+ * The state files at the vault root. Nothing else there belongs to a vault.
+ *
+ * Named from the modules that write them where a module exports the name,
+ * so that a file the server starts writing under a new name is a compile
+ * error here rather than a file the backup quietly leaves behind. That is how
+ * `.github-secret` was lost for a while: config.json kept the client id, so a
+ * restored vault offered GitHub sign-in and failed every attempt at the
+ * token exchange, and `mochi backup verify` had nothing to say about it.
+ */
+exports.ROOT_FILES = [
+    'vault.json',
+    'config.json',
+    'runners.json',
+    'redirects.json',
+    'domains.json',
+    egress_1.EGRESS_FILE,
+    '.secret',
+    githubauth_1.GITHUB_SECRET_FILE,
+];
 /** Which of those `--no-secrets` leaves out. config.json holds no credential. */
-const SECRET_FILES = new Set(['vault.json', 'runners.json', '.secret']);
+exports.SECRET_FILES = new Set(['vault.json', 'runners.json', '.secret', githubauth_1.GITHUB_SECRET_FILE]);
 /**
  * The files inside a bare repository that git's own transport leaves behind. A
  * mirror clone carries objects and refs; it writes its own default description
  * and its own config, so a backup that relied on it alone would lose every
  * repository's description, its `mochi.forkedFrom`, and the `receive.*`
  * settings a repository is created with. mochi.json is the worst of the
- * three to lose: it holds the private flag and the collaborators, so a
+ * set to lose: it holds the private flag and the collaborators, so a
  * restore without it would serve every private repository as public.
+ * site.json is the site's enabled switch, source, and label, which a restore
+ * without it would leave every site dark.
  */
-const REPO_FILES = ['description', 'config', 'mochi.json'];
+const REPO_FILES = ['description', 'config', 'mochi.json', 'site.json'];
 /** What a caller may ask to have left out, as `?exclude=runs,sites`. */
 const EXCLUDABLE = new Set(['runs', 'sites', 'lfs', 'secrets']);
 /** At most this many paths in one fetch, so a request cannot become a whole vault. */
@@ -97,22 +122,16 @@ function isTempName(name) {
  * file: this runs on a 512mb machine, and an LFS object on the volume can be
  * gigabytes, so reading a whole file to hash it would be the one place a backup
  * could take the vault down.
+ *
+ * Streamed rather than read synchronously, because the other thing a backup
+ * could do to the vault is stall it: the client asks for hashes by default,
+ * and a synchronous loop over gigabytes of LFS objects held the event loop,
+ * and so every other request, for as long as the hashing took.
  */
-function sha256File(file) {
+async function sha256File(file) {
     const h = crypto.createHash('sha256');
-    const fd = fs.openSync(file, 'r');
-    try {
-        const buf = Buffer.allocUnsafe(1 << 16);
-        for (;;) {
-            const n = fs.readSync(fd, buf, 0, buf.length, null);
-            if (n === 0)
-                break;
-            h.update(buf.subarray(0, n));
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
+    for await (const chunk of fs.createReadStream(file, { highWaterMark: 1 << 16 }))
+        h.update(chunk);
     return h.digest('hex');
 }
 /**
@@ -157,7 +176,7 @@ function vaultPath(root, p) {
     return path.join(root, ...segments);
 }
 /** One `kind:"file"` line, or null for something that is not a file of the vault. */
-function fileLine(root, abs, opts) {
+async function fileLine(root, abs, opts) {
     let st;
     try {
         st = fs.lstatSync(abs);
@@ -179,7 +198,7 @@ function fileLine(root, abs, opts) {
     };
     if (opts.hash) {
         try {
-            line.sha256 = sha256File(abs);
+            line.sha256 = await sha256File(abs);
         }
         catch {
             return null;
@@ -226,11 +245,17 @@ async function refsDigest(dir) {
     }
     return crypto.createHash('sha256').update(out).update(`HEAD ${head}\n`).digest('hex');
 }
-function registerBackupApi(app, root, limiter, gates) {
-    // The manifest necessarily names vault.json and .secret, and a fetch will
-    // hand over their contents, so nothing narrower than site admin is enough.
-    // A restricted (token-scoped) token is refused by isSiteAdmin whatever its
-    // user's standing, which is the behaviour wanted here.
+/**
+ * The two backup routes, over any layout. See the top of this file for the
+ * protocol; everything here is the same whichever application is serving it.
+ */
+function registerBackupRoutes(app, root, limiter, layout) {
+    const noun = () => naming_1.naming.rootNoun;
+    const enter = layout.enter ?? (async () => () => undefined);
+    // The manifest necessarily names the identity file and .secret, and a fetch
+    // will hand over their contents, so nothing narrower than site admin is
+    // enough. A restricted (token-scoped) token is refused by isSiteAdmin
+    // whatever its user's standing, which is the behaviour wanted here.
     function requireVaultAdmin(req, res) {
         const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
         if (!auth)
@@ -243,7 +268,7 @@ function registerBackupApi(app, root, limiter, gates) {
     }
     function sendBusy(res) {
         res.setHeader('Retry-After', String(limit_1.BUSY_RETRY_SECONDS));
-        (0, auth_1.apiError)(res, 503, 'the vault is busy; try again shortly');
+        (0, auth_1.apiError)(res, 503, `the ${noun()} is busy; try again shortly`);
     }
     function exclusions(req, res) {
         const raw = typeof req.query.exclude === 'string' ? req.query.exclude : '';
@@ -251,9 +276,9 @@ function registerBackupApi(app, root, limiter, gates) {
             .split(',')
             .map((s) => s.trim())
             .filter((s) => s.length > 0);
-        const unknown = names.filter((n) => !EXCLUDABLE.has(n));
+        const unknown = names.filter((n) => !layout.excludable.has(n));
         if (unknown.length) {
-            (0, auth_1.apiError)(res, 400, `unknown exclusion${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}; one of: ${[...EXCLUDABLE].join(', ')}`);
+            (0, auth_1.apiError)(res, 400, `unknown exclusion${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}; one of: ${[...layout.excludable].join(', ')}`);
             return null;
         }
         return new Set(names);
@@ -265,9 +290,9 @@ function registerBackupApi(app, root, limiter, gates) {
         if (!exclude)
             return;
         const opts = { hash: req.query.hash === '1', exclude };
-        // The same gate a file listing and a source archive hold, so that a backup
-        // in progress cannot crowd out a push.
-        const release = await gates.tree.enter();
+        // Gated, where the application has a gate, so that a backup in progress
+        // cannot crowd out the work the gate protects.
+        const release = await enter();
         if (!release) {
             sendBusy(res);
             return;
@@ -276,173 +301,60 @@ function registerBackupApi(app, root, limiter, gates) {
         // A manifest is a walk of a live tree and is never worth a cache.
         res.set('Cache-Control', 'no-store');
         const counts = { files: 0, bytes: 0, repos: 0 };
-        try {
-            // Which LFS backend is live is decided from the environment, so the
-            // client cannot infer it from the vault's files. A vault using a bucket
-            // has objects that are not in the vault at all, and a backup that did not
-            // say so would look complete while missing them.
-            let lfs = 'volume';
+        const emitFile = async (abs) => {
+            const line = await fileLine(root, abs, opts);
+            if (!line)
+                return true;
+            counts.files++;
+            counts.bytes += JSON.parse(line).size;
+            return send(res, line + '\n');
+        };
+        const walkTree = async (dir, skip) => {
+            let entries;
             try {
-                lfs = (0, lfsstore_1.createLfsStore)(root).store.kind === 's3' ? 'bucket' : 'volume';
+                entries = fs.readdirSync(dir, { withFileTypes: true });
             }
             catch {
-                // A partially configured bucket throws at startup, so a serving vault
-                // never reaches this; report the honest "unknown" if it somehow does.
-                lfs = 'unknown';
+                return true;
             }
-            if (!(await send(res, JSON.stringify({ kind: 'vault', lfs, excluded: [...exclude] }) + '\n')))
-                return;
-            for (const name of ROOT_FILES) {
-                if (exclude.has('secrets') && SECRET_FILES.has(name))
+            for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (e.isSymbolicLink() || isTempName(e.name))
                     continue;
-                const line = fileLine(root, path.join(root, name), opts);
-                if (!line)
-                    continue;
-                counts.files++;
-                counts.bytes += JSON.parse(line).size;
-                if (!(await send(res, line + '\n')))
-                    return;
-            }
-            const walkFiles = async (dir) => {
-                let entries;
-                try {
-                    entries = fs.readdirSync(dir, { withFileTypes: true });
-                }
-                catch {
-                    return true;
-                }
-                for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-                    if (e.isSymbolicLink() || isTempName(e.name))
-                        continue;
-                    const abs = path.join(dir, e.name);
-                    if (e.isDirectory()) {
-                        if (!(await walkFiles(abs)))
-                            return false;
+                const abs = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    if (skip?.(e.name, abs))
                         continue;
-                    }
-                    const line = fileLine(root, abs, opts);
-                    if (!line)
-                        continue;
-                    counts.files++;
-                    counts.bytes += JSON.parse(line).size;
-                    if (!(await send(res, line + '\n')))
+                    if (!(await walkTree(abs, skip)))
                         return false;
-                }
-                return true;
-            };
-            let collections;
-            try {
-                collections = fs.readdirSync((0, layout_1.collectionsDir)(root), { withFileTypes: true });
-            }
-            catch {
-                collections = [];
-            }
-            for (const c of collections.sort((a, b) => a.name.localeCompare(b.name))) {
-                if (!c.isDirectory() || c.isSymbolicLink() || !(0, scan_1.isValidName)(c.name))
                     continue;
-                // Whatever the collection keeps of its own, beside its repositories.
-                // There is nothing there today; it is walked as ordinary files so that
-                // the first thing put there is backed up without this being revisited.
-                let ownEntries;
-                try {
-                    ownEntries = fs.readdirSync((0, layout_1.collectionDir)(root, c.name), { withFileTypes: true });
-                }
-                catch {
-                    ownEntries = [];
                 }
-                for (const e of ownEntries.sort((a, b) => a.name.localeCompare(b.name))) {
-                    if (e.name === layout_1.REPOS_DIR || e.isSymbolicLink() || isTempName(e.name))
-                        continue;
-                    const abs = path.join((0, layout_1.collectionDir)(root, c.name), e.name);
-                    if (e.isDirectory()) {
-                        if (!(await walkFiles(abs)))
-                            return;
-                        continue;
-                    }
-                    const line = fileLine(root, abs, opts);
-                    if (!line)
-                        continue;
-                    counts.files++;
-                    counts.bytes += JSON.parse(line).size;
-                    if (!(await send(res, line + '\n')))
-                        return;
-                }
-                const repos = (0, layout_1.reposDir)(root, c.name);
-                let entries;
-                try {
-                    entries = fs.readdirSync(repos, { withFileTypes: true });
-                }
-                catch {
+                if (!(await emitFile(abs)))
+                    return false;
+            }
+            return true;
+        };
+        const writer = {
+            file: emitFile,
+            tree: walkTree,
+            line: async (entry) => {
+                if (entry.kind === 'repo')
+                    counts.repos++;
+                return send(res, JSON.stringify(entry) + '\n');
+            },
+        };
+        try {
+            // The header's kind is the protocol's name for the root directory, and
+            // stays "vault" whatever the application calls it: a client reads it.
+            if (!(await send(res, JSON.stringify({ kind: 'vault', ...layout.header(), excluded: [...exclude] }) + '\n')))
+                return;
+            for (const name of layout.rootFiles) {
+                if (exclude.has('secrets') && layout.secretFiles.has(name))
                     continue;
-                }
-                for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-                    if (e.isSymbolicLink() || isTempName(e.name))
-                        continue;
-                    const abs = path.join(repos, e.name);
-                    const rel = `${layout_1.COLLECTIONS_DIR}/${c.name}/${layout_1.REPOS_DIR}/${e.name}`;
-                    if (!e.isDirectory()) {
-                        const line = fileLine(root, abs, opts);
-                        if (!line)
-                            continue;
-                        counts.files++;
-                        counts.bytes += JSON.parse(line).size;
-                        if (!(await send(res, line + '\n')))
-                            return;
-                        continue;
-                    }
-                    // A repository's contents are not enumerated: git is their
-                    // transport, and listing a hundred thousand loose objects as files
-                    // would be both enormous and the wrong way to move them.
-                    if ((0, scan_1.isValidName)(e.name) && (0, scan_1.isBareRepo)(abs)) {
-                        let refs;
-                        try {
-                            refs = await refsDigest(abs);
-                        }
-                        catch {
-                            // A directory that looks like a repository but cannot be read is
-                            // reported as nothing rather than failing the whole manifest.
-                            continue;
-                        }
-                        counts.repos++;
-                        const line = JSON.stringify({
-                            kind: 'repo',
-                            path: rel,
-                            collection: c.name,
-                            repo: e.name.replace(/\.git$/, ''),
-                            refs,
-                            packed: await repoBytes(abs),
-                        });
-                        if (!(await send(res, line + '\n')))
-                            return;
-                        // A few files inside the repository are named all the same,
-                        // because a mirror clone does not carry them and they are not git
-                        // data: the description, which every listing shows; the config,
-                        // which holds the fork parent and the receive protections a
-                        // repository was created with; and mochi.json, which holds
-                        // the private flag and the collaborators. Restoring a vault whose
-                        // private repositories had come back public would be far worse
-                        // than a poor restore.
-                        for (const inside of REPO_FILES) {
-                            const fileEntry = fileLine(root, path.join(abs, inside), opts);
-                            if (!fileEntry)
-                                continue;
-                            counts.files++;
-                            counts.bytes += JSON.parse(fileEntry).size;
-                            if (!(await send(res, fileEntry + '\n')))
-                                return;
-                        }
-                        continue;
-                    }
-                    if (exclude.has('runs') && e.name.endsWith('.runs'))
-                        continue;
-                    if (exclude.has('sites') && e.name.endsWith('.site'))
-                        continue;
-                    if (exclude.has('lfs') && e.name.endsWith('.lfs'))
-                        continue;
-                    if (!(await walkFiles(abs)))
-                        return;
-                }
+                if (!(await emitFile(path.join(root, name))))
+                    return;
             }
+            if (!(await layout.walk(writer, exclude)))
+                return;
             await send(res, JSON.stringify({ kind: 'end', ...counts }) + '\n');
             res.end();
         }
@@ -472,7 +384,7 @@ function registerBackupApi(app, root, limiter, gates) {
         const body = (req.body ?? {});
         const paths = body.paths;
         if (!Array.isArray(paths) || paths.length === 0) {
-            (0, auth_1.apiError)(res, 400, '"paths" must be a non-empty list of vault-relative paths');
+            (0, auth_1.apiError)(res, 400, `"paths" must be a non-empty list of ${noun()}-relative paths`);
             return;
         }
         if (paths.length > MAX_FETCH_PATHS) {
@@ -483,7 +395,7 @@ function registerBackupApi(app, root, limiter, gates) {
         for (const p of paths) {
             const abs = vaultPath(root, p);
             if (!abs) {
-                (0, auth_1.apiError)(res, 400, `not a path inside the vault: ${typeof p === 'string' ? p : typeof p}`);
+                (0, auth_1.apiError)(res, 400, `not a path inside the ${noun()}: ${typeof p === 'string' ? p : typeof p}`);
                 return;
             }
             absolute.push(abs);
@@ -493,7 +405,7 @@ function registerBackupApi(app, root, limiter, gates) {
             rootReal = fs.realpathSync(root);
         }
         catch {
-            (0, auth_1.apiError)(res, 500, 'the vault directory could not be read');
+            (0, auth_1.apiError)(res, 500, `the ${noun()} directory could not be read`);
             return;
         }
         // Sized before anything is sent, so that a request over the cap is a 400
@@ -512,7 +424,7 @@ function registerBackupApi(app, root, limiter, gates) {
             (0, auth_1.apiError)(res, 400, `the paths named come to ${total} bytes, over the ${MAX_FETCH_BYTES} byte limit for one request; ask for fewer`);
             return;
         }
-        const release = await gates.tree.enter();
+        const release = await enter();
         if (!release) {
             sendBusy(res);
             return;
@@ -596,3 +508,126 @@ function registerBackupApi(app, root, limiter, gates) {
         }
     });
 }
+/** Mochi's layout: the vault's state files, then each collection and its repositories. */
+function vaultLayout(root, gates) {
+    return {
+        rootFiles: exports.ROOT_FILES,
+        secretFiles: exports.SECRET_FILES,
+        excludable: EXCLUDABLE,
+        enter: () => gates.tree.enter(),
+        header() {
+            // Which LFS backend is live is decided from the environment, so the
+            // client cannot infer it from the vault's files. A vault using a bucket
+            // has objects that are not in the vault at all, and a backup that did not
+            // say so would look complete while missing them.
+            let lfs = 'volume';
+            try {
+                lfs = (0, lfsstore_1.createLfsStore)(root).store.kind === 's3' ? 'bucket' : 'volume';
+            }
+            catch {
+                // A partially configured bucket throws at startup, so a serving vault
+                // never reaches this; report the honest "unknown" if it somehow does.
+                lfs = 'unknown';
+            }
+            return { lfs };
+        },
+        async walk(w, exclude) {
+            let collections;
+            try {
+                collections = fs.readdirSync((0, layout_1.collectionsDir)(root), { withFileTypes: true });
+            }
+            catch {
+                collections = [];
+            }
+            for (const c of collections.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (!c.isDirectory() || c.isSymbolicLink() || !(0, scan_1.isValidName)(c.name))
+                    continue;
+                // Whatever the collection keeps of its own, beside its repositories.
+                // There is nothing there today; it is walked as ordinary files so that
+                // the first thing put there is backed up without this being revisited.
+                let ownEntries;
+                try {
+                    ownEntries = fs.readdirSync((0, layout_1.collectionDir)(root, c.name), { withFileTypes: true });
+                }
+                catch {
+                    ownEntries = [];
+                }
+                for (const e of ownEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (e.name === layout_1.REPOS_DIR || e.isSymbolicLink() || isTempName(e.name))
+                        continue;
+                    const abs = path.join((0, layout_1.collectionDir)(root, c.name), e.name);
+                    if (!(await (e.isDirectory() ? w.tree(abs) : w.file(abs))))
+                        return false;
+                }
+                const repos = (0, layout_1.reposDir)(root, c.name);
+                let entries;
+                try {
+                    entries = fs.readdirSync(repos, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (e.isSymbolicLink() || isTempName(e.name))
+                        continue;
+                    const abs = path.join(repos, e.name);
+                    const rel = `${layout_1.COLLECTIONS_DIR}/${c.name}/${layout_1.REPOS_DIR}/${e.name}`;
+                    if (!e.isDirectory()) {
+                        if (!(await w.file(abs)))
+                            return false;
+                        continue;
+                    }
+                    // A repository's contents are not enumerated: git is their
+                    // transport, and listing a hundred thousand loose objects as files
+                    // would be both enormous and the wrong way to move them.
+                    if ((0, scan_1.isValidName)(e.name) && (0, scan_1.isBareRepo)(abs)) {
+                        let refs;
+                        try {
+                            refs = await refsDigest(abs);
+                        }
+                        catch {
+                            // A directory that looks like a repository but cannot be read is
+                            // reported as nothing rather than failing the whole manifest.
+                            continue;
+                        }
+                        const ok = await w.line({
+                            kind: 'repo',
+                            path: rel,
+                            collection: c.name,
+                            repo: e.name.replace(/\.git$/, ''),
+                            refs,
+                            packed: await repoBytes(abs),
+                        });
+                        if (!ok)
+                            return false;
+                        // A few files inside the repository are named all the same,
+                        // because a mirror clone does not carry them and they are not git
+                        // data: the description, which every listing shows; the config,
+                        // which holds the fork parent and the receive protections a
+                        // repository was created with; and mochi.json, which holds
+                        // the private flag and the collaborators. Restoring a vault whose
+                        // private repositories had come back public would be far worse
+                        // than a poor restore.
+                        for (const inside of REPO_FILES) {
+                            if (!(await w.file(path.join(abs, inside))))
+                                return false;
+                        }
+                        continue;
+                    }
+                    if (exclude.has('runs') && e.name.endsWith('.runs'))
+                        continue;
+                    if (exclude.has('sites') && e.name.endsWith('.site'))
+                        continue;
+                    if (exclude.has('lfs') && e.name.endsWith('.lfs'))
+                        continue;
+                    if (!(await w.tree(abs)))
+                        return false;
+                }
+            }
+            return true;
+        },
+    };
+}
+function registerBackupApi(app, root, limiter, gates) {
+    registerBackupRoutes(app, root, limiter, vaultLayout(root, gates));
+}

package/dist/api/contents.js

@@ -35,6 +35,8 @@ const MAX_COMMITS = 250;
 const MAX_LISTED_PATHS = 20000;
 /** The same ceiling the editor applies, so that the two interfaces agree on what is too big. */
 const MAX_FILE_BYTES = 1024 * 1024;
+/** Raw files over this size are streamed from git rather than read into memory first. */
+const STREAM_ABOVE = 8 * 1024 * 1024;
 function registerContentsApi(app, root, limiter, gates) {
     // A directory listing. ?commits=1 adds the last commit per entry, which costs
     // one git log per entry; it is off by default because an API caller asking for
@@ -92,12 +94,20 @@ function registerContentsApi(app, root, limiter, gates) {
             (0, auth_1.apiError)(res, 400, 'that is not a usable path');
             return;
         }
+        // The size before the bytes: a file over the limit is refused from its
+        // size alone rather than read whole to be measured. A pointer is a few
+        // hundred bytes and is never the file refused here.
+        const info = await found.repo.blobInfo(ref, filePath);
+        if (!info) {
+            (0, auth_1.apiError)(res, 404, `no file at ${filePath} in ${ref}`);
+            return;
+        }
+        if (info.size > MAX_FILE_BYTES) {
+            (0, auth_1.apiError)(res, 413, `${filePath} is larger than ${MAX_FILE_BYTES} bytes; fetch it from the raw route or a clone`);
+            return;
+        }
         let buf;
         try {
-            if ((await found.repo.entryType(ref, filePath)) !== 'blob') {
-                (0, auth_1.apiError)(res, 404, `no file at ${filePath} in ${ref}`);
-                return;
-            }
             buf = await found.repo.catBlob(ref, filePath);
         }
         catch {
@@ -142,20 +152,29 @@ function registerContentsApi(app, root, limiter, gates) {
             (0, auth_1.apiError)(res, 400, 'ask for a file as /raw/<path>?ref=<ref>');
             return;
         }
+        const info = await found.repo.blobInfo(ref, filePath);
+        if (!info) {
+            (0, auth_1.apiError)(res, 404, `no file at ${filePath} in ${ref}`);
+            return;
+        }
+        res.setHeader('Content-Security-Policy', 'sandbox');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        // Large files go from git to the socket without being held here, as a
+        // download, since telling text from binary needs the bytes in hand.
+        if (info.size > STREAM_ABOVE) {
+            res.setHeader('Content-Length', String(info.size));
+            res.type('application/octet-stream');
+            await found.repo.streamBlob(ref, filePath, res);
+            return;
+        }
         let buf;
         try {
-            if ((await found.repo.entryType(ref, filePath)) !== 'blob') {
-                (0, auth_1.apiError)(res, 404, `no file at ${filePath} in ${ref}`);
-                return;
-            }
             buf = await found.repo.catBlob(ref, filePath);
         }
         catch {
             (0, auth_1.apiError)(res, 404, `no file at ${filePath} in ${ref}`);
             return;
         }
-        res.setHeader('Content-Security-Policy', 'sandbox');
-        res.setHeader('X-Content-Type-Options', 'nosniff');
         res.type((0, render_1.isBinary)(buf) ? 'application/octet-stream' : 'text/plain; charset=utf-8');
         res.send(buf);
     });
@@ -174,18 +193,29 @@ function registerContentsApi(app, root, limiter, gates) {
             return;
         }
         const limit = (0, auth_1.limitParam)(req.query.limit, 30, MAX_COMMITS);
-        try {
-            const commits = await found.repo.log(ref, 0, limit, filePath || undefined);
-            res.json({ ref, commits });
-        }
-        catch {
+        // log() answers an unknown ref with an empty list rather than an error,
+        // because the web's tree page wants exactly that for an empty repository.
+        // The API is asked a question and should say no: a ref that does not
+        // resolve is 404, and an empty history is 200 with nothing in it.
+        if (!(await found.repo.resolve(ref))) {
             (0, auth_1.apiError)(res, 404, `ref ${ref} not found`);
+            return;
         }
+        const commits = await found.repo.log(ref, 0, limit, filePath || undefined);
+        res.json({ ref, commits });
     });
+    // A commit id, possibly abbreviated, as the web route takes it. Checked
+    // before it reaches git: an argument beginning with a dash is an option to
+    // git, and `--output=<path>` would write the listing into the vault.
+    const COMMIT_ID = /^[0-9a-f]{4,40}$/i;
     app.get('/api/repos/:collection/:repo/commits/:sha', async (req, res) => {
         const found = (0, auth_1.requireRepo)(root, limiter, req, res);
         if (!found)
             return;
+        if (!COMMIT_ID.test(req.params.sha)) {
+            (0, auth_1.apiError)(res, 404, `no commit ${req.params.sha}`);
+            return;
+        }
         const detail = await found.repo.commit(req.params.sha);
         if (!detail) {
             (0, auth_1.apiError)(res, 404, `no commit ${req.params.sha}`);
@@ -197,7 +227,7 @@ function registerContentsApi(app, root, limiter, gates) {
         const found = (0, auth_1.requireRepo)(root, limiter, req, res);
         if (!found)
             return;
-        if (!(await found.repo.commit(req.params.sha))) {
+        if (!COMMIT_ID.test(req.params.sha) || !(await found.repo.commit(req.params.sha))) {
             (0, auth_1.apiError)(res, 404, `no commit ${req.params.sha}`);
             return;
         }