@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/git-source.js

@@ -0,0 +1,409 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, rename, rm, rmdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { assertNoSymlinkPath } from "./path-safety.js";
+import { runProcess } from "./process-runner.js";
+export const SKILL_TREE_LIMITS = Object.freeze({
+    maxFiles: 256,
+    maxFileBytes: 2 * 1024 * 1024,
+    maxTotalBytes: 8 * 1024 * 1024,
+    maxPathBytes: 4096,
+    maxDepth: 32,
+    maxListingBytes: 16 * 1024 * 1024,
+});
+const EXCLUDED_LIFECYCLE_SEGMENTS = new Set([
+    "in-progress",
+    "beta",
+    "deprecated",
+    "retired",
+]);
+export class GitSourceAccessError extends Error {
+    constructor(source, reason) {
+        super(`Unable to refresh Git Source ${JSON.stringify(source.id)} from ${JSON.stringify(source.url)}: ${reason}`);
+        this.name = "GitSourceAccessError";
+    }
+}
+function gitFailureDetail(result) {
+    return result.stderr.trim()
+        || (result.signal ? `terminated by ${result.signal}` : `exited with code ${result.code ?? "unknown"}`);
+}
+class NodeGitCommandRunner {
+    async run(command, args, options = {}) {
+        const result = await runProcess(command, args, options.cwd === undefined ? {} : { cwd: options.cwd });
+        if (result.code !== 0) {
+            throw new Error(`git command failed: ${gitFailureDetail(result)}`);
+        }
+    }
+}
+class NodeGitSnapshotCommandRunner {
+    async run(command, args, options = {}) {
+        return Buffer.from(await this.runBinary(command, args, options)).toString("utf8");
+    }
+    async runBinary(command, args, options = {}) {
+        const result = await runProcess(command, args, {
+            captureStdout: true,
+            ...(options.maxOutputBytes === undefined ? {} : { maxOutputBytes: options.maxOutputBytes }),
+        });
+        if (result.outputTooLarge) {
+            throw new Error("git command output exceeds the safe size limit");
+        }
+        if (result.code !== 0) {
+            throw new Error(`git command failed: ${gitFailureDetail(result)}`);
+        }
+        return result.stdout;
+    }
+}
+const SOURCE_LOCK_TIMEOUT_MS = 30_000;
+const SOURCE_LOCK_RETRY_MS = 10;
+/**
+ * Clones each Source into a local mirror and refreshes it from the registered
+ * URL. Mirrors are intentionally not checked out: discovery owns later reads.
+ */
+export class GitSourceAccessAdapter {
+    cachePath;
+    runner;
+    constructor(options = {}) {
+        this.cachePath = options.cachePath ?? defaultGitSourceCachePath();
+        this.runner = options.runner ?? new NodeGitCommandRunner();
+    }
+    async refresh(source) {
+        const expectedId = sourceIdForUrl(source.url);
+        if (source.kind !== "git" || source.id !== expectedId) {
+            throw new GitSourceAccessError(source, "the Source identity does not match its registered URL");
+        }
+        const destination = cachePathForValidatedSource(this.cachePath, source);
+        try {
+            await assertNoSymlinkPath(this.cachePath, "cache path");
+            await mkdir(this.cachePath, { recursive: true });
+            await assertNoSymlinkPath(this.cachePath, "cache path");
+            const release = await acquireSourceLock(`${destination}.lock`);
+            try {
+                await this.refreshLocked(source, destination);
+            }
+            finally {
+                await release();
+            }
+        }
+        catch (error) {
+            if (error instanceof GitSourceAccessError) {
+                throw error;
+            }
+            const reason = error instanceof Error ? error.message : "the Git command failed";
+            throw new GitSourceAccessError(source, reason);
+        }
+    }
+    async refreshLocked(source, destination) {
+        const existing = await pathType(destination);
+        if (existing === "symlink") {
+            throw new Error("the Source cache path is a symbolic link");
+        }
+        if (existing === "file") {
+            throw new Error("the Source cache path is not a directory");
+        }
+        if (existing === "directory") {
+            await assertNoSymlinkPath(destination, "cache path");
+            // The explicit mirror refspec synchronizes branches, tags, and other
+            // refs from the registered URL while --prune removes deleted refs.
+            await this.runner.run("git", [
+                "-C",
+                destination,
+                "fetch",
+                "--prune",
+                "--force",
+                source.url,
+                "+refs/*:refs/*",
+            ]);
+            return;
+        }
+        const temporaryDestination = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await this.runner.run("git", ["clone", "--mirror", source.url, temporaryDestination]);
+            await assertNoSymlinkPath(temporaryDestination, "cache path");
+            if ((await pathType(temporaryDestination)) !== "directory") {
+                throw new Error("Git clone did not create a directory mirror");
+            }
+            await rename(temporaryDestination, destination);
+        }
+        finally {
+            await rm(temporaryDestination, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+}
+/** Validates one `git ls-tree -z` record of a selected Skill directory. */
+function parseSkillTreeRecord(record, relativeSkillPath) {
+    const separator = record.indexOf("\t");
+    if (separator < 0) {
+        throw new Error("Git Source returned a malformed Skill tree entry");
+    }
+    const [mode, objectType, objectId] = record.slice(0, separator).split(" ");
+    const relativePath = record.slice(separator + 1);
+    if (!relativePath.startsWith(`${relativeSkillPath}/`) || !isSafeSourcePath(relativePath)) {
+        throw new Error("Git Source returned a Skill tree path outside the selected directory");
+    }
+    if (objectType !== "blob" || (mode !== "100644" && mode !== "100755")) {
+        throw new Error(`Selected Skill tree contains an unsupported Git entry: ${relativePath}`);
+    }
+    if (!objectId || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(objectId)) {
+        throw new Error("Git Source returned an unsafe object reference");
+    }
+    return { relativePath, objectId, executable: mode === "100755" };
+}
+export class GitSourceSnapshotAccess {
+    cachePath;
+    runner;
+    constructor(options = {}) {
+        this.cachePath = options.cachePath ?? defaultGitSourceCachePath();
+        this.runner = options.runner ?? new NodeGitSnapshotCommandRunner();
+    }
+    async requireMirror(source) {
+        const destination = cachePathForSource(this.cachePath, source);
+        if ((await pathType(destination)) !== "directory") {
+            throw new Error(`Git Source mirror is not available: ${destination}`);
+        }
+        await assertNoSymlinkPath(destination, "cache path");
+        return destination;
+    }
+    async readSkillTree(source, skillPath) {
+        return (await this.readSkillTreeSnapshot(source, skillPath)).files;
+    }
+    /** Reads Skill bytes and the commit they came from as one immutable snapshot. */
+    async readSkillTreeSnapshot(source, skillPath) {
+        const relativeSkillPath = validateSkillDirectoryPath(skillPath);
+        const destination = await this.requireMirror(source);
+        const commit = await this.readResolvedCommit(source);
+        const tree = await this.runner.run("git", [
+            "--git-dir",
+            destination,
+            "ls-tree",
+            "-r",
+            "-z",
+            commit,
+            "--",
+            relativeSkillPath,
+        ], { maxOutputBytes: SKILL_TREE_LIMITS.maxListingBytes });
+        if (Buffer.byteLength(tree, "utf8") > SKILL_TREE_LIMITS.maxListingBytes) {
+            throw new Error("Selected Skill tree listing exceeds the safe size limit");
+        }
+        const files = [];
+        let totalBytes = 0;
+        for (const record of tree.split("\0")) {
+            if (!record) {
+                continue;
+            }
+            if (files.length >= SKILL_TREE_LIMITS.maxFiles) {
+                throw new Error("Selected Skill tree contains too many files");
+            }
+            const entry = parseSkillTreeRecord(record, relativeSkillPath);
+            const content = await this.runner.runBinary("git", ["--git-dir", destination, "cat-file", "blob", entry.objectId], {
+                maxOutputBytes: SKILL_TREE_LIMITS.maxFileBytes,
+            });
+            if (content.byteLength > SKILL_TREE_LIMITS.maxFileBytes) {
+                throw new Error(`Selected Skill file exceeds the safe size limit: ${entry.relativePath}`);
+            }
+            totalBytes += content.byteLength;
+            if (totalBytes > SKILL_TREE_LIMITS.maxTotalBytes) {
+                throw new Error("Selected Skill tree exceeds the safe total size limit");
+            }
+            files.push({ path: entry.relativePath, content, executable: entry.executable });
+        }
+        const hasSkillManifest = files.some((file) => file.path === `${relativeSkillPath}/SKILL.md`);
+        if (!hasSkillManifest) {
+            throw new Error(`Selected Skill directory does not contain ${relativeSkillPath}/SKILL.md`);
+        }
+        return Object.freeze({
+            resolvedVersion: commit,
+            files: Object.freeze(files),
+        });
+    }
+    /** Resolves the selected ref to an immutable commit without refreshing the mirror. */
+    async readResolvedCommit(source) {
+        const destination = await this.requireMirror(source);
+        const revision = source.ref === undefined ? "HEAD" : validateGitRef(source.ref);
+        const commit = (await this.runner.run("git", [
+            "--git-dir",
+            destination,
+            "rev-parse",
+            "--verify",
+            `${revision}^{commit}`,
+        ], { maxOutputBytes: 128 })).trim();
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(commit)) {
+            throw new Error(`Git Source mirror has no safe HEAD snapshot: ${source.id}`);
+        }
+        return commit;
+    }
+    async readSnapshot(source) {
+        const destination = await this.requireMirror(source);
+        const commit = await this.readResolvedCommit(source);
+        const tree = await this.runner.run("git", ["--git-dir", destination, "ls-tree", "-r", "-z", commit]);
+        const files = [];
+        for (const record of tree.split("\0")) {
+            if (!record) {
+                continue;
+            }
+            const separator = record.indexOf("\t");
+            if (separator < 0) {
+                continue;
+            }
+            const metadata = record.slice(0, separator).split(" ");
+            const relativePath = record.slice(separator + 1);
+            if (metadata[0] === "120000"
+                || metadata[1] !== "blob"
+                || !relativePath
+                || path.posix.basename(relativePath) !== "SKILL.md"
+                || relativePath.split("/").slice(0, -1).some((segment) => EXCLUDED_LIFECYCLE_SEGMENTS.has(segment))) {
+                continue;
+            }
+            files.push({
+                path: relativePath,
+                content: await this.runner.run("git", ["--git-dir", destination, "show", `${commit}:${relativePath}`]),
+            });
+        }
+        return Object.freeze(files);
+    }
+}
+export function defaultGitSourceCachePath(environment = process.env, platform = process.platform, homeDirectory = homedir()) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    if (platform === "win32") {
+        const localAppData = environment.LOCALAPPDATA || environment.APPDATA;
+        return pathApi.join(localAppData || pathApi.join(homeDirectory, "AppData", "Local"), "Agent Depot", "git-sources");
+    }
+    const cacheHome = environment.XDG_CACHE_HOME;
+    return pathApi.join(cacheHome && pathApi.isAbsolute(cacheHome) ? cacheHome : pathApi.join(homeDirectory, ".cache"), "agent-depot", "git-sources");
+}
+export function cachePathForSource(cachePath, source) {
+    const expectedId = sourceIdForUrl(source.url);
+    if (source.kind !== "git" || source.id !== expectedId) {
+        throw new GitSourceAccessError(source, "the Source identity does not match its registered URL");
+    }
+    return cachePathForValidatedSource(cachePath, source);
+}
+function cachePathForValidatedSource(cachePath, source) {
+    return path.join(cachePath, source.id.slice("git:".length));
+}
+async function pathType(candidate) {
+    try {
+        const information = await lstat(candidate);
+        if (information.isSymbolicLink()) {
+            return "symlink";
+        }
+        return information.isDirectory() ? "directory" : "file";
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return "missing";
+        }
+        throw error;
+    }
+}
+async function acquireSourceLock(lockPath) {
+    const deadline = Date.now() + SOURCE_LOCK_TIMEOUT_MS;
+    while (true) {
+        try {
+            await mkdir(lockPath);
+            return async () => {
+                await rmdir(lockPath);
+            };
+        }
+        catch (error) {
+            if (!isAlreadyExists(error)) {
+                throw error;
+            }
+            if ((await pathType(lockPath)) === "symlink") {
+                throw new Error("the Source cache lock is a symbolic link");
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`the Source cache lock directory is busy: ${lockPath}; another refresh might be active. Wait for it to finish before retrying`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, SOURCE_LOCK_RETRY_MS));
+        }
+    }
+}
+export function validateGitRef(candidate) {
+    if (typeof candidate !== "string" || candidate.length === 0 || candidate.trim() !== candidate ||
+        Array.from(candidate).some((character) => (character.codePointAt(0) ?? 0) <= 0x20) ||
+        /[~^:?*[\\]/u.test(candidate) || candidate.includes("..") || candidate.includes("@{")) {
+        throw new Error("Git Source ref contains unsafe characters");
+    }
+    const segments = candidate.split("/");
+    if (segments.some((segment) => segment.length === 0 || segment === "." || segment.endsWith(".") || segment.startsWith("."))) {
+        throw new Error("Git Source ref contains an unsafe path segment");
+    }
+    return candidate;
+}
+export function validateSkillDirectoryPath(candidate) {
+    if (typeof candidate !== "string" || candidate.length === 0) {
+        throw new Error("Selected Skill path must be a non-empty relative POSIX path");
+    }
+    if (Buffer.byteLength(candidate, "utf8") > SKILL_TREE_LIMITS.maxPathBytes
+        || candidate.includes("\\")
+        || Array.from(candidate).some((character) => {
+            const code = character.codePointAt(0) ?? 0;
+            return code <= 0x1f || code === 0x7f;
+        })
+        || candidate.startsWith("/")
+        || candidate.endsWith("/")) {
+        throw new Error("Selected Skill path contains unsafe characters");
+    }
+    const segments = candidate.split("/");
+    if (segments.length > SKILL_TREE_LIMITS.maxDepth || segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        throw new Error("Selected Skill path must not contain traversal segments");
+    }
+    return candidate;
+}
+function isSafeSourcePath(candidate) {
+    try {
+        validateSkillDirectoryPath(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isAlreadyExists(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+const GIT_PROTOCOLS = new Set(["git:", "http:", "https:", "ssh:"]);
+export function canonicalizeGitSourceUrl(input) {
+    if (typeof input !== "string" || input.length === 0 || input.trim() !== input) {
+        throw new Error("Git Source URL must be a non-empty URL without surrounding whitespace");
+    }
+    if (/\s/u.test(input) || input.includes("\\") || Array.from(input).some((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code <= 0x1f || code === 0x7f;
+    })) {
+        throw new Error("Git Source URL contains unsafe characters");
+    }
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        throw new Error("Git Source URL is invalid");
+    }
+    if (!GIT_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`Unsupported Git Source protocol: ${parsed.protocol}`);
+    }
+    if (!parsed.hostname || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("Git Source URL contains unsupported or unsafe components");
+    }
+    if (parsed.username && parsed.username !== "git") {
+        throw new Error("Git Source URL credentials are not allowed");
+    }
+    if ((parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.username) {
+        throw new Error("HTTP Git Source URLs cannot contain credentials");
+    }
+    parsed.pathname = parsed.pathname.replace(/\/+$/u, "");
+    if (parsed.pathname === "/" || parsed.pathname.length < 2) {
+        throw new Error("Git Source URL must identify a repository path");
+    }
+    return parsed.toString();
+}
+export function sourceIdForUrl(url) {
+    const canonicalUrl = canonicalizeGitSourceUrl(url);
+    const digest = createHash("sha256").update(canonicalUrl, "utf8").digest("hex").slice(0, 24);
+    return `git:${digest}`;
+}

package/dist/src/path-safety.js

@@ -0,0 +1,31 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+/** True when the paths are equal or one contains the other. Callers normalize first. */
+export function pathsOverlap(left, right) {
+    const relative = path.relative(left, right);
+    const reverse = path.relative(right, left);
+    return relative === "" || reverse === "" ||
+        (!relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) ||
+        (!reverse.startsWith(`..${path.sep}`) && !path.isAbsolute(reverse));
+}
+/** Walks every existing component of a path and rejects the first symbolic link. */
+export async function assertNoSymlinkPath(candidate, label) {
+    const absolute = path.resolve(candidate);
+    const root = path.parse(absolute).root;
+    let current = root;
+    const segments = path.relative(root, absolute).split(path.sep).filter(Boolean);
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        try {
+            if ((await lstat(current)).isSymbolicLink()) {
+                throw new Error(`${label} contains a symbolic link: ${current}`);
+            }
+        }
+        catch (error) {
+            if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+    }
+}

package/dist/src/process-runner.js

@@ -0,0 +1,41 @@
+import { spawn } from "node:child_process";
+/** Runs a command with an argument vector and no shell; rejects only when spawning fails. */
+export function runProcess(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            shell: false,
+            stdio: ["ignore", options.captureStdout ? "pipe" : "ignore", "pipe"],
+        });
+        const stdout = [];
+        let stdoutBytes = 0;
+        let stderr = "";
+        let stderrBytes = 0;
+        let outputTooLarge = false;
+        child.stdout?.on("data", (chunk) => {
+            stdoutBytes += chunk.length;
+            if (options.maxOutputBytes !== undefined && stdoutBytes > options.maxOutputBytes) {
+                outputTooLarge = true;
+                child.kill();
+                return;
+            }
+            stdout.push(chunk);
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            const bytes = Buffer.from(chunk);
+            const remaining = options.maxStderrBytes === undefined
+                ? bytes.length : Math.max(0, options.maxStderrBytes - stderrBytes);
+            stderrBytes += bytes.length;
+            stderr += bytes.subarray(0, remaining).toString("utf8");
+            if (options.maxStderrBytes !== undefined && stderrBytes > options.maxStderrBytes) {
+                outputTooLarge = true;
+                child.kill();
+            }
+        });
+        child.on("error", reject);
+        child.on("close", (code, signal) => {
+            resolve({ code, signal, stdout: Buffer.concat(stdout), stderr, outputTooLarge });
+        });
+    });
+}