evolcore 0.0.1 → 0.0.2

package/dist/aun/aid/identity.js

@@ -0,0 +1,518 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { getAidStore, loadAid, loadClient, AidLoadError, SLOT } from './store.js';
+import { downloadCaRoot } from './client.js';
+import { resolvePaths, agentMdPath, aunPath as defaultAunPath } from '../../paths.js';
+// ==================== Validation ====================
+export function isValidAid(name) {
+    const labels = name.split('.');
+    return labels.length >= 3 && labels.every(l => /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(l));
+}
+/**
+ * 根据扫描得到的状态推断 AID 分类。
+ *  - hasPrivateKey + signVerified=true            → mine
+ *  - hasPrivateKey + (signVerified=false 或未实测) → broken
+ *  - !hasPrivateKey + hasCert                     → peer-cert
+ *  - !hasPrivateKey + !hasCert                    → no-cert
+ */
+function categorizeAid(info) {
+    if (info.hasPrivateKey) {
+        if (info.signVerified === true)
+            return 'mine';
+        return 'broken';
+    }
+    return info.hasCert ? 'peer-cert' : 'no-cert';
+}
+// ==================== AID Operations ====================
+export function aidList(aunPath) {
+    const root = aunPath ?? defaultAunPath();
+    const aunAidsDir = path.join(root, 'AIDs');
+    const seen = new Map();
+    if (fs.existsSync(aunAidsDir)) {
+        for (const e of fs.readdirSync(aunAidsDir, { withFileTypes: true })) {
+            if (!e.isDirectory())
+                continue;
+            const aidDir = path.join(aunAidsDir, e.name);
+            const keyJsonPath = path.join(aidDir, 'private', 'key.json');
+            const hasPrivateKey = fs.existsSync(path.join(aidDir, 'private'));
+            const certPath = path.join(aidDir, 'public', 'cert.pem');
+            let hasCert = false;
+            let certExpired = false;
+            let keyMatchesCert = null;
+            if (fs.existsSync(certPath)) {
+                hasCert = true;
+                try {
+                    const certPem = fs.readFileSync(certPath, 'utf-8');
+                    const x509 = new crypto.X509Certificate(certPem);
+                    certExpired = new Date(x509.validTo) < new Date();
+                    if (hasPrivateKey && fs.existsSync(keyJsonPath)) {
+                        try {
+                            const kp = JSON.parse(fs.readFileSync(keyJsonPath, 'utf-8'));
+                            const localPubB64 = typeof kp?.public_key_der_b64 === 'string' ? kp.public_key_der_b64 : '';
+                            if (localPubB64) {
+                                const certPubDer = x509.publicKey.export({ type: 'spki', format: 'der' });
+                                const localPubDer = Buffer.from(localPubB64, 'base64');
+                                keyMatchesCert = certPubDer.equals(localPubDer);
+                            }
+                        }
+                        catch { /* key.json 不可解析视作不匹配 */
+                            keyMatchesCert = false;
+                        }
+                    }
+                }
+                catch {
+                    // 证书无法解析视为过期 / 不可用
+                    certExpired = true;
+                }
+            }
+            seen.set(e.name, {
+                aid: e.name,
+                category: categorizeAid({
+                    hasPrivateKey,
+                    hasCert,
+                    // 静态扫描没跑实测，用 canSign 作为 mine/broken 的近似判定
+                    signVerified: hasPrivateKey ? (hasCert && !certExpired && keyMatchesCert === true) : null,
+                    canSign: hasPrivateKey && hasCert && !certExpired && keyMatchesCert === true,
+                }),
+                hasPrivateKey,
+                hasAgentMd: fs.existsSync(agentMdPath(e.name)),
+                hasCert,
+                certExpired,
+                keyMatchesCert,
+                canSign: hasPrivateKey && hasCert && !certExpired && keyMatchesCert === true,
+                signVerified: null,
+            });
+        }
+    }
+    return [...seen.values()];
+}
+// ==================== Sign Self-Test ====================
+/**
+ * 实跑一次本地 sign + verify，验证 AID 是否真能签名/验签。
+ * 全本地（不联网）：用 SDK 解密私钥 → ECDSA 签 payload → 用本地 cert 公钥验。
+ * 任一环节失败都视为不可签——包括私钥 passphrase 解不开、cert 被 SDK 主动 discard 等。
+ */
+export async function verifySignAbility(aid, opts) {
+    const aunPath = opts?.aunPath ?? defaultAunPath();
+    let ownStore = null;
+    try {
+        let store = opts?.store;
+        if (!store) {
+            store = await getAidStore({ slotId: SLOT.cli, aunPath });
+            ownStore = store;
+        }
+        // 加载本地 AID 值对象（含私钥），sign + verify 全本地完成
+        let aidObj;
+        try {
+            aidObj = loadAid(store, aid);
+        }
+        catch (e) {
+            const code = e instanceof AidLoadError ? e.code : 'LOAD_FAILED';
+            return { ok: false, reason: `load failed: ${code} ${String(e?.message || e).slice(0, 100)}` };
+        }
+        const probe = `# probe\naid: "${aid}"\n`;
+        const signRes = aidObj.signAgentMd(probe);
+        if (!signRes.ok) {
+            return { ok: false, reason: `sign failed: ${String(signRes.error?.message || signRes.error?.code).slice(0, 120)}` };
+        }
+        const verifyRes = aidObj.verifyAgentMd(signRes.data.signed);
+        if (!verifyRes.ok) {
+            return { ok: false, reason: `verify threw: ${String(verifyRes.error?.message || verifyRes.error?.code).slice(0, 120)}` };
+        }
+        if (verifyRes.data.status === 'verified')
+            return { ok: true };
+        return { ok: false, reason: `verify failed: ${verifyRes.data.status ?? 'unknown'}${verifyRes.data.reason ? ' — ' + verifyRes.data.reason : ''}` };
+    }
+    finally {
+        if (ownStore) {
+            try {
+                ownStore.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/**
+ * aidList 的"实测版"：先做静态扫描，再对每个 AID 跑一次本地 sign+verify。
+ * 共用同一个 AUNClient 实例，避免重复初始化 secret-store / sqlite。
+ */
+export async function aidListVerified(aunPath) {
+    const list = aidList(aunPath);
+    const root = aunPath ?? defaultAunPath();
+    const store = await getAidStore({ slotId: SLOT.cli, aunPath: root });
+    try {
+        for (const a of list) {
+            // canSign=false 的 AID 不必跑实测，结论已经明确
+            if (!a.canSign) {
+                a.signVerified = false;
+                if (!a.hasPrivateKey)
+                    a.signError = 'no private key';
+                else if (!a.hasCert)
+                    a.signError = 'no cert';
+                else if (a.certExpired)
+                    a.signError = 'cert expired';
+                else if (a.keyMatchesCert === false)
+                    a.signError = 'key/cert public-key mismatch';
+                a.category = categorizeAid({
+                    hasPrivateKey: a.hasPrivateKey, hasCert: a.hasCert,
+                    signVerified: a.signVerified, canSign: a.canSign,
+                });
+                continue;
+            }
+            const r = await verifySignAbility(a.aid, { aunPath: root, store });
+            a.signVerified = r.ok;
+            if (!r.ok)
+                a.signError = r.reason;
+            a.category = categorizeAid({
+                hasPrivateKey: a.hasPrivateKey, hasCert: a.hasCert,
+                signVerified: a.signVerified, canSign: a.canSign,
+            });
+        }
+    }
+    finally {
+        try {
+            store.close();
+        }
+        catch { /* ignore */ }
+    }
+    return list;
+}
+export async function aidCreate(aid, opts) {
+    const aunPath = opts?.aunPath ?? defaultAunPath();
+    const aidDir = path.join(aunPath, 'AIDs', aid);
+    const hasPrivateKey = fs.existsSync(path.join(aidDir, 'private'));
+    // 如果私钥已存在，先验证签名能力
+    if (hasPrivateKey) {
+        const verifyResult = await verifySignAbility(aid, { aunPath });
+        if (verifyResult.ok) {
+            // 身份有效：加载并认证，返回已认证的 client
+            const store = await getAidStore({ slotId: SLOT.cli, aunPath });
+            try {
+                const client = await loadClient(store, aid);
+                const auth = await client.authenticate();
+                return { aid, alreadyExisted: true, gateway: String(auth?.gateway ?? ''), client, store };
+            }
+            catch (e) {
+                store.close();
+                throw e;
+            }
+        }
+        // 签名验证失败
+        if (!opts?.force) {
+            const error = new Error(`AID ${aid} 已存在但身份无效（${verifyResult.reason || '签名验证失败'}）。\n` +
+                `使用 --force 参数尝试恢复或重新注册。`);
+            error.code = 'AID_INVALID';
+            error.reason = verifyResult.reason;
+            throw error;
+        }
+        // --force：先尝试 authenticate 恢复证书
+        const recoverStore = await getAidStore({ slotId: SLOT.cli, aunPath });
+        try {
+            const recoverClient = await loadClient(recoverStore, aid);
+            const auth = await recoverClient.authenticate();
+            return { aid, alreadyExisted: true, gateway: String(auth?.gateway ?? ''), client: recoverClient, store: recoverStore };
+        }
+        catch {
+            recoverStore.close();
+            fs.rmSync(aidDir, { recursive: true, force: true });
+        }
+    }
+    // 新注册流程：AIDStore.register → downloadCaRoot → load → authenticate
+    const store = await getAidStore({ slotId: SLOT.cli, aunPath });
+    try {
+        const regResult = await store.register(aid);
+        if (!regResult.ok) {
+            const e = new Error(regResult.error.message);
+            e.code = regResult.error.code;
+            throw e;
+        }
+        // 注册成功后下载 CA 根证书（如果还没有）
+        // 从 AID well-known 发现 gateway 用于 CA 下载
+        let gatewayUrl = '';
+        try {
+            const { GatewayDiscovery } = await import('@agentunion/fastaun');
+            const discovery = new GatewayDiscovery({});
+            gatewayUrl = await discovery.discover(`https://${aid}/.well-known/aun-gateway`);
+        }
+        catch { /* fall through */ }
+        if (gatewayUrl) {
+            await downloadCaRoot(aunPath, gatewayUrl);
+        }
+        // 重建 store（CA 可能刚下载，需要 rootCaPath 生效）
+        store.close();
+        const store2 = await getAidStore({ slotId: SLOT.cli, aunPath });
+        try {
+            const client = await loadClient(store2, aid);
+            await client.authenticate();
+            return { aid, alreadyExisted: false, gateway: gatewayUrl, client, store: store2 };
+        }
+        catch (e) {
+            store2.close();
+            throw e;
+        }
+    }
+    catch (e) {
+        store.close();
+        throw e;
+    }
+}
+// ==================== Show ====================
+export async function aidShow(aid, opts) {
+    const aunPath = opts?.aunPath ?? defaultAunPath();
+    const aidDir = path.join(aunPath, 'AIDs', aid);
+    const hasPrivateKey = fs.existsSync(path.join(aidDir, 'private'));
+    const hasAgentMd = fs.existsSync(agentMdPath(aid));
+    let certExpiresAt = null;
+    let certSubject = null;
+    let certExpired = false;
+    let certPem = null;
+    let keyMatchesCert = null;
+    const certPath = path.join(aidDir, 'public', 'cert.pem');
+    if (fs.existsSync(certPath)) {
+        try {
+            certPem = fs.readFileSync(certPath, 'utf-8');
+            const x509 = new crypto.X509Certificate(certPem);
+            certExpiresAt = x509.validTo;
+            certSubject = x509.subject;
+            certExpired = new Date(x509.validTo) < new Date();
+            const keyJsonPath = path.join(aidDir, 'private', 'key.json');
+            if (hasPrivateKey && fs.existsSync(keyJsonPath)) {
+                try {
+                    const kp = JSON.parse(fs.readFileSync(keyJsonPath, 'utf-8'));
+                    const localPubB64 = typeof kp?.public_key_der_b64 === 'string' ? kp.public_key_der_b64 : '';
+                    if (localPubB64) {
+                        const certPubDer = x509.publicKey.export({ type: 'spki', format: 'der' });
+                        const localPubDer = Buffer.from(localPubB64, 'base64');
+                        keyMatchesCert = certPubDer.equals(localPubDer);
+                    }
+                }
+                catch {
+                    keyMatchesCert = false;
+                }
+            }
+        }
+        catch { /* ignore parse errors */ }
+    }
+    let agentMdSignature = 'unknown';
+    let agentMdSignatureReason;
+    let signVerified = null;
+    let signError;
+    // 先做一次签名自检（共享 store，避免重复起 SDK）
+    const store = await getAidStore({ slotId: SLOT.cli, aunPath });
+    try {
+        if (hasPrivateKey && certPem && !certExpired && keyMatchesCert !== false) {
+            const r = await verifySignAbility(aid, { aunPath, store });
+            signVerified = r.ok;
+            if (!r.ok)
+                signError = r.reason;
+        }
+        else {
+            signVerified = false;
+            if (!hasPrivateKey)
+                signError = 'no private key';
+            else if (!certPem)
+                signError = 'no cert';
+            else if (certExpired)
+                signError = 'cert expired';
+            else if (keyMatchesCert === false)
+                signError = 'key/cert public-key mismatch';
+        }
+        if (hasAgentMd) {
+            try {
+                const content = fs.readFileSync(agentMdPath(aid), 'utf-8');
+                if (!content.includes('AUN-SIGNATURE')) {
+                    agentMdSignature = 'unsigned';
+                }
+                else {
+                    // 用本地 AID 值对象验签（含本地 cert 公钥）
+                    const aidObj = loadAid(store, aid);
+                    const result = aidObj.verifyAgentMd(content);
+                    if (!result.ok) {
+                        agentMdSignature = 'unknown';
+                        agentMdSignatureReason = String(result.error?.message || result.error?.code).slice(0, 100);
+                    }
+                    else if (result.data.status === 'verified') {
+                        agentMdSignature = 'verified';
+                    }
+                    else if (result.data.status === 'unsigned') {
+                        agentMdSignature = 'unsigned';
+                    }
+                    else {
+                        agentMdSignature = 'invalid';
+                        agentMdSignatureReason = result.data.reason;
+                    }
+                }
+            }
+            catch (e) {
+                agentMdSignature = 'unknown';
+                agentMdSignatureReason = String(e?.message || e).slice(0, 100);
+            }
+        }
+    }
+    finally {
+        try {
+            store.close();
+        }
+        catch { }
+    }
+    return { aid, hasPrivateKey, hasAgentMd, certExpiresAt, certSubject, certExpired, keyMatchesCert, signVerified, signError, agentMdSignature, agentMdSignatureReason };
+}
+// ==================== Delete ====================
+export function aidDelete(aid, opts) {
+    const aunPath = opts?.aunPath ?? defaultAunPath();
+    const aidDir = path.join(aunPath, 'AIDs', aid);
+    if (!fs.existsSync(aidDir))
+        return false;
+    fs.rmSync(aidDir, { recursive: true, force: true });
+    return true;
+}
+export async function probePkiRecoverability(aid, opts) {
+    const aunPath = opts?.aunPath ?? defaultAunPath();
+    const timeoutMs = opts?.timeoutMs ?? 8000;
+    const keyJsonPath = path.join(aunPath, 'AIDs', aid, 'private', 'key.json');
+    if (!fs.existsSync(keyJsonPath))
+        return { kind: 'no-key' };
+    let localPubB64 = '';
+    try {
+        const kp = JSON.parse(fs.readFileSync(keyJsonPath, 'utf-8'));
+        if (typeof kp?.public_key_der_b64 !== 'string' || !kp.public_key_der_b64) {
+            return { kind: 'unknown', reason: 'key.json missing public_key_der_b64' };
+        }
+        localPubB64 = kp.public_key_der_b64;
+    }
+    catch (e) {
+        return { kind: 'unknown', reason: `key.json parse failed: ${String(e?.message || e).slice(0, 80)}` };
+    }
+    // 1. 发现网关
+    let gateway = '';
+    try {
+        const ctl = AbortSignal.timeout(timeoutMs);
+        const gwResp = await fetch(`https://${aid}/.well-known/aun-gateway`, { redirect: 'follow', signal: ctl });
+        if (gwResp.ok) {
+            const text = (await gwResp.text()).trim();
+            try {
+                const parsed = JSON.parse(text);
+                gateway = parsed?.gateways?.[0]?.url || text;
+            }
+            catch {
+                gateway = text;
+            }
+        }
+    }
+    catch (e) {
+        return { kind: 'no-server-record', reason: `gateway discovery failed: ${String(e?.message || e).slice(0, 80)}` };
+    }
+    if (!gateway)
+        return { kind: 'no-server-record', reason: 'no gateway for AID' };
+    // 2. 拉云端 cert
+    let certPem = '';
+    try {
+        const parsed = new URL(gateway);
+        const scheme = parsed.protocol === 'wss:' ? 'https:' : 'http:';
+        const certUrl = `${scheme}//${parsed.host}/pki/cert/${encodeURIComponent(aid)}`;
+        const ctl = AbortSignal.timeout(timeoutMs);
+        const resp = await fetch(certUrl, { redirect: 'follow', signal: ctl });
+        if (!resp.ok) {
+            return { kind: 'no-server-record', reason: `pki/cert HTTP ${resp.status}` };
+        }
+        certPem = (await resp.text()).trim();
+        if (!certPem.includes('BEGIN CERTIFICATE')) {
+            return { kind: 'no-server-record', reason: 'pki/cert returned non-cert content' };
+        }
+    }
+    catch (e) {
+        return { kind: 'no-server-record', reason: `pki/cert fetch failed: ${String(e?.message || e).slice(0, 80)}` };
+    }
+    // 3. 比对公钥
+    try {
+        const x509 = new crypto.X509Certificate(certPem);
+        const certPubDer = x509.publicKey.export({ type: 'spki', format: 'der' });
+        const localPubDer = Buffer.from(localPubB64, 'base64');
+        if (certPubDer.equals(localPubDer)) {
+            return { kind: 'recoverable', serverCertPubB64: certPubDer.toString('base64') };
+        }
+        return {
+            kind: 'unrecoverable',
+            reason: 'server has different public key registered, current local private key cannot be used',
+        };
+    }
+    catch (e) {
+        return { kind: 'unknown', reason: `cert parse failed: ${String(e?.message || e).slice(0, 80)}` };
+    }
+}
+// ==================== Lookup ====================
+export async function aidLookup(aid) {
+    // gateway：well-known 探测（保留，供 aid lookup 命令展示）
+    let gateway = '';
+    try {
+        const gwResp = await fetch(`https://${aid}/.well-known/aun-gateway`, { redirect: 'follow' });
+        if (gwResp.ok) {
+            const text = await gwResp.text();
+            // Response may be JSON with gateways array or plain URL
+            try {
+                const parsed = JSON.parse(text.trim());
+                if (parsed.gateways?.[0]?.url) {
+                    gateway = parsed.gateways[0].url;
+                }
+                else {
+                    gateway = text.trim();
+                }
+            }
+            catch {
+                gateway = text.trim();
+            }
+        }
+    }
+    catch { /* ignore */ }
+    const { agentmdGet } = await import('./agentmd.js');
+    const store = await getAidStore({ slotId: SLOT.cli });
+    try {
+        // 权威注册判据：PKI 证书 HEAD（与 agent.md 无关）
+        const existsResult = await store.exists(aid);
+        if (!existsResult.ok) {
+            return { exists: false, aid, gateway, error: existsResult.error?.message ?? 'exists check failed' };
+        }
+        const exists = existsResult.data.exists;
+        if (!exists) {
+            return { exists: false, aid, gateway };
+        }
+        // 已注册：尽力拉 agent.md content（无 agent.md 不影响 exists）
+        let content;
+        try {
+            content = await agentmdGet(aid, { store });
+        }
+        catch { /* registered but no agent.md — content stays undefined */ }
+        return { exists, aid, gateway, content };
+    }
+    finally {
+        store.close();
+    }
+}
+function lifecycleLogPath(aid) {
+    const aidName = aid.startsWith('@') ? aid.slice(1) : aid;
+    return path.join(resolvePaths().aidLogsDir, `${aidName}.jsonl`);
+}
+export function appendAidLifecycle(event) {
+    const filePath = lifecycleLogPath(event.aid);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, JSON.stringify(event) + '\n');
+}
+export function readAidLifecycle(aid, lastN = 50) {
+    const filePath = lifecycleLogPath(aid);
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        const events = [];
+        for (const line of lines.slice(-lastN)) {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch { }
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/aun/aid/index.js

@@ -0,0 +1,4 @@
+export { isValidAid, aidList, aidListVerified, aidCreate, aidShow, aidDelete, aidLookup, verifySignAbility, probePkiRecoverability, appendAidLifecycle, readAidLifecycle } from './identity.js';
+export { buildInitialAgentMd, agentmdGet, agentmdPut, agentmdSync, stripAgentMdSignature, updateAgentMdFrontmatterAvatar, updateAgentMdFrontmatterName } from './agentmd.js';
+export { MIN_AUN_CORE_SDK, AUN_CORE_SDK_PKG, isAunSdkVersionOk, resolveAunCoreSdkPkg, ensureAunSdk, isAunSdkReady, downloadCaRoot, suppressSdkLogs, } from './client.js';
+export { getAidStore, loadClient, loadAid, AidLoadError, SLOT } from './store.js';

package/dist/aun/aid/store.js

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Slot 命名约定（基于 fastaun 0.4.3 隔离键语义）。
+ *
+ * slotIsolationKey 取第一个分隔符（空格/'/'/':'）之前的部分作为隔离键，
+ * 隔离键相同 = 共享消费通道（token / seq 游标 / 消息过滤）。
+ *
+ *   'evolcore daemon'   → 隔离键 'evolcore'   ┐
+ *   'evolcore cli'      → 隔离键 'evolcore'   ├ 共享 evolcore 消费通道
+ *   'evolcore netcheck' → 隔离键 'evolcore'   ┘
+ *   'evolcore-bench'    → 隔离键 'evolcore-bench'（连字符非分隔符）→ 独立通道
+ *
+ * 设计意图：
+ *  - daemon 长连接 + cli 短连接共存于 evolcore 通道（1 长 + N 短，短连接不踢长连接）
+ *  - netcheck 长连接抢 evolcore 长连接位 → 踢掉 daemon（用于踢人/extra_info 测试）
+ *  - bench 各并发单元用 evolcore-bench-<N>，各自独立隔离键，互不干扰
+ */
+export const SLOT = {
+    daemon: 'evolcore daemon',
+    cli: 'evolcore cli',
+    bench: 'evolcore-bench',
+    netcheck: 'evolcore netcheck',
+};
+/** 加载身份失败时抛出，携带 SDK 的错误码与消息。 */
+export class AidLoadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AidLoadError';
+        this.code = code;
+    }
+}
+/**
+ * 统一构造 AIDStore。
+ *
+ * 接管旧 createAunClient 的职责：注入 encryptionSeed、rootCaPath、debug、slotId。
+ * deviceId 不传 —— 由 SDK 从 {aunPath}/.device_id 读取或生成（同机共享）。
+ */
+export async function getAidStore(opts) {
+    const { aunPath: defaultAunPath } = await import('../../paths.js');
+    const { loadDaemonConfig } = await import('../../config-store.js');
+    const { AIDStore } = await import('@agentunion/fastaun');
+    const aunPath = opts.aunPath ?? defaultAunPath();
+    const encryptionSeed = loadDaemonConfig().aun?.encryptionSeed
+        ?? process.env.AUN_ENCRYPTION_SEED
+        ?? 'evol';
+    const caCertPath = path.join(aunPath, 'CA', 'root', 'root.crt');
+    const storeOpts = {
+        aunPath,
+        encryptionSeed,
+        slotId: opts.slotId,
+        debug: opts.debug ?? false,
+    };
+    if (fs.existsSync(caCertPath))
+        storeOpts.rootCaPath = caCertPath;
+    return new AIDStore(storeOpts);
+}
+/**
+ * 从 store 加载本地身份并构造已就绪的 AUNClient（尚未连接）。
+ *
+ * load 失败（证书缺失/过期/链断裂/私钥不匹配等）抛 AidLoadError，携带 SDK 错误码。
+ */
+export async function loadClient(store, aid) {
+    const { AUNClient } = await import('@agentunion/fastaun');
+    return new AUNClient(loadAid(store, aid));
+}
+/** 加载本地 AID 值对象（用于离线签名/验签，无需连接）。load 失败抛 AidLoadError。 */
+export function loadAid(store, aid) {
+    const r = store.load(aid);
+    if (!r.ok)
+        throw new AidLoadError(r.error.code, r.error.message);
+    return r.data.aid;
+}

package/dist/aun/aid/types.js

@@ -0,0 +1 @@
+export {};

package/dist/aun/aid/validation.js

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+import { isValidAid } from './identity.js';
+/**
+ * `agents/<dirName>` 是否能被当作合法的 self-agent 目录：
+ *   - 目录名通过 isValidAid（标准多级域名）
+ *   - 目录下存在 config.json
+ *
+ * 不满足返回原因字符串，调用方决定是 warn-and-skip 还是 throw。
+ */
+export function checkAgentDir(agentsDir, dirName) {
+    if (!isValidAid(dirName)) {
+        return `dir name "${dirName}" is not a valid AID`;
+    }
+    const configPath = path.join(agentsDir, dirName, 'config.json');
+    if (!fs.existsSync(configPath)) {
+        return `missing ${path.join(dirName, 'config.json')}`;
+    }
+    return null;
+}
+export { isValidAid };

package/dist/aun/group-identity.js

@@ -0,0 +1,10 @@
+export function isExplicitGroupId(value) {
+    const id = value.trim();
+    if (!id)
+        return false;
+    return (id.startsWith('group.') && id.includes('/'))
+        || /^\d+\.[a-z0-9.-]+$/i.test(id)
+        || /^grp_[a-z0-9_-]+$/i.test(id)
+        || /^g-[a-z0-9_-]+(?:[.@][a-z0-9.-]+)?$/i.test(id)
+        || /(?:^|\.)groupid\.pub$/i.test(id);
+}

package/dist/aun/msg/group-index.js

@@ -0,0 +1,6 @@
+export async function checkGroupIndex(client, groupId) {
+    return await client.group.checkGroupIndex({ group_id: groupId });
+}
+export async function getGroupIndex(client, groupId) {
+    return await client.group.getGroupIndex({ group_id: groupId });
+}