@awiki/dsh-plugin 0.3.17 → 0.3.19

package/lib/types/index.js

@@ -32,6 +32,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { TenantCapabilityCache } from "./tenant-capability-cache.js";
+import { backendAttachmentMaxBytes, projectBackendFeatures, projectBackendSnapshot, requireBackendFeature } from "./backend-capabilities.js";
 export { registerAwikiLoopbackRpc } from "./settings-transport.js";
 import { registerAwikiSettingsTransport } from "./settings-transport.js";
 import { registrationHandleLocalPart } from "./registration-policy.js";
@@ -115,6 +117,8 @@ export const Config = z.object({
     summaryMaxInputBytes: z.number().default(DEFAULT_SUMMARY_MAX_INPUT_BYTES),
 });
 const FAILURE_CODES = new Set([
+    'backend-not-supported',
+    'backend-unconfirmed',
     'client-version-unsupported',
     'not-registered',
     'signed-out',
@@ -132,6 +136,7 @@ const FAILURE_CODES = new Set([
     'state-in-use',
     'rate-limited',
     'group-membership-required',
+    'group-member-encryption-not-ready',
     'group-identity-stale',
     'attachment-too-large',
     'summary-unavailable',
@@ -154,6 +159,8 @@ const RESUMABLE_JOIN_PHASES = new Set([
     'approval_prepared',
 ]);
 const FAILURE_MESSAGES = {
+    'backend-not-supported': 'This server does not support this feature.',
+    'backend-unconfirmed': 'Server features are not confirmed yet. Please retry.',
     'client-version-unsupported': 'This AWiki plugin version is not supported by the active tenant. Update the plugin or switch tenants.',
     'not-registered': 'No AWiki identity is registered for this deployment.',
     'signed-out': 'This installation is signed out of AWiki.',
@@ -170,6 +177,7 @@ const FAILURE_MESSAGES = {
     'conflict': 'The AWiki operation conflicts with current state.',
     'state-in-use': 'AWiki data is already open in another client.',
     'rate-limited': 'The AWiki service rate-limited the request.',
+    'group-member-encryption-not-ready': 'The member has not prepared encrypted messaging.',
     'group-membership-required': 'The active AWiki identity is not a member of this group.',
     'group-identity-stale': 'The AWiki group identity binding is still recovering.',
     'attachment-too-large': 'The attachment exceeds this deployment\'s size limit.',
@@ -272,7 +280,7 @@ function publishedServiceBaseUrl(services, name, allowInsecureLoopbackForTesting
     if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate))
         return undefined;
     const value = candidate;
-    if (value.enabled !== true || typeof value.base_url !== 'string')
+    if (value.enabled !== true || value.protocol_version !== 1 || typeof value.base_url !== 'string')
         return undefined;
     try {
         const baseUrl = serviceUrl(`server-info.services.${name}.base_url`, value.base_url, allowInsecureLoopbackForTesting);
@@ -470,6 +478,10 @@ const MAX_PROFILE_TAGS = 5;
 const MAX_PROFILE_TAG_CHARACTERS = 30;
 const MAX_MESSAGE_CHARACTERS = 20_000;
 function normalizeCreateGroupRequest(request) {
+    if (request?.operationId !== undefined && (typeof request.operationId !== 'string' || !/^[a-zA-Z0-9_-]{1,100}$/.test(request.operationId)))
+        return undefined;
+    if (request?.encrypted !== undefined && typeof request.encrypted !== 'boolean')
+        return undefined;
     if (typeof request?.name !== 'string' || !Array.isArray(request.members))
         return undefined;
     const name = request.name.trim();
@@ -490,7 +502,7 @@ function normalizeCreateGroupRequest(request) {
         seen.add(member);
         members.push(member);
     }
-    return { name, members };
+    return { name, members, ...request.operationId === undefined ? {} : { operationId: request.operationId }, ...request.encrypted === undefined ? {} : { encrypted: request.encrypted } };
 }
 function normalizeMember(value) {
     if (typeof value !== 'string')
@@ -505,6 +517,24 @@ function normalizeGroupDid(value) {
         return undefined;
     return value;
 }
+function validAvatarRequest(request, image) {
+    if (request === null || typeof request !== 'object' || Array.isArray(request))
+        return false;
+    const value = request;
+    const keys = image ? ['requestId', 'expectedProfileVersion', 'imageBase64'] : ['requestId', 'expectedProfileVersion'];
+    if (Object.keys(value).length !== keys.length || Object.keys(value).some(key => !keys.includes(key)))
+        return false;
+    if (typeof value.requestId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value.requestId))
+        return false;
+    if (typeof value.expectedProfileVersion !== 'string' || !/^(0|[1-9][0-9]{0,18})$/u.test(value.expectedProfileVersion) || BigInt(value.expectedProfileVersion) > 9223372036854775807n)
+        return false;
+    if (!image)
+        return true;
+    if (typeof value.imageBase64 !== 'string' || value.imageBase64.length === 0 || value.imageBase64.length > 699052)
+        return false;
+    const bytes = Buffer.from(value.imageBase64, 'base64');
+    return bytes.length <= 512 * 1024 && bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216 && bytes[bytes.length - 2] === 255 && bytes[bytes.length - 1] === 217 && bytes.toString('base64') === value.imageBase64;
+}
 function normalizeProfileRequest(request) {
     if (typeof request?.displayName !== 'string' || typeof request.bio !== 'string' || !Array.isArray(request.tags))
         return undefined;
@@ -617,6 +647,8 @@ function identityAccessTarget(request, configuredDomain) {
     return { localPart, fullHandle: `${localPart}.${configuredDomain}` };
 }
 function normalizeSendTextRequest(request) {
+    if (request?.security !== undefined && request.security !== 'plain' && request.security !== 'e2ee-required')
+        return undefined;
     if (typeof request?.text !== 'string' || typeof request.idempotencyKey !== 'string'
         || !isMessageTarget(request.target))
         return undefined;
@@ -778,6 +810,7 @@ let AwikiService = (() => {
     let _classSuper = TypertRemoteService;
     let _instanceExtraInitializers = [];
     let _getConfig_decorators;
+    let _refreshBackendCapabilities_decorators;
     let _getIntegration_decorators;
     let _createIntegration_decorators;
     let _updateIntegration_decorators;
@@ -808,6 +841,8 @@ let AwikiService = (() => {
     let _prepareRootTransfer_decorators;
     let _confirmRootTransfer_decorators;
     let _updateDisplayName_decorators;
+    let _setAvatar_decorators;
+    let _clearAvatar_decorators;
     let _getProfile_decorators;
     let _updateProfile_decorators;
     let _sendRecoveryOtp_decorators;
@@ -820,6 +855,7 @@ let AwikiService = (() => {
     let _resolvePeer_decorators;
     let _createGroup_decorators;
     let _getGroup_decorators;
+    let _repairGroupSecurity_decorators;
     let _joinGroup_decorators;
     let _leaveGroup_decorators;
     let _getDisplayProfiles_decorators;
@@ -847,6 +883,7 @@ let AwikiService = (() => {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _getConfig_decorators = [Remote];
+            _refreshBackendCapabilities_decorators = [Remote];
             _getIntegration_decorators = [Remote];
             _createIntegration_decorators = [Remote];
             _updateIntegration_decorators = [Remote];
@@ -877,6 +914,8 @@ let AwikiService = (() => {
             _prepareRootTransfer_decorators = [Remote];
             _confirmRootTransfer_decorators = [Remote];
             _updateDisplayName_decorators = [Remote];
+            _setAvatar_decorators = [Remote];
+            _clearAvatar_decorators = [Remote];
             _getProfile_decorators = [Remote];
             _updateProfile_decorators = [Remote];
             _sendRecoveryOtp_decorators = [Remote];
@@ -889,6 +928,7 @@ let AwikiService = (() => {
             _resolvePeer_decorators = [Remote];
             _createGroup_decorators = [Remote];
             _getGroup_decorators = [Remote];
+            _repairGroupSecurity_decorators = [Remote];
             _joinGroup_decorators = [Remote];
             _leaveGroup_decorators = [Remote];
             _getDisplayProfiles_decorators = [Remote];
@@ -913,6 +953,7 @@ let AwikiService = (() => {
             _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, _refreshBackendCapabilities_decorators, { kind: "method", name: "refreshBackendCapabilities", static: false, private: false, access: { has: obj => "refreshBackendCapabilities" in obj, get: obj => obj.refreshBackendCapabilities }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getIntegration_decorators, { kind: "method", name: "getIntegration", static: false, private: false, access: { has: obj => "getIntegration" in obj, get: obj => obj.getIntegration }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _createIntegration_decorators, { kind: "method", name: "createIntegration", static: false, private: false, access: { has: obj => "createIntegration" in obj, get: obj => obj.createIntegration }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateIntegration_decorators, { kind: "method", name: "updateIntegration", static: false, private: false, access: { has: obj => "updateIntegration" in obj, get: obj => obj.updateIntegration }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -943,6 +984,8 @@ let AwikiService = (() => {
             __esDecorate(this, null, _prepareRootTransfer_decorators, { kind: "method", name: "prepareRootTransfer", static: false, private: false, access: { has: obj => "prepareRootTransfer" in obj, get: obj => obj.prepareRootTransfer }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _confirmRootTransfer_decorators, { kind: "method", name: "confirmRootTransfer", static: false, private: false, access: { has: obj => "confirmRootTransfer" in obj, get: obj => obj.confirmRootTransfer }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateDisplayName_decorators, { kind: "method", name: "updateDisplayName", static: false, private: false, access: { has: obj => "updateDisplayName" in obj, get: obj => obj.updateDisplayName }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setAvatar_decorators, { kind: "method", name: "setAvatar", static: false, private: false, access: { has: obj => "setAvatar" in obj, get: obj => obj.setAvatar }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _clearAvatar_decorators, { kind: "method", name: "clearAvatar", static: false, private: false, access: { has: obj => "clearAvatar" in obj, get: obj => obj.clearAvatar }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getProfile_decorators, { kind: "method", name: "getProfile", static: false, private: false, access: { has: obj => "getProfile" in obj, get: obj => obj.getProfile }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateProfile_decorators, { kind: "method", name: "updateProfile", static: false, private: false, access: { has: obj => "updateProfile" in obj, get: obj => obj.updateProfile }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendRecoveryOtp_decorators, { kind: "method", name: "sendRecoveryOtp", static: false, private: false, access: { has: obj => "sendRecoveryOtp" in obj, get: obj => obj.sendRecoveryOtp }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -955,6 +998,7 @@ let AwikiService = (() => {
             __esDecorate(this, null, _resolvePeer_decorators, { kind: "method", name: "resolvePeer", static: false, private: false, access: { has: obj => "resolvePeer" in obj, get: obj => obj.resolvePeer }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _createGroup_decorators, { kind: "method", name: "createGroup", static: false, private: false, access: { has: obj => "createGroup" in obj, get: obj => obj.createGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getGroup_decorators, { kind: "method", name: "getGroup", static: false, private: false, access: { has: obj => "getGroup" in obj, get: obj => obj.getGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _repairGroupSecurity_decorators, { kind: "method", name: "repairGroupSecurity", static: false, private: false, access: { has: obj => "repairGroupSecurity" in obj, get: obj => obj.repairGroupSecurity }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _joinGroup_decorators, { kind: "method", name: "joinGroup", static: false, private: false, access: { has: obj => "joinGroup" in obj, get: obj => obj.joinGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _leaveGroup_decorators, { kind: "method", name: "leaveGroup", static: false, private: false, access: { has: obj => "leaveGroup" in obj, get: obj => obj.leaveGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getDisplayProfiles_decorators, { kind: "method", name: "getDisplayProfiles", static: false, private: false, access: { has: obj => "getDisplayProfiles" in obj, get: obj => obj.getDisplayProfiles }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -997,6 +1041,15 @@ let AwikiService = (() => {
         tenantSwitching = false;
         tenantParticipants = new Set();
         activeCapabilities;
+        backendFeatures = {};
+        backendDiagnostics = {};
+        backendFeaturesTask;
+        backendFeaturesRevision = -1;
+        backendSubscriptions = new Map();
+        backendSubscriptionPending = new Set();
+        backendAttachmentLimit;
+        capabilityDiscoveryTask;
+        capabilityDiscoveryAt = 0;
         updatePolicyStatus;
         updatePolicyRequest;
         updatePolicyTask;
@@ -1097,6 +1150,7 @@ let AwikiService = (() => {
             registerAwikiTools(ctx, this);
             ctx.effect(() => async () => {
                 this.updatePolicyRequest?.abort();
+                this.stopBackendSubscriptions();
                 const provider = this.provider;
                 if (provider !== undefined)
                     await this.disposeProvider(provider);
@@ -1196,12 +1250,38 @@ let AwikiService = (() => {
             this.conversationPreferenceStore = new AwikiConversationPreferenceStore(options.stateRoot);
             this.mailListClient = new AwikiMailListClient(options.mailServiceUrl, this.externalHttpAuth);
             this.integrationClient = undefined;
+            this.stopBackendSubscriptions();
+            this.backendFeatures = {};
+            this.backendDiagnostics = {};
+            this.backendFeaturesRevision = -1;
+            this.backendFeaturesTask = undefined;
+            this.backendAttachmentLimit = undefined;
+            this.capabilityDiscoveryTask = undefined;
+            this.capabilityDiscoveryAt = 0;
             this.activeCapabilities = {
                 tenantId: tenant.tenantId,
                 generation: this.runtimeGeneration,
                 online: false,
                 handleRecoveryPhoneEnabled: false,
             };
+            const metadata = new TenantCapabilityCache(options.stateRoot, options.userServiceUrl).read(value => {
+                const services = {
+                    model_proxy: { enabled: true, protocol_version: 1, base_url: value.modelProxyBaseUrl },
+                    guest_gateway: { enabled: true, protocol_version: 1, base_url: value.guestGatewayBaseUrl },
+                };
+                const modelProxyBaseUrl = publishedServiceBaseUrl(services, 'model_proxy', this.resolved.allowInsecureLoopbackForTesting);
+                const guestGatewayBaseUrl = publishedServiceBaseUrl(services, 'guest_gateway', false);
+                return {
+                    handleRecoveryPhoneEnabled: value.handleRecoveryPhoneEnabled,
+                    ...modelProxyBaseUrl === undefined ? {} : { modelProxyBaseUrl },
+                    ...guestGatewayBaseUrl === undefined ? {} : { guestGatewayBaseUrl },
+                };
+            });
+            if (metadata !== undefined) {
+                this.activeCapabilities = { ...this.activeCapabilities, ...metadata, online: true };
+                this.integrationClient = metadata.guestGatewayBaseUrl === undefined ? undefined
+                    : new AwikiIntegrationClient(metadata.guestGatewayBaseUrl, this.externalHttpAuth);
+            }
             this.signedOut = undefined;
             this.activeIdentityDid = undefined;
             this.pendingDeviceJoin = undefined;
@@ -1380,6 +1460,12 @@ let AwikiService = (() => {
             let committed = false;
             try {
                 await this.sessionMutation;
+                // Lock both scopes before disposal/open. A crash or rollback must not log in.
+                await this.sessionStore.signOut();
+                this.signedOut = true;
+                this.sessionRevision += 1;
+                this.activeIdentityDid = undefined;
+                await new AwikiSessionStore(registry.stateRoot(target)).signOut();
                 this.invalidateSummaries();
                 for (const participant of this.tenantParticipants) {
                     await participant.prepareSwitch(context);
@@ -1390,8 +1476,14 @@ let AwikiService = (() => {
                 targetOpened = true;
                 // The factory returns an adapter immediately; its native Core opens asynchronously.
                 // A local identity read proves both open and Registry loading before committing the switch.
-                await targetProvider.client.getIdentity();
-                await Promise.all([this.discoverTenantCapabilities(3_000), this.refreshUpdatePolicy()]);
+                const targetIdentity = await targetProvider.client.getIdentity();
+                if (targetIdentity === null) {
+                    // An empty scope has no session to restore. Keep the normal registration
+                    // entry available; only scopes with retained credentials need the lock.
+                    await this.sessionStore.signIn();
+                    this.signedOut = false;
+                }
+                void Promise.all([this.refreshTenantCapabilities(), this.refreshUpdatePolicy()]).catch(() => undefined);
                 registry.commitActive(target.tenantId);
                 committed = true;
                 for (const participant of prepared)
@@ -1491,17 +1583,22 @@ let AwikiService = (() => {
          */
         async getConfig() {
             this.ensureTenantOptions();
-            const capabilities = await this.discoverTenantCapabilities(10_000);
-            if (this.tenantSwitching
-                || capabilities.generation !== this.runtimeGeneration
-                || capabilities.tenantId !== this.activeTenant?.tenantId) {
+            const requestedGeneration = this.runtimeGeneration;
+            if (requestedGeneration !== this.runtimeGeneration)
                 return { ok: false, error: failure('conflict') };
-            }
+            // Config and local session/history reads never join discovery's network wait.
+            const capabilities = this.activeCapabilities;
+            this.refreshBackendProjection();
+            void this.refreshTenantCapabilities(false).catch(() => undefined);
+            const serverFeatures = this.backendFeatures;
+            const attachmentMaxBytes = this.backendAttachmentLimit ?? this.resolved.attachmentMaxBytes;
             return {
                 ok: true,
                 value: {
+                    serverFeatures,
+                    serverFeatureDiagnostics: this.backendDiagnostics,
                     pollIntervalMs: this.resolved.pollIntervalMs,
-                    attachmentMaxBytes: this.resolved.attachmentMaxBytes,
+                    attachmentMaxBytes,
                     mailAttachmentMaxCount: this.resolved.mailAttachmentMaxCount,
                     mailAttachmentMaxBytes: Math.min(this.resolved.mailAttachmentMaxBytes, MAIL_HTTP_UPLOAD_MAX_BYTES),
                     mailAttachmentDownloadMaxBytes: this.resolved.mailAttachmentMaxBytes,
@@ -1511,6 +1608,7 @@ let AwikiService = (() => {
                         ? {}
                         : { integrationGuideUrl: new URL('/guest/guide/integration', capabilities.guestGatewayBaseUrl).toString() },
                     tenantId: capabilities.tenantId,
+                    tenantStorageScopeId: this.activeTenant.storageScopeId,
                     tenantGeneration: capabilities.generation,
                     tenantOnline: capabilities.online,
                     services: {
@@ -1520,6 +1618,15 @@ let AwikiService = (() => {
                 },
             };
         }
+        /** Explicit discovery retry; ordinary config reads retain their zero-argument contract. */
+        async refreshBackendCapabilities() {
+            this.ensureTenantOptions();
+            const generation = this.runtimeGeneration;
+            await Promise.allSettled([this.refreshTenantCapabilities(true), this.refreshBackendProjection(true)]);
+            if (generation !== this.runtimeGeneration)
+                return { ok: false, error: failure('conflict') };
+            return this.getConfig();
+        }
         /** Trusted same-process capability binding for optional tenant participants. */
         getTenantCapabilities() {
             const capabilities = this.activeCapabilities;
@@ -1528,9 +1635,124 @@ let AwikiService = (() => {
             return { ...capabilities };
         }
         /** Refresh the active tenant's optional service advertisement without affecting Core availability. */
-        refreshTenantCapabilities() {
+        refreshTenantCapabilities(force = true) {
             this.ensureTenantOptions();
-            return this.discoverTenantCapabilities(10_000);
+            if (this.capabilityDiscoveryTask !== undefined)
+                return this.capabilityDiscoveryTask;
+            if (!force && Date.now() - this.capabilityDiscoveryAt < 300_000 && this.activeCapabilities !== undefined)
+                return Promise.resolve(this.activeCapabilities);
+            const generation = this.runtimeGeneration;
+            const task = this.discoverTenantCapabilities(10_000).finally(() => {
+                if (this.runtimeGeneration === generation && this.capabilityDiscoveryTask === task) {
+                    this.capabilityDiscoveryTask = undefined;
+                    this.capabilityDiscoveryAt = Date.now();
+                }
+            });
+            this.capabilityDiscoveryTask = task;
+            return task;
+        }
+        refreshBackendProjection(force = false) {
+            const provider = this.provider;
+            if (provider === undefined)
+                return Promise.resolve();
+            if (this.backendFeaturesTask !== undefined)
+                return this.backendFeaturesTask;
+            const revision = this.sessionRevision;
+            const generation = this.runtimeGeneration;
+            if (this.backendFeaturesRevision !== revision) {
+                // Only public facts survive a sign-out or identity change in this tenant.
+                this.backendFeatures = Object.fromEntries(Object.entries(this.backendFeatures).filter(([key]) => key.includes('.')));
+                this.backendAttachmentLimit = undefined;
+                this.backendDiagnostics = this.backendDiagnostics.public === undefined ? {} : { public: this.backendDiagnostics.public };
+                this.backendFeaturesRevision = revision;
+            }
+            const current = () => provider === this.provider && revision === this.sessionRevision && generation === this.runtimeGeneration;
+            const task = (async () => {
+                const authenticated = !await this.isSignedOut() && await provider.client.getIdentity() !== null;
+                await Promise.all([false, ...(authenticated ? [true] : [])].map(async (local) => {
+                    try {
+                        this.observeBackendProjection(provider, local, current);
+                        const snapshot = await provider.client.backendCapabilities?.(local, force);
+                        if (!current())
+                            return;
+                        if (snapshot === undefined)
+                            return;
+                        // A subscribed source is authoritative: a query started before a
+                        // disable notification must never restore its older result.
+                        if (this.backendSubscriptions.has(local))
+                            return;
+                        this.recordBackendDiagnostics(local, snapshot);
+                        if (snapshot.status === 'unavailable')
+                            return;
+                        this.backendFeatures = { ...this.backendFeatures, ...projectBackendSnapshot(snapshot, local) };
+                        if (local)
+                            this.backendAttachmentLimit = backendAttachmentMaxBytes(snapshot, this.resolved.attachmentMaxBytes);
+                        if (this.backendFeatures['agents.managed_agents'] === 'unsupported')
+                            await this.detachAgentConsumer(provider);
+                        else if (this.backendFeatures['agents.managed_agents'] === 'supported')
+                            this.ensureAgentConsumer(provider);
+                    }
+                    catch (error) {
+                        // Preserve successful facts; auth failures keep their established category.
+                        if (current())
+                            this.ctx.logger('awiki-capabilities').debug('AWiki capability refresh failed: %s', error instanceof AwikiSdkError ? error.code : 'unavailable');
+                    }
+                }));
+            })().finally(() => { if (this.backendFeaturesTask === task)
+                this.backendFeaturesTask = undefined; });
+            this.backendFeaturesTask = task;
+            void task.catch(() => undefined);
+            return task;
+        }
+        recordBackendDiagnostics(local, snapshot) {
+            this.backendDiagnostics = { ...this.backendDiagnostics, [local ? 'message' : 'public']: {
+                    ...typeof snapshot.fetched_at === 'number' ? { fetchedAt: snapshot.fetched_at } : {},
+                    ...snapshot.refresh_error === undefined ? {} : { refreshError: snapshot.refresh_error },
+                } };
+        }
+        stopBackendSubscriptions() {
+            for (const subscription of this.backendSubscriptions.values())
+                subscription.stop();
+            this.backendSubscriptions.clear();
+            this.backendSubscriptionPending.clear();
+        }
+        observeBackendProjection(provider, local, current) {
+            const subscribe = provider.client.subscribeBackendCapabilities;
+            if (subscribe === undefined || this.backendSubscriptions.has(local) || this.backendSubscriptionPending.has(local))
+                return;
+            this.backendSubscriptionPending.add(local);
+            void (async () => {
+                const subscription = await subscribe.call(provider.client, local);
+                if (!current()) {
+                    subscription.stop();
+                    return;
+                }
+                this.backendSubscriptionPending.delete(local);
+                this.backendSubscriptions.set(local, subscription);
+                try {
+                    while (current()) {
+                        const state = await subscription.nextUpdate();
+                        if (state === null || !current())
+                            break;
+                        this.recordBackendDiagnostics(local, state.snapshot);
+                        if (state.snapshot.status === 'unavailable')
+                            continue;
+                        this.backendFeatures = { ...this.backendFeatures, ...projectBackendSnapshot(state.snapshot, local) };
+                        if (local)
+                            this.backendAttachmentLimit = backendAttachmentMaxBytes(state.snapshot, this.resolved.attachmentMaxBytes);
+                        if (this.backendFeatures['agents.managed_agents'] === 'unsupported')
+                            await this.detachAgentConsumer(provider);
+                        else if (this.backendFeatures['agents.managed_agents'] === 'supported')
+                            this.ensureAgentConsumer(provider);
+                    }
+                }
+                finally {
+                    subscription.stop();
+                    if (this.backendSubscriptions.get(local) === subscription)
+                        this.backendSubscriptions.delete(local);
+                }
+            })().catch(() => { if (current())
+                this.backendSubscriptionPending.delete(local); });
         }
         async discoverTenantCapabilities(timeoutMs) {
             const options = this.activeClientOptions;
@@ -1538,12 +1760,10 @@ let AwikiService = (() => {
             if (options === undefined || tenant === undefined)
                 throw new ProviderUnavailableError();
             const generation = this.runtimeGeneration;
-            const fallback = {
-                tenantId: tenant.tenantId,
-                generation,
-                online: false,
-                handleRecoveryPhoneEnabled: false,
-            };
+            const previous = this.activeCapabilities;
+            const fallback = previous?.tenantId === tenant.tenantId && previous.generation === generation
+                ? { ...previous }
+                : { tenantId: tenant.tenantId, generation, online: false, handleRecoveryPhoneEnabled: false };
             const publish = (capabilities) => {
                 if (this.runtimeGeneration === generation && this.activeTenant?.tenantId === tenant.tenantId) {
                     this.activeCapabilities = capabilities;
@@ -1558,6 +1778,7 @@ let AwikiService = (() => {
             try {
                 const endpoint = new URL('/user-service/v1/server-info', options.userServiceUrl);
                 endpoint.searchParams.set('client_platform', 'dsh');
+                endpoint.searchParams.set('capabilities_version', '1');
                 const response = await fetch(endpoint, {
                     method: 'GET',
                     headers: { accept: 'application/json', 'cache-control': 'no-store' },
@@ -1571,13 +1792,19 @@ let AwikiService = (() => {
                 const value = text === undefined ? undefined : JSON.parse(text);
                 if (typeof value !== 'object' || value === null || value.schema_version !== 1)
                     return publish(fallback);
+                const versioned = value.capabilities_version === 1;
+                if (!versioned) {
+                    if ('capabilities_version' in value)
+                        return publish({ tenantId: tenant.tenantId, generation, online: true, handleRecoveryPhoneEnabled: false });
+                    return publish(fallback);
+                }
                 const methods = value.identity?.handle_recovery?.methods;
-                const handleRecoveryPhoneEnabled = Array.isArray(methods) && methods.some((method) => (typeof method === 'object' && method !== null
+                const handleRecoveryPhoneEnabled = versioned && Array.isArray(methods) && methods.some((method) => (typeof method === 'object' && method !== null
                     && method.id === 'phone'
                     && method.enabled === true
                     && method.verification?.required === true
                     && method.verification?.type === 'sms_otp'));
-                const services = value.services;
+                const services = versioned ? value.services : undefined;
                 const modelProxyBaseUrl = publishedServiceBaseUrl(services, 'model_proxy', this.resolved.allowInsecureLoopbackForTesting);
                 const guestGatewayBaseUrl = publishedServiceBaseUrl(services, 'guest_gateway', false);
                 const capabilities = {
@@ -1588,6 +1815,15 @@ let AwikiService = (() => {
                     ...modelProxyBaseUrl === undefined ? {} : { modelProxyBaseUrl },
                     ...guestGatewayBaseUrl === undefined ? {} : { guestGatewayBaseUrl },
                 };
+                if (this.runtimeGeneration === generation && this.activeTenant?.tenantId === tenant.tenantId) {
+                    const saved = new TenantCapabilityCache(options.stateRoot, options.userServiceUrl).write({
+                        handleRecoveryPhoneEnabled,
+                        ...modelProxyBaseUrl === undefined ? {} : { modelProxyBaseUrl },
+                        ...guestGatewayBaseUrl === undefined ? {} : { guestGatewayBaseUrl },
+                    });
+                    if (!saved)
+                        this.ctx.logger('awiki-capabilities').debug('AWiki capability metadata persistence failed');
+                }
                 return publish(capabilities);
             }
             catch {
@@ -1670,11 +1906,6 @@ let AwikiService = (() => {
             return this.mutateSession(async () => {
                 if (await this.isSignedOut())
                     return { ok: true, value: { status: 'signed-out' } };
-                const identity = await this.run(client => client.getIdentity(), { allowSignedOut: true });
-                if (!identity.ok)
-                    return identity;
-                if (identity.value === null)
-                    return { ok: false, error: failure('not-registered') };
                 try {
                     await this.sessionStore.signOut();
                     this.signedOut = true;
@@ -1683,8 +1914,10 @@ let AwikiService = (() => {
                     const session = { status: 'signed-out' };
                     this.publishSession(session);
                     const provider = this.provider;
-                    if (provider !== undefined)
+                    if (provider !== undefined) {
                         await this.stopProviderRuntime(provider);
+                        await this.updateBackendDiscoveryLifecycle(provider, false);
+                    }
                     return { ok: true, value: session };
                 }
                 catch {
@@ -1708,8 +1941,10 @@ let AwikiService = (() => {
                     const session = { status: 'active', identity: identity.value };
                     this.publishSession(session);
                     const provider = this.provider;
-                    if (provider !== undefined)
+                    if (provider !== undefined) {
                         this.ensureProviderRuntime(provider);
+                        await this.updateBackendDiscoveryLifecycle(provider, true);
+                    }
                     return { ok: true, value: session };
                 }
                 catch {
@@ -1896,6 +2131,9 @@ let AwikiService = (() => {
                 const recoveries = await client.listPendingRecoveries();
                 const pendingRegistrations = await client.pendingIdentityRegistrations();
                 const creationMethods = await client.identityCreationMethods().catch(() => []);
+                const backend = await client.backendCapabilities?.(false);
+                const registrationHandleOnly = backend?.capabilities['registration.handle_only']?.support === 'supported'
+                    && (backend.status === 'confirmed' || backend.status === 'stale');
                 const identity = await client.getIdentity();
                 const capabilities = identity === null ? undefined : await client.identityMethodCapabilities(identity.did);
                 const domain = this.activeClientOptions?.userServiceDomain;
@@ -1909,6 +2147,7 @@ let AwikiService = (() => {
                     },
                     joining,
                     creationMethods,
+                    registrationHandleOnly,
                     pendingRegistrations,
                     ...capabilities === undefined ? {} : { methodCapabilities: capabilities },
                     recoveries: recoveries.filter(value => domain !== undefined && value.fullHandle.slice(value.fullHandle.indexOf('.') + 1) === domain),
@@ -2164,6 +2403,18 @@ let AwikiService = (() => {
                 this.activeIdentityDid = result.value.did;
             return result;
         }
+        /** Replace only the current authenticated human account's avatar. */
+        setAvatar(request) {
+            if (!validAvatarRequest(request, true))
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.setAvatar(request));
+        }
+        /** Restore the current account's default character avatar. */
+        clearAvatar(request) {
+            if (!validAvatarRequest(request, false))
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.clearAvatar(request));
+        }
         /** Return the public editable profile for the active identity. */
         getProfile() {
             return this.run(client => client.getProfile());
@@ -2255,7 +2506,14 @@ let AwikiService = (() => {
             const normalized = normalizeCreateGroupRequest(request);
             if (normalized === undefined)
                 return { ok: false, error: failure('invalid-request') };
-            const created = await this.run(client => client.createGroup(normalized.name));
+            const created = await this.run(async (client) => {
+                await requireBackendFeature(client, 'groups');
+                if (normalized.encrypted)
+                    await requireBackendFeature(client, 'group_e2ee');
+                if (normalized.members.length > 0)
+                    await requireBackendFeature(client, 'group_admin_add');
+                return client.createGroup(normalized.name, normalized.encrypted, normalized.operationId);
+            });
             if (!created.ok)
                 return created;
             const addedMembers = [];
@@ -2279,12 +2537,19 @@ let AwikiService = (() => {
                 return Promise.resolve({ ok: false, error: failure('invalid-request') });
             return this.run(client => client.getGroup(groupDid));
         }
+        /** Resume owner-held group encryption maintenance through Core. */
+        repairGroupSecurity(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            if (groupDid === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(async (client) => { await requireBackendFeature(client, 'group_e2ee'); return client.repairGroupSecurity(groupDid); });
+        }
         /** Join one open group and return its authoritative membership state. */
         joinGroup(request) {
             const groupDid = normalizeGroupDid(request?.groupDid);
             if (groupDid === undefined)
                 return Promise.resolve({ ok: false, error: failure('invalid-request') });
-            return this.run(client => client.joinGroup(groupDid));
+            return this.run(async (client) => { await requireBackendFeature(client, 'group_open_join'); return client.joinGroup(groupDid); });
         }
         /** Leave one group. Core rejects owner leave and unsupported security profiles. */
         async leaveGroup(request) {
@@ -2295,11 +2560,11 @@ let AwikiService = (() => {
             return result.ok ? { ok: true, value: { completed: true } } : result;
         }
         /** Read one authoritative versioned member page. */
-        getDisplayProfiles(peers) {
-            if (!Array.isArray(peers) || peers.length > 100 || peers.some(peer => typeof peer !== 'string' || !peer.startsWith('did:'))) {
+        getDisplayProfiles(peers, refresh) {
+            if ((refresh !== undefined && typeof refresh !== 'boolean') || !Array.isArray(peers) || peers.length > 100 || peers.some(peer => typeof peer !== 'string' || !peer.startsWith('did:'))) {
                 return Promise.resolve({ ok: false, error: failure('invalid-request') });
             }
-            return this.run(client => client.getDisplayProfiles(peers));
+            return this.run(client => client.getDisplayProfiles(peers, refresh));
         }
         listGroupMembers(request) {
             const groupDid = normalizeGroupDid(request?.groupDid);
@@ -2478,6 +2743,8 @@ let AwikiService = (() => {
          * @returns The accepted attachment message or a closed failure.
          */
         async sendAttachment(request) {
+            if (request?.security !== undefined && request.security !== 'plain' && request.security !== 'e2ee-required')
+                return { ok: false, error: failure('invalid-request') };
             if (!isMessageTarget(request?.target))
                 return { ok: false, error: failure('invalid-request') };
             const decoded = decodeAttachment(request.bytesBase64, this.resolved.attachmentMaxBytes);
@@ -2485,6 +2752,7 @@ let AwikiService = (() => {
                 return decoded;
             return this.run(async (client) => {
                 const message = await client.sendAttachment({
+                    ...request.security === undefined ? {} : { security: request.security },
                     target: request.target,
                     attachment: {
                         fileName: request.fileName,
@@ -2823,12 +3091,14 @@ let AwikiService = (() => {
             return client.getLocalDeviceJoinVerificationProgress(notice.joinSessionId);
         }
         async requireDeviceManager(client) {
+            await requireBackendFeature(client, 'identity.multi_device');
             const current = await client.getCurrentDeviceSummary();
             if (!current.canManage || current.role !== 'admin' || current.readiness !== 'admin_ready') {
                 throw Object.assign(new Error('device manager required'), { name: 'AwikiSdkError', code: 'forbidden' });
             }
         }
         async requireRootTransferRecipient(client, deviceId) {
+            await requireBackendFeature(client, 'identity.root_transfer');
             if (!client.trustedUserPresenceSupported) {
                 throw Object.assign(new Error('trusted user presence unsupported'), { name: 'AwikiSdkError', code: 'forbidden' });
             }
@@ -2961,6 +3231,7 @@ let AwikiService = (() => {
         }
         /** Invalidate cached session work and cancel every model request still owned by the old session. */
         invalidateSummaries() {
+            this.stopBackendSubscriptions();
             this.sessionRevision += 1;
             this.requestRefs.clear();
             this.requestSessions.clear();
@@ -3042,7 +3313,10 @@ let AwikiService = (() => {
             catch {
                 return Promise.resolve({ ok: false, error: failure('invalid-request') });
             }
-            return this.run(client => operation(client, request), options);
+            return this.run(async (client) => {
+                await requireBackendFeature(client, 'services.mail');
+                return operation(client, request);
+            }, options);
         }
         /** Read and cache the private Host-owned session marker. */
         async isSignedOut() {
@@ -3103,6 +3377,16 @@ let AwikiService = (() => {
             this.sessionMutation = pending.then(() => undefined, () => undefined);
             return pending;
         }
+        /** Discovery is an optional projection, not authority for a committed session transition. */
+        async updateBackendDiscoveryLifecycle(provider, active) {
+            try {
+                await provider.client.setBackendDiscoveryActive?.(active);
+            }
+            catch {
+                // Do not include bridge errors: provider diagnostics may contain private context.
+                this.ctx.logger('awiki-backend').warn('AWiki backend discovery lifecycle unavailable');
+            }
+        }
         /** Start identity realtime and the optional Agent consumer without blocking identity success. */
         ensureProviderRuntime(provider) {
             if (this.tenantSwitching)
@@ -3116,6 +3400,7 @@ let AwikiService = (() => {
                 this.replaceProviderRuntime(provider, identityDid);
                 return;
             }
+            this.refreshBackendProjection();
             this.ensureRealtimeSupervisor(provider);
             this.ensureAgentConsumer(provider);
         }
@@ -3222,6 +3507,9 @@ let AwikiService = (() => {
             const logger = this.ctx.logger('awiki-listener');
             const startup = (async () => {
                 await this.detachAgentConsumer(provider);
+                const features = await projectBackendFeatures(provider.client, false);
+                if (features['agents.managed_agents'] !== 'supported')
+                    return;
                 if (!this.agentConsumerFenceMatches(provider, workspaceContext, identityDid, generation))
                     return;
                 const agents = new DshAwikiListenerAgentRuntime(workspaceContext, this.resolved.listener.workspacePath);