@enbox/api 0.6.24 → 0.6.26

package/dist/types/enbox-types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Public type surface for the {@link Enbox} class.
+ *
+ * Session and connect types are derived from
+ * {@link AgentSessionPrimitives} in `@enbox/agent`, so the minimal session
+ * shape lives in one place and downstream packages stay in sync.
+ *
+ * @module
+ */
+import type { AgentSessionPrimitives } from '@enbox/agent';
+import type { AuthManager } from '@enbox/auth/auth-manager';
+import type { DidMethodResolver } from '@enbox/dids';
+import type { AuthManagerOptions, AuthSession, HandlerConnectOptions, VaultConnectOptions } from '@enbox/auth';
+import type { DwnReaderApi } from './dwn-reader-api.js';
+import type { Enbox } from './enbox.js';
+/**
+ * Options for creating an anonymous (read-only) Enbox instance via {@link Enbox.anonymous}.
+ *
+ * @beta
+ */
+export type EnboxAnonymousOptions = {
+    /** Override the default DID method resolvers. Defaults to `[DidDht, DidJwk, DidKey, DidWeb]`. */
+    didResolvers?: DidMethodResolver[];
+};
+/**
+ * The result of calling {@link Enbox.anonymous}.
+ *
+ * Contains only a read-only `dwn` property — no `did`, `vc`, or `agent`.
+ *
+ * @beta
+ */
+export type EnboxAnonymousApi = {
+    /** A read-only DWN API for querying public data on remote DWNs. */
+    dwn: DwnReaderApi;
+};
+/**
+ * Parameters for constructing an {@link Enbox} instance.
+ *
+ * These are the minimal primitives needed to interact with the DWN network.
+ * Typically obtained from an agent session via `@enbox/auth`.
+ *
+ * Built on {@link AgentSessionPrimitives}: same `agent`/`delegateDid` shape,
+ * with `did` renamed to `connectedDid` to mirror the constructor parameter
+ * name used throughout `@enbox/api` for the tenant DID.
+ */
+export type EnboxParams = Omit<AgentSessionPrimitives, 'did'> & {
+    /** The DID of the tenant under which all DID, DWN, and VC requests are being performed. */
+    connectedDid: string;
+};
+/**
+ * Session-shaped parameters accepted by {@link Enbox.fromSession}.
+ *
+ * Alias for {@link AgentSessionPrimitives} so callers can pass an
+ * `AuthSession` from `@enbox/auth`, an `AgentSession` from `@enbox/agent`, or
+ * any compatible custom session without duplicating field declarations.
+ */
+export type EnboxSessionParams = AgentSessionPrimitives;
+/**
+ * High-level connection options for {@link Enbox.connect}.
+ *
+ * Composed of two parts:
+ *
+ * 1. **Manager-wide defaults** ({@link AuthManagerOptions}) — `password`,
+ *    `sync`, `dwnEndpoints`, `connectHandler`, etc. Forwarded to
+ *    `AuthManager.create()` and reused across reconnects.
+ * 2. **Per-call signals** ({@link HandlerConnectOptions} ∪
+ *    {@link VaultConnectOptions}) — `protocols`, `createIdentity`,
+ *    `recoveryPhrase`, `metadata`, etc. Forwarded to
+ *    `AuthManager.connect()` and used to route handler vs local flow.
+ *
+ * Several fields (`password`, `sync`, `dwnEndpoints`, `connectHandler`)
+ * appear on multiple parents. The intersection keeps a single `?:`-typed
+ * field; the value flows to both the manager (as a default) and the
+ * per-call payload — matching the behavior of restored sessions.
+ *
+ * Routing between local and handler flow happens at runtime inside
+ * `AuthManager._isLocalConnect` based on whether `protocols` or
+ * `connectHandler` is provided. See `Enbox.connect()` for examples.
+ *
+ * If you need full control of the exact options forwarded to
+ * `AuthManager.connect()`, drop down one layer: create the
+ * `AuthManager` yourself and pass its session to `Enbox.fromSession`.
+ */
+export type EnboxConnectOptions = AuthManagerOptions & HandlerConnectOptions & VaultConnectOptions;
+/** The result of a high-level asynchronous {@link Enbox.connect} call. */
+export type EnboxConnectResult = {
+    /** The AuthManager that owns the session lifecycle. */
+    auth: AuthManager;
+    /** The high-level Enbox API instance. */
+    enbox: Enbox;
+    /** The active session returned by `AuthManager.connect()`. */
+    session: AuthSession;
+};
+//# sourceMappingURL=enbox-types.d.ts.map

package/dist/types/enbox-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enbox-types.d.ts","sourceRoot":"","sources":["../../src/enbox-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,iGAAiG;IACjG,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mEAAmE;IACnE,GAAG,EAAE,YAAY,CAAC;CACnB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,GAAG;IAC9D,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,qBAAqB,GACrB,mBAAmB,CAAC;AAExB,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uDAAuD;IACvD,IAAI,EAAE,WAAW,CAAC;IAElB,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IAEb,8DAA8D;IAC9D,OAAO,EAAE,WAAW,CAAC;CACtB,CAAC"}

package/dist/types/enbox.d.ts

@@ -2,79 +2,43 @@
  * NOTE: Added reference types here to avoid a `pnpm` bug during build.
  * https://github.com/enboxorg/enbox/pull/507
  */
-import type { AuthSession } from '@enbox/auth';
-import type { DidMethodResolver } from '@enbox/dids';
-import type { EnboxAgent } from '@enbox/agent';
+import type { EnboxPlatformAgent } from '@enbox/agent';
 import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+import type { EnboxAnonymousApi, EnboxAnonymousOptions, EnboxConnectOptions, EnboxConnectResult, EnboxParams, EnboxSessionParams } from './enbox-types.js';
 import type { SchemaMap, TypedProtocol } from './protocol-types.js';
 import { DidApi } from './did-api.js';
-import { DwnReaderApi } from './dwn-reader-api.js';
 import { TypedEnbox } from './typed-enbox.js';
 import { VcApi } from './vc-api.js';
-/**
- * Options for creating an anonymous (read-only) Enbox instance via {@link Enbox.anonymous}.
- *
- * @beta
- */
-export type EnboxAnonymousOptions = {
-    /** Override the default DID method resolvers. Defaults to `[DidDht, DidJwk, DidKey, DidWeb]`. */
-    didResolvers?: DidMethodResolver[];
-};
-/**
- * The result of calling {@link Enbox.anonymous}.
- *
- * Contains only a read-only `dwn` property — no `did`, `vc`, or `agent`.
- *
- * @beta
- */
-export type EnboxAnonymousApi = {
-    /** A read-only DWN API for querying public data on remote DWNs. */
-    dwn: DwnReaderApi;
-};
-/**
- * Parameters for constructing an {@link Enbox} instance.
- *
- * These are the minimal primitives needed to interact with the DWN network.
- * Typically obtained from an {@link AuthSession} via `@enbox/auth`.
- */
-export type EnboxParams = {
-    /**
-     * A {@link EnboxAgent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
-     * user keys and identities, and is responsible to sign and verify messages.
-     */
-    agent: EnboxAgent;
-    /** The DID of the tenant under which all DID, DWN, and VC requests are being performed. */
-    connectedDid: string;
-    /** The DID that will be signing messages using grants from the connectedDid. */
-    delegateDid?: string;
-};
 /**
  * The main Enbox API interface. It provides protocol-scoped access to
  * Decentralized Web Nodes (DWNs), Decentralized Identifiers (DIDs),
  * and Verifiable Credentials (VCs).
  *
- * Authentication and identity management are handled externally by
- * `@enbox/auth`. Use {@link Enbox.connect} to create an instance from
- * an {@link AuthSession} or raw parameters.
+ * For common app flows, use the asynchronous {@link Enbox.connect} helper.
+ * For custom auth/session flows, use {@link Enbox.fromSession} with an
+ * existing session, or the public constructor with raw `{ agent, connectedDid }`.
  *
  * @example
  * ```ts
- * import { AuthManager } from '@enbox/auth';
  * import { Enbox } from '@enbox/api';
  *
- * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connect();
+ * const { enbox } = await Enbox.connect({
+ *   createIdentity: true,
+ *   sync: '15s',
+ * });
  *
- * const enbox = Enbox.connect({ session });
  * const social = enbox.using(SocialProtocol);
  * ```
  */
 export declare class Enbox {
     /**
-     * A {@link EnboxAgent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
-     * user keys and identities, and is responsible to sign and verify messages.
+     * The {@link EnboxPlatformAgent} this instance is bound to. The platform
+     * agent handles DIDs, DWN access, signing keys, and DWN sync — every
+     * Enbox session needs all of those, so the type is narrower than the
+     * minimal {@link EnboxAgent} interface and the constructor refuses
+     * non-platform agents at compile time.
      */
-    agent: EnboxAgent;
+    agent: EnboxPlatformAgent;
     /** Exposed instance to the DID APIs, allow users to create and resolve DIDs. */
     did: DidApi;
     /** Internal DWN API instance. Use {@link Enbox.using} for protocol-scoped access. */
@@ -89,6 +53,20 @@ export declare class Enbox {
     private readonly _typedInstances;
     /** Exposed instance to the VC APIs, allow users to issue, present and verify VCs. */
     vc: VcApi;
+    /**
+     * The `AuthManager` this instance owns and is responsible for tearing down
+     * during {@link Enbox.disconnect}. Set only by the async
+     * {@link Enbox.connect} factory; never populated by the public constructor
+     * or {@link Enbox.fromSession}.
+     */
+    private _ownedAuth?;
+    /**
+     * Memoized teardown promise. Two parallel `enbox.disconnect()` calls
+     * share the same promise so `agent.sync.stopSync()` (and the optional
+     * `auth.shutdown()`) run exactly once even when callers fire the
+     * teardown from independent code paths.
+     */
+    private _disconnecting?;
     constructor({ agent, connectedDid, delegateDid }: EnboxParams);
     /**
      * Returns a {@link TypedEnbox} instance scoped to the given protocol.
@@ -120,23 +98,57 @@ export declare class Enbox {
      */
     using<D extends ProtocolDefinition, M extends SchemaMap>(protocol: TypedProtocol<D, M>): TypedEnbox<D, M>;
     /**
-     * Stops DWN sync and clears the cached {@link TypedEnbox} instances.
+     * Signs the user out and releases resources held by this Enbox instance.
+     *
+     * When this instance owns the underlying `AuthManager` (i.e. it was
+     * created via `Enbox.connect()` with no caller-supplied `agent`), the
+     * disconnect proceeds in three phases:
+     *
+     *   1. **Stop sync** — `agent.sync.stopSync(timeout)` halts the DWN
+     *      sync engine. Always runs, regardless of ownership.
+     *   2. **Sign out** — `AuthManager.disconnect()` sends delegate-grant
+     *      revocations to the connected DWN endpoints, clears session
+     *      restore markers (PREVIOUSLY_CONNECTED, ACTIVE_IDENTITY,
+     *      delegate keys, etc.) from the StorageAdapter, and clears the
+     *      in-memory delegate decryption key cache. **Without this step
+     *      a later `Enbox.connect()` would silently restore the
+     *      supposedly signed-out session from the persisted markers.**
+     *   3. **Release resources** — `AuthManager.shutdown()` locks the
+     *      vault, closes the sync engine, and closes the StorageAdapter.
+     *
+     * When the instance was created from a caller-owned session
+     * ({@link Enbox.fromSession}), a raw agent (the public constructor),
+     * or `Enbox.connect({ agent })`, only step 1 (stop sync) runs — the
+     * caller's AuthManager / agent keep their lifecycle. The caller is
+     * responsible for calling `auth.disconnect()` and `auth.shutdown()`
+     * on their own handle when they're done.
      *
-     * Call this when the application is shutting down or the user is
-     * disconnecting to cleanly release background resources. After calling
-     * `disconnect()`, the `Enbox` instance should not be reused.
+     * Idempotent: parallel calls share the same teardown promise. After
+     * calling `disconnect()`, the `Enbox` instance should not be reused.
      *
      * @param timeout - Maximum milliseconds to wait for an in-progress sync
      *   cycle to finish before force-stopping. Defaults to `2000`.
      *
      * @example
      * ```ts
-     * await enbox.disconnect();
+     * // High-level flow: a single disconnect() does sign-out + teardown.
+     * const { enbox } = await Enbox.connect({ createIdentity: true });
+     * // ... user uses the app ...
+     * await enbox.disconnect();   // revoke grants, clear markers, close vault
+     *
+     * // Caller-owned auth: enbox.disconnect() only stops Enbox-side state.
+     * const auth = await AuthManager.create({...});
+     * const session = await auth.connect();
+     * const enbox = Enbox.fromSession(session);
+     * await enbox.disconnect();   // stops sync + clears typed-enbox cache
+     * await auth.disconnect();    // sign-out: caller's responsibility
+     * await auth.shutdown();      // close resources: caller's responsibility
      * ```
      *
      * @beta
      */
     disconnect(timeout?: number): Promise<void>;
+    private _doDisconnect;
     /**
      * Creates a lightweight, read-only Enbox instance for querying public DWN data.
      *
@@ -165,30 +177,85 @@ export declare class Enbox {
      */
     static anonymous(options?: EnboxAnonymousOptions): EnboxAnonymousApi;
     /**
-     * Creates an {@link Enbox} instance from an {@link AuthSession} or raw parameters.
+     * Creates an {@link Enbox} instance from a session-shaped object.
+     *
+     * Accepts `AuthSession`, `AgentSession`, or any compatible custom session
+     * with `{ agent, did, delegateDid? }`. This is the right entry point
+     * whenever you already hold an active session — including ones produced by
+     * a caller-managed `AuthManager`.
+     *
+     * For raw `{ agent, connectedDid }` access (no session shape), use the
+     * public constructor directly: `new Enbox({ agent, connectedDid })`.
+     */
+    static fromSession(session: EnboxSessionParams): Enbox;
+    /**
+     * High-level entry point that creates an {@link AuthManager}, runs
+     * `auth.connect()`, and returns the resulting `{ auth, session, enbox }`.
+     *
+     * For callers that already own an agent and DID, use the dedicated
+     * synchronous entry points instead:
+     * - `new Enbox({ agent, connectedDid })` for raw parameters
+     * - {@link Enbox.fromSession} for session-shaped objects
      *
-     * This is a thin factory — all authentication, identity management, vault
-     * initialization, DWN registration, and sync setup are handled externally
-     * by `@enbox/auth` via {@link AuthSession}.
+     * Routing happens at runtime inside `AuthManager._isVaultConnect`:
+     * presence of a non-empty `protocols` array or a `connectHandler` selects
+     * the handler flow; everything else routes to local. Local-style fields
+     * (`password`, `dwnEndpoints`, etc.) are forwarded to both the manager
+     * (as defaults) and the per-call payload, so behavior is consistent with
+     * restored sessions.
      *
-     * @param params - Either `{ session }` with an {@link AuthSession} from
-     *   `@enbox/auth`, or raw `{ agent, connectedDid, delegateDid? }` parameters.
-     * @returns A new {@link Enbox} instance ready for use.
+     * If you need exact control of the `AuthManager.connect()` payload,
+     * drop down one layer: create the `AuthManager` yourself with
+     * `AuthManager.create()`, call `auth.connect(...)` with your exact
+     * options, and pass the resulting session to `Enbox.fromSession`.
      *
      * @example
      * ```ts
-     * // Using an AuthSession from @enbox/auth
-     * import { AuthManager } from '@enbox/auth';
-     * const auth = await AuthManager.create({ sync: '15s' });
-     * const session = await auth.connect();
-     * const enbox = Enbox.connect({ session });
-     *
-     * // Using raw parameters
-     * const enbox = Enbox.connect({ agent, connectedDid: did });
+     * const { enbox, session, auth } = await Enbox.connect({ createIdentity: true });
+     * // ...
+     * await enbox.disconnect();
+     * await auth.shutdown(); // release vault + storage handles
      * ```
      */
-    static connect(params: {
-        session: AuthSession;
-    } | EnboxParams): Enbox;
+    static connect(options?: EnboxConnectOptions): Promise<EnboxConnectResult>;
+    /**
+     * Split `EnboxConnectOptions` into the manager-wide defaults that
+     * `AuthManager.create()` consumes.
+     *
+     * Implemented as an **explicit allowlist** for the same reason as
+     * `toAuthConnectOptions`: a denylist would silently leak future
+     * `HandlerConnectOptions` / `VaultConnectOptions` fields into the
+     * manager-default record. The `satisfies Partial<AuthManagerOptions>`
+     * annotation makes the compiler verify every key in the allowlist
+     * exists on `AuthManagerOptions`, so a misspelled or stale field name
+     * is a type error.
+     */
+    private static toAuthManagerOptions;
+    /**
+     * Split `EnboxConnectOptions` into the per-call payload that
+     * `AuthManager.connect()` consumes.
+     *
+     * Implemented as an **explicit allowlist** of the fields declared on
+     * {@link HandlerConnectOptions} ∪ {@link VaultConnectOptions}. A
+     * denylist (strip manager-only fields, forward the rest) would
+     * silently leak any future `AuthManagerOptions` field into
+     * `AuthManager.connect()`; the allowlist makes the type boundary
+     * explicit and the leak impossible. The trade-off is symmetric:
+     * any new connect-options field requires an edit here. That's
+     * acceptable — it's the same edit the public `ConnectOptions` type
+     * already needs, just on one extra line.
+     *
+     * The `satisfies Partial<ConnectOptions>` annotation makes the
+     * compiler verify every key in the allowlist exists on `ConnectOptions`,
+     * so misspelling a field name is a type error rather than a silent
+     * drop. Routing between local and handler flow happens inside
+     * `AuthManager._isVaultConnect` based on the presence of `protocols`
+     * / `connectHandler`.
+     *
+     * `protocols: []` is normalized away — an empty array carries no
+     * permission intent and would otherwise produce a zero-grant
+     * "connected" handler session indistinguishable from a denied connect.
+     */
+    private static toAuthConnectOptions;
 }
 //# sourceMappingURL=enbox.d.ts.map

package/dist/types/enbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enbox.d.ts","sourceRoot":"","sources":["../../src/enbox.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAMpE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,iGAAiG;IACjG,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mEAAmE;IACnE,GAAG,EAAE,YAAY,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAC;IAErB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,KAAK;IAChB;;;OAGG;IACI,KAAK,EAAE,UAAU,CAAC;IAEzB,gFAAgF;IACzE,GAAG,EAAE,MAAM,CAAC;IAEnB,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgE;IAEhG,qFAAqF;IAC9E,EAAE,EAAE,KAAK,CAAC;gBAEL,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,WAAW;IAO7D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,SAAS,SAAS,EAC5D,QAAQ,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;IAenB;;;;;;;;;;;;;;;;OAgBG;IACU,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACW,SAAS,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB;IAc3E;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACW,OAAO,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,GAAG,WAAW,GAAG,KAAK;CAW7E"}
+{"version":3,"file":"enbox.d.ts","sourceRoot":"","sources":["../../src/enbox.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQpE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAkBpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,KAAK;IAChB;;;;;;OAMG;IACI,KAAK,EAAE,kBAAkB,CAAC;IAEjC,gFAAgF;IACzE,GAAG,EAAE,MAAM,CAAC;IAEnB,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgE;IAEhG,qFAAqF;IAC9E,EAAE,EAAE,KAAK,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAC,CAAc;IAEjC;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAAC,CAAgB;gBAE3B,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,WAAW;IAO7D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,SAAS,SAAS,EAC5D,QAAQ,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;IAenB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACU,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAY1C,aAAa;IAwC3B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACW,SAAS,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB;IAc3E;;;;;;;;;;OAUG;WACW,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,KAAK;IAQ7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;WACiB,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqF3F;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAmBnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAyBpC"}

package/dist/types/index.d.ts

@@ -4,16 +4,18 @@
  * The SDK provides protocol-scoped access to DWN records with compile-time
  * type safety, DID management, and Verifiable Credential operations.
  *
- * Authentication and identity management are handled by `@enbox/auth`.
+ * Common authentication and identity setup is available through
+ * `Enbox.connect()`. Advanced session management can use `@enbox/auth` or
+ * `@enbox/agent` directly.
  *
  * @example
  * ```ts
- * import { AuthManager } from '@enbox/auth';
  * import { Enbox } from '@enbox/api';
  *
- * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connect();
- * const enbox = Enbox.connect({ session });
+ * const { enbox } = await Enbox.connect({
+ *   createIdentity: true,
+ *   sync: '15s',
+ * });
  * ```
  *
  * [Link to GitHub Repo](https://github.com/enboxorg/enbox)
@@ -24,6 +26,7 @@ export * from './define-protocol.js';
 export * from './did-api.js';
 export * from './dwn-reader-api.js';
 export * from './enbox.js';
+export type * from './enbox-types.js';
 export * from './grant-revocation.js';
 export * from './live-query.js';
 export * from './permission-grant.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,mBAAmB,kBAAkB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/repository.d.ts

@@ -24,6 +24,25 @@
  * const members = await social.group.member.query(groupContextId);
  * ```
  *
+ * ## Deliberate `as never` pattern
+ *
+ * The CRUD methods below pass their `options: Record<string, unknown>`
+ * parameter to `typed.records.{create, query, subscribe, update}` with
+ * `as never`. This is the type-system bridge between the type-erased
+ * Proxy (which doesn't carry the per-protocol generic) and the strictly-
+ * typed record methods (which take `TypedRecordCreateParams<...>` etc.).
+ *
+ * `never` is the universal bottom subtype, so any strict generic is
+ * satisfied. The structural runtime shape of `options` is validated by
+ * the DWN SDK's grant-processing layer downstream — the cast is a
+ * narrow, intentional escape hatch at the proxy boundary.
+ *
+ * SonarCloud's `typescript:S4325` flags these casts as redundant
+ * because its rule doesn't model generic-parameter constraints. We
+ * suppress S4325 at the file level (see `sonar-project.properties`)
+ * because every CRUD method uses the same pattern and per-line
+ * `// NOSONAR` would dwarf the actual code.
+ *
  * @module
  */
 import type { Repository } from './repository-types.js';

package/dist/types/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,mBAAmB,CAAC;AAoS7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CACxB,CAAC,SAAS,kBAAkB,EAC5B,CAAC,SAAS,SAAS,EACnB,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAqC3C"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,mBAAmB,CAAC;AA2S7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CACxB,CAAC,SAAS,kBAAkB,EAC5B,CAAC,SAAS,SAAS,EACnB,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAqC3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/api",
-  "version": "0.6.24",
+  "version": "0.6.26",
   "description": "Enbox SDK — high-level API for Decentralized Web Nodes, DIDs, and Verifiable Credentials",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -81,15 +81,15 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@enbox/agent": "0.7.0",
-    "@enbox/auth": "0.6.32",
-    "@enbox/common": "0.1.0",
-    "@enbox/dwn-clients": "0.4.0"
+    "@enbox/agent": "0.7.2",
+    "@enbox/auth": "0.6.34",
+    "@enbox/common": "0.1.1",
+    "@enbox/dwn-clients": "0.4.1"
   },
   "devDependencies": {
-    "@enbox/crypto": "0.1.0",
-    "@enbox/dids": "0.1.0",
-    "@enbox/dwn-sdk-js": "0.3.5",
+    "@enbox/crypto": "0.1.1",
+    "@enbox/dids": "0.1.1",
+    "@enbox/dwn-sdk-js": "0.3.6",
     "@types/node": "22.19.15",
     "@types/sinon": "17.0.3",
     "@typescript-eslint/eslint-plugin": "8.32.1",

package/src/enbox-types.ts

@@ -0,0 +1,111 @@
+/**
+ * Public type surface for the {@link Enbox} class.
+ *
+ * Session and connect types are derived from
+ * {@link AgentSessionPrimitives} in `@enbox/agent`, so the minimal session
+ * shape lives in one place and downstream packages stay in sync.
+ *
+ * @module
+ */
+
+import type { AgentSessionPrimitives } from '@enbox/agent';
+import type { AuthManager } from '@enbox/auth/auth-manager';
+import type { DidMethodResolver } from '@enbox/dids';
+import type {
+  AuthManagerOptions,
+  AuthSession,
+  HandlerConnectOptions,
+  VaultConnectOptions,
+} from '@enbox/auth';
+
+import type { DwnReaderApi } from './dwn-reader-api.js';
+import type { Enbox } from './enbox.js';
+
+/**
+ * Options for creating an anonymous (read-only) Enbox instance via {@link Enbox.anonymous}.
+ *
+ * @beta
+ */
+export type EnboxAnonymousOptions = {
+  /** Override the default DID method resolvers. Defaults to `[DidDht, DidJwk, DidKey, DidWeb]`. */
+  didResolvers?: DidMethodResolver[];
+};
+
+/**
+ * The result of calling {@link Enbox.anonymous}.
+ *
+ * Contains only a read-only `dwn` property — no `did`, `vc`, or `agent`.
+ *
+ * @beta
+ */
+export type EnboxAnonymousApi = {
+  /** A read-only DWN API for querying public data on remote DWNs. */
+  dwn: DwnReaderApi;
+};
+
+/**
+ * Parameters for constructing an {@link Enbox} instance.
+ *
+ * These are the minimal primitives needed to interact with the DWN network.
+ * Typically obtained from an agent session via `@enbox/auth`.
+ *
+ * Built on {@link AgentSessionPrimitives}: same `agent`/`delegateDid` shape,
+ * with `did` renamed to `connectedDid` to mirror the constructor parameter
+ * name used throughout `@enbox/api` for the tenant DID.
+ */
+export type EnboxParams = Omit<AgentSessionPrimitives, 'did'> & {
+  /** The DID of the tenant under which all DID, DWN, and VC requests are being performed. */
+  connectedDid: string;
+};
+
+/**
+ * Session-shaped parameters accepted by {@link Enbox.fromSession}.
+ *
+ * Alias for {@link AgentSessionPrimitives} so callers can pass an
+ * `AuthSession` from `@enbox/auth`, an `AgentSession` from `@enbox/agent`, or
+ * any compatible custom session without duplicating field declarations.
+ */
+export type EnboxSessionParams = AgentSessionPrimitives;
+
+/**
+ * High-level connection options for {@link Enbox.connect}.
+ *
+ * Composed of two parts:
+ *
+ * 1. **Manager-wide defaults** ({@link AuthManagerOptions}) — `password`,
+ *    `sync`, `dwnEndpoints`, `connectHandler`, etc. Forwarded to
+ *    `AuthManager.create()` and reused across reconnects.
+ * 2. **Per-call signals** ({@link HandlerConnectOptions} ∪
+ *    {@link VaultConnectOptions}) — `protocols`, `createIdentity`,
+ *    `recoveryPhrase`, `metadata`, etc. Forwarded to
+ *    `AuthManager.connect()` and used to route handler vs local flow.
+ *
+ * Several fields (`password`, `sync`, `dwnEndpoints`, `connectHandler`)
+ * appear on multiple parents. The intersection keeps a single `?:`-typed
+ * field; the value flows to both the manager (as a default) and the
+ * per-call payload — matching the behavior of restored sessions.
+ *
+ * Routing between local and handler flow happens at runtime inside
+ * `AuthManager._isLocalConnect` based on whether `protocols` or
+ * `connectHandler` is provided. See `Enbox.connect()` for examples.
+ *
+ * If you need full control of the exact options forwarded to
+ * `AuthManager.connect()`, drop down one layer: create the
+ * `AuthManager` yourself and pass its session to `Enbox.fromSession`.
+ */
+export type EnboxConnectOptions =
+  & AuthManagerOptions
+  & HandlerConnectOptions
+  & VaultConnectOptions;
+
+/** The result of a high-level asynchronous {@link Enbox.connect} call. */
+export type EnboxConnectResult = {
+  /** The AuthManager that owns the session lifecycle. */
+  auth: AuthManager;
+
+  /** The high-level Enbox API instance. */
+  enbox: Enbox;
+
+  /** The active session returned by `AuthManager.connect()`. */
+  session: AuthSession;
+};