@synonymdev/pubky 0.10.0-alpha.0 → 0.11.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@synonymdev/pubky",
   "type": "module",
-  "description": "Pubky client",
-  "version": "0.10.0-alpha.0",
+  "description": "Decentralized identity, auth flows, and user-owned storage",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pubky/pubky-core.git"
+    "url": "git+https://github.com/pubky/pubky-homeserver.git"
   },
   "scripts": {
     "testnet": "cargo run -p pubky-testnet",
@@ -16,6 +16,7 @@
     "test-browser": "npm run build:test && browserify dist/tests/setup.js dist/tests/*.js -p esmify | npx tape-run",
     "test-browser:ci": "npm run build:test && browserify dist/tests/setup.js dist/tests/*.js -p esmify | tape-run --browser electron --electron-arg=--no-sandbox --electron-arg=--disable-gpu",
     "build": "cargo run --bin bundle_npm",
+    "docs": "typedoc",
     "prepublishOnly": "npm run build"
   },
   "files": [
@@ -42,9 +43,13 @@
     "esmify": "^2.1.1",
     "tape": "^5.8.1",
     "tape-run": "^11.0.0",
+    "typedoc": "^0.28.20",
     "typescript": "^5.4.5"
   },
   "dependencies": {
     "fetch-cookie": "^3.0.1"
+  },
+  "overrides": {
+    "electron": "41.0.2"
   }
 }

package/pubky.d.ts

@@ -21,6 +21,31 @@ type ReadableStreamType = "bytes";
  */
 export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
 
+/**
+ * Optional x-callback-url metadata carried by a Pubky deep link.
+ *
+ * Callback destinations are untrusted navigation hints. Authentication still
+ * completes through the encrypted relay.
+ */
+export interface XCallbackParams {
+    /**
+     * Human-readable name of the requesting application.
+     */
+    xSource?: string | null;
+    /**
+     * Destination to open after successful completion.
+     */
+    xSuccess?: string | null;
+    /**
+     * Destination to open after an error.
+     */
+    xError?: string | null;
+    /**
+     * Destination to open after user cancellation or timeout.
+     */
+    xCancel?: string | null;
+}
+
 /**
  * Options for starting a grant-backed pubkyauth flow.
  */
@@ -34,6 +59,10 @@ export interface GrantAuthFlowOptions {
      * Defaults to the default Synonym-hosted relay when omitted.
      */
     relay?: string | null;
+    /**
+     * Optional return destinations for success, error, and cancellation.
+     */
+    xCallback?: XCallbackParams | null;
 }
 
 /**
@@ -251,6 +280,9 @@ export class AuthFlow {
      * Optional HTTP relay base, e.g. `"https://demo.httprelay.io/inbox/"`.
      * Defaults to the default Synonym-hosted relay when omitted.
      *
+     * @param {XCallbackParams} [xCallback]
+     * Optional return destinations for success, error, and cancellation.
+     *
      * @returns {AuthFlow}
      * A running auth flow. Call `authorizationUrl()` to show the deep link,
      * then `awaitApproval()` to receive a `Session`.
@@ -264,7 +296,7 @@ export class AuthFlow {
      *
      * @deprecated Use `GrantAuthFlow.start(...)` instead.
      */
-    static start(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
+    static start(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null, x_callback?: XCallbackParams | null): AuthFlow;
     /**
      * Non-blocking single poll step (advanced UIs).
      *
@@ -406,6 +438,51 @@ export class AuthToken {
     readonly publicKey: PublicKey;
 }
 
+/**
+ * Browser-backed durable store for completed grant sessions.
+ */
+export class BrowserSessionStore {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Clear all local stored session records for this origin.
+     *
+     * Delegated keys referenced by those stored session records are removed.
+     * Delegated keys that only belong to pending grant flows are preserved.
+     */
+    clear(): Promise<void>;
+    /**
+     * Clear all browser auth persistence owned by this SDK origin.
+     *
+     * This removes all stored session records and all browser-held delegated
+     * grant keys, including keys for pending delegated grant flows. Saved
+     * delegated flow state becomes unrestorable. This does not revoke remote
+     * grants or immediately invalidate already-live in-memory sessions.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Whether IndexedDB is available for durable session persistence.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * List all locally stored sessions for this origin.
+     */
+    list(): Promise<StoredSessionInfo[]>;
+    /**
+     * Remove local stored session metadata and any SDK-owned delegated key for that record.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Restore a specific stored session by id.
+     */
+    restore(id: string): Promise<Session>;
+    /**
+     * Persist a completed grant session in IndexedDB.
+     */
+    save(session: Session): Promise<StoredSessionInfo>;
+}
+
 /**
  * Low-level HTTP bridge used by the Pubky facade and actors.
  *
@@ -499,6 +576,32 @@ export class CookieSession {
     exportSecret(): Promise<string>;
 }
 
+/**
+ * Parsed direct signup deeplink.
+ */
+export class DirectSignupDeepLink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Parse a direct signup deeplink URL.
+     */
+    static parse(url: string): DirectSignupDeepLink;
+    toString(): string;
+    /**
+     * Homeserver public key requested for account creation.
+     */
+    readonly homeserver: PublicKey;
+    /**
+     * Optional signup token included in the request.
+     */
+    readonly signupToken: string | undefined;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
+}
+
 /**
  * A single event from the event stream.
  *
@@ -559,6 +662,15 @@ export class Event {
  *   console.log(event.eventType, event.resource.path);
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Private events: attach a session and request a `/priv/...` path.
+ * const stream = await pubky.eventStreamForUser(userPubkey, null)
+ *   .session(session)
+ *   .path("/priv/app/")
+ *   .subscribe();
+ * ```
  */
 export class EventStreamBuilder {
     private constructor();
@@ -628,12 +740,17 @@ export class EventStreamBuilder {
      */
     live(): EventStreamBuilder;
     /**
-     * Filter events by path prefix.
+     * Filter events by path. Call once per path to receive the
+     * union of several scopes (e.g. `/pub/` plus a private `/priv/app/`).
      *
-     * Format: Path WITHOUT `pubky://` scheme or user pubkey (e.g., "/pub/files/" or "/pub/").
-     * Only events whose path starts with this prefix are returned.
+     * Format: a path WITHOUT the `pubky://` scheme or user pubkey. A trailing
+     * slash matches a directory and all its descendants (`/pub/files/`); no
+     * trailing slash matches an exact file (`/pub/notes.txt`).
      *
-     * @param {string} path - Path prefix to filter by
+     * Private (`/priv/...`) paths require a session attached via `session()`;
+     * without one the homeserver rejects the subscription with 401.
+     *
+     * @param {string} path - Path filter (repeatable)
      * @returns {EventStreamBuilder} - Builder for chaining
      */
     path(path: string): EventStreamBuilder;
@@ -649,6 +766,19 @@ export class EventStreamBuilder {
      * @returns {EventStreamBuilder} - Builder for chaining
      */
     reverse(): EventStreamBuilder;
+    /**
+     * Authenticate the subscription with a user `Session`.
+     *
+     * Required to receive private (`/priv/...`) events: the session credential
+     * (grant or cookie) is attached so the homeserver can authorize each private
+     * `path()` against the session's read capabilities. Public subscriptions
+     * don't need this.
+     *
+     *
+     * @param {Session} session - The authenticated session
+     * @returns {EventStreamBuilder} - Builder for chaining
+     */
+    session(session: Session): EventStreamBuilder;
     /**
      * Subscribe to the event stream.
      *
@@ -699,20 +829,37 @@ export class GrantAuthFlow {
      * **Security:** `savedState` contains the relay secret and PoP client private key.
      * Store it only temporarily and delete it once the flow completes or is abandoned.
      *
-     * @param {string} savedState A string produced by `grantFlow.save()`.
+     * @param {string} savedState A string produced by `grantFlow.saveLocal()`.
      * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
      */
     static resume(saved_state: string): GrantAuthFlow;
     /**
-     * Save sensitive state required to resume this pending grant flow.
+     * Resume a previously saved pending delegated grant auth flow.
+     *
+     * Runtime: delegated grant keys require a secure browser context with
+     * WebCrypto `crypto.subtle` and IndexedDB. The saved `keyId` must still
+     * exist in IndexedDB for the same origin. Unsupported runtimes reject with
+     * `ClientStateError`.
+     */
+    static resumeDelegated(saved_state: string): Promise<GrantAuthFlow>;
+    /**
+     * Save sensitive state required to resume this delegated pending grant flow.
+     *
+     * This does not export the delegated private key, but it includes the relay
+     * secret in the authorization URL. Store it only temporarily and delete it
+     * once the flow completes or is abandoned.
+     */
+    saveDelegated(): string;
+    /**
+     * Save sensitive state required to resume this pending local grant flow.
      *
      * @returns {string} Opaque state for `GrantAuthFlow.resume()` or
      * `pubky.resumeGrantAuthFlow()`.
      */
-    save(): string;
+    saveLocal(): string;
     /**
-     * Start a grant-backed flow (standalone).
-     * Prefer `pubky.startGrantAuthFlow()` to reuse a facade client.
+     * Start a grant-backed flow with a new DHT client.
+     * Prefer `pubky.startGrantAuthFlow()` to reuse a facade DHT client.
      *
      * @param {string} capabilities
      * Comma-separated capabilities, e.g. `"/pub/app/:rw,/priv/foo.txt:r"`.
@@ -722,13 +869,24 @@ export class GrantAuthFlow {
      * The kind of authentication flow to perform.
      *
      * @param {GrantAuthFlowOptions} options
-     * Options for the grant flow: `{ clientId, relay? }`.
+     * Options for the grant flow: `{ clientId, relay?, xCallback? }`.
      *
      * @returns {GrantAuthFlow}
      * A running grant auth flow. Call `authorizationUrl()` to show the deep link,
      * then `awaitApproval()` to receive a grant-backed `Session`.
      */
     static start(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): GrantAuthFlow;
+    /**
+     * Start a browser delegated grant-backed flow.
+     *
+     * The SDK creates a fresh non-extractable WebCrypto Ed25519 key in
+     * IndexedDB and uses that key for grant Proof-of-Possession signing.
+     *
+     * Runtime: delegated grant keys require a secure browser context with
+     * WebCrypto `crypto.subtle` and IndexedDB. Unsupported runtimes reject
+     * with `ClientStateError`.
+     */
+    static startDelegated(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): Promise<GrantAuthFlow>;
     /**
      * Non-blocking single poll step (advanced UIs).
      *
@@ -739,6 +897,14 @@ export class GrantAuthFlow {
      * Return the authorization deep link (URL) to show as QR or open on the signer device.
      */
     readonly authorizationUrl: string;
+    /**
+     * Whether delegated grant auth is available in the current JS runtime.
+     *
+     * This checks for a secure browser context with WebCrypto `crypto.subtle`
+     * and IndexedDB. It is a coarse synchronous feature-detection helper only;
+     * some runtimes expose those primitives without Ed25519 support.
+     */
+    static readonly isDelegationAvailable: boolean;
 }
 
 /**
@@ -815,14 +981,14 @@ export class GrantSession {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Export the durable refresh material needed to restore this grant session.
+     * Export the portable local secret material needed to restore this grant session.
      *
      * Treat the returned string as bearer-equivalent secret material until the
      * grant expires or is revoked.
      *
      * @returns {Promise<string>}
      */
-    exportSecret(): Promise<string>;
+    exportLocalSecret(): Promise<string>;
     /**
      * Current grant id (`jti`) backing this session.
      *
@@ -957,13 +1123,17 @@ export class Pkdns {
      * Resolve the homeserver for **this** user (requires keypair).
      *
      * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
+     * @throws When no keypair is attached, Pkarr resolution fails, or a resolved `_pubky` target
+     *   is malformed.
      */
     getHomeserver(): Promise<PublicKey | undefined>;
     /**
      * Resolve the homeserver for a given public key (read-only).
      *
      * @param {PublicKey} user
-     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
+     * @returns {Promise<PublicKey|undefined>} Homeserver public key, or `undefined` when the
+     *   user has no resolvable homeserver record.
+     * @throws When Pkarr resolution fails or a resolved `_pubky` target is malformed.
      */
     getHomeserverOf(pubky: PublicKey): Promise<PublicKey | undefined>;
     /**
@@ -1048,7 +1218,9 @@ export class Pubky {
      * Uses an internal read-only Pkdns actor.
      *
      * @param {PublicKey} user
-     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
+     * @returns {Promise<PublicKey|undefined>} Homeserver public key, or `undefined` when the
+     *   user has no resolvable homeserver record.
+     * @throws When Pkarr resolution fails or a resolved `_pubky` target is malformed.
      */
     getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
     /**
@@ -1069,11 +1241,11 @@ export class Pubky {
     /**
      * Restore a session from a previously exported token or snapshot, using this instance's client.
      *
-     * Accepts grant secret tokens from `session.exportSecret()` and legacy cookie
+     * Accepts grant secret tokens from `session.exportLocalSecret()` and legacy cookie
      * secret tokens. Also accepts legacy cookie metadata snapshots from `session.export()`.
      * Grant restore mints a fresh short-lived bearer.
      *
-     * @param {string} exported A string produced by `session.exportSecret()` or legacy `session.export()`.
+     * @param {string} exported A string produced by `session.exportLocalSecret()` or legacy `session.export()`.
      * @returns {Promise<Session>}
      * A rehydrated session bound to this SDK's HTTP client.
      *
@@ -1084,11 +1256,17 @@ export class Pubky {
     /**
      * Resume a previously started **pubkyauth** flow from its saved `authorizationUrl`.
      *
+     * If the user refreshes or navigates away mid-flow, WASM memory is lost and
+     * the original `AuthFlow` object is gone. You can reconnect to the same relay
+     * channel by saving the `authorizationUrl` beforehand and calling this method
+     * after reload.
+     *
      * The relay inbox retains messages for **~5 minutes**. Resume is only
      * viable within that window; afterwards start a fresh flow.
      *
      * **Security:** The URL contains the `client_secret` in plaintext.
-     * Delete it from storage as soon as the resumed flow completes.
+     * Store it in `sessionStorage` (scoped to the tab), **not** `localStorage`,
+     * and delete it as soon as the resumed flow completes or is abandoned.
      * See `startCookieAuthFlow()` docs for full storage guidance.
      *
      * @param {string} authorizationUrl The `pubkyauth://…` URL from a previous flow.
@@ -1096,15 +1274,41 @@ export class Pubky {
      * @throws {PubkyError}
      * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
      * - `{ name: "RequestError" }` on network/relay failure
+     *
+     * @example
+     * // 1) Before a potential refresh, persist the URL.
+     * const flow = pubky.startCookieAuthFlow("/pub/my-cool-app/:rw", AuthFlowKind.signin());
+     * sessionStorage.setItem("pubky-auth-url", flow.authorizationUrl);
+     * renderQr(flow.authorizationUrl);
+     *
+     * // 2) After reload, resume from the saved URL.
+     * const savedUrl = sessionStorage.getItem("pubky-auth-url");
+     * if (savedUrl) {
+     *   try {
+     *     const resumed = pubky.resumeCookieAuthFlow(savedUrl);
+     *     const session = await resumed.awaitApproval();
+     *   } finally {
+     *     sessionStorage.removeItem("pubky-auth-url");
+     *   }
+     * }
      */
     resumeCookieAuthFlow(authorization_url: string): AuthFlow;
+    /**
+     * Resume a previously saved pending delegated grant auth flow.
+     *
+     * Runtime: delegated grant keys require a secure browser context with
+     * WebCrypto `crypto.subtle` and IndexedDB. The saved `keyId` must still
+     * exist in IndexedDB for the same origin. Unsupported runtimes reject with
+     * `ClientStateError`.
+     */
+    resumeDelegatedGrantAuthFlow(saved_state: string): Promise<GrantAuthFlow>;
     /**
      * Resume a previously saved pending grant auth flow.
      *
      * **Security:** `savedState` contains the relay secret and PoP client private key.
      * Delete it from storage as soon as the resumed flow completes.
      *
-     * @param {string} savedState A string produced by `grantFlow.save()`.
+     * @param {string} savedState A string produced by `grantFlow.saveLocal()`.
      * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
      */
     resumeGrantAuthFlow(saved_state: string): GrantAuthFlow;
@@ -1139,6 +1343,7 @@ export class Pubky {
      * - `AuthFlowKind.signin()` - Sign in to an existing account.
      * - `AuthFlowKind.signup(homeserverPublicKey, signupToken)` - Sign up for a new account.
      * @param {string=} relay Optional HTTP relay base (e.g. `"https://…/inbox/"`).
+     * @param {XCallbackParams=} xCallback Optional app return destinations.
      * @returns {AuthFlow}
      * A running auth flow. Show `authorizationUrl` as QR/deeplink,
      * then `awaitApproval()` to obtain a `Session`.
@@ -1152,7 +1357,7 @@ export class Pubky {
      * renderQr(flow.authorizationUrl);
      * const session = await flow.awaitApproval();
      */
-    startCookieAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
+    startCookieAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null, x_callback?: XCallbackParams | null): AuthFlow;
     /**
      * Start a grant-backed **pubkyauth** flow.
      *
@@ -1161,19 +1366,20 @@ export class Pubky {
      *
      * @param {string} capabilities Comma-separated caps, e.g. `"/pub/app/:rw,/pub/foo/file:r"`.
      * @param {AuthFlowKind} kind The kind of authentication flow to perform.
-     * @param {GrantAuthFlowOptions} options Options for the grant flow: `{ clientId, relay? }`.
-     * @returns {GrantAuthFlow}
+     * @param {GrantAuthFlowOptions} options Options for the grant flow:
+     * `{ clientId, relay?, xCallback? }`.
+     * @returns {Promise<GrantAuthFlow>}
      * A running grant auth flow. Show `authorizationUrl` as QR/deeplink,
      * then `awaitApproval()` to obtain a grant-backed `Session`.
      *
      * @example
-     * const flow = pubky.startGrantAuthFlow(
+     * const flow = await pubky.startGrantAuthFlow(
      *   "/pub/my-cool-app/:rw",
      *   AuthFlowKind.signin(),
      *   { clientId: "my-cool-app.example" },
      * );
      */
-    startGrantAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): GrantAuthFlow;
+    startGrantAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): Promise<GrantAuthFlow>;
     /**
      * Create a Pubky facade preconfigured for a **local testnet**.
      *
@@ -1199,6 +1405,14 @@ export class Pubky {
      * const pubky = Pubky.withClient(client);
      */
     static withClient(client: Client): Pubky;
+    /**
+     * Browser-backed store for explicitly persisted completed grant sessions.
+     *
+     * Use `browserSessionStore.save(session)` after a successful grant auth flow to make
+     * the session restorable after reload. The store supports multiple accounts
+     * and multiple grants per account.
+     */
+    readonly browserSessionStore: BrowserSessionStore;
     /**
      * Access the underlying HTTP client (advanced).
      *
@@ -1367,6 +1581,10 @@ export class SeedExportDeepLink {
     static parse(url: string): SeedExportDeepLink;
     toString(): string;
     readonly secret: Uint8Array;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
 }
 
 /**
@@ -1387,15 +1605,16 @@ export class Session {
      * @returns {string}
      * A base64 string to store (e.g. in `localStorage`).
      *
-     * @deprecated Prefer `exportSecret()` for grant sessions.
+     * @deprecated Prefer `exportLocalSecret()` for grant sessions.
      */
     export(): string;
     /**
-     * Export the secret material needed to restore this session.
+     * Export the local secret material needed to restore this session.
      *
-     * For grant sessions this exports the grant JWS and PoP client secret; restoring
-     * mints a fresh bearer. For legacy cookie sessions this exports the cookie secret
-     * when the SDK owns it.
+     * For local grant sessions this exports the grant JWS and PoP client secret;
+     * restoring mints a fresh bearer. For legacy cookie sessions this exports the
+     * cookie secret when the SDK owns it. Delegated browser grant sessions cannot
+     * export raw secret material; use `BrowserSessionStore`.
      *
      * Treat the returned string as a bearer-equivalent secret until the grant or
      * cookie session expires or is revoked.
@@ -1403,7 +1622,7 @@ export class Session {
      * @returns {Promise<string>}
      * A secret token that can be passed to `pubky.restoreSession()`.
      */
-    exportSecret(): Promise<string>;
+    exportLocalSecret(): Promise<string>;
     /**
      * Restore a session from an `export()` string.
      *
@@ -1599,6 +1818,13 @@ export class Signer {
      * @returns {Signer}
      */
     static fromKeypair(keypair: Keypair): Signer;
+    /**
+     * Handle a `pubkyauth://` deep link.
+     *
+     * Auth requests are approved through their relay. A `direct_signup` link
+     * creates an account on its target homeserver.
+     */
+    handleDeepLink(pubkyauth_url: string): Promise<void>;
     /**
      * Fast sign-in for a returning user. Publishes PKDNS in the background.
      *
@@ -1679,6 +1905,10 @@ export class SigninDeepLink {
     readonly baseRelayUrl: string;
     readonly capabilities: string;
     readonly secret: Uint8Array;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
 }
 
 /**
@@ -1737,6 +1967,10 @@ export class SigninGrantDeepLink {
      * @returns {Uint8Array}
      */
     readonly secret: Uint8Array;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
 }
 
 export class SignupDeepLink {
@@ -1750,6 +1984,10 @@ export class SignupDeepLink {
     readonly homeserver: PublicKey;
     readonly secret: Uint8Array;
     readonly signupToken: string | undefined;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
 }
 
 /**
@@ -1820,6 +2058,55 @@ export class SignupGrantDeepLink {
      * @returns {string|undefined}
      */
     readonly signupToken: string | undefined;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
+}
+
+/**
+ * Metadata for a session saved in the browser session store.
+ */
+export class StoredSessionInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Authorized capabilities.
+     */
+    readonly capabilities: string[];
+    /**
+     * Application/client identifier.
+     */
+    readonly clientId: string;
+    /**
+     * Local save timestamp, in Unix milliseconds.
+     */
+    readonly createdAt: number;
+    /**
+     * Underlying grant expiry timestamp, in Unix seconds.
+     */
+    readonly grantExpiresAt: number;
+    /**
+     * Grant identifier backing this stored session.
+     */
+    readonly grantId: string;
+    /**
+     * Homeserver public key as z32.
+     */
+    readonly homeserver: string;
+    /**
+     * Stable local identifier for this stored session.
+     */
+    readonly id: string;
+    /**
+     * User public key as z32.
+     */
+    readonly publicKey: string;
+    /**
+     * `delegated` for origin-bound WebCrypto sessions, `localSecret` for raw local PoP secret storage.
+     */
+    readonly storageMode: string;
 }
 
 /**
@@ -1857,11 +2144,11 @@ export function setLogLevel(level: Level): void;
  * Validate and normalize a capabilities string.
  *
  * - Normalizes action order (`wr` -> `rw`)
- * - Throws `InvalidInput` listing malformed entries.
+ * - Throws `InvalidInput` identifying the first malformed entry.
  *
  * @param {string} input
  * @returns {string} Normalized string (same shape as input).
  * @throws {PubkyError} `{ name: "InvalidInput" }` with a helpful message.
- * The error's `data` field is `{ invalidEntries: string[] }` listing malformed tokens.
+ * The error's `data` field is `{ invalidEntries: string[] }` containing the malformed token.
  */
 export function validateCapabilities(input: string): string;