@awiki/dsh-plugin 0.3.5 → 0.3.6

package/lib/types/index.js

@@ -34,6 +34,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     done = true;
 };
 import { Context } from '@deepseek-ai/cordis';
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
@@ -44,7 +45,7 @@ import { AWIKI_CLEAR_LOCAL_DATA_CONFIRMATION, AWIKI_LOGOUT_CONFIRMATION } from "
 import { AwikiExternalHttpAuthError, createAwikiExternalHttpAuth, externalHttpAuthError, mapProviderError as mapExternalHttpProviderError, } from "./external-http-auth.js";
 import { downloadedAttachment } from "./sdk-adapter.js";
 import { registerAwikiTools } from "./tools.js";
-import { mailInboxRequest, mailMarkReadRequest, mailReadRequest, mailSendRequest, } from "./mail.js";
+import { MAIL_ATTACHMENT_SERVICE_MAX_BYTES, MAIL_ATTACHMENT_SERVICE_MAX_COUNT, MAIL_ATTACHMENT_SERVICE_TOTAL_MAX_BYTES, mailAttachmentDownloadRequest, mailAttachmentContentType, mailAttachmentFileName, mailInboxRequest, mailMarkReadRequest, mailReadRequest, mailSendRequest, } from "./mail.js";
 import { AwikiSettingsSchema, validateAwikiSettings, } from "./settings.js";
 import { AWIKI_SETTINGS_NAMESPACE, DEFAULT_AWIKI_DOMAIN, normalizeAwikiDomain } from "./domain.js";
 import { AWIKI_SETTINGS_RPC_CHANNEL } from "./settings-rpc-contract.js";
@@ -54,7 +55,7 @@ import { AwikiImageAttachmentCache, minimumImageAttachmentCacheMaxBytes } from "
 import { AwikiSentMailStore, isLocalSentMailId } from "./sent-mail-store.js";
 import { AwikiConversationPreferenceStore, normalizeConversationPreferenceMutation, } from "./conversation-preferences.js";
 import { AwikiAgentListener, DshAwikiListenerAgentRuntime, } from "./listener.js";
-import { resolveAwikiProfileName, resolveAwikiStateRoot } from "./profile-state.js";
+import { resolveAwikiProfileName, resolveAwikiStateRoot, resolveAwikiTenantStateRoot, } from "./profile-state.js";
 export { AWIKI_CLEAR_LOCAL_DATA_CONFIRMATION, AWIKI_LOGOUT_CONFIRMATION } from "./types.js";
 export { AWIKI_EXTERNAL_HTTP_MAX_BODY_BYTES, AwikiExternalHttpAuthError, } from "./external-http-auth.js";
 export { AWIKI_DOMAIN_FIELD, AWIKI_SETTINGS_NAMESPACE, AwikiSettingsSchema, DEFAULT_AWIKI_DOMAIN, normalizeAwikiDomain, validateAwikiSettings, } from "./settings.js";
@@ -75,16 +76,19 @@ export const DEFAULT_SUMMARY_MAX_INPUT_BYTES = 32 * 1024;
 export const MAX_SUMMARY_MESSAGES = 50;
 /** Loader schema for the Host deployment configuration. */
 export const Config = z.object({
-    userServiceUrl: z.string().default(DEFAULT_AWIKI_SERVICE_URL),
+    userServiceUrl: z.string(),
     userServiceDomain: z.string().default(DEFAULT_AWIKI_DOMAIN),
-    messageServiceUrl: z.string().default(DEFAULT_AWIKI_SERVICE_URL),
+    messageServiceUrl: z.string(),
     mailServiceUrl: z.string(),
-    messageServicePublicUrl: z.string().default(DEFAULT_AWIKI_SERVICE_URL),
-    messageServiceDid: z.string().default(DEFAULT_AWIKI_MESSAGE_SERVICE_DID),
+    messageServicePublicUrl: z.string(),
+    messageServiceDid: z.string(),
     allowedAttachmentOrigins: z.array(z.string()).default([]),
     allowInsecureLoopbackForTesting: z.boolean().default(false),
     stateRoot: z.string(),
     attachmentMaxBytes: z.number().default(DEFAULT_ATTACHMENT_MAX_BYTES),
+    mailAttachmentMaxCount: z.number().default(MAIL_ATTACHMENT_SERVICE_MAX_COUNT),
+    mailAttachmentMaxBytes: z.number().default(MAIL_ATTACHMENT_SERVICE_MAX_BYTES),
+    mailAttachmentTotalMaxBytes: z.number().default(MAIL_ATTACHMENT_SERVICE_TOTAL_MAX_BYTES),
     imageAttachmentCacheMaxBytes: z.number().default(DEFAULT_IMAGE_ATTACHMENT_CACHE_MAX_BYTES),
     pollIntervalMs: z.number().default(DEFAULT_POLL_INTERVAL_MS),
     listenerEnabled: z.boolean().default(false),
@@ -250,6 +254,24 @@ function resolveConfig(ctx, config) {
     if (!Number.isSafeInteger(attachmentMaxBytes) || attachmentMaxBytes < 1) {
         throw new TypeError('awiki: attachmentMaxBytes must be a positive safe integer');
     }
+    const mailAttachmentMaxCount = config.mailAttachmentMaxCount ?? MAIL_ATTACHMENT_SERVICE_MAX_COUNT;
+    if (!Number.isSafeInteger(mailAttachmentMaxCount)
+        || mailAttachmentMaxCount < 0
+        || mailAttachmentMaxCount > MAIL_ATTACHMENT_SERVICE_MAX_COUNT) {
+        throw new TypeError('awiki: mailAttachmentMaxCount must be an integer from 0 through 10');
+    }
+    const mailAttachmentMaxBytes = config.mailAttachmentMaxBytes ?? MAIL_ATTACHMENT_SERVICE_MAX_BYTES;
+    if (!Number.isSafeInteger(mailAttachmentMaxBytes)
+        || mailAttachmentMaxBytes < 1
+        || mailAttachmentMaxBytes > MAIL_ATTACHMENT_SERVICE_MAX_BYTES) {
+        throw new TypeError('awiki: mailAttachmentMaxBytes must be a positive safe integer no greater than 10 MiB');
+    }
+    const mailAttachmentTotalMaxBytes = config.mailAttachmentTotalMaxBytes ?? MAIL_ATTACHMENT_SERVICE_TOTAL_MAX_BYTES;
+    if (!Number.isSafeInteger(mailAttachmentTotalMaxBytes)
+        || mailAttachmentTotalMaxBytes < mailAttachmentMaxBytes
+        || mailAttachmentTotalMaxBytes > MAIL_ATTACHMENT_SERVICE_TOTAL_MAX_BYTES) {
+        throw new TypeError('awiki: mailAttachmentTotalMaxBytes must cover one attachment and not exceed 18 MiB');
+    }
     const imageAttachmentCacheMaxBytes = config.imageAttachmentCacheMaxBytes ?? DEFAULT_IMAGE_ATTACHMENT_CACHE_MAX_BYTES;
     if (!Number.isSafeInteger(imageAttachmentCacheMaxBytes)
         || imageAttachmentCacheMaxBytes < minimumImageAttachmentCacheMaxBytes(attachmentMaxBytes)) {
@@ -274,6 +296,7 @@ function resolveConfig(ctx, config) {
     const mailServiceUrl = serviceUrl('mailServiceUrl', config.mailServiceUrl ?? userServiceUrl, allowInsecureLoopbackForTesting);
     const messageServicePublicUrl = serviceUrl('messageServicePublicUrl', config.messageServicePublicUrl ?? DEFAULT_AWIKI_SERVICE_URL, allowInsecureLoopbackForTesting);
     return {
+        tenantDomain: serviceDomain(config.userServiceDomain ?? DEFAULT_AWIKI_DOMAIN),
         userServiceUrl,
         userServiceDomain: serviceDomain(config.userServiceDomain ?? DEFAULT_AWIKI_DOMAIN),
         messageServiceUrl,
@@ -284,6 +307,9 @@ function resolveConfig(ctx, config) {
         allowInsecureLoopbackForTesting,
         stateRoot,
         attachmentMaxBytes,
+        mailAttachmentMaxCount,
+        mailAttachmentMaxBytes,
+        mailAttachmentTotalMaxBytes,
         imageAttachmentCacheMaxBytes,
         pollIntervalMs,
         ...profileName === undefined ? {} : { profileName, legacySharedStateDetected },
@@ -294,6 +320,42 @@ function resolveConfig(ctx, config) {
             stateRoot,
         },
         summaryMaxInputBytes,
+        deriveUserServiceUrl: config.userServiceUrl === undefined,
+        deriveMessageServiceUrl: config.messageServiceUrl === undefined,
+        deriveMailServiceUrl: config.mailServiceUrl === undefined,
+        deriveMessageServicePublicUrl: config.messageServicePublicUrl === undefined,
+        deriveMessageServiceDid: config.messageServiceDid === undefined,
+        deriveAllowedAttachmentOrigins: config.allowedAttachmentOrigins === undefined
+            || config.allowedAttachmentOrigins.length === 0,
+    };
+}
+/** Resolve every tenant-sensitive endpoint and state path from one selected domain. */
+function activeTenantConfig(config, domain) {
+    const tenantOrigin = `https://${domain}`;
+    const userServiceUrl = config.deriveUserServiceUrl ? tenantOrigin : config.userServiceUrl;
+    const messageServiceUrl = config.deriveMessageServiceUrl ? tenantOrigin : config.messageServiceUrl;
+    const mailServiceUrl = config.deriveMailServiceUrl ? userServiceUrl : config.mailServiceUrl;
+    const messageServicePublicUrl = config.deriveMessageServicePublicUrl
+        ? tenantOrigin
+        : config.messageServicePublicUrl;
+    const messageServiceDid = config.deriveMessageServiceDid
+        ? `did:wba:${domain}`
+        : config.messageServiceDid;
+    const allowedAttachmentOrigins = config.deriveAllowedAttachmentOrigins
+        ? attachmentOrigins(undefined, messageServicePublicUrl, config.allowInsecureLoopbackForTesting)
+        : config.allowedAttachmentOrigins;
+    return {
+        domain,
+        userServiceUrl,
+        userServiceDomain: domain,
+        messageServiceUrl,
+        mailServiceUrl,
+        messageServicePublicUrl,
+        messageServiceDid,
+        allowedAttachmentOrigins,
+        attachmentMaxBytes: config.attachmentMaxBytes,
+        allowInsecureLoopbackForTesting: config.allowInsecureLoopbackForTesting,
+        stateRoot: resolveAwikiTenantStateRoot(config.stateRoot, domain, config.userServiceDomain),
     };
 }
 /** Return a public, fixed-message failure without retaining a thrown value. */
@@ -708,6 +770,7 @@ let AwikiService = (() => {
     let _readMail_decorators;
     let _markMailRead_decorators;
     let _sendMail_decorators;
+    let _downloadMailAttachment_decorators;
     let _clearLocalData_decorators;
     return class AwikiService extends _classSuper {
         static {
@@ -753,6 +816,7 @@ let AwikiService = (() => {
             _readMail_decorators = [Remote];
             _markMailRead_decorators = [Remote];
             _sendMail_decorators = [Remote];
+            _downloadMailAttachment_decorators = [Remote];
             _clearLocalData_decorators = [Remote];
             __esDecorate(this, null, _getConfig_decorators, { kind: "method", name: "getConfig", static: false, private: false, access: { has: obj => "getConfig" in obj, get: obj => obj.getConfig }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getIdentity_decorators, { kind: "method", name: "getIdentity", static: false, private: false, access: { has: obj => "getIdentity" in obj, get: obj => obj.getIdentity }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -795,16 +859,15 @@ let AwikiService = (() => {
             __esDecorate(this, null, _readMail_decorators, { kind: "method", name: "readMail", static: false, private: false, access: { has: obj => "readMail" in obj, get: obj => obj.readMail }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _markMailRead_decorators, { kind: "method", name: "markMailRead", static: false, private: false, access: { has: obj => "markMailRead" in obj, get: obj => obj.markMailRead }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendMail_decorators, { kind: "method", name: "sendMail", static: false, private: false, access: { has: obj => "sendMail" in obj, get: obj => obj.sendMail }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _downloadMailAttachment_decorators, { kind: "method", name: "downloadMailAttachment", static: false, private: false, access: { has: obj => "downloadMailAttachment" in obj, get: obj => obj.downloadMailAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _clearLocalData_decorators, { kind: "method", name: "clearLocalData", static: false, private: false, access: { has: obj => "clearLocalData" in obj, get: obj => obj.clearLocalData }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        static inject = ['tools'];
+        static inject = ['tools', 'settings'];
         static Config = Config;
         resolved = __runInitializers(this, _instanceExtraInitializers);
-        sessionStore;
-        imageAttachmentCache;
-        sentMailStore;
-        conversationPreferenceStore;
+        tenantConfigCache;
+        tenantStateCache;
         startupUserServiceDomain;
         settingsProvider;
         provider;
@@ -828,27 +891,21 @@ let AwikiService = (() => {
             this.hostContext = ctx;
             this.resolved = resolveConfig(ctx, config);
             this.externalHttpAuth = createAwikiExternalHttpAuth(() => this.acquireExternalHttpAuthSession());
-            this.sessionStore = new AwikiSessionStore(this.resolved.stateRoot);
-            this.imageAttachmentCache = new AwikiImageAttachmentCache(this.resolved.stateRoot, this.resolved.attachmentMaxBytes, this.resolved.imageAttachmentCacheMaxBytes);
-            this.sentMailStore = new AwikiSentMailStore(this.resolved.stateRoot);
-            this.conversationPreferenceStore = new AwikiConversationPreferenceStore(this.resolved.stateRoot);
             this.startupUserServiceDomain = this.resolved.userServiceDomain;
-            ctx.inject(['settings'], (settingsCtx) => {
-                const provider = settingsCtx.settings;
-                const settingsScope = settingsCtx.settings.register(settingsNamespace(AWIKI_SETTINGS_NAMESPACE), AwikiSettingsSchema, {
-                    base: { domain: this.resolved.userServiceDomain },
-                    applies: 'restart',
-                    validate: validateAwikiSettings,
-                });
-                this.settingsProvider = provider;
-                this.startupUserServiceDomain = settingsScope.get().domain;
-                settingsCtx.effect(() => () => {
-                    if (this.settingsProvider === provider) {
-                        this.settingsProvider = undefined;
-                        this.startupUserServiceDomain = this.resolved.userServiceDomain;
-                    }
-                }, 'awiki: release settings namespace');
+            const provider = ctx.settings;
+            const settingsScope = provider.register(settingsNamespace(AWIKI_SETTINGS_NAMESPACE), AwikiSettingsSchema, {
+                base: { domain: this.resolved.userServiceDomain },
+                applies: 'restart',
+                validate: validateAwikiSettings,
             });
+            this.settingsProvider = provider;
+            this.startupUserServiceDomain = settingsScope.get().domain;
+            ctx.effect(() => () => {
+                if (this.settingsProvider === provider) {
+                    this.settingsProvider = undefined;
+                    this.startupUserServiceDomain = this.resolved.userServiceDomain;
+                }
+            }, 'awiki: release settings namespace');
             ctx.inject(['connection'], (connectionCtx) => {
                 connectionCtx.connection.rpc.handle(AWIKI_SETTINGS_RPC_CHANNEL, createAwikiSettingsRpcHandler(() => this.settingsProvider), { authority: 'loopback' });
             });
@@ -886,18 +943,7 @@ let AwikiService = (() => {
         registerClientFactory(factory) {
             if (this.provider !== undefined)
                 throw new Error('awiki: a client provider is already registered');
-            const client = factory({
-                userServiceUrl: this.resolved.userServiceUrl,
-                userServiceDomain: this.startupUserServiceDomain,
-                messageServiceUrl: this.resolved.messageServiceUrl,
-                mailServiceUrl: this.resolved.mailServiceUrl,
-                messageServicePublicUrl: this.resolved.messageServicePublicUrl,
-                messageServiceDid: this.resolved.messageServiceDid,
-                allowedAttachmentOrigins: this.resolved.allowedAttachmentOrigins,
-                attachmentMaxBytes: this.resolved.attachmentMaxBytes,
-                allowInsecureLoopbackForTesting: this.resolved.allowInsecureLoopbackForTesting,
-                stateRoot: this.resolved.stateRoot,
-            });
+            const client = factory(this.activeTenant());
             const provider = {
                 client,
                 listenerRestartAttempt: 0,
@@ -949,8 +995,12 @@ let AwikiService = (() => {
             return Promise.resolve({
                 ok: true,
                 value: {
+                    tenantDomain: this.activeTenant().domain,
                     pollIntervalMs: this.resolved.pollIntervalMs,
                     attachmentMaxBytes: this.resolved.attachmentMaxBytes,
+                    mailAttachmentMaxCount: this.resolved.mailAttachmentMaxCount,
+                    mailAttachmentMaxBytes: this.resolved.mailAttachmentMaxBytes,
+                    mailAttachmentTotalMaxBytes: this.resolved.mailAttachmentTotalMaxBytes,
                     ...this.resolved.profileName === undefined ? {} : {
                         profileName: this.resolved.profileName,
                         legacySharedStateDetected: this.resolved.legacySharedStateDetected,
@@ -958,6 +1008,42 @@ let AwikiService = (() => {
                 },
             });
         }
+        activeTenant() {
+            const cached = this.tenantConfigCache;
+            if (cached !== undefined)
+                return cached;
+            const value = Object.freeze(activeTenantConfig(this.resolved, this.startupUserServiceDomain));
+            this.tenantConfigCache = value;
+            return value;
+        }
+        activeTenantState() {
+            const cached = this.tenantStateCache;
+            if (cached !== undefined)
+                return cached;
+            const tenant = this.activeTenant();
+            const value = Object.freeze({
+                domain: tenant.domain,
+                stateRoot: tenant.stateRoot,
+                sessionStore: new AwikiSessionStore(tenant.stateRoot),
+                imageAttachmentCache: new AwikiImageAttachmentCache(tenant.stateRoot, this.resolved.attachmentMaxBytes, this.resolved.imageAttachmentCacheMaxBytes),
+                sentMailStore: new AwikiSentMailStore(tenant.stateRoot),
+                conversationPreferenceStore: new AwikiConversationPreferenceStore(tenant.stateRoot),
+            });
+            this.tenantStateCache = value;
+            return value;
+        }
+        get sessionStore() {
+            return this.activeTenantState().sessionStore;
+        }
+        get imageAttachmentCache() {
+            return this.activeTenantState().imageAttachmentCache;
+        }
+        get sentMailStore() {
+            return this.activeTenantState().sentMailStore;
+        }
+        get conversationPreferenceStore() {
+            return this.activeTenantState().conversationPreferenceStore;
+        }
         /**
          * Read the deployment's identity status.
          * @returns The public deployment identity or `null`.
@@ -1042,7 +1128,7 @@ let AwikiService = (() => {
             const target = identityAccessTarget(request, this.startupUserServiceDomain);
             if (target === undefined)
                 return { ok: false, error: failure('invalid-request') };
-            const endpoint = new URL(`/.well-known/handle/${encodeURIComponent(target.localPart)}`, this.resolved.userServiceUrl);
+            const endpoint = new URL(`/.well-known/handle/${encodeURIComponent(target.localPart)}`, this.activeTenant().userServiceUrl);
             const abort = new AbortController();
             const timeout = setTimeout(() => { abort.abort(); }, 10_000);
             let response;
@@ -1496,7 +1582,7 @@ let AwikiService = (() => {
         }
         /** Return the deployment identity's public mailbox state. */
         getMailAccount() {
-            return this.run(client => client.getMailAccount());
+            return this.run(client => client.getMailAccount(), { bindMailOwner: true });
         }
         /** List one bounded mailbox page on explicit browser/tool demand. */
         async listMailInbox(request) {
@@ -1507,11 +1593,11 @@ let AwikiService = (() => {
             catch {
                 return { ok: false, error: failure('invalid-request') };
             }
-            return this.run(async (client) => {
+            return this.run(async (client, _provider, ownerDid) => {
                 if (normalized.folder !== 'sent')
                     return client.listMailInbox(normalized);
-                return this.sentMailStore.list(await this.ownerDid(client), normalized);
-            });
+                return this.sentMailStore.list(ownerDid, normalized);
+            }, { bindMailOwner: true });
         }
         /** Read one bounded plain-text mail message. */
         async readMail(request) {
@@ -1522,45 +1608,116 @@ let AwikiService = (() => {
             catch {
                 return { ok: false, error: failure('invalid-request') };
             }
-            return this.run(async (client) => {
+            return this.run(async (client, _provider, ownerDid) => {
                 if (!isLocalSentMailId(normalized.messageId))
                     return client.readMail(normalized);
-                const local = await this.sentMailStore.read(await this.ownerDid(client), normalized.messageId);
+                const local = await this.sentMailStore.read(ownerDid, normalized.messageId);
                 if (local === undefined) {
                     throw Object.assign(new Error('sent mail not found'), { name: 'AwikiSdkError', code: 'not-found' });
                 }
                 return local;
-            });
+            }, { bindMailOwner: true });
         }
         /** Mark explicitly selected mail messages read. Browser callers require an explicit click. */
         markMailRead(request) {
-            return this.runValidatedMail(() => mailMarkReadRequest(request), (client, normalized) => client.markMailRead(normalized));
+            return this.runValidatedMail(() => mailMarkReadRequest(request), (client, normalized) => client.markMailRead(normalized), { bindMailOwner: true });
         }
-        /** Send one plain-text mail once. Browser callers require an explicit confirmation. */
+        /** Send one mail once. Browser callers require an explicit confirmation. */
         async sendMail(request) {
             let normalized;
             try {
-                normalized = mailSendRequest(request);
+                normalized = mailSendRequest(request, {
+                    maxCount: this.resolved.mailAttachmentMaxCount,
+                    maxBytes: this.resolved.mailAttachmentMaxBytes,
+                    totalMaxBytes: this.resolved.mailAttachmentTotalMaxBytes,
+                });
             }
             catch {
                 return { ok: false, error: failure('invalid-request') };
             }
-            return this.run(async (client) => {
-                const result = await client.sendMail(normalized);
+            return this.run(async (client, _provider, ownerDid, assertActive) => {
+                const result = await client.sendMail({
+                    to: [...normalized.to],
+                    cc: [...normalized.cc],
+                    subject: normalized.subject,
+                    bodyText: normalized.bodyText,
+                    ...normalized.attachments.length === 0 ? {} : {
+                        attachments: normalized.attachments.map(attachment => ({
+                            fileName: attachment.fileName,
+                            contentType: attachment.contentType,
+                            bytes: attachment.bytes,
+                        })),
+                    },
+                });
+                assertActive();
                 if (!result.accepted)
                     return result;
+                const settled = normalized.attachments.length > 0
+                    && result.messageId === undefined
+                    && result.warnings.length < 100
+                    ? { ...result, warnings: [...result.warnings, 'Sent attachment download is unavailable because the service returned no message id.'] }
+                    : result;
                 try {
-                    const ownerDid = await this.ownerDid(client);
                     const account = await client.getMailAccount().catch(() => undefined);
-                    await this.sentMailStore.append(ownerDid, normalized, result, account);
-                    return result;
+                    assertActive();
+                    await this.sentMailStore.append(ownerDid, normalized, settled, account);
+                    assertActive();
+                    return settled;
                 }
                 catch {
-                    return result.warnings.length >= 100
-                        ? result
-                        : { ...result, warnings: [...result.warnings, 'Sent history could not be saved locally.'] };
+                    assertActive();
+                    return settled.warnings.length >= 100
+                        ? settled
+                        : { ...settled, warnings: [...settled.warnings, 'Sent history could not be saved locally.'] };
                 }
-            });
+            }, { bindMailOwner: true });
+        }
+        /** Download one mail attachment only after an explicit browser action. */
+        async downloadMailAttachment(request) {
+            let normalized;
+            try {
+                normalized = mailAttachmentDownloadRequest(request);
+            }
+            catch {
+                return { ok: false, error: failure('invalid-request') };
+            }
+            return this.run(async (client, _provider, ownerDid, assertActive) => {
+                let serviceMessageId = normalized.localMessageId;
+                if (isLocalSentMailId(serviceMessageId)) {
+                    const resolved = await this.sentMailStore.resolveAttachment(ownerDid, serviceMessageId, normalized.attachmentIndex);
+                    if (resolved === undefined) {
+                        throw Object.assign(new Error('sent mail attachment is unavailable'), {
+                            name: 'AwikiSdkError', code: 'not-found',
+                        });
+                    }
+                    serviceMessageId = resolved;
+                }
+                const value = await client.downloadMailAttachment({
+                    messageId: serviceMessageId,
+                    attachmentIndex: normalized.attachmentIndex,
+                });
+                assertActive();
+                if (!Number.isSafeInteger(value.sizeBytes) || value.sizeBytes < 0)
+                    throw new TypeError('invalid mail attachment size');
+                if (value.sizeBytes > this.resolved.mailAttachmentMaxBytes) {
+                    throw Object.assign(new Error('mail attachment exceeds Host limit'), {
+                        name: 'AwikiSdkError', code: 'attachment-too-large',
+                    });
+                }
+                if (!(value.bytes instanceof Uint8Array) || value.bytes.byteLength !== value.sizeBytes) {
+                    throw new TypeError('invalid mail attachment bytes');
+                }
+                const fileName = mailAttachmentFileName(value.fileName);
+                const contentType = mailAttachmentContentType(value.contentType);
+                const bytes = value.bytes;
+                return {
+                    fileName,
+                    contentType,
+                    sizeBytes: bytes.byteLength,
+                    sha256: createHash('sha256').update(bytes).digest('hex'),
+                    bytesBase64: Buffer.from(bytes).toString('base64'),
+                };
+            }, { bindMailOwner: true });
         }
         /**
          * Permanently remove the exact SDK-owned local state after an explicit browser acknowledgement.
@@ -1657,24 +1814,40 @@ let AwikiService = (() => {
         }
         /** Resolve and cache the owner binding required by private Host-side projections. */
         async ownerDid(client) {
-            const identity = this.activeIdentityDid === undefined ? await client.getIdentity() : undefined;
-            const ownerDid = this.activeIdentityDid ?? identity?.did;
+            const identity = await client.getIdentity();
+            const ownerDid = identity?.did;
             if (ownerDid === undefined) {
                 throw Object.assign(new Error('not registered'), { name: 'AwikiSdkError', code: 'not-registered' });
             }
+            if (this.activeIdentityDid !== undefined && this.activeIdentityDid !== ownerDid) {
+                throw new ProviderUnavailableError();
+            }
             this.activeIdentityDid = ownerDid;
             return ownerDid;
         }
         /** Invoke the current client and normalize every rejection to a public result. */
         async run(operation, options = {}) {
             try {
+                const sessionRevision = this.sessionRevision;
                 if (options.allowSignedOut !== true && await this.isSignedOut()) {
                     return { ok: false, error: failure('signed-out') };
                 }
                 const provider = this.provider;
                 if (provider === undefined)
                     throw new ProviderUnavailableError();
-                const value = await operation(provider.client);
+                const ownerDid = options.bindMailOwner === true
+                    ? await this.ownerDid(provider.client)
+                    : undefined;
+                const assertActive = () => {
+                    if (this.provider !== provider
+                        || (options.bindMailOwner === true && (this.sessionRevision !== sessionRevision
+                            || this.signedOut === true
+                            || this.activeIdentityDid !== ownerDid)))
+                        throw new ProviderUnavailableError();
+                };
+                assertActive();
+                const value = await operation(provider.client, provider, ownerDid, assertActive);
+                assertActive();
                 if (options.skipAttachmentByteValidation !== true && containsUnexpectedBinary(value, new Set())) {
                     return { ok: false, error: failure('remote') };
                 }
@@ -1685,7 +1858,7 @@ let AwikiService = (() => {
             }
         }
         /** Validate mail input before entering the provider and preserve fixed public failures. */
-        runValidatedMail(validate, operation) {
+        runValidatedMail(validate, operation, options = {}) {
             let request;
             try {
                 request = validate();
@@ -1693,7 +1866,7 @@ let AwikiService = (() => {
             catch {
                 return Promise.resolve({ ok: false, error: failure('invalid-request') });
             }
-            return this.run(client => operation(client, request));
+            return this.run(client => operation(client, request), options);
         }
         /** Read and cache the private Host-owned session marker. */
         async isSignedOut() {
@@ -1774,7 +1947,10 @@ let AwikiService = (() => {
                 if (!this.listenerFenceMatches(provider, workspaceContext, generation))
                     return;
                 const agents = new DshAwikiListenerAgentRuntime(workspaceContext, this.resolved.listener.workspacePath);
-                const listener = new AwikiAgentListener(source, agents, this.resolved.listener, logger);
+                const listener = new AwikiAgentListener(source, agents, {
+                    ...this.resolved.listener,
+                    stateRoot: this.activeTenant().stateRoot,
+                }, logger);
                 provider.listener = listener;
                 try {
                     await listener.start();