@agentunion/fastaun 0.5.18 → 0.5.20

package/dist/aid-store.js

@@ -4,12 +4,14 @@
  */
 import * as http from 'node:http';
 import * as https from 'node:https';
-import { X509Certificate, createPrivateKey, createPublicKey } from 'node:crypto';
+import { X509Certificate, createPrivateKey, createPublicKey, randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { AID } from './aid.js';
 import * as codes from './error-codes.js';
-import { certCommonName, certMatchesFingerprint, certTimeError, signBytes, verifySignatureWithCert } from './cert-utils.js';
+import { certCommonName, certMatchesFingerprint, certTimeError, parseAgentMdTailSignature, publicKeyMatchesFingerprint, signBytes, signDocument, verifyDocument, verifySignatureWithCert } from './cert-utils.js';
+import { certFingerprint as _certFingerprint } from './cert-utils.js';
 import { resultErr, resultOk } from './result.js';
 import { LocalIdentityStore } from './keystore/local-identity-store.js';
 import { CryptoProvider } from './crypto.js';
@@ -18,17 +20,21 @@ import { GatewayDiscovery } from './discovery.js';
 import { DnsResilientNet } from './net.js';
 import { AUNLogger } from './logger.js';
 import { getDeviceId, normalizeSlotId } from './config.js';
-import { ClientSignatureError, IdentityConflictError, NotFoundError, ValidationError } from './errors.js';
+import { AUNError, ClientSignatureError, IdentityConflictError, NotFoundError, ValidationError } from './errors.js';
 import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
+import { parseFileFrontmatter, validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-schema.js';
 import { LocalTokenStore } from './keystore/local-token-store.js';
 import { AuthFlow } from './auth.js';
-import { OwnershipStatement, signOwnershipStatement } from './ownership-proof.js';
+import { OWNERSHIP_UUID_V4_RE, ownershipFailure, signOwnershipFile } from './ownership-v21.js';
+import { validateAIDFormat } from './validators.js';
 function resultError(r) {
     if (r.ok)
         return null;
     return r.error;
 }
 function agentMdFailure(exc) {
+    if (exc instanceof AUNError && exc.stringCode)
+        return resultErr(exc.stringCode, exc.message, exc);
     if (exc instanceof ClientSignatureError) {
         return resultErr(codes.SIGNATURE_INVALID, exc.message, exc);
     }
@@ -40,19 +46,6 @@ function agentMdFailure(exc) {
     }
     return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
 }
-function ownerAgentMd(content, ownerAid, proof) {
-    const marker = content.indexOf('<!-- AUN-SIGNATURE');
-    const payload = marker >= 0 ? content.slice(0, marker) : content;
-    const lines = payload.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
-    const end = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
-    if (end < 0)
-        throw new ValidationError('agent.md frontmatter is required for ownership operation');
-    const filtered = lines.filter((line, index) => !(index > 0 && index < end && (/^\s*owner\s*:/.test(line) || /^\s*ownership_proof\s*:/.test(line))));
-    const closed = filtered.findIndex((line, index) => index > 0 && line.trim() === '---');
-    filtered.splice(closed, 0, `owner: ${JSON.stringify(ownerAid)}`, `ownership_proof: ${JSON.stringify(proof)}`);
-    const result = filtered.join('\n');
-    return result.endsWith('\n') ? result : `${result}\n`;
-}
 /** 发起 HTTP HEAD 请求，返回 [status, headers] */
 function httpHead(url, verifySsl, timeoutMs = 5000) {
     return new Promise((resolve, reject) => {
@@ -104,6 +97,114 @@ export class AIDStore {
     _gatewayCache = new Map();
     _agentMdManager;
     _peerAuth;
+    async sign(aid, input, options = {}) {
+        try {
+            if (!['text', 'file'].includes(options.inputType ?? 'text') || !['raw', 'document'].includes(options.format ?? 'raw'))
+                throw new Error('invalid signature inputType or format');
+            if (options.append && options.format !== 'document')
+                throw new Error('append requires document format');
+            if (options.inPlace && (options.inputType !== 'file' || options.format !== 'document'))
+                throw new Error('inPlace requires file input and document format');
+            const raw = options.inputType === 'file' ? readFileSync(input) : input;
+            if (typeof raw === 'string' && options.format !== 'document' && new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(new TextEncoder().encode(raw)) !== raw)
+                throw new Error('signature text must be valid UTF-8');
+            const loaded = options.identity ? resultOk({ aid: options.identity }) : this.load(aid);
+            if (!loaded.ok)
+                return loaded;
+            const identity = loaded.data.aid;
+            if (identity.aid !== aid || identity.certSubject.toLowerCase() !== aid.toLowerCase() || !identity.isPrivateKeyValid() || !identity.isCertValid())
+                return resultErr(codes.PRIVATE_KEY_NOT_VALID, 'sign requires a valid local signing identity');
+            if (options.format !== 'document')
+                return identity.sign(raw);
+            const content = typeof raw === 'string' ? raw : new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+            const signed = signDocument(identity, content, { append: options.append, tag: options.tag, timestamp: options.timestamp, signerAid: options.signerAid });
+            if (options.inPlace)
+                writeFileSync(input, signed.signed, 'utf8');
+            return resultOk(signed);
+        }
+        catch (error) {
+            return resultErr(codes.SIGNATURE_OPERATION_ERROR, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    async verify(aid, input, signatureOrOptions, options = {}) {
+        const signature = typeof signatureOrOptions === 'string' ? signatureOrOptions : undefined;
+        if (signatureOrOptions && typeof signatureOrOptions === 'object')
+            options = signatureOrOptions;
+        try {
+            if (!['text', 'file'].includes(options.inputType ?? 'text') || !['raw', 'document'].includes(options.format ?? 'raw'))
+                throw new Error('invalid signature inputType or format');
+            if (options.inPlace)
+                throw new Error('verify does not modify files');
+            if (options.identity && (options.identity.aid !== aid || options.identity.certSubject.toLowerCase() !== aid.toLowerCase()))
+                throw new Error('verification identity does not match AID');
+            const raw = options.inputType === 'file' ? readFileSync(input) : input;
+            if (typeof raw === 'string' && options.format !== 'document' && new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(new TextEncoder().encode(raw)) !== raw)
+                throw new Error('signature text must be valid UTF-8');
+            if (options.format === 'document') {
+                const text = typeof raw === 'string' ? raw : new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+                const parsed = parseAgentMdTailSignature(text, options.readCompatibility);
+                if (parsed.parseError || !parsed.fields)
+                    return resultOk(verifyDocument(text, { expectedAid: aid, readCompatibility: options.readCompatibility }));
+            }
+            let loaded = options.identity ? resultOk({ aid: options.identity }) : this.load(aid);
+            if (!loaded.ok && options.format === 'document' && options.certificateResolver) {
+                const text = typeof raw === 'string' ? raw : new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+                const primary = parseAgentMdTailSignature(text, options.readCompatibility).fields;
+                if (primary) {
+                    const certificate = await options.certificateResolver(aid, primary.cert_fingerprint, Number(primary.timestamp));
+                    loaded = resultOk({ aid: typeof certificate === 'string' ? AID._create({ aid, aunPath: this.aunPath, certPem: certificate, certValid: true, privateKeyPem: null, privateKeyValid: false }) : certificate });
+                }
+            }
+            if (!loaded.ok)
+                return loaded;
+            const identity = loaded.data.aid;
+            if (identity.aid !== aid || identity.certSubject.toLowerCase() !== aid.toLowerCase())
+                throw new Error('verification identity does not match AID');
+            if (options.format !== 'document')
+                return identity.verify(raw, signature ?? '');
+            const content = typeof raw === 'string' ? raw : new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+            const certificates = await this._documentCertificates(content, options, identity);
+            const primary = parseAgentMdTailSignature(content, options.readCompatibility).fields;
+            const primaryCertPem = primary ? certificates.get(`${aid};${primary.cert_fingerprint}`) ?? identity.certPem : identity.certPem;
+            return resultOk(verifyDocument(content, { expectedAid: aid, primaryCertPem, readCompatibility: options.readCompatibility, requireCurrentValidity: options.requireCurrentValidity, certificateResolver: (signer, fingerprint) => certificates.get(`${signer};${fingerprint}`) }));
+        }
+        catch (error) {
+            return resultErr(codes.VERIFICATION_OPERATION_ERROR, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    async _documentCertificates(content, options, primary) {
+        const certificates = new Map();
+        let inferredAid = primary?.aid;
+        if (!inferredAid) {
+            try {
+                const meta = parseFileFrontmatter(parseAgentMdTailSignature(content).payload);
+                inferredAid = String(meta.aid ?? meta.owner_aid ?? '') || undefined;
+            }
+            catch { }
+        }
+        for (const item of parseAgentMdTailSignature(content, options.readCompatibility).signatures) {
+            const fields = item.fields, signer = fields.signer_aid ?? inferredAid;
+            if (!signer)
+                continue;
+            let cert;
+            if (options.certificateResolver)
+                cert = await options.certificateResolver(signer, fields.cert_fingerprint, Number(fields.timestamp));
+            else if (primary?.aid === signer && certMatchesFingerprint(primary.certPem, fields.cert_fingerprint))
+                cert = primary;
+            else {
+                const loaded = this.load(signer);
+                if (loaded.ok && certMatchesFingerprint(loaded.data.aid.certPem, fields.cert_fingerprint))
+                    cert = loaded.data.aid;
+                else
+                    throw new Error('signing certificate is unavailable locally; an explicit certificateResolver is required');
+            }
+            if (cert && typeof cert !== 'string' && cert.aid !== signer)
+                throw new Error('resolved certificate identity does not match signer AID');
+            if (cert)
+                certificates.set(`${signer};${fields.cert_fingerprint}`, typeof cert === 'string' ? cert : cert.certPem);
+        }
+        return certificates;
+    }
     constructor(opts) {
         this.aunPath = String(opts.aunPath ?? join(homedir(), '.aun'));
         this._encryptionSeed = String(opts.encryptionSeed ?? '');
@@ -148,28 +249,15 @@ export class AIDStore {
             logger: this._log.for('aun_core.agent_md'),
             aidValidator: (target) => this._registerFlow.validateAidName(target),
             gatewayResolver: (target) => this._resolveGateway(target),
-            peerResolver: async (target, certFingerprint) => {
-                const fp = String(certFingerprint ?? '').trim().toLowerCase();
-                const cachedCert = this._keystore.loadCert(target, fp || undefined);
-                if (cachedCert) {
-                    return AID._create({ aid: target, aunPath: this.aunPath, certPem: cachedCert, privateKeyPem: null, certValid: true, privateKeyValid: false, deviceId: this.deviceId, slotId: this.slotId, verifySsl: this._verifySsl, rootCaPath: this._rootCaPath, debug: this._debug });
-                }
-                if (fp) {
-                    const gatewayUrl = await this._resolveGateway(target);
-                    const certPem = await this._net.httpGetText(pkiCertUrl(gatewayUrl, target, fp), 10_000);
-                    await this._verifyDownloadedPeerCertificate(gatewayUrl, target, certPem, fp);
-                    this._keystore.saveCert(target, certPem, fp, { makeActive: false });
-                    return AID._create({ aid: target, aunPath: this.aunPath, certPem, privateKeyPem: null, certValid: true, privateKeyValid: false });
-                }
-                const gatewayUrl = await this._resolveGateway(target);
-                const certPem = await this._registerFlow.fetchPeerCert(gatewayUrl, target);
-                if (!certPem) {
-                    throw new Error(`certificate not found for aid: ${target}`);
-                }
-                await this._verifyDownloadedPeerCertificate(gatewayUrl, target, certPem);
-                this._keystore.saveCert(target, certPem);
-                return AID._create({ aid: target, aunPath: this.aunPath, certPem, privateKeyPem: null, certValid: true, privateKeyValid: false });
+            entitySignerResolver: async (target, fingerprint) => {
+                const material = await this._peerAuth.resolveOwnershipCertificate(await this._resolveGateway(target), target, fingerprint, 'signing');
+                return AID._create({ aid: target, aunPath: this.aunPath, certPem: material.cert_pem, privateKeyPem: null, certValid: true, privateKeyValid: false });
+            },
+            entityIdentityGetter: async (target, type) => {
+                const material = await this._peerAuth.resolveCurrentEntityCertificate(await this._resolveGateway(target), target, type ?? 'org');
+                return AID._create({ aid: target, aunPath: this.aunPath, certPem: material.cert_pem, privateKeyPem: null, certValid: true, privateKeyValid: false });
             },
+            peerResolver: (target, certFingerprint, signedAt) => this._resolveAgentMdPeerCertificate(target, certFingerprint, signedAt),
         });
     }
     close() {
@@ -179,6 +267,29 @@ export class AIDStore {
         if (typeof net.close === 'function')
             net.close();
     }
+    async _resolveAgentMdPeerCertificate(target, certFingerprint, signedAt) {
+        const fp = String(certFingerprint ?? '').trim().toLowerCase();
+        const cachedCert = this._keystore.loadCert(target, fp || undefined);
+        if (cachedCert && (!fp || certMatchesFingerprint(cachedCert, fp) || publicKeyMatchesFingerprint(cachedCert, fp))) {
+            if (signedAt !== undefined)
+                await this._verifyDownloadedPeerCertificate(await this._resolveGateway(target), target, cachedCert, fp, signedAt);
+            return AID._create({ aid: target, aunPath: this.aunPath, certPem: cachedCert, privateKeyPem: null, certValid: true, privateKeyValid: false, deviceId: this.deviceId, slotId: this.slotId, verifySsl: this._verifySsl, rootCaPath: this._rootCaPath, debug: this._debug });
+        }
+        if (fp) {
+            const gatewayUrl = await this._resolveGateway(target);
+            const certPem = await this._net.httpGetText(pkiCertUrl(gatewayUrl, target, fp), 10_000);
+            await this._verifyDownloadedPeerCertificate(gatewayUrl, target, certPem, fp, signedAt);
+            this._keystore.saveCert(target, certPem, _certFingerprint(certPem), { makeActive: false });
+            return AID._create({ aid: target, aunPath: this.aunPath, certPem, privateKeyPem: null, certValid: true, privateKeyValid: false });
+        }
+        const gatewayUrl = await this._resolveGateway(target);
+        const certPem = await this._registerFlow.fetchPeerCert(gatewayUrl, target);
+        if (!certPem)
+            throw new Error(`certificate not found for aid: ${target}`);
+        await this._verifyDownloadedPeerCertificate(gatewayUrl, target, certPem, undefined, signedAt);
+        this._keystore.saveCert(target, certPem);
+        return AID._create({ aid: target, aunPath: this.aunPath, certPem, privateKeyPem: null, certValid: true, privateKeyValid: false });
+    }
     // ── 离线方法 ──────────────────────────────────────────────────
     load(aid) {
         const target = String(aid ?? '').trim();
@@ -193,6 +304,9 @@ export class AIDStore {
         catch (exc) {
             return resultErr(codes.CERT_PARSE_ERROR, `certificate parse failed for aid: ${target}`, exc);
         }
+        if (this._tokenStore.loadMetadata?.(target)?.invalidated_entity_certificate === _certFingerprint(certPem)) {
+            return resultErr(codes.CERT_NOT_VALID, `group/org identity has been invalidated: ${target}`);
+        }
         const timeErr = certTimeError(certPem);
         if (timeErr === 'expired')
             return resultErr(codes.CERT_EXPIRED, `certificate expired for aid: ${target}`);
@@ -295,11 +409,28 @@ export class AIDStore {
         return Promise.resolve(this.changeSeed(oldSeed, newSeed));
     }
     // ── 联网方法 ──────────────────────────────────────────────────
-    async registerIdentity(aid, uploadDefault = true) {
+    async register(aid, options) {
         const target = String(aid ?? '').trim();
         this._log.for('aun_core.aid_store').debug(`register enter: aid=${target || '-'}`);
         try {
             this._registerFlow.validateAidName(target);
+            const type = String(options?.type ?? '').trim(), owner = String(options?.owner ?? '').trim().toLowerCase();
+            const entity = ['group', 'org'].includes(type);
+            if (entity && !owner)
+                throw new ValidationError('group/org registration requires owner');
+            if (!type || type === 'human' && owner)
+                throw new ValidationError('register requires type; human forbids owner');
+            if (owner)
+                validateAIDFormat(owner, 'owner');
+            const previous = this._tokenStore.loadMetadata(target)?.registration_intent;
+            const exttype = String(options?.exttype ?? '').trim();
+            if (previous && (entity ? previous.protocol !== 'entity' || previous.pending !== false : previous.protocol !== '2.1' || !OWNERSHIP_UUID_V4_RE.test(String(previous.operation_id)) || typeof previous.pending !== 'boolean'))
+                throw ownershipFailure('persistence_unavailable', 'registration ownership intent is corrupt');
+            if (previous && (previous.type !== type || previous.owner !== owner || previous.exttype !== exttype))
+                throw new IdentityConflictError('registration ownership intent already exists with a different context');
+            const intent = previous ?? (entity ? { protocol: 'entity', type, owner, exttype, pending: false } : { protocol: '2.1', type, owner, exttype, operation_id: randomUUID(), pending: Boolean(owner) });
+            if (type !== 'agent' || owner)
+                this._tokenStore.saveMetadata(target, { registration_intent: intent });
             const gatewayUrl = await this._resolveGateway(target);
             const result = await this._registerFlow.registerAid(gatewayUrl, target);
             if (result.cert) {
@@ -310,8 +441,8 @@ export class AIDStore {
                 public_key_der_b64: result.public_key_der_b64,
                 curve: result.curve,
             });
-            if (uploadDefault)
-                await this.uploadAgentMd(target, buildDefaultAgentMd(target));
+            if (!entity)
+                await this._createInitialRegistrationAgentMd(target, type, exttype);
             return resultOk({ registered: true });
         }
         catch (exc) {
@@ -328,219 +459,32 @@ export class AIDStore {
             return resultErr(codes.SERVER_ERROR, msg, exc);
         }
     }
-    async register(aidOrParams) {
-        if (typeof aidOrParams === 'string')
-            return await this.registerIdentity(aidOrParams);
-        const params = aidOrParams;
-        const target = String(params?.aid ?? '').trim();
-        const aidType = String(params?.type ?? '').trim().toLowerCase();
-        const owner = String(params?.owner ?? params?.owner_aid ?? '').trim();
-        if (!target || !aidType)
-            return resultErr(codes.INVALID_AID_FORMAT, 'register requires aid and type');
-        try {
-            const identity = await this.registerIdentity(target, false);
-            if (!identity.ok)
-                return identity;
-            const gatewayUrl = await this._resolveGateway(target);
-            const prepareParams = { aid: target, type: aidType };
-            if (owner)
-                prepareParams.owner = owner;
-            const idempotencyKey = params.idempotencyKey ?? params.idempotency_key;
-            if (idempotencyKey)
-                prepareParams.idempotency_key = idempotencyKey;
-            const prepared = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_register_prepare', prepareParams);
-            const operationId = String(prepared.operation_id ?? '').trim();
-            if (!operationId)
-                throw new ValidationError('aid_register_prepare response missing operation_id');
-            let subjectSignature = params.subjectSignature ?? params.subject_signature;
-            const ownerSignature = params.ownerSignature ?? params.owner_signature;
-            if (!subjectSignature && owner) {
-                const loaded = this.load(target);
-                if (loaded.ok) {
-                    const statement = OwnershipStatement.create(String(prepared.proof_id ?? ''), target, owner);
-                    const signed = signOwnershipStatement({ certFingerprint: loaded.data.aid.certFingerprint, sign: (payload) => loaded.data.aid.sign(Buffer.from(payload)) }, statement);
-                    subjectSignature = { cert_fingerprint: signed.cert_fingerprint, signature: signed.signature };
-                }
-            }
-            const signatures = {};
-            if (subjectSignature)
-                signatures.subject_signature = subjectSignature;
-            if (ownerSignature)
-                signatures.owner_signature = ownerSignature;
-            let response = prepared;
-            if (Object.keys(signatures).length > 0)
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_register_submit', { operation_id: operationId, ...signatures });
-            const state = String(response.state ?? response.operation_state ?? '').toLowerCase();
-            const complete = !owner || owner === target || (!!ownerSignature && !!subjectSignature);
-            if (complete && state === 'agent_md_pending') {
-                let content = params.agentMd ?? params.agent_md ?? buildDefaultAgentMd(target, { type: aidType });
-                if (owner) {
-                    const proof = { proof_id: prepared.proof_id, subject_aid: target, owner_aid: owner, fact_hash: prepared.fact_hash, statement_hash: prepared.statement_hash, subject_signature: subjectSignature };
-                    if (owner !== target)
-                        proof.owner_signature = ownerSignature;
-                    content = ownerAgentMd(content, owner, proof);
-                }
-                const uploaded = await this.uploadAgentMd(target, content, { ownerOperationId: operationId });
-                if (!uploaded.ok)
-                    return uploaded;
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_register_activate', { operation_id: operationId });
-            }
-            return resultOk(response);
-        }
-        catch (exc) {
-            if (exc instanceof ValidationError)
-                return resultErr(codes.INVALID_AID_FORMAT, exc.message, exc);
-            return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
-        }
-    }
-    async create(params) { return await this.register(params); }
-    async bindAid(params) {
-        const target = String(params?.aid ?? '').trim();
-        const aidType = String(params?.type ?? '').trim().toLowerCase();
-        const owner = String(params?.owner ?? params?.owner_aid ?? '').trim();
-        if (!target || !aidType)
-            return resultErr(codes.INVALID_AID_FORMAT, 'bindAid requires aid and type');
+    async _createInitialRegistrationAgentMd(target, type, exttype) {
         try {
-            this._registerFlow.validateAidName(target);
-            const gatewayUrl = await this._resolveGateway(target);
-            const prepareParams = { aid: target, type: aidType };
-            if (owner)
-                prepareParams.owner = owner;
-            const idempotencyKey = params.idempotencyKey ?? params.idempotency_key;
-            if (idempotencyKey)
-                prepareParams.idempotency_key = idempotencyKey;
-            const prepared = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_bind_prepare', prepareParams);
-            const operationId = String(prepared.operation_id ?? '').trim();
-            if (!operationId)
-                throw new ValidationError('aid_bind_prepare response missing operation_id');
-            const signatures = {};
-            let subjectSignature = params.subjectSignature ?? params.subject_signature;
-            if (!subjectSignature && owner) {
-                const loaded = this.load(target);
-                if (loaded.ok) {
-                    const statement = OwnershipStatement.create(String(prepared.proof_id ?? ''), target, owner);
-                    const signed = signOwnershipStatement({
-                        certFingerprint: loaded.data.aid.certFingerprint,
-                        sign: (payload) => loaded.data.aid.sign(Buffer.from(payload)),
-                    }, statement);
-                    subjectSignature = { cert_fingerprint: signed.cert_fingerprint, signature: signed.signature };
-                }
-            }
-            if (subjectSignature)
-                signatures.subject_signature = subjectSignature;
-            const ownerSignature = params.ownerSignature ?? params.owner_signature;
-            if (ownerSignature)
-                signatures.owner_signature = ownerSignature;
-            let response = prepared;
-            if (Object.keys(signatures).length > 0) {
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_bind_submit', { operation_id: operationId, ...signatures });
-            }
-            const agentMd = params.agentMd ?? params.agent_md;
-            if (agentMd !== undefined) {
-                const uploaded = await this.uploadAgentMd(target, agentMd, {
-                    ownerOperationId: operationId,
-                });
-                if (!uploaded.ok)
-                    return uploaded;
-            }
-            const state = String(response.state ?? response.operation_state ?? '').toLowerCase();
-            if (state === 'agent_md_pending' || (!Object.keys(signatures).length && !owner && String(prepared.state ?? '') === 'agent_md_pending')) {
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_bind_activate', { operation_id: operationId });
-            }
-            return resultOk(response);
-        }
-        catch (exc) {
-            if (exc instanceof ValidationError)
-                return resultErr(codes.INVALID_AID_FORMAT, exc.message, exc);
-            return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
-        }
-    }
-    async getAidBindingStatus(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            return resultErr(codes.INVALID_AID_FORMAT, 'getAidBindingStatus requires aid');
-        try {
-            this._registerFlow.validateAidName(target);
-            const gatewayUrl = await this._resolveGateway(target);
-            return resultOk(await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_bind_status', { aid: target }));
-        }
-        catch (exc) {
-            return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
-        }
-    }
-    async resumeAidBinding(operationId) {
-        const target = String(operationId ?? '').trim();
-        if (!target)
-            return resultErr(codes.INVALID_AID_FORMAT, 'resumeAidBinding requires operationId');
-        try {
-            const gatewayUrl = await this._resolveGateway(target);
-            let response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_operation_get', { operation_id: target });
-            if (String(response.state ?? response.operation_state ?? '').toLowerCase() === 'agent_md_pending') {
-                const method = String(response.kind ?? '').toLowerCase() === 'owner_change' ? 'auth.owner_change_activate' : 'auth.aid_bind_activate';
-                response = await this._registerFlow.shortRpc(gatewayUrl, method, { operation_id: target });
-            }
-            return resultOk(response);
-        }
-        catch (exc) {
-            return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
-        }
-    }
-    async bind_aid(params) { return this.bindAid(params); }
-    async get_aid_binding_status(aid) { return this.getAidBindingStatus(aid); }
-    async resume_aid_binding(operationId) { return this.resumeAidBinding(operationId); }
-    async changeOwner(params) {
-        const subject = String(params?.subject_aid ?? params?.aid ?? '').trim();
-        const newOwner = String(params?.new_owner_aid ?? params?.new_owner ?? '').trim();
-        if (!subject || !newOwner)
-            return resultErr(codes.INVALID_AID_FORMAT, 'changeOwner requires subject_aid and new_owner_aid');
-        try {
-            this._registerFlow.validateAidName(subject);
-            const gatewayUrl = await this._resolveGateway(subject);
-            const prepare = { subject_aid: subject, new_owner_aid: newOwner };
-            if (params.current_owner_aid ?? params.owner_aid)
-                prepare.current_owner_aid = params.current_owner_aid ?? params.owner_aid;
-            if (params.expected_relation_version !== undefined)
-                prepare.expected_relation_version = params.expected_relation_version;
-            if (params.idempotencyKey ?? params.idempotency_key)
-                prepare.idempotency_key = params.idempotencyKey ?? params.idempotency_key;
-            const prepared = await this._registerFlow.shortRpc(gatewayUrl, 'auth.owner_change_prepare', prepare);
-            const operationId = String(prepared.operation_id ?? '').trim();
-            if (!operationId)
-                throw new ValidationError('owner_change_prepare response missing operation_id');
-            const signatures = {};
-            for (const key of ['old_owner_signature', 'subject_signature', 'new_owner_signature'])
-                if (params[key])
-                    signatures[key] = params[key];
-            let response = prepared;
-            if (Object.keys(signatures).length > 0)
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.owner_change_submit', { operation_id: operationId, ...signatures });
-            if (String(response.state ?? response.operation_state ?? '').toLowerCase() === 'agent_md_pending' && (params.agentMd ?? params.agent_md) !== undefined) {
-                const proof = { proof_id: prepared.proof_id, subject_aid: subject, owner_aid: newOwner, fact_hash: prepared.fact_hash, statement_hash: prepared.statement_hash, subject_signature: params.subject_signature, owner_signature: params.new_owner_signature };
-                const content = ownerAgentMd(String(params.agentMd ?? params.agent_md), newOwner, proof);
-                const uploaded = await this.uploadAgentMd(subject, content, { ownerOperationId: operationId });
-                if (!uploaded.ok)
-                    return uploaded;
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.owner_change_activate', { operation_id: operationId });
-            }
-            return resultOk(response);
-        }
-        catch (exc) {
-            return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
-        }
-    }
-    async resumeOwnerChange(operationId, aid) {
-        const id = String(operationId ?? '').trim();
-        if (!id)
-            return resultErr(codes.INVALID_AID_FORMAT, 'resumeOwnerChange requires operationId');
-        try {
-            const gatewayUrl = await this._resolveGateway(String(aid ?? id));
-            let response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_operation_get', { operation_id: id });
-            if (String(response.state ?? response.operation_state ?? '').toLowerCase() === 'agent_md_pending')
-                response = await this._registerFlow.shortRpc(gatewayUrl, 'auth.owner_change_activate', { operation_id: id });
-            return resultOk(response);
+            const loaded = this.load(target);
+            if (!loaded.ok)
+                return loaded;
+            const current = loaded.data.aid;
+            const manager = new AgentMdManager({
+                aunPath: this.aunPath, verifySsl: this._verifySsl, logger: this._log.for('aun_core.agent_md'), uploadViaGatewayHost: true,
+                ownerAidGetter: () => target, currentAidGetter: () => current,
+                gatewayResolver: (value) => this._resolveGateway(value),
+                accessTokenResolver: async () => this._uploadAgentMdToken(current, await this._resolveGateway(target)),
+                aidValidator: (value) => this._registerFlow.validateAidName(value),
+            });
+            const fresh = await manager.readOwnershipFresh(target), now = Math.trunc(Date.now() / 1000);
+            if (fresh.protocol !== '2.1' || fresh.sub_aid !== target || !Number.isSafeInteger(fresh.relation_version) || fresh.relation_version < 0 || !['locked', 'unlocked'].includes(fresh.lock) || !Number.isSafeInteger(fresh.observed_at) || fresh.observed_at < now - 30 || fresh.observed_at > now + 5)
+                throw ownershipFailure('unavailable', 'initial NS authority is unavailable', true);
+            if (fresh.exists)
+                return resultOk({ initialized: false });
+            if (fresh.relation_version !== 0 || fresh.lock !== 'unlocked')
+                throw ownershipFailure('conflict', 'initial NS relation is not unbound');
+            const raw = signOwnershipFile(current, buildDefaultAgentMd(target, { type, exttype }), 'agent', { now });
+            await manager.submitOwnershipRaw(target, raw, { if_none_match: '*' });
+            return resultOk({ initialized: true });
         }
-        catch (exc) {
-            return resultErr(codes.NETWORK_ERROR, exc instanceof Error ? exc.message : String(exc), exc);
+        catch (error) {
+            return agentMdFailure(error);
         }
     }
     async exists(aid) {
@@ -569,6 +513,19 @@ export class AIDStore {
             let peer;
             let certFromCache = false;
             const loaded = this.load(target);
+            const local = !forceRefresh && !skipAgentMd && ((loaded.ok && loaded.data?.aid.isPrivateKeyValid()) || this._keystore.loadKeyPair(target)?.private_key_pem) ? (this._agentMdManager._loadRecord?.(target, true) ?? this._agentMdManager.loadRecord(target)) : null;
+            const draft = String(local?.local_draft_content ?? '');
+            const content = draft || String(local?.content ?? '');
+            if (content) {
+                peer = loaded.ok && loaded.data ? loaded.data.aid : AID._create({ aid: target, aunPath: this.aunPath, certPem: this._keystore.loadCert(target) ?? '', privateKeyPem: null, certValid: false, privateKeyValid: false, deviceId: this.deviceId, slotId: this.slotId, verifySsl: this._verifySsl, rootCaPath: this._rootCaPath, debug: this._debug, aidStore: this });
+                const localEtag = AgentMdManager.contentEtag(content), remoteEtag = String(local?.remote_etag ?? '');
+                return resultOk({ aid: peer, source: { cert_from_cache: true, agent_md_fetched: false }, agent_md: {
+                        aid: target, content, verification: { status: 'unverified' }, signature: {}, cert_pem: '',
+                        etag: localEtag, last_modified: String(local?.last_modified ?? ''), status: 200,
+                        in_sync: !draft && !!remoteEtag && localEtag === remoteEtag,
+                        saved_to: draft ? this._agentMdManager.metaPath(target) : this._agentMdManager.filePath(target), save_error: null,
+                    } });
+            }
             if (loaded.ok && loaded.data && !forceRefresh) {
                 peer = loaded.data.aid;
                 certFromCache = true;
@@ -595,6 +552,8 @@ export class AIDStore {
             return resultOk({ aid: peer, agent_md: agentMd.data, source });
         }
         catch (exc) {
+            if (exc instanceof AUNError && exc.stringCode)
+                return resultErr(exc.stringCode, exc.message, exc);
             return resultErr(codes.NETWORK_ERROR, String(exc), exc);
         }
     }
@@ -614,12 +573,17 @@ export class AIDStore {
             return agentMdFailure(exc);
         }
     }
-    async _verifyDownloadedPeerCertificate(gatewayUrl, aid, certPem, certFingerprint = '') {
+    async _verifyDownloadedPeerCertificate(gatewayUrl, aid, certPem, certFingerprint = '', signedAt) {
         const expectedFp = String(certFingerprint ?? '').trim().toLowerCase();
-        if (expectedFp && !certMatchesFingerprint(certPem, expectedFp)) {
+        if (expectedFp && !certMatchesFingerprint(certPem, expectedFp) && !(signedAt !== undefined && publicKeyMatchesFingerprint(certPem, expectedFp))) {
             throw new ValidationError(`certificate fingerprint mismatch for aid: ${aid}`);
         }
-        await this._peerAuth.verifyPeerCertificate(gatewayUrl, certPem, aid);
+        if (signedAt === undefined)
+            await this._peerAuth.verifyPeerCertificate(gatewayUrl, certPem, aid);
+        else {
+            validateAgentMdCertificate(certPem, aid, signedAt, { requireCurrentValidity: false, readCompatibility: true });
+            await this._peerAuth._verifyAuthCertChain(gatewayUrl, new X509Certificate(certPem), aid, signedAt);
+        }
     }
     _authIdentityFromAid(aid) {
         return {
@@ -658,10 +622,11 @@ export class AIDStore {
                 return resultErr(err?.code ?? codes.CERT_NOT_FOUND, err?.message ?? `certificate not found for aid: ${target}`);
             }
             const current = loaded.data.aid;
-            if (!current.isPrivateKeyValid() || !current.privateKeyPem) {
-                return resultErr(codes.PRIVATE_KEY_NOT_VALID, `uploadAgentMd requires local AID with a valid private key: ${target}`);
-            }
-            const uploaderTarget = String(options.uploaderAid ?? options.uploader_aid ?? target).trim();
+            const raw = content ?? (String((this._agentMdManager._loadRecord?.(target, true) ?? this._agentMdManager.loadRecord(target))?.local_draft_content ?? '') || this._agentMdManager.readContent(target));
+            const parsed = validateAgentMdDocument(raw, { expectedAid: target, validateOwnership: false });
+            const meta = parsed.frontmatter;
+            const entity = ['group', 'org'].includes(String(meta.type));
+            const uploaderTarget = String(options.uploaderAid ?? options.uploader_aid ?? (entity ? meta.owner : target)).trim();
             this._registerFlow.validateAidName(uploaderTarget);
             let uploader = current;
             if (uploaderTarget.toLowerCase() !== target.toLowerCase()) {
@@ -675,19 +640,48 @@ export class AIDStore {
                     return resultErr(codes.PRIVATE_KEY_NOT_VALID, `uploadAgentMd requires uploader AID with a valid private key: ${uploaderTarget}`);
                 }
             }
+            if (!entity && (!current.isPrivateKeyValid() || !current.privateKeyPem)) {
+                return resultErr(codes.PRIVATE_KEY_NOT_VALID, `uploadAgentMd requires local AID with a valid private key: ${target}`);
+            }
             const manager = new AgentMdManager({
                 aunPath: this.aunPath,
                 verifySsl: this._verifySsl,
                 logger: this._log.for('aun_core.agent_md'),
                 uploadViaGatewayHost: true,
-                ownerAidGetter: () => target,
-                currentAidGetter: () => current,
+                ownerAidGetter: () => entity ? uploaderTarget : target,
+                currentAidGetter: () => entity ? uploader : current,
+                entityIdentityGetter: options.entityIdentityGetter ?? (async (value, type) => {
+                    const gateway = await this._resolveGateway(value);
+                    const material = await this._peerAuth.resolveCurrentEntityCertificate(gateway, value, type ?? 'org');
+                    const certPem = material.cert_pem;
+                    return AID._create({ aid: value, aunPath: this.aunPath, certPem, certValid: true, privateKeyPem: null, privateKeyValid: false });
+                }),
+                entitySignerResolver: async (value, fingerprint) => {
+                    const material = await this._peerAuth.resolveOwnershipCertificate(await this._resolveGateway(value), value, fingerprint, 'signing');
+                    return AID._create({ aid: value, aunPath: this.aunPath, certPem: material.cert_pem, certValid: true, privateKeyPem: null, privateKeyValid: false });
+                },
+                entityOwnerResolver: options.entityOwnerResolver,
+                peerResolver: (value, fingerprint, signedAt) => this._resolveAgentMdPeerCertificate(value, fingerprint, signedAt),
                 gatewayResolver: (value) => this._resolveGateway(value),
                 accessTokenResolver: async () => this._uploadAgentMdToken(uploader, await this._resolveGateway(uploaderTarget)),
                 aidValidator: (value) => this._registerFlow.validateAidName(value),
             });
-            const ownerOperationId = options.ownerOperationId ?? options.owner_operation_id;
-            return resultOk(await manager.upload(content, ownerOperationId));
+            let prepared = raw;
+            if (entity && !parsed.signature) {
+                const signed = await this.sign(target, raw, { format: 'document', identity: current, signerAid: target });
+                if (!signed.ok)
+                    return signed;
+                prepared = signed.data.signed;
+            }
+            if (entity && options.coSignerAid) {
+                if (options.coSignerAid !== uploaderTarget)
+                    throw new ValidationError('entity additional signer must be its uploading owner');
+                const signed = await this.sign(options.coSignerAid, prepared, { format: 'document', append: true, identity: uploader });
+                if (!signed.ok)
+                    return signed;
+                prepared = signed.data.signed;
+            }
+            return resultOk(entity ? await manager.uploadAs(target, prepared, current) : await manager.upload(raw));
         }
         catch (exc) {
             return agentMdFailure(exc);
@@ -782,8 +776,44 @@ export class AIDStore {
         try {
             this._registerFlow.validateAidName(target);
             const oldAid = loaded.data.aid;
-            const newIdentity = this._registerFlow.generateIdentity();
             const gatewayUrl = await this._resolveGateway(target);
+            const pendingStore = this._keystore;
+            let pendingDir = null;
+            let newIdentity = null;
+            for (const handle of pendingStore.listPendingIdentityDirs(target)) {
+                const candidate = pendingStore.loadPendingKeyPair(handle, target);
+                if (candidate?.rekey_pending === true) {
+                    pendingDir = handle;
+                    newIdentity = candidate;
+                    break;
+                }
+            }
+            if (newIdentity) {
+                const serverCert = await this._registerFlow.fetchPeerCert(gatewayUrl, target);
+                if (serverCert) {
+                    const cert = new X509Certificate(serverCert);
+                    const serverPublicKey = cert.publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+                    if (serverPublicKey === newIdentity.public_key_der_b64 && certCommonName(serverCert) === target && !certTimeError(serverCert)) {
+                        pendingStore.savePendingCert(pendingDir, serverCert);
+                        this._keystore.saveIdentity(target, {
+                            aid: target, private_key_pem: newIdentity.private_key_pem,
+                            public_key_der_b64: newIdentity.public_key_der_b64, curve: newIdentity.curve, cert: serverCert,
+                        });
+                        pendingStore.discardPendingIdentity(pendingDir);
+                        const refreshed = this.load(target);
+                        if (!refreshed.ok || !refreshed.data)
+                            return resultErr(codes.REKEY_FAILED, 'rekeyed identity reload failed');
+                        return resultOk({ rekeyed: true, new_cert_not_after: refreshed.data.aid.certNotAfter, new_fingerprint: refreshed.data.aid.certFingerprint });
+                    }
+                }
+            }
+            else {
+                newIdentity = this._registerFlow.generateIdentity();
+                pendingDir = pendingStore.pendingIdentityDir(target);
+                pendingStore.savePendingKeyPair(pendingDir, target, { ...newIdentity, aid: target, rekey_pending: true });
+            }
+            if (!pendingDir || !newIdentity)
+                return resultErr(codes.REKEY_FAILED, 'pending rekey identity is unavailable');
             const clientNonce = this._registerFlow.newClientNonce();
             const phase1 = await this._registerFlow.shortRpc(gatewayUrl, 'auth.aid_login1', {
                 aid: target, cert: oldAid.certPem, client_nonce: clientNonce,
@@ -801,7 +831,12 @@ export class AIDStore {
             const certPem = String(response.cert ?? response.cert_pem ?? '').trim();
             if (!certPem)
                 return resultErr(codes.REKEY_FAILED, 'server response missing certificate');
-            this._keystore.saveIdentity(target, { aid: target, ...newIdentity, cert: certPem });
+            pendingStore.savePendingCert(pendingDir, certPem);
+            this._keystore.saveIdentity(target, {
+                aid: target, private_key_pem: newIdentity.private_key_pem,
+                public_key_der_b64: newIdentity.public_key_der_b64, curve: newIdentity.curve, cert: certPem,
+            });
+            pendingStore.discardPendingIdentity(pendingDir);
             const refreshed = this.load(target);
             if (!refreshed.ok || !refreshed.data)
                 return resultErr(codes.REKEY_FAILED, 'rekeyed identity reload failed');