@agentunion/fastaun-browser 0.5.17 → 0.5.19

package/dist/ownership-v21.js

@@ -0,0 +1,609 @@
+import { parseFileFrontmatter, validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-schema.js';
+import { buildAgentMdSignatureBlock, certFingerprint, isStrictBase64, parseAgentMdTailSignature, publicKeyFingerprint, publicKeyMatchesFingerprint, signBytes, verifySignatureWithCert } from './cert-utils.js';
+import { base64ToUint8 } from './crypto.js';
+import { StateError, ValidationError } from './errors.js';
+import { buildDefaultAgentMd, buildOwnershipAgentMdV21 } from './agent-md.js';
+const AID_RE = /^[a-z0-9_][a-z0-9_-]*(?:\.[a-z0-9_][a-z0-9_-]*)+$/;
+export const OWNERSHIP_UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const STATEMENT_KEYS = ['version', 'declaration_id', 'owner_aid', 'sub_aid', 'relation_version', 'declared_at'];
+export function ownershipAid(value, field) {
+    if (typeof value !== 'string' || !AID_RE.test(value))
+        throw new ValidationError(`${field} must be a complete lowercase AID`);
+    return value;
+}
+export function ownershipInteger(value, field, min = 1) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min)
+        throw new ValidationError(`${field} must be an integer in ${min}..9007199254740991`);
+    return value;
+}
+function mapping(value, field) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ValidationError(`${field} must be a mapping`);
+    return value;
+}
+function exactKeys(value, keys, field) {
+    if (Object.keys(value).some((key) => !keys.includes(key)) || keys.some((key) => !(key in value)))
+        throw new ValidationError(`${field} contains unknown or missing fields`);
+}
+export function validateOwnershipStatement(value) {
+    const statement = mapping(value, 'ownership.statement');
+    exactKeys(statement, STATEMENT_KEYS, 'ownership.statement');
+    if (statement.version !== 2)
+        throw new ValidationError('ownership.statement.version must be integer 2');
+    if (typeof statement.declaration_id !== 'string' || !OWNERSHIP_UUID_V4_RE.test(statement.declaration_id))
+        throw new ValidationError('declaration_id must be a lowercase UUIDv4');
+    ownershipAid(statement.owner_aid, 'owner_aid');
+    ownershipAid(statement.sub_aid, 'sub_aid');
+    ownershipInteger(statement.relation_version, 'relation_version');
+    ownershipInteger(statement.declared_at, 'declared_at');
+    return statement;
+}
+export function validateOwnershipAgentFrontmatter(meta, expectedAid) {
+    const aid = ownershipAid(meta.aid, 'aid');
+    if (expectedAid && expectedAid !== aid)
+        throw new ValidationError('agent.md AID mismatch');
+    if ('ownership_proof' in meta || 'ownership_release' in meta)
+        throw new ValidationError('legacy ownership fields cannot be used by Ownership 2.1');
+    if (meta.type === 'group' || meta.type === 'org') {
+        if ('ownership' in meta)
+            throw new ValidationError('group/org cannot declare Ownership 2.1', { stringCode: 'invalid' });
+        if ('owner' in meta)
+            ownershipAid(meta.owner, 'owner');
+        return undefined;
+    }
+    if (!('owner' in meta) && !('ownership' in meta))
+        return undefined;
+    if (meta.type === 'human')
+        throw new ValidationError('human cannot declare ownership');
+    const owner = ownershipAid(meta.owner, 'owner');
+    const ownership = mapping(meta.ownership, 'ownership');
+    exactKeys(ownership, ['statement'], 'agent.md ownership');
+    const statement = validateOwnershipStatement(ownership.statement);
+    if (statement.owner_aid !== owner || statement.sub_aid !== aid)
+        throw new ValidationError('agent.md ownership statement identity mismatch');
+    return statement;
+}
+function strictDerSignature(value) {
+    if (!isStrictBase64(value))
+        return false;
+    const bytes = base64ToUint8(value);
+    if (bytes.length < 8 || bytes.length > 72 || bytes[0] !== 0x30 || bytes[1] !== bytes.length - 2)
+        return false;
+    let offset = 2;
+    for (let i = 0; i < 2; i++) {
+        if (bytes[offset++] !== 0x02)
+            return false;
+        const length = bytes[offset++];
+        if (!length || length > 33 || offset + length > bytes.length || bytes[offset] & 0x80)
+            return false;
+        if (length > 1 && bytes[offset] === 0 && !(bytes[offset + 1] & 0x80))
+            return false;
+        if (bytes.subarray(offset, offset + length).every((byte) => byte === 0))
+            return false;
+        offset += length;
+    }
+    return offset === bytes.length;
+}
+function rawText(content) {
+    try {
+        const raw = typeof content === 'string' ? new TextEncoder().encode(content) : new Uint8Array(content);
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+        if (typeof content === 'string' && text !== content)
+            throw new Error('invalid Unicode');
+        return { raw, text };
+    }
+    catch {
+        throw new ValidationError('ownership file must be valid UTF-8');
+    }
+}
+export function parseOwnershipFile(content, role, context = {}) {
+    const { raw, text } = rawText(content);
+    const parsed = parseAgentMdTailSignature(text);
+    if (parsed.parseError)
+        throw new ValidationError(parsed.parseError);
+    if ((context.requireSignature ?? true) && !parsed.fields)
+        throw new ValidationError('ownership file signature is required');
+    if (new TextEncoder().encode(parsed.payload).length > 4096)
+        throw new ValidationError('ownership file payload exceeds 4096 bytes');
+    if (raw.length - new TextEncoder().encode(parsed.payload).length > 2048)
+        throw new ValidationError('ownership file signature exceeds 2048 bytes');
+    const fields = parsed.fields;
+    if (fields) {
+        if (!/^sha256:[0-9a-f]{64}$/.test(fields.cert_fingerprint) || fields.public_key_fingerprint !== undefined && !/^sha256:[0-9a-f]{64}$/.test(fields.public_key_fingerprint))
+            throw new ValidationError('ownership file fingerprint is invalid');
+        if (!/^[1-9][0-9]*$/.test(fields.timestamp) || !Number.isSafeInteger(Number(fields.timestamp)))
+            throw new ValidationError('ownership file timestamp must be a positive integer');
+        if (!strictDerSignature(fields.signature))
+            throw new ValidationError('ownership file signature must be strict Base64 DER');
+    }
+    let frontmatter;
+    let statement;
+    let action;
+    let transfer;
+    if (role === 'agent') {
+        frontmatter = validateAgentMdDocument(text, { expectedAid: context.expectedSubAid, validateOwnership: false, now: context.now, checkTimestamp: false }).frontmatter;
+        requireOwnershipApplicable(frontmatter.type);
+        statement = validateOwnershipAgentFrontmatter(frontmatter, context.expectedSubAid);
+        if (context.expectedOwnerAid && statement?.owner_aid !== context.expectedOwnerAid)
+            throw new ValidationError('agent.md owner mismatch');
+    }
+    else if (role === 'owner') {
+        frontmatter = parseFileFrontmatter(parsed.payload);
+        exactKeys(frontmatter, ['owner_aid', 'sub_aid', 'ownership'], 'owner.md');
+        const owner = ownershipAid(frontmatter.owner_aid, 'owner_aid'), sub = ownershipAid(frontmatter.sub_aid, 'sub_aid');
+        if (context.expectedOwnerAid && owner !== context.expectedOwnerAid || context.expectedSubAid && sub !== context.expectedSubAid)
+            throw new ValidationError('owner.md path identity mismatch');
+        const ownership = mapping(frontmatter.ownership, 'ownership');
+        action = ownership.action;
+        if (typeof action !== 'string' || !['declare', 'release', 'transfer_owner'].includes(action))
+            throw new ValidationError('owner.md action is invalid');
+        exactKeys(ownership, action === 'transfer_owner' ? ['statement', 'action', 'transfer'] : ['statement', 'action'], 'owner.md ownership');
+        statement = validateOwnershipStatement(ownership.statement);
+        if (statement.owner_aid !== owner || statement.sub_aid !== sub)
+            throw new ValidationError('owner.md ownership statement identity mismatch');
+        if (action === 'transfer_owner') {
+            const value = mapping(ownership.transfer, 'ownership.transfer');
+            exactKeys(value, ['new_owner_aid', 'target_relation_version', 'expires_at'], 'ownership.transfer');
+            if (ownershipAid(value.new_owner_aid, 'new_owner_aid') === owner)
+                throw new ValidationError('transfer target must differ from current owner');
+            if (ownershipInteger(value.target_relation_version, 'target_relation_version') !== statement.relation_version + 1)
+                throw new ValidationError('transfer target_relation_version mismatch');
+            ownershipInteger(value.expires_at, 'expires_at');
+            transfer = value;
+        }
+    }
+    else
+        throw new ValidationError('ownership file role is invalid');
+    return { raw, payload: parsed.payload, frontmatter, signature: fields, statement, action, transfer };
+}
+export async function verifyOwnershipFile(content, role, certificate, context = {}) {
+    const parsed = parseOwnershipFile(content, role, { ...context, requireSignature: true });
+    const fields = parsed.signature;
+    const signer = role === 'agent' ? String(parsed.frontmatter.aid) : String(parsed.frontmatter.owner_aid);
+    const sub = role === 'agent' ? signer : String(parsed.frontmatter.sub_aid);
+    const storagePath = role === 'agent' ? 'agent.md' : `sub_aids/${sub}/owner.md`;
+    if (context.expectedTargetAid && context.expectedTargetAid !== sub || context.authenticatedAid && context.authenticatedAid !== signer || context.certificateAid && context.certificateAid !== signer || context.resourcePath && context.resourcePath !== `${signer}:/${storagePath}` || context.storagePath && context.storagePath !== storagePath)
+        throw new ValidationError('ownership file resource or authenticated identity mismatch');
+    const now = Math.trunc(context.now ?? Date.now() / 1000);
+    if (Number(fields.timestamp) > now + 300)
+        throw new ValidationError('ownership file timestamp is too far in the future');
+    if (certificate.chain_valid === false || certificate.revoked === true || typeof certificate.state === 'string' && certificate.state !== 'active_signing')
+        throw new ValidationError('ownership signing certificate is not currently verified and active_signing', { stringCode: 'invalid' });
+    if (certificate.chain_valid !== true || certificate.state !== 'active_signing' || certificate.revoked !== false || certificate.revocation_checked !== true || !Number.isSafeInteger(certificate.observed_at) || certificate.observed_at <= 0 || certificate.observed_at > now + 5 || certificate.observed_at < now - 30)
+        throw new StateError('ownership certificate current status is unavailable', { stringCode: 'unavailable', retryable: true });
+    validateAgentMdCertificate(certificate.cert_pem, signer, Number(fields.timestamp), now);
+    if (await certFingerprint(certificate.cert_pem) !== fields.cert_fingerprint)
+        throw new ValidationError('ownership certificate fingerprint mismatch');
+    if (fields.public_key_fingerprint && !await publicKeyMatchesFingerprint(certificate.cert_pem, fields.public_key_fingerprint))
+        throw new ValidationError('ownership public key fingerprint mismatch');
+    if (!await verifySignatureWithCert(certificate.cert_pem, fields.signature, new TextEncoder().encode(parsed.payload)))
+        throw new ValidationError('ownership file signature verification failed');
+    return parsed;
+}
+export async function signOwnershipFile(identity, content, role, context = {}) {
+    if (!identity.isPrivateKeyValid() || !identity.privateKeyPem || !identity.isCertValid())
+        throw new StateError('ownership requires a loaded signing identity');
+    const parsed = parseOwnershipFile(content, role, { ...context, requireSignature: false });
+    if (parsed.signature)
+        throw new ValidationError('ownership file is already signed');
+    const signer = role === 'agent' ? parsed.frontmatter.aid : parsed.frontmatter.owner_aid;
+    if (signer !== identity.aid)
+        throw new ValidationError('ownership files must be signed by their own AID');
+    if (!parsed.payload.endsWith('\n') && !parsed.payload.endsWith('\r'))
+        throw new ValidationError('ownership payload must end with a newline before signature');
+    const now = Math.trunc(context.now ?? Date.now() / 1000);
+    validateAgentMdCertificate(identity.certPem, identity.aid, now, now);
+    const signature = await signBytes(identity.privateKeyPem, new TextEncoder().encode(parsed.payload));
+    return parsed.payload + buildAgentMdSignatureBlock(identity.certFingerprint, now, signature, await publicKeyFingerprint(identity.certPem), role === 'agent' ? 'AUN-SIGNATURE-AGENTMD-V2' : 'AUN-SIGNATURE-OWNERSHIP-V2');
+}
+export async function ownershipSha256(content) {
+    const bytes = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+    const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer);
+    return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+export function ownershipStatementsMatch(first, second) {
+    return first.version === second.version && first.owner_aid === second.owner_aid && first.sub_aid === second.sub_aid && first.relation_version === second.relation_version;
+}
+export class OwnershipStorageAdapter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    error(code, reason) { return new StateError(reason, { stringCode: code, retryable: code === 'unavailable' }); }
+    async request(method, params) {
+        try {
+            const result = await this.deps.call(method, params);
+            if (!result || typeof result !== 'object' || Array.isArray(result))
+                throw this.error('unavailable', 'Storage authoritative result unavailable');
+            return result;
+        }
+        catch (error) {
+            if (error instanceof StateError && error.stringCode)
+                throw error;
+            const code = error?.code;
+            throw this.error(code === -32009 ? 'conflict' : code === -32004 ? 'forbidden' : code === -32601 || code === -32602 ? 'unsupported_protocol' : 'unavailable', `Storage ownership request failed: ${String(error)}`);
+        }
+    }
+    metadata(value, ownerAid, path) {
+        const now = Math.trunc(this.deps.now?.() ?? Date.now() / 1000);
+        const observed = value.observed_at;
+        const service = `st.${ownerAid.slice(ownerAid.indexOf('.') + 1)}`;
+        if (Object.hasOwn(value, 'service_aid') && value.service_aid !== service || Object.hasOwn(value, 'authenticated_service_aid') && value.authenticated_service_aid !== service)
+            throw this.error('unavailable', 'Storage authoritative service identity unavailable');
+        if (value.consistency !== 'authoritative' || Object.hasOwn(value, 'recovery_ready') && value.recovery_ready !== true || value.owner_aid !== ownerAid || value.bucket !== 'default' || value.path !== path || typeof value.exists !== 'boolean' || typeof value.revision !== 'string' || !value.revision || !Number.isSafeInteger(observed) || observed < now - 30 || observed > now + 5 || observed <= 0)
+            throw this.error('unavailable', 'Storage authoritative namespace, revision or freshness unavailable');
+        if (value.exists && (typeof value.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(value.sha256) || typeof value.object_id !== 'string' || !value.object_id || !Number.isSafeInteger(value.version) || Number(value.version) <= 0))
+            throw this.error('unavailable', 'Storage authoritative object metadata unavailable');
+        return { owner_aid: ownerAid, bucket: 'default', path, exists: value.exists, revision: value.revision,
+            observed_at: observed, sha256: value.exists ? String(value.sha256) : '', content: '', authoritative: true,
+            service_aid: service, authenticated_service_aid: service };
+    }
+    async readFile(ownerAid, path) {
+        ownershipAid(ownerAid, 'owner_aid');
+        const began = Math.trunc(this.deps.now?.() ?? Date.now() / 1000);
+        const params = { owner_aid: ownerAid, bucket: 'default', object_key: path, consistency: 'authoritative' };
+        const beforeRaw = await this.request('storage.head_object', params);
+        const before = this.metadata(beforeRaw, ownerAid, path);
+        if (!before.exists)
+            return before;
+        const body = await this.request('storage.get_object', { ...params, expected_revision: before.revision });
+        const current = this.metadata(body, ownerAid, path);
+        if (!current.exists || current.revision !== before.revision || current.sha256 !== before.sha256 || body.object_id !== beforeRaw.object_id || body.version !== beforeRaw.version)
+            throw this.error('unavailable', 'Storage ownership body revision changed');
+        if (typeof body.content !== 'string')
+            throw this.error('unavailable', 'Storage ownership body is unavailable');
+        if (body.content !== '' && !isStrictBase64(body.content))
+            throw this.error('unavailable', 'Storage ownership body is not strict Base64');
+        const bytes = base64ToUint8(body.content);
+        if (await ownershipSha256(bytes) !== before.sha256)
+            throw this.error('unavailable', 'Storage ownership body digest mismatch');
+        let content;
+        try {
+            content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            throw this.error('invalid', 'Storage ownership file is not UTF-8');
+        }
+        const afterRaw = await this.request('storage.head_object', params);
+        const after = this.metadata(afterRaw, ownerAid, path);
+        if (!after.exists || after.revision !== before.revision || after.sha256 !== before.sha256 || afterRaw.object_id !== beforeRaw.object_id || afterRaw.version !== beforeRaw.version || Math.trunc(this.deps.now?.() ?? Date.now() / 1000) - began > 30)
+            throw this.error('unavailable', 'Storage ownership changed during authoritative read');
+        return { ...after, content };
+    }
+    async readOwnerMd(ownerAid, subAid) {
+        return await this.readFile(ownerAid, `sub_aids/${ownershipAid(subAid, 'sub_aid')}/owner.md`);
+    }
+    async writeOwnerMd(ownerAid, subAid, raw, expectedRevision) {
+        if (ownerAid !== this.deps.currentAid())
+            throw this.error('forbidden', 'only the authenticated owner may publish owner.md');
+        if (typeof expectedRevision !== 'string' || !expectedRevision)
+            throw this.error('invalid', 'ownership expected_revision is required');
+        const bytes = new TextEncoder().encode(raw);
+        let binary = '';
+        for (const byte of bytes)
+            binary += String.fromCharCode(byte);
+        await this.request('storage.put_object', { owner_aid: ownershipAid(ownerAid, 'owner_aid'), bucket: 'default', object_key: `sub_aids/${ownershipAid(subAid, 'sub_aid')}/owner.md`, content: btoa(binary), content_type: 'text/markdown', is_private: false, overwrite: true, expected_revision: expectedRevision });
+        return await this.readOwnerMd(ownerAid, subAid);
+    }
+    async deleteOwnerMd(ownerAid, subAid, expectedRevision) {
+        if (ownerAid !== this.deps.currentAid())
+            throw this.error('forbidden', 'only the authenticated owner may delete owner.md');
+        if (typeof expectedRevision !== 'string' || !expectedRevision)
+            throw this.error('invalid', 'ownership expected_revision is required');
+        const path = `sub_aids/${ownershipAid(subAid, 'sub_aid')}/owner.md`;
+        await this.request('storage.delete_object', { owner_aid: ownershipAid(ownerAid, 'owner_aid'), bucket: 'default', object_key: path, expected_revision: expectedRevision });
+        const after = this.metadata(await this.request('storage.head_object', { owner_aid: ownerAid, bucket: 'default', object_key: path, consistency: 'authoritative' }), ownerAid, path);
+        if (after.exists || after.revision === expectedRevision)
+            throw this.error('conflict', 'Storage ownership deletion could not be confirmed');
+    }
+}
+export function requireOwnershipApplicable(type) {
+    if (type === 'group' || type === 'org')
+        throw new StateError('group/org use their dedicated lifecycle ownership', { stringCode: 'not_applicable', retryable: false });
+}
+export class OwnershipFiles {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() { return Math.trunc(this.deps.now?.() ?? Date.now() / 1000); }
+    fresh(observedAt) {
+        const now = this.now();
+        if (!Number.isSafeInteger(observedAt) || observedAt <= 0 || observedAt < now - 30 || observedAt > now + 5)
+            throw new StateError('ownership authoritative material is unavailable or stale');
+    }
+    validateAgentSnapshot(snapshot, subAid) {
+        if (snapshot.protocol !== '2.1')
+            throw new StateError('NS ownership 2.1 protocol capability is unavailable', { stringCode: 'unsupported_protocol', retryable: true });
+        if (snapshot.sub_aid !== subAid || Object.hasOwn(snapshot, 'recovery_ready') && snapshot.recovery_ready !== true || !['locked', 'unlocked'].includes(snapshot.lock) || typeof snapshot.exists !== 'boolean' || !Number.isSafeInteger(snapshot.relation_version) || snapshot.relation_version < 0)
+            throw new StateError('NS ownership 2.1 authoritative metadata is unavailable', { stringCode: 'unavailable', retryable: true });
+        if (snapshot.exists && !snapshot.etag || !snapshot.exists && (snapshot.lock !== 'unlocked' || snapshot.relation_version !== 0))
+            throw new StateError('NS ownership document or ledger is unavailable');
+        this.fresh(snapshot.observed_at);
+    }
+    async validateOwnerSnapshot(snapshot, ownerAid, subAid) {
+        const expectedService = `st.${ownerAid.slice(ownerAid.indexOf('.') + 1)}`;
+        if (snapshot.error || snapshot.authoritative !== true || Object.hasOwn(snapshot, 'recovery_ready') && snapshot.recovery_ready !== true || snapshot.owner_aid !== ownerAid || snapshot.bucket !== 'default' || snapshot.path !== `sub_aids/${subAid}/owner.md` || snapshot.service_aid !== expectedService || snapshot.authenticated_service_aid !== expectedService || typeof snapshot.revision !== 'string' || !snapshot.revision || typeof snapshot.exists !== 'boolean')
+            throw new StateError('Storage authoritative ownership object is unavailable');
+        this.fresh(snapshot.observed_at);
+        if (snapshot.exists && (!/^[0-9a-f]{64}$/.test(snapshot.sha256) || await ownershipSha256(snapshot.content) !== snapshot.sha256))
+            throw new StateError('Storage ownership body and metadata differ', { stringCode: 'unavailable', retryable: true });
+    }
+    async readAgent(subAid) {
+        if (this.deps.currentAidType && subAid === this.deps.currentAid().aid)
+            requireOwnershipApplicable(this.deps.currentAidType());
+        const snapshot = await this.deps.readAgentMdFresh(ownershipAid(subAid, 'sub_aid'));
+        if (snapshot.exists && typeof snapshot.content === 'string')
+            requireOwnershipApplicable(parseFileFrontmatter(parseAgentMdTailSignature(snapshot.content).payload).type);
+        this.validateAgentSnapshot(snapshot, subAid);
+        return snapshot;
+    }
+    async readOwner(ownerAid, subAid) {
+        const snapshot = await this.deps.readOwnerMd(ownershipAid(ownerAid, 'owner_aid'), ownershipAid(subAid, 'sub_aid'));
+        await this.validateOwnerSnapshot(snapshot, ownerAid, subAid);
+        return snapshot;
+    }
+    async verify(content, role, subAid, ownerAid) {
+        if (role === 'agent') {
+            const meta = parseFileFrontmatter(parseAgentMdTailSignature(content).payload);
+            requireOwnershipApplicable(meta.type);
+            if ('ownership_proof' in meta || 'ownership_release' in meta || 'owner' in meta && !('ownership' in meta))
+                throw new StateError('legacy ownership requires explicit migration', { stringCode: 'unsupported_protocol', retryable: true });
+        }
+        const file = parseOwnershipFile(content, role, { expectedSubAid: subAid, expectedOwnerAid: role === 'owner' ? ownerAid : undefined, now: this.now() });
+        const signer = role === 'agent' ? subAid : ownerAid;
+        const certificate = await this.deps.resolveCertificate(signer, file.signature.cert_fingerprint, role === 'agent' && file.frontmatter.type === 'group' ? 'group_identity' : undefined);
+        return await verifyOwnershipFile(content, role, certificate, { expectedSubAid: subAid, expectedOwnerAid: role === 'owner' ? ownerAid : undefined, certificateAid: signer, now: this.now() });
+    }
+    async checkConsensus(subAid = this.deps.currentAid().aid, pendingTarget) {
+        const began = this.now();
+        const result = { status: 'unavailable', sub_aid: subAid, owner_aid: null, relation_version: 0, lock: 'unlocked', agent_md_etag: '', agent_md_sha256: '', owner_md_revision: '', owner_md_sha256: '' };
+        try {
+            const first = await this.readAgent(subAid);
+            Object.assign(result, { relation_version: first.relation_version, lock: first.lock, agent_md_etag: first.etag, agent_md_sha256: first.exists ? await ownershipSha256(first.content) : '' });
+            const released = first.lock === 'unlocked' && first.relation_version > 0;
+            const agent = !released && first.exists ? await this.verify(first.content, 'agent', subAid) : null;
+            if (first.lock === 'unlocked' && first.relation_version === 0 && agent?.statement)
+                throw new StateError('NS relation metadata does not match agent.md', { stringCode: 'unavailable', retryable: true });
+            const ownerAid = released ? undefined : agent?.statement?.owner_aid ?? pendingTarget?.owner_aid;
+            let owner = null;
+            let object = null;
+            if (ownerAid) {
+                object = await this.readOwner(ownerAid, subAid);
+                result.owner_md_revision = object.revision;
+                result.owner_md_sha256 = object.exists ? object.sha256 : '';
+                if (object.exists)
+                    owner = await this.verify(object.content, 'owner', subAid, ownerAid);
+            }
+            const last = await this.readAgent(subAid);
+            if (last.relation_version !== first.relation_version || last.etag !== first.etag || last.lock !== first.lock || last.exists !== first.exists || last.owner_aid !== first.owner_aid || first.exists && await ownershipSha256(last.content) !== result.agent_md_sha256)
+                throw new StateError('NS ownership changed during verification');
+            this.fresh(began);
+            this.fresh(first.observed_at);
+            if (object)
+                this.fresh(object.observed_at);
+            if (released) {
+                result.status = 'released';
+            }
+            else if (first.lock === 'locked') {
+                if (!agent?.statement || agent.statement.relation_version !== first.relation_version || first.owner_aid !== undefined && first.owner_aid !== agent.statement.owner_aid)
+                    throw new StateError('ownership current files do not match the NS lock', { stringCode: 'unavailable', retryable: true });
+                if (!owner)
+                    throw new StateError('NS has not confirmed owner object absence');
+                if (!owner.statement || !ownershipStatementsMatch(agent.statement, owner.statement))
+                    throw new ValidationError('ownership current files do not match the NS lock');
+                if (owner.action === 'release')
+                    throw new StateError('NS has not confirmed the current release');
+                result.status = 'consensus';
+                result.owner_aid = agent.statement.owner_aid;
+            }
+            else if (pendingTarget && owner?.action === 'declare' && owner.statement?.relation_version === pendingTarget.relation_version && pendingTarget.relation_version === first.relation_version + 1) {
+                result.status = 'single_sided';
+            }
+            else
+                result.status = 'unbound';
+        }
+        catch (error) {
+            result.status = error instanceof StateError && error.stringCode === 'not_applicable' ? 'not_applicable' : error instanceof ValidationError || error?.stringCode === 'invalid' ? 'invalid' : 'unavailable';
+            result.owner_aid = null;
+            result.code = error instanceof StateError && error.stringCode ? error.stringCode : result.status;
+            result.reason = error instanceof Error ? error.message : String(error);
+            result.retryable = result.status === 'unavailable';
+        }
+        return result;
+    }
+    local(aid) {
+        const identity = this.deps.currentAid();
+        if (identity.aid !== aid)
+            throw new ValidationError('ownership file requires its own authenticated identity');
+        return identity;
+    }
+    statement(ownerAid, subAid, version) {
+        return { version: 2, declaration_id: crypto.randomUUID(), owner_aid: ownerAid, sub_aid: subAid, relation_version: ownershipInteger(version, 'relation_version'), declared_at: this.now() };
+    }
+    async requireBase(task) {
+        const snapshot = await this.readAgent(task.sub_aid);
+        if (snapshot.relation_version !== task.base_relation_version || snapshot.lock !== (task.operation === 'bind' ? 'unlocked' : 'locked'))
+            throw new StateError('ownership relation version conflict', { stringCode: 'ownership_conflict', retryable: false });
+        if (!snapshot.exists)
+            throw new StateError('initial agent.md is not published', { stringCode: 'unavailable', retryable: true });
+        if (snapshot.exists) {
+            const file = task.operation === 'bind' && snapshot.relation_version > 0 ? parseOwnershipFile(snapshot.content, 'agent', { expectedSubAid: task.sub_aid }) : await this.verify(snapshot.content, 'agent', task.sub_aid);
+            if (snapshot.lock === 'unlocked' && snapshot.relation_version === 0 && file.statement)
+                throw new StateError('NS relation metadata does not match agent.md', { stringCode: 'unavailable', retryable: true });
+            if (task.operation !== 'bind' && file.statement?.owner_aid !== task.owner_aid || task.operation === 'bind' && file.statement && file.statement.relation_version >= snapshot.relation_version)
+                throw new StateError('ownership current owner mismatch', { stringCode: 'conflict', retryable: false });
+        }
+        return snapshot;
+    }
+    async verifyTransfer(task) {
+        await this.requireBase(task);
+        const object = await this.readOwner(task.owner_aid, task.sub_aid);
+        if (!object.exists)
+            throw new StateError('ownership transfer authorization is unavailable');
+        const file = await this.verify(object.content, 'owner', task.sub_aid, task.owner_aid);
+        if (file.action !== 'transfer_owner' || file.statement?.relation_version !== task.base_relation_version || !file.transfer || file.transfer.new_owner_aid !== task.new_owner_aid || file.transfer.target_relation_version !== task.target_relation_version)
+            throw new StateError('ownership transfer authorization target changed', { stringCode: 'conflict', retryable: false });
+        if (file.transfer.expires_at <= this.now())
+            throw new StateError('ownership transfer authorization expired', { stringCode: 'conflict', retryable: false });
+        if (task.authorization_sha256 !== undefined && task.authorization_sha256 !== object.sha256 || task.expires_at !== undefined && task.expires_at !== file.transfer.expires_at)
+            throw new StateError('ownership transfer authorization changed', { stringCode: 'conflict', retryable: false });
+        if (task.authorization_sha256 === undefined || task.expires_at === undefined) {
+            task.authorization_sha256 = object.sha256;
+            task.expires_at = file.transfer.expires_at;
+            await task.persist();
+        }
+        return file;
+    }
+    async publishOwner(task, key, action, ownerAid, version) {
+        const identity = this.local(ownerAid);
+        await this.readAgent(task.sub_aid);
+        const current = await this.readOwner(ownerAid, task.sub_aid);
+        let prepared = task.files[key];
+        if (!prepared) {
+            await this.requireBase(task);
+            if (action === 'transfer_owner')
+                task.expires_at = this.now() + 3600;
+            const ownership = { statement: this.statement(ownerAid, task.sub_aid, version), action,
+                ...(action === 'transfer_owner' ? { transfer: { new_owner_aid: task.new_owner_aid, target_relation_version: task.target_relation_version, expires_at: task.expires_at } } : {}) };
+            const payload = `---\nowner_aid: ${ownerAid}\nsub_aid: ${task.sub_aid}\nownership: ${JSON.stringify(ownership)}\n---\n`;
+            const raw = await signOwnershipFile(identity, payload, 'owner', { now: this.now() });
+            await this.verify(raw, 'owner', task.sub_aid, ownerAid);
+            prepared = { raw, sha256: await ownershipSha256(raw), condition: { expected_revision: current.revision } };
+            if (action === 'transfer_owner')
+                prepared.expires_at = task.expires_at;
+            task.files[key] = prepared;
+            await task.persist();
+        }
+        if (!prepared.condition || typeof prepared.condition.expected_revision !== 'string' || !prepared.condition.expected_revision)
+            throw new StateError('ownership original Storage revision is unavailable', { stringCode: 'ownership_conflict' });
+        if (current.exists && current.sha256 === prepared.sha256 && current.content === prepared.raw) {
+            if (prepared.published_revision !== undefined && prepared.published_revision !== current.revision)
+                throw new StateError('ownership published file revision changed', { stringCode: 'ownership_conflict' });
+            prepared.published_revision = current.revision;
+            await task.persist();
+            return prepared;
+        }
+        await this.requireBase(task);
+        if (current.revision !== prepared.condition.expected_revision)
+            throw new StateError('ownership Storage revision conflict', { stringCode: 'ownership_conflict' });
+        if (action === 'transfer_owner' && (!task.expires_at || task.expires_at <= this.now()))
+            throw new StateError('ownership transfer authorization expired', { stringCode: 'conflict', retryable: false });
+        await this.verify(prepared.raw, 'owner', task.sub_aid, ownerAid);
+        await task.guard?.();
+        await this.deps.writeOwnerMd(ownerAid, task.sub_aid, prepared.raw, prepared.condition.expected_revision);
+        const saved = await this.readOwner(ownerAid, task.sub_aid);
+        if (!saved.exists || saved.sha256 !== prepared.sha256 || saved.content !== prepared.raw)
+            throw new StateError('ownership published file could not be confirmed');
+        prepared.published_revision = saved.revision;
+        await task.persist();
+        return prepared;
+    }
+    async declareSubaid(task) {
+        const owner = task.operation === 'transfer' ? task.new_owner_aid : task.owner_aid;
+        if (task.operation === 'transfer')
+            await this.verifyTransfer(task);
+        return await this.publishOwner(task, 'owner', 'declare', owner, task.target_relation_version);
+    }
+    async revokeSubaid(task) {
+        return await this.publishOwner(task, 'release', 'release', task.owner_aid, task.base_relation_version);
+    }
+    async transferOwneraid(task) {
+        if (!task.new_owner_aid || task.new_owner_aid === task.owner_aid)
+            throw new ValidationError('ownership transfer target must differ from current owner');
+        return await this.publishOwner(task, 'transfer', 'transfer_owner', task.owner_aid, task.base_relation_version);
+    }
+    async publishAgent(task, cleanup) {
+        const identity = this.local(task.sub_aid), key = cleanup ? 'cleanup' : 'agent';
+        const current = await this.readAgent(task.sub_aid);
+        let prepared = task.files[key];
+        if (!prepared) {
+            if (cleanup) {
+                if (current.lock !== 'unlocked' || current.relation_version !== task.target_relation_version)
+                    throw new StateError('owner_locked or ownership cleanup version conflict');
+                const prior = current.exists ? parseOwnershipFile(current.content, 'agent', { expectedSubAid: task.sub_aid, now: this.now() }) : null;
+                if (prior?.statement && (prior.statement.owner_aid !== task.owner_aid || prior.statement.relation_version !== task.base_relation_version))
+                    throw new StateError('ownership cleanup historical authorization mismatch', { stringCode: 'conflict', retryable: false });
+            }
+            else {
+                await this.requireBase(task);
+                if (task.operation === 'transfer')
+                    await this.verifyTransfer(task);
+                const targetOwner = task.operation === 'transfer' ? task.new_owner_aid : task.owner_aid;
+                const target = await this.readOwner(targetOwner, task.sub_aid);
+                if (!target.exists)
+                    throw new StateError('ownership target declaration is unavailable');
+                const owner = await this.verify(target.content, 'owner', task.sub_aid, targetOwner);
+                if (owner.action === 'release' || owner.statement?.relation_version !== task.target_relation_version)
+                    throw new StateError('ownership target declaration mismatch', { stringCode: 'conflict', retryable: false });
+            }
+            const ownerAid = task.operation === 'transfer' ? task.new_owner_aid : task.owner_aid;
+            const payload = buildOwnershipAgentMdV21(current.exists ? current.content : buildDefaultAgentMd(task.sub_aid), cleanup ? undefined : this.statement(ownerAid, task.sub_aid, task.target_relation_version));
+            const raw = await signOwnershipFile(identity, payload, 'agent', { now: this.now() });
+            await this.verify(raw, 'agent', task.sub_aid);
+            prepared = { raw, sha256: await ownershipSha256(raw), condition: current.exists ? { if_match: current.etag } : { if_none_match: '*' } };
+            task.files[key] = prepared;
+            await task.persist();
+        }
+        if (!prepared.condition || !(typeof prepared.condition.if_match === 'string' && prepared.condition.if_match || prepared.condition.if_none_match === '*'))
+            throw new StateError('ownership original agent.md condition is unavailable', { stringCode: 'ownership_conflict' });
+        if (current.exists && await ownershipSha256(current.content) === prepared.sha256 && current.content === prepared.raw && current.relation_version === task.target_relation_version) {
+            if (prepared.published_etag !== undefined && prepared.published_etag !== current.etag)
+                throw new StateError('ownership published agent ETag changed', { stringCode: 'ownership_conflict' });
+            prepared.published_etag = current.etag;
+            await task.persist();
+            return prepared;
+        }
+        if (current.exists ? current.etag !== prepared.condition.if_match : prepared.condition.if_none_match !== '*')
+            throw new StateError('ownership agent.md condition conflict', { stringCode: 'ownership_conflict' });
+        if (cleanup) {
+            if (current.lock !== 'unlocked' || current.relation_version !== task.target_relation_version)
+                throw new StateError('owner_locked or ownership cleanup version conflict');
+        }
+        else {
+            await this.requireBase(task);
+            if (task.operation === 'transfer')
+                await this.verifyTransfer(task);
+        }
+        await this.verify(prepared.raw, 'agent', task.sub_aid);
+        await task.guard?.();
+        const saved = await this.deps.submitAgentMdRaw(task.sub_aid, prepared.raw, prepared.condition);
+        this.validateAgentSnapshot(saved, task.sub_aid);
+        if (!saved.exists || await ownershipSha256(saved.content) !== prepared.sha256 || saved.relation_version !== task.target_relation_version)
+            throw new StateError('NS ownership submitted file could not be confirmed');
+        prepared.published_etag = saved.etag;
+        await task.persist();
+        return prepared;
+    }
+    async declareOwneraid(task) { return await this.publishAgent(task, false); }
+    async revokeOwneraid(task) { return await this.publishAgent(task, true); }
+    async cleanupOwnerFile(task) {
+        this.local(task.owner_aid);
+        await this.readAgent(task.sub_aid);
+        const prepared = task.files[task.operation === 'release' ? 'release' : 'transfer'];
+        if (!prepared?.published_revision || prepared.cleaned)
+            return;
+        const consensus = await this.checkConsensus(task.sub_aid);
+        if (consensus.status === 'not_applicable')
+            throw new StateError(consensus.reason || 'group/org use their dedicated lifecycle ownership', { stringCode: 'not_applicable', retryable: false });
+        if (consensus.status === 'invalid' || consensus.status === 'unavailable')
+            throw new StateError(consensus.reason || 'ownership cleanup verification failed', { stringCode: consensus.status, retryable: consensus.status === 'unavailable' });
+        if (consensus.relation_version !== task.target_relation_version || (task.operation === 'release' ? consensus.status !== 'released' : consensus.status !== 'consensus' || consensus.owner_aid !== task.new_owner_aid))
+            throw new StateError('ownership cleanup relation is not confirmed', { stringCode: 'conflict', retryable: false });
+        const object = await this.readOwner(task.owner_aid, task.sub_aid);
+        if (!object.exists) {
+            prepared.cleaned = true;
+            await task.persist();
+            return;
+        }
+        if (object.revision !== prepared.published_revision || object.sha256 !== prepared.sha256)
+            throw new StateError('ownership cleanup revision conflict');
+        if (!this.deps.deleteOwnerMd)
+            throw new StateError('ownership conditional delete unsupported');
+        await task.guard?.();
+        await this.deps.deleteOwnerMd(task.owner_aid, task.sub_aid, prepared.published_revision);
+        prepared.cleaned = true;
+        await task.persist();
+    }
+}
+//# sourceMappingURL=ownership-v21.js.map