@agentunion/fastaun 0.5.20 → 0.5.22

package/dist/agent-md.js

@@ -20,9 +20,6 @@ function relationshipFields(meta) {
 function legacyRelationship(meta) {
     if (['group', 'org'].includes(String(meta.type)))
         return undefined;
-    const statement = meta.ownership?.statement;
-    if (statement && typeof statement === 'object' && Object.hasOwn(statement, 'relation_version'))
-        return undefined;
     const fields = relationshipFields(meta);
     return Object.keys(fields).length ? fields : undefined;
 }
@@ -35,7 +32,7 @@ export function buildOwnershipAgentMd(content, owner, proof) {
 }
 export 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);
+    const match = /^\ufeff?---(?:\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 });
@@ -51,7 +48,7 @@ export function updateOwnershipAgentMd(content, fields) {
     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]}`;
+    const updated = `${payload.startsWith('\ufeff') ? '\ufeff' : ''}---\n${yamlText.endsWith('\n') ? yamlText : `${yamlText}\n`}---${match[2]}`;
     validateAgentMdDocument(updated, { expectedAid: String(frontmatter.aid ?? '') });
     return updated;
 }
@@ -366,7 +363,7 @@ export class AgentMdManager {
         });
         this._cache.delete(aid);
     }
-    async upload(content) {
+    async upload(content, originalCondition) {
         const target = this._ownerAid();
         if (!target)
             throw new ValidationError('uploadAgentMd requires local AID');
@@ -382,7 +379,7 @@ export class AgentMdManager {
             return await this.uploadAs(target, rawContent, current);
         if (parseAgentMdTailSignature(rawContent).signatures.length > 1) {
             await this._verifyDocument(rawContent, target, current, true, true);
-            return await this._uploadPrepared(target, rawContent, current);
+            return await this._uploadPrepared(target, rawContent, current, originalCondition);
         }
         const signed = current.signAgentMd(rawContent);
         if (!signed.ok || !signed.data) {
@@ -391,15 +388,40 @@ export class AgentMdManager {
         }
         const signedContent = signed.data.signed;
         verifyAgentMdBodyUpdate(signedContent, current.certPem, target);
-        return await this._uploadPrepared(target, signedContent, current);
+        return await this._uploadPrepared(target, signedContent, current, originalCondition);
+    }
+    async readAgentMdFresh(aid) {
+        const target = this.safeAid(aid), gateway = await this._resolveGateway(target);
+        const response = await requestText(this._url(target, gateway, this._uploadViaGatewayHost), {
+            method: 'GET', verifySsl: this._verifySsl,
+            headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache', ...(this._uploadViaGatewayHost ? { Host: target } : {}) },
+            timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true,
+        });
+        if (response.status === 404)
+            return { exists: false, content: '', etag: '' };
+        if (response.status !== 200)
+            throw ownershipFailure('unavailable', `agent.md fresh read failed: HTTP ${response.status}`, true);
+        const etag = headerValue(response.headers, 'ETag');
+        if (!etag)
+            throw ownershipFailure('unavailable', 'agent.md fresh read has no ETag', true);
+        return { exists: true, content: response.text, etag };
     }
     async readOwnershipFresh(aid) {
         const target = this.safeAid(aid);
         const response = await this._ownershipRequest(target, 'GET');
+        if ([200, 400, 404].includes(response.status) && headerValue(response.headers, 'X-AUN-Ownership-Status') === 'not_applicable')
+            throw ownershipFailure('not_applicable', 'group/org uses its lifecycle owner relationship');
+        if (response.status === 400) {
+            let value;
+            try {
+                value = JSON.parse(response.text);
+            }
+            catch { }
+            if (isJsonObject(value) && value.error === 'invalid')
+                throw ownershipFailure('invalid', 'NS rejected the current agent.md: HTTP 400');
+        }
         if (response.status !== 200 && response.status !== 404)
             throw ownershipFailure('unavailable', `NS fresh read failed: HTTP ${response.status}`, true);
-        if (headerValue(response.headers, 'X-AUN-Ownership-Status') === 'not_applicable')
-            throw ownershipFailure('not_applicable', 'group/org uses its lifecycle owner relationship');
         let type;
         if (response.status === 200) {
             try {
@@ -417,9 +439,10 @@ export class AgentMdManager {
         const etag = headerValue(response.headers, 'ETag');
         if (!/^(?:0|[1-9][0-9]*)$/.test(version) || !Number.isSafeInteger(Number(version)) || !['locked', 'unlocked'].includes(lock) || response.status === 200 && !etag || response.status === 404 && (version !== '0' || lock !== 'unlocked'))
             throw ownershipFailure('unavailable', 'NS fresh metadata is incomplete', true);
-        return { sub_aid: target, exists: response.status === 200, content: response.status === 200 ? response.text : '', etag, protocol, relation_version: Number(version), lock: lock, observed_at: Math.floor(Date.now() / 1000) };
+        const ownershipStatus = headerValue(response.headers, 'X-AUN-Ownership-Status');
+        return { sub_aid: target, exists: response.status === 200, content: response.status === 200 ? response.text : '', etag, protocol, relation_version: Number(version), lock: lock, stage_supported: headerValue(response.headers, 'X-AUN-Ownership-Stage') === '1', ...(ownershipStatus ? { ownership_status: ownershipStatus } : {}), ...(ownershipStatus === 'pending' ? { pending: true } : {}), observed_at: Math.floor(Date.now() / 1000) };
     }
-    async submitOwnershipRaw(aid, raw, condition) {
+    async submitOwnershipRaw(aid, raw, condition, assertActive, stage) {
         const target = this.safeAid(aid), current = this._currentAid();
         if (!current?.isPrivateKeyValid() || current.aid !== target || this._ownerAid() !== target)
             throw ownershipFailure('forbidden', 'raw agent.md submission requires its own authenticated identity');
@@ -427,7 +450,9 @@ export class AgentMdManager {
             throw new ValidationError('raw agent.md requires one original condition');
         parseOwnershipFile(raw, 'agent', { expectedSubAid: target });
         verifyAgentMdUpload(raw, current.certPem, target);
-        const response = await this._ownershipRequest(target, 'PUT', raw, condition);
+        if (stage && (await this.readOwnershipFresh(target)).stage_supported !== true)
+            throw ownershipFailure('unsupported_protocol', 'NS does not support Ownership Stage', true);
+        const response = stage ? await this._ownershipRequest(target, 'PUT', raw, condition, false, assertActive, true) : await this._ownershipRequest(target, 'PUT', raw, condition, false, assertActive);
         if (response.status === 409 || response.status === 412)
             throw ownershipFailure('conflict', `NS original condition failed: HTTP ${response.status}`);
         if (response.status === 428)
@@ -438,16 +463,19 @@ export class AgentMdManager {
             throw ownershipFailure('invalid', 'NS rejected the submitted agent.md: HTTP 400');
         if (response.status < 200 || response.status >= 300)
             throw ownershipFailure('unavailable', `NS raw submission failed: HTTP ${response.status}`, true);
+        if (stage && (headerValue(response.headers, 'X-AUN-Ownership-Stage') !== '1' || headerValue(response.headers, 'X-AUN-Ownership-Lock') !== 'unlocked' || headerValue(response.headers, 'X-AUN-Ownership-Status') !== 'pending'))
+            throw ownershipFailure('unsupported_protocol', 'NS did not confirm Ownership Stage', true);
         const fresh = await this.readOwnershipFresh(target);
         if (fresh.content !== raw)
             throw ownershipFailure('unavailable', 'NS raw submission cannot be confirmed from the current document', true);
-        this.saveRecord(target, { content: raw, local_etag: AgentMdManager.contentEtag(raw), remote_etag: fresh.etag, fetched_at: Date.now(), checked_at: Date.now(), remote_status: 'found' });
         return fresh;
     }
-    async _ownershipRequest(target, method, raw, condition, legacyRead = false) {
+    async _ownershipRequest(target, method, raw, condition, legacyRead = false, assertActive, stage) {
         const gatewayUrl = await this._resolveGateway(target);
         const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache', ...(!legacyRead ? { 'X-AUN-Ownership-Check': '1' } : {}) };
         if (method === 'PUT') {
+            if (stage)
+                headers['X-AUN-Ownership-Stage'] = '1';
             headers['Content-Type'] = 'text/markdown; charset=utf-8';
             headers.Authorization = `Bearer ${await this._uploadAccessToken(target, gatewayUrl)}`;
             if (condition?.if_match)
@@ -458,11 +486,13 @@ export class AgentMdManager {
         const viaGateway = this._uploadViaGatewayHost;
         if (viaGateway)
             headers.Host = target;
-        const request = (url) => requestText(url, { method, verifySsl: this._verifySsl, headers, body: raw, timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true });
-        let response = await request(this._url(target, gatewayUrl, viaGateway));
+        const request = (url) => { if (method === 'PUT')
+            assertActive?.(); return requestText(url, { method, verifySsl: this._verifySsl, headers, body: raw, timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true }); };
+        const primary = this._url(target, gatewayUrl, viaGateway);
+        let response = await request(primary);
         if (response.status === 404 && !headerValue(response.headers, 'X-AUN-Ownership-Protocol') && headerValue(response.headers, 'X-AUN-Ownership-Status') !== 'not_applicable') {
             const fallback = nameServiceAgentMdUrl(target, gatewayUrl);
-            if (fallback && fallback !== this._url(target, gatewayUrl, viaGateway)) {
+            if (fallback && fallback !== primary) {
                 headers.Host = target;
                 response = await request(fallback);
             }
@@ -522,6 +552,27 @@ export class AgentMdManager {
         try {
             if (pending.relation?.legacy === true)
                 return await this._resumeLegacyBodyUpload(aid, pending, signer ?? this._currentAid());
+            if (legacyRelationship(meta) && pending.relation && Object.keys(pending.relation).length === 4 && ['relation_version', 'lock', 'owner_aid', 'statement'].every((field) => Object.hasOwn(pending.relation, field))) {
+                const relation = pending.relation, statement = parseOwnershipFile(pending.content, 'agent', { expectedSubAid: aid }).statement;
+                if (!statement || !isDeepStrictEqual(statement, relation.statement) || statement.relation_version !== relation.relation_version || statement.owner_aid !== relation.owner_aid || !['locked', 'unlocked'].includes(String(relation.lock)) || pending.content_etag !== AgentMdManager.contentEtag(pending.content))
+                    throw ownershipFailure('persistence_unavailable', 'pending original relationship context is corrupt');
+                const identity = signer ?? this._currentAid();
+                if (!identity || identity.aid !== aid || this._currentAid()?.aid !== aid || this._ownerAid() !== aid)
+                    throw ownershipFailure('forbidden', 'body recovery requires its current subject identity');
+                await this._verifyDocument(pending.content, aid, identity, true, true);
+                const remote = await this.readAgentMdFresh(aid);
+                if (!remote.exists || !isDeepStrictEqual(legacyRelationship(meta), legacyRelationship(validateAgentMdReadDocument(remote.content, { expectedAid: aid }).frontmatter)))
+                    throw ownershipFailure('conflict', 'pending agent.md relationship material changed');
+                if (remote.etag === pending.content_etag && remote.content === pending.content) {
+                    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: '' });
+                    this._clearConfirmedDraft(aid, pending.content);
+                    return true;
+                }
+                if (!condition.if_match || remote.etag !== condition.if_match)
+                    throw ownershipFailure('conflict', 'pending agent.md original document condition changed');
+                await this._uploadPrepared(aid, pending.content, identity, condition);
+                return true;
+            }
             if (legacyRelationship(meta))
                 throw ownershipFailure('unsupported_protocol', 'legacy ownership pending agent.md requires its original relationship snapshot');
             if (['group', 'org'].includes(String(meta.type))) {
@@ -556,28 +607,15 @@ export class AgentMdManager {
             if (multipleSignatures) {
                 if (!identity)
                     throw new StateError('pending agent.md requires a signer identity');
-                await this._verifyDocument(pending.content, aid, identity, true);
-            }
-            const remote = await this.readOwnershipFresh(aid);
-            const fail = (code, reason, retryable = false) => ownershipFailure(code, reason, 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 || first !== null && second !== null && typeof first === 'object' && typeof second === 'object' && ['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');
-                }
+                await this._verifyDocument(pending.content, aid, identity, true, true);
             }
-            if (!relation && (remote.relation_version !== 0 || remote.lock !== 'unlocked'))
-                throw fail('unavailable', 'pending agent.md cannot overwrite relationship history', true);
+            if (pending.content_etag !== AgentMdManager.contentEtag(pending.content))
+                throw ownershipFailure('persistence_unavailable', 'pending agent.md original bytes are corrupt');
+            if (!identity)
+                throw new StateError('pending agent.md requires a signer identity');
+            if (!multipleSignatures)
+                verifyAgentMdBodyUpdate(pending.content, identity.certPem, aid);
+            const remote = await this.readAgentMdFresh(aid);
             if (remote.exists && remote.etag === pending.content_etag && remote.content === pending.content) {
                 const saved = 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)
@@ -587,10 +625,8 @@ export class AgentMdManager {
             }
             if (condition.if_match && (!remote.exists || remote.etag !== condition.if_match) || condition.if_none_match === '*' && remote.exists)
                 throw ownershipFailure('conflict', 'pending agent.md original document condition changed');
-            if (!identity)
-                throw new StateError('pending agent.md requires a signer identity');
-            if (!multipleSignatures)
-                verifyAgentMdUpload(pending.content, identity.certPem, aid);
+            if (remote.exists && legacyRelationship(validateAgentMdReadDocument(remote.content, { expectedAid: aid }).frontmatter))
+                throw ownershipFailure('conflict', 'legacy relationship material cannot be removed or replaced');
             await this._uploadPrepared(aid, pending.content, identity, condition);
             return true;
         }
@@ -603,34 +639,27 @@ export class AgentMdManager {
         const meta = validateAgentMdDocument(signedContent, { expectedAid: target, validateOwnership: false }).frontmatter;
         const entity = ['group', 'org'].includes(String(meta.type));
         const legacy = legacyRelationship(meta);
-        const draftStrict = !originalCondition;
+        const draftStrict = !originalCondition || !this._pendingUpload(target, true);
         if (legacy && (signer.aid !== target || this._currentAid()?.aid !== target || this._ownerAid() !== target))
             throw ownershipFailure('forbidden', 'legacy relationship body updates require current subject identity');
-        if (legacy && Object.hasOwn(meta, 'owner'))
-            validateOwnershipFrontmatter({ aid: meta.aid, type: meta.type, owner: meta.owner }, target);
-        if (!entity && !legacy)
-            parseOwnershipFile(signedContent, 'agent', { expectedSubAid: target });
         if (draftStrict && this._saveRecord(target, { local_draft_content: signedContent }, true).local_draft_content !== signedContent)
             throw new StateError('agent.md local draft persistence failed');
         const entityContext = entity ? await this._entityContext(target, meta, signer) : undefined;
         let condition = originalCondition;
         let relation = entityContext ?? (this._pendingUpload(target, draftStrict))?.relation;
         if (!condition) {
-            const fresh = entity ? await this._readEntityFresh(target) : legacy ? await this._readLegacyBodyBase(target) : await this.readOwnershipFresh(target);
+            const fresh = entity ? await this._readEntityFresh(target) : legacy ? await this._readLegacyBodyBase(target) : await this.readAgentMdFresh(target);
             condition = fresh.exists ? { if_match: fresh.etag } : { if_none_match: '*' };
             if (!entity) {
                 if (legacy) {
                     if (!fresh.exists || !fresh.etag || !isDeepStrictEqual(legacy, legacyRelationship(validateAgentMdReadDocument(fresh.content, { expectedAid: target }).frontmatter)))
-                        throw ownershipFailure('unsupported_protocol', 'legacy relationship material must remain unchanged');
+                        throw ownershipFailure('conflict', 'legacy relationship material must remain unchanged');
                     relation = { legacy: true, base_content: fresh.content, base_content_etag: AgentMdManager.contentEtag(fresh.content), base_etag: fresh.etag, fields: legacy };
                 }
                 else {
                     if (fresh.exists && legacyRelationship(validateAgentMdReadDocument(fresh.content, { expectedAid: target }).frontmatter))
-                        throw ownershipFailure('unsupported_protocol', 'legacy relationship material cannot be removed or replaced');
-                    const authority = fresh;
-                    const candidate = parseOwnershipFile(signedContent, '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 };
+                        throw ownershipFailure('conflict', 'legacy relationship material cannot be removed or replaced');
+                    relation = undefined;
                 }
             }
         }
@@ -676,16 +705,10 @@ export class AgentMdManager {
         return parsed;
     }
     async _readLegacyBodyBase(target) {
-        const response = await this._ownershipRequest(target, 'GET', undefined, undefined, true);
-        if (response.status === 404)
-            return { exists: false, content: '', etag: '' };
-        if (response.status !== 200)
-            throw ownershipFailure('unavailable', `legacy agent.md fresh read failed: HTTP ${response.status}`, true);
-        await this._verifyLegacyBodyContent(target, response.text);
-        const etag = headerValue(response.headers, 'ETag');
-        if (!etag)
-            throw ownershipFailure('unavailable', 'legacy agent.md original ETag is missing', true);
-        return { exists: true, content: response.text, etag };
+        const response = await this.readAgentMdFresh(target);
+        if (response.exists)
+            await this._verifyLegacyBodyContent(target, response.content);
+        return response;
     }
     async _resumeLegacyBodyUpload(target, pending, identity) {
         const relation = pending.relation;
@@ -771,7 +794,8 @@ export class AgentMdManager {
     async _verifyDocument(content, target, identity, current = false, bodyUpdate = false) {
         const certificates = new Map();
         const parsed = parseAgentMdTailSignature(content, !current);
-        const meta = validateAgentMdReadDocument(content).frontmatter;
+        const meta = validateAgentMdReadDocument(content, { expectedAid: target }).frontmatter;
+        const historicalEntityOwner = !current && ['group', 'org'].includes(String(meta.type)) && parsed.signatures.length === 1 && parsed.fields?.signer_aid !== undefined && parsed.fields.signer_aid === meta.owner && parsed.fields.signer_aid !== meta.aid;
         const readCompatibility = !current && (!['group', 'org'].includes(String(meta.type)) || meta.type === 'group' && !Object.hasOwn(meta, 'entity_cert_fingerprint') && parsed.signatures.length === 1 && (parsed.fields?.signer_aid === undefined || parsed.fields.signer_aid === meta.aid));
         for (const item of parsed.signatures.slice(1)) {
             const fields = item.fields;
@@ -781,7 +805,7 @@ export class AgentMdManager {
         const resolver = (aid, fingerprint) => certificates.get(`${aid};${fingerprint}`);
         if (current)
             (bodyUpdate ? verifyAgentMdBodyUpdate : verifyAgentMdUpload)(content, identity.certPem, target, undefined, resolver);
-        const result = verifyDocument(content, { expectedAid: target, primaryCertPem: identity.certPem, requireCurrentValidity: current, readCompatibility, certificateResolver: resolver });
+        const result = verifyDocument(content, { expectedAid: historicalEntityOwner ? String(meta.owner) : target, primaryCertPem: identity.certPem, requireCurrentValidity: current, readCompatibility, certificateResolver: resolver });
         if (result.status === 'invalid')
             throw ownershipFailure('invalid', result.reason ?? 'document signature verification failed');
         return result;
@@ -845,7 +869,6 @@ export class AgentMdManager {
         const uploadHeaders = {
             'X-AUN-Signature-Format': 'multi-v1',
             'Content-Type': 'text/markdown; charset=utf-8',
-            ...(!entity && !legacyRelationship(meta) ? { 'X-AUN-Ownership-Check': '1' } : {}),
             ...(condition.if_match ? { 'If-Match': condition.if_match } : { 'If-None-Match': '*' }),
             ...(this._uploadViaGatewayHost ? { Host: target } : {}),
             ...(authorization && !entity ? { 'X-AUN-AgentMD-Owner-Authorization': authorization } : {}),
@@ -1296,6 +1319,7 @@ export class AgentMdManager {
         return {
             aid: target,
             content,
+            frontmatter,
             verification,
             signature,
             cert_pem: peer.certPem,