* test(#2322): fail-first tests for third-party capability skill materialization Red phase: tests (1) and (6) fail — resolveSurface reports the third-party stem surfaced (#2045) but no SKILL.md is ever written to disk. The other four are controls that must keep holding: first-party-wins collision, profile-tier filter, nested-router layout unperturbed, and absent/malformed capability must not throw. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SLufH5sDuqA1AiEGu45cuA * fix(#2322): materialize installed third-party capability skills A capability could report installed:true, surfaced:true, active:true and still never exist as an invocable command. #2045 fixed the registry layer — resolveSurface unions registry.capabilityClusters into the resolved skill set — but the materialization layer never got the matching fix. stageSkillsForRuntimeAsSkills only ever read gsd-core's own bundled commands/gsd/*.md and silently skipped any stem it couldn't find there, so a third-party skill living at <GSD_HOME>/.gsd/capabilities/<id>/skills/<stem>/ was never copied. Registry said surfaced; disk had nothing. Installed capability skills are now staged alongside the first-party ones, copied verbatim (they are authored complete for their target runtime and need no converter). First-party stems always win a collision, the profile filter still applies, and an absent or malformed capability degrades rather than throwing. Security: capability.json's skills[] entries are validated only as non-empty non-reserved strings (capability-validator.cjs:503-514) — no path shape is enforced upstream — so stems are sanitized (rejecting separators, '..', absolute paths, NUL) with an independent isPathConfined check on both the read and write paths. A '../../evil' stem writes nothing outside the capability's own dir. Also fixes a defect this surfaced in pruneSkillDirs: a materialized capability skill dir has no first-party manifest entry, so every apply logged "preserving (user-owned or unknown)" for a live GSD-managed dir. The retained check now precedes the manifest gate; no deletion outcome changes, and genuinely unknown gsd-* dirs still warn and are preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SLufH5sDuqA1AiEGu45cuA * fix(#2322): address security review — bind skills to declaring capability, fix full profile An independent security review BLOCKED the first pass. Both blockers were mine. BLOCKER 1 (security): readInstalledCapabilitySkill scanned every capability dir and returned the first sorted match, never checking that a capability DECLARES the stem — ownership was inferred from attacker-controlled filesystem layout. Since install copies the whole bundle and the validator only checks DECLARED entries, a capability declaring `skills: []` could ship an undeclared skills/deploy/SKILL.md and win the `deploy` stem on sort order, supplying the agent-invocable instructions the user believed came from the registered capability. Stems are now bound to their owning capId via registry.capabilityClusters, and only that capability's dir is read. BLOCKER 2: the fill-in pass was gated `skills !== '*'` on the premise that applySurface materializes `full` into a concrete Set. True for applySurface — false for the installer, which is the default path: resolveProfile returns the '*' sentinel and bin/install.js passes it straight to staging. So #2322 survived on the default `full` profile, i.e. the fix didn't fix the reported bug. The registry is now plumbed to staging, and '*' stages all capability-cluster stems. Wiring this surfaced a second gap: the ADR-1239 imperative adapter (the primary install path) never threaded its registry either, which would have silently defeated the fix on the real default install. HIGH: staged capability skills were never prunable — pruneSkillDirs gates on the first-party manifest, so uninstalling a capability left its instructions live in the agent's context forever. Staged skills now carry a marker making them GSD-owned and prunable; genuinely unknown gsd-* dirs still warn and are preserved. MEDIUM: the "staged verbatim" claim was false — applySurface rewrites bodies over the whole stage dir. The tests asserted byte-equality and passed only because their fixtures contained no rewrite triggers. Claim dropped; tests now assert the rewrite against triggering content. LOW: isPathConfined is lexical, not realpath (symlink-defeatable, currently unreachable because install rejects symlinks) — comment corrected. The validator does not enforce non-empty, so isSafeCapabilitySkillStem is the sole defense, not a second layer — comment corrected and it now has traversal/NUL/absolute/empty test coverage (previously mutating it to `return true` left every test green). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SLufH5sDuqA1AiEGu45cuA * test(#2322): pin that the imperative adapter forwards a capability registry The delegation-args test deep-equalled the exact argv to installRuntimeArtifacts, so threading the composed capability registry through the ADR-1239 imperative adapter (required for #2322 — without it the default `full` install path never materializes third-party capability skills) failed it. The contract legitimately gained a parameter, so this is a stale-test correction, not a regression. Rather than deep-equalling the whole composed registry (brittle — it embeds the full agent/profile map), the test pins the leading args exactly and asserts only that a registry-shaped value is forwarded. That still fails if the adapter stops threading it, which is the regression the test exists to catch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SLufH5sDuqA1AiEGu45cuA * docs(#2322): backfill PR number 2340 into changeset Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SLufH5sDuqA1AiEGu45cuA --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -11,6 +11,9 @@ import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import os from 'node:os';
|
||||
import { platformWriteSync } from './shell-command-projection.cjs';
|
||||
// #2322: reuse the existing pure path-containment seam (ADR-1239 Phase C-2)
|
||||
// instead of hand-rolling a new traversal check for capability skill stems.
|
||||
import { isPathConfined } from './external-descriptor-trust.cjs';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import conversionModule = require('./runtime-artifact-conversion.cjs');
|
||||
const {
|
||||
@@ -470,12 +473,174 @@ function transformRouterBodyToNested(converted: string): string {
|
||||
return out.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* #2322 SECURITY: a third-party `capability.json`'s `skills[]` entries are only
|
||||
* validated for being STRINGS and not one of the 3 reserved prototype-pollution
|
||||
* names (capability-validator.cjs validateFeatureBody, ~line 503) — NOT for
|
||||
* non-emptiness and NOT for a safe path-segment shape. `isSafeCapabilitySkillStem`
|
||||
* is therefore the SOLE defense against an empty-string, `..`-escaping,
|
||||
* separator-carrying, absolute, or NUL-carrying stem reaching a filesystem path
|
||||
* as a literal component — not a second defense-in-depth layer on top of any
|
||||
* validator-enforced non-emptiness (there is none). Once unioned into
|
||||
* resolveSurface's `resolved.skills` (#2045), such a stem must never reach
|
||||
* fs.readFileSync/writeFileSync as a literal path component, or it can escape
|
||||
* the capabilities root on read (or stageDir on write). Reject anything but a
|
||||
* single, ordinary path segment.
|
||||
*/
|
||||
function isSafeCapabilitySkillStem(stem: string): boolean {
|
||||
if (typeof stem !== 'string' || stem.length === 0) return false;
|
||||
if (stem.includes('\0')) return false;
|
||||
if (stem === '.' || stem === '..') return false;
|
||||
if (stem.includes('/') || stem.includes('\\')) return false;
|
||||
if (path.isAbsolute(stem)) return false;
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve which capability id DECLARES ownership of `stem`, per the registry's
|
||||
* `capabilityClusters` view (capId -> [owned skill stems]) — the SAME
|
||||
* authoritative binding `_capabilitySkillsForMode` (above) and `resolveSurface`
|
||||
* (surface.cts) already trust to decide which stems a capability contributes.
|
||||
* `capabilityClusters` is derived (gen-capability-registry.cjs
|
||||
* deriveCapabilityClusters) straight from each ACCEPTED capability's OWN
|
||||
* declared, non-empty `skills[]` array — an UNDECLARED directory a capability
|
||||
* happens to ship on disk (an unlisted `skills/<stem>/` bundled by mistake, or
|
||||
* by a malicious author trying to hijack another capability's stem) never
|
||||
* appears here, so it can never resolve as an owner. Two capabilities can never
|
||||
* both own the same stem: the registry loader (capability-loader.cts) rejects a
|
||||
* candidate whose declared skill collides with an already-registered owner
|
||||
* BEFORE it is ever composed into the registry — so this lookup is unambiguous
|
||||
* by construction. Returns null for an unowned/unregistered stem or a
|
||||
* malformed registry (never throws).
|
||||
*/
|
||||
function _owningCapabilityId(stem: string, clusters: Record<string, string[]>): string | null {
|
||||
const BANNED = ['__proto__', 'constructor', 'prototype'];
|
||||
for (const capId of Object.keys(clusters)) {
|
||||
if (BANNED.includes(capId)) continue;
|
||||
const owned = clusters[capId];
|
||||
if (!Array.isArray(owned)) continue;
|
||||
if (owned.includes(stem)) return capId;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Union every stem ANY accepted capability declares across the WHOLE registry
|
||||
* (unfiltered by mode/tier) — used only for the `'*'` (full profile) staging
|
||||
* fill-in below, mirroring the SAME unconditional union `resolveSurface`
|
||||
* (surface.cts) already performs when ITS OWN base profile resolves to `'*'`.
|
||||
* Guards against a malformed/prototype-polluted registry; never throws.
|
||||
*/
|
||||
function capabilityClusterStems(registry: CapabilityRegistry | undefined): Set<string> {
|
||||
const result = new Set<string>();
|
||||
const clusters = registry?.capabilityClusters;
|
||||
if (!clusters || typeof clusters !== 'object') return result;
|
||||
const BANNED = ['__proto__', 'constructor', 'prototype'];
|
||||
for (const capId of Object.keys(clusters)) {
|
||||
if (BANNED.includes(capId)) continue;
|
||||
const stems = clusters[capId];
|
||||
if (!Array.isArray(stems)) continue;
|
||||
for (const s of stems) {
|
||||
if (typeof s === 'string' && s.length > 0) result.add(s);
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* #2322 HIGH-3: filesystem marker written into every staged THIRD-PARTY
|
||||
* capability skill directory (alongside SKILL.md) so a later prune pass
|
||||
* (surface.cts pruneSkillDirs) can identify the directory as GSD-capability-
|
||||
* owned even after the owning capability has been uninstalled/unsurfaced and
|
||||
* no longer appears in ANY registry view. Without a persisted marker, an
|
||||
* orphaned capability skill directory has no first-party manifest entry (the
|
||||
* skill manifest only ever knows gsd-core's own bundled stems) and
|
||||
* pruneSkillDirs' conservative unknown-directory branch would preserve it
|
||||
* FOREVER — uninstalling a malicious capability would never actually remove
|
||||
* its already-staged instructions from the agent's context. A directory
|
||||
* WITHOUT this marker is presumed genuinely user-created (data-loss
|
||||
* protection is unchanged for that case).
|
||||
*/
|
||||
const CAPABILITY_SKILL_MARKER = '.gsd-capability-skill';
|
||||
|
||||
/**
|
||||
* Look up an installed third-party capability's already-authored SKILL.md for
|
||||
* `stem`, bound to its DECLARING capability via the registry's
|
||||
* `capabilityClusters` view (capId -> owned stems) — NEVER by scanning every
|
||||
* installed capability directory and taking the first (sorted) match.
|
||||
*
|
||||
* #2322 BLOCKER 1: the prior implementation scanned every directory under the
|
||||
* capabilities root for a `skills/<stem>/SKILL.md` file and returned the FIRST
|
||||
* SORTED match, regardless of whether that capability actually DECLARED the
|
||||
* stem in its `capability.json` `skills[]` and regardless of whether it was
|
||||
* the (sole) REGISTERED owner. An attacker-controlled capability could ship an
|
||||
* UNDECLARED `skills/<victim-stem>/SKILL.md` directory that sorted ahead of
|
||||
* the legitimate, declaring capability and hijack its stem — the agent would
|
||||
* load the attacker's instructions believing they came from the legitimate
|
||||
* capability. Resolving `stem -> capId` via `capabilityClusters` FIRST (the
|
||||
* same authoritative binding `resolveSurface`/`_capabilitySkillsForMode`
|
||||
* trust) then reading ONLY that capability's own directory makes an
|
||||
* undeclared/unregistered sibling directory unreachable by construction.
|
||||
*
|
||||
* The install-root path convention (`<capabilitiesRoot>/<capId>/skills/<stem>/
|
||||
* SKILL.md` under `GSD_HOME || homedir()`) mirrors capability-loader.cts
|
||||
* (global overlay root) and capability-source.cts's `stageValidated` finalDir.
|
||||
*
|
||||
* Total/non-throwing (#2322 requirement 5): no registry, an unowned stem, a
|
||||
* missing capabilities root, an unreadable capability dir, or a missing/
|
||||
* corrupt SKILL.md all degrade to `null` (skip that stem) rather than
|
||||
* throwing — a partial/corrupt third-party install must never break
|
||||
* first-party staging. No registry at all means NOTHING third-party is
|
||||
* staged (fail closed — never a fallback scan).
|
||||
*
|
||||
* NOTE: the content returned here is staged AS-IS (no per-file `converter`
|
||||
* runs on it — unlike gsd-core's flat command `.md`, an installed capability
|
||||
* skill is already a complete SKILL.md), but it is NOT immune from the LATER
|
||||
* runtime-targeted body rewrite pass `applySurface` runs over the ENTIRE
|
||||
* staged directory (`rewriteStagedSkillBodies`, surface.cts): a `~/.claude/`
|
||||
* (etc.) path reference in a third-party skill body IS rewritten exactly like
|
||||
* a first-party one. "As-is" here refers only to this copy step, not to the
|
||||
* final on-disk content after a full `applySurface` run.
|
||||
*/
|
||||
function readInstalledCapabilitySkill(stem: string, registry: CapabilityRegistry | undefined): { capId: string; content: string } | null {
|
||||
if (!isSafeCapabilitySkillStem(stem)) return null;
|
||||
if (!registry || !registry.capabilityClusters || typeof registry.capabilityClusters !== 'object') return null;
|
||||
const capId = _owningCapabilityId(stem, registry.capabilityClusters);
|
||||
if (capId === null) return null;
|
||||
// Defense-in-depth: capId is a real accepted-capability directory name (a
|
||||
// trusted fs.readdirSync entry at capability-loader.cts accept time), but
|
||||
// re-validate its path-segment shape before using it as a literal path
|
||||
// component in case a future registry composer ever stops guaranteeing that.
|
||||
if (!isSafeCapabilitySkillStem(capId)) return null;
|
||||
const home = process.env['GSD_HOME'] || os.homedir();
|
||||
const capDir = path.join(home, '.gsd', 'capabilities', capId);
|
||||
const relSkillPath = path.join('skills', stem, 'SKILL.md');
|
||||
// Defense-in-depth: isSafeCapabilitySkillStem already rejects separators/
|
||||
// '..'/absolute stems, but re-confirm the resolved read path stays under
|
||||
// this capability's own directory before ever touching the filesystem.
|
||||
if (!isPathConfined(relSkillPath, capDir)) return null;
|
||||
const skillPath = path.join(capDir, relSkillPath);
|
||||
try {
|
||||
if (!fs.statSync(skillPath).isFile()) return null;
|
||||
return { capId, content: fs.readFileSync(skillPath, 'utf8') };
|
||||
} catch {
|
||||
return null; // missing / unreadable / corrupt entry -> skip
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @param registry optional capability registry (capabilityClusters view) —
|
||||
* when present, third-party capability skills are unioned into the staged
|
||||
* output (bound to their declaring capId; see readInstalledCapabilitySkill).
|
||||
* When absent, NOTHING third-party is staged (fail closed).
|
||||
*/
|
||||
function stageSkillsForRuntimeAsSkills(
|
||||
srcCommandsDir: string,
|
||||
resolvedProfile: ResolvedProfile,
|
||||
converter: (content: string, skillName: string) => string,
|
||||
prefix: string,
|
||||
nested = false,
|
||||
registry?: CapabilityRegistry,
|
||||
): string {
|
||||
if (!fs.existsSync(srcCommandsDir)) return srcCommandsDir;
|
||||
|
||||
@@ -496,6 +661,11 @@ function stageSkillsForRuntimeAsSkills(
|
||||
}
|
||||
}
|
||||
|
||||
// #2322: stems actually staged from gsd-core's OWN bundled commands/gsd dir
|
||||
// this call, so the third-party fill-in pass below can enforce "first-party
|
||||
// ALWAYS wins on collision" without re-deriving membership.
|
||||
const firstPartyStems = new Set<string>();
|
||||
|
||||
const stageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-profile-runtime-skills-'));
|
||||
try {
|
||||
const entries = fs.readdirSync(srcCommandsDir, { withFileTypes: true });
|
||||
@@ -504,6 +674,7 @@ function stageSkillsForRuntimeAsSkills(
|
||||
if (!entry.name.endsWith('.md')) continue;
|
||||
const stem = entry.name.slice(0, -3);
|
||||
if (resolvedProfile.skills !== '*' && !(resolvedProfile.skills).has(stem)) continue;
|
||||
firstPartyStems.add(stem);
|
||||
const content = fs.readFileSync(path.join(srcCommandsDir, entry.name), 'utf8');
|
||||
const skillName = `${prefix}${stem}`;
|
||||
const converted = converter(content, skillName);
|
||||
@@ -535,6 +706,54 @@ function stageSkillsForRuntimeAsSkills(
|
||||
fs.mkdirSync(destDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(destDir, 'SKILL.md'), converted);
|
||||
}
|
||||
|
||||
// #2322: materialize installed THIRD-PARTY capability skills, bound to
|
||||
// their DECLARING capability via the registry's capabilityClusters view
|
||||
// (see readInstalledCapabilitySkill — NEVER scan-and-first-match). The
|
||||
// registry union (#2045) already puts every accepted-capability stem into
|
||||
// a concrete resolvedProfile.skills Set, but srcCommandsDir only ever
|
||||
// holds gsd-core's own bundled commands — so any stem with no first-party
|
||||
// file here was silently dropped (registry says surfaced:true, nothing on
|
||||
// disk) unless we fill it in from the capability's own install dir.
|
||||
//
|
||||
// BLOCKER 2 (#2322): `resolveProfile` short-circuits the `full` profile
|
||||
// straight to the `'*'` sentinel BEFORE ever consulting a registry — the
|
||||
// sentinel therefore carries no per-stem list of its own, and a bare
|
||||
// `resolvedProfile.skills !== '*'` gate here skipped this ENTIRE fill-in
|
||||
// pass for a `full` install regardless of what the registry declared
|
||||
// (the issue's default-profile repro: `mode=full` staged zero third-party
|
||||
// skills even when `mode=standard` on the SAME registry staged them
|
||||
// correctly). When `resolvedProfile.skills === '*'`, the candidate stems
|
||||
// are instead every stem the registry's `capabilityClusters` declares —
|
||||
// mirroring the SAME unconditional union `resolveSurface` (surface.cts,
|
||||
// "Issue #2045" block) already performs for its own `'*'` case. When
|
||||
// `resolvedProfile.skills` is a concrete Set, the candidate stems are the
|
||||
// ones `_capabilitySkillsForMode` already unioned into it (unchanged).
|
||||
//
|
||||
// No registry in scope at all -> stage NOTHING third-party (fail closed —
|
||||
// never fall back to scanning). Nesting (#69) never applies to a
|
||||
// capability skill — it was never a child of any ns-* router's
|
||||
// `requires:` list — so it always lands flat at the top level, exactly
|
||||
// like an unrouted first-party skill.
|
||||
if (registry) {
|
||||
const candidateStems: Iterable<string> =
|
||||
resolvedProfile.skills === '*' ? capabilityClusterStems(registry) : resolvedProfile.skills;
|
||||
for (const stem of candidateStems) {
|
||||
if (firstPartyStems.has(stem)) continue; // first-party always wins
|
||||
const found = readInstalledCapabilitySkill(stem, registry);
|
||||
if (found === null) continue; // absent/malformed/unowned -> skip gracefully
|
||||
const skillName = `${prefix}${stem}`;
|
||||
if (!isPathConfined(skillName, stageDir)) continue; // defense-in-depth
|
||||
const destDir = path.join(stageDir, skillName);
|
||||
fs.mkdirSync(destDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(destDir, 'SKILL.md'), found.content);
|
||||
// #2322 HIGH-3: persist the capability-owned marker so a later prune
|
||||
// pass (surface.cts pruneSkillDirs) can identify — and remove — this
|
||||
// directory even once the owning capability is uninstalled/unsurfaced
|
||||
// and no longer appears in any registry view.
|
||||
fs.writeFileSync(path.join(destDir, CAPABILITY_SKILL_MARKER), found.capId + '\n', 'utf8');
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
try { fs.rmSync(stageDir, { recursive: true, force: true }); } catch { /* best-effort */ }
|
||||
throw err;
|
||||
@@ -878,6 +1097,12 @@ export = {
|
||||
parseRequires,
|
||||
parseCallsAgents,
|
||||
cleanupStagedSkills,
|
||||
// #2322: capability-skill security seams — exported for direct unit-testing
|
||||
// and for surface.cts's prune pass (CAPABILITY_SKILL_MARKER parity).
|
||||
isSafeCapabilitySkillStem,
|
||||
readInstalledCapabilitySkill,
|
||||
capabilityClusterStems,
|
||||
CAPABILITY_SKILL_MARKER,
|
||||
// Back-compat / deprecated
|
||||
MINIMAL_SKILL_ALLOWLIST,
|
||||
isMinimalMode,
|
||||
|
||||
Reference in New Issue
Block a user