@magland/mochi 0.3.1

package/dist/vault.js

@@ -0,0 +1,442 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAULT_VERSION = exports.VAULT_FILE = void 0;
+exports.tokenId = tokenId;
+exports.vaultFilePath = vaultFilePath;
+exports.loadVault = loadVault;
+exports.hashToken = hashToken;
+exports.mintToken = mintToken;
+exports.globMatch = globMatch;
+exports.authenticate = authenticate;
+exports.authenticateToken = authenticateToken;
+exports.addUserToken = addUserToken;
+exports.finishPermsMigration = finishPermsMigration;
+exports.setSiteAdmin = setSiteAdmin;
+exports.bootstrapVault = bootstrapVault;
+exports.revokeToken = revokeToken;
+exports.setUserEmails = setUserEmails;
+exports.accountForEmail = accountForEmail;
+exports.mergeContributors = mergeContributors;
+exports.removeUser = removeUser;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const atomic_1 = require("./atomic");
+const filecache_1 = require("./filecache");
+const scan_1 = require("./scan");
+exports.VAULT_FILE = 'vault.json';
+/** How a token is named in a listing or a revocation: its id, or a stand-in for one. */
+function tokenId(t) {
+    return t.id ?? t.hash.slice(0, 8);
+}
+/** The version written to vault.json since roles replaced glob scopes. */
+exports.VAULT_VERSION = 2;
+function vaultFilePath(root) {
+    return path.join(root, exports.VAULT_FILE);
+}
+function asStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string') ? v : null;
+}
+function normalizeVault(parsed) {
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('vault.json must be a JSON object');
+    }
+    const usersRaw = parsed.users;
+    if (typeof usersRaw !== 'object' || usersRaw === null) {
+        throw new Error('vault.json must have a "users" object');
+    }
+    // A file without the version marker was written before roles existed and
+    // still carries glob scopes. Its users and tokens parse as usual, and the
+    // globs ride along in `legacy` for the migration to translate; the file is
+    // legacy as a whole, so half-migrated states cannot exist.
+    const legacy = parsed.version !== exports.VAULT_VERSION;
+    const users = {};
+    for (const [name, u] of Object.entries(usersRaw)) {
+        if (typeof u !== 'object' || u === null) {
+            throw new Error(`user ${name} must be an object`);
+        }
+        const rec = u;
+        const scope = asStringArray(rec.scope ?? []);
+        if (!scope) {
+            throw new Error(`user ${name}: "scope" must be a list of strings`);
+        }
+        const admin = asStringArray(rec.admin ?? []);
+        if (!admin) {
+            throw new Error(`user ${name}: "admin" must be a list of strings`);
+        }
+        const tokensRaw = rec.tokens ?? [];
+        if (!Array.isArray(tokensRaw)) {
+            throw new Error(`user ${name}: "tokens" must be a list`);
+        }
+        const tokens = tokensRaw.map((t, i) => {
+            if (typeof t === 'string')
+                return { hash: t };
+            if (typeof t === 'object' && t !== null && typeof t.hash === 'string') {
+                const tRec = t;
+                const rec = { hash: tRec.hash };
+                if (typeof tRec.id === 'string' && tRec.id !== '')
+                    rec.id = tRec.id;
+                if (typeof tRec.created === 'string' && tRec.created !== '')
+                    rec.created = tRec.created;
+                if (tRec.scope !== undefined) {
+                    const ts = asStringArray(tRec.scope);
+                    if (!ts)
+                        throw new Error(`user ${name}: token ${i} "scope" must be a list of strings`);
+                    rec.scope = ts;
+                }
+                return rec;
+            }
+            throw new Error(`user ${name}: token ${i} must be a hash string or an object with a "hash"`);
+        });
+        const emails = asStringArray(rec.emails ?? []);
+        if (!emails) {
+            throw new Error(`user ${name}: "emails" must be a list of strings`);
+        }
+        users[name] = {
+            tokens,
+            ...(rec.siteAdmin === true ? { siteAdmin: true } : {}),
+            ...(emails.length ? { emails } : {}),
+            ...(legacy ? { legacy: { scope, admin } } : {}),
+        };
+    }
+    return { users, ...(legacy ? { legacy: true } : {}) };
+}
+const cache = (0, filecache_1.fileCache)({
+    read: (file) => {
+        try {
+            return { status: 'ok', vault: normalizeVault(JSON.parse(fs.readFileSync(file, 'utf8'))) };
+        }
+        catch (e) {
+            return { status: 'error', message: e instanceof Error ? e.message : String(e) };
+        }
+    },
+    missing: () => ({ status: 'missing' }),
+});
+function loadVault(root) {
+    return cache.get(vaultFilePath(root));
+}
+function hashToken(token) {
+    return crypto.createHash('sha256').update(token).digest('hex');
+}
+function mintToken() {
+    const token = 'mochi_' + crypto.randomBytes(32).toString('hex');
+    return { token, hash: hashToken(token) };
+}
+function globMatch(pattern, target) {
+    const rx = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp(`^${rx}$`).test(target);
+}
+function authenticate(vault, username, tokenPlain) {
+    const user = vault.users[username];
+    if (!user)
+        return null;
+    const presented = Buffer.from(hashToken(tokenPlain), 'hex');
+    for (const t of user.tokens) {
+        let stored;
+        try {
+            stored = Buffer.from(t.hash, 'hex');
+        }
+        catch {
+            continue;
+        }
+        if (stored.length === presented.length && crypto.timingSafeEqual(stored, presented)) {
+            return { username, user, token: t };
+        }
+    }
+    return null;
+}
+function authenticateToken(vault, tokenPlain) {
+    const presented = Buffer.from(hashToken(tokenPlain), 'hex');
+    for (const [username, user] of Object.entries(vault.users)) {
+        for (const t of user.tokens) {
+            let stored;
+            try {
+                stored = Buffer.from(t.hash, 'hex');
+            }
+            catch {
+                continue;
+            }
+            if (stored.length === presented.length && crypto.timingSafeEqual(stored, presented)) {
+                return { username, user, token: t };
+            }
+        }
+    }
+    return null;
+}
+// Who may do what lives in src/perms.ts, which reads roles and ownership from
+// where each is stored; this file holds only who somebody is.
+function writeVault(file, vault) {
+    const users = {};
+    for (const [name, u] of Object.entries(vault.users)) {
+        const { legacy: _legacy, ...rest } = u;
+        users[name] = rest;
+    }
+    (0, atomic_1.writeFileAtomic)(file, JSON.stringify({ version: exports.VAULT_VERSION, users }, null, 2) + '\n', { mode: 0o600 });
+}
+/**
+ * Every edit to vault.json is a read, a change in memory, and a write back, and
+ * they are all short. Holding one lock across the whole of one makes them
+ * serial against a second server and against a CLI run on the same directory,
+ * which is the arrangement the documentation invites by saying a vault is just
+ * a directory. Readers do not take the lock: they see the old file or the new
+ * one, which the atomic rename already guarantees.
+ */
+function editVault(root, fn) {
+    return (0, atomic_1.withFileLock)(path.join(root, `${exports.VAULT_FILE}.lock`), () => fn(vaultFilePath(root)));
+}
+// Reread under the lock, refusing a pre-roles file: writeVault writes the
+// current shape, so editing a legacy file in place would silently drop the
+// glob scopes the migration still has to translate.
+function readVaultForEdit(file) {
+    const vault = normalizeVault(JSON.parse(fs.readFileSync(file, 'utf8')));
+    if (vault.legacy) {
+        throw new Error('vault.json predates roles; start the server once to migrate it');
+    }
+    return vault;
+}
+// The body of addUserToken, without the lock, so that bootstrapVault can put
+// its own check-then-act inside the same one rather than nesting a second.
+function addUserTokenLocked(file, username, opts) {
+    let vault = { users: {} };
+    if (fs.existsSync(file)) {
+        vault = normalizeVault(JSON.parse(fs.readFileSync(file, 'utf8')));
+        if (vault.legacy) {
+            throw new Error('vault.json predates roles; start the server once to migrate it');
+        }
+    }
+    let user = vault.users[username];
+    const created = !user;
+    if (!user) {
+        // A leading dot is allowed in a repository's name and in nothing else; a
+        // user carrying one would be a name the interface hides for no reason.
+        if ((0, scan_1.isDotName)(username))
+            throw new Error(`invalid username ${username}`);
+        user = { tokens: [], ...(opts.siteAdmin ? { siteAdmin: true } : {}) };
+        vault.users[username] = user;
+    }
+    else if (opts.siteAdmin) {
+        throw new Error(`user ${username} already exists; site admin is granted from the admin page or the users API`);
+    }
+    // A caller may supply the token instead of taking a minted one, which is how
+    // a vault can be bootstrapped with a token its operator already holds. Only
+    // the hash is stored either way, so the two cases differ in nothing else.
+    const { token, hash } = opts.token ? { token: opts.token, hash: hashToken(opts.token) } : mintToken();
+    const rec = { hash, id: crypto.randomBytes(4).toString('hex'), created: new Date().toISOString() };
+    if (opts.tokenScope && opts.tokenScope.length)
+        rec.scope = opts.tokenScope;
+    user.tokens.push(rec);
+    writeVault(file, vault);
+    return { token, created, user };
+}
+function addUserToken(root, username, opts = {}) {
+    return editVault(root, (file) => addUserTokenLocked(file, username, opts));
+}
+/**
+ * The last step of the permissions migration (src/migrate.ts): rewrite a
+ * pre-roles vault.json in the current shape, granting the site-admin bit to
+ * the users named. The glob scopes are dropped here and only here, after the
+ * migration has translated them into ownership and collaborator files; the
+ * original file survives as the backup the migration wrote first.
+ */
+function finishPermsMigration(root, siteAdmins) {
+    editVault(root, (file) => {
+        const vault = normalizeVault(JSON.parse(fs.readFileSync(file, 'utf8')));
+        if (!vault.legacy)
+            return;
+        delete vault.legacy;
+        for (const [name, user] of Object.entries(vault.users)) {
+            delete user.legacy;
+            if (siteAdmins.includes(name))
+                user.siteAdmin = true;
+        }
+        writeVault(file, vault);
+    });
+}
+/** Grant or withdraw the site-admin bit. */
+function setSiteAdmin(root, username, value) {
+    return editVault(root, (file) => {
+        if (!fs.existsSync(file)) {
+            throw new Error(`no vault.json at ${file}; create the user first with: mochi user add ${username}`);
+        }
+        const vault = readVaultForEdit(file);
+        const user = vault.users[username];
+        if (!user) {
+            throw new Error(`user ${username} does not exist; create it with: mochi user add ${username}`);
+        }
+        if (value)
+            user.siteAdmin = true;
+        else
+            delete user.siteAdmin;
+        writeVault(file, vault);
+        return user;
+    });
+}
+/**
+ * Initialize a vault that has none, creating the owner and its first token.
+ * Returns null when there is already a vault.json, since a vault is
+ * initialized once and everything after that is the operator's own doing.
+ *
+ * `presetToken` lets the token be handed in rather than minted, which is what
+ * `mochi deploy` does: it mints the token on the operator's machine and
+ * passes it to the server as an environment secret, so a fresh remote vault can
+ * be logged in to without reading a token back out of the logs. A preset token
+ * is never echoed by the caller, so it does not reach the log at all.
+ */
+function bootstrapVault(root, presetToken) {
+    const preset = (presetToken ?? '').trim();
+    if (presetToken !== undefined && presetToken !== null && presetToken !== '' && !preset) {
+        throw new Error('the owner token given for a new vault is blank');
+    }
+    // A token travels as a Basic-auth password and lands in URLs' credential
+    // slots, so a supplied one is held to the shape of a minted one rather than
+    // taken as given: printable, no spaces, and long enough not to be guessed.
+    if (preset && !/^[\x21-\x7e]{24,256}$/.test(preset)) {
+        throw new Error('the owner token given for a new vault is not usable: it must be 24 to 256 characters, ' +
+            'printable, and contain no spaces');
+    }
+    // The existence check and the creation are one operation. Two servers started
+    // against one fresh directory would otherwise both find no vault.json and both
+    // bootstrap, and the second owner token to be written would be the only one
+    // that worked, while both had been printed as if they were the credential.
+    return editVault(root, (file) => {
+        if (fs.existsSync(file))
+            return null;
+        const { token } = addUserTokenLocked(file, 'owner', {
+            siteAdmin: true,
+            ...(preset ? { token: preset } : {}),
+        });
+        return { username: 'owner', token, preset: preset !== '' };
+    });
+}
+/**
+ * Revoke one token by its id. Revoking the token currently in use is allowed and
+ * reported plainly rather than refused: locking yourself out is your business,
+ * and vault.json remains hand-editable either way.
+ */
+function revokeToken(root, username, id) {
+    return editVault(root, (file) => {
+        const vault = readVaultForEdit(file);
+        const user = vault.users[username];
+        if (!user)
+            throw new Error(`no user ${username}`);
+        const before = user.tokens.length;
+        user.tokens = user.tokens.filter((t) => tokenId(t) !== id);
+        if (user.tokens.length === before)
+            return { revoked: false, remaining: before };
+        writeVault(file, vault);
+        return { revoked: true, remaining: user.tokens.length };
+    });
+}
+/** Replace the git author emails aliased to a user. An empty list clears them. */
+function setUserEmails(root, username, emails) {
+    return editVault(root, (file) => {
+        const vault = readVaultForEdit(file);
+        const user = vault.users[username];
+        if (!user)
+            throw new Error(`no user ${username}`);
+        if (emails.length)
+            user.emails = emails;
+        else
+            delete user.emails;
+        writeVault(file, vault);
+        return user;
+    });
+}
+/**
+ * The user a commit author email belongs to, or null when it belongs to no
+ * one this vault knows. Two ways in: the synthetic `<user>@noreply.<anything>`
+ * the web editor writes, recognised by shape so the answer does not depend on
+ * which hostname the vault was being served under at the time, and the emails
+ * a user has listed as theirs.
+ */
+function accountForEmail(vault, email) {
+    const lower = email.toLowerCase();
+    const m = lower.match(/^([^@]+)@noreply\./);
+    if (m && vault.users[m[1]])
+        return m[1];
+    for (const [name, user] of Object.entries(vault.users)) {
+        if (user.emails?.some((e) => e.toLowerCase() === lower))
+            return name;
+    }
+    return null;
+}
+/**
+ * Fold one person's identities into one contributor. Grouped by account where
+ * an email resolves to one, and by email otherwise; within a group the
+ * human-written identity is preferred over the synthetic one for the name and
+ * the email shown, since "Jeremy" is who committed and `owner@noreply...` is
+ * how. Without a vault (one that failed to load) everyone stands as git
+ * reported them.
+ */
+function mergeContributors(vault, people) {
+    const groups = new Map();
+    for (const p of people) {
+        const account = vault ? accountForEmail(vault, p.email) : null;
+        const key = account !== null ? `u:${account}` : `e:${(p.email || p.name).toLowerCase()}`;
+        const synthetic = /@noreply\./i.test(p.email);
+        const g = groups.get(key);
+        if (!g) {
+            groups.set(key, { ...p, account, bestCommits: p.commits, bestSynthetic: synthetic });
+            continue;
+        }
+        g.commits += p.commits;
+        // The identity shown is the best-represented human one; a synthetic
+        // identity only fronts a group that holds nothing else.
+        if ((g.bestSynthetic && !synthetic) || (g.bestSynthetic === synthetic && p.commits > g.bestCommits)) {
+            g.name = p.name;
+            g.email = p.email;
+            g.bestCommits = p.commits;
+            g.bestSynthetic = synthetic;
+        }
+    }
+    return [...groups.values()]
+        .map(({ bestCommits: _b, bestSynthetic: _s, ...c }) => c)
+        .sort((a, b) => b.commits - a.commits);
+}
+/** Remove a user, and with them every token they hold. */
+function removeUser(root, username) {
+    return editVault(root, (file) => {
+        const vault = readVaultForEdit(file);
+        if (!vault.users[username])
+            return false;
+        delete vault.users[username];
+        writeVault(file, vault);
+        return true;
+    });
+}

package/dist/version.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageVersion = packageVersion;
+exports.buildInfo = buildInfo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// What this vault is running, in the two forms something asks for it: the
+// version of the package, and the build that version was compiled from.
+//
+// The version is read from the running package's own package.json. It is used
+// where the server writes a command for somebody else's machine to run: the
+// pasted `npx @magland/mochi@<version>` pins what that machine executes to
+// what this vault was tested against, rather than to whatever npm serves the
+// day the command is pasted.
+//
+// The build is a question package.json cannot answer. Two vaults reporting
+// 0.3.0 can be different commits, since main carries the version of the last
+// release until the next bump, and "is the fix I pushed the code that is
+// running" is then unanswerable from the version alone. So the compile writes
+// dist/build-info.json beside the code it emits (scripts/build-info.js, run by
+// `npm run build`) and it is read back here. Running from source has no such
+// file and says so rather than guessing.
+let cached = null;
+function packageVersion() {
+    if (cached !== null)
+        return cached;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+        cached = typeof pkg.version === 'string' && pkg.version !== '' ? pkg.version : 'latest';
+    }
+    catch {
+        cached = 'latest';
+    }
+    return cached;
+}
+let build = null;
+function buildInfo() {
+    if (build !== null)
+        return build;
+    let commit = null;
+    let builtAt = null;
+    try {
+        const stamp = JSON.parse(fs.readFileSync(path.join(__dirname, 'build-info.json'), 'utf8'));
+        if (typeof stamp.commit === 'string' && stamp.commit !== '')
+            commit = stamp.commit;
+        if (typeof stamp.builtAt === 'string' && stamp.builtAt !== '')
+            builtAt = stamp.builtAt;
+    }
+    catch {
+        // No stamp: source under tsx, or a dist compiled by tsc on its own. Both
+        // are honest as "unbuilt" and neither is worth inventing a date for.
+    }
+    build = { version: packageVersion(), commit, builtAt };
+    return build;
+}