@holon-run/agentinbox 1.7.2 → 1.8.1

package/dist/src/email_attachment_content.js

@@ -0,0 +1,759 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailAttachmentContentManager = exports.EMAIL_ATTACHMENT_DEFAULT_MAX_TOTAL_BYTES = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
+const email_attachment_1 = require("./email_attachment");
+const email_1 = require("./sources/email");
+const util_1 = require("./util");
+exports.EMAIL_ATTACHMENT_DEFAULT_MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+const EMAIL_ATTACHMENT_DEFAULT_GC_BATCH_SIZE = 256;
+const EMAIL_ATTACHMENT_STAGING_MAX_AGE_MS = 60 * 60 * 1000;
+class EmailAttachmentError extends Error {
+    code;
+    rejected;
+    statusCode;
+    constructor(code, rejected, message) {
+        super(message);
+        this.code = code;
+        this.rejected = rejected;
+        this.statusCode = code === "attachment_content_unavailable"
+            ? 404
+            : rejected
+                ? 400
+                : 503;
+    }
+}
+class EmailAttachmentContentManager {
+    store;
+    uxc;
+    inFlight = new Map();
+    itemInFlight = new Map();
+    publishingObjects = new Map();
+    stagingDir;
+    objectsDir;
+    scanner;
+    maxTotalBytes;
+    gcBatchSize;
+    constructor(store, rootDir, uxc = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env }), options = {}) {
+        this.store = store;
+        this.uxc = uxc;
+        this.stagingDir = node_path_1.default.join(rootDir, "staging");
+        this.objectsDir = node_path_1.default.join(rootDir, "objects");
+        this.scanner = options.scanner ?? null;
+        this.maxTotalBytes = positiveIntegerOrDefault(options.maxTotalBytes ?? process.env.AGENTINBOX_EMAIL_ATTACHMENT_MAX_TOTAL_BYTES, exports.EMAIL_ATTACHMENT_DEFAULT_MAX_TOTAL_BYTES);
+        this.gcBatchSize = positiveIntegerOrDefault(options.gcBatchSize, EMAIL_ATTACHMENT_DEFAULT_GC_BATCH_SIZE);
+    }
+    inspect(agentId, attachmentRef) {
+        try {
+            const owned = this.resolveOwned(agentId, attachmentRef);
+            if (owned.attachment.status === "deleted") {
+                throw unknownAttachment(attachmentRef);
+            }
+            this.appendAudit(agentId, attachmentRef, "metadata_read", "success", owned);
+            return owned.attachment;
+        }
+        catch (error) {
+            this.appendAudit(agentId, attachmentRef, "metadata_read", "rejected", null, auditErrorCode(error));
+            throw error;
+        }
+    }
+    async materialize(agentId, attachmentRef) {
+        let owned;
+        try {
+            owned = this.resolveOwned(agentId, attachmentRef);
+            if (owned.attachment.status === "deleted") {
+                throw unknownAttachment(attachmentRef);
+            }
+            this.appendAudit(agentId, attachmentRef, "materialize", "started", owned);
+        }
+        catch (error) {
+            this.appendAudit(agentId, attachmentRef, "materialize", "rejected", null, auditErrorCode(error));
+            throw error;
+        }
+        const current = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+        if (current?.status === "available" && current.objectKey && this.objectExists(current.objectKey)) {
+            const attachment = this.resolveOwned(agentId, attachmentRef).attachment;
+            this.appendAudit(agentId, attachmentRef, "materialize", "available", owned, null, current);
+            return attachment;
+        }
+        const key = `${owned.inboxId}:${owned.item.itemId}:${owned.attachmentSelector}`;
+        const existing = this.inFlight.get(key);
+        if (existing) {
+            return this.auditMaterializationResult(agentId, attachmentRef, owned, existing);
+        }
+        const itemKey = `${owned.inboxId}:${owned.item.itemId}`;
+        const previousItem = this.itemInFlight.get(itemKey) ?? Promise.resolve();
+        const pending = previousItem
+            .catch(() => undefined)
+            .then(() => this.materializeOnce(agentId, attachmentRef, owned))
+            .finally(() => this.inFlight.delete(key));
+        const itemCompletion = pending.then(() => undefined, () => undefined).finally(() => {
+            if (this.itemInFlight.get(itemKey) === itemCompletion) {
+                this.itemInFlight.delete(itemKey);
+            }
+        });
+        this.itemInFlight.set(itemKey, itemCompletion);
+        this.inFlight.set(key, pending);
+        return this.auditMaterializationResult(agentId, attachmentRef, owned, pending);
+    }
+    openContent(agentId, attachmentRef) {
+        try {
+            const content = this.openContentOnce(agentId, attachmentRef);
+            const owned = this.resolveOwned(agentId, attachmentRef);
+            const materialization = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+            this.appendAudit(agentId, attachmentRef, "content_read", "success", owned, null, materialization);
+            return content;
+        }
+        catch (error) {
+            this.appendAudit(agentId, attachmentRef, "content_read", "rejected", null, auditErrorCode(error));
+            throw error;
+        }
+    }
+    openContentOnce(agentId, attachmentRef) {
+        const owned = this.resolveOwned(agentId, attachmentRef);
+        const materialization = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+        if (materialization?.status !== "available"
+            || !materialization.objectKey
+            || !materialization.sha256
+            || materialization.storedSize == null) {
+            throw new EmailAttachmentError("attachment_content_unavailable", false, "Email attachment content is not available.");
+        }
+        const objectPath = this.resolveObjectPath(materialization.objectKey);
+        let fd = null;
+        try {
+            fd = node_fs_1.default.openSync(objectPath, "r");
+            const stat = node_fs_1.default.fstatSync(fd);
+            if (!stat.isFile() || stat.size !== materialization.storedSize) {
+                throw new Error("managed attachment object mismatch");
+            }
+        }
+        catch {
+            if (fd != null) {
+                node_fs_1.default.closeSync(fd);
+            }
+            throw new EmailAttachmentError("attachment_content_unavailable", false, "Email attachment content is not available.");
+        }
+        if (fd == null) {
+            throw new EmailAttachmentError("attachment_content_unavailable", false, "Email attachment content is not available.");
+        }
+        let verified;
+        try {
+            // Re-check ownership after opening the managed object and before returning bytes.
+            verified = this.resolveOwned(agentId, attachmentRef);
+        }
+        catch (error) {
+            node_fs_1.default.closeSync(fd);
+            throw error;
+        }
+        return {
+            attachment: verified.attachment,
+            stream: node_fs_1.default.createReadStream(objectPath, { fd, autoClose: true }),
+            size: materialization.storedSize,
+            sha256: materialization.sha256,
+            contentType: materialization.detectedContentType ?? "application/octet-stream",
+        };
+    }
+    async delete(agentId, attachmentRef) {
+        let owned;
+        try {
+            owned = this.resolveOwned(agentId, attachmentRef);
+        }
+        catch (error) {
+            this.appendAudit(agentId, attachmentRef, "delete", "rejected", null, auditErrorCode(error));
+            throw error;
+        }
+        const itemKey = `${owned.inboxId}:${owned.item.itemId}`;
+        const previousItem = this.itemInFlight.get(itemKey) ?? Promise.resolve();
+        const deletion = previousItem
+            .catch(() => undefined)
+            .then(() => this.deleteOnce(agentId, attachmentRef, owned));
+        const itemCompletion = deletion.then(() => undefined, () => undefined).finally(() => {
+            if (this.itemInFlight.get(itemKey) === itemCompletion) {
+                this.itemInFlight.delete(itemKey);
+            }
+        });
+        this.itemInFlight.set(itemKey, itemCompletion);
+        return deletion;
+    }
+    gc(now = new Date()) {
+        const objectKeys = new Set();
+        let expired = 0;
+        let capacityEvicted = 0;
+        let objectsDeleted = 0;
+        const cutoffIso = now.toISOString();
+        for (const candidate of this.store.listExpiredEmailAttachmentMaterializations(cutoffIso, this.gcBatchSize)) {
+            const previous = this.tombstoneForGc(candidate, "attachment_retention_expired", cutoffIso);
+            if (previous) {
+                expired += 1;
+                if (previous.objectKey) {
+                    objectKeys.add(previous.objectKey);
+                }
+            }
+        }
+        let managedBytes = this.store.sumManagedEmailAttachmentBytes();
+        if (managedBytes > this.maxTotalBytes) {
+            for (const object of this.store.listOldestEmailAttachmentObjects(this.gcBatchSize)) {
+                if (managedBytes <= this.maxTotalBytes) {
+                    break;
+                }
+                const references = this.store.listEmailAttachmentMaterializationsForObject(object.objectKey);
+                let evictedObject = false;
+                for (const candidate of references) {
+                    const previous = this.tombstoneForGc(candidate, "attachment_capacity_evicted", cutoffIso);
+                    if (previous) {
+                        capacityEvicted += 1;
+                        evictedObject = true;
+                    }
+                }
+                if (evictedObject) {
+                    objectKeys.add(object.objectKey);
+                    managedBytes = Math.max(0, managedBytes - object.storedSize);
+                }
+            }
+        }
+        for (const objectKey of objectKeys) {
+            if (this.deleteObjectIfUnreferenced(objectKey)) {
+                objectsDeleted += 1;
+            }
+        }
+        const orphanObjectsDeleted = this.deleteOrphanObjects(this.gcBatchSize);
+        const stagingFilesDeleted = this.deleteStaleStagingFiles(now.getTime() - EMAIL_ATTACHMENT_STAGING_MAX_AGE_MS, this.gcBatchSize);
+        return {
+            expired,
+            capacityEvicted,
+            objectsDeleted,
+            orphanObjectsDeleted,
+            stagingFilesDeleted,
+            managedBytes: this.store.sumManagedEmailAttachmentBytes(),
+        };
+    }
+    async materializeOnce(agentId, attachmentRef, owned) {
+        const policy = (0, email_1.parseEmailAttachmentPolicy)(owned.source.config?.attachmentPolicy ?? owned.source.config?.attachment_policy);
+        if (policy.mode !== "store_reference") {
+            throw new EmailAttachmentError("attachment_policy_metadata_only", true, "This email source does not allow attachment content storage.");
+        }
+        if (!owned.handle) {
+            throw new EmailAttachmentError("attachment_not_retrievable", true, "This attachment does not have a retrievable provider reference.");
+        }
+        const collection = (0, email_attachment_1.publicEmailAttachmentCollection)(owned.item.itemId, owned.item.metadata);
+        const knownCount = collection.attachmentCount ?? collection.attachments.length;
+        if (knownCount > policy.maxAttachmentsPerMessage) {
+            throw new EmailAttachmentError("attachment_count_limit_exceeded", true, "The message exceeds the configured attachment count limit.");
+        }
+        if (owned.attachment.size != null
+            && owned.attachment.size > policy.maxBytesPerAttachment) {
+            throw new EmailAttachmentError("attachment_size_limit_exceeded", true, "The attachment exceeds the configured size limit.");
+        }
+        assertContentTypeAllowed(owned.attachment.contentType, policy, "declared");
+        const storedBeforeFetch = this.store.sumAvailableEmailAttachmentBytes(owned.item.itemId, owned.attachmentSelector);
+        if (owned.attachment.size != null
+            && storedBeforeFetch + owned.attachment.size > policy.maxBytesPerMessage) {
+            throw new EmailAttachmentError("attachment_message_size_limit_exceeded", true, "The message exceeds the configured stored attachment byte limit.");
+        }
+        const now = (0, util_1.nowIso)();
+        const prior = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+        const pending = {
+            itemId: owned.item.itemId,
+            attachmentSelector: owned.attachmentSelector,
+            status: "pending",
+            lastErrorCode: null,
+            objectKey: null,
+            sha256: null,
+            declaredContentType: owned.attachment.contentType,
+            detectedContentType: null,
+            declaredSize: owned.attachment.size,
+            storedSize: null,
+            createdAt: prior?.createdAt ?? now,
+            updatedAt: now,
+            expiresAt: null,
+            deletedAt: null,
+        };
+        if (!this.store.beginEmailAttachmentMaterialization(owned.inboxId, pending)) {
+            throw unknownAttachment(attachmentRef);
+        }
+        node_fs_1.default.mkdirSync(this.stagingDir, { recursive: true, mode: 0o700 });
+        node_fs_1.default.chmodSync(this.stagingDir, 0o700);
+        const stagingPath = node_path_1.default.join(this.stagingDir, node_crypto_1.default.randomBytes(18).toString("hex"));
+        try {
+            const result = await this.retrieve(owned.handle, stagingPath, policy.maxBytesPerAttachment);
+            const stat = node_fs_1.default.statSync(stagingPath);
+            if (!stat.isFile() || stat.size > policy.maxBytesPerAttachment || stat.size !== result.size_bytes) {
+                throw new EmailAttachmentError("attachment_size_mismatch", true, "The retrieved attachment size did not match the provider result.");
+            }
+            node_fs_1.default.chmodSync(stagingPath, 0o600);
+            const sha256 = await hashFile(stagingPath);
+            if (sha256 !== result.sha256.toLowerCase()) {
+                throw new EmailAttachmentError("attachment_hash_mismatch", true, "The retrieved attachment hash did not match the provider result.");
+            }
+            const detectedContentType = detectContentType(stagingPath);
+            assertContentTypeAllowed(detectedContentType, policy, "detected");
+            const scanResult = this.scanner
+                ? await this.scanner.scan({
+                    path: stagingPath,
+                    sha256,
+                    size: stat.size,
+                    contentType: detectedContentType,
+                })
+                : { status: "clean", code: null };
+            if (scanResult.status === "rejected") {
+                throw new EmailAttachmentError(stableAttachmentErrorCode(scanResult.code, "attachment_scanner_rejected"), true, "The attachment was rejected by the configured scanner.");
+            }
+            const alreadyStored = this.store.sumAvailableEmailAttachmentBytes(owned.item.itemId, owned.attachmentSelector);
+            if (alreadyStored + stat.size > policy.maxBytesPerMessage) {
+                throw new EmailAttachmentError("attachment_message_size_limit_exceeded", true, "The message exceeds the configured stored attachment byte limit.");
+            }
+            const verified = this.resolveOwned(agentId, attachmentRef);
+            syncFile(stagingPath);
+            const objectKey = objectKeyForSha256(sha256);
+            this.beginObjectPublication(objectKey);
+            try {
+                await this.putObject(stagingPath, sha256, objectKey);
+                const completedAt = (0, util_1.nowIso)();
+                const record = {
+                    ...pending,
+                    status: scanResult.status === "quarantined" ? "quarantined" : "available",
+                    lastErrorCode: scanResult.status === "quarantined"
+                        ? stableAttachmentErrorCode(scanResult.code, "attachment_scanner_quarantined")
+                        : null,
+                    objectKey,
+                    sha256,
+                    detectedContentType,
+                    storedSize: stat.size,
+                    updatedAt: completedAt,
+                    expiresAt: new Date(Date.parse(completedAt) + policy.retentionSecs * 1000).toISOString(),
+                };
+                if (verified.item.itemId !== owned.item.itemId
+                    || verified.attachmentSelector !== owned.attachmentSelector
+                    || !this.store.finishEmailAttachmentMaterialization(owned.inboxId, record)) {
+                    throw unknownAttachment(attachmentRef);
+                }
+            }
+            finally {
+                this.endObjectPublication(objectKey);
+            }
+            return this.resolveOwned(agentId, attachmentRef).attachment;
+        }
+        catch (error) {
+            node_fs_1.default.rmSync(stagingPath, { force: true });
+            if (error instanceof Error && error.message.startsWith("unknown inbox attachment:")) {
+                throw error;
+            }
+            const failure = attachmentFailure(error);
+            const failedAt = (0, util_1.nowIso)();
+            this.store.finishEmailAttachmentMaterialization(owned.inboxId, {
+                ...pending,
+                status: failure.rejected ? "rejected" : "failed",
+                lastErrorCode: failure.code,
+                updatedAt: failedAt,
+            });
+            throw failure;
+        }
+    }
+    async auditMaterializationResult(agentId, attachmentRef, owned, operation) {
+        try {
+            const attachment = await operation;
+            const materialization = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+            this.appendAudit(agentId, attachmentRef, "materialize", materialization?.status ?? attachment.status, owned, materialization?.lastErrorCode ?? null, materialization);
+            return attachment;
+        }
+        catch (error) {
+            const materialization = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+            this.appendAudit(agentId, attachmentRef, "materialize", materialization?.status ?? "failed", owned, materialization?.lastErrorCode ?? auditErrorCode(error), materialization);
+            throw error;
+        }
+    }
+    deleteOnce(agentId, attachmentRef, initial) {
+        const owned = this.resolveOwned(agentId, attachmentRef);
+        if (owned.item.itemId !== initial.item.itemId
+            || owned.attachmentSelector !== initial.attachmentSelector) {
+            throw unknownAttachment(attachmentRef);
+        }
+        const current = this.store.getEmailAttachmentMaterialization(owned.item.itemId, owned.attachmentSelector);
+        if (current?.status === "deleted") {
+            this.appendAudit(agentId, attachmentRef, "delete", "already_deleted", owned);
+            return { attachmentRef, deleted: false };
+        }
+        const deletedAt = (0, util_1.nowIso)();
+        const tombstoneFallback = {
+            itemId: owned.item.itemId,
+            attachmentSelector: owned.attachmentSelector,
+            status: "deleted",
+            lastErrorCode: "attachment_explicitly_deleted",
+            objectKey: null,
+            sha256: null,
+            declaredContentType: owned.attachment.contentType,
+            detectedContentType: owned.attachment.detectedContentType,
+            declaredSize: owned.attachment.size,
+            storedSize: null,
+            createdAt: deletedAt,
+            updatedAt: deletedAt,
+            expiresAt: null,
+            deletedAt,
+        };
+        const previous = this.store.tombstoneEmailAttachmentMaterialization(owned.inboxId, owned.item.itemId, owned.attachmentSelector, deletedAt, this.auditEvent(agentId, attachmentRef, "delete", "deleted", owned, "attachment_explicitly_deleted", current), tombstoneFallback);
+        if (!previous) {
+            throw unknownAttachment(attachmentRef);
+        }
+        if (previous.objectKey) {
+            this.deleteObjectIfUnreferenced(previous.objectKey);
+        }
+        return { attachmentRef, deleted: true };
+    }
+    tombstoneForGc(candidate, errorCode, deletedAt) {
+        const materialization = candidate.materialization;
+        const attachmentRef = `att_v1.${materialization.itemId}.${materialization.attachmentSelector}`;
+        return this.store.tombstoneEmailAttachmentMaterialization(candidate.inboxId, materialization.itemId, materialization.attachmentSelector, deletedAt, {
+            auditId: (0, util_1.generateCanonicalId)("aat"),
+            attachmentRef,
+            claimedAgentId: candidate.agentId,
+            inboxId: candidate.inboxId,
+            itemId: materialization.itemId,
+            sourceId: candidate.sourceId,
+            action: "gc",
+            result: "deleted",
+            errorCode,
+            bytes: materialization.storedSize,
+            sha256: materialization.sha256,
+            createdAt: deletedAt,
+        });
+    }
+    appendAudit(agentId, attachmentRef, action, result, owned, errorCode = null, materialization = null) {
+        this.store.appendEmailAttachmentAudit(this.auditEvent(agentId, attachmentRef, action, result, owned, errorCode, materialization));
+    }
+    auditEvent(agentId, attachmentRef, action, result, owned, errorCode = null, materialization = null) {
+        return {
+            auditId: (0, util_1.generateCanonicalId)("aat"),
+            attachmentRef: safeAuditAttachmentRef(attachmentRef),
+            claimedAgentId: agentId,
+            inboxId: owned?.inboxId ?? null,
+            itemId: owned?.item.itemId ?? null,
+            sourceId: owned?.source.sourceId ?? null,
+            action,
+            result,
+            errorCode: errorCode
+                ? stableAttachmentErrorCode(errorCode, "attachment_operation_failed")
+                : null,
+            bytes: materialization?.storedSize ?? null,
+            sha256: materialization?.sha256 ?? null,
+            createdAt: (0, util_1.nowIso)(),
+        };
+    }
+    deleteObjectIfUnreferenced(objectKey) {
+        if (this.publishingObjects.has(objectKey)) {
+            return false;
+        }
+        if (this.store.countEmailAttachmentObjectReferences(objectKey) > 0) {
+            return false;
+        }
+        try {
+            const objectPath = this.resolveObjectPath(objectKey);
+            node_fs_1.default.rmSync(objectPath, { force: true });
+            try {
+                node_fs_1.default.rmdirSync(node_path_1.default.dirname(objectPath));
+            }
+            catch {
+                // A shared hash prefix may still contain other managed objects.
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    deleteOrphanObjects(limit) {
+        const referenced = new Set(this.store.listReferencedEmailAttachmentObjectKeys());
+        let deleted = 0;
+        let prefixes;
+        try {
+            prefixes = node_fs_1.default.readdirSync(this.objectsDir, { withFileTypes: true });
+        }
+        catch {
+            return 0;
+        }
+        for (const prefix of prefixes) {
+            if (deleted >= limit || !prefix.isDirectory() || !/^[a-f0-9]{2}$/.test(prefix.name)) {
+                continue;
+            }
+            const prefixPath = node_path_1.default.join(this.objectsDir, prefix.name);
+            let objects;
+            try {
+                objects = node_fs_1.default.readdirSync(prefixPath, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const object of objects) {
+                if (deleted >= limit) {
+                    break;
+                }
+                const objectKey = node_path_1.default.posix.join("objects", prefix.name, object.name);
+                if (object.isFile()
+                    && /^[a-f0-9]{64}$/.test(object.name)
+                    && !referenced.has(objectKey)
+                    && this.deleteObjectIfUnreferenced(objectKey)) {
+                    deleted += 1;
+                }
+            }
+        }
+        return deleted;
+    }
+    deleteStaleStagingFiles(olderThanMs, limit) {
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(this.stagingDir, { withFileTypes: true });
+        }
+        catch {
+            return 0;
+        }
+        let deleted = 0;
+        for (const entry of entries) {
+            if (deleted >= limit || !entry.isFile() || !/^[a-f0-9]{36}$/.test(entry.name)) {
+                continue;
+            }
+            const stagingPath = node_path_1.default.join(this.stagingDir, entry.name);
+            try {
+                if (node_fs_1.default.statSync(stagingPath).mtimeMs <= olderThanMs) {
+                    node_fs_1.default.rmSync(stagingPath, { force: true });
+                    deleted += 1;
+                }
+            }
+            catch {
+                // A concurrent materialization may already have published or removed it.
+            }
+        }
+        return deleted;
+    }
+    async retrieve(handle, stagingPath, maxBytes) {
+        const result = await this.uxc.request("email.attachment.get", {
+            handle: JSON.stringify(handle),
+            output: stagingPath,
+            max_bytes: maxBytes,
+        });
+        if (!isRecord(result)) {
+            throw new EmailAttachmentError("attachment_provider_invalid_result", false, "UXC returned an invalid attachment result.");
+        }
+        const size = optionalInteger(result.size_bytes);
+        const sha256 = optionalString(result.sha256);
+        if (size == null || !sha256 || !/^[a-f0-9]{64}$/i.test(sha256)) {
+            throw new EmailAttachmentError("attachment_provider_invalid_result", false, "UXC returned an invalid attachment result.");
+        }
+        return {
+            size_bytes: size,
+            sha256: sha256.toLowerCase(),
+            content_type: optionalString(result.content_type),
+        };
+    }
+    resolveOwned(agentId, attachmentRef) {
+        const inbox = this.store.getInboxByAgentId(agentId);
+        const parsed = inbox ? attachmentRefParts(attachmentRef) : null;
+        const item = parsed && inbox
+            ? this.store.getInboxItemForInbox(inbox.inboxId, parsed.itemId)
+            : null;
+        const source = item ? this.store.getSource(item.sourceId) : null;
+        if (!inbox
+            || !item
+            || item.eventVariant !== "email.message.received"
+            || source?.sourceType !== "email_mailbox") {
+            throw unknownAttachment(attachmentRef);
+        }
+        const resolved = (0, email_attachment_1.resolveEmailAttachment)(item, attachmentRef, (itemId, selector) => this.store.getEmailAttachmentMaterialization(itemId, selector));
+        if (!resolved) {
+            throw unknownAttachment(attachmentRef);
+        }
+        return {
+            inboxId: inbox.inboxId,
+            item,
+            source,
+            ...resolved,
+        };
+    }
+    async putObject(stagingPath, sha256, objectKey) {
+        const objectPath = this.resolveObjectPath(objectKey);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(objectPath), { recursive: true, mode: 0o700 });
+        node_fs_1.default.chmodSync(node_path_1.default.dirname(objectPath), 0o700);
+        if (node_fs_1.default.existsSync(objectPath)) {
+            const stagedSize = node_fs_1.default.statSync(stagingPath).size;
+            const existing = node_fs_1.default.statSync(objectPath);
+            if (!existing.isFile()
+                || existing.size !== stagedSize
+                || await hashFile(objectPath) !== sha256) {
+                throw new EmailAttachmentError("attachment_object_integrity_mismatch", false, "The managed attachment object failed integrity verification.");
+            }
+            node_fs_1.default.rmSync(stagingPath, { force: true });
+        }
+        else {
+            node_fs_1.default.renameSync(stagingPath, objectPath);
+            node_fs_1.default.chmodSync(objectPath, 0o600);
+            syncDirectory(node_path_1.default.dirname(objectPath));
+        }
+    }
+    beginObjectPublication(objectKey) {
+        this.publishingObjects.set(objectKey, (this.publishingObjects.get(objectKey) ?? 0) + 1);
+    }
+    endObjectPublication(objectKey) {
+        const count = this.publishingObjects.get(objectKey) ?? 0;
+        if (count <= 1) {
+            this.publishingObjects.delete(objectKey);
+            return;
+        }
+        this.publishingObjects.set(objectKey, count - 1);
+    }
+    objectExists(objectKey) {
+        try {
+            return node_fs_1.default.statSync(this.resolveObjectPath(objectKey)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    resolveObjectPath(objectKey) {
+        if (!/^objects\/[a-f0-9]{2}\/[a-f0-9]{64}$/.test(objectKey)) {
+            throw new EmailAttachmentError("attachment_content_unavailable", false, "Email attachment content is not available.");
+        }
+        const resolved = node_path_1.default.resolve(node_path_1.default.dirname(this.objectsDir), objectKey);
+        const root = `${node_path_1.default.resolve(node_path_1.default.dirname(this.objectsDir))}${node_path_1.default.sep}`;
+        if (!resolved.startsWith(root)) {
+            throw new EmailAttachmentError("attachment_content_unavailable", false, "Email attachment content is not available.");
+        }
+        return resolved;
+    }
+}
+exports.EmailAttachmentContentManager = EmailAttachmentContentManager;
+function attachmentRefParts(attachmentRef) {
+    const match = /^att_v1\.([A-Za-z0-9_-]+)\.[A-Za-z0-9_-]{22}$/.exec(attachmentRef);
+    return match ? { itemId: match[1] } : null;
+}
+function objectKeyForSha256(sha256) {
+    return node_path_1.default.posix.join("objects", sha256.slice(0, 2), sha256);
+}
+function unknownAttachment(attachmentRef) {
+    return new Error(`unknown inbox attachment: ${attachmentRef}`);
+}
+function attachmentFailure(error) {
+    if (error instanceof EmailAttachmentError) {
+        return error;
+    }
+    const data = isRecord(error) && isRecord(error.data) ? error.data : {};
+    const code = stableAttachmentErrorCode(data.code, "");
+    if (code) {
+        return new EmailAttachmentError(code, false, "Email attachment retrieval failed.");
+    }
+    return new EmailAttachmentError("attachment_provider_unavailable", false, "Email attachment retrieval is temporarily unavailable.");
+}
+function assertContentTypeAllowed(contentType, policy, phase) {
+    if (!contentType) {
+        return;
+    }
+    const normalized = contentType.split(";", 1)[0].trim().toLowerCase();
+    if (policy.denyContentTypes.some((pattern) => contentTypeMatches(normalized, pattern))) {
+        throw new EmailAttachmentError(`attachment_${phase}_content_type_denied`, true, "The attachment content type is denied by source policy.");
+    }
+    if (policy.allowContentTypes.length > 0
+        && !policy.allowContentTypes.some((pattern) => contentTypeMatches(normalized, pattern))) {
+        throw new EmailAttachmentError(`attachment_${phase}_content_type_not_allowed`, true, "The attachment content type is not allowed by source policy.");
+    }
+}
+function contentTypeMatches(contentType, pattern) {
+    return pattern.endsWith("/*")
+        ? contentType.startsWith(pattern.slice(0, -1))
+        : contentType === pattern;
+}
+async function hashFile(filePath) {
+    const hash = node_crypto_1.default.createHash("sha256");
+    const stream = node_fs_1.default.createReadStream(filePath);
+    for await (const chunk of stream) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+function syncFile(filePath) {
+    const fd = node_fs_1.default.openSync(filePath, "r");
+    try {
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+function syncDirectory(directoryPath) {
+    const fd = node_fs_1.default.openSync(directoryPath, "r");
+    try {
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+function detectContentType(filePath) {
+    const fd = node_fs_1.default.openSync(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(512);
+        const bytes = node_fs_1.default.readSync(fd, buffer, 0, buffer.length, 0);
+        const header = buffer.subarray(0, bytes);
+        if (header.subarray(0, 5).toString("ascii") === "%PDF-") {
+            return "application/pdf";
+        }
+        if (header.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+            return "image/png";
+        }
+        if (header[0] === 0xff && header[1] === 0xd8 && header[2] === 0xff) {
+            return "image/jpeg";
+        }
+        const gif = header.subarray(0, 6).toString("ascii");
+        if (gif === "GIF87a" || gif === "GIF89a") {
+            return "image/gif";
+        }
+        if (header[0] === 0x50 && header[1] === 0x4b && header[2] === 0x03 && header[3] === 0x04) {
+            return "application/zip";
+        }
+        if (header.length > 0 && !header.includes(0) && Buffer.from(header.toString("utf8"), "utf8").equals(header)) {
+            return "text/plain";
+        }
+        return "application/octet-stream";
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : null;
+}
+function optionalInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+function safeAuditAttachmentRef(attachmentRef) {
+    return /^att_v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{22}$/.test(attachmentRef)
+        ? attachmentRef
+        : "invalid_attachment_ref";
+}
+function stableAttachmentErrorCode(value, fallback) {
+    return typeof value === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(value)
+        ? value
+        : fallback;
+}
+function auditErrorCode(error) {
+    if (error instanceof EmailAttachmentError) {
+        return error.code;
+    }
+    if (error instanceof Error && error.message.startsWith("unknown inbox attachment:")) {
+        return "attachment_not_found";
+    }
+    return "attachment_operation_failed";
+}
+function positiveIntegerOrDefault(value, fallback) {
+    const parsed = typeof value === "string" && value.trim().length > 0
+        ? Number(value)
+        : value;
+    return Number.isSafeInteger(parsed) && Number(parsed) > 0
+        ? Number(parsed)
+        : fallback;
+}