@synonymdev/pubky 0.9.3 → 0.10.0-alpha.0

package/pubky.d.ts

@@ -21,6 +21,21 @@ type ReadableStreamType = "bytes";
  */
 export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
 
+/**
+ * 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;
+}
+
 /**
  * Pkarr Config
  */
@@ -160,16 +175,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 +215,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 +231,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"`.
@@ -244,6 +261,8 @@ 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;
     /**
@@ -257,7 +276,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 +324,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 +386,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>"`.
@@ -450,6 +469,36 @@ 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>;
+}
+
 /**
  * A single event from the event stream.
  *
@@ -627,6 +676,208 @@ 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.save()`.
+     * @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.
+     *
+     * @returns {string} Opaque state for `GrantAuthFlow.resume()` or
+     * `pubky.resumeGrantAuthFlow()`.
+     */
+    save(): string;
+    /**
+     * Start a grant-backed flow (standalone).
+     * Prefer `pubky.startGrantAuthFlow()` to reuse a facade 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? }`.
+     *
+     * @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;
+    /**
+     * 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;
+}
+
+/**
+ * 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 durable refresh 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>;
+    /**
+     * 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;
@@ -816,12 +1067,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.exportSecret()` 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.exportSecret()` or legacy `session.export()`.
      * @returns {Promise<Session>}
      * A rehydrated session bound to this SDK's HTTP client.
      *
@@ -837,7 +1089,7 @@ export class Pubky {
      *
      * **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.
+     * 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.
@@ -845,7 +1097,17 @@ export class Pubky {
      * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
      * - `{ name: "RequestError" }` on network/relay failure
      */
-    resumeAuthFlow(authorization_url: string): AuthFlow;
+    resumeCookieAuthFlow(authorization_url: string): AuthFlow;
+    /**
+     * 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()`.
+     * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
+     */
+    resumeGrantAuthFlow(saved_state: string): GrantAuthFlow;
     /**
      * Create a `Signer` from an existing `Keypair`.
      *
@@ -854,7 +1116,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;
     /**
@@ -886,11 +1148,32 @@ 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): 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? }`.
+     * @returns {GrantAuthFlow}
+     * A running grant auth flow. Show `authorizationUrl` as QR/deeplink,
+     * then `awaitApproval()` to obtain a grant-backed `Session`.
+     *
+     * @example
+     * const flow = pubky.startGrantAuthFlow(
+     *   "/pub/my-cool-app/:rw",
+     *   AuthFlowKind.signin(),
+     *   { clientId: "my-cool-app.example" },
+     * );
+     */
+    startGrantAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): GrantAuthFlow;
     /**
      * Create a Pubky facade preconfigured for a **local testnet**.
      *
@@ -1103,8 +1386,24 @@ export class Session {
      *
      * @returns {string}
      * A base64 string to store (e.g. in `localStorage`).
+     *
+     * @deprecated Prefer `exportSecret()` for grant sessions.
      */
     export(): string;
+    /**
+     * Export the 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.
+     *
+     * 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()`.
+     */
+    exportSecret(): Promise<string>;
     /**
      * Restore a session from an `export()` string.
      *
@@ -1116,6 +1415,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 +1426,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 +1484,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();
@@ -1285,35 +1602,57 @@ export class Signer {
     /**
      * 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).
      *
@@ -1342,6 +1681,64 @@ export class SigninDeepLink {
     readonly secret: Uint8Array;
 }
 
+/**
+ * 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;
+}
+
 export class SignupDeepLink {
     private constructor();
     free(): void;
@@ -1355,6 +1752,76 @@ export class SignupDeepLink {
     readonly signupToken: string | undefined;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Resolve a `pubky://` or `pubky<pk>/…` identifier into the homeserver transport URL.
  *