@squadrules/mcp 5.16.0 → 5.17.0

package/dist/tools/artifact-local-cache.js

@@ -0,0 +1,315 @@
+/**
+ * STDIO local artifact cache (ADR 0040).
+ *
+ * The stdio transport has no HTTP listener, so the running server writes the
+ * verified artifact bytes it already holds (`AdapterArtifactMetadata.text`) to a
+ * private per-process namespace under `os.tmpdir()` and returns a `file://` URL.
+ * That gives linked-artifact materialization one transport-neutral URL contract
+ * shared with the HTTP capability URL — no CLI, no second backend, and no
+ * artifact bytes (raw or base64) through MCP context.
+ *
+ * Each server process owns exactly one `0700` namespace, publishes with digest
+ * verification and atomic rename, leases each returned URL for
+ * `SQUADRULES_EXPORT_DOWNLOAD_TTL_SEC` after its last issuance, admits within
+ * per-instance entry/byte quotas (failing the whole batch rather than evicting a
+ * live lease), and scavenges only namespaces whose owner PID is dead. Helpers,
+ * quotas, and error types live in `artifact-local-cache-support.ts`.
+ */
+import { randomBytes } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SQUADRULES_EXPORT_DOWNLOAD_TTL_SEC } from '../config/export-download-settings.js';
+import { sha256Hex } from './skill-export/sha256.js';
+import { ArtifactCacheDigestError, ArtifactCacheError, ArtifactCacheQuotaError, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, DEFAULT_ORPHAN_GRACE_SEC, LEASE_SUFFIX, MAINTENANCE_INTERVAL_MS, NAMESPACE_PREFIX, SHA256_RE, UUID_RE, defaultRootDir, envInt, extensionFor, ownerUid, processMayBeAlive } from './artifact-local-cache-support.js';
+export { ArtifactCacheDigestError, ArtifactCacheError, ArtifactCacheQuotaError };
+/**
+ * Read-only open flags that refuse to follow a trailing symlink where the
+ * platform exposes `O_NOFOLLOW` (POSIX): a symlink then fails the open with
+ * `ELOOP` instead of resolving to its target. On a platform without the flag the
+ * bitwise OR degrades to a plain read-only open.
+ */
+const READ_NOFOLLOW = fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW;
+export class ArtifactLocalCache {
+    rootDir;
+    ttlSec;
+    maxEntries;
+    maxBytes;
+    orphanGraceSec;
+    now;
+    namespace = null;
+    lock = Promise.resolve();
+    maintenance = null;
+    constructor(options = {}) {
+        this.rootDir = options.rootDir ?? defaultRootDir();
+        this.ttlSec = options.ttlSec ?? envInt('SQUADRULES_ARTIFACT_CACHE_TTL_SEC', SQUADRULES_EXPORT_DOWNLOAD_TTL_SEC);
+        this.maxEntries = options.maxEntries ?? envInt('SQUADRULES_ARTIFACT_CACHE_MAX_ENTRIES', DEFAULT_MAX_ENTRIES);
+        this.maxBytes = options.maxBytes ?? envInt('SQUADRULES_ARTIFACT_CACHE_MAX_BYTES', DEFAULT_MAX_BYTES);
+        this.orphanGraceSec =
+            options.orphanGraceSec ?? envInt('SQUADRULES_ARTIFACT_CACHE_ORPHAN_GRACE_SEC', DEFAULT_ORPHAN_GRACE_SEC);
+        this.now = options.now ?? (() => Date.now());
+    }
+    /**
+     * Verify and publish a whole activation batch, or fail it entirely. Digest
+     * verification and quota preflight run before any write, so a bad artifact or
+     * an over-quota batch never leaves a partially usable cache behind.
+     */
+    async publishBatch(entries) {
+        return this.withLock(async () => {
+            const ns = await this.ensureNamespace();
+            const nowSec = Math.floor(this.now() / 1000);
+            const prepared = entries.map((entry) => this.prepare(entry));
+            await this.pruneExpiredIn(ns, nowSec);
+            this.preflightQuota(await this.listLeases(ns), prepared, nowSec);
+            const out = new Map();
+            for (const item of prepared) {
+                out.set(item.uuid, await this.publishOne(ns, item, nowSec));
+            }
+            return out;
+        });
+    }
+    /** Remove entries whose lease has expired. Returns the number pruned. */
+    async pruneExpired() {
+        return this.withLock(async () => {
+            if (!this.namespace)
+                return 0;
+            return this.pruneExpiredIn(this.namespace, Math.floor(this.now() / 1000));
+        });
+    }
+    /**
+     * Scavenge namespaces whose owner PID is dead, whose newest lease has expired,
+     * and whose grace period has passed. Never touches a live process's namespace,
+     * including this one; ambiguous liveness is treated as live.
+     */
+    async scavengeOrphans() {
+        return this.withLock(async () => {
+            await this.ensureRoot();
+            const nowSec = Math.floor(this.now() / 1000);
+            let removed = 0;
+            for (const entry of await fsp.readdir(this.rootDir, { withFileTypes: true })) {
+                if (!entry.name.startsWith(NAMESPACE_PREFIX) || !entry.isDirectory())
+                    continue;
+                const full = path.join(this.rootDir, entry.name);
+                if (full === this.namespace)
+                    continue;
+                const pid = Number.parseInt(entry.name.slice(NAMESPACE_PREFIX.length).split('-')[0] ?? '', 10);
+                if (!Number.isFinite(pid) || pid === process.pid || processMayBeAlive(pid))
+                    continue;
+                const newest = await this.newestLeaseExpiry(full);
+                const mtimeSec = Math.floor((await fsp.lstat(full)).mtimeMs / 1000);
+                if (nowSec < Math.max(newest, mtimeSec) + this.orphanGraceSec)
+                    continue;
+                await fsp.rm(full, { recursive: true, force: true });
+                removed += 1;
+            }
+            return removed;
+        });
+    }
+    startPeriodicMaintenance(intervalMs = MAINTENANCE_INTERVAL_MS) {
+        if (this.maintenance)
+            return;
+        const timer = setInterval(() => {
+            void this.runMaintenance();
+        }, intervalMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        this.maintenance = timer;
+    }
+    stopPeriodicMaintenance() {
+        if (this.maintenance) {
+            clearInterval(this.maintenance);
+            this.maintenance = null;
+        }
+    }
+    async runMaintenance() {
+        try {
+            await this.pruneExpired();
+            await this.scavengeOrphans();
+        }
+        catch {
+            // Best-effort maintenance; a failure here must not crash the server.
+        }
+    }
+    prepare(entry) {
+        if (!UUID_RE.test(entry.artifactUuid)) {
+            throw new ArtifactCacheError('artifact identity is not a UUID; refusing to cache it');
+        }
+        if (!SHA256_RE.test(entry.sha256)) {
+            throw new ArtifactCacheError(`artifact ${entry.artifactUuid} has no valid SHA-256; refusing to cache it`);
+        }
+        const sha256 = entry.sha256.toLowerCase();
+        const buf = Buffer.from(entry.text, 'utf8');
+        if (sha256Hex(buf) !== sha256) {
+            throw new ArtifactCacheDigestError(`artifact ${entry.artifactUuid} bytes do not match their stored SHA-256; re-activate to refresh the source`);
+        }
+        const ext = extensionFor(entry.relativePath, entry.contentType);
+        return { uuid: entry.artifactUuid, name: `${entry.artifactUuid}-${sha256}.${ext}`, buf, bytes: buf.length };
+    }
+    preflightQuota(leases, prepared, nowSec) {
+        const live = new Map();
+        for (const lease of leases) {
+            if (lease.expiresSec > nowSec)
+                live.set(lease.name, lease);
+        }
+        let entries = live.size;
+        let bytes = 0;
+        for (const lease of live.values())
+            bytes += lease.bytes;
+        const counted = new Set();
+        for (const item of prepared) {
+            if (live.has(item.name) || counted.has(item.name))
+                continue;
+            counted.add(item.name);
+            entries += 1;
+            bytes += item.bytes;
+        }
+        if (entries > this.maxEntries || bytes > this.maxBytes) {
+            throw new ArtifactCacheQuotaError(`linked-artifact batch does not fit the local cache quota (${entries} entries / ${bytes} bytes); ` +
+                'no cached artifact is evicted while its lease is live — re-activate after cached entries expire');
+        }
+    }
+    async publishOne(ns, item, nowSec) {
+        const finalPath = path.join(ns, item.name);
+        const prior = await this.readLease(`${finalPath}${LEASE_SUFFIX}`);
+        if (!(await this.matchesDigest(finalPath, sha256Hex(item.buf)))) {
+            await this.writeFileAtomic(finalPath, item.buf, 0o600);
+        }
+        const lease = {
+            v: 1,
+            name: item.name,
+            bytes: item.bytes,
+            createdSec: prior?.createdSec ?? nowSec,
+            lastIssuedSec: nowSec,
+            expiresSec: nowSec + this.ttlSec
+        };
+        await this.writeFileAtomic(`${finalPath}${LEASE_SUFFIX}`, Buffer.from(JSON.stringify(lease), 'utf8'), 0o600);
+        return { url: pathToFileURL(finalPath).href, path: finalPath, bytes: item.bytes };
+    }
+    /**
+     * True only when `finalPath` is an existing regular file whose bytes match the
+     * digest. The path is resolved exactly once: it is opened read-only with
+     * `O_NOFOLLOW` (so a symlink fails the open with `ELOOP` instead of being
+     * followed), and both the type check and the read run through that single
+     * descriptor. Operating on the opened fd instead of re-resolving the path after
+     * a stat removes the check-then-read race on `finalPath`.
+     */
+    async matchesDigest(finalPath, sha256) {
+        const handle = await fsp.open(finalPath, READ_NOFOLLOW).catch((err) => {
+            if (err.code === 'ELOOP') {
+                throw new ArtifactCacheError('a cache entry is a symlink; refusing to reuse or overwrite it');
+            }
+            return null;
+        });
+        if (handle === null)
+            return false;
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile())
+                return false;
+            return sha256Hex(await handle.readFile()) === sha256;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async ensureNamespace() {
+        if (this.namespace)
+            return this.namespace;
+        await this.ensureRoot();
+        const token = randomBytes(8).toString('hex');
+        const ns = await fsp.mkdtemp(path.join(this.rootDir, `${NAMESPACE_PREFIX}${process.pid}-${token}-`));
+        await fsp.chmod(ns, 0o700);
+        this.namespace = ns;
+        return ns;
+    }
+    async ensureRoot() {
+        await fsp.mkdir(this.rootDir, { recursive: true, mode: 0o700 });
+        const stat = await fsp.lstat(this.rootDir);
+        if (stat.isSymbolicLink())
+            throw new ArtifactCacheError('the artifact cache root is a symlink; refusing to use it');
+        if (!stat.isDirectory())
+            throw new ArtifactCacheError('the artifact cache root is not a directory');
+        const uid = ownerUid();
+        if (uid !== undefined && stat.uid !== uid) {
+            throw new ArtifactCacheError('the artifact cache root is owned by another user; refusing to use it');
+        }
+        if (stat.mode & 0o077)
+            await fsp.chmod(this.rootDir, 0o700);
+    }
+    async writeFileAtomic(target, data, mode) {
+        const tmp = `${target}.tmp-${randomBytes(6).toString('hex')}`;
+        const handle = await fsp.open(tmp, 'w', mode);
+        try {
+            await handle.writeFile(data);
+            await handle.chmod(mode);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fsp.rename(tmp, target);
+    }
+    async readLease(leasePath) {
+        try {
+            const parsed = JSON.parse(await fsp.readFile(leasePath, 'utf8'));
+            return parsed && typeof parsed === 'object' && parsed.v === 1 ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async listLeases(ns) {
+        const leases = [];
+        let names;
+        try {
+            names = await fsp.readdir(ns);
+        }
+        catch {
+            return leases;
+        }
+        for (const name of names) {
+            if (!name.endsWith(LEASE_SUFFIX))
+                continue;
+            const lease = await this.readLease(path.join(ns, name));
+            if (lease)
+                leases.push(lease);
+        }
+        return leases;
+    }
+    async pruneExpiredIn(ns, nowSec) {
+        let removed = 0;
+        for (const lease of await this.listLeases(ns)) {
+            if (lease.expiresSec > nowSec)
+                continue;
+            const dataPath = path.join(ns, lease.name);
+            await fsp.rm(dataPath, { force: true });
+            await fsp.rm(`${dataPath}${LEASE_SUFFIX}`, { force: true });
+            removed += 1;
+        }
+        return removed;
+    }
+    async newestLeaseExpiry(ns) {
+        let newest = 0;
+        for (const lease of await this.listLeases(ns)) {
+            if (lease.expiresSec > newest)
+                newest = lease.expiresSec;
+        }
+        return newest;
+    }
+    async withLock(fn) {
+        const run = this.lock.then(fn, fn);
+        this.lock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+let singleton;
+/** The process-wide stdio cache; created on first use with periodic maintenance. */
+export function getArtifactLocalCache() {
+    if (!singleton) {
+        singleton = new ArtifactLocalCache();
+        singleton.startPeriodicMaintenance();
+    }
+    return singleton;
+}
+//# sourceMappingURL=artifact-local-cache.js.map

package/dist/tools/artifact-local-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-local-cache.js","sourceRoot":"","sources":["../../src/tools/artifact-local-cache.ts"],"names":[],"mappings":"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"}

package/dist/tools/artifact-materialize-command.d.ts

@@ -1,41 +1,47 @@
 /**
- * Build the materialize instruction for one adapter-linked artifact.
+ * Build the materialize instruction for one adapter-linked artifact (ADR 0040).
  *
  * Byte-exactness is framework work, not agent work: the instruction carries an
- * exact shell line (`cmd`) that writes, verifies, and marks the file executable,
- * so the agent never re-types artifact bytes through an editor or a heredoc
- * (SquadRules/mcp#231). The byte source depends on the transport: HTTP serves the
- * stored bytes itself, stdio has no listener and goes through the `export` tool.
+ * exact shell line (`cmd`) that downloads the artifact from a transport-neutral
+ * URL, verifies its digest, marks it `0700`, and publishes it atomically, so the
+ * agent never re-types artifact bytes through an editor or a heredoc
+ * (SquadRules/mcp#231). The URL is a `file://` cache path on stdio and a
+ * short-lived capability URL on HTTP; this builder does not branch on transport
+ * because `curl` fetches both. The destination tree is caller-owned and trusted:
+ * a POSIX shell alone cannot close time-of-check/time-of-use races against a
+ * hostile concurrent writer, so `cmd` rejects symlinked roots/ancestors and
+ * re-checks containment after resolution, but does not claim race-free isolation.
  */
 export declare const SQUADRULES_LOCAL_ARTIFACT_DIR_ENV = "SQUADRULES_LOCAL_ARTIFACT_DIR";
 export interface ArtifactMaterializeInput {
-    transport: 'http' | 'stdio';
-    /** Artifact URI accepted by the `export` tool: `squadrules://artifact/{slug|uuid}`. */
-    artifactUri: string;
-    /** Capability download URL served by the HTTP transport. */
-    downloadUrl: string;
+    /** Transport-neutral source URL `cmd` curls: a `file://` cache path (stdio) or an `http(s)://` capability URL (HTTP). */
+    url: string;
     /** Skill-root-relative artifact path; the payload lands here under the artifact dir. */
     relativePath: string;
-    /** SHA-256 hex of the stored artifact bytes. */
+    /** SHA-256 hex of the stored artifact bytes; `cmd` verifies the download against it. */
     sha256: string;
 }
 export interface MaterializeInstruction {
-    /** MCP tool that returns the bytes (required on stdio, a read option on HTTP). */
-    tool: 'export';
-    arguments: {
-        uri: string;
-        format: 'source';
-        /** Set on stdio: raw text cannot be re-written byte-exactly by an agent. */
-        delivery?: 'inline_base64';
-    };
+    /** Always `url`: the bytes are fetched from `url` by `cmd` on every transport. */
+    method: 'url';
+    /** Source URL `cmd` downloads (a `file://` cache path on stdio, a capability URL on HTTP). */
+    url: string;
     /** Absolute path where the bytes land (uses $SQUADRULES_LOCAL_ARTIFACT_DIR). */
     out: string;
     /** SHA-256 digest `cmd` verifies; check it against the same value. */
     sha256: string;
-    /** File permissions the agent must set after verification. */
+    /** File permissions `cmd` sets on the verified bytes before publishing. */
     chmod: '700';
-    /** Exact POSIX shell line that writes the file, verifies the digest, and sets permissions. */
+    /** Exact POSIX shell line that downloads, verifies, chmods, and atomically publishes. Run it verbatim. */
     cmd: string;
 }
+/**
+ * Wrap a value in single quotes for safe interpolation into a POSIX shell
+ * command. Every embedded `'` becomes the four-character sequence `'\''`, which
+ * closes the quoted string, adds an escaped quote, and reopens it. Single quotes
+ * suppress `$`, backtick, glob, and word-splitting expansion, so any URL — even
+ * one carrying adversarial characters — reaches `curl` as a literal argument.
+ */
+export declare function shellSingleQuote(value: string): string;
 export declare function buildArtifactMaterializeInstruction(input: ArtifactMaterializeInput): MaterializeInstruction;
 //# sourceMappingURL=artifact-materialize-command.d.ts.map

package/dist/tools/artifact-materialize-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-materialize-command.d.ts","sourceRoot":"","sources":["../../src/tools/artifact-materialize-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iCAAiC,kCAAkC,CAAC;AAEjF,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,QAAQ,CAAC;QACjB,4EAA4E;QAC5E,QAAQ,CAAC,EAAE,eAAe,CAAC;KAC5B,CAAC;IACF,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,KAAK,EAAE,KAAK,CAAC;IACb,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,wBAAwB,GAAG,sBAAsB,CAmB3G"}
+{"version":3,"file":"artifact-materialize-command.d.ts","sourceRoot":"","sources":["../../src/tools/artifact-materialize-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,iCAAiC,kCAAkC,CAAC;AAKjF,MAAM,WAAW,wBAAwB;IACvC,yHAAyH;IACzH,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,MAAM,EAAE,KAAK,CAAC;IACd,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;IACb,0GAA0G;IAC1G,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,wBAAwB,GAAG,sBAAsB,CA0D3G"}

package/dist/tools/artifact-materialize-command.js

@@ -1,29 +1,80 @@
 /**
- * Build the materialize instruction for one adapter-linked artifact.
+ * Build the materialize instruction for one adapter-linked artifact (ADR 0040).
  *
  * Byte-exactness is framework work, not agent work: the instruction carries an
- * exact shell line (`cmd`) that writes, verifies, and marks the file executable,
- * so the agent never re-types artifact bytes through an editor or a heredoc
- * (SquadRules/mcp#231). The byte source depends on the transport: HTTP serves the
- * stored bytes itself, stdio has no listener and goes through the `export` tool.
+ * exact shell line (`cmd`) that downloads the artifact from a transport-neutral
+ * URL, verifies its digest, marks it `0700`, and publishes it atomically, so the
+ * agent never re-types artifact bytes through an editor or a heredoc
+ * (SquadRules/mcp#231). The URL is a `file://` cache path on stdio and a
+ * short-lived capability URL on HTTP; this builder does not branch on transport
+ * because `curl` fetches both. The destination tree is caller-owned and trusted:
+ * a POSIX shell alone cannot close time-of-check/time-of-use races against a
+ * hostile concurrent writer, so `cmd` rejects symlinked roots/ancestors and
+ * re-checks containment after resolution, but does not claim race-free isolation.
  */
+import { normalizeMaterializeRelativePath } from './artifact-relative-path.js';
 export const SQUADRULES_LOCAL_ARTIFACT_DIR_ENV = 'SQUADRULES_LOCAL_ARTIFACT_DIR';
+const SHA256_RE = /^[a-f0-9]{64}$/i;
+const URL_SCHEME_RE = /^(?:https?|file):\/\//i;
+/**
+ * Wrap a value in single quotes for safe interpolation into a POSIX shell
+ * command. Every embedded `'` becomes the four-character sequence `'\''`, which
+ * closes the quoted string, adds an escaped quote, and reopens it. Single quotes
+ * suppress `$`, backtick, glob, and word-splitting expansion, so any URL — even
+ * one carrying adversarial characters — reaches `curl` as a literal argument.
+ */
+export function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
 export function buildArtifactMaterializeInstruction(input) {
-    const outPath = `$${SQUADRULES_LOCAL_ARTIFACT_DIR_ENV}/${input.relativePath}`;
-    const outRef = `"${outPath}"`;
-    const bytes = input.transport === 'http'
-        ? `curl -fsS -o ${outRef} ${JSON.stringify(input.downloadUrl)}`
-        : `: "\${B64:?B64 must hold the export response content field}" && printf '%s' "$B64" | base64 -d > ${outRef}`;
-    const verify = `printf '%s  %s\\n' '${input.sha256}' ${outRef} | sha256sum -c`;
-    return {
-        tool: 'export',
-        arguments: input.transport === 'http'
-            ? { uri: input.artifactUri, format: 'source' }
-            : { uri: input.artifactUri, format: 'source', delivery: 'inline_base64' },
-        out: outPath,
-        sha256: input.sha256,
-        chmod: '700',
-        cmd: `mkdir -p "$(dirname ${outRef})" && ${bytes} && ${verify} && chmod 700 ${outRef}`
-    };
+    const relativePath = normalizeMaterializeRelativePath(input.relativePath);
+    if (relativePath === null) {
+        throw new Error(`refusing to build a materialize command for an unsafe artifact relative_path: ${JSON.stringify(input.relativePath)}`);
+    }
+    if (!SHA256_RE.test(input.sha256)) {
+        throw new Error(`refusing to build a materialize command without a valid SHA-256 for ${relativePath}`);
+    }
+    if (!URL_SCHEME_RE.test(input.url)) {
+        throw new Error(`refusing to build a materialize command for a URL scheme that is not http(s) or file: ${JSON.stringify(input.url)}`);
+    }
+    const envName = SQUADRULES_LOCAL_ARTIFACT_DIR_ENV;
+    const sha256 = input.sha256.toLowerCase();
+    const out = `$${envName}/${relativePath}`;
+    // Reject a symlinked root, every existing destination ancestor, and the final
+    // destination before anything is created or written.
+    const segments = relativePath.split('/');
+    const symlinkGuards = ['[ ! -L "$dir" ]'];
+    for (let i = 1; i <= segments.length; i += 1) {
+        symlinkGuards.push(`[ ! -L "$dir/${segments.slice(0, i).join('/')}" ]`);
+    }
+    const cmd = [
+        // Fail closed unless the artifact dir is set, non-empty, and absolute.
+        `dir="\${${envName}:?${envName} must be set to an absolute artifact directory}"`,
+        `case "$dir" in /*) ;; *) printf '%s\\n' '${envName} must be an absolute path' >&2; exit 1 ;; esac`,
+        ...symlinkGuards,
+        `out="$dir/${relativePath}"`,
+        `parent="$(dirname "$out")"`,
+        `mkdir -p "$parent"`,
+        // The resolved parent must stay inside the resolved root, not merely lack `../`.
+        `root_phys="$(cd "$dir" && pwd -P)"`,
+        `parent_phys="$(cd "$parent" && pwd -P)"`,
+        `case "$parent_phys" in "$root_phys" | "$root_phys"/*) ;; *) printf '%s\\n' 'resolved destination escapes the artifact root' >&2; exit 1 ;; esac`,
+        // Download into a fresh private temp file in the destination directory so the
+        // final rename is atomic on one filesystem.
+        `staging="$(mktemp "$parent/.squadrules-materialize.XXXXXX")"`,
+        `trap 'rm -f "$staging"' EXIT INT TERM HUP`,
+        `curl -fsS -o "$staging" ${shellSingleQuote(input.url)}`,
+        // Portable digest chain with no platform assumption baked in.
+        `{ if command -v sha256sum >/dev/null 2>&1; then digest="$(sha256sum "$staging" | cut -d' ' -f1)"; ` +
+            `elif command -v shasum >/dev/null 2>&1; then digest="$(shasum -a 256 "$staging" | cut -d' ' -f1)"; ` +
+            `elif command -v openssl >/dev/null 2>&1; then digest="$(openssl dgst -sha256 "$staging" | sed 's/^.*= //')"; ` +
+            `else printf '%s\\n' 'no sha256 tool (need sha256sum, shasum, or openssl) on PATH' >&2; exit 1; fi; }`,
+        `[ "$digest" = '${sha256}' ]`,
+        // Only a verified file is chmod'd and published; a prior destination survives any earlier failure.
+        `chmod 700 "$staging"`,
+        `mv -f "$staging" "$out"`,
+        `trap - EXIT INT TERM HUP`
+    ].join(' && ');
+    return { method: 'url', url: input.url, out, sha256, chmod: '700', cmd };
 }
 //# sourceMappingURL=artifact-materialize-command.js.map

package/dist/tools/artifact-materialize-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-materialize-command.js","sourceRoot":"","sources":["../../src/tools/artifact-materialize-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,iCAAiC,GAAG,+BAA+B,CAAC;AAiCjF,MAAM,UAAU,mCAAmC,CAAC,KAA+B;IACjF,MAAM,OAAO,GAAG,IAAI,iCAAiC,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;IAC9E,MAAM,MAAM,GAAG,IAAI,OAAO,GAAG,CAAC;IAC9B,MAAM,KAAK,GACT,KAAK,CAAC,SAAS,KAAK,MAAM;QACxB,CAAC,CAAC,gBAAgB,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE;QAC/D,CAAC,CAAC,oGAAoG,MAAM,EAAE,CAAC;IACnH,MAAM,MAAM,GAAG,uBAAuB,KAAK,CAAC,MAAM,KAAK,MAAM,iBAAiB,CAAC;IAC/E,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,SAAS,EACP,KAAK,CAAC,SAAS,KAAK,MAAM;YACxB,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE;YAC9C,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC7E,GAAG,EAAE,OAAO;QACZ,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK;QACZ,GAAG,EAAE,uBAAuB,MAAM,SAAS,KAAK,OAAO,MAAM,iBAAiB,MAAM,EAAE;KACvF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"artifact-materialize-command.js","sourceRoot":"","sources":["../../src/tools/artifact-materialize-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gCAAgC,EAAE,MAAM,6BAA6B,CAAC;AAE/E,MAAM,CAAC,MAAM,iCAAiC,GAAG,+BAA+B,CAAC;AAEjF,MAAM,SAAS,GAAG,iBAAiB,CAAC;AACpC,MAAM,aAAa,GAAG,wBAAwB,CAAC;AA0B/C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,KAA+B;IACjF,MAAM,YAAY,GAAG,gCAAgC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1E,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,iFAAiF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CACtH,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,uEAAuE,YAAY,EAAE,CAAC,CAAC;IACzG,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,yFAAyF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CACrH,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,iCAAiC,CAAC;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;IAE1C,8EAA8E;IAC9E,qDAAqD;IACrD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,aAAa,GAAa,CAAC,iBAAiB,CAAC,CAAC;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,aAAa,CAAC,IAAI,CAAC,gBAAgB,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,GAAG,GAAG;QACV,uEAAuE;QACvE,WAAW,OAAO,KAAK,OAAO,kDAAkD;QAChF,4CAA4C,OAAO,gDAAgD;QACnG,GAAG,aAAa;QAChB,aAAa,YAAY,GAAG;QAC5B,4BAA4B;QAC5B,oBAAoB;QACpB,iFAAiF;QACjF,oCAAoC;QACpC,yCAAyC;QACzC,iJAAiJ;QACjJ,8EAA8E;QAC9E,4CAA4C;QAC5C,8DAA8D;QAC9D,2CAA2C;QAC3C,2BAA2B,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;QACxD,8DAA8D;QAC9D,oGAAoG;YAClG,qGAAqG;YACrG,+GAA+G;YAC/G,sGAAsG;QACxG,kBAAkB,MAAM,KAAK;QAC7B,mGAAmG;QACnG,sBAAsB;QACtB,yBAAyB;QACzB,0BAA0B;KAC3B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEf,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAC3E,CAAC"}

package/dist/tools/artifact-relative-path.d.ts

@@ -4,4 +4,20 @@
  */
 /** Normalize and validate a skill-root-relative path. Returns null if invalid. */
 export declare function normalizeArtifactRelativePath(raw: string): string | null;
+/**
+ * Canonicalize and validate a skill-root-relative path destined for the
+ * materialize command. Stricter than {@link normalizeArtifactRelativePath}, which
+ * is shared with the ZIP export layout: this also rejects shell metacharacters and
+ * ambiguous interior `.` segments, because the result is embedded in a shell
+ * command and resolved against an absolute filesystem root. Returns null if
+ * invalid; the caller must fail closed rather than substitute a default.
+ */
+export declare function normalizeMaterializeRelativePath(raw: string): string | null;
+/**
+ * Reduce an arbitrary artifact name to a conservative, shell-safe single filename
+ * segment for a synthesized materialize path. Disallowed characters become `_`;
+ * an empty, `.`, or `..` result is ambiguous and returns null so the caller fails
+ * the load instead of inventing an unsafe destination.
+ */
+export declare function sanitizeArtifactFileName(name: string): string | null;
 //# sourceMappingURL=artifact-relative-path.d.ts.map

package/dist/tools/artifact-relative-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-relative-path.d.ts","sourceRoot":"","sources":["../../src/tools/artifact-relative-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBxE"}
+{"version":3,"file":"artifact-relative-path.d.ts","sourceRoot":"","sources":["../../src/tools/artifact-relative-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBxE;AAcD;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmB3E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMpE"}

package/dist/tools/artifact-relative-path.js

@@ -26,4 +26,55 @@ export function normalizeArtifactRelativePath(raw) {
     }
     return s;
 }
+/**
+ * Shell metacharacters that must never appear in a materialize destination path
+ * (ADR 0040): double quote, single quote, backtick, dollar sign, backslash, and
+ * control / DEL bytes (including newline). Spaces and ordinary filename
+ * characters stay allowed; {@link normalizeArtifactRelativePath} already rejects
+ * `..`, absolute paths, empty segments, and over-long paths.
+ */
+const MATERIALIZE_FORBIDDEN_RE = /["'`$\\\u0000-\u001f\u007f]/;
+/** Characters allowed in a synthesized artifact filename segment. */
+const FILENAME_DISALLOWED_RE = /[^A-Za-z0-9._-]/g;
+/**
+ * Canonicalize and validate a skill-root-relative path destined for the
+ * materialize command. Stricter than {@link normalizeArtifactRelativePath}, which
+ * is shared with the ZIP export layout: this also rejects shell metacharacters and
+ * ambiguous interior `.` segments, because the result is embedded in a shell
+ * command and resolved against an absolute filesystem root. Returns null if
+ * invalid; the caller must fail closed rather than substitute a default.
+ */
+export function normalizeMaterializeRelativePath(raw) {
+    if (MATERIALIZE_FORBIDDEN_RE.test(raw)) {
+        return null;
+    }
+    const normalized = normalizeArtifactRelativePath(raw);
+    if (normalized === null) {
+        return null;
+    }
+    for (const segment of normalized.split('/')) {
+        if (segment === '.') {
+            return null;
+        }
+    }
+    // Defense in depth: the base canonicalizer maps `\` to `/`, so re-check the
+    // normalized result for metacharacters that must never reach the shell.
+    if (MATERIALIZE_FORBIDDEN_RE.test(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+/**
+ * Reduce an arbitrary artifact name to a conservative, shell-safe single filename
+ * segment for a synthesized materialize path. Disallowed characters become `_`;
+ * an empty, `.`, or `..` result is ambiguous and returns null so the caller fails
+ * the load instead of inventing an unsafe destination.
+ */
+export function sanitizeArtifactFileName(name) {
+    const candidate = name.trim().replace(FILENAME_DISALLOWED_RE, '_');
+    if (candidate.length === 0 || candidate === '.' || candidate === '..') {
+        return null;
+    }
+    return candidate;
+}
 //# sourceMappingURL=artifact-relative-path.js.map

package/dist/tools/artifact-relative-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-relative-path.js","sourceRoot":"","sources":["../../src/tools/artifact-relative-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kFAAkF;AAClF,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACvD,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9B,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;IAC9B,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"artifact-relative-path.js","sourceRoot":"","sources":["../../src/tools/artifact-relative-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kFAAkF;AAClF,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACvD,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9B,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;IAC9B,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;GAMG;AACH,MAAM,wBAAwB,GAAG,6BAA6B,CAAC;AAE/D,qEAAqE;AACrE,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,UAAU,gCAAgC,CAAC,GAAW;IAC1D,IAAI,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,UAAU,GAAG,6BAA6B,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,4EAA4E;IAC5E,wEAAwE;IACxE,IAAI,wBAAwB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IACnE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,KAAK,GAAG,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}