@agentunion/fastaun-browser 0.5.19 → 0.5.20

package/dist/agent-md.js

@@ -1,11 +1,11 @@
 import { AID } from './aid.js';
 import { parseDocument } from 'yaml';
-import { certMatchesFingerprint, parseAgentMdTailSignature } from './cert-utils.js';
-import { parseFileFrontmatter, validateAgentMdDocument, verifyAgentMdUpload } from './agent-md-schema.js';
+import { certMatchesFingerprint, normalizeFingerprintHex, parseAgentMdTailSignature, parseAgentMdTailSignatureForRead } from './cert-utils.js';
+import { parseFileFrontmatter, validateAgentMdDocument, validateAgentMdDocumentForRead, verifyAgentMdUpload, verifyAgentMdLegacyBodyUpload } from './agent-md-schema.js';
 import { validateOwnershipFrontmatter, verifyOwnershipFrontmatterStatus } from './ownership-proof.js';
 import { AUNError, ClientSignatureError, NotFoundError, StateError, ValidationError } from './errors.js';
 import { isJsonObject } from './types.js';
-import { parseOwnershipFile } from './ownership-v21.js';
+import { ownershipAid, parseOwnershipFile } from './ownership-v21.js';
 const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
 export function buildOwnershipReleaseAgentMd(content, release) {
     return updateOwnershipAgentMd(content, { ownership_release: release });
@@ -327,7 +327,7 @@ export class AgentMdManager {
         const target = this._safeAid(aid);
         const gatewayUrl = await this._resolveGateway(target);
         const viaGatewayHost = this._uploadViaGatewayHost && nodeBuiltin('node:http') !== null;
-        const headers = { Accept: 'text/markdown', 'X-AUN-Ownership-Check': '1', ...(viaGatewayHost ? { Host: target } : {}) };
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache', 'X-AUN-Ownership-Check': '1', ...(viaGatewayHost ? { Host: target } : {}) };
         let url = this._url(target, gatewayUrl);
         if (viaGatewayHost) {
             const parsed = new URL(gatewayUrl);
@@ -380,7 +380,7 @@ export class AgentMdManager {
         const token = await this._uploadAccessToken(target, gatewayUrl);
         const response = await fetchWithTimeout(this._url(target, gatewayUrl), {
             method: 'PUT', cache: 'no-store', redirect: 'error', body: content,
-            headers: { 'Content-Type': 'text/markdown; charset=utf-8', Authorization: `Bearer ${token}`,
+            headers: { 'X-AUN-Signature-Format': 'multi-v1', 'Content-Type': 'text/markdown; charset=utf-8', Authorization: `Bearer ${token}`,
                 ...(condition.if_match ? { 'If-Match': condition.if_match } : { 'If-None-Match': '*' }) },
         });
         if (!response.ok) {
@@ -408,30 +408,23 @@ export class AgentMdManager {
         if (!current.isPrivateKeyValid()) {
             throw new StateError('uploadAgentMd requires loaded AID with a valid private key');
         }
-        if (content !== undefined && content !== null) {
-            const text = String(content ?? '');
-            if (text.length === 0)
-                throw new ValidationError('uploadAgentMd requires non-empty content');
-            validateAgentMdDocument(text, { expectedAid: target });
-            await this.saveRecord(target, {
-                content: text,
-                local_etag: await AgentMdManager.contentEtag(text),
-                fetched_at: Date.now(),
-            });
-        }
-        const localContent = await this.readContent(target);
+        const localContent = content ?? (String((await this.loadRecord(target, true))?.local_draft_content ?? '') || await this.readContent(target));
         if (localContent === null || localContent.length === 0) {
             throw new ValidationError('uploadAgentMd requires local agent.md content');
         }
-        const parsed = validateAgentMdDocument(localContent, { expectedAid: target });
+        const parsed = this._parseBodyUpdate(localContent, target);
         if (['group', 'org'].includes(String(parsed.frontmatter.type)))
             return await this.uploadAs(target, localContent, current);
-        const signedResult = await current.signAgentMd(localContent);
+        if (parsed.signatures.length > 1) {
+            await this._verifyBodyUpload(target, localContent, current);
+            return await this._uploadPrepared(target, localContent, current);
+        }
+        const signedResult = await current.signAgentMd(this._isLegacyBodyRelation(parsed.frontmatter) ? parsed.payload : localContent);
         if (!signedResult.ok) {
             throw new ClientSignatureError(signedResult.error.message || 'agent.md signing failed');
         }
         const signed = signedResult.data.signed;
-        await verifyAgentMdUpload(signed, current.certPem, target);
+        await this._verifyBodyUpload(target, signed, current);
         return await this._uploadPrepared(target, signed, current);
     }
     async uploadAs(targetAid, content, signer) {
@@ -439,19 +432,33 @@ export class AgentMdManager {
         const rawContent = String(content ?? '');
         if (!rawContent.trim())
             throw new ValidationError('uploadAgentMd requires non-empty content');
-        const parsed = validateAgentMdDocument(rawContent, { expectedAid: target });
+        const parsed = this._parseBodyUpdate(rawContent, target);
+        if (!['group', 'org'].includes(String(parsed.frontmatter.type)) && parsed.signatures.length > 1) {
+            await this._verifyBodyUpload(target, rawContent, signer);
+            return await this._uploadPrepared(target, rawContent, signer);
+        }
         if (['group', 'org'].includes(String(parsed.frontmatter.type)) && parsed.signature) {
-            const identity = await this._entityDocumentSigner(target, rawContent);
-            await verifyAgentMdUpload(rawContent, identity.certPem, target);
-            return await this._uploadPrepared(target, rawContent, identity);
+            await verifyAgentMdUpload(rawContent, signer.certPem, target, undefined, async (aid, fingerprint) => {
+                if (!this._entitySignerResolver)
+                    throw new StateError('entity additional signing certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+                return await this._entitySignerResolver(aid, fingerprint);
+            });
+            return await this._uploadPrepared(target, rawContent, signer);
+        }
+        if (['group', 'org'].includes(String(parsed.frontmatter.type)) && signer.aid !== target) {
+            if (!this._entityIdentityGetter)
+                throw new StateError('entity signing identity is unavailable');
+            signer = await this._entityIdentityGetter(target, String(parsed.frontmatter.type));
+            if (signer.aid !== target)
+                throw new StateError('entity signing identity does not match target');
         }
         if (!signer?.isPrivateKeyValid())
             throw new StateError('uploadAgentMd requires a valid signer identity');
-        const signedResult = await signer.signAgentMd(rawContent);
+        const signedResult = await signer.signAgentMd(this._isLegacyBodyRelation(parsed.frontmatter) ? parsed.payload : rawContent);
         if (!signedResult.ok)
             throw new ClientSignatureError(signedResult.error.message || 'agent.md signing failed');
         const signed = signedResult.data.signed;
-        await verifyAgentMdUpload(signed, signer.certPem, target);
+        await this._verifyBodyUpload(target, signed, signer);
         return await this._uploadPrepared(target, signed, signer);
     }
     async pendingUpload(aid) {
@@ -467,10 +474,34 @@ export class AgentMdManager {
         const condition = pending.condition;
         if (!condition || Object.keys(condition).length !== 1 || !(typeof condition.if_match === 'string' && condition.if_match || condition.if_none_match === '*'))
             throw new StateError('pending agent.md requires its original document condition', { stringCode: 'persistence_unavailable' });
-        const meta = validateAgentMdDocument(pending.content, { expectedAid: aid, validateOwnership: false }).frontmatter;
-        if ('ownership_proof' in meta || 'ownership_release' in meta)
-            throw new StateError('legacy ownership pending agent.md cannot be recovered through ordinary upload', { stringCode: 'unsupported_protocol' });
+        const pendingDocument = validateAgentMdDocument(pending.content, { expectedAid: aid, validateOwnership: false });
+        const meta = pendingDocument.frontmatter;
+        if (this._isLegacyBodyRelation(meta) && pending.relation?.protocol !== 'legacy')
+            throw new StateError('legacy ownership pending agent.md requires its original relationship snapshot', { stringCode: 'unsupported_protocol' });
         try {
+            if (pending.relation?.protocol === 'legacy') {
+                const relation = pending.relation;
+                if (!condition.if_match || condition.if_match !== relation.original_etag || typeof relation.original_content !== 'string' || relation.original_content_etag !== await AgentMdManager.contentEtag(relation.original_content) || pending.content_etag !== await AgentMdManager.contentEtag(pending.content))
+                    throw new StateError('pending legacy original bytes or document condition are corrupt', { stringCode: 'persistence_unavailable' });
+                const original = await this._verifyLegacyBodyOriginal(aid, relation.original_content);
+                if (!this._isLegacyBodyRelation(original) || !this._sameBodyRelation(this._bodyRelationFields(original), relation.fields))
+                    throw new StateError('pending legacy original relationship snapshot is corrupt', { stringCode: 'persistence_unavailable' });
+                if (!this._sameBodyRelation(this._bodyRelationFields(meta), relation.fields))
+                    throw new StateError('legacy relationship changes require their original protocol', { stringCode: 'unsupported_protocol' });
+                const identity = signer ?? this._currentAid();
+                if (!identity || identity.aid.toLowerCase() !== aid.toLowerCase() || this._currentAid()?.aid.toLowerCase() !== aid.toLowerCase())
+                    throw new StateError('legacy body recovery requires its current subject identity', { stringCode: 'forbidden' });
+                await this._verifyBodyUpload(aid, pending.content, identity);
+                const remote = await this._readLegacyBodyFresh(aid);
+                if (remote.content === pending.content && remote.etag === pending.content_etag) {
+                    await this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, local_draft_content: '', pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+                    return true;
+                }
+                if (remote.etag !== condition.if_match || remote.content !== relation.original_content)
+                    throw new StateError('pending legacy original document changed', { stringCode: 'conflict' });
+                await this._uploadPrepared(aid, pending.content, identity, condition);
+                return true;
+            }
             if (['group', 'org'].includes(String(meta.type))) {
                 const identity = signer ?? this._currentAid();
                 if (!identity)
@@ -485,12 +516,10 @@ export class AgentMdManager {
                 if (pending.content_etag !== await AgentMdManager.contentEtag(pending.content))
                     throw new StateError('pending entity original bytes are corrupt', { stringCode: 'persistence_unavailable' });
                 const documentSigner = await this._entityDocumentSigner(aid, pending.content);
-                await verifyAgentMdUpload(pending.content, documentSigner.certPem, aid);
-                if (identity.aid.toLowerCase() !== aid.toLowerCase())
-                    await this._validateEntityUploadAuthorization(pending.authorization, aid, pending.content, identity, String(context.entity_cert_fingerprint));
+                await this._verifyEntityDocument(aid, pending.content);
                 const remote = await this._readEntityFresh(aid);
                 if (remote.exists && remote.content === pending.content && remote.etag === pending.content_etag) {
-                    await this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+                    await this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, local_draft_content: '', pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
                     return true;
                 }
                 if (condition.if_match && (!remote.exists || remote.etag !== condition.if_match) || condition.if_none_match === '*' && remote.exists)
@@ -498,6 +527,12 @@ export class AgentMdManager {
                 await this._uploadPrepared(aid, pending.content, identity, condition);
                 return true;
             }
+            const identity = signer ?? this._currentAid();
+            if (pendingDocument.signatures.length > 1) {
+                if (!identity)
+                    throw new StateError('pending agent.md requires a signer identity');
+                await this._verifyBodyUpload(aid, pending.content, identity);
+            }
             const remote = await this.readOwnershipFresh(aid);
             const fail = (code, reason, retryable = false) => new StateError(reason, { stringCode: code, retryable });
             const candidate = parseOwnershipFile(pending.content, 'agent', { expectedSubAid: aid });
@@ -519,17 +554,17 @@ export class AgentMdManager {
             if (!relation && (remote.relation_version !== 0 || remote.lock !== 'unlocked'))
                 throw fail('unavailable', 'pending agent.md cannot overwrite relationship history', true);
             if (remote.exists && remote.etag === pending.content_etag && remote.content === pending.content) {
-                const saved = await this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+                const saved = await this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, local_draft_content: '', pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
                 if (!saved.aid)
                     throw new StateError('agent.md pending completion persistence failed');
                 return true;
             }
             if (condition.if_match && (!remote.exists || remote.etag !== condition.if_match) || condition.if_none_match === '*' && remote.exists)
                 throw new StateError('pending agent.md original document condition changed', { stringCode: 'conflict' });
-            const identity = signer ?? this._currentAid();
             if (!identity)
                 throw new StateError('pending agent.md requires a signer identity');
-            await verifyAgentMdUpload(pending.content, identity.certPem, aid);
+            if (pendingDocument.signatures.length <= 1)
+                await this._verifyBodyUpload(aid, pending.content, identity);
             await this._uploadPrepared(aid, pending.content, identity, condition);
             return true;
         }
@@ -538,33 +573,142 @@ export class AgentMdManager {
             throw error;
         }
     }
+    _parseBodyUpdate(content, target) {
+        const parsed = validateAgentMdDocumentForRead(content, { expectedAid: target, validateOwnership: false });
+        return validateAgentMdDocument(this._isLegacyBodyRelation(parsed.frontmatter) && parsed.signatures.length <= 1 ? parsed.payload : content, { expectedAid: target, validateOwnership: false });
+    }
+    _isLegacyBodyRelation(meta) {
+        if (['group', 'org'].includes(String(meta.type)))
+            return false;
+        if (Object.hasOwn(meta, 'ownership')) {
+            const ownership = meta.ownership;
+            const statement = isJsonObject(ownership) ? ownership.statement : undefined;
+            return isJsonObject(statement) && statement.version === 2 && !Object.hasOwn(statement, 'relation_version');
+        }
+        return ['owner', 'ownership_proof', 'ownership_release'].some((field) => Object.hasOwn(meta, field));
+    }
+    _bodyRelationFields(meta) {
+        return Object.fromEntries(['owner', 'ownership', 'ownership_proof', 'ownership_release'].filter((field) => Object.hasOwn(meta, field)).map((field) => [field, meta[field]]));
+    }
+    _sameBodyRelation(first, second) {
+        const stable = (value) => Array.isArray(value) ? value.map(stable) : isJsonObject(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])])) : value;
+        return JSON.stringify(stable(first)) === JSON.stringify(stable(second));
+    }
+    async _readLegacyBodyFresh(target) {
+        const gateway = await this._resolveGateway(target);
+        const response = await fetchWithTimeout(this._url(target, gateway), { method: 'GET', headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache' }, cache: 'no-store', redirect: 'error' });
+        if (response.status === 404)
+            throw new StateError('legacy relationship cannot be created by an ordinary body update', { stringCode: 'unsupported_protocol' });
+        const etag = headerValue(response.headers, 'ETag');
+        if (response.status !== 200 || !etag)
+            throw new StateError('legacy original document or ETag is unavailable', { stringCode: 'unavailable', retryable: true });
+        let content;
+        try {
+            content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(await response.arrayBuffer());
+        }
+        catch {
+            throw new ValidationError('agent.md must be valid UTF-8', { stringCode: 'invalid' });
+        }
+        return { content, etag, last_modified: headerValue(response.headers, 'Last-Modified'), status: response.status };
+    }
+    async _verifyLegacyBodyOriginal(target, content) {
+        const parsed = validateAgentMdDocumentForRead(content, { expectedAid: target, validateOwnership: false, requireSignature: true });
+        const peer = await this._resolvePeer(target, parsed.signature.cert_fingerprint, Number(parsed.signature.timestamp));
+        const verified = await this._verifyPeerDocument(peer, content);
+        if (!verified.ok || verified.data.status !== 'verified')
+            throw new ClientSignatureError('legacy original agent.md signature verification failed', { stringCode: 'invalid' });
+        return parsed.frontmatter;
+    }
+    async _verifyPeerDocument(peer, content) {
+        const parsed = parseAgentMdTailSignatureForRead(content);
+        const additionalCertificates = new Map();
+        if (parsed.fields)
+            additionalCertificates.set(`${parsed.fields.signer_aid ?? peer.aid};${parsed.fields.cert_fingerprint}`, peer);
+        for (const block of parsed.signatures.slice(1))
+            additionalCertificates.set(`${block.fields.signer_aid};${block.fields.cert_fingerprint}`, await this._resolvePeer(block.fields.signer_aid, block.fields.cert_fingerprint, Number(block.fields.timestamp)));
+        return await peer.verifyAgentMd(content, (signer, fingerprint) => {
+            const certificate = additionalCertificates.get(`${signer};${fingerprint}`);
+            if (!certificate)
+                throw new StateError('additional signing certificate is unavailable', { stringCode: 'unavailable', retryable: true });
+            return certificate;
+        });
+    }
+    async _verifyBodyUpload(target, content, signer) {
+        const meta = validateAgentMdDocument(content, { expectedAid: target, validateOwnership: false }).frontmatter;
+        await (this._isLegacyBodyRelation(meta) ? verifyAgentMdLegacyBodyUpload : verifyAgentMdUpload)(content, signer.certPem, target, undefined, async (aid, fingerprint, timestamp) => {
+            if (this._entitySignerResolver)
+                return await this._entitySignerResolver(aid, fingerprint);
+            return await this._resolvePeer(aid, fingerprint, timestamp);
+        });
+    }
     async _uploadPrepared(target, signed, signer, originalCondition) {
-        const meta = validateAgentMdDocument(signed, { expectedAid: target }).frontmatter;
+        const meta = validateAgentMdDocument(signed, { expectedAid: target, validateOwnership: false }).frontmatter;
+        if (this._isLegacyBodyRelation(meta))
+            validateOwnershipFrontmatter(Object.fromEntries(['aid', 'type', 'owner'].filter((field) => Object.hasOwn(meta, field)).map((field) => [field, meta[field]])), target);
+        if (!['group', 'org'].includes(String(meta.type)))
+            await this._verifyBodyUpload(target, signed, signer);
+        if (!originalCondition) {
+            const draft = await this.saveRecord(target, { local_draft_content: signed });
+            if (draft.local_draft_content !== signed)
+                throw new StateError('agent.md local draft persistence failed', { stringCode: 'persistence_unavailable' });
+        }
         const entity = ['group', 'org'].includes(String(meta.type));
         const uploader = entity ? this._currentAid() ?? signer : signer;
         const entityContext = entity ? await this._entityContext(target, meta, uploader) : undefined;
         if (entity)
-            await verifyAgentMdUpload(signed, (await this._entityDocumentSigner(target, signed)).certPem, target);
+            await this._verifyEntityDocument(target, signed);
         let condition = originalCondition;
         let relation = entityContext ?? (await this.pendingUpload(target))?.relation;
         if (!condition) {
-            const fresh = entity ? await this._readEntityFresh(target) : await this.readOwnershipFresh(target);
-            condition = fresh.exists ? { if_match: fresh.etag } : { if_none_match: '*' };
-            if (!entity) {
+            let fresh;
+            if (!entity && this._isLegacyBodyRelation(meta))
+                fresh = await this._readLegacyBodyFresh(target);
+            else {
+                try {
+                    fresh = entity ? await this._readEntityFresh(target) : await this.readOwnershipFresh(target);
+                }
+                catch (error) {
+                    if (entity || !['unavailable', 'unsupported_protocol'].includes(String(error?.stringCode)))
+                        throw error;
+                    const legacy = await this._readLegacyBodyFresh(target);
+                    const legacyMeta = validateAgentMdDocumentForRead(legacy.content, { expectedAid: target, validateOwnership: false }).frontmatter;
+                    if (!this._isLegacyBodyRelation(legacyMeta))
+                        throw error;
+                    fresh = legacy;
+                }
+            }
+            const freshMeta = !entity && (!('exists' in fresh) || fresh.exists) && fresh.content ? validateAgentMdDocumentForRead(fresh.content, { expectedAid: target, validateOwnership: false }).frontmatter : undefined;
+            const legacy = !entity && (this._isLegacyBodyRelation(meta) || freshMeta && this._isLegacyBodyRelation(freshMeta));
+            if (legacy) {
+                if (!freshMeta || !this._isLegacyBodyRelation(freshMeta) || !this._sameBodyRelation(this._bodyRelationFields(meta), this._bodyRelationFields(freshMeta)))
+                    throw new StateError('legacy relationship changes require their original protocol', { stringCode: 'unsupported_protocol' });
+                if (!fresh.etag)
+                    throw new StateError('legacy original document ETag is unavailable', { stringCode: 'unavailable', retryable: true });
+                await this._verifyLegacyBodyOriginal(target, fresh.content);
+                condition = { if_match: fresh.etag };
+                relation = { protocol: 'legacy', original_content: fresh.content, original_content_etag: await AgentMdManager.contentEtag(fresh.content), original_etag: fresh.etag, fields: this._bodyRelationFields(freshMeta) };
+            }
+            else {
                 const authority = fresh;
-                const candidate = parseOwnershipFile(signed, 'agent', { expectedSubAid: target });
-                const statement = fresh.exists && (authority.relation_version > 0 || candidate.statement) ? parseOwnershipFile(fresh.content, 'agent', { expectedSubAid: target }).statement : undefined;
-                relation = { relation_version: authority.relation_version, lock: authority.lock, owner_aid: authority.owner_aid ?? statement?.owner_aid ?? null, statement: statement ?? null };
+                condition = authority.exists ? { if_match: fresh.etag } : { if_none_match: '*' };
+                if (!entity) {
+                    const candidate = parseOwnershipFile(signed, 'agent', { expectedSubAid: target });
+                    const statement = authority.exists && (authority.relation_version > 0 || candidate.statement) ? parseOwnershipFile(fresh.content, 'agent', { expectedSubAid: target }).statement : undefined;
+                    relation = { relation_version: authority.relation_version, lock: authority.lock, owner_aid: authority.owner_aid ?? statement?.owner_aid ?? null, statement: statement ?? null };
+                }
             }
         }
-        const ownerUpload = entity && uploader.aid.toLowerCase() !== target.toLowerCase();
-        const entityAuthorization = ownerUpload ? originalCondition ? (await this.pendingUpload(target))?.authorization : await this._ownerUploadAuthorization(target, signed, uploader, String(entityContext.entity_cert_fingerprint)) : '';
-        if (ownerUpload) {
-            const timestamp = await this._validateEntityUploadAuthorization(entityAuthorization, target, signed, uploader, String(entityContext.entity_cert_fingerprint));
-            if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300)
-                throw new StateError('pending entity V2 authorization expired; explicit upload is required', { stringCode: 'conflict' });
+        if (relation?.protocol === 'legacy') {
+            if (signer.aid.toLowerCase() !== target.toLowerCase() || this._currentAid()?.aid.toLowerCase() !== target.toLowerCase() || this._currentAid()?.certFingerprint !== signer.certFingerprint)
+                throw new StateError('legacy body update requires its current subject identity', { stringCode: 'forbidden' });
+            if (!this._isLegacyBodyRelation(meta) || !this._sameBodyRelation(this._bodyRelationFields(meta), relation.fields))
+                throw new StateError('legacy relationship changes require their original protocol', { stringCode: 'unsupported_protocol' });
+            await this._verifyBodyUpload(target, signed, signer);
         }
+        const entityAuthorization = '';
         const pending = await this.saveRecord(target, { pending_operation: 'replace', pending_target_aid: target, pending_content: signed, pending_content_etag: await AgentMdManager.contentEtag(signed), pending_error: '', pending_condition: condition, pending_relation: relation, pending_authorization: entityAuthorization });
+        if (relation?.protocol === 'legacy' && !this._sameBodyRelation(pending.pending_relation, relation))
+            throw new StateError('legacy original relationship snapshot persistence failed', { stringCode: 'persistence_unavailable' });
         const savedCondition = pending.pending_condition;
         if (pending.pending_content !== signed || savedCondition?.if_match !== condition.if_match || savedCondition?.if_none_match !== condition.if_none_match || pending.pending_authorization !== entityAuthorization)
             throw new StateError('agent.md pending upload persistence failed');
@@ -573,11 +717,12 @@ export class AgentMdManager {
             const delegated = target.toLowerCase() !== this._ownerAid().toLowerCase();
             if (delegated && !owner?.isPrivateKeyValid())
                 throw new StateError('owner agent.md upload requires a loaded owner identity');
-            const authorization = entity ? entityAuthorization : delegated ? await this._ownerUploadAuthorization(target, signed, owner) : '';
-            const result = await this._uploadHttp(target, signed, authorization, condition);
+            const authorization = entity ? '' : delegated ? await this._ownerUploadAuthorization(target, signed, owner) : '';
+            const result = await this._uploadHttp(target, signed, authorization, condition, relation?.protocol === 'legacy');
             const remoteEtag = String(result.etag ?? '').trim();
+            const contentEtag = await AgentMdManager.contentEtag(signed);
             const saved = await this.saveRecord(target, {
-                content: signed, local_etag: await AgentMdManager.contentEtag(signed), remote_etag: remoteEtag || undefined,
+                content: signed, local_etag: contentEtag, remote_etag: remoteEtag || undefined, ...(remoteEtag === contentEtag ? { local_draft_content: '' } : {}),
                 last_modified: String(result.last_modified ?? result.lastModified ?? '').trim(), fetched_at: Date.now(), checked_at: Date.now(),
                 remote_status: remoteEtag ? 'found' : 'unknown', last_error: '',
                 pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '',
@@ -595,12 +740,17 @@ export class AgentMdManager {
         const fresh = await this._readEntityFresh(this._safeAid(target));
         if (fresh.ownership_status !== 'not_applicable' || !['current', 'stale'].includes(fresh.entity_status ?? '') || !fresh.owner_aid || !/^sha256:[0-9a-f]{64}$/.test(fresh.entity_cert_fingerprint ?? ''))
             throw new StateError('entity current owner authority is unavailable', { stringCode: 'unavailable', retryable: true });
-        return { owner_aid: this._safeAid(fresh.owner_aid), entity_cert_fingerprint: fresh.entity_cert_fingerprint };
+        try {
+            return { owner_aid: this._safeAid(ownershipAid(fresh.owner_aid, 'owner_aid')), entity_cert_fingerprint: fresh.entity_cert_fingerprint };
+        }
+        catch {
+            throw new StateError('entity current owner authority is unavailable', { stringCode: 'unavailable', retryable: true });
+        }
     }
     async _readEntityFresh(target) {
         const gateway = await this._resolveGateway(target);
         const viaGatewayHost = this._uploadViaGatewayHost && nodeBuiltin('node:http') !== null;
-        const headers = { 'Cache-Control': 'no-cache', ...(viaGatewayHost ? { Host: target } : {}) };
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1', 'X-AUN-Ownership-Check': '1', 'Cache-Control': 'no-cache', ...(viaGatewayHost ? { Host: target } : {}) };
         let url = this._url(target, gateway);
         if (viaGatewayHost) {
             const parsed = new URL(gateway);
@@ -656,8 +806,8 @@ export class AgentMdManager {
     }
     async _entityContext(target, meta, signer) {
         const owner = String(meta.owner ?? '').trim().toLowerCase();
-        if (![owner, target.toLowerCase()].includes(signer.aid.toLowerCase()) || signer.aid.toLowerCase() !== this._ownerAid().toLowerCase())
-            throw new StateError('group/org agent.md requires entity or current owner uploader', { stringCode: 'forbidden' });
+        if (signer.aid.toLowerCase() !== owner || signer.aid.toLowerCase() !== this._ownerAid().toLowerCase())
+            throw new StateError('group/org agent.md requires current owner uploader', { stringCode: 'forbidden' });
         const context = await this._entityCurrentContext(target, meta, true);
         if (signer.aid.toLowerCase() === owner)
             await this._verifyEntityOwnerSigner(signer);
@@ -683,6 +833,17 @@ export class AgentMdManager {
             throw new StateError('entity signing certificate changed', { stringCode: 'conflict' });
         return signer;
     }
+    async _verifyEntityDocument(target, content) {
+        const primary = await this._entityDocumentSigner(target, content);
+        await verifyAgentMdUpload(content, primary.certPem, target, undefined, async (signer, fingerprint) => {
+            if (!this._entitySignerResolver)
+                throw new StateError('entity additional signing certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+            const material = await this._entitySignerResolver(signer, fingerprint);
+            if (material.aid !== signer || material.certFingerprint !== fingerprint)
+                throw new StateError('entity additional signing certificate changed', { stringCode: 'conflict' });
+            return material;
+        });
+    }
     async _verifyEntityOwnerSigner(owner) {
         if (!this._entitySignerResolver)
             throw new StateError('entity owner signing certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
@@ -694,15 +855,15 @@ export class AgentMdManager {
     async download(aid, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) {
         const target = this._safeAid(String(aid ?? this._ownerAid() ?? '').trim());
         const contentResult = await this._downloadHttp(target, timeoutMs);
-        const parsed = parseAgentMdTailSignature(contentResult.content);
+        const parsed = parseAgentMdTailSignatureForRead(contentResult.content);
         let entity = false;
         try {
-            entity = ['group', 'org'].includes(String(parseFileFrontmatter(parsed.payload).type));
+            entity = ['group', 'org'].includes(String(parseFileFrontmatter(parsed.payload, false, false).type));
         }
         catch { }
         let frontmatter;
         try {
-            frontmatter = validateAgentMdDocument(contentResult.content, { expectedAid: target, validateOwnership: false, ...(entity ? { requireSignature: true } : {}) }).frontmatter;
+            frontmatter = validateAgentMdDocumentForRead(contentResult.content, { expectedAid: target, validateOwnership: false, ...(entity ? { requireSignature: true } : {}) }).frontmatter;
         }
         catch (error) {
             if (entity)
@@ -710,10 +871,9 @@ export class AgentMdManager {
             throw error;
         }
         const expectedFp = parsed.fields?.cert_fingerprint || parsed.fields?.public_key_fingerprint || null;
-        if (entity)
-            await this._entityCurrentContext(target, frontmatter);
-        const peer = entity ? await this._entityDocumentSigner(target, contentResult.content) : await this._resolvePeer(target, expectedFp, parsed.fields?.timestamp ? Number(parsed.fields.timestamp) : undefined);
-        const verified = await peer.verifyAgentMd(contentResult.content);
+        const signerAid = entity ? (parsed.fields?.signer_aid ?? target) : target;
+        const peer = await this._resolvePeer(signerAid, expectedFp, parsed.fields?.timestamp ? Number(parsed.fields.timestamp) : undefined);
+        const verified = await this._verifyPeerDocument(peer, contentResult.content);
         if (!verified.ok)
             throw new AUNError(verified.error.message);
         const signature = { ...verified.data };
@@ -971,7 +1131,7 @@ export class AgentMdManager {
         const root = this.root;
         await this._writeStorage(this._contentKey(aid), String(content ?? ''), root);
     }
-    async loadRecord(aid) {
+    async loadRecord(aid, strict = false) {
         const target = String(aid ?? '').trim();
         if (!target)
             return null;
@@ -979,7 +1139,7 @@ export class AgentMdManager {
         const generation = this._storageGeneration;
         try {
             const loaded = await this._withLock(async () => {
-                const record = await this._readRecordUnlocked(target, root);
+                const record = await this._readRecordUnlocked(target, root, strict);
                 const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
                 try {
                     const content = await this._readStorage(this._contentKey(target), root);
@@ -1005,6 +1165,8 @@ export class AgentMdManager {
             return { ...loaded };
         }
         catch (err) {
+            if (strict)
+                throw err;
             this._log.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
             return null;
         }
@@ -1015,10 +1177,12 @@ export class AgentMdManager {
             return {};
         const root = this.root;
         const generation = this._storageGeneration;
+        let strictDraft = false;
         try {
             const inputFields = { ...fields };
+            strictDraft = typeof inputFields.local_draft_content === 'string';
             const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
-            if (hasContent) {
+            if (hasContent && !strictDraft) {
                 const text = String(inputFields.content ?? '');
                 await this._writeStorage(this._contentKey(target), text, root);
                 if (!inputFields.local_etag)
@@ -1028,8 +1192,18 @@ export class AgentMdManager {
             }
             delete inputFields.content;
             const record = await this._withLock(async () => {
-                const next = { ...(await this._readRecordUnlocked(target, root)), aid: target };
+                const next = { ...(await this._readRecordUnlocked(target, root, strictDraft)), aid: target };
+                if (hasContent && strictDraft) {
+                    const text = String(fields.content ?? '');
+                    await this._writeStorage(this._contentKey(target), text, root);
+                    if (!inputFields.local_etag)
+                        inputFields.local_etag = await AgentMdManager.contentEtag(text);
+                    if (!inputFields.fetched_at)
+                        inputFields.fetched_at = Date.now();
+                }
                 for (const [key, value] of Object.entries(inputFields)) {
+                    if (key === 'local_draft_content' && value === '' && hasContent && next.local_draft_content !== fields.content)
+                        continue;
                     if (value !== undefined && value !== null)
                         next[key] = value;
                 }
@@ -1045,6 +1219,8 @@ export class AgentMdManager {
             return { ...loaded };
         }
         catch (err) {
+            if (strictDraft)
+                throw err;
             this._log.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
             return {};
         }
@@ -1105,7 +1281,8 @@ export class AgentMdManager {
         return String(await this._gatewayResolver?.(aid) ?? '');
     }
     async _resolvePeer(aid, certFingerprint, signedAt) {
-        const expectedFp = String(certFingerprint ?? '').trim().toLowerCase();
+        const normalizedFp = normalizeFingerprintHex(certFingerprint);
+        const expectedFp = normalizedFp ? `sha256:${normalizedFp}` : String(certFingerprint ?? '').trim().toLowerCase();
         const current = this._currentAid();
         if (current && current.aid.toLowerCase() === aid.toLowerCase()) {
             if (!expectedFp || await certMatchesFingerprint(current.certPem, expectedFp))
@@ -1115,6 +1292,8 @@ export class AgentMdManager {
         if (!(peer instanceof AID)) {
             throw new StateError(`agent.md peer resolver did not return AID for ${aid}`);
         }
+        if (peer.aid.toLowerCase() !== aid.toLowerCase())
+            throw new ClientSignatureError(`agent.md signer does not match requested AID: ${aid}`, { stringCode: 'invalid' });
         return peer;
     }
     async _accessToken(aid, gatewayUrl) {
@@ -1130,52 +1309,21 @@ export class AgentMdManager {
             throw new StateError('authenticate did not return access_token');
         return token;
     }
-    async _validateEntityUploadAuthorization(authorization, target, content, owner, entityFingerprint) {
-        const invalid = new StateError('pending entity original V2 authorization is missing or invalid', { stringCode: 'persistence_unavailable' });
-        try {
-            if (typeof authorization !== 'string' || !/^[A-Za-z0-9_-]+={0,2}$/.test(authorization) || authorization.includes('=') && authorization.length % 4 !== 0)
-                throw invalid;
-            const binary = globalThis.atob(authorization.replace(/-/g, '+').replace(/_/g, '/'));
-            const text = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(binary, char => char.charCodeAt(0)));
-            if (base64UrlEncode(text) !== authorization.replace(/=+$/, ''))
-                throw invalid;
-            const value = JSON.parse(text);
-            const lexical = parseDocument(text, { uniqueKeys: true });
-            if (lexical.errors.length || lexical.get('version', true)?.source !== '2' || !/^[1-9][0-9]*$/.test(lexical.get('timestamp', true)?.source ?? ''))
-                throw invalid;
-            const fields = ['version', 'target_aid', 'uploader_aid', 'body_sha256', 'entity_cert_fingerprint', 'timestamp', 'nonce', 'cert_fingerprint', 'signature'];
-            if (!isJsonObject(value) || Object.keys(value).length !== fields.length || fields.some(field => !(field in value)) || value.version !== 2)
-                throw invalid;
-            const timestamp = value.timestamp, nonce = value.nonce;
-            if (typeof timestamp !== 'number' || !Number.isSafeInteger(timestamp) || timestamp <= 0 || typeof nonce !== 'string' || !nonce.trim() || new TextEncoder().encode(nonce).length > 128)
-                throw invalid;
-            if (value.target_aid !== target.toLowerCase() || value.uploader_aid !== owner.aid.toLowerCase() || value.body_sha256 !== await sha256Hex(content) || value.entity_cert_fingerprint !== entityFingerprint || value.cert_fingerprint !== owner.certFingerprint || typeof value.signature !== 'string')
-                throw invalid;
-            const verified = await owner.verify(`AUN-AGENTMD-OWNER-AUTH-V2;${value.uploader_aid};${value.target_aid};${value.body_sha256};${entityFingerprint};${timestamp};${nonce}`, value.signature);
-            if (!verified.ok || !verified.data?.valid)
-                throw invalid;
-            return timestamp;
-        }
-        catch {
-            throw invalid;
-        }
-    }
-    async _ownerUploadAuthorization(target, content, owner, entityFingerprint = '') {
+    async _ownerUploadAuthorization(target, content, owner) {
         const bodySha256 = await sha256Hex(content);
         const timestamp = Math.floor(Date.now() / 1000);
         const nonce = randomOwnerAuthorizationNonce();
-        const canonical = entityFingerprint ? `AUN-AGENTMD-OWNER-AUTH-V2;${owner.aid.toLowerCase()};${target.toLowerCase()};${bodySha256};${entityFingerprint};${timestamp};${nonce}` : `AUN-AGENT-MD-UPLOAD-V1;${owner.aid.toLowerCase()};${target.toLowerCase()};${bodySha256};${timestamp};${nonce}`;
+        const canonical = `AUN-AGENT-MD-UPLOAD-V1;${owner.aid.toLowerCase()};${target.toLowerCase()};${bodySha256};${timestamp};${nonce}`;
         const signed = await owner.sign(canonical);
         if (!signed.ok || !signed.data) {
             const message = signed.error?.message || 'owner authorization signing failed';
             throw new ClientSignatureError(message);
         }
         return base64UrlEncode(JSON.stringify({
-            version: entityFingerprint ? 2 : 1,
+            version: 1,
             target_aid: target.toLowerCase(),
             uploader_aid: owner.aid.toLowerCase(),
             body_sha256: bodySha256,
-            ...(entityFingerprint ? { entity_cert_fingerprint: entityFingerprint } : {}),
             timestamp,
             nonce,
             cert_fingerprint: owner.certFingerprint,
@@ -1185,20 +1333,21 @@ export class AgentMdManager {
     _url(aid, gatewayUrl) {
         return `${agentMdHttpScheme(gatewayUrl)}://${this._safeAid(aid)}/agent.md`;
     }
-    async _uploadHttp(aid, content, ownerAuthorization = '', condition) {
+    async _uploadHttp(aid, content, ownerAuthorization = '', condition, legacyBodyUpdate = false) {
         if (!condition || Object.keys(condition).length !== 1 || !(typeof condition.if_match === 'string' && condition.if_match || condition.if_none_match === '*'))
             throw new StateError('agent.md upload requires its original document condition', { stringCode: 'persistence_unavailable' });
         const gatewayUrl = await this._resolveGateway(aid);
         const authorization = String(ownerAuthorization ?? '').trim();
-        const entity = ['group', 'org'].includes(String(validateAgentMdDocument(content, { expectedAid: aid }).frontmatter.type));
+        const meta = validateAgentMdDocument(content, { expectedAid: aid, validateOwnership: false }).frontmatter;
+        const entity = ['group', 'org'].includes(String(meta.type));
         // 浏览器禁止覆盖 Host；动态 AID URL 由浏览器/Docker 的通配解析路由。
         const viaGatewayHost = this._uploadViaGatewayHost && nodeBuiltin('node:http') !== null;
-        const headers = {
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1',
             'Content-Type': 'text/markdown; charset=utf-8',
-            ...(!entity ? { 'X-AUN-Ownership-Check': '1' } : {}),
+            ...(!entity && !(legacyBodyUpdate && this._isLegacyBodyRelation(meta)) ? { 'X-AUN-Ownership-Check': '1' } : {}),
             ...(condition.if_match ? { 'If-Match': condition.if_match } : { 'If-None-Match': '*' }),
             ...(viaGatewayHost ? { Host: this._safeAid(aid) } : {}),
-            ...(authorization ? { [entity ? 'AUN-AGENTMD-OWNER-AUTHORIZATION' : 'X-AUN-AgentMD-Owner-Authorization']: authorization } : {}),
+            ...(!entity && authorization ? { 'X-AUN-AgentMD-Owner-Authorization': authorization } : {}),
         };
         if (!authorization || entity) {
             const token = await this._uploadAccessToken(aid, gatewayUrl);
@@ -1223,7 +1372,7 @@ export class AgentMdManager {
         }
         let response;
         try {
-            response = await fetchWithTimeout(url, { method: 'PUT', headers, body: content });
+            response = await fetchWithTimeout(url, { method: 'PUT', headers, body: content, redirect: 'error' });
         }
         catch (error) {
             if (!viaGatewayHost)
@@ -1231,12 +1380,12 @@ export class AgentMdManager {
             const fallbackUrl = nameServiceAgentMdUrl(aid, gatewayUrl);
             if (!fallbackUrl || fallbackUrl === url)
                 throw error;
-            response = await fetchWithTimeout(fallbackUrl, { method: 'PUT', headers, body: content });
+            response = await fetchWithTimeout(fallbackUrl, { method: 'PUT', headers, body: content, redirect: 'error' });
         }
         if (response.status === 404 && viaGatewayHost) {
             const fallbackUrl = nameServiceAgentMdUrl(aid, gatewayUrl);
             if (fallbackUrl && fallbackUrl !== url) {
-                response = await fetchWithTimeout(fallbackUrl, { method: 'PUT', headers, body: content });
+                response = await fetchWithTimeout(fallbackUrl, { method: 'PUT', headers, body: content, redirect: 'error' });
             }
         }
         if (response.status === 404) {
@@ -1260,13 +1409,13 @@ export class AgentMdManager {
         const cached = await this.loadRecord(target) ?? {};
         const gatewayUrl = await this._resolveGateway(target);
         const url = this._url(target, gatewayUrl);
-        const headers = { Accept: 'text/markdown' };
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown' };
         const cachedEtag = String(cached.remote_etag ?? cached.etag ?? cached.local_etag ?? '').trim();
         const cachedLastModified = String(cached.last_modified ?? '').trim();
         let response = await fetchWithTimeout(url, {
             method: 'GET',
             headers,
-            redirect: 'follow',
+            redirect: 'error',
         }, timeoutMs);
         if (response.status === 304 && cached.content !== undefined && cached.content !== null) {
             return {
@@ -1279,8 +1428,8 @@ export class AgentMdManager {
         if (response.status === 304) {
             response = await fetchWithTimeout(url, {
                 method: 'GET',
-                headers: { Accept: 'text/markdown' },
-                redirect: 'follow',
+                headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown' },
+                redirect: 'error',
             }, timeoutMs);
         }
         if (response.status === 404) {
@@ -1310,7 +1459,7 @@ export class AgentMdManager {
         const gatewayUrl = await this._resolveGateway(target);
         const response = await fetchWithTimeout(this._url(target, gatewayUrl), {
             method: 'HEAD',
-            headers: { Accept: 'text/markdown' },
+            headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown' },
         }, HEAD_HTTP_TIMEOUT_MS);
         const etag = headerValue(response.headers, 'ETag');
         const lastModified = headerValue(response.headers, 'Last-Modified');
@@ -1405,14 +1554,22 @@ export class AgentMdManager {
         payload.aid = this._safeAid(aid);
         await this._writeStorage(this._metaKey(aid), `${JSON.stringify(payload, null, 2)}\n`, root);
     }
-    async _readRecordUnlocked(aid, root = this.root) {
-        const raw = await this._readStorage(this._metaKey(aid), root);
-        if (raw === null)
-            return {};
+    async _readRecordUnlocked(aid, root = this.root, strict = false) {
         try {
-            return this._normalizeRecord(aid, JSON.parse(raw));
+            const raw = await this._readStorage(this._metaKey(aid), root);
+            if (raw === null)
+                return {};
+            const parsed = JSON.parse(raw);
+            if (strict && !isRecord(parsed))
+                throw new StateError('agent.md metadata is damaged', { stringCode: 'persistence_unavailable' });
+            return this._normalizeRecord(aid, parsed);
         }
         catch (err) {
+            if (strict) {
+                if (err instanceof StateError)
+                    throw err;
+                throw new StateError('agent.md metadata is damaged', { stringCode: 'persistence_unavailable' });
+            }
             this._log.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
             return {};
         }