@synonymdev/pubky 0.6.0-rc.6 → 0.6.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Pubky client",
-  "version": "0.6.0-rc.6",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,8 +13,8 @@
     "build:test": "tsc --project tsconfig.json && mkdir -p dist && cp index.js dist/index.js",
     "test": "npm run test-nodejs && npm run test-browser",
     "test-nodejs": "npm run build:test && node --require ./node-header.cjs node_modules/tape/bin/tape dist/tests/*.js -cov",
-    "test-browser": "npm run build:test && browserify dist/tests/*.js -p esmify | npx tape-run",
-    "test-browser:ci": "npm run build:test && browserify dist/tests/*.js -p esmify | tape-run --browser electron --electron-arg=--no-sandbox --electron-arg=--disable-gpu",
+    "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",
     "prepublishOnly": "npm run build"
   },

package/pubky.d.ts

@@ -51,47 +51,14 @@ type Level = "error" | "warn" | "info" | "debug" | "trace";
  * *This API requires the following crate features to be activated: `ReadableStreamType`*
  */
 type ReadableStreamType = "bytes";
-/**
- * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
- *
- * @typedef {Object} ResourceStats
- * @property {number=} contentLength  Size in bytes.
- * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
- * @property {number=} lastModifiedMs Unix epoch milliseconds.
- * @property {string=} etag           Opaque server ETag for the current version.
- *
- * @example
- * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
- * if (stats) {
- *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
- * }
- *
- * Notes:
- * - `contentLength` equals `getBytes(...).length`.
- * - `etag` may be absent and is opaque; compare values to detect updates.
- * - `lastModifiedMs` increases when the resource is updated.
- */
-export interface ResourceStats {
-    /**
-     * Size in bytes of the stored object.
-     */
-    contentLength?: number;
-    /**
-     * Media type of the stored object (e.g., `\"application/json\"`).
-     */
-    contentType?: string;
-    /**
-     * Unix epoch **milliseconds** for the last modification time.
-     */
-    lastModifiedMs?: number;
-    /**
-     * Opaque entity tag identifying the current stored version.
-     */
-    etag?: string;
-}
-
 export type Path = `/pub/${string}`;
 
+export type CapabilityAction = "r" | "w" | "rw";
+export type CapabilityScope = `/${string}`;
+export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
+type CapabilitiesTail = `,${CapabilityEntry}${string}`;
+export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
+
 /**
  * A union type of all possible machine-readable codes for the `name` property
  * of a {@link PubkyError}.
@@ -195,11 +162,44 @@ export interface PubkyClientConfig {
     pkarr?: PkarrConfig;
 }
 
-export type CapabilityAction = "r" | "w" | "rw";
-export type CapabilityScope = `/${string}`;
-export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
-type CapabilitiesTail = `,${CapabilityEntry}${string}`;
-export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
+/**
+ * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
+ *
+ * @typedef {Object} ResourceStats
+ * @property {number=} contentLength  Size in bytes.
+ * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
+ * @property {number=} lastModifiedMs Unix epoch milliseconds.
+ * @property {string=} etag           Opaque server ETag for the current version.
+ *
+ * @example
+ * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
+ * if (stats) {
+ *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
+ * }
+ *
+ * Notes:
+ * - `contentLength` equals `getBytes(...).length`.
+ * - `etag` may be absent and is opaque; compare values to detect updates.
+ * - `lastModifiedMs` increases when the resource is updated.
+ */
+export interface ResourceStats {
+    /**
+     * Size in bytes of the stored object.
+     */
+    contentLength?: number;
+    /**
+     * Media type of the stored object (e.g., `\"application/json\"`).
+     */
+    contentType?: string;
+    /**
+     * Unix epoch **milliseconds** for the last modification time.
+     */
+    lastModifiedMs?: number;
+    /**
+     * Opaque entity tag identifying the current stored version.
+     */
+    etag?: string;
+}
 
 /**
  * Start and control a pubkyauth authorization flow.
@@ -212,6 +212,7 @@ export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${Capabilit
 export class AuthFlow {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Start a flow (standalone).
    * Prefer `pubky.startAuthFlow()` to reuse a facade client.
@@ -219,10 +220,17 @@ export class AuthFlow {
    * @param {string} capabilities
    * Comma-separated capabilities, e.g. `"/pub/app/:rw,/priv/foo.txt:r"`.
    * Each entry must be `"<scope>:<actions>"`, where:
-   * - `scope` starts with `/` (e.g. `/pub/example.app/`)
+   * - `scope` starts with `/` (e.g. `/pub/example.com/`)
    * - `actions` is any combo of `r` and/or `w` (order is normalized; `wr` -> `rw`)
    * Empty string is allowed (no scopes).
    *
+   * @param {AuthFlowKind} kind
+   * The kind of authentication flow to perform.
+   * This can either be a sign in or a sign up flow.
+   * Examples:
+   * - `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://demo.httprelay.io/link/"`.
    * Defaults to the default Synonym-hosted relay when omitted.
@@ -234,11 +242,11 @@ export class AuthFlow {
    * - `{ name: "InvalidInput", message: string }` if any capability entry is invalid
    *     or for an invalid relay URL.
    * @example
-   * const flow = AuthFlow.start("/pub/my.app/:rw,/pub/pubky.app/:w");
+   * const flow = AuthFlow.start("/pub/my-cool-app/:rw,/pub/pubky.app/:w");
    * renderQRCode(flow.authorizationUrl());
    * const session = await flow.awaitApproval();
    */
-  static start(capabilities: Capabilities, relay?: string | null): AuthFlow;
+  static start(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
   /**
    * Block until the user approves on their signer device; returns a `Session`.
    *
@@ -276,6 +284,33 @@ export class AuthFlow {
    */
   readonly authorizationUrl: string;
 }
+/**
+ * The kind of authentication flow to perform.
+ * This can either be a sign in or a sign up flow.
+ */
+export class AuthFlowKind {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Create a sign in flow.
+   */
+  static signin(): AuthFlowKind;
+  /**
+   * Create a sign up flow.
+   * # Arguments
+   * * `homeserver_public_key` - The public key of the homeserver to sign up on.
+   * * `signup_token` - The signup token to use for the signup flow. This is optional.
+   */
+  static signup(homeserver_public_key: PublicKey, signup_token?: string | null): AuthFlowKind;
+  /**
+   * Get the intent of the authentication flow.
+   * # Returns
+   * * `"signin"` - If the authentication flow is a sign in flow.
+   * * `"signup"` - If the authentication flow is a sign up flow.
+   */
+  readonly intent: string;
+}
 /**
  * AuthToken: signed, time-bound proof of key ownership.
  *
@@ -292,7 +327,7 @@ export class AuthFlow {
  * const token = await flow.awaitToken();
  *
  * // Identify the user
- * console.log(token.publicKey().z32());
+ * console.log(token.publicKey().toString());
  *
  * // Optionally forward to a server for verification:
  * await fetch("/api/verify", { method: "POST", body: token.toBytes() });
@@ -305,6 +340,7 @@ export class AuthFlow {
 export class AuthToken {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Parse and verify an `AuthToken` from its canonical bytes.
    *
@@ -319,7 +355,7 @@ export class AuthToken {
    * export async function POST(req) {
    *   const bytes = new Uint8Array(await req.arrayBuffer());
    *   const token = AuthToken.verify(bytes); // throws on failure
-   *   return new Response(token.publicKey().z32(), { status: 200 });
+   *   return new Response(token.publicKey().toString(), { status: 200 });
    * }
    * ```
    */
@@ -347,10 +383,11 @@ export class AuthToken {
   /**
    * Returns the **public key** that authenticated with this token.
    *
-   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   * Use `.toString()` on the returned `PublicKey` to get the `pubky<z32>` identifier.
+   * Call `.z32()` when you specifically need the raw z-base32 value (e.g. hostnames).
    *
    * @example
-   * const who = sessionInfo.publicKey.z32();
+   * const who = token.publicKey.toString();
    */
   readonly publicKey: PublicKey;
   /**
@@ -361,7 +398,7 @@ export class AuthToken {
    *
    * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
    *
-   * Example entry: `"/pub/my.app/:rw"`
+   * Example entry: `"/pub/my-cool-app/:rw"`
    */
   readonly capabilities: string[];
 }
@@ -373,6 +410,7 @@ export class AuthToken {
  */
 export class Client {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Perform a raw fetch. Works with `http(s)://` URLs.
    *
@@ -429,6 +467,7 @@ export class Client {
 export class IntoUnderlyingByteSource {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   start(controller: ReadableByteStreamController): void;
   pull(controller: ReadableByteStreamController): Promise<any>;
   cancel(): void;
@@ -438,6 +477,7 @@ export class IntoUnderlyingByteSource {
 export class IntoUnderlyingSink {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   write(chunk: any): Promise<any>;
   close(): Promise<any>;
   abort(reason: any): Promise<any>;
@@ -445,24 +485,26 @@ export class IntoUnderlyingSink {
 export class IntoUnderlyingSource {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   pull(controller: ReadableStreamDefaultController): Promise<any>;
   cancel(): void;
 }
 export class Keypair {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Generate a random [Keypair]
    */
   static random(): Keypair;
   /**
-   * Generate a [Keypair] from a secret key.
+   * Generate a [Keypair] from a 32-byte secret.
    */
-  static fromSecretKey(secret_key: Uint8Array): Keypair;
+  static fromSecret(secret: Uint8Array): Keypair;
   /**
-   * Returns the secret key of this keypair.
+   * Returns the secret of this keypair.
    */
-  secretKey(): Uint8Array;
+  secret(): Uint8Array;
   /**
    * Create a recovery file for this keypair (encrypted with the given passphrase).
    */
@@ -474,10 +516,12 @@ export class Keypair {
   /**
    * Returns the [PublicKey] of this keypair.
    *
-   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   * Use `.toString()` on the returned `PublicKey` to get the string form
+   * or `.z32()` to get the z32 string form without prefix.
+   * Transport/storage (query params, headers, persistence) should use `.z32()`.
    *
    * @example
-   * const who = keypair.publicKey.z32();
+   * const who = keypair.publicKey.toString();
    */
   readonly publicKey: PublicKey;
 }
@@ -486,6 +530,7 @@ export class Keypair {
  */
 export class Pkdns {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Read-only PKDNS actor (no keypair; resolve only).
    */
@@ -531,9 +576,14 @@ export class Pkdns {
  */
 export class Pubky {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * 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.
    *
@@ -573,11 +623,15 @@ export class Pubky {
    * 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.app/`).
+   * - `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).
    *
    * @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.
+   * Examples:
+   * - `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://…/link/"`).
    * @returns {AuthFlow}
    * A running auth flow. Show `authorizationUrl` as QR/deeplink,
@@ -588,11 +642,11 @@ export class Pubky {
    * - `{ name: "RequestError" }` if the flow cannot be started (network/relay)
    *
    * @example
-   * const flow = pubky.startAuthFlow("/pub/my.app/:rw");
+   * const flow = pubky.startAuthFlow("/pub/my-cool-app/:rw");
    * renderQr(flow.authorizationUrl);
    * const session = await flow.awaitApproval();
    */
-  startAuthFlow(capabilities: Capabilities, relay?: string | null): AuthFlow;
+  startAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
   /**
    * Create a `Signer` from an existing `Keypair`.
    *
@@ -610,19 +664,33 @@ export class Pubky {
    * Uses an internal read-only Pkdns actor.
    *
    * @param {PublicKey} user
-   * @returns {Promise<PublicKey|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
    */
   getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
+  /**
+   * Restore a session from a previously exported 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.
+   *
+   * @param {string} exported A string produced by `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")!);
+   */
+  restoreSession(exported: string): Promise<Session>;
   /**
    * Public, unauthenticated storage API.
    *
    * Use for **read-only** public access via addressed paths:
-   * `"<user-z32>/pub/…"`.
+   * `"pubky<user>/pub/…"`.
    *
    * @returns {PublicStorage}
    *
    * @example
-   * const text = await pubky.publicStorage.getText(`${userPk.z32()}/pub/example.com/hello.txt`);
+   * const text = await pubky.publicStorage.getText(`${userPk.toString()}/pub/example.com/hello.txt`);
    */
   readonly publicStorage: PublicStorage;
   /**
@@ -632,13 +700,14 @@ export class Pubky {
    * Use this for low-level `fetch()` calls or testing with raw URLs.
    *
    * @example
-   * const r = await pubky.client.fetch(`pubky://${user}/pub/app/file.txt`, { credentials: "include" });
+   * const r = await pubky.client.fetch(`pubky://${userPk.z32()}/pub/app/file.txt`, { credentials: "include" });
    */
   readonly client: Client;
 }
 export class PublicKey {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Convert the PublicKey to Uint8Array
    */
@@ -647,16 +716,22 @@ export class PublicKey {
    * Returns the z-base32 encoding of this public key
    */
   z32(): string;
+  /**
+   * Returns the identifier form with the `pubky` prefix.
+   * Use for display only; transport/storage should use `.z32()`.
+   */
+  toString(): string;
   /**
    * @throws
    */
   static from(value: string): PublicKey;
 }
 /**
- * Read-only public storage using addressed paths (`"<user-z32>/pub/...")`.
+ * Read-only public storage using addressed paths (`"pubky<user>/pub/..."`).
  */
 export class PublicStorage {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Construct PublicStorage using global client (mainline relays).
    */
@@ -716,6 +791,14 @@ export class PublicStorage {
    */
   stats(address: Address): Promise<ResourceStats | undefined>;
 }
+export class SeedExportDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SeedExportDeepLink;
+  toString(): string;
+  readonly secret: Uint8Array;
+}
 /**
  * An authenticated context “as the user”.
  * - Use `storage` for reads/writes (absolute paths like `/pub/app/file.txt`)
@@ -724,6 +807,7 @@ export class PublicStorage {
 export class Session {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Invalidate the session on the server (clears server cookie).
    * Further calls to storage API will fail.
@@ -731,6 +815,29 @@ export class Session {
    * @returns {Promise<void>}
    */
   signout(): Promise<void>;
+  /**
+   * Export the session metadata so it can be restored after a tab refresh.
+   *
+   * The export string contains **no secrets**; it only serializes the public `SessionInfo`.
+   * Browsers remain responsible for persisting the HTTP-only session cookie.
+   *
+   * @returns {string}
+   * A base64 string to store (e.g. in `localStorage`).
+   */
+  export(): string;
+  /**
+   * Restore a session from an `export()` string.
+   *
+   * The HTTP-only cookie must still be present in the browser; this function does not
+   * read or write any secrets.
+   *
+   * @param {string} exported
+   * A string produced by `session.export()`.
+   * @param {Client=} client
+   * Optional client to reuse transport configuration.
+   * @returns {Promise<Session>}
+   */
+  static restore(exported: string, client?: Client | null): Promise<Session>;
   /**
    * Retrieve immutable info about this session (user & capabilities).
    *
@@ -750,15 +857,17 @@ export class Session {
 export class SessionInfo {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * The user’s public key for this session.
    *
-   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   * Use `.toString()` on the returned `PublicKey` to get the `pubky<z32>` identifier.
+   * Call `.z32()` when you specifically need the raw z-base32 value (e.g. hostnames).
    *
    * @returns {PublicKey}
    *
    * @example
-   * const who = sessionInfo.publicKey.z32();
+   * const who = sessionInfo.publicKey.toString();
    */
   readonly publicKey: PublicKey;
   /**
@@ -774,6 +883,7 @@ export class SessionInfo {
 export class SessionStorage {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * List a directory (absolute session path). Returns `pubky://…` URLs.
    *
@@ -870,6 +980,7 @@ export class SessionStorage {
 export class Signer {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Create a signer from a `Keypair` (prefer `pubky.signer(kp)`).
    *
@@ -929,3 +1040,25 @@ export class Signer {
    */
   readonly pkdns: Pkdns;
 }
+export class SigninDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SigninDeepLink;
+  toString(): string;
+  readonly capabilities: string;
+  readonly baseRelayUrl: string;
+  readonly secret: Uint8Array;
+}
+export class SignupDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SignupDeepLink;
+  toString(): string;
+  readonly capabilities: string;
+  readonly baseRelayUrl: string;
+  readonly secret: Uint8Array;
+  readonly homeserver: PublicKey;
+  readonly signupToken: string | undefined;
+}