Class Pubky

constructor

• new Pubky(): Pubky

  Create a Pubky facade wired for mainnet defaults (public relays).

  Prefer to instantiate only once and use trough your application a single shared Pubky instead of constructing one per request. This avoids reinitializing transports and keeps the same client available for repeated usage.

  Returns Pubky

  A new facade instance. Use this to create signers, start auth flows, etc.

  Example

  const pubky = new Pubky();
  const signer = pubky.signer(Keypair.random());
  Copy

ReadonlybrowserSessionStore

Readonlyclient

const r = await pubky.client.fetch(`pubky://${userPk.z32()}/pub/app/file.txt`, { credentials: "include" });
Copy

ReadonlypublicStorage

const text = await pubky.publicStorage.getText(`${userPk.toString()}/pub/example.com/hello.txt`);
Copy

[dispose]

• "[dispose]"(): void

  Returns void

eventStreamFor

• eventStreamFor(homeserver: PublicKey): EventStreamBuilder

  Create an event stream builder for a specific homeserver.

  Use this when you already know the homeserver pubkey. This avoids Pkarr resolution overhead. Obtain a homeserver pubkey via getHomeserverOf().

  Parameters

  • homeserver: PublicKey

    The homeserver public key

  Returns EventStreamBuilder

  • Builder for configuring and subscribing to the stream

  Example

  const homeserver = await pubky.getHomeserverOf(user1);
  const stream = await pubky.eventStreamFor(homeserver)
    .addUsers([[user1.z32(), null], [user2.z32(), null]])
    .live()
    .subscribe();
  
  for await (const event of stream) {
    console.log(`${event.eventType}: ${event.resource.path}`);
  }
  Copy

eventStreamForUser

• eventStreamForUser(user: PublicKey, cursor?: string | null): EventStreamBuilder

  Create an event stream builder for a single user.

  This is the simplest way to subscribe to events for one user. The homeserver is automatically resolved from the user's Pkarr record.

  Parameters

  • user: PublicKey

    The user's public key

  • Optionalcursor: string | null

    Optional cursor position to start from

  Returns EventStreamBuilder

  • Builder for configuring and subscribing to the stream

  Example

  const user = PublicKey.from("o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo");
  const stream = await pubky.eventStreamForUser(user, null)
    .live()
    .subscribe();
  
  for await (const event of stream) {
    console.log(`${event.eventType}: ${event.resource.path}`);
  }
  Copy

free

• free(): void

  Returns void

getHomeserverOf

• getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>

  Resolve the homeserver for a given public key (read-only).

  Uses an internal read-only Pkdns actor.

  Parameters

  • user_public_key: PublicKey

  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.

restoreSession

• restoreSession(exported: string): Promise<Session>

  Restore a session from a previously exported token or snapshot, using this instance's client.

  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.

  Parameters

  • exported: string

    A string produced by session.exportLocalSecret() or legacy session.export().

  Returns Promise<Session>

  A rehydrated session bound to this SDK's HTTP client.

  Example

  const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
  Copy

resumeCookieAuthFlow

• resumeCookieAuthFlow(authorization_url: string): AuthFlow

  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. 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.

  Parameters

  • authorization_url: string

  Returns AuthFlow

  A flow reconnected to the original relay channel.

  Throws

  • { 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");
    }
  }
  Copy

resumeDelegatedGrantAuthFlow

• resumeDelegatedGrantAuthFlow(saved_state: string): Promise<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.

  Parameters

  • saved_state: string

  Returns Promise<GrantAuthFlow>

resumeGrantAuthFlow

• resumeGrantAuthFlow(saved_state: string): 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.

  Parameters

  • saved_state: string

  Returns GrantAuthFlow

  A flow reconnected to the original relay channel.

signer

• signer(keypair: Keypair): Signer

  Create a Signer from an existing Keypair.

  Parameters

  • keypair: Keypair

    The user’s keys.

  Returns Signer

  Example

  const signer = pubky.signer(Keypair.random());
  await signer.signup(homeserverPk);
  Copy

startCookieAuthFlow

• startCookieAuthFlow(
      capabilities: Capabilities,
      kind: AuthFlowKind,
      relay?: string | null,
      x_callback?: XCallbackParams | null,
  ): AuthFlow

  Start a pubkyauth flow.

  Provide a capabilities string and (optionally) a relay base URL. The capabilities string is a comma-separated list of entries: "<scope>:<actions>", where:

  • scope starts with / (e.g. /pub/example.com/).
  • actions is any combo of r and/or w (order normalized; wr -> rw). Pass "" for no scopes (read-only public session).

  Security: authorizationUrl contains the client_secret in plaintext. If you need resume after refresh/app switch, save it in sessionStorage (not localStorage), then delete it once approval arrives or is abandoned.

  Parameters

  • capabilities: Capabilities

    Comma-separated caps, e.g. "/pub/app/:rw,/pub/foo/file:r".

  • kind: AuthFlowKind

    The kind of authentication flow to perform. Examples:

    • AuthFlowKind.signin() - Sign in to an existing account.
    • AuthFlowKind.signup(homeserverPublicKey, signupToken) - Sign up for a new account.
  • Optionalrelay: string | null

    Optional HTTP relay base (e.g. "https://…/inbox/").

  • Optionalx_callback: XCallbackParams | null

  Returns AuthFlow

  A running auth flow. Show authorizationUrl as QR/deeplink, then awaitApproval() to obtain a Session.

  Throws

  • { name: "InvalidInput" } for malformed capabilities or bad relay URL
  • { name: "RequestError" } if the flow cannot be started (network/relay)

  Example

  const flow = pubky.startCookieAuthFlow("/pub/my-cool-app/:rw");
  renderQr(flow.authorizationUrl);
  const session = await flow.awaitApproval();
  Copy

startGrantAuthFlow

• startGrantAuthFlow(
      capabilities: Capabilities,
      kind: AuthFlowKind,
      options: GrantAuthFlowOptions,
  ): Promise<GrantAuthFlow>

  Start a grant-backed pubkyauth flow.

  Grant auth uses a user-signed grant JWS plus Proof-of-Possession and returns a self-refreshing session.

  Parameters

  • capabilities: Capabilities

    Comma-separated caps, e.g. "/pub/app/:rw,/pub/foo/file:r".

  • kind: AuthFlowKind

    The kind of authentication flow to perform.

  • options: GrantAuthFlowOptions

    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" },
  );
  Copy

Statictestnet

• testnet(host?: string | null): Pubky

  Create a Pubky facade preconfigured for a local testnet.

  If host is provided, PKARR and HTTP endpoints are derived as http://<host>:ports/.... If omitted, "localhost" is assumed (handy for cargo install pubky-testnet).

  Parameters

  • Optionalhost: string | null

    Optional host (e.g. "localhost", "docker-host", "127.0.0.1").

  Returns Pubky

  Example

  const pubky = Pubky.testnet();              // localhost default
  const pubky = Pubky.testnet("docker-host"); // custom hostname/IP
  Copy

StaticwithClient

• withClient(client: Client): Pubky

  Wrap an existing configured HTTP client into a Pubky facade.

  Parameters

  • client: Client

    A previously constructed client.

  Returns Pubky

  Example

  const client = Client.testnet();
  const pubky = Pubky.withClient(client);
  Copy