@enbox/auth 0.6.32 → 0.6.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/auth",
-  "version": "0.6.32",
+  "version": "0.6.34",
   "description": "Headless authentication and identity management SDK for Enbox",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -37,6 +37,10 @@
     ".": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./auth-manager": {
+      "types": "./dist/types/auth-manager.d.ts",
+      "import": "./dist/esm/auth-manager.js"
     }
   },
   "keywords": [
@@ -56,12 +60,12 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@enbox/agent": "0.7.0",
-    "@enbox/common": "0.1.0",
-    "@enbox/crypto": "0.1.0",
-    "@enbox/dids": "0.1.0",
-    "@enbox/dwn-clients": "0.4.0",
-    "@enbox/dwn-sdk-js": "0.3.5",
+    "@enbox/agent": "0.7.2",
+    "@enbox/common": "0.1.1",
+    "@enbox/crypto": "0.1.1",
+    "@enbox/dids": "0.1.1",
+    "@enbox/dwn-clients": "0.4.1",
+    "@enbox/dwn-sdk-js": "0.3.6",
     "level": "8.0.1"
   },
   "devDependencies": {

package/src/auth-manager.ts

@@ -3,10 +3,19 @@
  *
  * Replaces `Enbox.connect()` (formerly `Web5.connect()`) with a composable,
  * multi-identity-aware auth system that works in both browser and CLI environments.
+ *
+ * NOTE: this file is also exposed as the `@enbox/auth/auth-manager` subpath
+ * export so `@enbox/api` can import the AuthManager class without pulling in
+ * the full barrel. The subpath is **internal to the monorepo** — external
+ * consumers should import from `@enbox/auth` (or `@enbox/browser`) instead;
+ * the subpath's file layout is not part of any stability guarantee.
+ *
+ * @internal
  * @module
  */
 
-import type { BearerIdentity, HdIdentityVault, PortableIdentity } from '@enbox/agent';
+import type { RecordsWriteMessage } from '@enbox/dwn-sdk-js';
+import type { AgentSessionIdentity, BearerIdentity, DwnDataEncodedRecordsWriteMessage, HdIdentityVault, PortableIdentity } from '@enbox/agent';
 
 import type { FlowContext } from './connect/lifecycle.js';
 import type { PasswordProvider } from './password-provider.js';
@@ -20,15 +29,14 @@ import type {
   DisconnectOptions,
   HandlerConnectOptions,
   HeadlessConnectOptions,
-  IdentityInfo,
   ImportFromPhraseOptions,
   ImportFromPortableOptions,
-  LocalConnectOptions,
   RegistrationOptions,
   RestoreSessionOptions,
   ShutdownOptions,
   StorageAdapter,
   SyncOption,
+  VaultConnectOptions,
   WalletConnectOptions,
 } from './types.js';
 
@@ -40,10 +48,10 @@ import { AuthEventEmitter } from './events.js';
 import { AuthSession } from './identity-session.js';
 import { createDefaultStorage } from './storage/storage.js';
 import { discoverLocalDwn } from './discovery.js';
-import { localConnect } from './connect/local.js';
 import { normalizeProtocolRequests } from './permissions.js';
 import { restoreSession } from './connect/restore.js';
 import { STORAGE_KEYS } from './types.js';
+import { vaultConnect } from './connect/vault.js';
 import { walletConnect } from './connect/wallet.js';
 import { deriveActiveSyncScope, ensureVaultReady, finalizeDelegateSession, importDelegateAndSetupSync, resolveIdentityDids, resolvePassword, startSyncIfEnabled, toSyncIdentityProtocols } from './connect/lifecycle.js';
 import { importFromPhrase, importFromPortable } from './connect/import.js';
@@ -241,27 +249,45 @@ export class AuthManager {
       const restored = await restoreSession(this._flowContext());
       if (restored) { return restored; }
 
-      // 2. Route to the appropriate flow.
-      if (this._isLocalConnect(options)) {
-        return localConnect(this._flowContext(), options as LocalConnectOptions);
+      // 2. Route to the appropriate flow. `_isVaultConnect` is a type guard
+      // so the two branches receive correctly narrowed `options` types
+      // without casts.
+      if (this._isVaultConnect(options)) {
+        return vaultConnect(this._flowContext(), options);
       }
 
-      return this._handlerConnect(options as HandlerConnectOptions | undefined);
+      return this._handlerConnect(options);
     });
   }
 
   /**
-   * Create or reconnect a local identity (explicit local connect).
+   * Create or reconnect a local identity (explicit vault connect).
    *
-   * Use this when you explicitly want the local vault flow, bypassing
+   * Use this when you explicitly want the vault flow, bypassing
    * auto-detection. This is the preferred method for wallet apps.
    *
-   * @param options - Local connect options.
+   * @param options - Vault connect options.
    * @returns An active AuthSession.
    * @throws If a connection attempt is already in progress.
+   * @deprecated Use {@link connectVault} instead. Will be removed in 1.0.
    */
-  async connectLocal(options?: LocalConnectOptions): Promise<AuthSession> {
-    return this._withConnect(() => localConnect(this._flowContext(), options));
+  async connectLocal(options?: VaultConnectOptions): Promise<AuthSession> {
+    return this.connectVault(options);
+  }
+
+  /**
+   * Create or reconnect an identity via the local HD vault.
+   *
+   * Use this when you explicitly want the vault flow, bypassing
+   * auto-detection. This is the preferred method for wallet apps
+   * and CLI tools that own the identity vault directly.
+   *
+   * @param options - Vault connect options.
+   * @returns An active AuthSession.
+   * @throws If a connection attempt is already in progress.
+   */
+  async connectVault(options?: VaultConnectOptions): Promise<AuthSession> {
+    return this._withConnect(() => vaultConnect(this._flowContext(), options));
   }
 
   /**
@@ -305,6 +331,7 @@ export class AuthManager {
    * This replaces the manual `previouslyConnected` localStorage pattern.
    */
   async restoreSession(options?: RestoreSessionOptions): Promise<AuthSession | undefined> {
+    this._guardShutdown();
     this._guardConcurrency();
     this._isConnecting = true;
 
@@ -345,6 +372,7 @@ export class AuthManager {
    * ```
    */
   async connectHeadless(options?: HeadlessConnectOptions): Promise<AuthSession> {
+    this._guardShutdown();
     let password = options?.password ?? this._defaultPassword;
     const isFirstLaunch = await this._userAgent.firstLaunch();
 
@@ -385,7 +413,7 @@ export class AuthManager {
 
     const { connectedDid, delegateDid } = resolveIdentityDids(identity);
 
-    const identityInfo: IdentityInfo = {
+    const identityInfo: AgentSessionIdentity = {
       didUri       : connectedDid,
       name         : identity.metadata.name,
       connectedDid : identity.metadata.connectedDid,
@@ -496,17 +524,17 @@ export class AuthManager {
                 messageType   : DwnInterface.RecordsRead,
                 messageParams : { filter: { recordId: grantId } },
               });
-              if (readReply.status.code !== 200 || !readReply.entry) { continue; }
+              if (readReply.status.code !== 200 || !readReply.entry?.recordsWrite) { continue; }
               // Reconstruct DwnDataEncodedRecordsWriteMessage: RecordsRead returns
               // data as a stream, but PermissionGrant.parse needs encodedData.
               const grantDataBytes = readReply.entry.data
                 ? await DataStream.toBytes(readReply.entry.data)
                 : new Uint8Array(0);
-              const grantMsgWithData = {
+              const grantMsgWithData: DwnDataEncodedRecordsWriteMessage = {
                 ...readReply.entry.recordsWrite,
                 encodedData: Convert.uint8Array(grantDataBytes).toBase64Url(),
               };
-              const grant = DwnPermissionGrant.parse(grantMsgWithData as any);
+              const grant = DwnPermissionGrant.parse(grantMsgWithData);
 
               // Self-healing: ensure the revocation grant is on the remote
               // DWN. The best-effort fanout at connect time may have failed.
@@ -519,7 +547,19 @@ export class AuthManager {
                     messageParams : { filter: { recordId: revocationGrantId } },
                   });
                   if (revGrantReply.status.code === 200 && revGrantReply.entry?.recordsWrite) {
-                    const { encodedData: revGrantEncoded, ...revGrantRaw } = revGrantReply.entry.recordsWrite as any;
+                    // Strip `encodedData` from the wire payload — the
+                    // bytes are sent via `data` (Blob) on the next line.
+                    // `RecordsWriteMessage` doesn't declare `encodedData`,
+                    // but the wire-format reply may include it; widen the
+                    // local type to acknowledge that without `any`.
+                    // NOSONAR S4325 false positive: the cast is required to
+                    // typecheck the destructuring of the undeclared
+                    // optional `encodedData` property; removing it fails
+                    // TS2339. Sonar reads the intersection-with-optional-
+                    // field as a no-op widening, which it isn't here.
+                    type RecordsWriteWireMessage = RecordsWriteMessage & { encodedData?: string };
+                    const { encodedData: _encoded, ...revGrantRaw } =
+                      revGrantReply.entry.recordsWrite as RecordsWriteWireMessage; // NOSONAR
                     const revGrantData = revGrantReply.entry.data
                       ? new Blob([await DataStream.toBytes(revGrantReply.entry.data) as BlobPart])
                       : undefined;
@@ -552,7 +592,7 @@ export class AuthManager {
               // delivery, the owner-side authority source won't see it.
               let remoteDelivered = false;
               if (revocationMessage && remoteDwnUrls.length > 0) {
-                const { encodedData, ...rawMessage } = revocationMessage as any;
+                const { encodedData, ...rawMessage } = revocationMessage;
                 const data = encodedData
                   ? new Blob([Convert.base64Url(encodedData).toUint8Array() as BlobPart])
                   : undefined;
@@ -783,7 +823,7 @@ export class AuthManager {
    * Each identity has a DID URI, name, and optional connected DID
    * (for wallet-connected/delegated identities).
    */
-  async listIdentities(): Promise<IdentityInfo[]> {
+  async listIdentities(): Promise<AgentSessionIdentity[]> {
     const identities = await this._userAgent.identity.list();
     return identities.map((identity: BearerIdentity) => ({
       didUri       : identity.did.uri,
@@ -815,7 +855,7 @@ export class AuthManager {
     await this._storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
     await this._storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
 
-    const identityInfo: IdentityInfo = {
+    const identityInfo: AgentSessionIdentity = {
       didUri       : connectedDid,
       name         : identity.metadata.name,
       connectedDid : identity.metadata.connectedDid,
@@ -952,47 +992,40 @@ export class AuthManager {
   // ─── Private helpers ───────────────────────────────────────────
 
   /**
-   * Determine whether the given options indicate a local connect flow.
+   * Determine whether the given options indicate a vault connect flow.
    *
-   * Local connect is indicated by the presence of `password`,
-   * `createIdentity`, or `recoveryPhrase` — signals that the caller
-   * is managing its own vault/identity lifecycle. In non-browser
-   * environments, local connect is the fallback.
+   * Handler intent is asserted by the presence of a non-empty `protocols`
+   * array OR a non-null `connectHandler`; everything else (including the
+   * no-options case, an empty `protocols: []`, and `null` values from JS
+   * callers) routes to vault connect. An empty `protocols` array is
+   * intentionally NOT a handler signal — it carries no permission scopes
+   * for the handler to authorize, so treating it as handler-flow would
+   * produce a zero-grant "connected" session indistinguishable from a
+   * denied connect.
+   *
+   * Acts as a TypeScript type guard: a `true` return narrows `options` to
+   * `VaultConnectOptions | undefined` at call sites, so the routing in
+   * {@link AuthManager.connect} can dispatch without unsafe casts.
    */
-  private _isLocalConnect(options?: ConnectOptions): boolean {
-    const o = (options ?? {}) as Record<string, unknown>;
-
-    // If any local-connect-specific keys are present, it's definitely local.
-    const hasLocalSignals = (
-      o.password !== undefined ||
-      o.createIdentity !== undefined ||
-      o.recoveryPhrase !== undefined ||
-      o.dwnEndpoints !== undefined ||
-      o.metadata !== undefined
-    );
-    if (hasLocalSignals) { return true; }
-
-    // If any handler-connect signals are present, use the handler flow.
-    const hasHandlerSignals = (
-      o.protocols !== undefined ||
-      o.connectHandler !== undefined
-    );
-    if (hasHandlerSignals) { return false; }
-
-    // No explicit signals → default to local connect.
-    // Callers that want handler-based connect must provide protocols
-    // or a connectHandler.
+  private _isVaultConnect(options?: ConnectOptions): options is VaultConnectOptions | undefined {
+    if (options === undefined || options === null) { return true; }
+    if ('protocols' in options && Array.isArray(options.protocols) && options.protocols.length > 0) { return false; }
+    if ('connectHandler' in options && options.connectHandler !== undefined && options.connectHandler !== null) { return false; }
     return true;
   }
 
   /**
    * Run a handler-based (delegated) connect flow.
    *
-   * 1. Initialize the vault (agent-only, no identity).
-   * 2. Normalize protocol permission requests.
-   * 3. Delegate to the connect handler for credential acquisition.
-   * 4. Import the delegate DID, process grants, set up sync.
-   * 5. Finalize and return the AuthSession.
+   * Handler resolution happens BEFORE any vault I/O so a misconfigured call
+   * (no handler reachable) fails fast without mutating on-disk state.
+   *
+   * 1. Resolve the connect handler (fast-fail when none is reachable).
+   * 2. Initialize the vault (agent-only, no identity).
+   * 3. Normalize protocol permission requests.
+   * 4. Delegate to the connect handler for credential acquisition.
+   * 5. Import the delegate DID, process grants, set up sync.
+   * 6. Finalize and return the AuthSession.
    */
   private async _handlerConnect(
     options?: HandlerConnectOptions,
@@ -1001,15 +1034,8 @@ export class AuthManager {
     const { userAgent, emitter, storage } = ctx;
     const sync = options?.sync ?? ctx.defaultSync;
 
-    // 1. Initialize vault (agent-only, no identity).
-    const isFirstLaunch = await userAgent.firstLaunch();
-    const password = await resolvePassword(ctx, undefined, isFirstLaunch);
-    await ensureVaultReady({ userAgent, emitter, password, isFirstLaunch });
-
-    // 2. Normalize protocol requests.
-    const permissionRequests = normalizeProtocolRequests(options?.protocols);
-
-    // 3. Resolve the handler.
+    // 1. Resolve the handler FIRST. Anything past this point may mutate the
+    //    vault on disk, so misconfiguration must fail before that happens.
     const handler = options?.connectHandler ?? this._connectHandler;
     if (!handler) {
       throw new Error(
@@ -1019,6 +1045,16 @@ export class AuthManager {
       );
     }
 
+    // 2. Initialize vault (agent-only, no identity). The per-call password
+    //    (when supplied via `HandlerConnectOptions.password`) wins over the
+    //    manager default, matching the behavior of the vault-connect flow.
+    const isFirstLaunch = await userAgent.firstLaunch();
+    const password = await resolvePassword(ctx, options?.password, isFirstLaunch);
+    await ensureVaultReady({ userAgent, emitter, password, isFirstLaunch });
+
+    // 3. Normalize protocol requests.
+    const permissionRequests = normalizeProtocolRequests(options?.protocols);
+
     // 4. Delegate to the handler.
     const result = await handler.requestAccess({ permissionRequests });
     if (!result) {
@@ -1033,14 +1069,22 @@ export class AuthManager {
     const identity = await importDelegateAndSetupSync({
       userAgent, delegatePortableDid, connectedDid, delegateGrants,
       delegateDecryptionKeys, delegateContextKeys, delegateMultiPartyProtocols,
-      sessionRevocations,
       flowName: 'Connect',
     });
 
-    // 6. Finalize session.
+    // 6. Finalize session. Pass the transient delegate state explicitly
+    // so `persistOrClearDelegateSecrets` doesn't need to read it back
+    // off the identity (which was the old `(identity as any)._foo`
+    // smuggling pattern).
     return finalizeDelegateSession({
       userAgent, emitter, storage, identity,
-      connectedDid, delegateDid: delegatePortableDid.uri, sync,
+      connectedDid, delegateDid   : delegatePortableDid.uri, sync,
+      delegateState : {
+        delegateDecryptionKeys,
+        delegateContextKeys,
+        delegateMultiPartyProtocols,
+        sessionRevocations,
+      },
     });
   }
 
@@ -1070,8 +1114,13 @@ export class AuthManager {
    * Consolidates the duplicated concurrency guard, `_isConnecting` flag management,
    * session assignment, and state transition across `connect()`, `walletConnect()`,
    * `importFromPhrase()`, and `importFromPortable()`.
+   *
+   * Also short-circuits if the manager has already been shut down — using
+   * a closed manager would otherwise fail deep inside sync/storage with an
+   * unhelpful error.
    */
   private async _withConnect(fn: () => Promise<AuthSession>): Promise<AuthSession> {
+    this._guardShutdown();
     this._guardConcurrency();
     this._isConnecting = true;
 
@@ -1186,4 +1235,13 @@ export class AuthManager {
       );
     }
   }
+
+  private _guardShutdown(): void {
+    if (this._isShutDown) {
+      throw new Error(
+        '[@enbox/auth] AuthManager has been shut down and cannot be reused. ' +
+        'Create a new instance via AuthManager.create().'
+      );
+    }
+  }
 }

package/src/connect/import.ts

@@ -10,10 +10,17 @@ import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
 import type { ImportFromPhraseOptions, ImportFromPortableOptions } from '../types.js';
 
+import { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
+
 import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
 import { registerWithDwnEndpoints } from '../registration.js';
 import { createDefaultIdentity, ensureVaultReady, finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, startSyncIfEnabled } from './lifecycle.js';
 
+const AGENT_DID_SYNC_PROTOCOLS: [string, ...string[]] = [
+  IdentityProtocolDefinition.protocol,
+  JwkProtocolDefinition.protocol,
+];
+
 /**
  * Import (or recover) an identity from a BIP-39 recovery phrase.
  *
@@ -80,6 +87,18 @@ export async function importFromPhrase(
     await registerSyncScopeForIdentity({ userAgent, connectedDid });
   }
 
+  // Register the agent DID for sync (same rationale as vaultConnect).
+  if (sync !== 'off') {
+    try {
+      await userAgent.sync.registerIdentity({
+        did     : userAgent.agentDid.uri,
+        options : { protocols: AGENT_DID_SYNC_PROTOCOLS },
+      });
+    } catch {
+      // Already registered from a previous session.
+    }
+  }
+
   // Start sync.
   await startSyncIfEnabled(userAgent, sync);
 

package/src/connect/lifecycle.ts

@@ -1,7 +1,7 @@
 /**
  * Shared helpers for connect flows.
  *
- * Consolidates duplicated logic across `local-connect`, `session-restore`,
+ * Consolidates duplicated logic across `vault-connect`, `session-restore`,
  * `wallet-connect`, and `import-identity` flows:
  *
  * - Password resolution chain
@@ -15,11 +15,11 @@
  */
 
 import type { PortableDid } from '@enbox/dids';
-import type { BearerIdentity, DelegateContextKey, DelegateDecryptionKey, DwnDataEncodedRecordsWriteMessage, EnboxUserAgent } from '@enbox/agent';
+import type { AgentSessionIdentity, BearerIdentity, DelegateContextKey, DelegateDecryptionKey, DwnDataEncodedRecordsWriteMessage, EnboxUserAgent } from '@enbox/agent';
 
 import type { AuthEventEmitter } from '../events.js';
 import type { PasswordProvider } from '../password-provider.js';
-import type { IdentityInfo, RegistrationOptions, StorageAdapter, SyncOption } from '../types.js';
+import type { RegistrationOptions, StorageAdapter, SyncOption } from '../types.js';
 
 import { Convert } from '@enbox/common';
 import type { GenericMessage } from '@enbox/dwn-sdk-js';
@@ -35,7 +35,7 @@ import { DEFAULT_DWN_ENDPOINTS, INSECURE_DEFAULT_PASSWORD, STORAGE_KEYS } from '
 /**
  * Unified context passed from `AuthManager` to every connect flow.
  *
- * Replaces the per-flow `LocalConnectContext`, `SessionRestoreContext`,
+ * Replaces the per-flow `VaultConnectContext`, `SessionRestoreContext`,
  * `WalletConnectContext`, and `ImportContext` interfaces. All fields are
  * optional beyond the core triple (`userAgent`, `emitter`, `storage`) so
  * flows only consume what they need.
@@ -91,11 +91,15 @@ export async function resolvePassword(
 
   password ??= INSECURE_DEFAULT_PASSWORD;
 
-  if (password === INSECURE_DEFAULT_PASSWORD) {
+  // Two cases reach this branch: no password was supplied at any level
+  // (and we fell through to the insecure default), or the caller explicitly
+  // supplied an empty string. Both produce a vault with effectively zero
+  // password protection — surface a single warning in both cases.
+  if (password === INSECURE_DEFAULT_PASSWORD || password.length === 0) {
     console.warn(
-      '[@enbox/auth] SECURITY WARNING: No password set. Using insecure default. ' +
-      'Set a password via AuthManager.create({ password }) or connect({ password }) ' +
-      'to protect your identity vault.'
+      '[@enbox/auth] SECURITY WARNING: No password set (or an empty string was supplied). ' +
+      'Using an insecure default; this leaves the identity vault unprotected. ' +
+      'Set a non-empty password via AuthManager.create({ password }) or connect({ password }).'
     );
   }
 
@@ -180,7 +184,7 @@ export async function startSyncIfEnabled(
  * encryption keys, and a DWN service endpoint.
  *
  * This consolidates the identical identity creation block that was
- * duplicated in `localConnect` and `importFromPhrase`.
+ * duplicated in `vaultConnect` and `importFromPhrase`.
  *
  * @internal
  */
@@ -270,9 +274,11 @@ export function deriveSyncScopeFromGrants(grants: DwnPermissionGrant[]): 'all' |
   const protocols = new Set<string>();
 
   for (const grant of grants) {
-    const scope = grant.scope as any;
-
-    // Only Messages.Read grants authorize sync.
+    // Only Messages.Read grants authorize sync. The discriminated union
+    // (`PermissionScope = Messages | Protocols | Records`) narrows
+    // `scope.protocol` to `string | undefined` after the interface +
+    // method checks — no cast needed.
+    const { scope } = grant;
     if (scope.interface !== 'Messages' || scope.method !== 'Read') {
       continue;
     }
@@ -282,7 +288,7 @@ export function deriveSyncScopeFromGrants(grants: DwnPermissionGrant[]): 'all' |
       continue;
     }
 
-    const protocol = scope.protocol as string | undefined;
+    const protocol = scope.protocol;
     if (protocol === undefined) {
       // Unrestricted Messages.Read — delegate can sync all protocols.
       return 'all';
@@ -331,10 +337,15 @@ export async function deriveActiveSyncScope(
   if (revocationResponse.reply.status.code !== 200) { return []; }
 
   // Build the set of revoked grant IDs from revocation parent context.
+  // `descriptor.parentId` is the canonical location; the top-level
+  // `parentId` is a legacy/alternate-format fallback. Typed narrowly
+  // (no `any`) so additions to the shape land in the type system.
   const revokedGrantIds = new Set<string>();
   if (revocationResponse.reply.entries) {
     for (const entry of revocationResponse.reply.entries as DwnDataEncodedRecordsWriteMessage[]) {
-      const parentId = (entry as any).descriptor?.parentId ?? (entry as any).parentId;
+      const parentId =
+        entry.descriptor.parentId
+        ?? (entry as { parentId?: string }).parentId;
       if (parentId) { revokedGrantIds.add(parentId); }
     }
   }
@@ -586,13 +597,12 @@ export async function importDelegateAndSetupSync(params: {
   delegateDecryptionKeys?: DelegateDecryptionKey[];
   delegateContextKeys?: DelegateContextKey[];
   delegateMultiPartyProtocols?: string[];
-  sessionRevocations?: { grantId: string; revocationGrantId: string }[];
   flowName: string;
 }): Promise<BearerIdentity> {
   const {
     userAgent, delegatePortableDid, connectedDid, delegateGrants,
     delegateDecryptionKeys, delegateContextKeys, delegateMultiPartyProtocols,
-    sessionRevocations, flowName,
+    flowName,
   } = params;
 
   let identity: BearerIdentity | undefined;
@@ -683,20 +693,11 @@ export async function importDelegateAndSetupSync(params: {
     // Doing a manual pull first would double the startup burst and can
     // trigger rate limits on the remote DWN.
 
-    // Store protocol keys on the identity for finalize to persist.
-    if (delegateDecryptionKeys && delegateDecryptionKeys.length > 0) {
-      (identity as any)._delegateDecryptionKeys = delegateDecryptionKeys;
-    }
-    if (delegateContextKeys && delegateContextKeys.length > 0) {
-      (identity as any)._delegateContextKeys = delegateContextKeys;
-    }
-    if (delegateMultiPartyProtocols && delegateMultiPartyProtocols.length > 0) {
-      (identity as any)._delegateMultiPartyProtocols = delegateMultiPartyProtocols;
-    }
-    if (sessionRevocations && sessionRevocations.length > 0) {
-      (identity as any)._sessionRevocations = sessionRevocations;
-    }
-
+    // Delegate protocol keys / multi-party state / revocation map are
+    // passed back to the caller explicitly via the return value so
+    // `finalizeDelegateSession` can persist them. (The previous flow
+    // smuggled them through `(identity as any)._foo`, which traded
+    // type safety for one fewer return value.)
     return identity;
   } catch (error: unknown) {
     if (identity) {
@@ -720,6 +721,21 @@ export async function importDelegateAndSetupSync(params: {
 
 // ─── finalizeDelegateSession ────────────────────────────────────
 
+/**
+ * Transient state produced by a successful delegated connect flow that
+ * `finalizeDelegateSession` persists into the SecretStore + storage
+ * adapter. Passed explicitly through the call chain rather than
+ * smuggled via private fields on `BearerIdentity`.
+ *
+ * @internal
+ */
+export type DelegateSessionState = {
+  delegateDecryptionKeys?: DelegateDecryptionKey[];
+  delegateContextKeys?: DelegateContextKey[];
+  delegateMultiPartyProtocols?: string[];
+  sessionRevocations?: { grantId: string; revocationGrantId: string }[];
+};
+
 /**
  * Build an `AuthSession` for a delegated connect flow (DWeb Connect or
  * relay WalletConnect). Starts sync and persists delegate/connected DID
@@ -735,8 +751,12 @@ export async function finalizeDelegateSession(params: {
   connectedDid: string;
   delegateDid: string;
   sync: SyncOption | undefined;
+  delegateState?: DelegateSessionState;
 }): Promise<AuthSession> {
-  const { userAgent, emitter, storage, identity, connectedDid, delegateDid, sync } = params;
+  const {
+    userAgent, emitter, storage, identity, connectedDid, delegateDid, sync,
+    delegateState = {},
+  } = params;
 
   await startSyncIfEnabled(userAgent, sync);
 
@@ -752,7 +772,7 @@ export async function finalizeDelegateSession(params: {
   // Persist or clear delegate keys/revocations. Clearing stale values
   // from prior sessions prevents a reconnect with fewer capabilities
   // from retaining old decryption material.
-  await persistOrClearDelegateSecrets(userAgent, storage, identity, extraStorageKeys);
+  await persistOrClearDelegateSecrets(userAgent, storage, extraStorageKeys, delegateState);
 
   // Wire post-connect context key persistence: when the owner creates a
   // new multi-party context, the agent injects the key into the delegate
@@ -837,8 +857,8 @@ export async function finalizeSession(params: {
   await Promise.all(storageWrites);
 
   // When identityName is undefined, no user identity exists (agent-only session).
-  // Build an IdentityInfo with the agent DID as a fallback.
-  const identityInfo: IdentityInfo = {
+  // Build an AgentSessionIdentity with the agent DID as a fallback.
+  const identityInfo: AgentSessionIdentity = {
     didUri       : connectedDid,
     name         : identityName ?? 'Agent',
     connectedDid : identityConnectedDid,
@@ -869,11 +889,15 @@ export async function finalizeSession(params: {
 async function persistOrClearDelegateSecrets(
   userAgent: EnboxUserAgent,
   storage: StorageAdapter,
-  identity: BearerIdentity,
   extraStorageKeys: Record<string, string>,
+  delegateState: DelegateSessionState,
 ): Promise<void> {
-  const delegateDecryptionKeys = (identity as any)._delegateDecryptionKeys as DelegateDecryptionKey[] | undefined;
-  const delegateContextKeys = (identity as any)._delegateContextKeys as DelegateContextKey[] | undefined;
+  const {
+    delegateDecryptionKeys,
+    delegateContextKeys,
+    delegateMultiPartyProtocols,
+    sessionRevocations,
+  } = delegateState;
 
   // Persist or clear keys in the SecretStore + legacy StorageAdapter.
   const secretWrites: Promise<void>[] = [];
@@ -895,14 +919,12 @@ async function persistOrClearDelegateSecrets(
     try { await storage.remove(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS); } catch { /* best-effort */ }
   }
 
-  const delegateMultiPartyProtocols = (identity as any)._delegateMultiPartyProtocols as string[] | undefined;
   if (delegateMultiPartyProtocols?.length) {
     extraStorageKeys[STORAGE_KEYS.DELEGATE_MULTI_PARTY_PROTOCOLS] = JSON.stringify(delegateMultiPartyProtocols);
   } else {
     try { await storage.remove(STORAGE_KEYS.DELEGATE_MULTI_PARTY_PROTOCOLS); } catch { /* best-effort */ }
   }
 
-  const sessionRevocations = (identity as any)._sessionRevocations as { grantId: string; revocationGrantId: string }[] | undefined;
   if (sessionRevocations?.length) {
     extraStorageKeys[STORAGE_KEYS.SESSION_REVOCATIONS] = JSON.stringify(sessionRevocations);
   } else {