@magland/mochi 0.3.1

package/dist/api/write.js

@@ -0,0 +1,518 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWriteApi = registerWriteApi;
+const trigger_1 = require("../ci/trigger");
+const git_1 = require("../git");
+const ops_1 = require("../ops");
+const perms_1 = require("../perms");
+const scan_1 = require("../scan");
+const vault_1 = require("../vault");
+const auth_1 = require("./auth");
+function writeBody(body, fallbackMessage) {
+    const branch = (0, auth_1.stringField)(body, 'branch');
+    if (branch === null || !(0, git_1.isValidRefName)(branch))
+        return '"branch" is required and must be a usable branch name';
+    const newBranch = (0, auth_1.stringField)(body, 'newBranch');
+    if (newBranch !== null && !(0, git_1.isValidRefName)(newBranch))
+        return '"newBranch" is not a usable branch name';
+    const expectedSha = (0, auth_1.stringField)(body, 'expectedSha');
+    return {
+        branch,
+        message: (0, auth_1.stringField)(body, 'message')?.trim() || fallbackMessage,
+        expectedSha,
+        newBranch,
+    };
+}
+/**
+ * Decode a file's content. base64 for anything that is not text, which is how a
+ * caller sends an image or a fixture through a JSON body.
+ */
+function decodeContent(body, res) {
+    const content = (0, auth_1.stringField)(body, 'content');
+    if (content === null) {
+        (0, auth_1.apiError)(res, 400, '"content" is required');
+        return null;
+    }
+    const encoding = (0, auth_1.stringField)(body, 'encoding') ?? 'utf-8';
+    if (encoding !== 'utf-8' && encoding !== 'base64') {
+        (0, auth_1.apiError)(res, 400, '"encoding" must be "utf-8" or "base64"');
+        return null;
+    }
+    const buf = Buffer.from(content, encoding === 'base64' ? 'base64' : 'utf8');
+    if (buf.length > ops_1.MAX_EDIT_SIZE) {
+        (0, auth_1.apiError)(res, 413, `a single file may be at most ${ops_1.MAX_EDIT_SIZE} bytes; push anything larger, or use Git LFS`);
+        return null;
+    }
+    return buf;
+}
+/** The wildcard tail of a route path. */
+function tail(req) {
+    return req.params['0'] ?? '';
+}
+/**
+ * The branch tip the write will be guarded against. When the caller supplied an
+ * expectedSha it is theirs; otherwise the write is unconditional and takes
+ * whatever the branch is at now, which is what an unguarded write means.
+ */
+async function baseFor(ctx, body) {
+    if (body.expectedSha) {
+        // A sha that names no commit here cannot be what the caller last saw, so it
+        // is refused as a stale expectation rather than handed to git, which would
+        // fail in a way that reads as the server breaking.
+        if (!(await ctx.repo.resolve(body.expectedSha))) {
+            throw new ops_1.OpError(`no commit ${body.expectedSha} in this repository; re-read the file and try again`, 'conflict');
+        }
+        return body.expectedSha;
+    }
+    const branches = await ctx.repo.listRefs('heads');
+    return branches.find((b) => b.name === body.branch)?.sha ?? null;
+}
+function reportWriteError(res, e) {
+    // A branch that could not be made is not a file that could not be written.
+    if (e instanceof ops_1.NewBranchError) {
+        (0, auth_1.apiError)(res, (0, ops_1.opErrorStatus)(e.kind), e.message);
+        return;
+    }
+    (0, auth_1.sendOpError)(res, e, 'the write failed');
+}
+function registerWriteApi(app, root, limiter, lfs = null, engine) {
+    // As in registerWebOps: one context for the operations that move or remove a
+    // repository, so both surfaces carry the same things across.
+    const repoCtx = { lfs: lfs?.store, runs: engine };
+    const fire = (ctx, branch, before, after, actor) => (0, trigger_1.firePush)(root, engine, { collection: ctx.repo.collection, name: ctx.repo.name }, branch, before, after, actor.username);
+    // ---- files ----
+    // PUT creates or updates, because a caller that has read a file and means to
+    // change it should not have to know which of the two it is doing. The action
+    // kind is decided from whether the path is there now.
+    app.put('/api/repos/:collection/:repo/contents/*', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const filePath = tail(req);
+        if (filePath === '' || !(0, git_1.isValidRepoPath)(filePath)) {
+            (0, auth_1.apiError)(res, 400, 'that is not a usable path');
+            return;
+        }
+        const body = (0, auth_1.bodyOf)(req);
+        const parsed = writeBody(body, `Update ${filePath.split('/').pop()}`);
+        if (typeof parsed === 'string') {
+            (0, auth_1.apiError)(res, 400, parsed);
+            return;
+        }
+        const content = decodeContent(body, res);
+        if (!content)
+            return;
+        try {
+            const base = await baseFor(ctx, parsed);
+            const exists = base !== null && (await ctx.repo.entryType(base, filePath)) === 'blob';
+            const action = exists ? { kind: 'edit', content } : { kind: 'create', content };
+            const written = await (0, ops_1.writeFile)(ctx.repo.dir, {
+                branch: parsed.branch,
+                newBranch: parsed.newBranch,
+                filePath,
+                message: parsed.message,
+                author: { name: ctx.actor.username, email: ctx.actor.email },
+                expectedHead: base,
+                action,
+            });
+            fire(ctx, written.branch, written.before, written.sha, ctx.actor);
+            res.json({ branch: written.branch, sha: written.sha, path: filePath, created: !exists });
+        }
+        catch (e) {
+            reportWriteError(res, e);
+        }
+    });
+    app.delete('/api/repos/:collection/:repo/contents/*', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const filePath = tail(req);
+        if (filePath === '' || !(0, git_1.isValidRepoPath)(filePath)) {
+            (0, auth_1.apiError)(res, 400, 'that is not a usable path');
+            return;
+        }
+        const body = (0, auth_1.bodyOf)(req);
+        const parsed = writeBody(body, `Delete ${filePath.split('/').pop()}`);
+        if (typeof parsed === 'string') {
+            (0, auth_1.apiError)(res, 400, parsed);
+            return;
+        }
+        try {
+            const written = await (0, ops_1.writeFile)(ctx.repo.dir, {
+                branch: parsed.branch,
+                newBranch: parsed.newBranch,
+                filePath,
+                message: parsed.message,
+                author: { name: ctx.actor.username, email: ctx.actor.email },
+                expectedHead: await baseFor(ctx, parsed),
+                action: { kind: 'delete' },
+            });
+            fire(ctx, written.branch, written.before, written.sha, ctx.actor);
+            res.json({ branch: written.branch, sha: written.sha, path: filePath, deleted: true });
+        }
+        catch (e) {
+            reportWriteError(res, e);
+        }
+    });
+    // Several files as one commit, which is what a caller changing three files as
+    // one logical edit wants, and what the upload route already does underneath.
+    app.post('/api/repos/:collection/:repo/commits', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const parsed = writeBody(body, 'Update files');
+        if (typeof parsed === 'string') {
+            (0, auth_1.apiError)(res, 400, parsed);
+            return;
+        }
+        const rawFiles = body.files;
+        if (!Array.isArray(rawFiles) || rawFiles.length === 0) {
+            (0, auth_1.apiError)(res, 400, '"files" must be a non-empty list');
+            return;
+        }
+        const writes = [];
+        const removals = [];
+        let total = 0;
+        for (const raw of rawFiles) {
+            if (typeof raw !== 'object' || raw === null) {
+                (0, auth_1.apiError)(res, 400, 'each entry of "files" must be an object');
+                return;
+            }
+            const entry = raw;
+            const filePath = (0, auth_1.stringField)(entry, 'path');
+            if (filePath === null || filePath === '' || !(0, git_1.isValidRepoPath)(filePath)) {
+                (0, auth_1.apiError)(res, 400, `"${String(entry.path)}" is not a usable path`);
+                return;
+            }
+            if (entry.delete === true) {
+                removals.push(filePath);
+                continue;
+            }
+            const content = decodeContent(entry, res);
+            if (!content)
+                return;
+            total += content.length;
+            if (total > ops_1.MAX_UPLOAD_SIZE) {
+                (0, auth_1.apiError)(res, 413, `one commit may carry at most ${ops_1.MAX_UPLOAD_SIZE} bytes; push anything larger`);
+                return;
+            }
+            writes.push({ path: filePath, content });
+        }
+        try {
+            let branch = parsed.branch;
+            const base = await baseFor(ctx, parsed);
+            if (parsed.newBranch) {
+                if (base === null) {
+                    (0, auth_1.apiError)(res, 400, 'there is nothing to branch from yet; commit to this branch first');
+                    return;
+                }
+                await (0, ops_1.createBranch)(ctx.repo.dir, parsed.newBranch, base);
+                branch = parsed.newBranch;
+            }
+            const sha = await (0, ops_1.commitFiles)(ctx.repo.dir, {
+                branch,
+                message: parsed.message,
+                author: { name: ctx.actor.username, email: ctx.actor.email },
+                expectedHead: base,
+                files: writes,
+                removals,
+            });
+            fire(ctx, branch, base, sha, ctx.actor);
+            res.json({ branch, sha, files: writes.length, removed: removals.length });
+        }
+        catch (e) {
+            reportWriteError(res, e);
+        }
+    });
+    // ---- branches and tags ----
+    //
+    // Deletion takes the name as a wildcard, because a ref name may contain
+    // slashes and one path segment could not hold `release/1.0`.
+    app.post('/api/repos/:collection/:repo/branches', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const name = (0, auth_1.stringField)(body, 'name');
+        const from = (0, auth_1.stringField)(body, 'from');
+        if (name === null || from === null) {
+            (0, auth_1.apiError)(res, 400, '"name" and "from" are required');
+            return;
+        }
+        try {
+            await (0, ops_1.createBranch)(ctx.repo.dir, name, from);
+            const sha = await ctx.repo.resolve(name);
+            res.status(201).json({ name, sha });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not create the branch');
+        }
+    });
+    app.delete('/api/repos/:collection/:repo/branches/*', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const name = tail(req);
+        if (!(0, git_1.isValidRefName)(name)) {
+            (0, auth_1.apiError)(res, 400, 'that is not a usable branch name');
+            return;
+        }
+        try {
+            await (0, ops_1.deleteBranch)(ctx.repo.dir, name);
+            res.json({ deleted: name });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not delete the branch');
+        }
+    });
+    app.post('/api/repos/:collection/:repo/tags', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const name = (0, auth_1.stringField)(body, 'name');
+        const at = (0, auth_1.stringField)(body, 'at');
+        if (name === null || at === null) {
+            (0, auth_1.apiError)(res, 400, '"name" and "at" are required');
+            return;
+        }
+        try {
+            await (0, ops_1.createTag)(ctx.repo.dir, name, at);
+            res.status(201).json({ name, sha: await ctx.repo.resolve(name) });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not create the tag');
+        }
+    });
+    app.delete('/api/repos/:collection/:repo/tags/*', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const name = tail(req);
+        if (!(0, git_1.isValidRefName)(name)) {
+            (0, auth_1.apiError)(res, 400, 'that is not a usable tag name');
+            return;
+        }
+        try {
+            await (0, ops_1.deleteTag)(ctx.repo.dir, name);
+            res.json({ deleted: name });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not delete the tag');
+        }
+    });
+    // ---- the repository itself ----
+    app.post('/api/repos', async (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const collection = (0, auth_1.stringField)(body, 'collection');
+        const name = (0, auth_1.stringField)(body, 'name');
+        if (collection === null || name === null || !(0, scan_1.isValidName)(collection) || !(0, scan_1.isValidName)(name)) {
+            (0, auth_1.apiError)(res, 400, 'a valid "collection" and "name" are required (letters, digits, dot, underscore, dash)');
+            return;
+        }
+        const reserved = (0, scan_1.reservedRepoSuffix)(name);
+        if (reserved) {
+            (0, auth_1.apiError)(res, 400, `a repository name may not end in ${reserved}, which is reserved for the directories a repository keeps beside it`);
+            return;
+        }
+        if (!(0, perms_1.canCreateRepo)(root, auth, collection, name)) {
+            (0, auth_1.apiError)(res, 403, `you are not allowed to create repositories in ${collection}`);
+            return;
+        }
+        if ((0, scan_1.findRepo)(root, collection, name)) {
+            (0, auth_1.apiError)(res, 409, `repository ${collection}/${name} already exists`);
+            return;
+        }
+        if (body.private !== undefined && typeof body.private !== 'boolean') {
+            (0, auth_1.apiError)(res, 400, '"private" must be a boolean');
+            return;
+        }
+        const host = (req.get('host') ?? 'localhost').replace(/:\d+$/, '');
+        try {
+            const created = await (0, ops_1.createRepoWithReadme)(root, collection, name, {
+                description: (0, auth_1.stringField)(body, 'description') ?? '',
+                readme: body.initReadme === true,
+                private: body.private === true,
+                author: { name: auth.username, email: `${auth.username}@noreply.${host}` },
+            });
+            if (created.sha) {
+                (0, trigger_1.firePush)(root, engine, { collection, name }, 'main', null, created.sha, auth.username);
+            }
+            res.status(201).json({ collection, name, created: true, private: body.private === true, sha: created.sha });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not create the repository');
+        }
+    });
+    app.post('/api/repos/:collection/:repo/fork', async (req, res) => {
+        // Reading the source is what forking needs; creating the fork needs
+        // permission to create where it lands, which is checked below rather than
+        // here.
+        const source = (0, auth_1.requireRepo)(root, limiter, req, res);
+        if (!source)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const collection = (0, auth_1.stringField)(body, 'collection');
+        const name = (0, auth_1.stringField)(body, 'name') ?? source.repo.name;
+        if (collection === null || !(0, scan_1.isValidName)(collection) || !(0, scan_1.isValidName)(name)) {
+            (0, auth_1.apiError)(res, 400, 'a valid "collection" is required');
+            return;
+        }
+        if (!(0, perms_1.canCreateRepo)(root, source.auth, collection, name)) {
+            (0, auth_1.apiError)(res, 403, `you are not allowed to create repositories in ${collection}`);
+            return;
+        }
+        try {
+            await (0, ops_1.forkRepo)(root, source.repo.collection, source.repo.name, collection, name);
+            res.status(201).json({ collection, name, forkedFrom: { collection: source.repo.collection, repo: source.repo.name } });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not fork the repository');
+        }
+    });
+    app.patch('/api/repos/:collection/:repo', async (req, res) => {
+        const ctx = (0, auth_1.requirePush)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const description = (0, auth_1.stringField)(body, 'description');
+        const defaultBranch = (0, auth_1.stringField)(body, 'defaultBranch');
+        const priv = body.private;
+        if (priv !== undefined && typeof priv !== 'boolean') {
+            (0, auth_1.apiError)(res, 400, '"private" must be a boolean');
+            return;
+        }
+        if (description === null && defaultBranch === null && priv === undefined) {
+            (0, auth_1.apiError)(res, 400, 'nothing to change; provide "description", "defaultBranch", and/or "private"');
+            return;
+        }
+        // Visibility is the one setting here that takes the admin role rather than
+        // write: publishing a repository, or withdrawing one from everybody who
+        // could see it, is the repository's own business the way deleting it is.
+        if (priv !== undefined && !(0, perms_1.canAdminRepo)(root, ctx.auth, ctx.repo)) {
+            (0, auth_1.apiError)(res, 403, `changing visibility needs the admin role on ${ctx.repo.collection}/${ctx.repo.name}`);
+            return;
+        }
+        try {
+            if (description !== null)
+                (0, ops_1.setDescription)(ctx.repo.dir, description);
+            if (defaultBranch !== null)
+                await (0, ops_1.setDefaultBranch)(ctx.repo.dir, defaultBranch);
+            if (priv !== undefined)
+                (0, perms_1.setRepoPrivate)(ctx.repo.dir, priv);
+            const branches = await ctx.repo.listRefs('heads');
+            res.json({
+                collection: ctx.repo.collection,
+                name: ctx.repo.name,
+                defaultBranch: await ctx.repo.defaultBranch(branches),
+                private: (0, perms_1.repoIsPrivate)(ctx.repo.dir),
+                changed: true,
+            });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not change the settings');
+        }
+    });
+    // Renaming and deleting are the two operations the web puts behind a typed
+    // confirmation, so they take the admin role on the repository rather than write.
+    app.post('/api/repos/:collection/:repo/rename', async (req, res) => {
+        const ctx = (0, auth_1.requireRepoAdmin)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const name = (0, auth_1.stringField)(body, 'name') ?? ctx.repo.name;
+        const collection = (0, auth_1.stringField)(body, 'collection') ?? ctx.repo.collection;
+        if (!(0, scan_1.isValidName)(name) || !(0, scan_1.isValidName)(collection)) {
+            (0, auth_1.apiError)(res, 400, '"name" and "collection" must be usable names');
+            return;
+        }
+        // The same rule the web settings page applies: admin on what is moving
+        // (which requireRepoAdmin has established), and for a move to another
+        // collection, permission to create over there.
+        const blocker = (0, perms_1.repoRenameBlocker)(root, ctx.auth, ctx.repo, collection, name);
+        if (blocker) {
+            (0, auth_1.apiError)(res, 403, `renaming this repository needs ${blocker}`);
+            return;
+        }
+        try {
+            await (0, ops_1.renameRepo)(root, ctx.repo.collection, ctx.repo.name, collection, name, repoCtx);
+            res.json({ collection, name, renamed: true });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not rename the repository');
+        }
+    });
+    // ?confirm= is the API's equivalent of the web's typed confirmation. It costs
+    // nothing and it makes an accidental DELETE from a loop over a listing
+    // impossible.
+    app.delete('/api/repos/:collection/:repo', async (req, res) => {
+        const ctx = (0, auth_1.requireRepoAdmin)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const full = `${ctx.repo.collection}/${ctx.repo.name}`;
+        if (String(req.query.confirm ?? '') !== full) {
+            (0, auth_1.apiError)(res, 400, `to delete this repository and everything beside it, send ?confirm=${full}`);
+            return;
+        }
+        try {
+            await (0, ops_1.deleteRepo)(root, ctx.repo.collection, ctx.repo.name, repoCtx);
+            res.json({ deleted: full });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not delete the repository');
+        }
+    });
+    // ---- collaborators ----
+    // All three take the admin role on the repository: who may see or write a
+    // repository is decided by the people who administer it, and the list of
+    // who those people are is itself not public.
+    app.get('/api/repos/:collection/:repo/collaborators', (req, res) => {
+        const ctx = (0, auth_1.requireRepoAdmin)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const access = (0, perms_1.repoAccess)(ctx.repo.dir);
+        res.json({
+            collaborators: Object.entries(access.collaborators).map(([username, role]) => ({ username, role })),
+            owners: (0, perms_1.collectionOwners)(root, ctx.repo.collection),
+            private: access.private,
+        });
+    });
+    app.put('/api/repos/:collection/:repo/collaborators/:user', (req, res) => {
+        const ctx = (0, auth_1.requireRepoAdmin)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const username = req.params.user;
+        const role = (0, auth_1.stringField)((0, auth_1.bodyOf)(req), 'role') ?? 'write';
+        if (role !== 'read' && role !== 'write' && role !== 'admin') {
+            (0, auth_1.apiError)(res, 400, '"role" must be "read", "write", or "admin"');
+            return;
+        }
+        // Only a user the vault knows: a collaborator entry for a name nobody
+        // holds grants nothing today and, worse, would grant everything it says
+        // to whoever is given the name later.
+        const state = (0, vault_1.loadVault)(root);
+        if (state.status !== 'ok' || !state.vault.users[username]) {
+            (0, auth_1.apiError)(res, 404, `no user ${username} in this vault`);
+            return;
+        }
+        (0, perms_1.setCollaborator)(ctx.repo.dir, username, role);
+        res.json({ username, role });
+    });
+    app.delete('/api/repos/:collection/:repo/collaborators/:user', (req, res) => {
+        const ctx = (0, auth_1.requireRepoAdmin)(root, limiter, req, res);
+        if (!ctx)
+            return;
+        const username = req.params.user;
+        const access = (0, perms_1.repoAccess)(ctx.repo.dir);
+        if (access.collaborators[username] === undefined) {
+            (0, auth_1.apiError)(res, 404, `${username} is not a collaborator on ${ctx.repo.collection}/${ctx.repo.name}`);
+            return;
+        }
+        (0, perms_1.removeCollaborator)(ctx.repo.dir, username);
+        res.json({ removed: username });
+    });
+}