@enbox/auth 0.6.32 → 0.6.33

package/src/connect/restore.ts

@@ -12,7 +12,8 @@ import type { RestoreSessionOptions } from '../types.js';
 
 import type { StorageAdapter } from '../types.js';
 
-import type { EnboxUserAgent } from '@enbox/agent';
+import type { RecordsWriteMessage } from '@enbox/dwn-sdk-js';
+import type { DwnDataEncodedRecordsWriteMessage, EnboxUserAgent } from '@enbox/agent';
 
 import { Convert } from '@enbox/common';
 import { DataStream } from '@enbox/dwn-sdk-js';
@@ -392,7 +393,16 @@ async function ensureRevocationGrantOnRemote(
     });
     if (reply.status.code !== 200 || !reply.entry?.recordsWrite) { return; }
 
-    const { encodedData, ...rawMessage } = reply.entry.recordsWrite as any;
+    // `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, ...rawMessage } =
+      reply.entry.recordsWrite as RecordsWriteWireMessage; // NOSONAR
     const data = reply.entry.data
       ? new Blob([await DataStream.toBytes(reply.entry.data) as BlobPart])
       : undefined;
@@ -439,18 +449,18 @@ async function revokeAndSendSingle(
     messageType   : DwnInterface.RecordsRead,
     messageParams : { filter: { recordId: entry.grantId } },
   });
-  if (readReply.status.code !== 200 || !readReply.entry) { return false; }
+  if (readReply.status.code !== 200 || !readReply.entry?.recordsWrite) { return false; }
 
   // Reconstruct DwnDataEncodedRecordsWriteMessage: RecordsRead returns
   // the data as a stream, but PermissionGrant.parse needs encodedData.
   const grantDataBytes = readReply.entry.data
     ? await DataStream.toBytes(readReply.entry.data)
     : new Uint8Array(0);
-  const grantMessageWithData = {
+  const grantMessageWithData: DwnDataEncodedRecordsWriteMessage = {
     ...readReply.entry.recordsWrite,
     encodedData: Convert.uint8Array(grantDataBytes).toBase64Url(),
   };
-  const grant = DwnPermissionGrant.parse(grantMessageWithData as any);
+  const grant = DwnPermissionGrant.parse(grantMessageWithData);
 
   const { message } = await userAgent.permissions.createRevocation({
     author            : connectedDid,

package/src/connect/wallet.ts

@@ -60,7 +60,6 @@ export async function walletConnect(
   const identity = await importDelegateAndSetupSync({
     userAgent, delegatePortableDid, connectedDid, delegateGrants,
     delegateDecryptionKeys, delegateContextKeys, delegateMultiPartyProtocols,
-    sessionRevocations,
     flowName: 'Wallet connect',
   });
 
@@ -80,9 +79,18 @@ export async function walletConnect(
     );
   }
 
-  // Finalize session.
+  // Finalize session. Pass the transient delegate state explicitly so
+  // `persistOrClearDelegateSecrets` doesn't have to read it back off
+  // the identity object (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,
+    },
   });
 }

package/src/identity-session.ts

@@ -1,65 +1,21 @@
 /**
- * AuthSession represents an active, authenticated session with a specific identity.
- * @module
- */
-
-import type { EnboxAgent } from '@enbox/agent';
-
-import type { IdentityInfo } from './types.js';
-
-/**
- * An active, authenticated session bound to a specific identity.
+ * `AuthSession` is an alias for {@link AgentSession} from `@enbox/agent`.
  *
- * The session exposes the authenticated **agent**, **did**, and
- * **delegateDid** — the primitives needed to interact with the DWN
- * network. Consumers that use `@enbox/api` can construct an `Enbox`
- * instance from these properties:
+ * The alias exists so `@enbox/auth`'s public surface stays self-contained.
+ * `new AuthSession(...)` constructs an `AgentSession`, and `instanceof
+ * AuthSession` and `instanceof AgentSession` both succeed on any session
+ * created through either name. New code should prefer `AgentSession`
+ * directly.
  *
+ * @example
  * ```ts
  * import { Enbox } from '@enbox/api';
  *
  * const session = await auth.connect();
- * const enbox = Enbox.connect({
- *   agent: session.agent,
- *   connectedDid: session.did,
- *   delegateDid: session.delegateDid,
- * });
+ * const enbox = Enbox.fromSession(session);
  * ```
+ *
+ * @module
  */
-export class AuthSession {
-  /** The authenticated Enbox agent managing keys, DIDs, and DWN access. */
-  readonly agent: EnboxAgent;
-
-  /** The DID URI of the connected identity. */
-  readonly did: string;
-
-  /**
-   * The delegate DID URI, present when connected via wallet connect.
-   * This is the locally-created DID that holds delegated permissions
-   * from the wallet's identity.
-   */
-  readonly delegateDid?: string;
-
-  /**
-   * The BIP-39 recovery phrase, present only on first-time local connect.
-   * Should be shown to the user for backup and then discarded from memory.
-   */
-  readonly recoveryPhrase?: string;
-
-  /** Metadata about the connected identity. */
-  readonly identity: IdentityInfo;
 
-  constructor(params: {
-    agent: EnboxAgent;
-    did: string;
-    delegateDid?: string;
-    recoveryPhrase?: string;
-    identity: IdentityInfo;
-  }) {
-    this.agent = params.agent;
-    this.did = params.did;
-    this.delegateDid = params.delegateDid;
-    this.recoveryPhrase = params.recoveryPhrase;
-    this.identity = params.identity;
-  }
-}
+export { AgentSession as AuthSession } from '@enbox/agent';

package/src/password-provider.ts

@@ -56,15 +56,25 @@ export interface PasswordProvider {
 
 // ─── Internal I/O interfaces (for testing) ───────────────────────
 
-/** @internal Minimal interface for an stdin-like readable stream. */
+/**
+ * Minimal interface for an stdin-like readable stream.
+ *
+ * The signature shape mirrors Node's `tty.ReadStream` closely enough
+ * that `process.stdin` is directly assignable without a cast — the
+ * payoff is that `readPasswordRawMode` is testable with a tiny in-memory
+ * stub and the production call site needs no `as` to bridge to Node's
+ * actual stdin type.
+ *
+ * @internal
+ */
 export interface TtyReadable {
   isTTY?: boolean;
-  setRawMode(mode: boolean): void;
-  setEncoding(encoding: string): void;
-  resume(): void;
-  pause(): void;
-  on(event: 'data', listener: (chunk: string) => void): void;
-  removeListener(event: 'data', listener: (chunk: string) => void): void;
+  setRawMode(mode: boolean): unknown;
+  setEncoding(encoding?: BufferEncoding): unknown;
+  resume(): unknown;
+  pause(): unknown;
+  on(event: 'data', listener: (chunk: string) => void): unknown;
+  removeListener(event: 'data', listener: (chunk: string) => void): unknown;
 }
 
 /** @internal Minimal interface for an stdout-like writable stream. */
@@ -127,13 +137,19 @@ export function readPasswordRawMode(
   });
 }
 
-/** @internal Injectable I/O for testing `readPasswordDevTty`. */
+/**
+ * @internal Injectable I/O for testing `readPasswordDevTty`.
+ *
+ * `execSync`'s `stdio` is narrowed to the literal-union Node accepts so
+ * the implementation below can call `child_process.execSync` without a
+ * `stdio: string -> stdio: StdioOptions` cast.
+ */
 export interface DevTtyIo {
   openSync(path: string, flags: string): number;
   readSync(fd: number, buf: Uint8Array, offset: number, length: number, position: null): number;
   writeSync(fd: number, data: string): number;
   closeSync(fd: number): void;
-  execSync(cmd: string, opts: { stdio: string }): void;
+  execSync(cmd: string, opts: { stdio: 'pipe' | 'ignore' | 'inherit' }): void;
 }
 
 /**
@@ -162,7 +178,7 @@ export async function readPasswordDevTty(
       readSync,
       writeSync,
       closeSync,
-      execSync: (cmd: string, opts: { stdio: string }): void => { execSync(cmd, opts as any); },
+      execSync: (cmd: string, opts: { stdio: 'pipe' | 'ignore' | 'inherit' }): void => { execSync(cmd, opts); },
     };
   }
 
@@ -303,7 +319,7 @@ export namespace PasswordProvider {
         }
 
         return readPasswordRawMode(
-          process.stdin as unknown as TtyReadable,
+          process.stdin,
           process.stdout,
           prompt,
         );

package/src/types.ts

@@ -4,7 +4,7 @@
  */
 
 import type { PortableDid } from '@enbox/dids';
-import type { ConnectPermissionRequest, DelegateContextKey, DelegateDecryptionKey, DwnDataEncodedRecordsWriteMessage, DwnProtocolDefinition, EnboxUserAgent, HdIdentityVault, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
+import type { AgentSessionIdentity, ConnectPermissionRequest, DelegateContextKey, DelegateDecryptionKey, DwnDataEncodedRecordsWriteMessage, DwnProtocolDefinition, EnboxUserAgent, HdIdentityVault, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
 
 import type { PasswordProvider } from './password-provider.js';
 
@@ -79,20 +79,15 @@ export type AuthEventHandler<E extends AuthEvent = AuthEvent> =
 
 // ─── Identity ────────────────────────────────────────────────────
 
-/** Lightweight metadata about a stored identity. */
-export interface IdentityInfo {
-  /** The DID URI for this identity. */
-  didUri: string;
-
-  /** Human-readable name. */
-  name: string;
-
-  /**
-   * Present when this identity is a delegate of another DID
-   * (i.e. connected via wallet connect).
-   */
-  connectedDid?: string;
-}
+/**
+ * Lightweight metadata about a stored identity.
+ *
+ * @deprecated Prefer {@link AgentSessionIdentity} from `@enbox/agent` — this
+ *   alias exists for `@enbox/auth`'s self-contained public surface but the
+ *   canonical name lives in the agent package. The two are structurally
+ *   identical; new code should import `AgentSessionIdentity` directly.
+ */
+export type IdentityInfo = AgentSessionIdentity;
 
 /** Serializable session info for the `session-start` event. */
 export interface AuthSessionInfo {
@@ -492,6 +487,15 @@ export interface HandlerConnectOptions {
    */
   connectHandler?: ConnectHandler;
 
+  /**
+   * Vault password for this call (overrides the manager default).
+   *
+   * The handler flow still needs to unlock the local agent's vault to receive
+   * delegated grants — passing `password` per-call lets callers override the
+   * default supplied to `AuthManager.create()`.
+   */
+  password?: string;
+
   /** Override manager default sync interval. */
   sync?: SyncOption;
 }

package/src/wallet-connect-client.ts

@@ -126,7 +126,7 @@ async function initClient({
   // Sign the request as a JWT.
   const requestJwt = await EnboxConnectProtocol.signJwt({
     did  : clientDid,
-    data : request as unknown as Record<string, unknown>,
+    data : request,
   });
 
   if (!requestJwt) {
@@ -191,18 +191,20 @@ async function initClient({
     // Get the PIN from the user and use it as AAD to decrypt.
     const pin = await validatePin();
     const jwt = await EnboxConnectProtocol.decryptResponse(clientDid, jwe, pin);
-    const verifiedResponse = (await EnboxConnectProtocol.verifyJwt({
-      jwt,
-    })) as unknown as EnboxConnectResponse;
+    const verifiedPayload = await EnboxConnectProtocol.verifyJwt({ jwt });
+    // Runtime narrowing — see `assertConnectResponse` in @enbox/agent for
+    // the shape validated. After this line `verifiedPayload` is narrowed
+    // to `EnboxConnectResponse`.
+    EnboxConnectProtocol.assertConnectResponse(verifiedPayload);
 
     return {
-      delegateGrants              : verifiedResponse.delegateGrants,
-      delegatePortableDid         : verifiedResponse.delegatePortableDid,
-      connectedDid                : verifiedResponse.providerDid,
-      delegateDecryptionKeys      : verifiedResponse.delegateDecryptionKeys,
-      delegateContextKeys         : verifiedResponse.delegateContextKeys,
-      delegateMultiPartyProtocols : verifiedResponse.delegateMultiPartyProtocols,
-      sessionRevocations          : verifiedResponse.sessionRevocations,
+      delegateGrants              : verifiedPayload.delegateGrants,
+      delegatePortableDid         : verifiedPayload.delegatePortableDid,
+      connectedDid                : verifiedPayload.providerDid,
+      delegateDecryptionKeys      : verifiedPayload.delegateDecryptionKeys,
+      delegateContextKeys         : verifiedPayload.delegateContextKeys,
+      delegateMultiPartyProtocols : verifiedPayload.delegateMultiPartyProtocols,
+      sessionRevocations          : verifiedPayload.sessionRevocations,
     };
   }
 }