@aopslabs/aops 0.2.0

package/dist/lib/agent-assets/package-manifest.js

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto';
+import { portablePackageCaseKeyV1, validatePortablePackagePath } from './portable-path.js';
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const MANIFEST_KEYS = new Set([
+    'schemaVersion',
+    'assetKind',
+    'name',
+    'version',
+    'versionId',
+    'entryFile',
+    'standard',
+    'packageSha256',
+    'files',
+    'compatibility',
+    'provenance',
+]);
+const FILE_DIGEST_KEYS = new Set(['path', 'sha256', 'byteLength']);
+const COMPATIBILITY_KEYS = new Set(['minCliVersion', 'maxSchemaVersion']);
+const PROVENANCE_KEYS = new Set([
+    'trustClass',
+    'expectedDigestSource',
+    'reference',
+    'releaseSha256',
+    'signatureRef',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function issue(code, at, message) {
+    return { code, at, message };
+}
+function requireKeys(record, required, at, issues) {
+    for (const key of required) {
+        if (!hasOwn(record, key))
+            issues.push(issue('missing_property', `${at}.${key}`, 'Required property is missing.'));
+    }
+}
+function rejectUnknownKeys(record, allowed, at, issues) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            issues.push(issue('unknown_property', `${at}.${key}`, 'Unknown property is not allowed.'));
+    }
+}
+function validateNonEmptyString(record, key, at, issues) {
+    if (!hasOwn(record, key))
+        return;
+    if (typeof record[key] !== 'string' || record[key].length === 0) {
+        issues.push(issue('invalid_type', `${at}.${key}`, 'Expected a non-empty string.'));
+    }
+}
+function validateSha256(record, key, at, issues) {
+    if (!hasOwn(record, key))
+        return;
+    if (typeof record[key] !== 'string' || !SHA256_HEX.test(record[key])) {
+        issues.push(issue('invalid_sha256', `${at}.${key}`, 'Expected a lowercase SHA-256 hex digest.'));
+    }
+}
+function validateRelativePath(record, key, at, issues) {
+    if (!hasOwn(record, key))
+        return;
+    const value = record[key];
+    if (typeof value !== 'string') {
+        issues.push(issue('invalid_type', `${at}.${key}`, 'Expected a package-relative path string.'));
+        return;
+    }
+    const result = validatePortablePackagePath(value);
+    if (!result.ok) {
+        issues.push(issue('invalid_package_path', `${at}.${key}`, `Path violates the portable package contract: ${result.issues.map((entry) => entry.code).join(', ')}.`));
+    }
+}
+function validateCompatibility(value, issues) {
+    const at = '$.compatibility';
+    if (!isRecord(value)) {
+        issues.push(issue('invalid_type', at, 'Expected a compatibility object.'));
+        return;
+    }
+    rejectUnknownKeys(value, COMPATIBILITY_KEYS, at, issues);
+    requireKeys(value, ['minCliVersion', 'maxSchemaVersion'], at, issues);
+    validateNonEmptyString(value, 'minCliVersion', at, issues);
+    if (hasOwn(value, 'maxSchemaVersion') && value.maxSchemaVersion !== 1) {
+        issues.push(issue('schema_incompatible', `${at}.maxSchemaVersion`, 'Only schema version 1 is supported.'));
+    }
+}
+function validateProvenance(value, issues) {
+    const at = '$.provenance';
+    if (!isRecord(value)) {
+        issues.push(issue('invalid_type', at, 'Expected a provenance object.'));
+        return undefined;
+    }
+    rejectUnknownKeys(value, PROVENANCE_KEYS, at, issues);
+    requireKeys(value, ['trustClass', 'expectedDigestSource', 'reference'], at, issues);
+    validateNonEmptyString(value, 'reference', at, issues);
+    if (hasOwn(value, 'trustClass') &&
+        value.trustClass !== 'signed-community-release' &&
+        value.trustClass !== 'verified-hosted-package') {
+        issues.push(issue('invalid_value', `${at}.trustClass`, 'Unknown package trust class.'));
+    }
+    if (hasOwn(value, 'expectedDigestSource') &&
+        value.expectedDigestSource !== 'signed-release-manifest' &&
+        value.expectedDigestSource !== 'immutable-hosted-metadata') {
+        issues.push(issue('invalid_value', `${at}.expectedDigestSource`, 'Unknown expected digest source.'));
+    }
+    if (hasOwn(value, 'releaseSha256'))
+        validateSha256(value, 'releaseSha256', at, issues);
+    if (hasOwn(value, 'signatureRef'))
+        validateNonEmptyString(value, 'signatureRef', at, issues);
+    return value;
+}
+function validateFileDigests(value, issues) {
+    const at = '$.files';
+    if (!Array.isArray(value) || value.length === 0) {
+        issues.push(issue('invalid_type', at, 'Expected a non-empty file digest array.'));
+        return;
+    }
+    const exactItems = new Set();
+    for (const [index, candidate] of value.entries()) {
+        const rowAt = `${at}[${index}]`;
+        if (!isRecord(candidate)) {
+            issues.push(issue('invalid_type', rowAt, 'Expected a file digest object.'));
+            continue;
+        }
+        rejectUnknownKeys(candidate, FILE_DIGEST_KEYS, rowAt, issues);
+        requireKeys(candidate, ['path', 'sha256', 'byteLength'], rowAt, issues);
+        validateRelativePath(candidate, 'path', rowAt, issues);
+        validateSha256(candidate, 'sha256', rowAt, issues);
+        if (hasOwn(candidate, 'byteLength') &&
+            (typeof candidate.byteLength !== 'number' || !Number.isInteger(candidate.byteLength) || candidate.byteLength < 0)) {
+            issues.push(issue('invalid_type', `${rowAt}.byteLength`, 'Expected a non-negative integer.'));
+        }
+        if (typeof candidate.path === 'string' &&
+            typeof candidate.sha256 === 'string' &&
+            typeof candidate.byteLength === 'number') {
+            const identity = `${candidate.path}\0${candidate.sha256}\0${candidate.byteLength}`;
+            if (exactItems.has(identity)) {
+                issues.push(issue('duplicate_manifest_item', rowAt, 'JSON Schema uniqueItems forbids duplicate file rows.'));
+            }
+            exactItems.add(identity);
+        }
+    }
+}
+export function validatePackageManifestStructureV1(value) {
+    if (!isRecord(value)) {
+        return { ok: false, issues: [issue('invalid_type', '$', 'Expected a PackageManifestV1 object.')] };
+    }
+    const issues = [];
+    rejectUnknownKeys(value, MANIFEST_KEYS, '$', issues);
+    requireKeys(value, [
+        'schemaVersion',
+        'assetKind',
+        'name',
+        'version',
+        'versionId',
+        'entryFile',
+        'standard',
+        'packageSha256',
+        'files',
+        'provenance',
+    ], '$', issues);
+    if (hasOwn(value, 'schemaVersion') && value.schemaVersion !== 1) {
+        issues.push(issue('schema_incompatible', '$.schemaVersion', 'Only PackageManifest schema version 1 is supported.'));
+    }
+    if (hasOwn(value, 'assetKind') && value.assetKind !== 'community-core' && value.assetKind !== 'skill-package') {
+        issues.push(issue('invalid_value', '$.assetKind', 'Unknown package asset kind.'));
+    }
+    for (const key of ['name', 'version', 'versionId', 'standard']) {
+        validateNonEmptyString(value, key, '$', issues);
+    }
+    validateRelativePath(value, 'entryFile', '$', issues);
+    validateSha256(value, 'packageSha256', '$', issues);
+    validateFileDigests(value.files, issues);
+    if (hasOwn(value, 'compatibility'))
+        validateCompatibility(value.compatibility, issues);
+    const provenance = validateProvenance(value.provenance, issues);
+    if (value.assetKind === 'community-core') {
+        if (value.name !== 'aops')
+            issues.push(issue('invalid_value', '$.name', 'Community core name must be aops.'));
+        if (value.entryFile !== 'SKILL.md') {
+            issues.push(issue('invalid_value', '$.entryFile', 'Community core entry file must be SKILL.md.'));
+        }
+        if (value.standard !== 'aops-community-core-v1') {
+            issues.push(issue('invalid_value', '$.standard', 'Community core standard must be aops-community-core-v1.'));
+        }
+        if (provenance?.trustClass !== 'signed-community-release') {
+            issues.push(issue('invalid_value', '$.provenance.trustClass', 'Community core must use signed-community-release.'));
+        }
+        if (provenance?.expectedDigestSource !== 'signed-release-manifest') {
+            issues.push(issue('invalid_value', '$.provenance.expectedDigestSource', 'Community core must use signed-release-manifest.'));
+        }
+    }
+    if (value.assetKind === 'skill-package') {
+        if (value.entryFile !== 'SKILL.md') {
+            issues.push(issue('invalid_value', '$.entryFile', 'Skill package entry file must be SKILL.md.'));
+        }
+        if (value.standard !== 'aops-skill-package-v1') {
+            issues.push(issue('invalid_value', '$.standard', 'Skill package standard must be aops-skill-package-v1.'));
+        }
+        if (provenance?.trustClass !== 'verified-hosted-package') {
+            issues.push(issue('invalid_value', '$.provenance.trustClass', 'Skill package must use verified-hosted-package.'));
+        }
+        if (provenance?.expectedDigestSource !== 'immutable-hosted-metadata') {
+            issues.push(issue('invalid_value', '$.provenance.expectedDigestSource', 'Skill package must use immutable-hosted-metadata.'));
+        }
+    }
+    return issues.length > 0
+        ? { ok: false, issues }
+        : { ok: true, value: value };
+}
+export function sha256Bytes(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function canonicalPackageSha256V1(files) {
+    const records = files.map((file) => {
+        if (!SHA256_HEX.test(file.sha256))
+            throw new TypeError('invalid_file_sha256');
+        return { path: file.path.normalize('NFC'), sha256: file.sha256 };
+    });
+    records.sort((left, right) => Buffer.compare(Buffer.from(left.path, 'utf8'), Buffer.from(right.path, 'utf8')));
+    const hash = createHash('sha256');
+    for (const record of records) {
+        hash.update(Buffer.from(record.path, 'utf8'));
+        hash.update(Buffer.from([0]));
+        hash.update(record.sha256, 'ascii');
+        hash.update(Buffer.from([0x0a]));
+    }
+    return hash.digest('hex');
+}
+function transferFileRecord(value) {
+    return isRecord(value) && typeof value.path === 'string' && value.bytes instanceof Uint8Array;
+}
+export function validatePortablePackageV1(manifestValue, transferFiles) {
+    const structural = validatePackageManifestStructureV1(manifestValue);
+    if (!structural.ok)
+        return structural;
+    const manifest = structural.value;
+    const issues = [];
+    const rawManifestPaths = new Set();
+    const normalizedManifestPaths = new Set();
+    const foldedManifestPaths = new Set();
+    const normalizedRows = [];
+    for (const [index, row] of manifest.files.entries()) {
+        const normalizedPath = row.path.normalize('NFC');
+        const foldedPath = portablePackageCaseKeyV1(normalizedPath);
+        if (rawManifestPaths.has(row.path)) {
+            issues.push(issue('duplicate_raw_path', `$.files[${index}].path`, 'Duplicate raw manifest path.'));
+        }
+        if (normalizedManifestPaths.has(normalizedPath)) {
+            issues.push(issue('duplicate_normalized_path', `$.files[${index}].path`, 'Duplicate NFC manifest path.'));
+        }
+        if (foldedManifestPaths.has(foldedPath)) {
+            issues.push(issue('portable_case_collision', `$.files[${index}].path`, 'Portable Unicode case-fold collision.'));
+        }
+        rawManifestPaths.add(row.path);
+        normalizedManifestPaths.add(normalizedPath);
+        foldedManifestPaths.add(foldedPath);
+        normalizedRows.push({ ...row, path: normalizedPath });
+    }
+    const normalizedEntryFile = manifest.entryFile.normalize('NFC');
+    if (!normalizedManifestPaths.has(normalizedEntryFile)) {
+        issues.push(issue('entry_file_missing', '$.entryFile', 'entryFile must name exactly one declared file.'));
+    }
+    const normalizedTransfer = new Map();
+    const rawTransferPaths = new Set();
+    const foldedTransferPaths = new Set();
+    for (const [index, candidate] of transferFiles.entries()) {
+        const at = `$transfer[${index}]`;
+        if (!transferFileRecord(candidate)) {
+            issues.push(issue('invalid_type', at, 'Expected { path, bytes: Uint8Array }.'));
+            continue;
+        }
+        const pathResult = validatePortablePackagePath(candidate.path);
+        if (!pathResult.ok) {
+            issues.push(issue('invalid_package_path', `${at}.path`, `Transfer path violates the portable package contract: ${pathResult.issues.map((entry) => entry.code).join(', ')}.`));
+            continue;
+        }
+        const normalizedPath = pathResult.normalizedPath;
+        const foldedPath = portablePackageCaseKeyV1(normalizedPath);
+        if (rawTransferPaths.has(candidate.path) || normalizedTransfer.has(normalizedPath)) {
+            issues.push(issue('duplicate_transfer_path', `${at}.path`, 'Duplicate raw or NFC transfer path.'));
+        }
+        if (foldedTransferPaths.has(foldedPath)) {
+            issues.push(issue('portable_case_collision', `${at}.path`, 'Portable transfer path case-fold collision.'));
+        }
+        rawTransferPaths.add(candidate.path);
+        foldedTransferPaths.add(foldedPath);
+        if (!normalizedTransfer.has(normalizedPath))
+            normalizedTransfer.set(normalizedPath, candidate.bytes);
+    }
+    const missing = [...normalizedManifestPaths].filter((path) => !normalizedTransfer.has(path));
+    const undeclared = [...normalizedTransfer.keys()].filter((path) => !normalizedManifestPaths.has(path));
+    if (missing.length > 0 || undeclared.length > 0 || normalizedTransfer.size !== normalizedManifestPaths.size) {
+        issues.push(issue('transfer_membership_mismatch', '$transfer', `Transfer membership differs from the manifest (missing=${missing.length}, undeclared=${undeclared.length}).`));
+    }
+    for (const [index, row] of normalizedRows.entries()) {
+        const bytes = normalizedTransfer.get(row.path);
+        if (!bytes)
+            continue;
+        if (bytes.byteLength !== row.byteLength) {
+            issues.push(issue('file_byte_length_mismatch', `$.files[${index}].byteLength`, `Expected ${row.byteLength} bytes but received ${bytes.byteLength}.`));
+        }
+        if (sha256Bytes(bytes) !== row.sha256) {
+            issues.push(issue('file_digest_mismatch', `$.files[${index}].sha256`, 'Transferred file digest does not match.'));
+        }
+    }
+    const computedPackageSha256 = canonicalPackageSha256V1(normalizedRows);
+    if (computedPackageSha256 !== manifest.packageSha256) {
+        issues.push(issue('package_digest_mismatch', '$.packageSha256', 'Canonical package digest does not match.'));
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    const normalizedManifest = { ...manifest, entryFile: normalizedEntryFile, files: normalizedRows };
+    return {
+        ok: true,
+        value: {
+            manifest,
+            normalizedManifest,
+            packageSha256: computedPackageSha256,
+            portableValidationComplete: true,
+            nativeAliasValidation: 'required',
+        },
+    };
+}

package/dist/lib/agent-assets/portable-path.js

@@ -0,0 +1,67 @@
+import { portableCaseFoldUnicode15_1 } from './unicode-case-folding-v15-1.generated.js';
+export const MAX_PACKAGE_PATH_CODE_POINTS = 4096;
+export const MAX_PACKAGE_SEGMENT_UTF8_BYTES = 255;
+const WINDOWS_INVALID_SEGMENT_CHARACTERS = new Set(['<', '>', ':', '"', '\\', '|', '?', '*']);
+const WINDOWS_DEVICE_ALIAS = /^(?:CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|CLOCK\$|COM[0-9¹²³]|LPT[0-9¹²³])(?:\..*)?$/;
+function asciiUpper(value) {
+    let result = '';
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        result += codePoint >= 0x61 && codePoint <= 0x7a
+            ? String.fromCodePoint(codePoint - 0x20)
+            : character;
+    }
+    return result;
+}
+function isControl(codePoint) {
+    return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+}
+export function validatePortablePackagePath(value) {
+    const issues = [];
+    if (value.length === 0)
+        issues.push({ code: 'empty_path' });
+    if ([...value].length > MAX_PACKAGE_PATH_CODE_POINTS)
+        issues.push({ code: 'path_too_long' });
+    if (value.startsWith('/') || /^[A-Za-z]:/.test(value))
+        issues.push({ code: 'absolute_path' });
+    if (value.includes('\\'))
+        issues.push({ code: 'backslash' });
+    const segments = value.split('/');
+    for (const [segmentIndex, segment] of segments.entries()) {
+        if (segment.length === 0) {
+            issues.push({ code: 'empty_segment', segmentIndex });
+            continue;
+        }
+        if (segment === '.' || segment === '..')
+            issues.push({ code: 'dot_segment', segmentIndex });
+        if (segment.endsWith('.') || segment.endsWith(' ')) {
+            issues.push({ code: 'trailing_dot_or_space', segmentIndex });
+        }
+        if (Buffer.byteLength(segment.normalize('NFC'), 'utf8') > MAX_PACKAGE_SEGMENT_UTF8_BYTES) {
+            issues.push({ code: 'segment_too_long', segmentIndex });
+        }
+        if (WINDOWS_DEVICE_ALIAS.test(asciiUpper(segment))) {
+            issues.push({ code: 'windows_device_alias', segmentIndex });
+        }
+        for (const character of segment) {
+            const codePoint = character.codePointAt(0);
+            if (isControl(codePoint))
+                issues.push({ code: 'control_character', segmentIndex });
+            if (WINDOWS_INVALID_SEGMENT_CHARACTERS.has(character)) {
+                issues.push({
+                    code: character === ':' ? 'alternate_data_stream' : 'windows_invalid_character',
+                    segmentIndex,
+                });
+            }
+        }
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    return { ok: true, normalizedPath: segments.map((segment) => segment.normalize('NFC')).join('/') };
+}
+export function portablePackageCaseKeyV1(value) {
+    return value
+        .split('/')
+        .map((segment) => portableCaseFoldUnicode15_1(segment.normalize('NFC')).normalize('NFC'))
+        .join('/');
+}

package/dist/lib/agent-assets/release-input.js

@@ -0,0 +1,177 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { verifyCommunityAgentAssetsReleaseBundle, } from '../community-release-verifier.js';
+import { AgentAssetsError } from './envelope.js';
+import { sha256Bytes, validatePortablePackageV1 } from './package-manifest.js';
+function releaseInputError(code, message, details) {
+    return new AgentAssetsError(code, message, {
+        nextActions: ['Acquire an exact signed Community release bundle and retry without modifying its contents.'],
+        ...(details === undefined ? {} : { details }),
+    });
+}
+function safeReleaseFile(releaseRoot, reference) {
+    if (!reference ||
+        path.isAbsolute(reference) ||
+        reference.includes('\\') ||
+        reference.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
+        throw releaseInputError('invalid_package_path', 'Signed release contains an unsafe asset reference.', { reference });
+    }
+    const normalizedRoot = path.normalize(releaseRoot);
+    const rootStat = lstatSync(normalizedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw releaseInputError('link_unsafe_path', 'Signed release root is not a real directory.');
+    }
+    const realRoot = realpathSync.native(normalizedRoot);
+    const candidate = path.join(normalizedRoot, ...reference.split('/'));
+    const relative = path.relative(normalizedRoot, candidate);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw releaseInputError('invalid_package_path', 'Signed release asset escaped its root.');
+    }
+    let cursor = normalizedRoot;
+    for (const segment of reference.split('/')) {
+        cursor = path.join(cursor, segment);
+        if (!existsSync(cursor))
+            throw releaseInputError('not_found', 'Signed release asset is missing.', { reference });
+        if (lstatSync(cursor).isSymbolicLink()) {
+            throw releaseInputError('link_unsafe_path', 'Signed release asset traverses a link.', { reference });
+        }
+    }
+    const stat = lstatSync(candidate);
+    if (!stat.isFile())
+        throw releaseInputError('link_unsafe_path', 'Signed release asset is not a regular file.', { reference });
+    const realCandidate = realpathSync.native(candidate);
+    const realRelative = path.relative(realRoot, realCandidate);
+    if (realRelative.startsWith('..') || path.isAbsolute(realRelative)) {
+        throw releaseInputError('link_unsafe_path', 'Signed release asset resolves outside its root.', { reference });
+    }
+    return candidate;
+}
+function parseJsonBytes(bytes) {
+    try {
+        return JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch (error) {
+        throw releaseInputError('schema_incompatible', 'Community agent-asset package manifest is not valid JSON.', {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function loadVerifiedReleasePackage(bundle, pointer, expected) {
+    const { files, setSha256 } = bundle.agentAssets;
+    const manifestPath = safeReleaseFile(bundle.releaseRoot, pointer.manifestRef);
+    const manifestBaseRef = pointer.manifestRef.endsWith('/manifest.json')
+        ? pointer.manifestRef.slice(0, -'/manifest.json'.length)
+        : '';
+    if (!manifestBaseRef) {
+        throw releaseInputError('expected_manifest_required', 'Community package manifest reference has an unexpected shape.');
+    }
+    const signedRows = new Map(files.map((row) => [row.ref, row]));
+    const manifestSignedRow = signedRows.get(pointer.manifestRef);
+    if (!manifestSignedRow) {
+        throw releaseInputError('expected_manifest_required', 'Community package manifest is outside the signed asset closure.');
+    }
+    const manifestBytes = readFileSync(manifestPath);
+    if (manifestBytes.byteLength !== manifestSignedRow.byteLength ||
+        sha256Bytes(manifestBytes) !== manifestSignedRow.sha256) {
+        throw releaseInputError('hash_mismatch', 'Community package manifest changed after release verification.');
+    }
+    const manifestValue = parseJsonBytes(manifestBytes);
+    if (!manifestValue || typeof manifestValue !== 'object' || Array.isArray(manifestValue)) {
+        throw releaseInputError('schema_incompatible', 'Community package manifest must be an object.');
+    }
+    const candidateFiles = manifestValue.files;
+    if (!Array.isArray(candidateFiles)) {
+        throw releaseInputError('schema_incompatible', 'Community package manifest does not declare files.');
+    }
+    const transferFiles = [];
+    for (const candidate of candidateFiles) {
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate) || typeof candidate.path !== 'string') {
+            throw releaseInputError('schema_incompatible', 'Community package manifest contains an invalid file row.');
+        }
+        const reference = `${manifestBaseRef}/files/${candidate.path}`;
+        const signedRow = signedRows.get(reference);
+        if (!signedRow) {
+            throw releaseInputError('expected_manifest_required', 'A declared Community package file is outside the signed closure.', {
+                reference,
+            });
+        }
+        const bytes = readFileSync(safeReleaseFile(bundle.releaseRoot, reference));
+        if (bytes.byteLength !== signedRow.byteLength || sha256Bytes(bytes) !== signedRow.sha256) {
+            throw releaseInputError('hash_mismatch', 'Signed Community package file changed after release verification.', {
+                reference,
+            });
+        }
+        transferFiles.push({ path: candidate.path, bytes });
+    }
+    const validation = validatePortablePackageV1(manifestValue, transferFiles);
+    if (!validation.ok) {
+        throw releaseInputError('hash_mismatch', 'Signed Community package failed the portable package contract.', {
+            issues: validation.issues,
+        });
+    }
+    const manifest = validation.value.normalizedManifest;
+    if (manifest.assetKind !== expected.assetKind ||
+        pointer.name !== manifest.name ||
+        pointer.version !== manifest.version ||
+        pointer.versionId !== manifest.versionId ||
+        pointer.packageSha256 !== manifest.packageSha256 ||
+        pointer.entryFile !== manifest.entryFile ||
+        pointer.optional !== expected.optional) {
+        throw releaseInputError('hash_mismatch', 'Signed release package pointer and package manifest disagree.');
+    }
+    return {
+        releaseRoot: realpathSync.native(bundle.releaseRoot),
+        manifestRef: pointer.manifestRef,
+        manifestSha256: manifestSignedRow.sha256,
+        packageRef: {
+            name: manifest.name,
+            version: manifest.version,
+            versionId: manifest.versionId,
+            packageSha256: manifest.packageSha256,
+            entryFile: manifest.entryFile,
+            origin: expected.origin,
+            trustClass: manifest.provenance.trustClass,
+        },
+        manifest,
+        transferFiles,
+        validation: validation.value,
+        releaseSetSha256: setSha256,
+    };
+}
+export function loadVerifiedCommunityCoreReleaseInput(bundle) {
+    const loaded = loadVerifiedReleasePackage(bundle, bundle.agentAssets.core, {
+        assetKind: 'community-core',
+        optional: false,
+        origin: 'bundled',
+    });
+    if (loaded.manifest.assetKind !== 'community-core') {
+        throw releaseInputError('schema_incompatible', 'Community core package kind changed after validation.');
+    }
+    return loaded;
+}
+export function loadVerifiedCommunityCatalogReleaseInputs(bundle) {
+    const loaded = bundle.agentAssets.catalog.packages.map((pointer) => {
+        const candidate = loadVerifiedReleasePackage(bundle, pointer, {
+            assetKind: 'skill-package',
+            optional: true,
+            origin: 'reserved-catalog',
+        });
+        if (candidate.manifest.assetKind !== 'skill-package') {
+            throw releaseInputError('schema_incompatible', 'Community catalog package kind changed after validation.');
+        }
+        return Object.freeze({
+            ...candidate,
+            manifest: candidate.manifest,
+            releaseTrustClass: 'signed-community-release',
+        });
+    });
+    return Object.freeze(loaded.sort((left, right) => Buffer.compare(Buffer.from(`${left.manifest.name}\0${left.manifest.versionId}`, 'utf8'), Buffer.from(`${right.manifest.name}\0${right.manifest.versionId}`, 'utf8'))));
+}
+export async function verifyAndLoadCommunityCoreReleaseInput(options) {
+    const bundle = await verifyCommunityAgentAssetsReleaseBundle(options);
+    return loadVerifiedCommunityCoreReleaseInput(bundle);
+}
+export async function verifyAndLoadCommunityCatalogReleaseInputs(options) {
+    const bundle = await verifyCommunityAgentAssetsReleaseBundle(options);
+    return loadVerifiedCommunityCatalogReleaseInputs(bundle);
+}

package/dist/lib/agent-assets/roots.js

@@ -0,0 +1,45 @@
+import os from 'node:os';
+import path from 'node:path';
+import { getAgentAssetsConfig } from '../../utils/config.js';
+function selectRoot(name, candidates) {
+    const selected = candidates.find((candidate) => candidate.value !== undefined && candidate.value.trim().length > 0);
+    if (!selected?.value)
+        throw new Error(`agent_assets_${name}_missing`);
+    const candidate = selected.value.trim();
+    if (!path.isAbsolute(candidate))
+        throw new Error(`agent_assets_${name}_must_be_absolute`);
+    return Object.freeze({
+        absolutePath: path.normalize(candidate),
+        source: selected.source,
+    });
+}
+export function resolveAgentAssetsRoots(options = {}) {
+    const env = options.env ?? process.env;
+    const homeDir = options.homeDir ?? os.homedir();
+    if (!path.isAbsolute(homeDir))
+        throw new Error('agent_assets_home_must_be_absolute');
+    const config = options.config ?? getAgentAssetsConfig();
+    const dataRoot = selectRoot('dataRoot', [
+        { value: options.dataRoot, source: 'option' },
+        { value: env.AOPS_AGENT_ASSETS_DATA_ROOT, source: 'environment' },
+        { value: config.dataRoot, source: 'user-config' },
+        { value: path.join(homeDir, '.aops'), source: 'default' },
+    ]);
+    const codex = selectRoot('codexHome', [
+        { value: options.codexHome, source: 'option' },
+        { value: env.CODEX_HOME, source: 'environment' },
+        { value: config.runtimeHomes?.codex, source: 'user-config' },
+        { value: path.join(homeDir, '.codex'), source: 'default' },
+    ]);
+    const claude = selectRoot('claudeHome', [
+        { value: options.claudeHome, source: 'option' },
+        { value: env.CLAUDE_HOME, source: 'environment' },
+        { value: config.runtimeHomes?.claude, source: 'user-config' },
+        { value: path.join(homeDir, '.claude'), source: 'default' },
+    ]);
+    return Object.freeze({
+        dataRoot,
+        assetRoot: path.join(dataRoot.absolutePath, 'agent-assets'),
+        runtimeHomes: Object.freeze({ codex, claude }),
+    });
+}