evolcore 0.0.1 → 0.0.2

package/dist/core/permission/unix-socket-policy.js

@@ -0,0 +1,99 @@
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths } from '../../paths.js';
+const MAX_SOCKET_SCAN_DEPTH = 16;
+const MAX_SOCKET_SCAN_ENTRIES = 4096;
+const MAX_ALLOWED_SOCKETS = 512;
+function normalize(value) {
+    const resolved = path.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function sameOrDescendant(candidate, parent) {
+    const relative = path.relative(normalize(parent), normalize(candidate));
+    return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+}
+function realpathIfExists(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function isSystemUnixSocketPath(socketPath) {
+    const normalized = normalize(socketPath);
+    const unixPath = normalized.split(path.sep).join('/');
+    if (unixPath === '/run' || unixPath.startsWith('/run/'))
+        return true;
+    if (unixPath === '/var/run' || unixPath.startsWith('/var/run/'))
+        return true;
+    if (/\/(?:docker|podman|containerd)(?:\.sock|\/)/i.test(unixPath))
+        return true;
+    if (/\/(?:dbus|systemd)(?:\.sock|\/)/i.test(unixPath))
+        return true;
+    if (/\/tmp\/ssh-[^/]+\/agent\.\d+$/i.test(unixPath))
+        return true;
+    if (/\/(?:gnupg|gpg-agent)(?:\/|\.sock|$)/i.test(unixPath))
+        return true;
+    return false;
+}
+function collectProjectUnixSockets(projectPath) {
+    const projectRoot = realpathIfExists(projectPath);
+    const sockets = [];
+    const seenDirs = new Set();
+    const stack = [{ dir: projectRoot, depth: 0 }];
+    let scanned = 0;
+    while (stack.length > 0 && scanned < MAX_SOCKET_SCAN_ENTRIES && sockets.length < MAX_ALLOWED_SOCKETS) {
+        const current = stack.pop();
+        let currentReal;
+        try {
+            currentReal = fs.realpathSync(current.dir);
+        }
+        catch {
+            continue;
+        }
+        if (seenDirs.has(currentReal) || !sameOrDescendant(currentReal, projectRoot))
+            continue;
+        seenDirs.add(currentReal);
+        let entries;
+        try {
+            entries = fs.readdirSync(currentReal, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (++scanned > MAX_SOCKET_SCAN_ENTRIES || sockets.length >= MAX_ALLOWED_SOCKETS)
+                break;
+            const entryPath = path.join(currentReal, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (current.depth < MAX_SOCKET_SCAN_DEPTH)
+                    stack.push({ dir: entryPath, depth: current.depth + 1 });
+                continue;
+            }
+            if (!entry.name.endsWith('.sock'))
+                continue;
+            try {
+                const stat = fs.lstatSync(entryPath);
+                if (stat.isSocket() && !isSystemUnixSocketPath(entryPath))
+                    sockets.push(entryPath);
+            }
+            catch { }
+        }
+    }
+    return sockets;
+}
+export function buildClaudeUnixSocketAllowlist(projectPath, context = {}) {
+    const sockets = new Set();
+    for (const socketPath of collectProjectUnixSockets(projectPath)) {
+        sockets.add(socketPath);
+    }
+    if (context.role === 'owner' || context.role === 'admin') {
+        const instanceSocket = resolvePaths().instanceSocket;
+        if (!isSystemUnixSocketPath(instanceSocket))
+            sockets.add(instanceSocket);
+    }
+    return [...sockets];
+}

package/dist/core/protected-paths.js

@@ -0,0 +1,330 @@
+import fs from 'fs';
+import path from 'path';
+import { resolveRoot } from '../paths.js';
+const H_CLASS_RELATIVE_PATTERNS = [
+    /^daemon\.json$/,
+    /^agents\/defaults\.json$/,
+    /^agents\/[^/]+\/config\.json$/,
+    /^agents\/[^/]+\/contact\.json$/,
+    /^agents\/[^/]+\/roles(?:\/|$)/,
+    /^agents\/[^/]+\/relations\/[^/]+\/config\.json$/,
+    /^backups\/config(?:\/|$)/,
+    /^\.snapshots(?:\/|$)/,
+    /^CA(?:\/|$)/,
+    /^(?:AIDs|aids)\/[^/]+\/(?:cert|keys)(?:\/|$)/,
+    /^\.device_id$/,
+    /^\.env$/,
+    /^\.seed(?:\.|$)/,
+    /^\.migrated-/,
+    /(?:^|\/)[^/]+\.json_$/,
+    /(?:^|\/)[^/]+\.json\.migrated$/,
+    /^agents\/defaults_\d+\.json$/,
+    /^\.lock$/,
+    /^daemon\.pid$/,
+    /^data\/causation-aun\.json(?:_|__)?$/,
+    /^data\/message-queue\.json(?:_|__|\.tmp-.*)?$/,
+    /^data\/instance\/control\.token$/,
+    /^data\/outbox(?:\/|$)/,
+    /^data\/handoff(?:\/|$)/,
+];
+const H_CLASS_REFERENCE_PATTERNS = [
+    /(?:^|[^A-Za-z0-9_.-])daemon\.json(?=$|[^A-Za-z0-9_.-])/,
+    /(?:^|[^A-Za-z0-9_.-])agents[\\/](?:defaults\.json|[^/\\\s"']+[\\/](?:(?:config|contact)\.json|relations[\\/][^/\\\s"']+[\\/]config\.json))(?=$|[\s"';&|<>)},])/,
+    /(?:^|[^A-Za-z0-9_.-])agents[\\/][^/\\\s"']+[\\/]roles(?:[\\/]|$|[\s"';&|<>)},])/,
+    /(?:^|[^A-Za-z0-9_.-])(?:backups[\\/]config|\.snapshots|CA|(?:AIDs|aids)[\\/][^/\\\s"']+[\\/](?:cert|keys))(?:[\\/]|$|[\s"';&|<>)},])/,
+    /(?:^|[/\\\s"'=<>])(?:\.device_id|\.env|\.seed(?:\.[^/\\\s"']*)?|\.migrated-[^/\\\s"']*|\.lock|daemon\.pid|data[\\/](?:causation-aun\.json(?:_|__)?|message-queue\.json(?:_|__|\.tmp-[^/\\\s"']*)?|instance[\\/]control\.token|outbox|handoff))(?:[\\/]|$|[\s"';&|<>)},])/,
+    /(?:^|[/\\\s"'=<>])(?:[^/\\\s"']+\.json_|[^/\\\s"']+\.json\.migrated|defaults_\d+\.json)(?=$|[\s"';&|<>)},])/,
+];
+const L_CLASS_RELATIVE_PATTERNS = [
+    /^data\/triggers(?:\/|$)/,
+];
+const L_CLASS_REFERENCE_PATTERNS = [
+    /(?:^|[/\\\s"'=<>])data[\\/]triggers(?:[\\/]|$|[\s"';&|<>)},])/,
+];
+function normalizeForComparison(value) {
+    const resolved = path.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function resolveThroughExistingAncestor(value) {
+    const absolute = path.resolve(value);
+    const missing = [];
+    let cursor = absolute;
+    while (!fs.existsSync(cursor)) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return absolute;
+        missing.unshift(path.basename(cursor));
+        cursor = parent;
+    }
+    try {
+        return path.join(fs.realpathSync(cursor), ...missing);
+    }
+    catch {
+        return absolute;
+    }
+}
+export function isSameOrDescendant(candidate, parent) {
+    const normalizedCandidate = normalizeForComparison(candidate);
+    const normalizedParent = normalizeForComparison(parent);
+    const relative = path.relative(normalizedParent, normalizedCandidate);
+    return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+}
+export function resolveProtectedCandidate(value, cwd = process.cwd()) {
+    const absolute = path.isAbsolute(value) ? value : path.resolve(cwd, value);
+    return resolveThroughExistingAncestor(absolute);
+}
+export function isHClassPath(value, options = {}) {
+    const root = resolveThroughExistingAncestor(options.root ?? resolveRoot());
+    const lexicalCandidate = path.isAbsolute(value)
+        ? path.resolve(value)
+        : path.resolve(options.cwd ?? process.cwd(), value);
+    if (isSameOrDescendant(lexicalCandidate, root)) {
+        const lexicalRelative = path.relative(root, lexicalCandidate).split(path.sep).join('/');
+        if (H_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(lexicalRelative)))
+            return true;
+    }
+    const candidate = resolveProtectedCandidate(value, options.cwd);
+    if (!isSameOrDescendant(candidate, root))
+        return false;
+    const relative = path.relative(root, candidate).split(path.sep).join('/');
+    return H_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(relative));
+}
+export function containsHClassReference(value) {
+    const normalized = value.replace(/\\/g, '/');
+    const unquoted = normalized.replace(/^["']|["']$/g, '').replace(/[;,) ]+$/, '');
+    if (H_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(unquoted)))
+        return true;
+    return H_CLASS_REFERENCE_PATTERNS.some(pattern => pattern.test(normalized));
+}
+/** L-class paths are readable by agents but may only be mutated by trusted daemon paths. */
+export function isLClassPath(value, options = {}) {
+    const root = resolveThroughExistingAncestor(options.root ?? resolveRoot());
+    const lexicalCandidate = path.isAbsolute(value)
+        ? path.resolve(value)
+        : path.resolve(options.cwd ?? process.cwd(), value);
+    if (isSameOrDescendant(lexicalCandidate, root)) {
+        const lexicalRelative = path.relative(root, lexicalCandidate).split(path.sep).join('/');
+        if (L_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(lexicalRelative)))
+            return true;
+    }
+    const candidate = resolveProtectedCandidate(value, options.cwd);
+    if (!isSameOrDescendant(candidate, root))
+        return false;
+    const relative = path.relative(root, candidate).split(path.sep).join('/');
+    return L_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(relative));
+}
+export function containsLClassReference(value) {
+    const normalized = value.replace(/\\/g, '/');
+    const unquoted = normalized.replace(/^["']|["']$/g, '').replace(/[;,) ]+$/, '');
+    if (L_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(unquoted)))
+        return true;
+    return L_CLASS_REFERENCE_PATTERNS.some(pattern => pattern.test(normalized));
+}
+export function getHClassSandboxPatterns(root = resolveRoot()) {
+    const absoluteRoot = resolveThroughExistingAncestor(root);
+    const entries = [
+        'daemon.json',
+        path.join('agents', 'defaults.json'),
+        path.join('agents', '*', 'config.json'),
+        path.join('agents', '*', 'contact.json'),
+        path.join('agents', '*', 'roles'),
+        path.join('agents', '*', 'roles', '**'),
+        path.join('agents', '*', 'relations', '*', 'config.json'),
+        path.join('backups', 'config'),
+        path.join('backups', 'config', '**'),
+        '.snapshots',
+        path.join('.snapshots', '**'),
+        'CA',
+        path.join('CA', '**'),
+        path.join('AIDs', '*', 'cert'),
+        path.join('AIDs', '*', 'cert', '**'),
+        path.join('AIDs', '*', 'keys'),
+        path.join('AIDs', '*', 'keys', '**'),
+        path.join('aids', '*', 'cert'),
+        path.join('aids', '*', 'cert', '**'),
+        path.join('aids', '*', 'keys'),
+        path.join('aids', '*', 'keys', '**'),
+        '.device_id',
+        '.env',
+        '.seed',
+        '.seed.*',
+        '.migrated-*',
+        path.join('**', '*.json_'),
+        path.join('**', '*.json.migrated'),
+        path.join('agents', 'defaults_*.json'),
+        '.lock',
+        'daemon.pid',
+        path.join('data', 'causation-aun.json*'),
+        path.join('data', 'message-queue.json*'),
+        path.join('data', 'instance', 'control.token'),
+        path.join('data', 'outbox'),
+        path.join('data', 'outbox', '**'),
+        path.join('data', 'handoff'),
+        path.join('data', 'handoff', '**'),
+    ];
+    return entries.map(entry => path.join(absoluteRoot, entry));
+}
+export function getLClassWritePatterns(root = resolveRoot()) {
+    const absoluteRoot = resolveThroughExistingAncestor(root);
+    return [
+        path.join(absoluteRoot, 'data', 'triggers'),
+        path.join(absoluteRoot, 'data', 'triggers', '**'),
+    ];
+}
+const CLAUDE_PROTECTED_TARGET_LIMIT = 8192;
+const CLAUDE_GLOB_MAGIC = /[*?[\]]/;
+function addExistingTarget(targets, value) {
+    try {
+        const stat = fs.lstatSync(value);
+        targets.set(path.resolve(value), {
+            path: path.resolve(value),
+            kind: stat.isDirectory() ? 'directory' : 'file',
+        });
+    }
+    catch { }
+}
+export function getExistingHClassMaskTargets(root = resolveRoot()) {
+    const absoluteRoot = resolveThroughExistingAncestor(root);
+    const targets = new Map();
+    for (const relative of [
+        'daemon.json', 'backups/config', '.snapshots', 'CA',
+        '.device_id', '.env', '.seed', '.lock', 'daemon.pid',
+        'data/causation-aun.json', 'data/message-queue.json', 'data/message-queue.json_', 'data/message-queue.json__',
+        'data/instance/control.token',
+        'data/outbox', 'data/handoff',
+    ]) {
+        addExistingTarget(targets, path.join(absoluteRoot, relative));
+    }
+    try {
+        for (const entry of fs.readdirSync(absoluteRoot)) {
+            if (entry.startsWith('.seed.') || entry.startsWith('.migrated-') || entry.endsWith('.json.migrated')) {
+                addExistingTarget(targets, path.join(absoluteRoot, entry));
+            }
+        }
+    }
+    catch { }
+    const agentsDir = path.join(absoluteRoot, 'agents');
+    addExistingTarget(targets, path.join(agentsDir, 'defaults.json'));
+    try {
+        for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (entry.name.match(/^defaults_\d+\.json$/) || entry.name.endsWith('.json_') || entry.name.endsWith('.json.migrated')) {
+                addExistingTarget(targets, path.join(agentsDir, entry.name));
+            }
+            if (!entry.isDirectory())
+                continue;
+            const agentRoot = path.join(agentsDir, entry.name);
+            for (const fileName of ['config.json', 'config.json_', 'contact.json', 'contact.json_']) {
+                addExistingTarget(targets, path.join(agentRoot, fileName));
+            }
+            addExistingTarget(targets, path.join(agentRoot, 'roles'));
+            const relationsDir = path.join(agentRoot, 'relations');
+            try {
+                for (const relation of fs.readdirSync(relationsDir, { withFileTypes: true })) {
+                    if (!relation.isDirectory())
+                        continue;
+                    for (const fileName of ['config.json', 'config.json_']) {
+                        addExistingTarget(targets, path.join(relationsDir, relation.name, fileName));
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    for (const aidsName of ['AIDs', 'aids']) {
+        const aidsRoot = path.join(absoluteRoot, aidsName);
+        try {
+            for (const aid of fs.readdirSync(aidsRoot, { withFileTypes: true })) {
+                if (!aid.isDirectory())
+                    continue;
+                addExistingTarget(targets, path.join(aidsRoot, aid.name, 'cert'));
+                addExistingTarget(targets, path.join(aidsRoot, aid.name, 'keys'));
+            }
+        }
+        catch { }
+    }
+    return [...targets.values()];
+}
+export function getExistingLClassReadOnlyTargets(root = resolveRoot()) {
+    const targets = new Map();
+    addExistingTarget(targets, path.join(resolveThroughExistingAncestor(root), 'data', 'triggers'));
+    return [...targets.values()];
+}
+export function buildClaudeProtectedFilesystem(root = resolveRoot()) {
+    const hClassPaths = getExistingHClassMaskTargets(root).map(target => target.path);
+    const lClassPaths = getExistingLClassReadOnlyTargets(root).map(target => target.path);
+    const allPaths = [...new Set([...hClassPaths, ...lClassPaths])];
+    if (allPaths.length > CLAUDE_PROTECTED_TARGET_LIMIT) {
+        throw new Error(`[ClaudeSandbox] protected target limit exceeded: ${allPaths.length} > ${CLAUDE_PROTECTED_TARGET_LIMIT}`);
+    }
+    for (const target of allPaths) {
+        if (!path.isAbsolute(target)) {
+            throw new Error(`[ClaudeSandbox] protected target must be absolute: ${target}`);
+        }
+        if (CLAUDE_GLOB_MAGIC.test(target)) {
+            throw new Error(`[ClaudeSandbox] glob paths are unsupported on Linux sandbox projections: ${target}`);
+        }
+    }
+    return {
+        denyRead: [...new Set(hClassPaths)],
+        denyWrite: allPaths,
+    };
+}
+export function buildCodexHClassFilesystemRules(root = resolveRoot()) {
+    return {
+        // Codex pre-expands unbounded deny globs on Linux/WSL/Windows. Without a
+        // bound, patterns such as **/*.json_ are accepted but may not be enforced.
+        glob_scan_max_depth: 64,
+        ...Object.fromEntries(getHClassSandboxPatterns(root).map(pattern => [pattern, 'deny'])),
+    };
+}
+export function buildCodexProtectedFilesystemRules(root = resolveRoot()) {
+    return {
+        ...buildCodexHClassFilesystemRules(root),
+        ...Object.fromEntries(getLClassWritePatterns(root).map(pattern => [pattern, 'read'])),
+    };
+}
+export function hClassGrantIncludesProtectedPath(value, options = {}) {
+    const root = resolveThroughExistingAncestor(options.root ?? resolveRoot());
+    if (containsHClassReference(value))
+        return true;
+    const normalized = value.replace(/\\/g, '/');
+    const globIndex = normalized.search(/[*?[{]/);
+    const literalGrantRoot = globIndex < 0
+        ? value
+        : normalized.slice(0, globIndex).replace(/\/+$/, '') || '.';
+    const candidate = resolveProtectedCandidate(literalGrantRoot, options.cwd);
+    if (isHClassPath(candidate, { root }))
+        return true;
+    if (isSameOrDescendant(root, candidate))
+        return true;
+    if (!isSameOrDescendant(candidate, root))
+        return false;
+    // A filesystem grant is a range, not a one-file allow. Every directory
+    // below the protected root can contain an H-class backup name (for example
+    // *.json_), so an overlay grant there could bypass the baseline deny rules.
+    return true;
+}
+export function lClassGrantIncludesProtectedPath(value, options = {}) {
+    const root = resolveThroughExistingAncestor(options.root ?? resolveRoot());
+    const protectedRoot = path.join(root, 'data', 'triggers');
+    if (isLClassPath(value, { cwd: options.cwd, root }))
+        return true;
+    const normalized = value.replace(/\\/g, '/');
+    const globIndex = normalized.search(/[*?[{]/);
+    const literalGrantRoot = globIndex < 0
+        ? value
+        : normalized.slice(0, globIndex).replace(/\/+$/, '') || '.';
+    const candidate = resolveProtectedCandidate(literalGrantRoot, options.cwd);
+    return isSameOrDescendant(candidate, protectedRoot)
+        || isSameOrDescendant(protectedRoot, candidate);
+}
+export function workspaceContainsHClassPaths(projectPath, root = resolveRoot()) {
+    const project = resolveThroughExistingAncestor(projectPath);
+    const protectedRoot = resolveThroughExistingAncestor(root);
+    if (isSameOrDescendant(protectedRoot, project))
+        return true;
+    if (!isSameOrDescendant(project, protectedRoot))
+        return false;
+    return hClassGrantIncludesProtectedPath(project, { root: protectedRoot });
+}

package/dist/core/relation/peer-identity.js

@@ -0,0 +1,222 @@
+/**
+ * PeerIdentityCache - 对端身份缓存管理
+ *
+ * 职责：
+ * 1. 通过 agentmdSync 标准流程获取对端 agent.md（check → fetch if changed）
+ * 2. 仅在 agent.md 内容变化时重写 peer-identity.json
+ * 3. 支持入站和出站消息的身份查询
+ *
+ * 信源：对端的 agent.md（通过 AIDStore.checkAgentMd + downloadAgentMd，由 agentmdSync 封装）
+ * 判定规则：type !== 'human' → agent
+ * 缓存位置：$AGENT_DIR/relations/<channel>#<urlEncode(peerId)>/peer-identity.json
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { logger } from '../../utils/logger.js';
+import { agentMdPath } from '../../paths.js';
+/**
+ * peerKey: 关系层路由键，格式 `<channelType>#<urlEncode(channelId)>`。
+ * 群聊场景下 channelId = groupId，所有发言者共用同一个 peerKey。
+ */
+export function formatPeerKey(channelType, channelId) {
+    return `${channelType}#${encodeURIComponent(channelId)}`;
+}
+export function parsePeerKey(key) {
+    const idx = key.indexOf('#');
+    if (idx <= 0)
+        throw new Error(`Invalid peer key: ${key}`);
+    return {
+        channelType: key.slice(0, idx),
+        channelId: decodeURIComponent(key.slice(idx + 1)),
+    };
+}
+/**
+ * 对端身份缓存管理器
+ */
+export class PeerIdentityCache {
+    /** 缓存最大时效：30 天 */
+    static CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+    /**
+     * 获取 peer-identity.json 文件路径
+     */
+    static getFilePath(channelType, peerId, agentDir) {
+        const peerKey = formatPeerKey(channelType, peerId);
+        return path.join(agentDir, 'relations', peerKey, 'peer-identity.json');
+    }
+    /**
+     * 从文件读取缓存
+     * @returns PeerIdentity | null（缓存不存在）
+     */
+    static get(channelType, peerId, agentDir) {
+        const filePath = this.getFilePath(channelType, peerId, agentDir);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 检查缓存是否需要刷新
+     * @param maxAgeMs 最大缓存时间（默认 30 天）
+     * @returns true=需要刷新
+     */
+    static needsRefresh(channelType, peerId, agentDir, maxAgeMs = this.CACHE_MAX_AGE_MS) {
+        const cached = this.get(channelType, peerId, agentDir);
+        if (!cached)
+            return true;
+        return Date.now() - cached.lastCheckedAt > maxAgeMs;
+    }
+    /**
+     * 从 agent.md 更新身份信息
+     * @param source 'agentmd'（验签通过）或 'agentmd-unverified'（内容可解析但验签未过）
+     * @param verifiedAt 验签通过时间戳；未验签传 0
+     */
+    static updateFromAgentMd(channelType, peerId, agentDir, agentMd, verifiedAt, source = 'agentmd') {
+        const typeMatch = agentMd.match(/^type:\s*["']?([^"'\n]+?)["']?\s*$/m);
+        const nameMatch = agentMd.match(/^name:\s*["']?(.+?)["']?\s*$/m);
+        const type = typeMatch?.[1] || 'unknown';
+        const isAgent = type !== 'human';
+        const name = nameMatch?.[1]?.trim();
+        const agentMdHash = 'sha256:' + crypto.createHash('sha256').update(agentMd, 'utf-8').digest('hex');
+        const now = Date.now();
+        const identity = {
+            aid: peerId,
+            type,
+            isAgent,
+            name,
+            agentMdHash,
+            agentMdUpdatedAt: now,
+            verifiedAt,
+            lastCheckedAt: now,
+            source,
+        };
+        const filePath = this.getFilePath(channelType, peerId, agentDir);
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, JSON.stringify(identity, null, 2), 'utf-8');
+            logger.debug(`[PeerIdentityCache] Updated: ${channelType}#${peerId} type=${type} isAgent=${isAgent} source=${source}`);
+        }
+        catch (err) {
+            logger.warn(`[PeerIdentityCache] Failed to write cache: ${filePath} err=${err}`);
+        }
+        return identity;
+    }
+    /**
+     * 仅更新 lastCheckedAt（内容未变时的轻量操作）
+     */
+    static touchLastChecked(channelType, peerId, agentDir, cached) {
+        const updated = { ...cached, lastCheckedAt: Date.now() };
+        const filePath = this.getFilePath(channelType, peerId, agentDir);
+        try {
+            fs.writeFileSync(filePath, JSON.stringify(updated, null, 2), 'utf-8');
+        }
+        catch { /* ignore */ }
+        return updated;
+    }
+    /**
+     * 标记为 unknown（验签失败或无 agent.md）
+     */
+    static markUnknown(channelType, peerId, agentDir) {
+        const identity = {
+            aid: peerId,
+            type: 'unknown',
+            isAgent: true,
+            agentMdHash: '',
+            agentMdUpdatedAt: 0,
+            verifiedAt: 0,
+            lastCheckedAt: Date.now(),
+            source: 'unknown',
+        };
+        const filePath = this.getFilePath(channelType, peerId, agentDir);
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, JSON.stringify(identity, null, 2), 'utf-8');
+            logger.debug(`[PeerIdentityCache] Marked unknown: ${channelType}#${peerId}`);
+        }
+        catch (err) {
+            logger.warn(`[PeerIdentityCache] Failed to write unknown cache: ${filePath} err=${err}`);
+        }
+        return identity;
+    }
+    /**
+     * 完整流程：缓存检查 → agentmdSync（check+fetch）→ 按 changed 决定是否重写
+     *
+     * @param channelType 渠道类型（如 'aun'）
+     * @param peerId 对端 ID（AUN 是 AID）
+     * @param agentDir agent 数据根目录
+     * @param store AIDStore 实例（由调用方提供，负责 checkAgentMd + downloadAgentMd）
+     * @param forceRefresh 强制刷新（忽略缓存时效）
+     */
+    static async resolve(channelType, peerId, agentDir, store, forceRefresh = false) {
+        // 1. 缓存检查
+        if (!forceRefresh && !this.needsRefresh(channelType, peerId, agentDir)) {
+            const cached = this.get(channelType, peerId, agentDir);
+            if (cached) {
+                logger.debug(`[PeerIdentityCache] Cache hit: ${channelType}#${peerId} type=${cached.type} age=${Math.floor((Date.now() - cached.lastCheckedAt) / 1000 / 60 / 60 / 24)}d`);
+                return cached;
+            }
+        }
+        // 2. 通过 agentmdSync 拉取（内部走 store.checkAgentMd → store.downloadAgentMd）
+        try {
+            logger.debug(`[PeerIdentityCache] Syncing agent.md: ${channelType}#${peerId}`);
+            const { agentmdSync } = await import('../../aun/aid/agentmd.js');
+            const result = await agentmdSync(peerId, { store });
+            const content = result.content;
+            if (!content) {
+                throw new Error('agent.md content unavailable');
+            }
+            // 验签通过 → 可信（source=agentmd）；否则 type 仍解析但标记未验证
+            const verified = result.verification?.status === 'verified';
+            const source = verified ? 'agentmd' : 'agentmd-unverified';
+            if (!verified) {
+                logger.info(`[PeerIdentityCache] agent.md unverified for ${peerId}: status=${result.verification?.status ?? 'unknown'} reason=${result.verification?.reason ?? '-'} (type 仍按声明解析)`);
+            }
+            // 3. 比较 hash，内容与可信级别都未变时仅 touch
+            const newHash = 'sha256:' + crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+            const cached = this.get(channelType, peerId, agentDir);
+            if (cached && cached.agentMdHash === newHash && cached.source === source) {
+                return this.touchLastChecked(channelType, peerId, agentDir, cached);
+            }
+            return this.updateFromAgentMd(channelType, peerId, agentDir, content, verified ? Date.now() : 0, source);
+        }
+        catch (err) {
+            // 4. agentmdSync 抛错（非网络失败——网络失败时它内部已 fallback 返回本地内容；
+            //    这里通常是无内容或解析异常）。兜底读本地文件，但无法重新验签，
+            //    故沿用缓存里已有的可信级别，绝不凭空升级为已验签。
+            const localPath = agentMdPath(peerId);
+            try {
+                if (fs.existsSync(localPath)) {
+                    const localContent = fs.readFileSync(localPath, 'utf-8');
+                    const cached = this.get(channelType, peerId, agentDir);
+                    logger.info(`[PeerIdentityCache] Using local agent.md for ${peerId} (cached source=${cached?.source ?? 'none'})`);
+                    const localHash = 'sha256:' + crypto.createHash('sha256').update(localContent, 'utf-8').digest('hex');
+                    if (cached && cached.agentMdHash === localHash && (cached.source === 'agentmd' || cached.source === 'agentmd-unverified')) {
+                        return this.touchLastChecked(channelType, peerId, agentDir, cached);
+                    }
+                    // 无匹配缓存可信级别 → 本地内容未经本次验签，标记为未验证
+                    const fallbackSource = cached?.source === 'agentmd' ? 'agentmd' : 'agentmd-unverified';
+                    return this.updateFromAgentMd(channelType, peerId, agentDir, localContent, cached?.verifiedAt ?? 0, fallbackSource);
+                }
+            }
+            catch { /* ignore fs errors */ }
+            logger.warn(`[PeerIdentityCache] Failed to resolve: ${channelType}#${peerId} err=${err instanceof Error ? err.message : String(err)}`);
+            return this.markUnknown(channelType, peerId, agentDir);
+        }
+    }
+    /**
+     * 清除指定对端的缓存
+     */
+    static clear(channelType, peerId, agentDir) {
+        const filePath = this.getFilePath(channelType, peerId, agentDir);
+        try {
+            fs.unlinkSync(filePath);
+            logger.debug(`[PeerIdentityCache] Cleared: ${channelType}#${peerId}`);
+        }
+        catch {
+            // 文件不存在，忽略
+        }
+    }
+}

package/dist/core/relation/peer-key.js

@@ -0,0 +1 @@
+export * from './peer-identity.js';