@synonymdev/pubky 0.16.2 → 0.18.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Decentralized identity, auth flows, and user-owned storage",
-  "version": "0.16.2",
+  "version": "0.18.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
     "@types/tape": "^5.6.4",
     "browser-resolve": "^2.0.0",
     "browserify": "^17.0.1",
-    "electron": "41.0.2",
+    "electron": "45.1.0",
     "esmify": "^2.1.1",
     "tape": "^5.8.1",
     "tape-run": "^11.0.0",
@@ -52,6 +52,7 @@
     "fetch-cookie": "^3.0.1"
   },
   "overrides": {
-    "electron": "41.0.2"
+    "electron": "45.1.0",
+    "minimist": "^1.2.8"
   }
 }

package/pubky.d.ts

@@ -25,6 +25,33 @@ export interface RecoveredEncryptionKeys {
 
 
 
+/** The individual limits of a quota. A limit is a number, a rate string such as
+ * `"100mb/m"`, or `"unlimited"`. Absent in `overrides` means the system default. */
+export interface AccountQuotaLimits {
+    /** Storage quota in megabytes, or "unlimited". */
+    storageQuotaMb?: number | "unlimited";
+    /** Read bandwidth limit, e.g. "100mb/m", or "unlimited". */
+    rateRead?: string;
+    /** Write bandwidth limit, e.g. "50mb/s", or "unlimited". */
+    rateWrite?: string;
+    /** Burst allowance for reads, in the rate's unit. Absent means burst equals rate. */
+    rateReadBurst?: number;
+    /** Burst allowance for writes, in the rate's unit. Absent means burst equals rate. */
+    rateWriteBurst?: number;
+    /** Path prefixes the user may write to. Absent means unrestricted; empty means read-only. */
+    allowedWritePaths?: string[];
+}
+
+/** A user's quota, both as it applies and as it was customised. */
+export interface AccountQuota {
+    /** Overrides merged with the homeserver's defaults. */
+    effective: AccountQuotaLimits;
+    /** Only the per-user overrides. */
+    overrides: AccountQuotaLimits;
+}
+
+
+
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 /** Root-signed grant claims. Public keys are z-base-32; times are Unix seconds. */
 export interface VerifiedGrantClaims {
@@ -45,7 +72,7 @@ export interface VerifiedGrantClaims {
  * Provides a simplified, actionable set of error categories for developers
  * to handle in their code.
  */
-export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
+export type PubkyErrorName = "RequestError" | "CredentialRefreshError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
 
 /**
  * Optional x-callback-url metadata carried by a Pubky deep link.
@@ -96,6 +123,15 @@ export interface GrantAuthFlowOptions {
      * `signedApprovalV1` sets `af=v1` in the authorization link.
      */
     approvalFormat?: GrantApprovalFormat;
+    /**
+     * Optional expected identity: public key of the signed-in user that must
+     * approve, as raw z32 or `pubky<z32>`. Set it only when the app already
+     * knows the user, e.g. to re-authorize or request more capabilities. It
+     * adds `spk` to the link; signers approve with that key or refuse, and the
+     * flow rejects approvals from any other key. Switching accounts takes a
+     * flow without it. Sign-up flows reject it.
+     */
+    expectedSigner?: string | null;
 }
 
 /**
@@ -152,7 +188,7 @@ export type GrantApprovalFormat = "bareGrant" | "signedApprovalV1";
  *
  * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
  * @property message - A human-readable, descriptive error message suitable for logging.
- * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ * @property data - Optional structured context. For a `RequestError` it is a {@link RequestErrorData}, e.g. `{ reason: "Http", statusCode: 404 }`.
  *
  * @example
  * ```typescript
@@ -160,14 +196,11 @@ export type GrantApprovalFormat = "bareGrant" | "signedApprovalV1";
  *   await client.signup(...);
  * } catch (e) {
  *   const error = e as PubkyError;
- *   if (
- *     error.name === "RequestError" &&
- *     typeof error.data === "object" &&
- *     error.data !== null &&
- *     "statusCode" in error.data &&
- *     (error.data as { statusCode?: number }).statusCode === 404
- *   ) {
- *     // Handle not found...
+ *   if (error.name === "RequestError") {
+ *     const data = error.data as RequestErrorData;
+ *     if (data.statusCode === 404) {
+ *       // Handle not found...
+ *     }
  *   }
  * }
  * ```
@@ -178,13 +211,35 @@ export interface PubkyError extends Error {
     data?: unknown;
 }
 
+/** The classified cause of a `RequestError`, carried in `PubkyError.data.reason`. */
+export type RequestErrorReason =
+| "Http"
+| "Timeout"
+| "Connection"
+| "TlsVerification"
+| "Body"
+| "Decode"
+| "InvalidRequest"
+| "Other";
+
+/**
+ * `PubkyError.data` for a `RequestError`.
+ *
+ * `statusCode` is present when `reason` is `"Http"`. A reason describes the
+ * failure, not whether retrying is safe.
+ */
+export interface RequestErrorData {
+    reason: RequestErrorReason;
+    statusCode?: number;
+}
+
 /**
  * Represents the standard error structure for all exceptions thrown by the Pubky
  * WASM client.
  *
  * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
  * @property message - A human-readable, descriptive error message suitable for logging.
- * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ * @property data - Optional structured context. For a `RequestError` it is a {@link RequestErrorData}, e.g. `{ reason: "Http", statusCode: 404 }`.
  *
  * @example
  * ```typescript
@@ -192,14 +247,11 @@ export interface PubkyError extends Error {
  *   await client.signup(...);
  * } catch (e) {
  *   const error = e as PubkyError;
- *   if (
- *     error.name === 'RequestError' &&
- *     typeof error.data === 'object' &&
- *     error.data !== null &&
- *     'statusCode' in error.data &&
- *     (error.data as { statusCode?: number }).statusCode === 404
- *   ) {
- *     // Handle not found...
+ *   if (error.name === 'RequestError') {
+ *     const data = error.data as RequestErrorData;
+ *     if (data.statusCode === 404) {
+ *       // Handle not found...
+ *     }
  *   }
  * }
  * ```
@@ -304,6 +356,39 @@ export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${Capabilit
 export type Path = `/pub/${string}` | `/priv/${string}`;
 
 
+/**
+ * A user's account as returned by `session.grant.account()`.
+ */
+export class AccountInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * When the user signed up, as an ISO 8601 date and time without a UTC
+     * offset (e.g. `2026-10-22T10:11:12.123456`).
+     */
+    readonly createdAt: string;
+    /**
+     * Whether the account is disabled. Disabled accounts can read and delete
+     * but not write.
+     */
+    readonly disabled: boolean;
+    /**
+     * The user this account belongs to.
+     */
+    readonly pubky: PublicKey;
+    /**
+     * The quota that applies and the per-user overrides behind it.
+     *
+     * @returns {AccountQuota}
+     */
+    readonly quota: AccountQuota;
+    /**
+     * Bytes of storage currently used.
+     */
+    readonly usedBytes: number;
+}
+
 /**
  * Start and control a pubkyauth authorization flow.
  *
@@ -1054,7 +1139,7 @@ export class GrantAuthFlow {
      * The kind of authentication flow to perform.
      *
      * @param {GrantAuthFlowOptions} options
-     * Options for the grant flow: `{ clientId, relay?, xCallback? }`.
+     * Options for the grant flow: `{ clientId, relay?, xCallback?, approvalFormat?, expectedSigner? }`.
      *
      * @returns {GrantAuthFlow}
      * A running grant auth flow. Call `authorizationUrl()` to show the deep link,
@@ -1154,6 +1239,17 @@ export class GrantSession {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Fetch this user's account: storage used, whether it is disabled, and
+     * the quota that applies.
+     *
+     * Requires read permission on the root scope (`/:r`, `/:rw`, ...).
+     * Path-scoped sessions surface the homeserver `403` as the standard
+     * request error.
+     *
+     * @returns {Promise<AccountInfo>}
+     */
+    account(): Promise<AccountInfo>;
     /**
      * Sign JSON data and return both the custom proof and its root-signed grant.
      * Data follows `JSON.stringify` semantics, e.g. `undefined` properties are omitted.
@@ -1596,7 +1692,7 @@ export class Pubky {
      * @param {string} capabilities Comma-separated caps, e.g. `"/pub/app/:rw,/pub/foo/file:r"`.
      * @param {AuthFlowKind} kind The kind of authentication flow to perform.
      * @param {GrantAuthFlowOptions} options Options for the grant flow:
-     * `{ clientId, relay?, xCallback?, approvalFormat? }`.
+     * `{ clientId, relay?, xCallback?, approvalFormat?, expectedSigner? }`.
      * @returns {Promise<GrantAuthFlow>}
      * A running grant auth flow. Show `authorizationUrl` as QR/deeplink,
      * then `awaitApproval()` to obtain a grant-backed `Session`.
@@ -1697,7 +1793,8 @@ export class PubkyResource {
      */
     static parse(value: string): PubkyResource;
     /**
-     * Render as `pubky://<owner>/<path>` (deep-link/URL form).
+     * Render as `pubky://<owner><path>` (deep-link form), the form listings
+     * and events use.
      */
     toPubkyUrl(): string;
     /**
@@ -1709,7 +1806,7 @@ export class PubkyResource {
      */
     readonly owner: PublicKey;
     /**
-     * Get the absolute path (e.g., "/pub/example.txt").
+     * Get the absolute path (e.g., "/pub/My File.txt").
      */
     readonly path: string;
 }
@@ -1779,10 +1876,10 @@ export class PublicStorage {
      */
     get(address: Address): Promise<Response>;
     /**
-     * List a directory. Results are `pubky://…` identifier URLs.
+     * List a directory. Results are `pubky://<pk><path>` entries.
      *
      * @param {Address} address Addressed directory (must end with `/`).
-     * @param {string|null=} cursor Optional suffix or full URL to start **after**.
+     * @param {string|null=} cursor Optional suffix or entry (as returned) to start **after**.
      * @param {boolean=} reverse Default `false`. When `true`, newest/lexicographically-last first.
      * @param {number=} limit Optional result limit.
      * @param {boolean=} shallow Default `false`. When `true`, lists only first-level entries.
@@ -1937,8 +2034,10 @@ export class SessionInfo {
  *
  * Failures reject with a {@link PubkyError}. Path validation, transport, and HTTP
  * failures use `RequestError`; only HTTP errors include `data.statusCode`.
- * URL parsing failures use `InvalidInput`. Credential preparation, refresh,
- * and reading response bodies can also fail.
+ * Automatic grant refresh failures use `CredentialRefreshError`, with the
+ * refresh HTTP status in `data.statusCode` when available. URL parsing failures
+ * use `InvalidInput`. Other credential preparation and reading response bodies
+ * can also fail.
  *
  * Only {@link SessionStorage.exists} and {@link SessionStorage.stats} treat
  * HTTP 404/410 as missing. Other HTTP failures, including 401/403 and 5xx, reject.
@@ -2017,11 +2116,11 @@ export class SessionStorage {
      * List a directory (absolute session path).
      *
      * @param {Path} path Must end with `/`.
-     * @param {string|null=} cursor Optional last entry URL to start **after**.
+     * @param {string|null=} cursor Optional last entry (as returned) to start **after**.
      * @param {boolean=} reverse Default `false`.
      * @param {number=} limit Optional result limit.
      * @param {boolean=} shallow Default `false`.
-     * @returns {Promise<string[]>} `pubky://…` entry URLs, or an empty array for an empty page.
+     * @returns {Promise<string[]>} `pubky://<pk><path>` entries, or an empty array for an empty page.
      * @throws {PubkyError} Missing directory (404), invalid cursor (400), invalid response
      * entries, or shared errors (see {@link SessionStorage}).
      */
@@ -2044,6 +2143,38 @@ export class SessionStorage {
      * See {@link SessionStorage} for shared errors.
      */
     lock(path: Path, timeout_seconds: number): Promise<StorageLock>;
+    /**
+     * Upload a Blob or File to a locked path without copying its contents into
+     * WASM memory.
+     *
+     * @param {StorageLock} lock A lock you hold. The upload uses the lock's path.
+     * @param {Blob} body A Blob or File to upload.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} An expired or released lock rejects with status `412`.
+     * A file that changed since the write was prepared rejects with status `409`.
+     * See {@link SessionStorage.putBytesLocked} for recovery and
+     * {@link SessionStorage.putBlob} for input validation and shared errors.
+     * @example
+     * const lock = await session.storage.lock("/pub/example.com/file.bin", 30);
+     * try {
+     *   await session.storage.putBlobLocked(lock, file);
+     * } finally {
+     *   await session.storage.unlock(lock);
+     * }
+     */
+    putBlobLocked(lock: StorageLock, body: Blob): Promise<void>;
+    /**
+     * Upload a Blob or File without copying its contents into WASM memory.
+     *
+     * @param {Path} path File path; must not end with `/`.
+     * @param {Blob} body A Blob or File to upload.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} `InvalidInput` if body is not a Blob or File;
+     * otherwise upload or shared write/request errors (see {@link SessionStorage}).
+     * @example
+     * await session.storage.putBlob("/pub/example.com/file.bin", file);
+     */
+    putBlob(path: Path, body: Blob): Promise<void>;
     /**
      * `PUT` binary data to the path of a lock this client holds.
      *
@@ -2325,6 +2456,13 @@ export class SigninGrantDeepLink {
      * @returns {Uint8Array|undefined}
      */
     readonly ephemeralPublicKey: Uint8Array | undefined;
+    /**
+     * Expected identity (`spk`): the public key that must approve this
+     * request, or `undefined`. Signers approve with this key or refuse.
+     *
+     * @returns {PublicKey|undefined}
+     */
+    readonly expectedSigner: PublicKey | undefined;
     /**
      * Shared relay secret, or `undefined` for an HPKE link.
      * Keep this secret confidential until the flow completes or is abandoned.