commandmate 0.11.3 → 0.12.0

package/dist/server/src/lib/skills/installed-state.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Installed-Skill index (Issue #1235)
+ *
+ * A lookup table over what the receipts already say. The receipt inside
+ * `.agents/skills/<id>/` is the truth; this table exists so "what is installed
+ * in this worktree" does not require walking every registered worktree.
+ *
+ * That ordering is the whole point. The row is written *after* the atomic
+ * rename, so a crash in between leaves a worktree that is installed and a table
+ * that has not caught up — which #1234 reconciliation converges forward from the
+ * receipt. Writing the row first would create the opposite and unrecoverable
+ * state: a table claiming an install that does not exist.
+ *
+ * {@link upsertSkillInstallation} is therefore idempotent by construction, so
+ * reconciliation may replay it any number of times.
+ *
+ * @module lib/skills/installed-state
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertSkillInstallation = upsertSkillInstallation;
+exports.getSkillInstallation = getSkillInstallation;
+exports.listSkillInstallations = listSkillInstallations;
+exports.deleteSkillInstallation = deleteSkillInstallation;
+const crypto_1 = require("crypto");
+const SELECT_COLUMNS = `
+  id, worktree_id, skill_id, version, install_root, install_roots, receipt_sha256,
+  source_repository, source_ref, source_commit, artifact_sha256,
+  effective_risk, operation_id, installed_at, updated_at
+`;
+/** Parse the JSON `install_roots` column, falling back to the single primary root. */
+function parseInstallRoots(raw, installRoot) {
+    if (raw === null)
+        return [installRoot];
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) &&
+            parsed.length > 0 &&
+            parsed.every((item) => typeof item === 'string')) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to the single-root reading below.
+    }
+    return [installRoot];
+}
+function mapRow(row) {
+    return {
+        id: row.id,
+        worktreeId: row.worktree_id,
+        skillId: row.skill_id,
+        version: row.version,
+        installRoot: row.install_root,
+        installRoots: parseInstallRoots(row.install_roots, row.install_root),
+        receiptSha256: row.receipt_sha256,
+        sourceRepository: row.source_repository,
+        sourceRef: row.source_ref,
+        sourceCommit: row.source_commit,
+        artifactSha256: row.artifact_sha256,
+        effectiveRisk: row.effective_risk,
+        operationId: row.operation_id,
+        installedAt: row.installed_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Record an install, replacing any earlier row for the same (worktree, skill).
+ *
+ * Idempotent: replaying the same operation rewrites the same values, so
+ * reconciliation can call this without first having to know whether an earlier
+ * attempt got this far. `installed_at` is preserved across replays so the
+ * original commit time is not rewritten by a later convergence.
+ */
+function upsertSkillInstallation(db, input) {
+    const { receipt } = input;
+    // Primary first; a pre-#1460 receipt with no install_roots is read as its
+    // single install_root, so the column is always a non-empty JSON array.
+    const installRoots = receipt.install_roots && receipt.install_roots.length > 0
+        ? receipt.install_roots
+        : [receipt.install_root];
+    db.prepare(`INSERT INTO skill_installations (
+       id, worktree_id, skill_id, version, install_root, install_roots, receipt_sha256,
+       source_repository, source_ref, source_commit, artifact_sha256,
+       effective_risk, operation_id, installed_at, updated_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT (worktree_id, skill_id) DO UPDATE SET
+       version = excluded.version,
+       install_root = excluded.install_root,
+       install_roots = excluded.install_roots,
+       receipt_sha256 = excluded.receipt_sha256,
+       source_repository = excluded.source_repository,
+       source_ref = excluded.source_ref,
+       source_commit = excluded.source_commit,
+       artifact_sha256 = excluded.artifact_sha256,
+       effective_risk = excluded.effective_risk,
+       operation_id = excluded.operation_id,
+       updated_at = excluded.updated_at`).run((0, crypto_1.randomUUID)(), input.worktreeId, receipt.skill_id, receipt.version, receipt.install_root, JSON.stringify(installRoots), input.receiptSha256, receipt.source.repository, receipt.source.ref, receipt.source.commit, receipt.artifact.sha256, receipt.effective_risk, input.operationId, input.installedAt, input.installedAt);
+    const record = getSkillInstallation(db, input.worktreeId, receipt.skill_id);
+    if (record === null) {
+        throw new Error('Skill installation row disappeared immediately after being written');
+    }
+    return record;
+}
+/** The indexed install for one Skill in one worktree, or null. */
+function getSkillInstallation(db, worktreeId, skillId) {
+    const row = db
+        .prepare(`SELECT ${SELECT_COLUMNS} FROM skill_installations
+       WHERE worktree_id = ? AND skill_id = ?`)
+        .get(worktreeId, skillId);
+    return row ? mapRow(row) : null;
+}
+/** Every indexed install in one worktree, by Skill ID. */
+function listSkillInstallations(db, worktreeId) {
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS} FROM skill_installations
+       WHERE worktree_id = ? ORDER BY skill_id ASC`)
+        .all(worktreeId);
+    return rows.map(mapRow);
+}
+/** Drop an index row. Returns whether a row was removed. */
+function deleteSkillInstallation(db, worktreeId, skillId) {
+    const result = db
+        .prepare('DELETE FROM skill_installations WHERE worktree_id = ? AND skill_id = ?')
+        .run(worktreeId, skillId);
+    return result.changes > 0;
+}

package/dist/server/src/lib/skills/integrity.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * Integrity verification and failure vocabulary for Skill fetching (Issue #1229)
+ *
+ * Two responsibilities that belong together: deciding whether a byte stream is
+ * the artifact the Catalog promised, and naming the ways that decision can fail.
+ *
+ * The error type is deliberately separate from `SkillContractError` (#1228):
+ * that one describes a *document* that failed validation and is addressed by a
+ * JSON pointer. These describe a *transfer or storage* failure and carry a
+ * retryability hint instead, because that is the question the UI has to answer
+ * ("can I press retry?", UX-09). Messages are derived from the code alone, so
+ * no token, signed query or machine-absolute path can leak through them.
+ *
+ * @module lib/skills/integrity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillFetchError = exports.SkillFetchErrorCode = void 0;
+exports.isSkillFetchError = isSkillFetchError;
+exports.redactUrlForLog = redactUrlForLog;
+exports.createSha256Accumulator = createSha256Accumulator;
+exports.computeSha256Hex = computeSha256Hex;
+exports.digestMatches = digestMatches;
+exports.assertArtifactBinding = assertArtifactBinding;
+exports.verifyArtifactIntegrity = verifyArtifactIntegrity;
+const crypto_1 = require("crypto");
+const skills_1 = require("../../lib/skills");
+// =============================================================================
+// Error vocabulary
+// =============================================================================
+/** Stable, client-safe reason codes for fetch and snapshot failures. */
+exports.SkillFetchErrorCode = {
+    /** URL is syntactically unusable (not absolute, not HTTPS, carries userinfo, …). */
+    URL_INVALID: 'SKILL_FETCH_URL_INVALID',
+    /** URL points outside the official allowlist for its document kind. */
+    SOURCE_NOT_ALLOWED: 'SKILL_FETCH_SOURCE_NOT_ALLOWED',
+    /** A redirect response was malformed or had no usable `Location`. */
+    REDIRECT_INVALID: 'SKILL_FETCH_REDIRECT_INVALID',
+    /** More redirect hops than the policy permits. */
+    REDIRECT_LIMIT_EXCEEDED: 'SKILL_FETCH_REDIRECT_LIMIT_EXCEEDED',
+    /** Server answered with a non-success status. */
+    HTTP_STATUS: 'SKILL_FETCH_HTTP_STATUS',
+    /** Response media type is not the one this document kind requires. */
+    CONTENT_TYPE_INVALID: 'SKILL_FETCH_CONTENT_TYPE_INVALID',
+    /** Response had no readable body. */
+    BODY_MISSING: 'SKILL_FETCH_BODY_MISSING',
+    /** Declared or measured size exceeded the policy limit. */
+    SIZE_LIMIT_EXCEEDED: 'SKILL_FETCH_SIZE_LIMIT_EXCEEDED',
+    /** Transferred size did not match the size the Catalog declared. */
+    SIZE_MISMATCH: 'SKILL_FETCH_SIZE_MISMATCH',
+    /** SHA-256 over the received bytes did not match the Catalog digest. */
+    CHECKSUM_MISMATCH: 'SKILL_FETCH_CHECKSUM_MISMATCH',
+    /** Catalog version is not bound to an immutable commit and exact version. */
+    BINDING_INVALID: 'SKILL_FETCH_BINDING_INVALID',
+    /** Request exceeded the header or total timeout. */
+    TIMEOUT: 'SKILL_FETCH_TIMEOUT',
+    /** Caller aborted the operation. */
+    ABORTED: 'SKILL_FETCH_ABORTED',
+    /** Transport-level failure (DNS, TLS, connection reset, …). */
+    NETWORK: 'SKILL_FETCH_NETWORK',
+    /** Snapshot ID is unknown, already released or malformed. */
+    SNAPSHOT_NOT_FOUND: 'SKILL_SNAPSHOT_NOT_FOUND',
+    /** Snapshot exists but its TTL has elapsed. */
+    SNAPSHOT_EXPIRED: 'SKILL_SNAPSHOT_EXPIRED',
+    /** Storing the snapshot would exceed the disk or count quota. */
+    QUOTA_EXCEEDED: 'SKILL_SNAPSHOT_QUOTA_EXCEEDED',
+    /** Snapshot store could not read or write the service-owned data root. */
+    STORE_IO: 'SKILL_SNAPSHOT_STORE_IO',
+    /** Snapshot store was used before initialization. */
+    STORE_UNINITIALIZED: 'SKILL_SNAPSHOT_STORE_UNINITIALIZED',
+};
+/**
+ * Codes worth retrying without user intervention.
+ *
+ * A checksum mismatch or a disallowed source is *not* here on purpose: retrying
+ * either one would just re-download bytes we already decided not to trust.
+ */
+const RETRYABLE_CODES = new Set([
+    exports.SkillFetchErrorCode.TIMEOUT,
+    exports.SkillFetchErrorCode.NETWORK,
+    exports.SkillFetchErrorCode.HTTP_STATUS,
+    exports.SkillFetchErrorCode.STORE_IO,
+]);
+/** Human-readable text per code. Contains no interpolated runtime value. */
+const MESSAGES = {
+    [exports.SkillFetchErrorCode.URL_INVALID]: 'Skill source URL is not a usable HTTPS URL',
+    [exports.SkillFetchErrorCode.SOURCE_NOT_ALLOWED]: 'Skill source is not on the official allowlist',
+    [exports.SkillFetchErrorCode.REDIRECT_INVALID]: 'Skill source redirect was malformed',
+    [exports.SkillFetchErrorCode.REDIRECT_LIMIT_EXCEEDED]: 'Skill source exceeded the redirect limit',
+    [exports.SkillFetchErrorCode.HTTP_STATUS]: 'Skill source responded with an error status',
+    [exports.SkillFetchErrorCode.CONTENT_TYPE_INVALID]: 'Skill source returned an unexpected media type',
+    [exports.SkillFetchErrorCode.BODY_MISSING]: 'Skill source response had no body',
+    [exports.SkillFetchErrorCode.SIZE_LIMIT_EXCEEDED]: 'Skill source response exceeded the size limit',
+    [exports.SkillFetchErrorCode.SIZE_MISMATCH]: 'Skill artifact size did not match the catalog',
+    [exports.SkillFetchErrorCode.CHECKSUM_MISMATCH]: 'Skill artifact checksum did not match the catalog',
+    [exports.SkillFetchErrorCode.BINDING_INVALID]: 'Skill catalog version is not bound to an immutable source',
+    [exports.SkillFetchErrorCode.TIMEOUT]: 'Skill source request timed out',
+    [exports.SkillFetchErrorCode.ABORTED]: 'Skill source request was aborted',
+    [exports.SkillFetchErrorCode.NETWORK]: 'Skill source could not be reached',
+    [exports.SkillFetchErrorCode.SNAPSHOT_NOT_FOUND]: 'Skill snapshot is unknown or already released',
+    [exports.SkillFetchErrorCode.SNAPSHOT_EXPIRED]: 'Skill snapshot has expired',
+    [exports.SkillFetchErrorCode.QUOTA_EXCEEDED]: 'Skill snapshot store quota exceeded',
+    [exports.SkillFetchErrorCode.STORE_IO]: 'Skill snapshot store could not be accessed',
+    [exports.SkillFetchErrorCode.STORE_UNINITIALIZED]: 'Skill snapshot store is not initialized',
+};
+/** A fetch or snapshot failure, safe to surface to API clients and logs. */
+class SkillFetchError extends Error {
+    code;
+    /** Whether a plain retry could plausibly succeed. */
+    retryable;
+    detail;
+    constructor(code, detail) {
+        super(MESSAGES[code]);
+        this.name = 'SkillFetchError';
+        this.code = code;
+        this.retryable = RETRYABLE_CODES.has(code);
+        if (detail)
+            this.detail = detail;
+    }
+}
+exports.SkillFetchError = SkillFetchError;
+/** Narrow an unknown thrown value to a {@link SkillFetchError}. */
+function isSkillFetchError(value) {
+    return value instanceof SkillFetchError;
+}
+// =============================================================================
+// Redaction
+// =============================================================================
+/**
+ * Reduce a URL to its origin for logging.
+ *
+ * Release asset URLs carry signed query parameters that are credentials in
+ * everything but name, and the path can identify a private repository. Only the
+ * origin is ever safe to record.
+ */
+function redactUrlForLog(rawUrl) {
+    try {
+        return new URL(rawUrl).origin;
+    }
+    catch {
+        return '<invalid-url>';
+    }
+}
+/** Create an incremental SHA-256 accumulator. */
+function createSha256Accumulator() {
+    const hash = (0, crypto_1.createHash)('sha256');
+    return {
+        update(chunk) {
+            hash.update(chunk);
+        },
+        hex() {
+            return hash.digest('hex');
+        },
+    };
+}
+/** Lowercase hex SHA-256 of a complete buffer. */
+function computeSha256Hex(bytes) {
+    return (0, crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}
+/**
+ * Compare two lowercase hex SHA-256 digests without leaking timing.
+ *
+ * Malformed input is a mismatch rather than a throw, so no caller can turn a
+ * bad digest into an accepted artifact by catching the wrong exception.
+ */
+function digestMatches(expected, actual) {
+    if (!skills_1.SHA256_HEX_PATTERN.test(expected) || !skills_1.SHA256_HEX_PATTERN.test(actual))
+        return false;
+    return (0, crypto_1.timingSafeEqual)(Buffer.from(expected, 'hex'), Buffer.from(actual, 'hex'));
+}
+// =============================================================================
+// Catalog binding
+// =============================================================================
+/**
+ * Assert that a Catalog version identifies one immutable artifact.
+ *
+ * `validateSkillCatalog` (#1228) already proves the document is well-formed.
+ * This is the separate question of whether the entry pins its bytes: an exact
+ * SemVer, a resolved 40-hex commit, the conventional asset name, and the one
+ * artifact format and media type this build accepts.
+ *
+ * @throws SkillFetchError with `BINDING_INVALID`
+ */
+function assertArtifactBinding(skillId, version) {
+    const fail = (field) => {
+        throw new SkillFetchError(exports.SkillFetchErrorCode.BINDING_INVALID, { field });
+    };
+    if (!(0, skills_1.isValidSemVer)(version.version))
+        fail('version');
+    if (!skills_1.GIT_COMMIT_SHA_PATTERN.test(version.source.commit))
+        fail('source.commit');
+    if (version.artifact.asset_name !== (0, skills_1.buildSkillAssetName)(skillId, version.version)) {
+        fail('artifact.asset_name');
+    }
+    if (version.artifact.format !== skills_1.SKILL_ARTIFACT_FORMAT)
+        fail('artifact.format');
+    if (version.artifact.content_type !== skills_1.SKILL_ARTIFACT_CONTENT_TYPE)
+        fail('artifact.content_type');
+    if (!skills_1.SHA256_HEX_PATTERN.test(version.artifact.sha256))
+        fail('artifact.sha256');
+    if (!Number.isSafeInteger(version.artifact.size) ||
+        version.artifact.size <= 0 ||
+        version.artifact.size > skills_1.SKILL_ARTIFACT_MAX_SIZE) {
+        fail('artifact.size');
+    }
+}
+/**
+ * Verify transferred bytes against the Catalog record.
+ *
+ * Size is checked first so a truncated transfer reports the useful reason
+ * rather than the digest mismatch it also causes.
+ *
+ * @throws SkillFetchError with `SIZE_MISMATCH` or `CHECKSUM_MISMATCH`
+ */
+function verifyArtifactIntegrity(input) {
+    if (input.actualSize !== input.expectedSize) {
+        throw new SkillFetchError(exports.SkillFetchErrorCode.SIZE_MISMATCH, {
+            expected: input.expectedSize,
+            actual: input.actualSize,
+        });
+    }
+    if (!digestMatches(input.expectedSha256, input.actualSha256)) {
+        throw new SkillFetchError(exports.SkillFetchErrorCode.CHECKSUM_MISMATCH);
+    }
+}