@agentunion/fastaun 0.5.18 → 0.5.20

package/dist/ownership-v21.js

@@ -0,0 +1,712 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { updateOwnershipAgentMd } from './agent-md.js';
+import { parseFileFrontmatter, validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-schema.js';
+import { certFingerprint, isStrictBase64, parseAgentMdTailSignature, publicKeyMatchesFingerprint, signDocument, verifyDocument } from './cert-utils.js';
+import { StateError, ValidationError } from './errors.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 = Buffer.from(value, 'base64');
+    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?.signer_aid !== undefined)
+        throw new ValidationError('ownership main signature contains unknown signer_aid');
+    for (const item of parsed.signatures) {
+        const fields = item.fields;
+        if (!/^sha256:[0-9a-f]{64}$/.test(fields.cert_fingerprint) || 'public_key_fingerprint' in fields && !/^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(parsed.payload, { expectedAid: context.expectedSubAid, validateOwnership: false, now: context.now }).frontmatter;
+        requireOwnershipApplicable(frontmatter.type);
+        statement = validateOwnershipAgentFrontmatter(frontmatter, context.expectedSubAid);
+        if (context.expectedOwnerAid && statement && 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 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' ? String(parsed.frontmatter.aid) : String(parsed.frontmatter.sub_aid);
+    const path = 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)
+        throw new ValidationError('ownership target, authenticated AID or certificate AID mismatch');
+    if (context.resourcePath && context.resourcePath !== `${signer}:/${path}` || context.storagePath && context.storagePath !== path)
+        throw new ValidationError('ownership resource path 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.revoked !== false || certificate.revocation_checked !== true || certificate.state !== 'active_signing' || !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 });
+    if (typeof certificate.cert_pem !== 'string' || !certificate.cert_pem.trim())
+        throw ownershipFailure('unavailable', 'ownership signing certificate is missing', true);
+    try {
+        validateAgentMdCertificate(certificate.cert_pem, signer, Number(fields.timestamp), { now, requireCurrentValidity: true });
+    }
+    catch (error) {
+        if (error instanceof ValidationError)
+            throw error;
+        throw new ValidationError('ownership signing certificate PEM is invalid', { stringCode: 'invalid' });
+    }
+    if (certFingerprint(certificate.cert_pem) !== fields.cert_fingerprint)
+        throw new ValidationError('ownership certificate fingerprint mismatch');
+    if ('public_key_fingerprint' in fields && !publicKeyMatchesFingerprint(certificate.cert_pem, fields.public_key_fingerprint))
+        throw new ValidationError('ownership public key fingerprint mismatch');
+    const additional = new Map();
+    for (const item of parseAgentMdTailSignature(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(parsed.raw)).signatures.slice(1)) {
+        const fields = item.fields, extra = context.certificateResolver?.(fields.signer_aid, fields.cert_fingerprint, Number(fields.timestamp));
+        if (extra && (extra.chain_valid === false || extra.revoked === true || typeof extra.state === 'string' && extra.state !== 'active_signing'))
+            throw new ValidationError('ownership additional signing certificate is not currently verified and active_signing', { stringCode: 'invalid' });
+        if (!extra || extra.chain_valid !== true || extra.revoked !== false || extra.revocation_checked !== true || extra.state !== 'active_signing' || !Number.isSafeInteger(extra.observed_at) || extra.observed_at <= 0 || extra.observed_at > now + 5 || extra.observed_at < now - 30 || !extra.cert_pem?.trim())
+            throw new StateError('ownership additional certificate current status is unavailable', { stringCode: 'unavailable', retryable: true });
+        additional.set(`${fields.signer_aid};${fields.cert_fingerprint}`, extra.cert_pem);
+    }
+    const verified = verifyDocument(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(parsed.raw), { expectedAid: signer, primaryCertPem: certificate.cert_pem, requireCurrentValidity: true, now, certificateResolver: (aid, fingerprint) => additional.get(`${aid};${fingerprint}`) });
+    if (!verified.valid)
+        throw new ValidationError(verified.reason ?? 'ownership file signature verification failed');
+    return parsed;
+}
+export 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 });
+    return signDocument(identity, parsed.payload, { timestamp: now, tag: role === 'agent' ? 'AGENTMD-V2' : 'OWNERSHIP-V2' }).signed;
+}
+export function ownershipSha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function ownershipFailure(code, reason, retryable = false) {
+    return new StateError(`${code}: ${reason}`, { stringCode: code, retryable });
+}
+export function requireOwnershipApplicable(type) {
+    if (type === 'group' || type === 'org')
+        throw ownershipFailure('not_applicable', 'group/org use their dedicated lifecycle ownership');
+}
+export class OwnershipFiles {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async checkConsensus(subAid, target) {
+        ownershipAid(subAid, 'sub_aid');
+        const began = this.deps.now();
+        const result = { status: 'unavailable', sub_aid: subAid, owner_aid: null, relation_version: 0, lock: 'unlocked', agent_md_etag: '', agent_md_sha256: '', owner_md_sha256: '' };
+        try {
+            const before = await this.readAgent(subAid);
+            Object.assign(result, { relation_version: before.relation_version, lock: before.lock, agent_md_etag: before.etag, agent_md_sha256: before.exists ? ownershipSha256(before.content) : '' });
+            const agent = before.exists ? await this.verifyFile(before.content, 'agent', subAid) : undefined;
+            const statement = agent?.statement;
+            if (before.relation_version !== (statement?.relation_version ?? 0))
+                throw ownershipFailure('unavailable', 'NS relation metadata does not match agent.md', true);
+            if (before.lock === 'locked' && (!statement || statement.relation_version !== before.relation_version))
+                throw ownershipFailure('unavailable', 'NS locked relation does not match agent.md', true);
+            const currentOwner = before.lock === 'locked' ? statement.owner_aid : null;
+            if (before.owner_aid !== undefined && before.owner_aid !== currentOwner)
+                throw ownershipFailure('unavailable', 'NS owner metadata does not match agent.md', true);
+            result.owner_aid = currentOwner;
+            result.status = statement ? 'single_sided' : 'unbound';
+            const ownerAid = statement?.owner_aid ?? target?.owner_aid;
+            let ownerBefore;
+            if (ownerAid) {
+                const owner = await this.readOwner(ownerAid, subAid);
+                ownerBefore = owner;
+                result.owner_md_sha256 = owner.exists ? owner.sha256 ?? '' : '';
+                if (owner.exists) {
+                    const declaration = await this.verifyFile(owner.content, 'owner', subAid, ownerAid);
+                    if (statement) {
+                        if (declaration.statement.relation_version !== before.relation_version)
+                            throw new ValidationError('ownership relation_version mismatch');
+                        result.status = declaration.action === 'release' ? 'released' : 'consensus';
+                    }
+                    else if (target && declaration.action === 'declare' && declaration.statement.relation_version === target.relation_version && target.relation_version === before.relation_version + 1) {
+                        result.status = 'single_sided';
+                    }
+                }
+                else if (statement)
+                    result.status = 'released';
+            }
+            if (statement && before.lock !== (result.status === 'released' ? 'unlocked' : 'locked'))
+                throw ownershipFailure('unavailable', 'NS lock does not match current ownership materials', true);
+            result.owner_aid = result.status === 'consensus' ? statement.owner_aid : null;
+            const after = await this.readAgent(subAid);
+            if (ownerAid && ownerBefore) {
+                const ownerAfter = await this.readOwner(ownerAid, subAid);
+                if (ownerBefore.exists !== ownerAfter.exists || ownerBefore.content !== ownerAfter.content || ownerBefore.sha256 !== ownerAfter.sha256)
+                    throw ownershipFailure('unavailable', 'owner.md changed during consensus check', true);
+            }
+            if (before.exists !== after.exists || before.etag !== after.etag || before.relation_version !== after.relation_version || before.lock !== after.lock || before.content !== after.content || before.owner_aid !== after.owner_aid || this.deps.now() - began > 30)
+                throw ownershipFailure('unavailable', 'NS relation changed or verification window elapsed during consensus check', true);
+            return result;
+        }
+        catch (error) {
+            result.status = error instanceof StateError && error.stringCode === 'not_applicable' ? 'not_applicable' : error instanceof ValidationError || error instanceof StateError && 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;
+        }
+    }
+    async declareSubaid(task) {
+        const ownerAid = this.targetOwner(task);
+        this.requireLocal(ownerAid);
+        return this.publishOwner(task, 'owner', ownerAid, async () => {
+            const agent = await this.readAgent(task.sub_aid);
+            await this.assertBase(task, agent);
+            if (task.operation === 'transfer')
+                await this.requireTransfer(task);
+            return { statement: this.statement(task, ownerAid, task.target_relation_version), action: 'declare' };
+        });
+    }
+    async declareOwneraid(task) {
+        this.requireLocal(task.sub_aid);
+        const ownerAid = this.targetOwner(task);
+        return this.publishAgent(task, async (agent) => {
+            await this.assertBase(task, agent);
+            if (task.operation === 'transfer')
+                await this.requireTransfer(task);
+            const owner = await this.readOwner(ownerAid, task.sub_aid);
+            if (!owner.exists)
+                throw ownershipFailure('unavailable', 'target owner declaration is missing', true);
+            const declaration = await this.verifyFile(owner.content, 'owner', task.sub_aid, ownerAid);
+            if (declaration.action !== 'declare' || declaration.statement.relation_version !== task.target_relation_version)
+                throw ownershipFailure('conflict', 'target owner declaration does not match this task');
+            return { owner: ownerAid, ownership: { statement: this.statement(task, ownerAid, task.target_relation_version) } };
+        });
+    }
+    async revokeSubaid(task) {
+        this.requireLocal(task.owner_aid);
+        return this.publishOwner(task, 'release', task.owner_aid, async (owner) => {
+            await this.requireOriginal(task);
+            const original = await this.verifyFile(owner.content, 'owner', task.sub_aid, task.owner_aid);
+            return { statement: original.statement, action: 'release' };
+        });
+    }
+    async revokeOwneraid(task) {
+        this.requireLocal(task.sub_aid);
+        return this.publishAgent(task, async (agent) => {
+            if (agent.lock === 'locked')
+                throw ownershipFailure('owner_locked', 'NS has not confirmed release');
+            const parsed = parseOwnershipFile(agent.content, 'agent', { expectedSubAid: task.sub_aid });
+            if (!parsed.statement && agent.relation_version === 0)
+                return {};
+            if (agent.relation_version !== task.target_relation_version)
+                throw ownershipFailure('conflict', 'release relation_version changed');
+            if (parsed.statement && (parsed.statement.owner_aid !== task.owner_aid || parsed.statement.relation_version !== task.base_relation_version))
+                throw ownershipFailure('conflict', 'agent.md no longer contains the released relation');
+            if (task.expected_agent_statement && Object.keys(task.expected_agent_statement).some((field) => task.expected_agent_statement[field] !== parsed.statement?.[field]))
+                throw ownershipFailure('conflict', 'agent.md no longer contains the approved statement');
+            return {};
+        }, true);
+    }
+    async transferOwneraid(task) {
+        this.requireLocal(task.owner_aid);
+        ownershipAid(task.new_owner_aid, 'new_owner_aid');
+        if (task.new_owner_aid === task.owner_aid)
+            throw new ValidationError('transfer target must differ from current owner');
+        return this.publishOwner(task, 'transfer', task.owner_aid, async (owner) => {
+            await this.requireOriginal(task);
+            const original = await this.verifyFile(owner.content, 'owner', task.sub_aid, task.owner_aid);
+            return { statement: original.statement, action: 'transfer_owner', transfer: { new_owner_aid: task.new_owner_aid, target_relation_version: task.target_relation_version, expires_at: this.deps.now() + 3600 } };
+        });
+    }
+    async cleanupOwnerFile(task) {
+        this.requireLocal(task.owner_aid);
+        const source = this.savedFile(task, task.operation === 'release' ? 'release' : 'transfer');
+        if (!source)
+            throw ownershipFailure('conflict', 'original owner file is unavailable');
+        const consensus = await this.checkConsensus(task.sub_aid);
+        if (consensus.status === 'not_applicable')
+            throw ownershipFailure('not_applicable', consensus.reason ?? 'group/org use their dedicated lifecycle ownership');
+        if (consensus.status === 'invalid')
+            throw new ValidationError(consensus.reason ?? 'ownership consensus is invalid', { stringCode: 'invalid' });
+        if (consensus.status === 'unavailable')
+            throw ownershipFailure(consensus.code ?? 'unavailable', consensus.reason ?? 'ownership consensus is unavailable', true);
+        if (task.operation === 'release' && consensus.status === 'released')
+            return;
+        if (task.operation === 'release' ? consensus.status !== 'unbound' && consensus.status !== 'consensus' : consensus.relation_version !== task.target_relation_version || consensus.status !== 'consensus' || consensus.owner_aid !== task.new_owner_aid)
+            throw ownershipFailure('conflict', 'current materials do not permit this task cleanup');
+        const current = await this.readOwner(task.owner_aid, task.sub_aid);
+        if (current.exists && (current.content !== source.raw || current.sha256 !== source.hash))
+            throw ownershipFailure('conflict', 'owner file changed before cleanup');
+        if (!task.files.cleanup) {
+            task.files.cleanup = { raw: source.raw, hash: source.hash, condition: {} };
+            await task.persist();
+        }
+        else
+            this.savedFile(task, 'cleanup');
+        const beforeDelete = await this.readOwner(task.owner_aid, task.sub_aid);
+        if (beforeDelete.exists && (beforeDelete.content !== source.raw || beforeDelete.sha256 !== source.hash))
+            throw ownershipFailure('conflict', 'owner file changed before cleanup');
+        if (beforeDelete.exists)
+            await this.deps.deleteOwnerMd(task.owner_aid, task.sub_aid);
+        task.files.cleanup.deleted = true;
+        await task.persist();
+    }
+    async readAgent(subAid) {
+        if (this.deps.currentType && subAid === this.deps.currentAid().aid)
+            requireOwnershipApplicable(this.deps.currentType());
+        const value = await this.deps.readAgentMdFresh(subAid);
+        if (value.exists && typeof value.content === 'string')
+            requireOwnershipApplicable(parseFileFrontmatter(parseAgentMdTailSignature(value.content).payload).type);
+        const now = this.deps.now();
+        if (value.protocol !== '2.1')
+            throw ownershipFailure('unsupported_protocol', 'NS does not provide Ownership 2.1 metadata', true);
+        if (value.sub_aid !== subAid || typeof value.exists !== 'boolean' || !Number.isSafeInteger(value.relation_version) || value.relation_version < 0 || !['locked', 'unlocked'].includes(value.lock) || !Number.isSafeInteger(value.observed_at) || value.observed_at > now + 5 || value.observed_at < now - 30 || value.recovery_ready === false || typeof value.content !== 'string' || value.exists && !value.etag || !value.exists && (value.relation_version !== 0 || value.lock !== 'unlocked'))
+            throw ownershipFailure('unavailable', 'NS authoritative observation is incomplete', true);
+        return value;
+    }
+    async readOwner(ownerAid, subAid) {
+        const value = await this.deps.readOwnerMd(ownerAid, subAid);
+        const now = this.deps.now();
+        if (value.owner_aid !== ownerAid || value.sub_aid !== undefined && value.sub_aid !== subAid || value.bucket !== 'default' || value.path !== `sub_aids/${subAid}/owner.md` || typeof value.exists !== 'boolean' || !Number.isSafeInteger(value.observed_at) || value.observed_at > now + 5 || value.observed_at < now - 30 || value.authoritative !== true || value.recovery_ready !== undefined && value.recovery_ready !== true || value.service_aid !== `st.${ownerAid.slice(ownerAid.indexOf('.') + 1)}` || value.service_aid !== value.authenticated_service_aid || typeof value.content !== 'string' || value.exists && !/^[0-9a-f]{64}$/.test(value.sha256 ?? ''))
+            throw ownershipFailure('unavailable', 'Storage authoritative observation is incomplete or changed', true);
+        if (value.exists && value.sha256 !== ownershipSha256(value.content))
+            throw ownershipFailure('unavailable', 'Storage complete file digest does not match authoritative observation', true);
+        return value;
+    }
+    async verifyFile(raw, role, subAid, ownerAid) {
+        if (role === 'agent') {
+            const meta = parseFileFrontmatter(parseAgentMdTailSignature(raw).payload);
+            requireOwnershipApplicable(meta.type);
+            if ('ownership_proof' in meta || 'ownership_release' in meta || 'owner' in meta && !('ownership' in meta))
+                throw ownershipFailure('unsupported_protocol', 'legacy ownership requires explicit migration', true);
+        }
+        const context = { expectedSubAid: subAid, expectedOwnerAid: ownerAid, now: this.deps.now() };
+        const parsed = parseOwnershipFile(raw, role, context);
+        const signer = role === 'agent' ? subAid : String(parsed.frontmatter.owner_aid);
+        const certificate = await this.deps.resolveCertificate(signer, parsed.signature.cert_fingerprint, role === 'agent' && parsed.frontmatter.type === 'group' ? 'group_identity' : undefined);
+        const additional = new Map();
+        for (const item of parseAgentMdTailSignature(raw).signatures.slice(1))
+            additional.set(`${item.fields.signer_aid};${item.fields.cert_fingerprint}`, await this.deps.resolveCertificate(item.fields.signer_aid, item.fields.cert_fingerprint));
+        return verifyOwnershipFile(raw, role, certificate, { ...context, now: this.deps.now(), certificateResolver: (aid, fingerprint) => additional.get(`${aid};${fingerprint}`) });
+    }
+    async requireTransfer(task) {
+        const owner = await this.readOwner(task.owner_aid, task.sub_aid);
+        if (!owner.exists)
+            throw ownershipFailure('unavailable', 'original owner authorization is missing', true);
+        const authorization = await this.verifyFile(owner.content, 'owner', task.sub_aid, task.owner_aid);
+        const saved = task.files.transfer;
+        if (saved && (saved.raw !== owner.content || saved.hash !== owner.sha256))
+            throw ownershipFailure('conflict', 'fixed transfer authorization changed');
+        if (authorization.action !== 'transfer_owner' || authorization.statement.relation_version !== task.base_relation_version || authorization.transfer.new_owner_aid !== task.new_owner_aid || authorization.transfer.target_relation_version !== task.target_relation_version)
+            throw ownershipFailure('conflict', 'transfer authorization does not match this task');
+        const expiresAt = authorization.transfer.expires_at;
+        if (expiresAt <= this.deps.now())
+            throw ownershipFailure('conflict', 'transfer authorization expired');
+        if (task.authorization_sha256 !== undefined && task.authorization_sha256 !== owner.sha256 || task.expires_at !== undefined && task.expires_at !== expiresAt)
+            throw ownershipFailure('conflict', 'transfer authorization changed');
+        if (task.authorization_sha256 === undefined || task.expires_at === undefined) {
+            task.authorization_sha256 = owner.sha256;
+            task.expires_at = expiresAt;
+            await task.persist();
+        }
+        return authorization;
+    }
+    targetOwner(task) {
+        return ownershipAid(task.operation === 'transfer' ? task.new_owner_aid : task.owner_aid, 'target_owner_aid');
+    }
+    requireLocal(aid) {
+        if (this.deps.currentAid().aid !== aid)
+            throw ownershipFailure('forbidden', 'ownership files require their own authenticated AID');
+    }
+    statement(task, ownerAid, version) {
+        return { version: 2, declaration_id: randomUUID(), owner_aid: ownerAid, sub_aid: task.sub_aid, relation_version: version, declared_at: this.deps.now() };
+    }
+    async assertBase(task, agent) {
+        ownershipInteger(task.base_relation_version, 'base_relation_version', 0);
+        if (ownershipInteger(task.target_relation_version, 'target_relation_version') !== task.base_relation_version + (task.operation === 'release' ? 0 : 1) || agent.relation_version !== task.base_relation_version)
+            throw ownershipFailure('conflict', 'NS relation_version changed');
+        if (!agent.exists)
+            throw ownershipFailure('unavailable', 'initial agent.md is not published', true);
+        const parsed = await this.verifyFile(agent.content, 'agent', task.sub_aid);
+        const base = task.base_agent_md;
+        if (base && (agent.exists !== base.exists || (base.statement ? !parsed.statement || Object.keys(base.statement).some((field) => base.statement[field] !== parsed.statement[field]) : parsed.statement || agent.content !== base.raw || ownershipSha256(agent.content) !== base.sha256)))
+            throw ownershipFailure('conflict', 'the original ownership statement was replaced');
+        if (agent.relation_version !== (parsed.statement?.relation_version ?? 0))
+            throw ownershipFailure('unavailable', 'NS relation metadata does not match agent.md', true);
+        if (task.operation === 'bind' && parsed.frontmatter.type === 'human')
+            throw ownershipFailure('invalid', 'human cannot declare an owner');
+        if (task.operation === 'bind' && agent.lock !== 'unlocked')
+            throw ownershipFailure('owner_locked', 'an existing owner relation is locked');
+        if (task.operation === 'bind' && parsed.statement?.owner_aid === this.targetOwner(task))
+            throw ownershipFailure('conflict', 'clear the released agent.md statement before binding the same owner');
+        if (task.operation !== 'bind' && (agent.lock !== 'locked' || parsed.statement?.owner_aid !== task.owner_aid || parsed.statement.relation_version !== task.base_relation_version))
+            throw ownershipFailure('conflict', 'the original relation is no longer current');
+    }
+    async requireOriginal(task) {
+        await this.assertBase(task, await this.readAgent(task.sub_aid));
+        const consensus = await this.checkConsensus(task.sub_aid);
+        if (consensus.status !== 'consensus' || consensus.owner_aid !== task.owner_aid || consensus.relation_version !== task.base_relation_version)
+            throw ownershipFailure(consensus.status === 'invalid' ? 'invalid' : 'unavailable', 'the original ownership consensus cannot be confirmed', consensus.status !== 'invalid');
+    }
+    savedFile(task, key) {
+        const saved = task.files[key];
+        if (saved && (typeof saved.raw !== 'string' || saved.hash !== ownershipSha256(saved.raw) || !this.validSavedCondition(key, saved.condition) || saved.published_etag !== undefined && (typeof saved.published_etag !== 'string' || !saved.published_etag)))
+            throw ownershipFailure('persistence_unavailable', 'saved ownership file is corrupt');
+        const original = saved?.original_owner;
+        if (saved && key !== 'agent' && key !== 'cleanup' && (!original || typeof original.exists !== 'boolean' || typeof original.raw !== 'string' || original.sha256 !== (original.exists ? ownershipSha256(original.raw) : '') || !original.exists && original.raw !== ''))
+            throw ownershipFailure('persistence_unavailable', 'original owner.md evidence is corrupt');
+        return saved;
+    }
+    validSavedCondition(key, condition) {
+        if (!condition || typeof condition !== 'object')
+            return false;
+        if (key !== 'agent')
+            return Object.keys(condition).length === 0;
+        if (Object.keys(condition).length !== 1)
+            return false;
+        if (key === 'agent')
+            return typeof condition.if_match === 'string' && condition.if_match.length > 0 || condition.if_none_match === '*';
+        return false;
+    }
+    async publishOwner(task, key, ownerAid, prepare) {
+        let saved = this.savedFile(task, key);
+        await this.readAgent(task.sub_aid);
+        const current = await this.readOwner(ownerAid, task.sub_aid);
+        if (!saved) {
+            const base = task.base_owner_md;
+            if (base && ownerAid === task.base_agent_md?.statement?.owner_aid && (current.exists !== base.exists || current.content !== base.raw || (current.exists ? current.sha256 : '') !== base.sha256))
+                throw ownershipFailure('conflict', 'original owner.md material changed before publication');
+            const ownership = await prepare(current);
+            const raw = signOwnershipFile(this.deps.currentAid(), `---\nowner_aid: ${ownerAid}\nsub_aid: ${task.sub_aid}\nownership: ${JSON.stringify(ownership)}\n---\n`, 'owner', { now: this.deps.now(), expectedOwnerAid: ownerAid, expectedSubAid: task.sub_aid });
+            saved = { raw, hash: ownershipSha256(raw), condition: {}, original_owner: { exists: current.exists, raw: current.content, sha256: current.exists ? ownershipSha256(current.content) : '' } };
+            if (key === 'transfer')
+                saved.expires_at = ownership.transfer.expires_at;
+            task.files[key] = saved;
+            await task.persist();
+        }
+        await this.verifyFile(saved.raw, 'owner', task.sub_aid, ownerAid);
+        if (current.exists && current.sha256 === saved.hash && current.content === saved.raw) {
+            await task.persist();
+            return current;
+        }
+        const original = saved.original_owner;
+        if (!original || typeof original.exists !== 'boolean' || typeof original.raw !== 'string' || original.sha256 !== (original.exists ? ownershipSha256(original.raw) : ''))
+            throw ownershipFailure('persistence_unavailable', 'owner file original material is missing or corrupt');
+        if (current.exists !== original.exists || current.content !== original.raw || (current.exists ? current.sha256 : '') !== original.sha256)
+            throw ownershipFailure('conflict', 'owner file original material changed');
+        await this.assertBase(task, await this.readAgent(task.sub_aid));
+        if (key === 'owner' && task.operation === 'transfer')
+            await this.requireTransfer(task);
+        if (key === 'transfer' && saved.expires_at <= this.deps.now())
+            throw ownershipFailure('conflict', 'transfer authorization expired');
+        const beforeWrite = await this.readOwner(ownerAid, task.sub_aid);
+        if (beforeWrite.exists !== original.exists || beforeWrite.content !== original.raw || (beforeWrite.exists ? beforeWrite.sha256 : '') !== original.sha256)
+            throw ownershipFailure('conflict', 'owner file original material changed before publication');
+        const published = await this.deps.writeOwnerMd(ownerAid, task.sub_aid, saved.raw);
+        if (!published.exists || published.sha256 !== saved.hash || published.content !== saved.raw)
+            throw ownershipFailure('unavailable', 'owner publication could not be verified', true);
+        await task.persist();
+        return published;
+    }
+    async publishAgent(task, prepare, cleanup = false) {
+        let saved = this.savedFile(task, 'agent');
+        const current = await this.readAgent(task.sub_aid);
+        if (!saved) {
+            const fields = await prepare(current);
+            if (cleanup && !parseOwnershipFile(current.content, 'agent', { now: this.deps.now() }).statement)
+                return current;
+            const payload = updateOwnershipAgentMd(current.content, fields);
+            const raw = signOwnershipFile(this.deps.currentAid(), payload.endsWith('\n') || payload.endsWith('\r') ? payload : `${payload}\n`, 'agent', { now: this.deps.now(), expectedSubAid: task.sub_aid });
+            saved = { raw, hash: ownershipSha256(raw), condition: current.exists ? { if_match: current.etag } : { if_none_match: '*' } };
+            task.files.agent = saved;
+            await task.persist();
+        }
+        await this.verifyFile(saved.raw, 'agent', task.sub_aid);
+        if (current.exists && ownershipSha256(current.content) === saved.hash && current.content === saved.raw && current.relation_version === (cleanup ? 0 : task.target_relation_version) && current.lock === (cleanup ? 'unlocked' : 'locked')) {
+            if (saved.published_etag !== undefined && current.etag !== saved.published_etag)
+                throw ownershipFailure('conflict', 'agent.md published ETag changed');
+            saved.published_etag = current.etag;
+            await task.persist();
+            return current;
+        }
+        if (current.etag !== saved.condition.if_match)
+            throw ownershipFailure('conflict', 'agent.md original ETag condition changed');
+        if (cleanup) {
+            if (current.lock !== 'unlocked' || current.relation_version !== task.target_relation_version)
+                throw ownershipFailure('conflict', 'release target is no longer current');
+        }
+        else {
+            await this.assertBase(task, current);
+            if (task.operation === 'transfer')
+                await this.requireTransfer(task);
+            const target = await this.readOwner(this.targetOwner(task), task.sub_aid);
+            if (!target.exists)
+                throw ownershipFailure('unavailable', 'target owner declaration is missing', true);
+            const declaration = await this.verifyFile(target.content, 'owner', task.sub_aid, this.targetOwner(task));
+            const savedOwner = task.files.owner;
+            if (savedOwner && (savedOwner.raw !== target.content || savedOwner.hash !== target.sha256))
+                throw ownershipFailure('conflict', 'fixed target owner declaration changed');
+            if (declaration.action !== 'declare' || declaration.statement.relation_version !== task.target_relation_version)
+                throw ownershipFailure('conflict', 'target owner declaration changed');
+        }
+        const published = await this.deps.submitAgentMdRaw(task.sub_aid, saved.raw, saved.condition);
+        if (published.content !== saved.raw || published.relation_version !== (cleanup ? 0 : task.target_relation_version) || published.lock !== (cleanup ? 'unlocked' : 'locked'))
+            throw ownershipFailure('unavailable', 'agent.md publication could not be verified', true);
+        saved.published_etag = published.etag;
+        await task.persist();
+        return published;
+    }
+}
+export class OwnershipStorageAdapter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() { return this.deps.now?.() ?? Math.trunc(Date.now() / 1000); }
+    async call(method, params) {
+        try {
+            const result = await this.deps.call(method, params);
+            if (!result || typeof result !== 'object' || Array.isArray(result))
+                throw ownershipFailure('unavailable', 'Storage response is not an object', true);
+            return result;
+        }
+        catch (error) {
+            const reading = method === 'storage.head_object' || method === 'storage.get_object';
+            const code = error && typeof error === 'object' ? error.code : undefined;
+            if (error instanceof ValidationError && code !== -32601 || error instanceof StateError && error.stringCode === 'invalid')
+                throw new ValidationError(error.message, { stringCode: 'invalid' });
+            if (error instanceof StateError && ['unavailable', 'unsupported_protocol', 'conflict'].includes(error.stringCode))
+                throw ownershipFailure(error.stringCode, error.message, error.stringCode !== 'conflict');
+            if (reading && error instanceof StateError && error.stringCode === 'forbidden')
+                throw ownershipFailure('unavailable', error.message, true);
+            if (error instanceof StateError && error.stringCode)
+                throw error;
+            throw ownershipFailure(code === -32009 ? 'conflict' : code === -32004 ? reading ? 'unavailable' : 'forbidden' : code === -32601 ? 'unsupported_protocol' : 'unavailable', error instanceof Error ? error.message : String(error), code !== -32009 && (reading || code !== -32004));
+        }
+    }
+    metadata(value, ownerAid, path) {
+        const now = this.now();
+        const expectedService = `st.${ownerAid.slice(ownerAid.indexOf('.') + 1)}`;
+        if (value.consistency !== 'authoritative' || value.owner_aid !== ownerAid || value.bucket !== 'default' || value.path !== path || typeof value.exists !== 'boolean' || !Number.isSafeInteger(value.observed_at) || Number(value.observed_at) < now - 30 || Number(value.observed_at) > now + 5 || value.recovery_ready !== undefined && value.recovery_ready !== true || value.service_aid !== undefined && value.service_aid !== expectedService || value.authenticated_service_aid !== undefined && value.authenticated_service_aid !== expectedService || value.exists && (typeof value.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(value.sha256)))
+            throw ownershipFailure('unavailable', 'Storage authoritative namespace or freshness metadata is incomplete', true);
+    }
+    async readObject(ownerAid, path) {
+        ownershipAid(ownerAid, 'owner_aid');
+        const began = this.now();
+        const params = { owner_aid: ownerAid, bucket: 'default', object_key: path, consistency: 'authoritative' };
+        const before = await this.call('storage.head_object', params);
+        this.metadata(before, ownerAid, path);
+        let content = '';
+        let final = before;
+        if (before.exists) {
+            const object = await this.call('storage.get_object', params);
+            this.metadata(object, ownerAid, path);
+            if (object.exists !== true || object.sha256 !== before.sha256 || typeof object.content !== 'string')
+                throw ownershipFailure('unavailable', 'Storage object changed or full Base64 content is unavailable', true);
+            if (object.content !== '' && !isStrictBase64(object.content))
+                throw ownershipFailure('unavailable', 'Storage Base64 content is unavailable', true);
+            const bytes = Buffer.from(object.content, 'base64');
+            if (ownershipSha256(bytes) !== before.sha256)
+                throw ownershipFailure('unavailable', 'Storage complete file digest does not match authoritative head', true);
+            try {
+                content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+            }
+            catch {
+                throw new ValidationError('Storage ownership file is not valid UTF-8', { stringCode: 'invalid' });
+            }
+            final = await this.call('storage.head_object', params);
+            this.metadata(final, ownerAid, path);
+            if (final.exists !== true || final.sha256 !== before.sha256 || this.now() - began > 30)
+                throw ownershipFailure('unavailable', 'Storage material changed during authoritative read', true);
+        }
+        const service = `st.${ownerAid.slice(ownerAid.indexOf('.') + 1)}`;
+        return { owner_aid: ownerAid, bucket: 'default', path, exists: Boolean(final.exists), observed_at: Number(final.observed_at),
+            content, sha256: final.exists ? String(final.sha256) : undefined, authoritative: true, recovery_ready: final.recovery_ready, service_aid: service, authenticated_service_aid: service, version: final.exists && Number.isSafeInteger(final.version) && Number(final.version) > 0 ? final.version : undefined };
+    }
+    async readOwnerMd(ownerAid, subAid) {
+        ownershipAid(subAid, 'sub_aid');
+        return this.readObject(ownerAid, `sub_aids/${subAid}/owner.md`);
+    }
+    async writeOwnerMd(ownerAid, subAid, raw) {
+        this.requireLocal(ownerAid);
+        ownershipAid(subAid, 'sub_aid');
+        const path = `sub_aids/${subAid}/owner.md`;
+        const before = await this.readOwnerMd(ownerAid, subAid);
+        const bytes = new TextEncoder().encode(raw);
+        const expectedVersion = before.exists ? before.version : 0;
+        if (typeof expectedVersion !== 'number' || !Number.isSafeInteger(expectedVersion) || expectedVersion < (before.exists ? 1 : 0))
+            throw ownershipFailure('unavailable', 'Storage owner.md version is unavailable', true);
+        const session = await this.call('storage.create_upload_session', { owner_aid: ownerAid, bucket: 'default', object_key: path, size_bytes: bytes.length, content_type: 'text/markdown; charset=utf-8', expected_version: expectedVersion, overwrite: true });
+        const uploadURL = String(session.upload_url ?? ''), sessionID = String(session.session_id ?? '');
+        if (!uploadURL || !sessionID)
+            throw ownershipFailure('unavailable', 'Storage owner.md upload session is incomplete', true);
+        const headers = {};
+        if (session.headers && typeof session.headers === 'object')
+            for (const [key, value] of Object.entries(session.headers))
+                if (value !== undefined && value !== null && key.toLowerCase() !== 'content-type')
+                    headers[key] = String(value);
+        headers['Content-Type'] = 'text/markdown; charset=utf-8';
+        if (this.deps.httpPut)
+            await this.deps.httpPut(uploadURL, bytes, headers);
+        else {
+            const response = await fetch(uploadURL, { method: 'PUT', body: bytes, headers });
+            if (!response.ok)
+                throw ownershipFailure('unavailable', `Storage owner.md HTTP PUT failed: ${response.status}`, true);
+        }
+        const complete = { owner_aid: ownerAid, bucket: 'default', object_key: path, session_id: sessionID, size_bytes: bytes.length, sha256: ownershipSha256(bytes), content_type: 'text/markdown; charset=utf-8', is_private: false, overwrite: true };
+        complete.expected_version = expectedVersion;
+        await this.call('storage.complete_upload', complete);
+        return this.readOwnerMd(ownerAid, subAid);
+    }
+    async deleteOwnerMd(ownerAid, subAid) {
+        this.requireLocal(ownerAid);
+        ownershipAid(subAid, 'sub_aid');
+        await this.call('storage.delete_object', { owner_aid: ownerAid, bucket: 'default', object_key: `sub_aids/${subAid}/owner.md` });
+        if ((await this.readOwnerMd(ownerAid, subAid)).exists)
+            throw ownershipFailure('unavailable', 'Storage deletion could not be confirmed', true);
+    }
+    requireLocal(ownerAid) {
+        if (ownershipAid(ownerAid, 'owner_aid') !== this.deps.currentAid())
+            throw ownershipFailure('forbidden', 'owner.md must be published by its own authenticated AID');
+    }
+}
+//# sourceMappingURL=ownership-v21.js.map