@synonymdev/pubky 0.9.3 → 0.10.0

package/pubky.d.ts

@@ -21,6 +21,50 @@ 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.
+ */
+export interface GrantAuthFlowOptions {
+    /**
+     * App identifier shown in the user\'s grant/session list, typically a domain.
+     */
+    clientId: string;
+    /**
+     * Optional HTTP relay base, e.g. `\"https://demo.httprelay.io/inbox/\"`.
+     * Defaults to the default Synonym-hosted relay when omitted.
+     */
+    relay?: string | null;
+    /**
+     * Optional return destinations for success, error, and cancellation.
+     */
+    xCallback?: XCallbackParams | null;
+}
+
 /**
  * Pkarr Config
  */
@@ -160,16 +204,18 @@ export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
 type CapabilitiesTail = `,${CapabilityEntry}${string}`;
 export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
 
-export type Path = `/pub/${string}`;
+export type Path = `/pub/${string}` | `/priv/${string}`;
 
 
 /**
  * Start and control a pubkyauth authorization flow.
  *
  * Typical flow:
- * 1) `AuthFlow.start(...)` or `pubky.startAuthFlow(...)`
+ * 1) `AuthFlow.start(...)` or `pubky.startCookieAuthFlow(...)`
  * 2) Show `authorizationUrl()` as QR/deeplink to the user’s signing device
  * 3) `awaitApproval()` to receive a ready `Session`
+ *
+ * @deprecated Use `GrantAuthFlow` instead.
  */
 export class AuthFlow {
     private constructor();
@@ -198,10 +244,10 @@ export class AuthFlow {
     awaitToken(): Promise<AuthToken>;
     /**
      * Resume a previously started auth flow from its saved `authorizationUrl` (standalone).
-     * Prefer `pubky.resumeAuthFlow()` to reuse a facade client; this creates a default (mainnet) client.
+     * Prefer `pubky.resumeCookieAuthFlow()` to reuse a facade client; this creates a default (mainnet) client.
      *
      * Relay messages expire after ~5 minutes; resume is only viable in that window.
-     * See `Pubky.resumeAuthFlow()` / `Pubky.startAuthFlow()` for full guidance.
+     * See `Pubky.resumeCookieAuthFlow()` / `Pubky.startCookieAuthFlow()` for full guidance.
      *
      * **Security:** `authorizationUrl` contains the `client_secret`.
      * Delete it from storage as soon as resume completes or is abandoned.
@@ -214,7 +260,7 @@ export class AuthFlow {
     static resume(authorization_url: string): AuthFlow;
     /**
      * Start a flow (standalone).
-     * Prefer `pubky.startAuthFlow()` to reuse a facade client.
+     * Prefer `pubky.startCookieAuthFlow()` to reuse a facade client.
      *
      * @param {string} capabilities
      * Comma-separated capabilities, e.g. `"/pub/app/:rw,/priv/foo.txt:r"`.
@@ -234,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`.
@@ -244,8 +293,10 @@ export class AuthFlow {
      * const flow = AuthFlow.start("/pub/my-cool-app/:rw,/pub/pubky.app/:w");
      * renderQRCode(flow.authorizationUrl());
      * const session = await flow.awaitApproval();
+     *
+     * @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).
      *
@@ -257,7 +308,7 @@ export class AuthFlow {
      *
      * **Security:** This URL contains the `client_secret` in plaintext.
      * Treat it as a short-lived secret and delete it after the flow completes.
-     * See `Pubky.startAuthFlow()` docs for storage guidance.
+     * See `Pubky.startCookieAuthFlow()` docs for storage guidance.
      *
      * @returns {string} A `pubkyauth://…` or `https://…` URL with channel info.
      *
@@ -305,7 +356,7 @@ export class AuthFlowKind {
  * ### Typical usage
  * ```js
  * // Start an auth-only flow (no capabilities)
- * const flow = pubky.startAuthFlow("", relay);
+ * const flow = pubky.startCookieAuthFlow("", relay);
  *
  * // Wait for the signer to approve; returns an AuthToken
  * const token = await flow.awaitToken();
@@ -367,7 +418,7 @@ export class AuthToken {
     /**
      * Returns the **capabilities** requested by the flow at the time this token was signed.
      *
-     * Most auth-only flows pass an empty string to `startAuthFlow("", relay)`, so this will
+     * Most auth-only flows pass an empty string to `startCookieAuthFlow("", relay)`, so this will
      * commonly be an empty array.
      *
      * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
@@ -387,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.
  *
@@ -450,6 +546,62 @@ export class Client {
     static testnet(host?: string | null): Client;
 }
 
+/**
+ * Cookie-only view over a cookie-backed `Session`.
+ *
+ * Grant-backed sessions do not expose this view; use `session.cookie` and
+ * check for `undefined` before calling cookie-specific methods.
+ */
+export class CookieSession {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Export session metadata for legacy cookie restore.
+     *
+     * The returned string contains no secrets; the browser cookie jar must
+     * still hold the HTTP-only cookie.
+     *
+     * @returns {string}
+     */
+    export(): string;
+    /**
+     * Export the cookie secret needed to restore this cookie session.
+     *
+     * This is available when the SDK captured the cookie secret, such as in
+     * Node.js. Browser sessions cannot read HTTP-only Set-Cookie values.
+     *
+     * @returns {Promise<string>}
+     */
+    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.
  *
@@ -510,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();
@@ -579,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: 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`).
      *
-     * Format: Path WITHOUT `pubky://` scheme or user pubkey (e.g., "/pub/files/" or "/pub/").
-     * Only events whose path starts with this prefix are returned.
+     * Private (`/priv/...`) paths require a session attached via `session()`;
+     * without one the homeserver rejects the subscription with 401.
      *
-     * @param {string} path - Path prefix to filter by
+     * @param {string} path - Path filter (repeatable)
      * @returns {EventStreamBuilder} - Builder for chaining
      */
     path(path: string): EventStreamBuilder;
@@ -600,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.
      *
@@ -627,6 +806,244 @@ export class EventStreamBuilder {
     subscribe(): Promise<ReadableStream>;
 }
 
+/**
+ * Start and control a grant-backed pubkyauth authorization flow.
+ *
+ * Typical flow:
+ * 1) `GrantAuthFlow.start(...)` or `pubky.startGrantAuthFlow(...)`
+ * 2) Show `authorizationUrl()` as QR/deeplink to the user's signing device
+ * 3) `awaitApproval()` to receive a grant-backed, self-refreshing `Session`
+ */
+export class GrantAuthFlow {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Block until the user approves on their signer device; returns a grant-backed `Session`.
+     */
+    awaitApproval(): Promise<Session>;
+    /**
+     * Resume a previously saved pending grant auth flow (standalone).
+     * Prefer `pubky.resumeGrantAuthFlow()` to reuse a facade client.
+     *
+     * **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.saveLocal()`.
+     * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
+     */
+    static resume(saved_state: string): GrantAuthFlow;
+    /**
+     * 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()`.
+     */
+    saveLocal(): string;
+    /**
+     * 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"`.
+     * Empty string is allowed (no scopes).
+     *
+     * @param {AuthFlowKind} kind
+     * The kind of authentication flow to perform.
+     *
+     * @param {GrantAuthFlowOptions} options
+     * 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).
+     *
+     * @returns {Promise<Session|undefined>} A session if the approval arrived, otherwise `undefined`.
+     */
+    tryPollOnce(): Promise<Session | undefined>;
+    /**
+     * 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;
+}
+
+/**
+ * Summary of an active grant returned by `GrantManager.list()`.
+ */
+export class GrantInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Comma-separated capabilities authorized by the grant.
+     */
+    readonly capabilities: string;
+    /**
+     * Application identifier.
+     */
+    readonly clientId: string;
+    /**
+     * Expiry timestamp, in Unix seconds.
+     */
+    readonly expiresAt: number;
+    /**
+     * Grant identifier used for revocation.
+     */
+    readonly grantId: string;
+    /**
+     * Issued-at timestamp, in Unix seconds.
+     */
+    readonly issuedAt: number;
+}
+
+/**
+ * Account-level grant management for a signed-in user.
+ */
+export class GrantManager {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * List all active grants for this user.
+     *
+     * Requires a root-capability session. Non-root sessions surface the
+     * homeserver `403` as the standard request error.
+     *
+     * @returns {Promise<GrantInfo[]>}
+     */
+    list(): Promise<GrantInfo[]>;
+    /**
+     * Create a grant manager authenticated by a session.
+     *
+     * @param {Session} session
+     * @returns {GrantManager}
+     */
+    constructor(session: Session);
+    /**
+     * Revoke a specific grant by id.
+     *
+     * Requires a root-capability session. Malformed ids throw
+     * `InvalidInput`.
+     *
+     * @param {string} grantId
+     * @returns {Promise<void>}
+     */
+    revoke(grant_id: string): Promise<void>;
+}
+
+/**
+ * Grant-only view over a grant-backed `Session`.
+ *
+ * Cookie-backed sessions do not expose this view; use `session.grant` and
+ * check for `undefined` before calling grant-session methods.
+ */
+export class GrantSession {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * 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>}
+     */
+    exportLocalSecret(): Promise<string>;
+    /**
+     * Current grant id (`jti`) backing this session.
+     *
+     * @returns {Promise<string>}
+     */
+    grantId(): Promise<string>;
+    /**
+     * Full grant session metadata.
+     *
+     * @returns {Promise<GrantSessionInfo>}
+     */
+    sessionInfo(): Promise<GrantSessionInfo>;
+}
+
+/**
+ * Grant-specific session metadata returned by `grant.sessionInfo()`.
+ */
+export class GrantSessionInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Authorized capabilities for this session.
+     */
+    readonly capabilities: string[];
+    /**
+     * Application identifier.
+     */
+    readonly clientId: string;
+    /**
+     * Session creation timestamp, in Unix seconds.
+     */
+    readonly createdAt: number;
+    /**
+     * Underlying grant expiry timestamp, in Unix seconds.
+     */
+    readonly grantExpiresAt: number;
+    /**
+     * Grant id this session was minted from.
+     */
+    readonly grantId: string;
+    /**
+     * Homeserver that issued this session.
+     */
+    readonly homeserver: PublicKey;
+    /**
+     * User public key for this session.
+     */
+    readonly publicKey: PublicKey;
+    /**
+     * Bearer token expiry timestamp, in Unix seconds.
+     */
+    readonly tokenExpiresAt: number;
+}
+
 export class IntoUnderlyingByteSource {
     private constructor();
     free(): void;
@@ -706,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>;
     /**
@@ -797,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>;
     /**
@@ -816,12 +1239,13 @@ export class Pubky {
      */
     constructor();
     /**
-     * Restore a session from a previously exported snapshot, using this instance's client.
+     * Restore a session from a previously exported token or snapshot, using this instance's client.
      *
-     * This does **not** read or write any secrets. It revalidates the session metadata with
-     * the server using the browser-managed HTTP-only cookie that must still be present.
+     * 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.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.
      *
@@ -832,20 +1256,62 @@ 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.
-     * See `startAuthFlow()` docs for full storage guidance.
+     * 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.
      * @returns {AuthFlow} A flow reconnected to the original relay channel.
      * @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.saveLocal()`.
+     * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
      */
-    resumeAuthFlow(authorization_url: string): AuthFlow;
+    resumeGrantAuthFlow(saved_state: string): GrantAuthFlow;
     /**
      * Create a `Signer` from an existing `Keypair`.
      *
@@ -854,7 +1320,7 @@ export class Pubky {
      *
      * @example
      * const signer = pubky.signer(Keypair.random());
-     * const session = await signer.signup(homeserverPk, null);
+     * await signer.signup(homeserverPk);
      */
     signer(keypair: Keypair): Signer;
     /**
@@ -877,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`.
@@ -886,11 +1353,33 @@ export class Pubky {
      * - `{ name: "RequestError" }` if the flow cannot be started (network/relay)
      *
      * @example
-     * const flow = pubky.startAuthFlow("/pub/my-cool-app/:rw");
+     * const flow = pubky.startCookieAuthFlow("/pub/my-cool-app/:rw");
      * renderQr(flow.authorizationUrl);
      * const session = await flow.awaitApproval();
      */
-    startAuthFlow(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.
+     *
+     * Grant auth uses a user-signed grant JWS plus Proof-of-Possession and
+     * returns a self-refreshing session.
+     *
+     * @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?, 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 = await pubky.startGrantAuthFlow(
+     *   "/pub/my-cool-app/:rw",
+     *   AuthFlowKind.signin(),
+     *   { clientId: "my-cool-app.example" },
+     * );
+     */
+    startGrantAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): Promise<GrantAuthFlow>;
     /**
      * Create a Pubky facade preconfigured for a **local testnet**.
      *
@@ -916,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).
      *
@@ -1084,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;
 }
 
 /**
@@ -1103,8 +1604,25 @@ export class Session {
      *
      * @returns {string}
      * A base64 string to store (e.g. in `localStorage`).
+     *
+     * @deprecated Prefer `exportLocalSecret()` for grant sessions.
      */
     export(): string;
+    /**
+     * Export the local secret material needed to restore this session.
+     *
+     * 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.
+     *
+     * @returns {Promise<string>}
+     * A secret token that can be passed to `pubky.restoreSession()`.
+     */
+    exportLocalSecret(): Promise<string>;
     /**
      * Restore a session from an `export()` string.
      *
@@ -1116,6 +1634,8 @@ export class Session {
      * @param {Client=} client
      * Optional client to reuse transport configuration.
      * @returns {Promise<Session>}
+     *
+     * @deprecated Prefer `Pubky.restoreSession(...)`.
      */
     static restore(exported: string, client?: Client | null): Promise<Session>;
     /**
@@ -1125,6 +1645,22 @@ export class Session {
      * @returns {Promise<void>}
      */
     signout(): Promise<void>;
+    /**
+     * Cookie-only view for cookie-backed sessions.
+     *
+     * Grant-backed sessions return `undefined`.
+     *
+     * @returns {CookieSession|undefined}
+     */
+    readonly cookie: CookieSession | undefined;
+    /**
+     * Grant-only management view for grant-backed sessions.
+     *
+     * Cookie-backed sessions return `undefined`.
+     *
+     * @returns {GrantSession|undefined}
+     */
+    readonly grant: GrantSession | undefined;
     /**
      * Retrieve immutable info about this session (user & capabilities).
      *
@@ -1167,7 +1703,7 @@ export class SessionInfo {
 }
 
 /**
- * Read/write storage scoped to **your** session (absolute paths: `/pub/...`).
+ * Read/write storage scoped to **your** session (absolute paths: `/pub/...` or `/priv/...`).
  */
 export class SessionStorage {
     private constructor();
@@ -1282,38 +1818,67 @@ 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.
      *
-     * Creates a valid homeserver Session with root capabilities
+     * Creates a valid grant-backed homeserver Session with root capabilities.
+     * `clientId` is shown in the user's grant/session list.
+     * @param {string} clientId App identifier, typically a domain.
      *
      * @returns {Promise<Session>}
      *
      * @throws {PubkyError}
      */
-    signin(): Promise<Session>;
+    signin(client_id: string): Promise<Session>;
     /**
      * Blocking sign-in. Waits for PKDNS publish to complete (slower; safer).
      *
-     * Creates a valid homeserver Session with root capabilities
+     * Creates a valid grant-backed homeserver Session with root capabilities.
+     * `clientId` is shown in the user's grant/session list.
+     * @param {string} clientId App identifier, typically a domain.
      *
      * @returns {Promise<Session>}
      */
-    signinBlocking(): Promise<Session>;
+    signinBlocking(client_id: string): Promise<Session>;
+    /**
+     * Legacy cookie signin. Prefer `signin(clientId)`.
+     *
+     * @deprecated Prefer `signin(clientId)`.
+     */
+    signinCookie(): Promise<Session>;
+    /**
+     * Legacy cookie blocking signin. Prefer `signinBlocking(clientId)`.
+     *
+     * @deprecated Prefer `signinBlocking(clientId)`.
+     */
+    signinCookieBlocking(): Promise<Session>;
     /**
-     * Sign up at a homeserver. Returns a ready `Session`.
+     * Sign up at a homeserver.
      *
-     * Creates a valid homeserver Session with root capabilities
+     * Creates the account and publishes PKDNS. Call `signin(clientId)` to create a session.
      *
      * @param {PublicKey} homeserver The homeserver’s public key.
      * @param {string|null} signupToken Invite/registration token or `null`.
-     * @returns {Promise<Session>}
+     * @returns {Promise<void>}
      *
      * @throws {PubkyError}
      * - `AuthenticationError` (bad/expired token)
      * - `RequestError` (network/server)
      */
-    signup(homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
+    signup(homeserver: PublicKey, signup_token?: string | null): Promise<void>;
+    /**
+     * Legacy cookie signup. Prefer `signup()` plus `signin(clientId)`.
+     *
+     * @deprecated Prefer `signup()` followed by `signin(clientId)`.
+     */
+    signupCookie(homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
     /**
      * Get a PKDNS actor bound to this signer's client & keypair (publishing enabled).
      *
@@ -1340,6 +1905,72 @@ 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;
+}
+
+/**
+ * Parsed grant-based signin deeplink.
+ *
+ * This is useful for tools, tests, and signer UIs that need to inspect a
+ * `pubky://signin-grant` authorization URL before approving it.
+ */
+export class SigninGrantDeepLink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Parse a grant signin deeplink URL.
+     *
+     * @param {string} url
+     * @returns {SigninGrantDeepLink}
+     * @throws {PubkyError} `InvalidInput` when the URL is malformed or not a grant signin link.
+     */
+    static parse(url: string): SigninGrantDeepLink;
+    /**
+     * Serialize this parsed deeplink back to its URL form.
+     *
+     * @returns {string}
+     */
+    toString(): string;
+    /**
+     * Base HTTP relay inbox URL used by this auth request.
+     *
+     * @returns {string}
+     */
+    readonly baseRelayUrl: string;
+    /**
+     * Capabilities requested by the application.
+     *
+     * @returns {string}
+     */
+    readonly capabilities: string;
+    /**
+     * Application identifier shown in the user's grant/session list.
+     *
+     * @returns {string}
+     */
+    readonly clientId: string;
+    /**
+     * Public key for the Proof-of-Possession client created by the application.
+     *
+     * @returns {PublicKey}
+     */
+    readonly clientPublicKey: PublicKey;
+    /**
+     * Relay channel secret embedded in the deeplink.
+     *
+     * Treat this as sensitive temporary auth-flow material.
+     *
+     * @returns {Uint8Array}
+     */
+    readonly secret: Uint8Array;
+    /**
+     * Optional x-callback-url metadata carried by this deep link.
+     */
+    readonly xCallback: XCallbackParams;
 }
 
 export class SignupDeepLink {
@@ -1353,6 +1984,129 @@ 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;
+}
+
+/**
+ * Parsed grant-based signup deeplink.
+ *
+ * This is useful for tools, tests, and signer UIs that need to inspect a
+ * `pubky://signup-grant` authorization URL before approving it.
+ */
+export class SignupGrantDeepLink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Parse a grant signup deeplink URL.
+     *
+     * @param {string} url
+     * @returns {SignupGrantDeepLink}
+     * @throws {PubkyError} `InvalidInput` when the URL is malformed or not a grant signup link.
+     */
+    static parse(url: string): SignupGrantDeepLink;
+    /**
+     * Serialize this parsed deeplink back to its URL form.
+     *
+     * @returns {string}
+     */
+    toString(): string;
+    /**
+     * Base HTTP relay inbox URL used by this auth request.
+     *
+     * @returns {string}
+     */
+    readonly baseRelayUrl: string;
+    /**
+     * Capabilities requested by the application.
+     *
+     * @returns {string}
+     */
+    readonly capabilities: string;
+    /**
+     * Application identifier shown in the user's grant/session list.
+     *
+     * @returns {string}
+     */
+    readonly clientId: string;
+    /**
+     * Public key for the Proof-of-Possession client created by the application.
+     *
+     * @returns {PublicKey}
+     */
+    readonly clientPublicKey: PublicKey;
+    /**
+     * Homeserver public key requested for account creation.
+     *
+     * @returns {PublicKey}
+     */
+    readonly homeserver: PublicKey;
+    /**
+     * Relay channel secret embedded in the deeplink.
+     *
+     * Treat this as sensitive temporary auth-flow material.
+     *
+     * @returns {Uint8Array}
+     */
+    readonly secret: Uint8Array;
+    /**
+     * Optional signup token included in the request.
+     *
+     * @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;
 }
 
 /**
@@ -1390,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;