@pugi/cli 0.1.0-alpha.10

package/dist/core/skills/sources.js

@@ -0,0 +1,480 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { request } from 'undici';
+import { validateHostnameForFetch } from '../../tools/web-fetch.js';
+/**
+ * Skill / Agent source resolver.
+ *
+ * Translates a `<source>` argument from `pugi skills install <source>`
+ * into a temp directory containing the canonical layout we install
+ * from (`SKILL.md` for skills, `<name>.md` for agents).
+ *
+ * Supported source schemes:
+ *
+ *   1. `gh:owner/repo[/subdir][@ref]`
+ *      → `gh:anthropics/skills/python-coding-standards@main`
+ *      Fetches the GitHub tarball via the public codeload endpoint,
+ *      extracts the requested subtree.
+ *
+ *   2. `https://github.com/<owner>/<repo>/tree/<ref>/<subdir>` (or `/blob/`)
+ *      Normalised to the gh: form above.
+ *
+ *   3. `anthropic:<slug>` — convenience alias for
+ *      `gh:anthropics/skills/<slug>@main`. Hard-coded base; the only
+ *      reason this exists is so operators can copy a slug from the
+ *      Anthropic docs without remembering the org name.
+ *
+ *   4. `npm:<package>` — fetches a tarball from the npm registry,
+ *      extracts, looks for `SKILL.md` at the package root.
+ *
+ *   5. Local path — `./relative` or `/abs/path`. Copied to tmp so the
+ *      caller can mutate the original without affecting install.
+ *
+ *   6. Catalog name — bare slug, queried against
+ *      `https://catalog.pugi.dev/api/skills/<name>`. Returns a 404 →
+ *      we surface a hint pointing at the `gh:anthropics/skills/<name>`
+ *      form rather than crashing.
+ *
+ * Every resolver writes the payload into a fresh temp dir under
+ * `/tmp/pugi-skill-XXXXXX/` (caller cleans up after install completes).
+ * Network failures bubble up as `SOURCE_NETWORK` errors with the host
+ * + status code so the operator can diagnose firewall / proxy issues.
+ */
+const ANTHROPIC_REPO = 'gh:anthropics/skills';
+const CATALOG_BASE = process.env.PUGI_CATALOG_URL ?? 'https://catalog.pugi.dev';
+const FETCH_TIMEOUT_MS = 30_000;
+const MAX_PAYLOAD_BYTES = 50 * 1024 * 1024; // 50 MB cap on any single download
+export async function fetchSource(source) {
+    if (source.startsWith('gh:')) {
+        return fetchGitHub(source.slice(3));
+    }
+    if (source.startsWith('https://github.com/') || source.startsWith('http://github.com/')) {
+        return fetchGitHub(normalizeGithubUrl(source));
+    }
+    if (source.startsWith('anthropic:')) {
+        const slug = source.slice('anthropic:'.length);
+        if (!slug || slug.includes('/')) {
+            throw new Error(`SOURCE_PARSE: anthropic: source needs a bare slug (got "${source}"). Example: anthropic:algorithmic-art`);
+        }
+        // Real layout is `anthropics/skills` repo → `skills/<slug>/SKILL.md`.
+        // Verified 2026-05-25 against the live repo tarball.
+        return fetchGitHub(`${ANTHROPIC_REPO}/skills/${slug}@main`.slice(3));
+    }
+    if (source.startsWith('npm:')) {
+        return fetchNpm(source.slice('npm:'.length));
+    }
+    if (source.startsWith('./') || source.startsWith('../') || isAbsolute(source)) {
+        return fetchLocal(source);
+    }
+    // Bare slug — try the catalog. Catalog might be down or the slug
+    // might not exist; fall through with a clear hint instead of crashing.
+    return fetchCatalog(source);
+}
+function normalizeGithubUrl(url) {
+    // https://github.com/<owner>/<repo>/tree/<ref>/<path...>
+    // https://github.com/<owner>/<repo>/blob/<ref>/<path...>
+    // https://github.com/<owner>/<repo>
+    const match = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\/(?:tree|blob)\/([^/]+)(?:\/(.+?))?)?(?:\.git)?\/?$/);
+    if (!match) {
+        throw new Error(`SOURCE_PARSE: cannot parse GitHub URL "${url}"`);
+    }
+    const [, owner, repo, ref, subdir] = match;
+    const ownerRepo = `${owner}/${repo}`;
+    const subPart = subdir ? `/${subdir}` : '';
+    const refPart = ref ? `@${ref}` : '';
+    return `${ownerRepo}${subPart}${refPart}`;
+}
+function parseGithubSpec(raw) {
+    // <owner>/<repo>[/<subdir>][@<ref>]
+    let ref = 'main';
+    let pathPart = raw;
+    const atIdx = raw.lastIndexOf('@');
+    if (atIdx > 0) {
+        ref = raw.slice(atIdx + 1);
+        pathPart = raw.slice(0, atIdx);
+    }
+    const segments = pathPart.split('/').filter((s) => s.length > 0);
+    if (segments.length < 2) {
+        throw new Error(`SOURCE_PARSE: gh: source needs owner/repo (got "${raw}"). Example: gh:anthropics/skills/python-coding-standards@main`);
+    }
+    const [owner, repo, ...subdirParts] = segments;
+    if (!owner || !repo) {
+        throw new Error(`SOURCE_PARSE: gh: source needs owner/repo (got "${raw}"). Example: gh:anthropics/skills/python-coding-standards@main`);
+    }
+    return {
+        owner,
+        repo,
+        subdir: subdirParts.join('/'),
+        ref,
+    };
+}
+async function fetchGitHub(raw) {
+    const spec = parseGithubSpec(raw);
+    // Use codeload.github.com — the public tarball endpoint requires no
+    // auth for public repos and returns a single .tar.gz of the requested
+    // ref's tree. Private repos are out of scope for α7.0.
+    const tarUrl = `https://codeload.github.com/${spec.owner}/${spec.repo}/tar.gz/${spec.ref}`;
+    const tmpRoot = mkdtempSync(join(tmpdir(), 'pugi-skill-gh-'));
+    const tarPath = join(tmpRoot, 'payload.tar.gz');
+    await downloadToFile(tarUrl, tarPath, `GitHub ${spec.owner}/${spec.repo}@${spec.ref}`);
+    const extractDir = join(tmpRoot, 'extract');
+    mkdirSync(extractDir, { recursive: true });
+    await extractTarball(tarPath, extractDir);
+    // GitHub tarballs unpack into `<repo>-<sanitised-ref>/` at the root.
+    const topLevel = readdirSync(extractDir);
+    if (topLevel.length !== 1) {
+        throw new Error(`SOURCE_TAR: expected a single root directory in tarball, got ${topLevel.length}`);
+    }
+    const rootName = topLevel[0];
+    if (!rootName) {
+        throw new Error('SOURCE_TAR: tarball root directory missing');
+    }
+    const repoRoot = join(extractDir, rootName);
+    const payloadRoot = spec.subdir ? join(repoRoot, spec.subdir) : repoRoot;
+    if (!existsSync(payloadRoot)) {
+        throw new Error(`SOURCE_PATH: subdirectory "${spec.subdir}" not found in ${spec.owner}/${spec.repo}@${spec.ref}`);
+    }
+    const sourceUrl = spec.subdir
+        ? `https://github.com/${spec.owner}/${spec.repo}/tree/${spec.ref}/${spec.subdir}`
+        : `https://github.com/${spec.owner}/${spec.repo}/tree/${spec.ref}`;
+    const inferredKind = inferKind(payloadRoot);
+    // Move payload into a stable directory inside tmpRoot for cleanup
+    // simplicity. The caller deletes tmpRoot when install completes.
+    // verbatimSymlinks: belt-and-braces with the extractTarball filter —
+    // if a symlink somehow survived (shouldn't), don't auto-follow it
+    // into secrets on this hop either.
+    const finalDir = join(tmpRoot, 'payload');
+    cpSync(payloadRoot, finalDir, { recursive: true, verbatimSymlinks: true });
+    return { tmpDir: finalDir, sourceUrl, inferredKind };
+}
+async function fetchNpm(pkg) {
+    // Resolve registry metadata to find the tarball URL of the latest
+    // dist-tag. Honour `npm:<pkg>@<version>` for pinning.
+    let name = pkg;
+    let version = 'latest';
+    const atIdx = pkg.lastIndexOf('@');
+    if (atIdx > 0) {
+        // Watch out for scoped packages — leading '@' is the scope marker.
+        name = pkg.slice(0, atIdx);
+        version = pkg.slice(atIdx + 1);
+    }
+    const registryBase = process.env.NPM_REGISTRY ?? 'https://registry.npmjs.org';
+    const metaUrl = `${registryBase}/${encodeURIComponent(name).replace(/^%40/, '@')}`;
+    const meta = await fetchJson(metaUrl, `npm registry ${name}`);
+    const distTags = meta['dist-tags'];
+    let targetVersion = version;
+    if (distTags && typeof distTags === 'object' && version in distTags) {
+        targetVersion = distTags[version] ?? version;
+    }
+    const versions = meta.versions;
+    const versionMeta = versions?.[targetVersion];
+    const tarballUrl = versionMeta?.dist?.tarball;
+    if (!tarballUrl) {
+        throw new Error(`SOURCE_NPM: no tarball for ${name}@${targetVersion}`);
+    }
+    const tmpRoot = mkdtempSync(join(tmpdir(), 'pugi-skill-npm-'));
+    const tarPath = join(tmpRoot, 'payload.tgz');
+    await downloadToFile(tarballUrl, tarPath, `npm ${name}@${targetVersion}`);
+    const extractDir = join(tmpRoot, 'extract');
+    mkdirSync(extractDir, { recursive: true });
+    await extractTarball(tarPath, extractDir);
+    // npm tarballs unpack as `package/` at the root.
+    const packageRoot = join(extractDir, 'package');
+    if (!existsSync(packageRoot)) {
+        throw new Error('SOURCE_NPM: expected "package/" root in npm tarball');
+    }
+    const inferredKind = inferKind(packageRoot);
+    const finalDir = join(tmpRoot, 'payload');
+    cpSync(packageRoot, finalDir, { recursive: true, verbatimSymlinks: true });
+    return { tmpDir: finalDir, sourceUrl: tarballUrl, inferredKind };
+}
+async function fetchLocal(rawPath) {
+    const abs = isAbsolute(rawPath) ? rawPath : resolve(process.cwd(), rawPath);
+    if (!existsSync(abs)) {
+        throw new Error(`SOURCE_LOCAL: path does not exist: ${abs}`);
+    }
+    const tmpRoot = mkdtempSync(join(tmpdir(), 'pugi-skill-local-'));
+    const finalDir = join(tmpRoot, 'payload');
+    const stat = statSync(abs);
+    if (stat.isFile()) {
+        // Single-file agent install: copy as-is into the tmp dir.
+        mkdirSync(finalDir, { recursive: true });
+        cpSync(abs, join(finalDir, abs.split(sep).pop() ?? 'agent.md'), { verbatimSymlinks: true });
+    }
+    else {
+        cpSync(abs, finalDir, { recursive: true, verbatimSymlinks: true });
+    }
+    const inferredKind = inferKind(finalDir);
+    return { tmpDir: finalDir, sourceUrl: `file://${abs}`, inferredKind };
+}
+async function fetchCatalog(name) {
+    const url = `${CATALOG_BASE}/api/skills/${encodeURIComponent(name)}`;
+    let meta = null;
+    try {
+        meta = await fetchJson(url, `catalog ${name}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`CATALOG_UNREACHABLE: could not query ${CATALOG_BASE} for "${name}" (${message}). Try a direct source like "gh:anthropics/skills/${name}@main".`);
+    }
+    if (!meta || typeof meta !== 'object') {
+        throw new Error(`CATALOG_NOT_FOUND: skill "${name}" not found in ${CATALOG_BASE}. Did you mean "gh:anthropics/skills/${name}@main"?`);
+    }
+    const upstream = meta.source;
+    if (typeof upstream !== 'string') {
+        throw new Error(`CATALOG_INVALID: catalog entry for "${name}" missing "source" field`);
+    }
+    // Catalog payload tells us which canonical source to fetch. Recurse.
+    return fetchSource(upstream);
+}
+/**
+ * Probe the payload root and decide whether it looks like a skill
+ * (`SKILL.md` at root) or an agent (single `.md` at root).
+ * Tie-breaker: SKILL.md wins because Skills are the dominant format.
+ */
+function inferKind(dir) {
+    const entries = readdirSync(dir);
+    if (entries.some((name) => name === 'SKILL.md')) {
+        return 'skill';
+    }
+    const mdFiles = entries.filter((name) => name.toLowerCase().endsWith('.md'));
+    if (mdFiles.length === 1) {
+        return 'agent';
+    }
+    if (mdFiles.length > 1) {
+        // Multiple markdowns without a SKILL.md — assume skill, the loader
+        // will throw a clear "missing SKILL.md" error.
+        return 'skill';
+    }
+    return 'skill';
+}
+const MAX_REDIRECTS = 5;
+/**
+ * Internal redirect-following GET. undici@8 does not honour
+ * `maxRedirections` on the top-level `request` call (it lives on the
+ * Agent), so we walk redirects manually. Hop cap prevents loops.
+ */
+async function requestFollow(url) {
+    let currentUrl = url;
+    // SSRF guard: every hop (initial + each redirect target) must resolve
+    // to a public address. The redirect-following loop below re-runs the
+    // guard on the post-redirect URL so a 302 → http://169.254.169.254/
+    // (AWS metadata service) cannot smuggle a private fetch.
+    //
+    // We reuse the shared `validateHostnameForFetch` from web-fetch.ts so
+    // there is one canonical IPv4/IPv6 blocklist + DNS-resolution check
+    // across every Pugi outbound surface (web_fetch tool, skills installer,
+    // future: webhook delivery). Drift between two copies of that block
+    // list would be a real footgun — the SSRF cheat-sheet covers ~10
+    // ranges and missing one (e.g. SIIT/NAT64) is exactly the class of
+    // bug Codex caught in PR #349.
+    // Initial scheme — locked for entire redirect chain. Codex P2 review
+    // (PR #362 v2): an HTTPS source that 302s к public http:// URL would
+    // otherwise be fetched cleartext, MITM tampers payload. Stay TLS.
+    const initialScheme = new URL(currentUrl).protocol;
+    await guardOutboundUrl(currentUrl, 'initial request', initialScheme);
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const response = await request(currentUrl, {
+            method: 'GET',
+            headersTimeout: FETCH_TIMEOUT_MS,
+            bodyTimeout: FETCH_TIMEOUT_MS,
+        });
+        if (response.statusCode >= 300 && response.statusCode < 400) {
+            const loc = response.headers['location'];
+            const locStr = Array.isArray(loc) ? loc[0] : loc;
+            if (typeof locStr !== 'string' || locStr.length === 0) {
+                return response;
+            }
+            // Drain body so socket reusable.
+            await response.body.dump();
+            const nextUrl = new URL(locStr, currentUrl).toString();
+            await guardOutboundUrl(nextUrl, `redirect from ${currentUrl}`, initialScheme);
+            currentUrl = nextUrl;
+            continue;
+        }
+        return response;
+    }
+    throw new Error(`SOURCE_NETWORK: redirect limit (${MAX_REDIRECTS}) exceeded`);
+}
+// P2 DNS rebinding follow-up: pinned-address Dispatcher с undici lookup
+// hook. Filed task — TOCTOU window microseconds + needs attacker DNS
+// control. Acceptable v1 trade-off; not blocking initial ship.
+/**
+ * SSRF gate for one outbound URL hop. Throws `SOURCE_SSRF` when the
+ * URL is malformed, uses a non-http(s) scheme, or resolves to any
+ * private/loopback/link-local/CGNAT/metadata range.
+ *
+ * Called from `requestFollow` on the initial URL and every redirect
+ * target so a 302 → http://10.0.0.5/ (or → http://169.254.169.254/)
+ * cannot bypass the gate. Also rejects scheme downgrades (https → http)
+ * so a redirect that takes us off TLS aborts loudly instead of silently.
+ */
+async function guardOutboundUrl(rawUrl, label, initialScheme) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`SOURCE_SSRF: ${label} URL is malformed: ${rawUrl}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`SOURCE_SSRF: ${label} uses unsupported scheme ${parsed.protocol} (only http/https).`);
+    }
+    // Codex P2 PR #362 v2: HTTPS source MUST NOT downgrade к HTTP across
+    // redirect chain — would let MITM tamper с payload after the initial
+    // TLS hop. Once we started TLS, stay TLS.
+    if (initialScheme === 'https:' && parsed.protocol === 'http:') {
+        throw new Error(`SOURCE_SSRF: ${label} attempts HTTPS→HTTP downgrade — refused (payload integrity required).`);
+    }
+    const verdict = await validateHostnameForFetch(parsed.hostname);
+    if (verdict !== null) {
+        throw new Error(`SOURCE_SSRF: ${label} refused — ${verdict}`);
+    }
+}
+async function downloadToFile(url, outPath, label) {
+    try {
+        const response = await requestFollow(url);
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+            const body = await response.body.text();
+            const err = new Error(`SOURCE_NETWORK: ${label} returned HTTP ${response.statusCode}. ${body.slice(0, 200)}`);
+            err.status = response.statusCode;
+            throw err;
+        }
+        mkdirSync(dirname(outPath), { recursive: true });
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of response.body) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buf.byteLength;
+            if (total > MAX_PAYLOAD_BYTES) {
+                throw new Error(`SOURCE_SIZE: ${label} payload exceeded ${Math.round(MAX_PAYLOAD_BYTES / (1024 * 1024))}MB cap`);
+            }
+            chunks.push(buf);
+        }
+        writeFileSync(outPath, Buffer.concat(chunks));
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('SOURCE_')) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`SOURCE_NETWORK: ${label} fetch failed (${message})`);
+    }
+}
+async function fetchJson(url, label) {
+    const response = await requestFollow(url);
+    if (response.statusCode === 404) {
+        throw new Error(`SOURCE_NOT_FOUND: ${label} returned HTTP 404`);
+    }
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        throw new Error(`SOURCE_NETWORK: ${label} returned HTTP ${response.statusCode}`);
+    }
+    const text = await response.body.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`SOURCE_PARSE: ${label} returned invalid JSON`);
+    }
+}
+async function extractTarball(tarPath, destDir) {
+    // Use the `tar` package (already on disk via transitive hoisting) so
+    // we get streaming gunzip + extraction without a custom parser.
+    // Dynamic import keeps the dependency lazy: operators who never
+    // install a skill never load tar.
+    //
+    // Security model: we collect filter violations in `violations`
+    // rather than throwing inside the filter callback. node-tar v6
+    // dispatches the filter from inside the streaming parser; a sync
+    // throw there surfaces as an uncaughtException because the parser's
+    // internal event chain is not awaited by tar.x's promise. Skipping
+    // (return false) keeps the stream healthy; we abort after extraction
+    // completes so no hostile entry is ever materialised to disk AND
+    // the operator sees a precise error.
+    const tarModule = await loadTarModule();
+    const violations = [];
+    await tarModule.x({
+        file: tarPath,
+        cwd: destDir,
+        // strict: true rejects bad records (bad checksums, truncated
+        // headers, mtime-newer-than-now). Required for defense-in-depth
+        // even though our filter below catches the high-value cases.
+        strict: true,
+        // Filter returns false to skip the entry. We accumulate the
+        // violations and throw AFTER extraction completes (see below).
+        filter: (path, entry) => {
+            // 1. Block any symlink or hardlink — these are the tar-slip
+            //    vectors. A symlink to ../../home/user/.ssh + a follow-up
+            //    write to that symlink would exfil secrets.
+            if (entry.type === 'SymbolicLink' || entry.type === 'Link') {
+                violations.push(`SOURCE_TAR_SYMLINK: tarball contains ${entry.type} entry (${path} → ${entry.linkpath ?? '?'}). Refusing extraction.`);
+                return false;
+            }
+            // 2. Block absolute paths — `tar` strips the leading "/" in
+            //    permissive mode and writes anyway. We refuse such entries.
+            if (path.startsWith('/')) {
+                violations.push(`SOURCE_TAR_ABSOLUTE: tarball entry has absolute path: ${path}`);
+                return false;
+            }
+            // 3. Block parent-traversal segments. `..` as a path segment
+            //    cannot be present in any legitimate skill/agent payload.
+            const segments = path.split(/[\\/]+/);
+            if (segments.includes('..')) {
+                violations.push(`SOURCE_TAR_TRAVERSAL: tarball entry has parent-traversal segment: ${path}`);
+                return false;
+            }
+            // 4. Block null-byte truncation attempts.
+            if (path.includes('\0')) {
+                violations.push(`SOURCE_TAR_NULLBYTE: tarball entry contains null byte: ${JSON.stringify(path)}`);
+                return false;
+            }
+            return true;
+        },
+    });
+    if (violations.length > 0) {
+        // Throw the FIRST violation verbatim so callers can pattern-match
+        // on the specific code (SOURCE_TAR_SYMLINK / _ABSOLUTE / _TRAVERSAL
+        // / _NULLBYTE). Append a count summary when there are multiple.
+        const head = violations[0] ?? 'SOURCE_TAR: unspecified violation';
+        if (violations.length === 1)
+            throw new Error(head);
+        throw new Error(`${head} (and ${violations.length - 1} more refused entries)`);
+    }
+}
+/**
+ * Lazy-loaded `tar` module reference. Decoupled so tests can stub it.
+ */
+let cachedTarModule = null;
+async function loadTarModule() {
+    if (cachedTarModule)
+        return cachedTarModule;
+    // `tar` is a CJS module exporting `x`/`c`/`u`/`t`. We type it loosely
+    // because we only need the extract entry-point.
+    const imported = (await import('tar'));
+    cachedTarModule = imported;
+    return imported;
+}
+/**
+ * Best-effort tmp cleanup. Never throws — install path must succeed
+ * even when the OS refuses to delete a tmp dir (rare but possible on
+ * Windows under tests).
+ */
+export function cleanupTmp(tmpDir) {
+    try {
+        // Walk up to the mkdtemp parent: tmpDir was created by either
+        // moving into `<root>/payload` or by reading `<root>/payload`. We
+        // delete the parent so the tarball + extract dir also go away.
+        const parent = dirname(tmpDir);
+        if (parent.includes('pugi-skill-')) {
+            rmSync(parent, { recursive: true, force: true });
+        }
+        else {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+    }
+    catch {
+        /* swallow */
+    }
+}
+//# sourceMappingURL=sources.js.map

package/dist/core/skills/trust.js

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+const trustEntrySchema = z.object({
+    kind: z.enum(['skill', 'agent']),
+    scope: z.enum(['global', 'workspace']),
+    name: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    source: z.string().min(1),
+    signedAt: z.string().datetime(),
+    signedBy: z.string().min(1),
+});
+const trustRegistrySchema = z.object({
+    schema: z.number().int().positive().default(1),
+    entries: z.array(trustEntrySchema).default([]),
+});
+const TRUST_REGISTRY_FILENAME = 'trust.json';
+function registryPath() {
+    const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(home, TRUST_REGISTRY_FILENAME);
+}
+function readRegistry() {
+    const path = registryPath();
+    if (!existsSync(path)) {
+        return { schema: 1, entries: [] };
+    }
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '') {
+        return { schema: 1, entries: [] };
+    }
+    // Recovery path for a corrupt trust.json. Without this, a single
+    // malformed entry (truncated write on power loss, partial disk
+    // corruption, manual edit gone wrong) would brick every skill +
+    // agent surface: every command calls readRegistry. We back up the
+    // bad file (preserving forensic evidence) and reset to an empty
+    // registry. The operator must re-trust on next install — strictly
+    // safer than auto-trusting on-disk payloads.
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const backup = `${path}.corrupt-${Date.now()}`;
+        try {
+            renameSync(path, backup);
+        }
+        catch {
+            /* swallow — best-effort backup */
+        }
+        process.stderr.write(`[pugi] trust.json invalid JSON: ${message}. Backed up to ${backup}. Resetting to empty registry.\n`);
+        return { schema: 1, entries: [] };
+    }
+    try {
+        return trustRegistrySchema.parse(parsedJson);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const backup = `${path}.corrupt-${Date.now()}`;
+        try {
+            renameSync(path, backup);
+        }
+        catch {
+            /* swallow */
+        }
+        process.stderr.write(`[pugi] trust.json failed schema validation: ${message}. Backed up to ${backup}. Resetting to empty registry.\n`);
+        return { schema: 1, entries: [] };
+    }
+}
+function writeRegistry(registry) {
+    const path = registryPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // Atomic write: write to a unique temp file, fsync via writeFileSync's
+    // default behaviour, then rename(2) over the live path. POSIX rename
+    // is atomic on the same filesystem, so a crash between write+rename
+    // leaves trust.json EITHER pre-state OR post-state — never a
+    // half-written file that would trip the schema parser on the next
+    // read. Mode 0o600 — registry reveals which third-party skills the
+    // operator has approved. Parity with the other Pugi trust ledgers.
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmp, path);
+}
+function entryKey(kind, scope, name) {
+    return `${kind}:${scope}:${name}`;
+}
+/**
+ * Walk a directory tree and produce a stable sha256 over its contents.
+ * Sorting filenames gives reproducible hashes across filesystems with
+ * different `readdir` orderings (ext4 vs apfs).
+ *
+ * Files are hashed as `<relative-path>\0<bytes>\0` segments so a file
+ * rename inside the tree is detectable even when total bytes are equal.
+ */
+export function hashSkillDir(rootDir) {
+    const hasher = createHash('sha256');
+    const walk = (dir, prefix) => {
+        const names = readdirSync(dir).sort((a, b) => a.localeCompare(b));
+        for (const name of names) {
+            const full = join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const stat = statSync(full);
+            if (stat.isDirectory()) {
+                walk(full, rel);
+            }
+            else if (stat.isFile()) {
+                hasher.update(rel);
+                hasher.update('\0');
+                hasher.update(readFileSync(full));
+                hasher.update('\0');
+            }
+        }
+    };
+    walk(rootDir, '');
+    return hasher.digest('hex');
+}
+/**
+ * sha256 of a single file — used for agent payloads (single .md file
+ * at `~/.pugi/agents/<slug>.md`).
+ */
+export function hashAgentFile(filePath) {
+    const hasher = createHash('sha256');
+    hasher.update(readFileSync(filePath));
+    return hasher.digest('hex');
+}
+export async function recordTrust(input) {
+    const registry = readRegistry();
+    const key = entryKey(input.kind, input.scope, input.name);
+    const filtered = registry.entries.filter((entry) => entryKey(entry.kind, entry.scope, entry.name) !== key);
+    filtered.push({
+        kind: input.kind,
+        scope: input.scope,
+        name: input.name,
+        sha256: input.sha256,
+        source: input.source,
+        signedAt: new Date().toISOString(),
+        signedBy: input.signedBy,
+    });
+    writeRegistry({ schema: registry.schema, entries: filtered });
+}
+export async function getTrust(kind, scope, name) {
+    const registry = readRegistry();
+    const key = entryKey(kind, scope, name);
+    return (registry.entries.find((entry) => entryKey(entry.kind, entry.scope, entry.name) === key) ??
+        null);
+}
+export async function revokeTrust(kind, scope, name) {
+    const registry = readRegistry();
+    const key = entryKey(kind, scope, name);
+    const filtered = registry.entries.filter((entry) => entryKey(entry.kind, entry.scope, entry.name) !== key);
+    writeRegistry({ schema: registry.schema, entries: filtered });
+}
+export async function listTrust() {
+    const registry = readRegistry();
+    return [...registry.entries];
+}
+export async function verifyTrust(kind, scope, name, actualSha256) {
+    const entry = await getTrust(kind, scope, name);
+    if (!entry) {
+        return { status: 'unsigned' };
+    }
+    if (entry.sha256 !== actualSha256) {
+        return { status: 'mismatch', recorded: entry.sha256, actual: actualSha256 };
+    }
+    return { status: 'trusted', signedAt: entry.signedAt, signedBy: entry.signedBy };
+}
+//# sourceMappingURL=trust.js.map