@agentunion/fastaun 0.5.26 → 0.5.27

package/dist/tools/cross-sdk-agent.js

@@ -4,6 +4,7 @@ import * as https from 'node:https';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { URL } from 'node:url';
@@ -11,13 +12,38 @@ import { fileURLToPath } from 'node:url';
 import { AUNClient } from '../client.js';
 import { AID } from '../aid.js';
 import { AIDStore } from '../aid-store.js';
-import { publicKeyFingerprint } from '../cert-utils.js';
+import { certCommonName, certFingerprint, isStrictBase64, publicKeyFingerprint, verifySignatureWithCert } from '../cert-utils.js';
+import { validateAgentMdCertificate } from '../agent-md-schema.js';
+import { createDefaultSecretStore } from '../secret-store/index.js';
+import { normalizeGroupId } from '../group-id.js';
+import { validateAIDFormat } from '../validators.js';
 import { VERSION } from '../version.js';
 import { canonicalJson, digest, buildRequestBinding, verifyMembershipBinding, ProtocolError } from '../org-protocol.js';
+import { decodeBase64 as semanticBase64, decodeSignedJson, digest as semanticDigest, validateStatusProof, SemanticProtocolError } from '../semantic-protocol.js';
 import { TimeoutError } from '../errors.js';
 const credentialProcessStartupId = crypto.randomUUID();
+const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
 const cacheReadContext = new AsyncLocalStorage();
 const cacheReadObservers = new WeakMap();
+function loadTrustedArchive(configPath, issuer) {
+    if (!configPath)
+        return undefined;
+    const value = jsonObjectOf(JSON.parse(fs.readFileSync(configPath, 'utf8')));
+    const owner = value?.owner_aid, routed = typeof owner === 'string' && owner.indexOf('.') > 0 && owner.indexOf('.') < owner.length - 1;
+    if (!value || Object.keys(value).some(key => !['service_aid', 'objects', 'owner_aid'].includes(key)) || Object.keys(value).length !== (routed ? 3 : 2) || ('owner_aid' in value && !routed) || value.service_aid !== `storage.${routed ? owner.slice(owner.indexOf('.') + 1) : issuer}` || !Array.isArray(value.objects))
+        throw new Error('ARCHIVE_SERVICE_UNTRUSTED');
+    const objects = new Map();
+    for (const row of value.objects) {
+        const item = jsonObjectOf(row);
+        if (!item || Object.keys(item).length !== 3 || !['object_id', 'object_version', 'share_id'].every(key => typeof item[key] === 'string' && item[key]))
+            throw new Error('ARCHIVE_OBJECT_UNTRUSTED');
+        const key = JSON.stringify([item.object_id, item.object_version]);
+        if (objects.has(key))
+            throw new Error('ARCHIVE_OBJECT_DUPLICATE');
+        objects.set(key, item.share_id);
+    }
+    return { serviceAid: value.service_aid, ...(routed ? { ownerAid: owner } : {}), objects };
+}
 function acquireCacheReadObserver(target, key, wrap) {
     let observers = cacheReadObservers.get(target);
     if (!observers) {
@@ -147,6 +173,10 @@ export class CrossSdkTsAgent {
     slotId = textOf(process.env.AUN_TEST_SLOT_ID || `cross-sdk-ts-${crypto.randomUUID().slice(0, 8)}`).trim();
     aunPath = textOf(process.env.AUN_TEST_AUN_PATH || process.env.AUN_DATA_ROOT || '/data/aun').trim();
     debug = envBool('AUN_TEST_DEBUG', false);
+    semanticReaderIdentityDir = textOf(process.env.AUN_SEMANTIC_READER_IDENTITY_DIR).trim();
+    semanticReaderAid = textOf(process.env.AUN_SEMANTIC_READER_AID).trim();
+    semanticReaderSeed = process.env.AUN_TEST_ENCRYPTION_SEED || process.env.AUN_ENCRYPTION_SEED || '';
+    semanticArchive = loadTrustedArchive(textOf(process.env.AUN_TEST_SEMANTIC_ARCHIVE_CONFIG), this.issuer);
     client;
     ready = false;
     startupError = '';
@@ -740,7 +770,10 @@ export class CrossSdkTsAgent {
                 const identity = JSON.parse(fs.readFileSync(fixedIdentityFile, 'utf-8'));
                 if (identity.aid !== this.aid)
                     throw new Error('固定测试身份与配置 AID 不一致');
-                store._keystore.saveIdentity(this.aid, identity);
+                const local = store.load(this.aid);
+                if (!local.ok || !local.data.aid.isPrivateKeyValid()) {
+                    store._keystore.saveIdentity(this.aid, identity);
+                }
             }
             const registered = fixedIdentityFile ? store.load(this.aid) : await store.register(this.aid, { type: 'service' });
             if (!registered.ok) {
@@ -913,6 +946,7 @@ export class CrossSdkTsAgent {
             error_code: errorCode,
             raw_sha256: sha256Json(data),
             ...metadata,
+            ...(decrypted && jsonObjectOf(data._semantic_evidence) ? { _semantic_evidence: structuredClone(data._semantic_evidence) } : {}),
         };
     }
     normalizeGroupMessage(msg, decrypted, errorCode = '') {
@@ -934,6 +968,7 @@ export class CrossSdkTsAgent {
             error_code: errorCode,
             raw_sha256: sha256Json(data),
             ...metadata,
+            ...(decrypted && jsonObjectOf(data._semantic_evidence) ? { _semantic_evidence: structuredClone(data._semantic_evidence) } : {}),
         };
     }
     async storeGroupInboxItem(item) {
@@ -954,6 +989,7 @@ export class CrossSdkTsAgent {
                     aid: this.aid,
                     language: this.language,
                     sdk_version: this.sdkVersion,
+                    gateway_url: textOf(this.client._gatewayUrl),
                     startup_error: this.startupError,
                 });
                 return;
@@ -1775,8 +1811,11 @@ export class CrossSdkTsAgent {
             return buildRequestBinding(textOf(params.method), textOf(params.target), params.params, textOf(params.credential_cid), textOf(params.nonce), textOf(params.request_id), now, now + 300);
         if (op === 'revocation_checkpoint') {
             const internal = this.client;
-            if (params.sync === true)
-                await internal._getCredentialRenewal()._syncRevocations();
+            if (params.sync === true) {
+                const manager = internal._getCredentialRenewal();
+                manager.invalidateQueries();
+                await manager._syncRevocations();
+            }
             return internal._tokenStore._loadMetadataStrict(this.aid)?.credential_revocations_v1 ?? { version: 1, authorities: {} };
         }
         if (op === 'credential_process')
@@ -1870,6 +1909,333 @@ export class CrossSdkTsAgent {
         }
         return result;
     }
+    semanticReaderMessageContext() {
+        const root = this.semanticReaderIdentityDir, aid = this.semanticReaderAid;
+        if (!root && !aid)
+            return {};
+        if (!root || !aid || validateAIDFormat(aid) !== aid || !fs.statSync(root).isDirectory())
+            throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'fixed semantic reader identity is unavailable');
+        const device = fs.readFileSync(path.join(root, '.device_id'), 'utf8').trim(), directory = path.join(root, 'AIDs', aid);
+        if (!device)
+            throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original receiver device is unavailable');
+        const stored = JSON.parse(fs.readFileSync(path.join(directory, 'private', 'key.json'), 'utf8'));
+        const pem = stored.private_key_pem || (stored.private_key_protection && createDefaultSecretStore(root, this.semanticReaderSeed).reveal(aid, 'identity/private_key', stored.private_key_protection)?.toString('utf8'));
+        if (!pem)
+            throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original receiver identity key is unavailable');
+        const privateKey = crypto.createPrivateKey(pem), publicKey = crypto.createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+        const certPem = fs.readFileSync(path.join(directory, 'public', 'cert.pem'), 'utf8'), certificate = new crypto.X509Certificate(certPem);
+        const jwk = privateKey.export({ format: 'jwk' });
+        if (certCommonName(certPem) !== aid || jwk.kty !== 'EC' || jwk.crv !== 'P-256' || !jwk.d
+            || !publicKey.equals(certificate.publicKey.export({ format: 'der', type: 'spki' })))
+            throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original receiver certificate or key differs');
+        const ikPriv = new Uint8Array(Buffer.from(jwk.d, 'base64url'));
+        return { selfAid: aid, selfDeviceId: device, resolveDecryptionKeys: (envelope) => {
+                const row = Array.isArray(envelope.recipients) ? envelope.recipients.find((item) => Array.isArray(item) && item.length === 8 && item[0] === aid && (item[1] === device || item[1] === '')) : undefined;
+                const recipient = jsonObjectOf(envelope.recipient);
+                if (!row && (!recipient || recipient.aid !== aid || recipient.device_id !== device && recipient.device_id !== ''))
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original receiver row is unavailable');
+                let spkId = textOf(row ? row[5] : recipient.spk_id), groupId = envelope.type === 'e2ee.group_encrypted' ? textOf(envelope.aad?.group_id) : '';
+                if (!spkId)
+                    return { ikPriv };
+                const separator = spkId.indexOf('\0');
+                if (separator >= 0) {
+                    if (!groupId || normalizeGroupId(spkId.slice(0, separator)) !== normalizeGroupId(groupId))
+                        throw new SemanticProtocolError('SEMANTIC_BINDING_INVALID', 'original group SPK scope differs');
+                    spkId = spkId.slice(separator + 1);
+                }
+                const db = new DatabaseSync(path.join(directory, 'aun.db'), { readOnly: true });
+                try {
+                    const find = (type, group) => db.prepare('SELECT private_key FROM v2_device_keys WHERE device_id=? AND key_type=? AND group_id=? AND key_id=?').get(device, type, group, spkId);
+                    let key;
+                    if (groupId)
+                        for (const candidate of new Set([groupId, normalizeGroupId(groupId)])) {
+                            key = find('group_spk', candidate);
+                            if (key)
+                                break;
+                        }
+                    key ??= find('spk', '');
+                    if (key)
+                        return { ikPriv, spkPriv: new Uint8Array(key.private_key) };
+                    const alias = find('ik', '');
+                    if (alias)
+                        return { ikPriv: new Uint8Array(alias.private_key), spkPriv: new Uint8Array(alias.private_key) };
+                    if (spkId === 'sha256:' + crypto.createHash('sha256').update(publicKey).digest('hex').slice(0, 16))
+                        return { ikPriv, spkPriv: ikPriv };
+                    throw new SemanticProtocolError('SEMANTIC_STATE_UNAVAILABLE', 'original receiver SPK is unavailable');
+                }
+                finally {
+                    db.close();
+                }
+            } };
+    }
+    semanticHistoricalSenderContext(context) {
+        const certificates = jsonObjectOf(context.certificates);
+        if (!certificates || Object.keys(certificates).length === 0)
+            return {};
+        const key = (fingerprint) => new crypto.X509Certificate(textOf(certificates[fingerprint])).publicKey.export({ type: 'spki', format: 'der' });
+        return {
+            resolveSenderKey: async (_sender, _device, fingerprint) => new Uint8Array(key(fingerprint)),
+            verifySenderIdentity: async (sender, _device, fingerprint, signedAt, publicKey) => {
+                if (!key(fingerprint).equals(Buffer.from(publicKey)))
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'historical sender identity differs from message key');
+                await this.client._semanticVerificationContext().verifyCertificateTrust(textOf(certificates[fingerprint]), { expectedAID: sender, signedAt, now: Math.floor(Date.now() / 1000) });
+            },
+        };
+    }
+    semanticContext(context, nativeOnline = false, original) {
+        if (!nativeOnline && (['query', 'queries', 'query_started_monotonic', 'elapsed_seconds', 'elapsedSeconds', 'monotonicNow'].some(key => Object.hasOwn(context, key))
+            || context.policy !== undefined && jsonObjectOf(context.policy)?.mode !== 'bounded') || context.require_current_validity === false || context.legacy_context !== undefined) {
+            throw new SemanticProtocolError('SEMANTIC_FORMAT_INVALID', 'unsupported cross-process semantic verification context override');
+        }
+        const native = this.client._semanticVerificationContext();
+        const certificates = jsonObjectOf(context.certificates) ?? {};
+        const signers = jsonObjectOf(context.credential_signers);
+        const services = jsonObjectOf(context.credential_services);
+        const supplied = jsonObjectOf(original), credential = supplied && Object.hasOwn(supplied, 'bytes_base64') ? jsonObjectOf(decodeSignedJson(supplied)) : supplied;
+        const signer = credential && signers ? textOf(signers[semanticDigest(credential)]) : '';
+        const expectedAid = textOf(context.expected_aid);
+        if (signer && expectedAid && signer !== expectedAid)
+            throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'explicit signer differs from trusted original signer');
+        return { ...native, now: typeof context.now === 'number' ? context.now : Math.floor(Date.now() / 1000),
+            expectedAid: expectedAid || signer || textOf(credential?.iss) || undefined, expectedServiceAid: textOf(context.service_aid) || undefined,
+            audience: textOf(context.audience), statePolicy: context.policy,
+            resolveCertificate: async (fingerprint, aid, signedAt) => Object.hasOwn(certificates, fingerprint)
+                ? certificates[fingerprint] : native.resolveCertificate(fingerprint, aid, signedAt),
+            ...(signers ? { originalSigner: (entry) => {
+                    const signer = textOf(signers[semanticDigest(entry.credential)]) || entry.credential.iss;
+                    if (!signer)
+                        throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'trusted original signer is required');
+                    return signer;
+                } } : {}),
+            ...(services ? { serviceFor: (cid) => {
+                    const service = Object.hasOwn(services, cid) ? textOf(services[cid]) : '';
+                    if (!service)
+                        throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'trusted credential service is required');
+                    return service;
+                } } : {}),
+        };
+    }
+    trustedArchiveResolvers() {
+        const config = this.semanticArchive;
+        if (!config)
+            return {};
+        return { [config.serviceAid]: async (locator) => {
+                if (Object.keys(locator).length !== 4 || locator.resolver !== 'aun-evidence-archive/1' || locator.service_aid !== config.serviceAid)
+                    throw new Error('ARCHIVE_LOCATOR_UNTRUSTED');
+                const share = config.objects.get(JSON.stringify([locator.object_id, locator.object_version]));
+                if (!share)
+                    throw new Error('ARCHIVE_OBJECT_UNTRUSTED');
+                const result = jsonObjectOf(await this.client.call('storage.get_by_share', { share_id: share, ...(config.ownerAid ? { owner_aid: config.ownerAid } : {}) }));
+                if (!result || result.object_id !== locator.object_id || String(result.version) !== locator.object_version)
+                    throw new Error('ARCHIVE_OBJECT_VERSION_MISMATCH');
+                const content = result.content;
+                if (typeof content !== 'string' || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)
+                    || Buffer.from(content, 'base64').toString('base64') !== content)
+                    throw new Error('ARCHIVE_CONTENT_INVALID');
+                return new Uint8Array(Buffer.from(content, 'base64'));
+            } };
+    }
+    async verifySemanticRepresentative(request, context) {
+        for (const grant of context.representation_grants ?? []) {
+            const root = grant.lineage[0], leaf = grant.lineage.at(-1);
+            if (root.credential.iss !== request.sub || root.metadata.iss !== request.sub || leaf.metadata.sub !== request.actor || !root.credential.cap.some((cap) => cap.ns === request.ns && [request.action, '*'].includes(cap.action) && [request.resource, '*'].includes(cap.resource) && cap.constraints.length === 0)
+                || root.credential.authorization.kind !== 'text' || root.credential.authorization.text !== '签发者明确授权已确认持有人代表签发者执行所列能力，仅限本次隔离报告测试。')
+                continue;
+            const { params_hash: _paramsHash, request_binding: _binding, ...fixed } = request;
+            const represented = await this.client.credential.buildRequest({ ...fixed, sub: request.actor, grant,
+                request_id: request.request_id + '-representation', nonce: Buffer.from(semanticDigest([request.request_binding.request_hash, 'representation']).slice(7), 'hex').toString('base64url') });
+            const nested = { ...context, representation_grants: undefined, grantors: [request.sub],
+                credential_services: Object.fromEntries(grant.lineage.map((item) => [item.credential.cid, context.representation_service])),
+                credential_signers: Object.fromEntries(grant.lineage.map((item) => [semanticDigest(item.credential), item.metadata.iss])) };
+            const result = await this.semanticProtocol({ op: 'refresh_and_verify_request', params: represented, context: nested });
+            return result.report.request_bound === true;
+        }
+        return false;
+    }
+    async semanticProtocol(params) {
+        if (params.op === 'state_checkpoint')
+            return { startup_id: credentialProcessStartupId, aid: this.aid, scope_identity: this.client._semanticContextKey(), state: this.client._loadSemanticState() };
+        const facade = this.client.credential, op = textOf(params.op);
+        if (op === 'probe_online_status') {
+            const began = performance.now() / 1000, input = jsonObjectOf(params.params) ?? {}, target = textOf(params.target);
+            const query = { request_hash: textOf(params.request_hash), nonce: crypto.randomBytes(24).toString('base64url') };
+            const proof = await facade.status({ ...input, request_id: crypto.randomUUID(), nonce: query.nonce, query }, { serviceAid: target });
+            const expectedQuery = { ...query };
+            if (params.probe === 'nonce')
+                expectedQuery.nonce = 'AAAAAAAAAAAAAAAAAAAAAA';
+            if (params.probe === 'request_hash')
+                expectedQuery.request_hash = `sha256:${'0'.repeat(64)}`;
+            if (params.probe === 'timeout')
+                await new Promise(resolve => setTimeout(resolve, Math.max(0, 30100 - (performance.now() / 1000 - began) * 1000)));
+            const context = this.semanticContext({ service_aid: target, audience: input.audience }, true);
+            const report = await facade.verifyStatus(proof, { ...context, policy: { mode: 'online' },
+                query: params.probe === 'missing_query' ? undefined : expectedQuery, elapsedSeconds: performance.now() / 1000 - began });
+            return { proof, query, report, elapsed_seconds: performance.now() / 1000 - began };
+        }
+        if (op === 'refresh_and_verify_request') {
+            const began = performance.now() / 1000, request = structuredClone(params.params);
+            const input = jsonObjectOf(params.context) ?? {}, context = this.semanticContext({ ...input, now: Math.floor(Date.now() / 1000) }, true);
+            const query = { request_hash: request.request_binding.request_hash, nonce: crypto.randomBytes(24).toString('base64url') };
+            const queries = {};
+            const legacyProofs = new Map(), legacyChecks = [], reader = this.client.aid;
+            const legacyCertificate = async (aid, signature, verifiedAt = Math.floor(Date.now() / 1000)) => {
+                if (!signature || !Number.isSafeInteger(signature.timestamp) || signature.timestamp < 0 || signature.timestamp > Math.floor(Date.now() / 1000) + 300
+                    || typeof signature.cert_fingerprint !== 'string' || !/^sha256:[0-9a-f]{64}$/i.test(signature.cert_fingerprint)
+                    || typeof signature.signature !== 'string' || !isStrictBase64(signature.signature)
+                    || Object.keys(signature).some(key => !['cert_fingerprint', 'public_key_fingerprint', 'timestamp', 'signature'].includes(key)))
+                    throw new ProtocolError('CREDENTIAL_SIGNATURE_INVALID', 'legacy signature is invalid');
+                const resolved = await context.resolveCertificate(signature.cert_fingerprint, aid, signature.timestamp);
+                const material = resolved && typeof resolved === 'object' && !(resolved instanceof Uint8Array) ? resolved.certificatePem : resolved;
+                if (!material)
+                    throw new ProtocolError('CREDENTIAL_SIGNATURE_INVALID', 'legacy certificate is unavailable');
+                const certificate = new crypto.X509Certificate(typeof material === 'string' && !material.startsWith('-----BEGIN') ? Buffer.from(material, 'base64') : material).toString();
+                if (certFingerprint(certificate).toLowerCase() !== signature.cert_fingerprint.toLowerCase()
+                    || signature.public_key_fingerprint !== undefined && (typeof signature.public_key_fingerprint !== 'string' || publicKeyFingerprint(certificate).toLowerCase() !== signature.public_key_fingerprint.toLowerCase()))
+                    throw new ProtocolError('CREDENTIAL_SIGNATURE_INVALID', 'legacy certificate fingerprint differs');
+                validateAgentMdCertificate(certificate, aid, signature.timestamp, { now: verifiedAt, requireCurrentValidity: true });
+                await context.verifyCertificateTrust(certificate, { expectedAID: aid, signedAt: signature.timestamp, now: Math.floor(Date.now() / 1000) });
+                return certificate;
+            };
+            for (const entry of request.grant.lineage) {
+                const cid = entry.credential.cid;
+                if (!context.serviceFor)
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'trusted credential service is required');
+                const service = context.serviceFor(cid);
+                if (entry.credential.ver === 'aun-cap/1' && 'legacy' in entry) {
+                    const original = entry.credential, requestedAt = Math.floor(Date.now() / 1000);
+                    const statusQuery = { credential_cid: cid, include_chain: true, request_id: crypto.randomUUID(), nonce: crypto.randomBytes(24).toString('base64url') };
+                    statusQuery.request_binding = buildRequestBinding('credential.status', service, statusQuery, cid, String(statusQuery.nonce), String(statusQuery.request_id), requestedAt, requestedAt + 300);
+                    const proof = await facade.status(statusQuery), now = Math.floor(Date.now() / 1000);
+                    if (!reader || reader !== this.client.aid || !proof || proof.ver !== 'aun-credential-status/1' || proof.credentialCid !== cid || proof.credential_hash !== digest(original)
+                        || proof.issuerAid !== original.iss || proof.subjectAid !== original.sub || proof.expiresAt !== original.exp || proof.responder !== service
+                        || proof.target !== reader || proof.request_id !== statusQuery.request_id || proof.nonce !== statusQuery.nonce || proof.status !== 'active'
+                        || !Number.isSafeInteger(proof.asOf) || proof.asOf < 0 || !Number.isSafeInteger(proof.proofExpiresAt) || proof.proofExpiresAt <= proof.asOf
+                        || proof.proofExpiresAt > proof.asOf + 300 || proof.asOf > now + 300 || now > proof.proofExpiresAt + 300
+                        || proof.signature?.timestamp !== proof.asOf)
+                        throw new ProtocolError('CREDENTIAL_STATUS_UNKNOWN', 'fresh legacy status differs from credential or query');
+                    const certificate = await legacyCertificate(service, proof.signature), unsigned = { ...proof };
+                    delete unsigned.signature;
+                    if (!verifySignatureWithCert(certificate, Buffer.from(proof.signature.signature, 'base64'), Buffer.from(canonicalJson(unsigned))))
+                        throw new ProtocolError('CREDENTIAL_SIGNATURE_INVALID', 'fresh legacy status signature is invalid');
+                    entry.legacy.status_proof = proof;
+                    legacyProofs.set(cid, proof);
+                    continue;
+                }
+                if (entry.credential.ver !== 'aun-cap/semantic-1' || !('metadata' in entry))
+                    continue;
+                const semantic = entry;
+                queries[cid] = query;
+                semantic.status = await facade.status({ request_id: crypto.randomUUID(), nonce: crypto.randomBytes(24).toString('base64url'),
+                    credential_cid: cid, authority: input.authority, audience: context.audience,
+                    expected_revision: { cid, original_hash: semantic.metadata.original_hash, metadata_hash: semanticDigest(semantic.metadata), metadata_version: semantic.metadata.version },
+                    policy: { mode: 'online' }, query }, { serviceAid: service, verificationContext: context });
+            }
+            if (legacyProofs.size)
+                context.legacyVerifier = async (entry, audience) => {
+                    const original = entry.credential, index = request.grant.lineage.findIndex(item => item.credential.cid === original.cid && digest(item.credential) === digest(original));
+                    if (index < 0)
+                        throw new ProtocolError('CREDENTIAL_CHAIN_INVALID', 'legacy original differs from fixed request lineage');
+                    const ancestors = request.grant.lineage.slice(0, index).reverse().map(item => item.credential), root = ancestors.at(-1) ?? original;
+                    if (!Array.isArray(input.grantors) || !input.grantors.includes(root.iss))
+                        throw new ProtocolError('CREDENTIAL_CHAIN_INVALID', 'legacy root issuer is not trusted for this resource');
+                    const certificates = new Map();
+                    for (const document of [original, ...ancestors])
+                        certificates.set(document.signature.cert_fingerprint, await legacyCertificate(document.iss, document.signature));
+                    const receipt = 'legacy' in entry ? entry.legacy.registration_receipt : undefined;
+                    if (receipt) {
+                        const service = context.serviceFor(original.cid), certificate = await legacyCertificate(service, receipt.signature, receipt.registered_at);
+                        facade.verifyRegistrationReceipt(receipt, original, { request_id: receipt.request_id, nonce: receipt.nonce, registrar_aid: original.iss, proof_chain: ancestors }, () => certificate, service, receipt.registered_at);
+                    }
+                    const now = Math.floor(Date.now() / 1000), method = request.ns + '.' + request.action;
+                    const requestBinding = buildRequestBinding(method, request.target, request.params, original.cid, request.nonce, request.request_id, now, now + 300);
+                    const verifyLegacy = () => {
+                        facade.verify(original, { audience, subject: original.sub, actor: original.sub, rootIssuer: root.iss, ns: request.ns, action: request.action, resource: request.resource,
+                            params: request.params, method, target: request.target, requestId: request.request_id, nonce: request.nonce,
+                            requestBinding, proofChain: ancestors, resolveCertificate: fingerprint => certificates.get(fingerprint), resolveStatusProof: cid => legacyProofs.get(cid), now: Math.floor(Date.now() / 1000) });
+                    };
+                    verifyLegacy();
+                    legacyChecks.push(verifyLegacy);
+                };
+            const packageReport = await facade.verifyPackage(request.grant, { ...context, audience: context.audience, now: Math.floor(Date.now() / 1000),
+                statePolicy: { mode: 'online' }, queries, elapsedSeconds: performance.now() / 1000 - began });
+            const requestReport = await facade.verifyRequest(request, input.authenticated, { now: Math.floor(Date.now() / 1000), representedActor: () => this.verifySemanticRepresentative(request, input) });
+            const elapsedSeconds = performance.now() / 1000 - began;
+            if (!Number.isFinite(elapsedSeconds) || elapsedSeconds < 0 || elapsedSeconds >= 30)
+                throw new SemanticProtocolError('SEMANTIC_STATE_UNAVAILABLE', 'online status monotonic lifetime exceeded');
+            for (const entry of request.grant.lineage)
+                if (entry.credential.ver === 'aun-cap/semantic-1' && 'status' in entry) {
+                    validateStatusProof(entry.status, { mode: 'online' }, { now: Math.floor(Date.now() / 1000), elapsedSeconds, query });
+                }
+            for (const proof of legacyProofs.values())
+                if (reader !== this.client.aid || Math.floor(Date.now() / 1000) < Number(proof.asOf) - 300 || Math.floor(Date.now() / 1000) > Number(proof.proofExpiresAt) + 300)
+                    throw new ProtocolError('CREDENTIAL_STATUS_UNKNOWN', 'fresh legacy status expired before verification completed');
+            for (const verifyLegacy of legacyChecks)
+                verifyLegacy();
+            if (legacyChecks.length && performance.now() / 1000 - began >= 30)
+                throw new SemanticProtocolError('SEMANTIC_STATE_UNAVAILABLE', 'online status monotonic lifetime exceeded');
+            if (requestReport.request_hash !== query.request_hash)
+                throw new SemanticProtocolError('SEMANTIC_BINDING_INVALID', 'refreshed request hash differs');
+            return { request, language: 'typescript', report: { ...packageReport, request_bound: true, request_hash: requestReport.request_hash,
+                    checked: [...new Set([...packageReport.checked, ...requestReport.checked, 'lineage_structure', 'signatures', 'identities', 'revisions', 'state', 'usage_refs', 'authenticated_request'])],
+                    required: [...new Set([...packageReport.required, ...requestReport.required.filter(item => item !== 'package_verification')])] } };
+        }
+        const management = { register: 'register', revise: 'revise', get: 'get', status: 'status', revoke: 'revoke', revocations: 'revocations', prepare_usage: 'prepareUsage', commit_usage: 'commitUsage', abort_usage: 'abortUsage' };
+        if (Object.hasOwn(management, op)) {
+            const method = management[op];
+            return facade[method].call(facade, params.params, params.target ? { serviceAid: textOf(params.target) } : {});
+        }
+        const signatures = { sign_credential: 'signCredential', sign_metadata: 'signMetadata', sign_allocation: 'signAllocation' };
+        if (Object.hasOwn(signatures, op))
+            return facade[signatures[op]](params.value, undefined, typeof params.now === 'number' ? { timestamp: params.now } : {});
+        if (op === 'sign_usage_record')
+            return facade.signUsageRecord(params.domain, params.value, undefined, typeof params.now === 'number' ? { timestamp: params.now } : {});
+        if (op === 'build_package')
+            return facade.buildPackage(params.params.lineage);
+        if (op === 'build_request')
+            return facade.buildRequest(params.params, typeof params.now === 'number' ? { now: params.now } : {});
+        const verification = { verify_original: 'verifyOriginal', verify_metadata: 'verifyMetadata', verify_receipt: 'verifyReceipt', verify_package: 'verifyPackage' };
+        if (Object.hasOwn(verification, op))
+            return facade[verification[op]].call(facade, params.value, this.semanticContext(jsonObjectOf(params.context) ?? {}, false, op === 'verify_original' ? params.value : undefined));
+        if (op === 'verify_status') {
+            const context = this.semanticContext(jsonObjectOf(params.context) ?? {});
+            return facade.verifyStatus(params.value, { ...context, policy: context.statePolicy });
+        }
+        if (op === 'verify_usage_record')
+            return facade.verifyUsageRecord(params.domain, params.value, this.semanticContext(jsonObjectOf(params.context) ?? {}));
+        const input = (jsonObjectOf(params.params) ?? {});
+        if (op === 'archive_received_message') {
+            const item = [...this.inbox, ...this.groupInbox].find(value => value.message_id === input.message_id && value.decrypted === true && jsonObjectOf(value._semantic_evidence));
+            const evidence = jsonObjectOf(item?._semantic_evidence);
+            if (!evidence)
+                throw new SemanticProtocolError('SEMANTIC_STATE_UNAVAILABLE', 'original decrypted message evidence is unavailable');
+            const receiver = this.client.aid;
+            if (!receiver || evidence.received_by !== receiver || receiver !== this.aid)
+                throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original message receiver differs from current identity');
+            const envelope = new Uint8Array(semanticBase64(evidence.envelope_bytes_base64));
+            semanticBase64(evidence.payload_bytes_base64);
+            return { archive: await facade.archiveMessage(envelope, { received_by: receiver, received_at: evidence.received_at, source: textOf(evidence.source) }),
+                envelope_bytes_base64: evidence.envelope_bytes_base64, payload_bytes_base64: evidence.payload_bytes_base64 };
+        }
+        if (op === 'verify_request') {
+            const request = input.request ?? input, actual = jsonObjectOf(input.context) ?? jsonObjectOf(params.context) ?? {}, context = this.semanticContext(actual);
+            const packageReport = await facade.verifyPackage(request.grant, context);
+            const requestReport = await facade.verifyRequest(request, actual.authenticated, { now: context.now });
+            return { ...packageReport, ...requestReport, request_bound: true, checked: [...new Set([...packageReport.checked, ...requestReport.checked])] };
+        }
+        if (op === 'build_decision_input')
+            return facade.buildDecisionInput(input.request, input.bodies, input.facts, input.policy);
+        if (op === 'create_evidence_ref')
+            return facade.createEvidenceRef(new Uint8Array(Buffer.from(textOf(input.bytes_base64), 'base64')), textOf(input.profile), input.locator);
+        if (op === 'resolve_evidence')
+            return { bytes_base64: Buffer.from(await facade.resolveEvidence(input.evidence ?? input, this.trustedArchiveResolvers())).toString('base64') };
+        if (op === 'archive_message')
+            return facade.archiveMessage(new Uint8Array(Buffer.from(textOf(input.bytes_base64), 'base64')), { received_by: this.aid, received_at: input.received_at, source: input.source });
+        if (op === 'verify_message_body') {
+            const context = jsonObjectOf(input.context) ?? jsonObjectOf(params.context) ?? {};
+            return facade.verifyMessageBody(input.credential ?? input, { ...this.semanticContext(context, false, input.credential ?? input), ...this.semanticReaderMessageContext(), ...this.semanticHistoricalSenderContext(context), resolvers: this.trustedArchiveResolvers() });
+        }
+        throw new SemanticProtocolError('SEMANTIC_FORMAT_INVALID', `unsupported semantic protocol operation: ${op}`);
+    }
     async groupCall(req, res) {
         const body = await readJson(req);
         const traceId = textOf(body.trace_id || crypto.randomUUID().replace(/-/g, ''));
@@ -1888,6 +2254,9 @@ export class CrossSdkTsAgent {
                 case 'sdk.org.protocol':
                     result = await this.orgProtocol(params);
                     break;
+                case 'sdk.semantic.protocol':
+                    result = await this.semanticProtocol(params);
+                    break;
                 case 'credential.register':
                     result = await this.client.credential.register(params);
                     break;
@@ -1900,9 +2269,16 @@ export class CrossSdkTsAgent {
                 case 'credential.revocationList':
                     result = await this.client.credential.revocationList(params);
                     break;
-                case 'org.lifecycle.create':
-                    result = await this.client.org.lifecycle.create(params);
+                case 'org.lifecycle.create': {
+                    const store = this.aidStore();
+                    try {
+                        result = await this.client.org.lifecycle.create({ ...params, aidStore: store });
+                    }
+                    finally {
+                        store.close();
+                    }
                     break;
+                }
                 case 'org.lifecycle.dissolve':
                     result = await this.client.org.lifecycle.dissolve(params);
                     break;
@@ -1992,9 +2368,14 @@ export class CrossSdkTsAgent {
                 error_code: err instanceof Error ? err.name : 'Error',
                 error_message: err instanceof Error ? err.message : String(err),
             };
-            if (method.startsWith('org.') || method === 'sdk.org.protocol') {
+            if (method.startsWith('org.') || method.startsWith('credential.semantic.') || method === 'sdk.org.protocol' || method === 'sdk.semantic.protocol') {
                 const remote = err;
                 error.rpc_error_code = remote?.stringCode || remote?.data?.error_code || remote?.data?.code || (typeof remote?.code === 'string' ? remote.code : '');
+                if (method.startsWith('credential.semantic.') || method === 'sdk.semantic.protocol') {
+                    error.rpc_numeric_code = typeof remote?.code === 'number' ? remote.code : null;
+                    error.error_data = jsonSafe(remote?.data);
+                    error.retryable = remote?.retryable === true || remote?.data?.retryable === true;
+                }
             }
             this.recordTrace(traceId, { stage: 'group_call_error', method, error });
             sendJson(res, 500, error);