@enbox/auth 0.6.0 → 0.6.1

package/src/connect/lifecycle.ts

@@ -14,12 +14,16 @@
  * @internal
  */
 
-import type { BearerIdentity, EnboxUserAgent } from '@enbox/agent';
+import type { PortableDid } from '@enbox/dids';
+import type { BearerIdentity, DwnDataEncodedRecordsWriteMessage, DwnMessagesPermissionScope, DwnRecordsPermissionScope, 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 { Convert } from '@enbox/common';
+import { DwnInterface, DwnPermissionGrant } from '@enbox/agent';
+
 import { AuthSession } from '../identity-session.js';
 import { DEFAULT_DWN_ENDPOINTS, INSECURE_DEFAULT_PASSWORD, STORAGE_KEYS } from '../types.js';
 
@@ -239,6 +243,166 @@ export function resolveIdentityDids(
   return { connectedDid, delegateDid };
 }
 
+// ─── processConnectedGrants ─────────────────────────────────────
+
+/**
+ * Process connected grants by storing them in the local DWN as the owner.
+ *
+ * This is the agent-level equivalent of `Enbox.processConnectedGrants()`.
+ * It stores each grant, signed as owner, and returns the deduplicated
+ * list of protocol URIs represented by the grants.
+ *
+ * @internal
+ */
+export async function processConnectedGrants(params: {
+  agent: EnboxUserAgent;
+  delegateDid: string;
+  grants: DwnDataEncodedRecordsWriteMessage[];
+}): Promise<string[]> {
+  const { agent, delegateDid, grants } = params;
+  const connectedProtocols = new Set<string>();
+
+  for (const grantMessage of grants) {
+    const grant = DwnPermissionGrant.parse(grantMessage);
+
+    // Store the grant as the owner of the DWN so the delegateDid
+    // can use it when impersonating the connectedDid.
+    const { encodedData, ...rawMessage } = grantMessage;
+    const dataStream = new Blob([Convert.base64Url(encodedData).toUint8Array() as BlobPart]);
+
+    const { reply } = await agent.processDwnRequest({
+      store       : true,
+      author      : delegateDid,
+      target      : delegateDid,
+      messageType : DwnInterface.RecordsWrite,
+      signAsOwner : true,
+      rawMessage,
+      dataStream,
+    });
+
+    if (reply.status.code !== 202) {
+      throw new Error(
+        `[@enbox/auth] Failed to process connected grant: ${reply.status.detail}`
+      );
+    }
+
+    const protocol = (grant.scope as DwnMessagesPermissionScope | DwnRecordsPermissionScope).protocol;
+    if (protocol) {
+      connectedProtocols.add(protocol);
+    }
+  }
+
+  return [...connectedProtocols];
+}
+
+// ─── importDelegateAndSetupSync ─────────────────────────────────
+
+/**
+ * Import a delegated DID, process its grants, register sync, and pull.
+ *
+ * This is the shared post-connect lifecycle used by both the DWeb Connect
+ * and relay WalletConnect flows. On failure, the imported identity is
+ * cleaned up before re-throwing.
+ *
+ * @internal
+ */
+export async function importDelegateAndSetupSync(params: {
+  userAgent: EnboxUserAgent;
+  delegatePortableDid: PortableDid;
+  connectedDid: string;
+  delegateGrants: DwnDataEncodedRecordsWriteMessage[];
+  flowName: string;
+}): Promise<BearerIdentity> {
+  const { userAgent, delegatePortableDid, connectedDid, delegateGrants, flowName } = params;
+
+  let identity: BearerIdentity | undefined;
+  try {
+    identity = await userAgent.identity.import({
+      portableIdentity: {
+        portableDid : delegatePortableDid,
+        metadata    : {
+          connectedDid,
+          name   : 'Default',
+          uri    : delegatePortableDid.uri,
+          tenant : userAgent.agentDid.uri,
+        },
+      },
+    });
+
+    const connectedProtocols = await processConnectedGrants({
+      agent       : userAgent,
+      delegateDid : delegatePortableDid.uri,
+      grants      : delegateGrants,
+    });
+
+    await userAgent.sync.registerIdentity({
+      did     : connectedDid,
+      options : {
+        delegateDid : delegatePortableDid.uri,
+        protocols   : connectedProtocols,
+      },
+    });
+
+    await userAgent.sync.sync('pull');
+
+    return identity;
+  } catch (error: unknown) {
+    if (identity) {
+      try {
+        await userAgent.did.delete({
+          didUri    : identity.did.uri,
+          tenant    : identity.metadata.tenant,
+          deleteKey : true,
+        });
+      } catch { /* best effort */ }
+
+      try {
+        await userAgent.identity.delete({ didUri: identity.did.uri });
+      } catch { /* best effort */ }
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[@enbox/auth] ${flowName} failed: ${message}`);
+  }
+}
+
+// ─── finalizeDelegateSession ────────────────────────────────────
+
+/**
+ * Build an `AuthSession` for a delegated connect flow (DWeb Connect or
+ * relay WalletConnect). Starts sync and persists delegate/connected DID
+ * markers.
+ *
+ * @internal
+ */
+export async function finalizeDelegateSession(params: {
+  userAgent: EnboxUserAgent;
+  emitter: AuthEventEmitter;
+  storage: StorageAdapter;
+  identity: BearerIdentity;
+  connectedDid: string;
+  delegateDid: string;
+  sync: SyncOption | undefined;
+}): Promise<AuthSession> {
+  const { userAgent, emitter, storage, identity, connectedDid, delegateDid, sync } = params;
+
+  startSyncIfEnabled(userAgent, sync);
+
+  return finalizeSession({
+    userAgent,
+    emitter,
+    storage,
+    connectedDid,
+    delegateDid,
+    identityName         : identity.metadata.name,
+    identityConnectedDid : identity.metadata.connectedDid,
+    extraStorageKeys     : {
+      [STORAGE_KEYS.DELEGATE_DID]  : delegateDid,
+      [STORAGE_KEYS.CONNECTED_DID] : connectedDid,
+    },
+  });
+}
+
 // ─── finalizeSession ────────────────────────────────────────────
 
 /**
@@ -267,7 +431,7 @@ export async function finalizeSession(params: {
   connectedDid: string;
   delegateDid?: string;
   recoveryPhrase?: string;
-  identityName: string;
+  identityName?: string;
   identityConnectedDid?: string;
   emitIdentityAdded?: boolean;
   extraStorageKeys?: Record<string, string>;
@@ -295,9 +459,11 @@ export async function finalizeSession(params: {
     }
   }
 
+  // When identityName is undefined, no user identity exists (agent-only session).
+  // Build an IdentityInfo with the agent DID as a fallback.
   const identityInfo: IdentityInfo = {
     didUri       : connectedDid,
-    name         : identityName,
+    name         : identityName ?? 'Agent',
     connectedDid : identityConnectedDid,
   };
 
@@ -309,7 +475,7 @@ export async function finalizeSession(params: {
     identity : identityInfo,
   });
 
-  if (emitIdentityAdded) {
+  if (emitIdentityAdded && identityName !== undefined) {
     emitter.emit('identity-added', { identity: identityInfo });
   }
 

package/src/connect/local.ts

@@ -18,8 +18,13 @@ import { createDefaultIdentity, ensureVaultReady, finalizeSession, resolveIdenti
 /**
  * Execute the local connect flow.
  *
- * - On first launch: initializes the vault, creates a new DID, returns recovery phrase.
+ * - On first launch: initializes the vault. Identity creation is opt-in via
+ *   `options.createIdentity: true`.
  * - On subsequent launches: unlocks the vault and reconnects to the existing identity.
+ *
+ * When no identities exist and `createIdentity` is not `true`, the session
+ * is returned with the **agent DID** as the connected DID. This allows apps to
+ * manage identity creation separately from vault setup.
  */
 export async function localConnect(
   ctx: FlowContext,
@@ -33,6 +38,7 @@ export async function localConnect(
 
   const sync = options.sync ?? ctx.defaultSync;
   const dwnEndpoints = options.dwnEndpoints ?? ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
+  const shouldCreateIdentity = options.createIdentity === true;
 
   // Initialize vault on first launch and start the agent.
   const recoveryPhrase = await ensureVaultReady({
@@ -55,12 +61,21 @@ export async function localConnect(
   let identity = identities[0];
   let isNewIdentity = false;
 
-  if (!identity) {
+  if (!identity && shouldCreateIdentity) {
     isNewIdentity = true;
     identity = await createDefaultIdentity(userAgent, dwnEndpoints, options.metadata?.name ?? 'Default');
   }
 
-  const { connectedDid, delegateDid } = resolveIdentityDids(identity);
+  // When no identity exists (createIdentity: false on first launch), use the
+  // agent DID as the session's connected DID. The session is still valid but
+  // operates in the agent's context rather than a user identity's context.
+  const connectedDid = identity
+    ? resolveIdentityDids(identity).connectedDid
+    : userAgent.agentDid.uri;
+
+  const delegateDid = identity
+    ? resolveIdentityDids(identity).delegateDid
+    : undefined;
 
   // Register with DWN endpoints (if registration options are provided).
   if (ctx.registration) {
@@ -95,7 +110,7 @@ export async function localConnect(
     connectedDid,
     delegateDid,
     recoveryPhrase,
-    identityName         : identity.metadata.name,
-    identityConnectedDid : identity.metadata.connectedDid,
+    identityName         : identity?.metadata.name,
+    identityConnectedDid : identity?.metadata.connectedDid,
   });
 }

package/src/connect/restore.ts

@@ -86,22 +86,38 @@ export async function restoreSession(
     }
   }
 
+  // Start sync.
+  startSyncIfEnabled(userAgent, ctx.defaultSync);
+
   if (!identity) {
-    // No identity found — clean up stale session data.
-    await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
-    await storage.remove(STORAGE_KEYS.ACTIVE_IDENTITY);
-    await storage.remove(STORAGE_KEYS.DELEGATE_DID);
-    await storage.remove(STORAGE_KEYS.CONNECTED_DID);
-    return undefined;
+    // No identity found — this is valid for agent-only sessions created
+    // with `createIdentity: false`. Restore a session using the agent DID.
+    // If the active identity stored was the agent DID, this is an
+    // intentional agent-only session rather than stale data.
+    const isAgentOnlySession = activeIdentityDid === userAgent.agentDid.uri;
+
+    if (!isAgentOnlySession) {
+      // Truly stale session data — clean up and bail.
+      await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
+      await storage.remove(STORAGE_KEYS.ACTIVE_IDENTITY);
+      await storage.remove(STORAGE_KEYS.DELEGATE_DID);
+      await storage.remove(STORAGE_KEYS.CONNECTED_DID);
+      return undefined;
+    }
+
+    return finalizeSession({
+      userAgent,
+      emitter,
+      storage,
+      connectedDid      : userAgent.agentDid.uri,
+      emitIdentityAdded : false,
+    });
   }
 
   const { connectedDid, delegateDid } = resolveIdentityDids(
     identity, storedDelegateDid ?? undefined,
   );
 
-  // Start sync.
-  startSyncIfEnabled(userAgent, ctx.defaultSync);
-
   // Persist session info, build AuthSession, and emit lifecycle events.
   // Session restore does not emit `identity-added` (identity was already added in the original flow).
   return finalizeSession({

package/src/connect/wallet.ts

@@ -7,68 +7,17 @@
  * @module
  */
 
-import type { DwnDataEncodedRecordsWriteMessage, DwnMessagesPermissionScope, DwnRecordsPermissionScope, EnboxUserAgent } from '@enbox/agent';
-
 import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
 import type { WalletConnectOptions } from '../types.js';
 
-import { Convert } from '@enbox/common';
+import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
 import { registerWithDwnEndpoints } from '../registration.js';
 import { WalletConnect } from '../wallet-connect-client.js';
-import { DEFAULT_DWN_ENDPOINTS, STORAGE_KEYS } from '../types.js';
-import { DwnInterface, DwnPermissionGrant } from '@enbox/agent';
-import { ensureVaultReady, finalizeSession, resolvePassword, startSyncIfEnabled } from './lifecycle.js';
-
-/**
- * Process connected grants by storing them in the local DWN as the owner.
- *
- * This is the agent-level equivalent of `Enbox.processConnectedGrants()`.
- * It stores each grant, signed as owner, and returns the deduplicated
- * list of protocol URIs represented by the grants.
- *
- * @internal
- */
-export async function processConnectedGrants(params: {
-  agent: EnboxUserAgent;
-  delegateDid: string;
-  grants: DwnDataEncodedRecordsWriteMessage[];
-}): Promise<string[]> {
-  const { agent, delegateDid, grants } = params;
-  const connectedProtocols = new Set<string>();
-
-  for (const grantMessage of grants) {
-    const grant = DwnPermissionGrant.parse(grantMessage);
+import { ensureVaultReady, finalizeDelegateSession, importDelegateAndSetupSync, resolvePassword } from './lifecycle.js';
 
-    // Store the grant as the owner of the DWN so the delegateDid
-    // can use it when impersonating the connectedDid.
-    const { encodedData, ...rawMessage } = grantMessage;
-    const dataStream = new Blob([Convert.base64Url(encodedData).toUint8Array() as BlobPart]);
-
-    const { reply } = await agent.processDwnRequest({
-      store       : true,
-      author      : delegateDid,
-      target      : delegateDid,
-      messageType : DwnInterface.RecordsWrite,
-      signAsOwner : true,
-      rawMessage,
-      dataStream,
-    });
-
-    if (reply.status.code !== 202) {
-      throw new Error(
-        `[@enbox/auth] Failed to process connected grant: ${reply.status.detail}`
-      );
-    }
-
-    const protocol = (grant.scope as DwnMessagesPermissionScope | DwnRecordsPermissionScope).protocol;
-    if (protocol) {
-      connectedProtocols.add(protocol);
-    }
-  }
-
-  return [...connectedProtocols];
-}
+// Re-export for backward compatibility — processConnectedGrants moved to lifecycle.ts.
+export { processConnectedGrants } from './lifecycle.js';
 
 /**
  * Execute the wallet connect flow.
@@ -94,16 +43,9 @@ export async function walletConnect(
   // Ensure the agent is initialized and started before the relay flow.
   const isFirstLaunch = await userAgent.firstLaunch();
   const password = await resolvePassword(ctx, undefined, isFirstLaunch);
-
-  await ensureVaultReady({
-    userAgent,
-    emitter,
-    password,
-    isFirstLaunch,
-  });
+  await ensureVaultReady({ userAgent, emitter, password, isFirstLaunch });
 
   // Run the Enbox Connect relay flow.
-  // permissionRequests are already agent-level ConnectPermissionRequest objects.
   const result = await WalletConnect.initClient({
     displayName        : options.displayName,
     connectServerUrl   : options.connectServerUrl,
@@ -117,93 +59,31 @@ export async function walletConnect(
     throw new Error('[@enbox/auth] Wallet connect flow was cancelled or returned no result.');
   }
 
+  // Import delegate DID, process grants, and set up sync.
   const { delegatePortableDid, connectedDid, delegateGrants } = result;
+  const identity = await importDelegateAndSetupSync({
+    userAgent, delegatePortableDid, connectedDid, delegateGrants,
+    flowName: 'Wallet connect',
+  });
 
-  // Import the delegated DID as an Identity.
-  let identity;
-  try {
-    identity = await userAgent.identity.import({
-      portableIdentity: {
-        portableDid : delegatePortableDid,
-        metadata    : {
-          connectedDid,
-          name   : 'Default',
-          uri    : delegatePortableDid.uri,
-          tenant : userAgent.agentDid.uri,
-        },
-      },
-    });
-
-    // Process the connected grants using agent primitives.
-    const connectedProtocols = await processConnectedGrants({
-      agent       : userAgent,
-      delegateDid : delegatePortableDid.uri,
-      grants      : delegateGrants,
-    });
-
-    // Register with DWN endpoints (if registration options are provided).
-    if (ctx.registration) {
-      const dwnEndpoints = ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
-      await registerWithDwnEndpoints(
-        {
-          userAgent : userAgent,
-          dwnEndpoints,
-          agentDid  : userAgent.agentDid.uri,
-          connectedDid,
-          storage   : storage,
-        },
-        ctx.registration,
-      );
-    }
-
-    // Register sync for the connected identity.
-    await userAgent.sync.registerIdentity({
-      did     : connectedDid,
-      options : {
-        delegateDid : delegatePortableDid.uri,
-        protocols   : connectedProtocols,
+  // Register with DWN endpoints (if registration options are provided).
+  if (ctx.registration) {
+    const dwnEndpoints = ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
+    await registerWithDwnEndpoints(
+      {
+        userAgent,
+        dwnEndpoints,
+        agentDid: userAgent.agentDid.uri,
+        connectedDid,
+        storage,
       },
-    });
-
-    // Pull down existing messages from the connected DID's DWN.
-    await userAgent.sync.sync('pull');
-  } catch (error: unknown) {
-    // Clean up on failure.
-    if (identity) {
-      try {
-        await userAgent.did.delete({
-          didUri    : identity.did.uri,
-          tenant    : identity.metadata.tenant,
-          deleteKey : true,
-        });
-      } catch { /* best effort */ }
-
-      try {
-        await userAgent.identity.delete({ didUri: identity.did.uri });
-      } catch { /* best effort */ }
-    }
-
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[@enbox/auth] Wallet connect failed: ${message}`);
+      ctx.registration,
+    );
   }
 
-  const delegateDid = delegatePortableDid.uri;
-
-  // Start sync.
-  startSyncIfEnabled(userAgent, sync);
-
-  // Persist session info, build AuthSession, and emit lifecycle events.
-  return finalizeSession({
-    userAgent,
-    emitter,
-    storage,
-    connectedDid,
-    delegateDid,
-    identityName         : identity.metadata.name,
-    identityConnectedDid : identity.metadata.connectedDid,
-    extraStorageKeys     : {
-      [STORAGE_KEYS.DELEGATE_DID]  : delegateDid,
-      [STORAGE_KEYS.CONNECTED_DID] : connectedDid,
-    },
+  // Finalize session.
+  return finalizeDelegateSession({
+    userAgent, emitter, storage, identity,
+    connectedDid, delegateDid: delegatePortableDid.uri, sync,
   });
 }

package/src/index.ts

@@ -5,30 +5,23 @@
  * in both browser and CLI environments. Depends only on `@enbox/agent`
  * and can be used standalone or consumed by `@enbox/api`.
  *
- * @example Standalone auth
+ * @example Standalone auth (wallet app)
  * ```ts
  * import { AuthManager } from '@enbox/auth';
  *
  * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.restoreSession() ?? await auth.connect();
- *
- * // session.agent — the authenticated Enbox agent
- * // session.did   — the connected DID URI
+ * const session = await auth.connectLocal({ password: userPin });
  * ```
  *
- * @example With @enbox/api
+ * @example Dapp with browser connect handler
  * ```ts
  * import { AuthManager } from '@enbox/auth';
- * import { Enbox } from '@enbox/api';
- *
- * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connect();
+ * import { BrowserConnectHandler } from '@enbox/browser';
  *
- * const enbox = Enbox.connect({
- *   agent: session.agent,
- *   connectedDid: session.did,
- *   delegateDid: session.delegateDid,
+ * const auth = await AuthManager.create({
+ *   connectHandler: BrowserConnectHandler(),
  * });
+ * const session = await auth.connect({ protocols: [NotesProtocol] });
  * ```
  *
  * @packageDocumentation
@@ -47,10 +40,11 @@ export type { PasswordContext } from './password-provider.js';
 // without a direct @enbox/agent dependency.
 export { EnboxUserAgent, HdIdentityVault } from '@enbox/agent';
 
-// Wallet-connect helpers
+// Connect helpers
 export { processConnectedGrants } from './connect/wallet.js';
+export { normalizeProtocolRequests } from './permissions.js';
 export { WalletConnect } from './wallet-connect-client.js';
-export type { Permission, ProtocolPermissionOptions, WalletConnectClientOptions } from './wallet-connect-client.js';
+export type { ProtocolPermissionOptions, WalletConnectClientOptions } from './wallet-connect-client.js';
 
 // Registration token storage helpers
 export { loadTokensFromStorage, saveTokensToStorage } from './registration.js';
@@ -77,8 +71,12 @@ export type {
   AuthManagerOptions,
   AuthSessionInfo,
   AuthState,
+  ConnectHandler,
+  ConnectOptions,
   ConnectPermissionRequest,
+  ConnectResult,
   DisconnectOptions,
+  HandlerConnectOptions,
   HeadlessConnectOptions,
   IdentityInfo,
   IdentityVaultBackup,
@@ -86,7 +84,9 @@ export type {
   ImportFromPortableOptions,
   LocalConnectOptions,
   LocalDwnStrategy,
+  Permission,
   PortableIdentity,
+  ProtocolRequest,
   ProviderAuthParams,
   ProviderAuthResult,
   RegistrationOptions,

package/src/permissions.ts

@@ -0,0 +1,48 @@
+/**
+ * Permission request normalization utilities.
+ *
+ * Converts simplified `ProtocolRequest` entries (just a protocol definition
+ * or `{ definition, permissions }`) into agent-level `ConnectPermissionRequest`
+ * objects used by connect handlers.
+ *
+ * @module
+ * @internal
+ */
+
+import type { ConnectPermissionRequest, DwnProtocolDefinition } from '@enbox/agent';
+
+import type { ProtocolRequest } from './types.js';
+
+import { DEFAULT_PERMISSIONS } from './types.js';
+import { WalletConnect } from './wallet-connect-client.js';
+
+/**
+ * Normalize simplified `ProtocolRequest[]` into agent-level
+ * `ConnectPermissionRequest[]`.
+ */
+export function normalizeProtocolRequests(
+  protocols: ProtocolRequest[] | undefined,
+): ConnectPermissionRequest[] {
+  if (!protocols || protocols.length === 0) { return []; }
+
+  return protocols.map((entry) => {
+    let definition: DwnProtocolDefinition;
+    let permissions: string[];
+
+    if ('protocol' in entry && 'types' in entry && 'structure' in entry) {
+      // Bare protocol definition — use default permissions.
+      definition = entry as DwnProtocolDefinition;
+      permissions = [...DEFAULT_PERMISSIONS];
+    } else {
+      // Object with explicit permissions.
+      const explicit = entry as { definition: DwnProtocolDefinition; permissions: string[] };
+      definition = explicit.definition;
+      permissions = explicit.permissions;
+    }
+
+    return WalletConnect.createPermissionRequestForProtocol({
+      definition,
+      permissions: permissions as Parameters<typeof WalletConnect.createPermissionRequestForProtocol>[0]['permissions'],
+    });
+  });
+}