@agentunion/fastaun-browser 0.5.18 → 0.5.19

package/dist/agent-md.js

@@ -1,9 +1,43 @@
 import { AID } from './aid.js';
+import { parseDocument } from 'yaml';
 import { certMatchesFingerprint, parseAgentMdTailSignature } from './cert-utils.js';
-import { validateAgentMdDocument, verifyAgentMdUpload } from './agent-md-schema.js';
+import { parseFileFrontmatter, validateAgentMdDocument, verifyAgentMdUpload } 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';
 const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+export function buildOwnershipReleaseAgentMd(content, release) {
+    return updateOwnershipAgentMd(content, { ownership_release: release });
+}
+export function buildOwnershipAgentMd(content, owner, proof) {
+    return updateOwnershipAgentMd(content, { owner, ownership_proof: proof });
+}
+export function buildOwnershipAgentMdV21(content, statement) {
+    return updateOwnershipAgentMd(content, statement ? { owner: statement.owner_aid, ownership: { statement } } : {});
+}
+function updateOwnershipAgentMd(content, fields) {
+    const payload = parseAgentMdTailSignature(String(content ?? '')).payload;
+    const match = /^---(?:\r\n|\n|\r)([\s\S]*?)(?:\r\n|\n|\r)---([\s\S]*)$/.exec(payload);
+    if (!match)
+        throw new ValidationError('agent.md must start with YAML frontmatter');
+    const document = parseDocument(match[1], { uniqueKeys: true });
+    if (document.errors.length)
+        throw new ValidationError(`agent.md frontmatter is invalid: ${document.errors[0].message}`);
+    const frontmatter = document.toJS();
+    if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter))
+        throw new ValidationError('agent.md frontmatter must be a mapping');
+    document.delete('owner');
+    document.delete('ownership_proof');
+    document.delete('ownership_release');
+    document.delete('ownership');
+    for (const [name, value] of Object.entries(fields))
+        document.set(name, value);
+    const yamlText = document.toString().replace(/\r\n/g, '\n');
+    const updated = `---\n${yamlText.endsWith('\n') ? yamlText : `${yamlText}\n`}---${match[2]}`;
+    validateAgentMdDocument(updated, { expectedAid: String(frontmatter.aid ?? '') });
+    return updated;
+}
 export function buildDefaultAgentMd(aid, options = {}) {
     const target = String(aid ?? '').trim();
     const type = String(options.type ?? 'agent').trim() || 'agent';
@@ -16,6 +50,10 @@ export function buildDefaultAgentMd(aid, options = {}) {
         `aid: ${JSON.stringify(target)}`,
         `name: ${JSON.stringify(name)}`,
         `type: ${JSON.stringify(type)}`,
+        ...(options.exttype ? [`exttype: ${JSON.stringify(options.exttype)}`] : []),
+        ...(options.owner ? [`owner: ${JSON.stringify(options.owner)}`] : []),
+        ...(options.entityCertFingerprint ? [`entity_cert_fingerprint: ${JSON.stringify(options.entityCertFingerprint)}`] : []),
+        ...(options.ownershipProof ? [`ownership_proof: ${JSON.stringify(options.ownershipProof)}`] : []),
         'version: "1.0.0"',
         `description: ${JSON.stringify(description)}`,
         ...(avatar ? [`avatar: ${JSON.stringify(avatar)}`] : []),
@@ -44,6 +82,24 @@ function nodeBuiltin(name) {
         return null;
     }
 }
+async function sha256Hex(value) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function randomOwnerAuthorizationNonce() {
+    if (typeof globalThis.crypto.randomUUID === 'function')
+        return globalThis.crypto.randomUUID().replaceAll('-', '');
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function base64UrlEncode(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
 function requestHeaders(init) {
     const out = {};
     try {
@@ -231,7 +287,11 @@ export class AgentMdManager {
     _gatewayResolver;
     _peerResolver;
     _accessTokenResolver;
+    _uploadAccessTokenResolver;
     _aidValidator;
+    _entityOwnerResolver;
+    _entityIdentityGetter;
+    _entitySignerResolver;
     _cache = new Map();
     _memoryStorage = new Map();
     _fetchInflight = new Set();
@@ -250,7 +310,11 @@ export class AgentMdManager {
         this._gatewayResolver = opts.gatewayResolver;
         this._peerResolver = opts.peerResolver;
         this._accessTokenResolver = opts.accessTokenResolver;
+        this._uploadAccessTokenResolver = opts.uploadAccessTokenResolver;
         this._aidValidator = opts.aidValidator;
+        this._entityOwnerResolver = opts.entityOwnerResolver;
+        this._entityIdentityGetter = opts.entityIdentityGetter;
+        this._entitySignerResolver = opts.entitySignerResolver;
     }
     get root() {
         return this._agentMdPath || this._defaultRoot();
@@ -259,6 +323,73 @@ export class AgentMdManager {
         this._aunPath = String(aunPath ?? '');
         this.setRoot(null);
     }
+    async readOwnershipFresh(aid) {
+        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 } : {}) };
+        let url = this._url(target, gatewayUrl);
+        if (viaGatewayHost) {
+            const parsed = new URL(gatewayUrl);
+            const port = parsed.port && parsed.port !== '443' && parsed.port !== '20001' ? `:${parsed.port}` : '';
+            url = `${agentMdHttpScheme(gatewayUrl)}://${parsed.hostname}${port}/agent.md`;
+        }
+        const read = (targetUrl) => fetchWithTimeout(targetUrl, {
+            method: 'GET', cache: 'no-store', redirect: 'error',
+            headers,
+        });
+        let response = await read(url);
+        if (response.status === 404 && !headerValue(response.headers, 'X-AUN-Ownership-Protocol') && headerValue(response.headers, 'X-AUN-Ownership-Status') !== 'not_applicable' && viaGatewayHost) {
+            const fallback = nameServiceAgentMdUrl(target, gatewayUrl);
+            if (fallback && fallback !== url)
+                response = await read(fallback);
+        }
+        if (!response.ok && response.status !== 404)
+            throw new StateError(`NS ownership check unavailable: HTTP ${response.status}`, { stringCode: 'unavailable', retryable: true });
+        if (headerValue(response.headers, 'X-AUN-Ownership-Status') === 'not_applicable')
+            throw new StateError('group/org uses its lifecycle owner relationship', { stringCode: 'not_applicable' });
+        const protocol = headerValue(response.headers, 'X-AUN-Ownership-Protocol');
+        const version = headerValue(response.headers, 'X-AUN-Ownership-Version');
+        const lock = headerValue(response.headers, 'X-AUN-Ownership-Lock');
+        const etag = headerValue(response.headers, 'ETag');
+        if (protocol !== '2.1')
+            throw new StateError('NS ownership protocol metadata unavailable', { stringCode: 'unsupported_protocol', retryable: true });
+        if (!/^(0|[1-9][0-9]*)$/.test(version) || !Number.isSafeInteger(Number(version)) || !['locked', 'unlocked'].includes(lock))
+            throw new StateError('NS ownership relationship metadata unavailable', { stringCode: 'unavailable', retryable: true });
+        if (response.status === 404 && (Number(version) !== 0 || lock !== 'unlocked') || response.ok && !etag)
+            throw new StateError('NS ownership document metadata unavailable', { stringCode: 'unavailable', retryable: true });
+        let content = '';
+        if (response.ok) {
+            try {
+                content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(await response.arrayBuffer());
+            }
+            catch {
+                throw new ValidationError('NS ownership file must be valid UTF-8', { stringCode: 'invalid' });
+            }
+        }
+        return { sub_aid: target, exists: response.ok, content, etag, protocol, relation_version: Number(version), lock: lock, observed_at: Math.trunc(Date.now() / 1000) };
+    }
+    async submitOwnershipRaw(aid, content, condition) {
+        const target = this._safeAid(aid);
+        if (this._currentAid()?.aid !== target)
+            throw new ValidationError('ownership upload requires its own identity', { stringCode: 'forbidden' });
+        parseOwnershipFile(content, 'agent', { expectedSubAid: target });
+        if (Boolean(condition.if_match) === Boolean(condition.if_none_match === '*'))
+            throw new ValidationError('ownership upload requires its original document condition');
+        const gatewayUrl = await this._resolveGateway(target);
+        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}`,
+                ...(condition.if_match ? { 'If-Match': condition.if_match } : { 'If-None-Match': '*' }) },
+        });
+        if (!response.ok) {
+            const reason = (await response.text()).trim();
+            const code = response.status === 409 || response.status === 412 ? 'conflict' : response.status === 401 || response.status === 403 ? 'forbidden' : response.status === 428 ? 'unsupported_protocol' : response.status >= 500 ? 'unavailable' : 'invalid';
+            throw new StateError(`ownership agent.md upload failed: HTTP ${response.status}${reason ? ` ${reason}` : ''}`, { stringCode: /owner_locked/.test(reason) ? 'owner_locked' : code, retryable: code === 'unavailable' });
+        }
+        return await this.readOwnershipFresh(target);
+    }
     setRoot(root) {
         this._agentMdPath = String(root ?? '').trim() || this._defaultRoot();
         this._storageGeneration += 1;
@@ -268,7 +399,7 @@ export class AgentMdManager {
         this._snapshotLoads.clear();
         return this._agentMdPath;
     }
-    async upload(content, ownerOperationId) {
+    async upload(content) {
         const target = this._ownerAid();
         const current = this._currentAid();
         if (!target || !current) {
@@ -292,34 +423,296 @@ export class AgentMdManager {
         if (localContent === null || localContent.length === 0) {
             throw new ValidationError('uploadAgentMd requires local agent.md content');
         }
-        validateAgentMdDocument(localContent, { expectedAid: target });
+        const parsed = validateAgentMdDocument(localContent, { expectedAid: target });
+        if (['group', 'org'].includes(String(parsed.frontmatter.type)))
+            return await this.uploadAs(target, localContent, current);
         const signedResult = await current.signAgentMd(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);
-        const result = await this._uploadHttp(target, signed, ownerOperationId);
-        const localEtag = await AgentMdManager.contentEtag(signed);
-        const remoteEtag = String(result.etag ?? '').trim();
-        await this.saveRecord(target, {
-            content: signed,
-            local_etag: localEtag,
-            remote_etag: remoteEtag || undefined,
-            last_modified: String(result.last_modified ?? result.lastModified ?? '').trim(),
-            fetched_at: Date.now(),
-            checked_at: Date.now(),
-            remote_status: remoteEtag ? 'found' : 'unknown',
-            last_error: '',
-        });
-        return result;
+        return await this._uploadPrepared(target, signed, current);
+    }
+    async uploadAs(targetAid, content, signer) {
+        const target = this._safeAid(String(targetAid ?? '').trim());
+        const rawContent = String(content ?? '');
+        if (!rawContent.trim())
+            throw new ValidationError('uploadAgentMd requires non-empty content');
+        const parsed = validateAgentMdDocument(rawContent, { expectedAid: target });
+        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);
+        }
+        if (!signer?.isPrivateKeyValid())
+            throw new StateError('uploadAgentMd requires a valid signer identity');
+        const signedResult = await signer.signAgentMd(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);
+        return await this._uploadPrepared(target, signed, signer);
+    }
+    async pendingUpload(aid) {
+        const record = await this.loadRecord(aid);
+        if (record?.pending_operation !== 'replace' || !String(record.pending_content ?? '').trim())
+            return null;
+        return { content: String(record.pending_content), content_etag: String(record.pending_content_etag ?? ''), last_error: String(record.pending_error ?? ''), condition: record.pending_condition, relation: record.pending_relation, authorization: record.pending_authorization };
+    }
+    async resumePendingUpload(aid, signer) {
+        const pending = await this.pendingUpload(aid);
+        if (!pending)
+            return false;
+        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' });
+        try {
+            if (['group', 'org'].includes(String(meta.type))) {
+                const identity = signer ?? this._currentAid();
+                if (!identity)
+                    throw new StateError('entity upload recovery requires current owner', { stringCode: 'forbidden' });
+                const context = await this._entityContext(aid, meta, identity);
+                if (!pending.relation?.entity_cert_fingerprint)
+                    throw new StateError('pending entity upload requires original owner and certificate context', { stringCode: 'persistence_unavailable' });
+                if (pending.relation.owner_aid !== context.owner_aid)
+                    throw new StateError('pending entity upload belongs to a different owner', { stringCode: 'forbidden' });
+                if (pending.relation.entity_cert_fingerprint !== context.entity_cert_fingerprint)
+                    throw new StateError('pending entity upload belongs to an old rekey generation', { stringCode: 'conflict' });
+                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));
+                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: '' });
+                    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' });
+                await this._uploadPrepared(aid, pending.content, identity, condition);
+                return true;
+            }
+            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 });
+            const relation = pending.relation && Object.keys(pending.relation).length ? pending.relation : undefined;
+            const sameStatement = (first, second) => first == null && second == null || isJsonObject(first) && isJsonObject(second) && ['version', 'declaration_id', 'owner_aid', 'sub_aid', 'relation_version', 'declared_at'].every((field) => first[field] === second[field]);
+            if (candidate.statement && !relation)
+                throw fail('persistence_unavailable', 'pending ownership body update requires its original relationship context');
+            if (relation) {
+                if (remote.relation_version !== relation.relation_version || remote.lock !== relation.lock)
+                    throw fail('conflict', 'pending agent.md original relationship changed');
+                if (!sameStatement(candidate.statement, relation.statement))
+                    throw fail('unsupported_protocol', 'ownership changes require their persisted 2.1 task');
+                if (remote.exists && (remote.relation_version > 0 || candidate.statement)) {
+                    const current = parseOwnershipFile(remote.content, 'agent', { expectedSubAid: aid });
+                    if (!sameStatement(current.statement, relation.statement) || (remote.owner_aid ?? current.statement?.owner_aid ?? null) !== relation.owner_aid)
+                        throw fail('conflict', 'pending agent.md relationship statement changed');
+                }
+            }
+            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: '' });
+                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);
+            await this._uploadPrepared(aid, pending.content, identity, condition);
+            return true;
+        }
+        catch (error) {
+            await this.saveRecord(aid, { pending_error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    async _uploadPrepared(target, signed, signer, originalCondition) {
+        const meta = validateAgentMdDocument(signed, { expectedAid: target }).frontmatter;
+        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);
+        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) {
+                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 };
+            }
+        }
+        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' });
+        }
+        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 });
+        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');
+        try {
+            const owner = this._currentAid();
+            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 remoteEtag = String(result.etag ?? '').trim();
+            const saved = await this.saveRecord(target, {
+                content: signed, local_etag: await AgentMdManager.contentEtag(signed), remote_etag: remoteEtag || undefined,
+                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: '',
+            });
+            if (!saved.aid)
+                throw new StateError('agent.md upload completion persistence failed');
+            return { ...result };
+        }
+        catch (error) {
+            await this.saveRecord(target, { pending_error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    async readEntityAuthorityFresh(target) {
+        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 };
+    }
+    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 } : {}) };
+        let url = this._url(target, gateway);
+        if (viaGatewayHost) {
+            const parsed = new URL(gateway);
+            const port = parsed.port && parsed.port !== '443' && parsed.port !== '20001' ? `:${parsed.port}` : '';
+            url = `${agentMdHttpScheme(gateway)}://${parsed.hostname}${port}/agent.md`;
+        }
+        let response;
+        try {
+            response = await fetchWithTimeout(url, { method: 'GET', cache: 'no-store', redirect: 'error', headers });
+        }
+        catch (error) {
+            throw new StateError(`entity agent.md fresh read unavailable: ${String(error)}`, { stringCode: 'unavailable', retryable: true });
+        }
+        if (response.status !== 200 && response.status !== 404)
+            throw new StateError(`entity agent.md fresh read failed: HTTP ${response.status}`, { stringCode: 'unavailable', retryable: true });
+        const etag = headerValue(response.headers, 'ETag');
+        if (response.status === 200 && !etag)
+            throw new StateError('entity agent.md fresh read has no ETag', { stringCode: 'unavailable', retryable: true });
+        let content = '';
+        if (response.status === 200) {
+            try {
+                content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(await response.arrayBuffer());
+            }
+            catch {
+                throw new ValidationError('entity agent.md must be valid UTF-8', { stringCode: 'invalid' });
+            }
+        }
+        const facts = {};
+        for (const [field, header] of [['ownership_status', 'X-AUN-Ownership-Status'], ['entity_status', 'X-AUN-Entity-Verification-Status'], ['owner_aid', 'X-AUN-Entity-Owner-AID'], ['entity_cert_fingerprint', 'X-AUN-Entity-Cert-Fingerprint']]) {
+            const value = headerValue(response.headers, header);
+            if (value)
+                facts[field] = value;
+        }
+        return { exists: response.status === 200, content, etag, ...facts };
+    }
+    async _entityCurrentContext(target, meta, uploading = false) {
+        const owner = String(meta.owner ?? '').trim().toLowerCase();
+        if (!this._entityOwnerResolver)
+            throw new StateError('entity owner resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+        const freshOwner = String(await this._entityOwnerResolver(target, String(meta.type))).trim().toLowerCase();
+        if (!freshOwner)
+            throw new StateError('entity current owner is unavailable', { stringCode: 'unavailable', retryable: true });
+        if (freshOwner !== owner)
+            throw new StateError('entity current owner changed', { stringCode: uploading ? 'forbidden' : 'conflict' });
+        if (!this._entityIdentityGetter)
+            throw new StateError('entity current certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+        const entity = await this._entityIdentityGetter(target, String(meta.type));
+        if (!entity.certFingerprint)
+            throw new StateError('entity current certificate is unavailable', { stringCode: 'unavailable', retryable: true });
+        if (meta.entity_cert_fingerprint !== entity.certFingerprint)
+            throw new StateError('entity agent.md certificate generation changed', { stringCode: 'conflict' });
+        return { type: meta.type, owner_aid: owner, entity_cert_fingerprint: entity.certFingerprint };
+    }
+    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' });
+        const context = await this._entityCurrentContext(target, meta, true);
+        if (signer.aid.toLowerCase() === owner)
+            await this._verifyEntityOwnerSigner(signer);
+        else if (signer.certFingerprint !== context.entity_cert_fingerprint)
+            throw new StateError('entity uploader certificate generation changed', { stringCode: 'conflict' });
+        return context;
+    }
+    async _entityDocumentSigner(target, content) {
+        const parsed = validateAgentMdDocument(content, { expectedAid: target, requireSignature: true });
+        const signerAid = parsed.signature.signer_aid ?? target;
+        let signer;
+        if (signerAid.toLowerCase() === target.toLowerCase()) {
+            if (!this._entityIdentityGetter)
+                throw new StateError('entity current certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+            signer = await this._entityIdentityGetter(target, String(parsed.frontmatter.type));
+        }
+        else {
+            if (!this._entitySignerResolver)
+                throw new StateError('entity owner signing certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+            signer = await this._entitySignerResolver(signerAid, parsed.signature.cert_fingerprint);
+        }
+        if (signer.aid.toLowerCase() !== signerAid.toLowerCase() || signer.certFingerprint !== parsed.signature.cert_fingerprint)
+            throw new StateError('entity signing certificate changed', { stringCode: 'conflict' });
+        return signer;
+    }
+    async _verifyEntityOwnerSigner(owner) {
+        if (!this._entitySignerResolver)
+            throw new StateError('entity owner signing certificate resolver is unavailable', { stringCode: 'unavailable', retryable: true });
+        const fresh = await this._entitySignerResolver(owner.aid, owner.certFingerprint);
+        if (fresh.aid.toLowerCase() !== owner.aid.toLowerCase() || fresh.certFingerprint !== owner.certFingerprint) {
+            throw new StateError('entity owner signing certificate changed', { stringCode: 'conflict' });
+        }
     }
     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);
+        let entity = false;
+        try {
+            entity = ['group', 'org'].includes(String(parseFileFrontmatter(parsed.payload).type));
+        }
+        catch { }
+        let frontmatter;
+        try {
+            frontmatter = validateAgentMdDocument(contentResult.content, { expectedAid: target, validateOwnership: false, ...(entity ? { requireSignature: true } : {}) }).frontmatter;
+        }
+        catch (error) {
+            if (entity)
+                throw new ValidationError(error instanceof Error ? error.message : String(error), { stringCode: 'invalid' });
+            throw error;
+        }
         const expectedFp = parsed.fields?.cert_fingerprint || parsed.fields?.public_key_fingerprint || null;
-        const peer = await this._resolvePeer(target, expectedFp);
+        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);
         if (!verified.ok)
             throw new AUNError(verified.error.message);
@@ -327,9 +720,30 @@ export class AgentMdManager {
         const statusText = String(signature.status ?? 'invalid');
         const reason = String(signature.reason ?? '').trim();
         if (statusText === 'invalid') {
-            throw new ClientSignatureError(`agent.md verification failed for ${target}${reason ? `: ${reason}` : ''}`);
+            throw new ClientSignatureError(`agent.md verification failed for ${target}${reason ? `: ${reason}` : ''}`, entity ? { stringCode: 'invalid' } : undefined);
+        }
+        let ownershipStatus;
+        if (entity)
+            ownershipStatus = 'not_applicable';
+        else {
+            try {
+                validateOwnershipFrontmatter(frontmatter, target);
+                const rawProof = (frontmatter.ownership_proof ?? {});
+                const subjectSignature = rawProof.subject_signature;
+                const ownerSignature = rawProof.owner_signature;
+                const release = frontmatter.ownership_release;
+                const subjectCertPem = subjectSignature ? (await this._resolvePeer(target, String(subjectSignature.cert_fingerprint), isJsonObject(subjectSignature.statement) ? Number(subjectSignature.statement.signed_at) : undefined)).certPem : undefined;
+                const ownerAid = String(ownerSignature ? frontmatter.owner : release?.statement && typeof release.statement === 'object' ? release.statement.owner_aid : '');
+                const ownerFingerprint = String(ownerSignature?.cert_fingerprint ?? release?.cert_fingerprint ?? '');
+                const ownerStatement = (ownerSignature ?? release)?.statement;
+                const ownerCertPem = ownerFingerprint ? (await this._resolvePeer(ownerAid, ownerFingerprint, isJsonObject(ownerStatement) ? Number(ownerStatement.signed_at) : undefined)).certPem : undefined;
+                ownershipStatus = await verifyOwnershipFrontmatterStatus(frontmatter, subjectCertPem, ownerCertPem);
+            }
+            catch {
+                ownershipStatus = 'invalid';
+            }
         }
-        const verification = { status: statusText };
+        const verification = { status: statusText, ownership_status: ownershipStatus };
         if (reason)
             verification.reason = reason;
         const localEtag = await AgentMdManager.contentEtag(contentResult.content);
@@ -690,14 +1104,14 @@ export class AgentMdManager {
     async _resolveGateway(aid) {
         return String(await this._gatewayResolver?.(aid) ?? '');
     }
-    async _resolvePeer(aid, certFingerprint) {
+    async _resolvePeer(aid, certFingerprint, signedAt) {
         const expectedFp = String(certFingerprint ?? '').trim().toLowerCase();
         const current = this._currentAid();
         if (current && current.aid.toLowerCase() === aid.toLowerCase()) {
             if (!expectedFp || await certMatchesFingerprint(current.certPem, expectedFp))
                 return current;
         }
-        const peer = await this._peerResolver?.(aid, expectedFp || null);
+        const peer = await this._peerResolver?.(aid, expectedFp || null, signedAt);
         if (!(peer instanceof AID)) {
             throw new StateError(`agent.md peer resolver did not return AID for ${aid}`);
         }
@@ -709,22 +1123,87 @@ export class AgentMdManager {
             throw new StateError('authenticate did not return access_token');
         return token;
     }
+    async _uploadAccessToken(aid, gatewayUrl) {
+        const resolver = this._uploadAccessTokenResolver ?? this._accessTokenResolver;
+        const token = String(await resolver?.(aid, gatewayUrl) ?? '').trim();
+        if (!token)
+            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 = '') {
+        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 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,
+            target_aid: target.toLowerCase(),
+            uploader_aid: owner.aid.toLowerCase(),
+            body_sha256: bodySha256,
+            ...(entityFingerprint ? { entity_cert_fingerprint: entityFingerprint } : {}),
+            timestamp,
+            nonce,
+            cert_fingerprint: owner.certFingerprint,
+            signature: signed.data.signature,
+        }));
+    }
     _url(aid, gatewayUrl) {
         return `${agentMdHttpScheme(gatewayUrl)}://${this._safeAid(aid)}/agent.md`;
     }
-    async _uploadHttp(aid, content, ownerOperationId) {
+    async _uploadHttp(aid, content, ownerAuthorization = '', condition) {
+        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 token = await this._accessToken(aid, gatewayUrl);
+        const authorization = String(ownerAuthorization ?? '').trim();
+        const entity = ['group', 'org'].includes(String(validateAgentMdDocument(content, { expectedAid: aid }).frontmatter.type));
         // 浏览器禁止覆盖 Host；动态 AID URL 由浏览器/Docker 的通配解析路由。
         const viaGatewayHost = this._uploadViaGatewayHost && nodeBuiltin('node:http') !== null;
         const headers = {
-            Authorization: `Bearer ${token}`,
             'Content-Type': 'text/markdown; charset=utf-8',
+            ...(!entity ? { '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 } : {}),
         };
-        const operationId = String(ownerOperationId ?? '').trim();
-        if (operationId)
-            headers['X-AUN-Owner-Operation-ID'] = operationId;
+        if (!authorization || entity) {
+            const token = await this._uploadAccessToken(aid, gatewayUrl);
+            headers.Authorization = `Bearer ${token}`;
+        }
         let url = this._url(aid, gatewayUrl);
         if (viaGatewayHost) {
             try {
@@ -765,6 +1244,10 @@ export class AgentMdManager {
         }
         if (!response.ok) {
             const message = (await response.text()).trim();
+            if (entity) {
+                const code = response.status === 409 || response.status === 412 ? 'conflict' : response.status === 401 || response.status === 403 ? 'forbidden' : response.status === 428 ? 'unsupported_protocol' : response.status >= 500 ? 'unavailable' : 'invalid';
+                throw new StateError(`upload agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`, { stringCode: code, retryable: code === 'unavailable' });
+            }
             throw new AUNError(`upload agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
         }
         const payload = await response.json();
@@ -806,9 +1289,15 @@ export class AgentMdManager {
         }
         if (!response.ok) {
             const message = (await response.text()).trim();
-            throw new AUNError(`download agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
+            throw new AUNError(`download agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`, response.status >= 500 ? { stringCode: 'unavailable', retryable: true } : undefined);
+        }
+        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' });
         }
-        const content = await response.text();
         return {
             content,
             etag: headerValue(response.headers, 'ETag') || cachedEtag,