@tequila99/githuman 0.6.0 → 0.8.0

package/dist/server/repositories/notes.repo.js

@@ -0,0 +1,402 @@
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { lstat, link, mkdir, open, readdir, realpath, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { BadRequestError, NotFoundError } from "../errors/http.js";
+import { isSystemError } from "../utils/system-error.js";
+import { sha256Hex } from "../utils/hash.js";
+import { NoteConflictError, NoteExistsError } from "../errors/notes.js";
+import { MAX_NOTE_ASSET_BYTES } from "../../shared/notes/constants.js";
+// Bound file reads before allocating document buffers.
+const MAX_BYTES = 1000000;
+export class NotesRepository {
+    root;
+    writes = new Map();
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    async path(path, markdown = true) {
+        if (!path ||
+            path.includes('\\') ||
+            path.includes('\0') ||
+            path.startsWith('/') ||
+            path
+                .split('/')
+                .some(part => !part || part === '.' || part === '..' || part.startsWith('.')) ||
+            (markdown && !path.toLowerCase().endsWith('.md'))) {
+            throw new BadRequestError('Invalid note path');
+        }
+        const target = resolve(this.root, path);
+        if (!target.startsWith(this.root + sep)) {
+            throw new BadRequestError('Path leaves the notes folder');
+        }
+        // Reject links inside the notes folder. The configured root and its parents may be links.
+        let current = this.root;
+        for (const part of target
+            .slice(this.root.length)
+            .split(sep)
+            .filter(Boolean)) {
+            current = join(current, part);
+            try {
+                if ((await lstat(current)).isSymbolicLink()) {
+                    throw new BadRequestError('Symbolic links are not supported in the notes path');
+                }
+            }
+            catch (error) {
+                if (!isSystemError(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+        return target;
+    }
+    async read(path) {
+        const target = await this.path(path);
+        try {
+            const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                if (!stat.isFile() || stat.size > MAX_BYTES) {
+                    throw new BadRequestError('Note must be a Markdown file under 1 MB');
+                }
+                const bytes = await file.readFile();
+                if (bytes.byteLength > MAX_BYTES) {
+                    throw new BadRequestError('Note exceeds 1 MB');
+                }
+                let text;
+                try {
+                    text = new TextDecoder('utf-8', {
+                        fatal: true,
+                        ignoreBOM: true
+                    }).decode(bytes);
+                }
+                catch {
+                    throw new BadRequestError('Note is not valid UTF-8');
+                }
+                return { path, text, version: sha256Hex(text) };
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT')) {
+                throw new NotFoundError('Note not found');
+            }
+            throw error;
+        }
+    }
+    async list() {
+        const result = [];
+        await this.path('probe.md');
+        const walk = async (dir, prefix) => {
+            const entries = (await readdir(dir, { withFileTypes: true })).filter(entry => !entry.name.startsWith('.') &&
+                !entry.isSymbolicLink() &&
+                entry.name !== 'node_modules' &&
+                (prefix || entry.name !== 'assets'));
+            for (const entry of entries.filter(item => item.isDirectory())) {
+                const path = prefix + entry.name;
+                await this.path(path, false);
+                result.push({ path, folder: true, signature: 'folder' });
+                await walk(join(dir, entry.name), path + '/');
+            }
+            const files = entries.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith('.md'));
+            // Bound concurrent metadata reads while retaining path checks for each file.
+            for (let offset = 0; offset < files.length; offset += 16) {
+                const batch = await Promise.allSettled(files.slice(offset, offset + 16).map(async (entry) => {
+                    const path = prefix + entry.name;
+                    const target = await this.path(path);
+                    const stat = await lstat(target, { bigint: true });
+                    return {
+                        path,
+                        folder: false,
+                        signature: `${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`
+                    };
+                }));
+                for (const item of batch) {
+                    if (item.status === 'rejected')
+                        throw item.reason;
+                    result.push(item.value);
+                }
+            }
+        };
+        await walk(this.root, '');
+        return result.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async serial(path, run) {
+        const prior = this.writes.get(path) ?? Promise.resolve();
+        const next = prior.catch(() => { }).then(run);
+        this.writes.set(path, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (this.writes.get(path) === next)
+                this.writes.delete(path);
+        }
+    }
+    async save(path, text, expected) {
+        return this.serial(path, async () => {
+            if (Buffer.byteLength(text) > MAX_BYTES) {
+                throw new BadRequestError('Note exceeds 1 MB');
+            }
+            const target = await this.path(path);
+            await mkdir(dirname(target), { recursive: true });
+            await this.path(path);
+            let current;
+            if (expected !== undefined) {
+                try {
+                    current = await this.read(path);
+                }
+                catch (error) {
+                    if (error instanceof NotFoundError)
+                        throw new NoteConflictError();
+                    throw error;
+                }
+                if (current.version !== expected)
+                    throw new NoteConflictError();
+                if (current.text === text)
+                    return current;
+                // Retain one previous version per note, without accumulating autosave history.
+                const backups = join(this.root, '.history');
+                await mkdir(backups, { recursive: true });
+                if ((await lstat(backups)).isSymbolicLink() ||
+                    !(await realpath(backups)).startsWith((await realpath(this.root)) + sep)) {
+                    throw new BadRequestError('Invalid backup folder');
+                }
+                const backupTemp = join(backups, '.backup-' + randomUUID());
+                try {
+                    await writeFile(backupTemp, current.text, { flag: 'wx', mode: 0o600 });
+                    await rename(backupTemp, join(backups, sha256Hex(path) + '.md'));
+                }
+                finally {
+                    await unlink(backupTemp).catch(error => {
+                        if (!isSystemError(error, 'ENOENT'))
+                            throw error;
+                    });
+                }
+            }
+            const temporary = join(dirname(target), '.note-' + randomUUID());
+            try {
+                const file = await open(temporary, 'wx', 0o600);
+                try {
+                    await file.writeFile(text);
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await this.path(path);
+                if (expected === undefined) {
+                    try {
+                        await link(temporary, target);
+                    }
+                    catch (error) {
+                        if (isSystemError(error, 'EEXIST'))
+                            throw new NoteExistsError();
+                        throw error;
+                    }
+                }
+                else {
+                    if ((await this.read(path)).version !== expected) {
+                        throw new NoteConflictError();
+                    }
+                    await rename(temporary, target);
+                }
+            }
+            finally {
+                await unlink(temporary).catch(error => {
+                    if (!isSystemError(error, 'ENOENT'))
+                        throw error;
+                });
+            }
+            return { path, text, version: sha256Hex(text) };
+        });
+    }
+    async saveAsset(bytes, extension) {
+        const id = sha256Hex(bytes) + '.' + extension;
+        const target = await this.path('assets/' + id, false);
+        await mkdir(dirname(target), { recursive: true });
+        await this.path('assets/' + id, false);
+        const temporary = join(dirname(target), '.asset-' + randomUUID());
+        try {
+            const file = await open(temporary, 'wx', 0o600);
+            try {
+                await file.writeFile(bytes);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await this.path('assets/' + id, false);
+            try {
+                await link(temporary, target);
+            }
+            catch (error) {
+                if (!isSystemError(error, 'EEXIST'))
+                    throw error;
+            }
+        }
+        finally {
+            await unlink(temporary).catch(error => {
+                if (!isSystemError(error, 'ENOENT'))
+                    throw error;
+            });
+        }
+        return id;
+    }
+    async readAsset(id) {
+        const target = await this.path('assets/' + id, false);
+        try {
+            const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                if (!stat.isFile() || stat.size > MAX_NOTE_ASSET_BYTES) {
+                    throw new BadRequestError('Invalid image attachment');
+                }
+                return await file.readFile();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT')) {
+                throw new NotFoundError('Attachment not found');
+            }
+            throw error;
+        }
+    }
+    async sameEntry(path, other) {
+        const a = await lstat(await this.path(path, false));
+        const b = await lstat(await this.path(other, false));
+        return a.dev === b.dev && a.ino === b.ino;
+    }
+    async exactEntry(path) {
+        const target = await this.path(path, false);
+        try {
+            return (await readdir(dirname(target))).includes(basename(target));
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT'))
+                return false;
+            throw error;
+        }
+    }
+    async exists(path) {
+        const target = await this.path(path, false);
+        try {
+            await lstat(target);
+            return true;
+        }
+        catch (error) {
+            if (isSystemError(error, 'ENOENT'))
+                return false;
+            throw error;
+        }
+    }
+    async moveEntry(path, destination, folder) {
+        const source = await this.path(path, !folder);
+        const target = await this.path(destination, !folder);
+        if (destination.split('/')[0] === 'assets' ||
+            path.split('/')[0] === 'assets') {
+            throw new BadRequestError('Cannot move attachments');
+        }
+        if (folder && destination.startsWith(path + '/')) {
+            throw new BadRequestError('Cannot move a folder into itself');
+        }
+        if (path === destination)
+            return;
+        if (await this.exists(destination))
+            throw new NoteExistsError();
+        const stat = await lstat(source);
+        if (folder ? !stat.isDirectory() : !stat.isFile()) {
+            throw new BadRequestError('Entry type changed');
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await this.path(destination, !folder);
+        if (folder) {
+            await rename(source, target);
+        }
+        else {
+            try {
+                await link(source, target);
+            }
+            catch (error) {
+                if (isSystemError(error, 'EEXIST'))
+                    throw new NoteExistsError();
+                throw error;
+            }
+            await unlink(source);
+        }
+    }
+    async renameEntry(path, name, folder) {
+        return this.serial('rename', async () => {
+            if (!name.trim() ||
+                name !== name.trim() ||
+                /[/\\\0]/.test(name) ||
+                name.startsWith('.')) {
+                throw new BadRequestError('Invalid entry name');
+            }
+            if (path.split('/')[0] === 'assets') {
+                throw new BadRequestError('Cannot rename attachments');
+            }
+            const targetPath = [...path.split('/').slice(0, -1), name].join('/');
+            if (targetPath.split('/')[0] === 'assets') {
+                throw new BadRequestError('Reserved folder name');
+            }
+            const source = await this.path(path, !folder);
+            const target = await this.path(targetPath, !folder);
+            let stat;
+            try {
+                stat = await lstat(source);
+            }
+            catch (error) {
+                if (isSystemError(error, 'ENOENT')) {
+                    throw new NotFoundError('Note entry not found');
+                }
+                throw error;
+            }
+            if (folder ? !stat.isDirectory() : !stat.isFile()) {
+                throw new BadRequestError('Entry type changed');
+            }
+            if (path === targetPath)
+                return targetPath;
+            try {
+                await lstat(target);
+                throw new NoteExistsError();
+            }
+            catch (error) {
+                if (!isSystemError(error, 'ENOENT'))
+                    throw error;
+            }
+            if (folder) {
+                await rename(source, target);
+            }
+            else {
+                try {
+                    await link(source, target);
+                }
+                catch (error) {
+                    if (isSystemError(error, 'EEXIST'))
+                        throw new NoteExistsError();
+                    throw error;
+                }
+                await unlink(source);
+            }
+            return targetPath;
+        });
+    }
+    async folder(path) {
+        const target = await this.path(path, false);
+        await mkdir(dirname(target), { recursive: true });
+        await this.path(path, false);
+        try {
+            await mkdir(target);
+        }
+        catch (error) {
+            if (isSystemError(error, 'EEXIST'))
+                throw new NoteExistsError();
+            throw error;
+        }
+    }
+}

package/dist/server/routes/notes.js

@@ -0,0 +1,167 @@
+import multipart from '@fastify/multipart';
+import { MAX_NOTE_ASSET_BYTES } from "../../shared/notes/constants.js";
+import { noteAssetFormat } from "../../shared/notes/asset-formats.js";
+import { NoteRecordSchema, NoteIdQuery, NoteDescriptorSchema, NoteResolveBody, NoteResolutionSchema, NoteGraphSchema, ResolveIdentityBody, NoteMutationSchema, UploadNoteAssetBody, NoteAssetSchema, NoteAssetContentSchema, NoteAssetParams, NoteQuery, NoteSchema, NotesIndexSchema, CreateNoteBody, SaveNoteBody, RenameNoteBody, CreateFolderBody } from "../../shared/notes/schemas.js";
+import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
+import { BadRequestError } from "../errors/http.js";
+import { createNotesOriginHook } from "../hooks/notes/same-origin.js";
+export async function notesRoutes(app, { service, loopbackBind = false }) {
+    await app.register(multipart, {
+        attachFieldsToBody: true,
+        limits: { fileSize: MAX_NOTE_ASSET_BYTES, files: 1, fields: 0, parts: 1 }
+    });
+    const typed = app.withTypeProvider();
+    app.addHook('onRequest', createNotesOriginHook({ loopbackBind }));
+    app.post('/api/notes/assets', {
+        preValidation: async (request) => {
+            if (!request.isMultipart()) {
+                throw new BadRequestError('Expected multipart/form-data');
+            }
+        },
+        schema: {
+            consumes: ['multipart/form-data'],
+            tags: ['notes'],
+            summary: 'Store a note image',
+            // The multipart validator rewrites file schemas during compilation.
+            body: structuredClone(UploadNoteAssetBody),
+            response: { 201: NoteAssetSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const asset = await service.uploadAsset(await request.body.file.toBuffer());
+        reply.code(201);
+        return asset;
+    });
+    app.get('/api/notes/assets/:id', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a stored note image',
+            params: NoteAssetParams,
+            response: { 200: NoteAssetContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const image = await service.readAsset(request.params.id);
+        const extension = request.params.id.split('.').at(-1);
+        const format = noteAssetFormat(extension);
+        if (!format)
+            throw new BadRequestError('Unsupported attachment format');
+        reply.type(format.mime);
+        reply.header('X-Content-Type-Options', 'nosniff');
+        return reply.send(image);
+    });
+    typed.get('/api/notes', {
+        schema: {
+            tags: ['notes'],
+            summary: 'List project notes',
+            response: { 200: NotesIndexSchema, ...ERROR_RESPONSES }
+        }
+    }, () => service.index());
+    typed.get('/api/notes/path', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Resolve a current or historical note path',
+            querystring: NoteQuery,
+            response: { 200: NoteRecordSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.resolvePath(request.query.path));
+    typed.get('/api/notes/identity', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a stable note identity and backlinks',
+            querystring: NoteIdQuery,
+            response: { 200: NoteDescriptorSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.descriptor(request.query.id, request.query.storageId));
+    typed.get('/api/notes/by-id', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a note by stable identity',
+            querystring: NoteIdQuery,
+            response: { 200: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.readId(request.query.id, request.query.storageId));
+    typed.get('/api/notes/graph', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read the graph of note relationships',
+            response: { 200: NoteGraphSchema, ...ERROR_RESPONSES }
+        }
+    }, () => service.identity.graph());
+    typed.post('/api/notes/resolve', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Resolve an occurrence in the current note source',
+            body: NoteResolveBody,
+            response: { 200: NoteResolutionSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.identity.resolve(request.body.sourceId, request.body.storageId, request.body.text, request.body.href, request.body.occurrence));
+    typed.post('/api/notes/identity/resolve', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Resolve a restored or moved file identity',
+            body: ResolveIdentityBody,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        await service.identity.resolveIdentity(request.body.issueId, request.body.restore, request.body.candidateId);
+        reply.code(204).send(null);
+    });
+    typed.post('/api/notes/repair', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Retry pending link repairs',
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (_request, reply) => {
+        await service.identity.retry();
+        reply.code(204).send(null);
+    });
+    typed.get('/api/notes/document', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Read a note',
+            querystring: NoteQuery,
+            response: { 200: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.read(request.query.path));
+    typed.post('/api/notes/document', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Create a note',
+            body: CreateNoteBody,
+            response: { 201: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const note = await service.save(request.body.path, request.body.text);
+        reply.code(201);
+        return note;
+    });
+    typed.patch('/api/notes/document', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Save a note if its version matches',
+            body: SaveNoteBody,
+            response: { 200: NoteSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.save(request.body.path, request.body.text, request.body.version, request.body.id, request.body.storageId));
+    typed.post('/api/notes/rename', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Rename a note or folder',
+            body: RenameNoteBody,
+            response: { 200: NoteMutationSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
+        return service.rename(request.body.path, request.body.name, request.body.folder, request.body.target, request.body.id, request.body.revision);
+    });
+    typed.post('/api/notes/folder', {
+        schema: {
+            tags: ['notes'],
+            summary: 'Create a notes folder',
+            body: CreateFolderBody,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        await service.folder(request.body.path);
+        reply.code(204).send(null);
+    });
+}

package/dist/server/routes/terminal.js

@@ -45,8 +45,9 @@ export async function terminalRoutes(app, options) {
         },
         onRequest: requireTerminalOrigin,
         preValidation: async (request) => {
-            if (!tokens.consume(request.query.token, request.headers.origin ?? ''))
+            if (!tokens.consume(request.query.token, request.headers.origin ?? '')) {
                 throw new ForbiddenError('Terminal connection token is invalid or expired.');
+            }
         }
     }, socket => {
         const connection = attachTerminalSocket(socket, options.registry, {

package/dist/server/services/git.service.js

@@ -1,6 +1,7 @@
+import { isMissingPathError } from "../utils/system-error.js";
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
-import { readFile } from 'node:fs/promises';
+import { readFile, realpath } from 'node:fs/promises';
 import { basename, posix, resolve, sep } from 'node:path';
 import { simpleGit } from 'simple-git';
 import { GitFileNotFoundError } from "../errors/git.js";
@@ -49,13 +50,6 @@ function objectSpecFor(ref, path) {
     // the injection this would otherwise guard against.
     return ref === 'INDEX' ? `:${path}` : `${ref}:${path}`;
 }
-/** `ENOENT` and `ENOTDIR` both mean that the file does not exist. */
-function isMissingPathError(error) {
-    return (!!error &&
-        typeof error === 'object' &&
-        'code' in error &&
-        (error.code === 'ENOENT' || error.code === 'ENOTDIR'));
-}
 /**
  * Checks one path with `ls-tree` instead of listing the whole tree. A failing
  * `ls-tree` means the ref is invalid, so the path is reported as present and
@@ -88,16 +82,25 @@ export async function getFileAtRef(repoPath, ref, path, strict = false) {
     if (ref === 'WORKTREE') {
         try {
             const absolutePath = resolveWithinRepo(repoPath, path);
-            const buffer = await readFile(absolutePath);
+            let target = absolutePath;
+            if (strict) {
+                const [root, file] = await Promise.all([
+                    realpath(repoPath),
+                    realpath(absolutePath)
+                ]);
+                target = resolveWithinRepo(root, file);
+            }
+            const buffer = await readFile(target);
             const isBinary = isBinaryBuffer(buffer);
             return { content: isBinary ? '' : buffer.toString('utf-8'), isBinary };
         }
         catch (error) {
             if (strict) {
-                if (isMissingPathError(error))
+                if (isMissingPathError(error)) {
                     throw new GitFileNotFoundError('File was deleted or moved', {
                         cause: error
                     });
+                }
                 throw error;
             }
             return { content: '', isBinary: false };
@@ -118,10 +121,11 @@ export async function getFileAtRef(repoPath, ref, path, strict = false) {
     }
     catch (error) {
         if (strict) {
-            if (!(await pathExistsAtRef(repoPath, ref, path)))
+            if (!(await pathExistsAtRef(repoPath, ref, path))) {
                 throw new GitFileNotFoundError('File was deleted or moved', {
                     cause: error
                 });
+            }
             throw error;
         }
         return { content: '', isBinary: false };