@synonymdev/pubky 0.13.0 → 0.15.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Decentralized identity, auth flows, and user-owned storage",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,7 +17,8 @@
     "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",
     "docs": "typedoc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test-browser:tabs": "npm run build:test && browserify dist/tests/browser/session-tabs.js -p esmify -o dist/session-tabs.bundle.js && electron scripts/session-tabs.cjs"
   },
   "files": [
     "index.cjs",
@@ -40,6 +41,7 @@
     "@types/tape": "^5.6.4",
     "browser-resolve": "^2.0.0",
     "browserify": "^17.0.1",
+    "electron": "41.0.2",
     "esmify": "^2.1.1",
     "tape": "^5.8.1",
     "tape-run": "^11.0.0",

package/pubky.d.ts

@@ -74,8 +74,8 @@ export interface PkarrConfig {
      */
     relays?: string[];
     /**
-     * The timeout for DHT requests in milliseconds.
-     * Default is 2000ms.
+     * The timeout for relay HTTP requests in milliseconds.
+     * Default is 5000ms.
      */
     requestTimeout?: number;
 }
@@ -459,7 +459,7 @@ export class BrowserSessionStore {
      * 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.
+     * grants. Browser-managed handles stop working when their saved record is removed.
      */
     clearAll(): Promise<void>;
     /**
@@ -470,7 +470,7 @@ export class BrowserSessionStore {
      */
     clear(): Promise<void>;
     /**
-     * Whether IndexedDB is available for durable session persistence.
+     * Whether IndexedDB and Web Locks are available.
      */
     isAvailable(): Promise<boolean>;
     /**
@@ -483,6 +483,9 @@ export class BrowserSessionStore {
     remove(id: string): Promise<void>;
     /**
      * Restore a specific stored session by id.
+     *
+     * Shares one bearer with other tabs on this origin. Requires IndexedDB and
+     * Web Locks in a secure browser context.
      */
     restore(id: string): Promise<Session>;
     /**
@@ -1778,12 +1781,23 @@ export class SessionInfo {
  * Only {@link SessionStorage.exists} and {@link SessionStorage.stats} treat
  * HTTP 404/410 as missing. Other HTTP failures, including 401/403 and 5xx, reject.
  * Writes require write permission and can fail on directory targets (400),
- * file/directory path conflicts (409), or exceeded quotas (507).
+ * file/directory path conflicts (409), a path someone holds a
+ * {@link StorageLock} on (423), or exceeded quotas (507).
  */
 export class SessionStorage {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * `DELETE` the path of a lock this client holds. The lock stays in place.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one.
+     * Otherwise as {@link SessionStorage.delete}.
+     */
+    deleteLocked(lock: StorageLock): Promise<void>;
     /**
      * Delete a file. Directory targets are unsupported.
      *
@@ -1850,6 +1864,35 @@ export class SessionStorage {
      * entries, or shared errors (see {@link SessionStorage}).
      */
     list(path: Path, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+    /**
+     * Take an exclusive write lock on a file at an **absolute session path**.
+     *
+     * The file need not exist; locking a free path reserves it. `timeoutSeconds` is
+     * the lifetime asked for; the homeserver caps it, and
+     * {@link StorageLock.timeoutSeconds} tells what was granted. A write made under
+     * the lock keeps it alive until the write ends, so it need not cover the upload itself.
+     *
+     * @param {Path} path File path; must not end with `/`.
+     * @param {number} timeoutSeconds Lifetime to ask for, in seconds; rounded down to
+     * whole seconds, and at least 1.
+     * @returns {Promise<StorageLock>} The granted lock.
+     * @throws {PubkyError} `InvalidInput` for a negative, NaN or out-of-range timeout;
+     * a path that is already locked rejects with `RequestError` and status `423`;
+     * directory targets with `400`; a homeserver without lock support with `405`.
+     * See {@link SessionStorage} for shared errors.
+     */
+    lock(path: Path, timeout_seconds: number): Promise<StorageLock>;
+    /**
+     * `PUT` binary data to the path of a lock this client holds.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @param {Uint8Array} body
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one and read the file again.
+     * Otherwise as {@link SessionStorage.putBytes}.
+     */
+    putBytesLocked(lock: StorageLock, body: Uint8Array): Promise<void>;
     /**
      * Create or replace a file with binary data at an absolute session path.
      *
@@ -1869,6 +1912,17 @@ export class SessionStorage {
      * otherwise serialization, upload, or shared write/request errors (see {@link SessionStorage}).
      */
     putJson(path: Path, body: any): Promise<void>;
+    /**
+     * `PUT` text to the path of a lock this client holds.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @param {string} body
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one and read the file again.
+     * Otherwise as {@link SessionStorage.putText}.
+     */
+    putTextLocked(lock: StorageLock, body: string): Promise<void>;
     /**
      * Create or replace a file with text at an absolute session path.
      *
@@ -1878,6 +1932,22 @@ export class SessionStorage {
      * @throws {PubkyError} Upload or shared write/request errors (see {@link SessionStorage}).
      */
     putText(path: Path, body: string): Promise<void>;
+    /**
+     * Restart the lifetime of a lock this client holds.
+     *
+     * On success the lock carries the newly granted
+     * {@link StorageLock.timeoutSeconds}.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @param {number} timeoutSeconds Lifetime to ask for, in seconds; rounded down to
+     * whole seconds, and at least 1.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one and read the file again.
+     * `InvalidInput` for a negative, NaN or out-of-range timeout.
+     * See {@link SessionStorage} for shared errors.
+     */
+    refreshLock(lock: StorageLock, timeout_seconds: number): Promise<void>;
     /**
      * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
      *
@@ -1888,6 +1958,15 @@ export class SessionStorage {
      * @throws {PubkyError} All other failures (see {@link SessionStorage}).
      */
     stats(path: Path): Promise<ResourceStats | undefined>;
+    /**
+     * Release a lock this client holds.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that no longer exists rejects with `RequestError`
+     * and status `409`. See {@link SessionStorage} for shared errors.
+     */
+    unlock(lock: StorageLock): Promise<void>;
 }
 
 /**
@@ -2158,6 +2237,52 @@ export class SignupGrantDeepLink {
     readonly xCallback: XCallbackParams;
 }
 
+/**
+ * An exclusive write lock on one file path, granted by the homeserver.
+ *
+ * While the lock lives, only writes that present it are accepted on the path;
+ * every other write, and every other {@link SessionStorage.lock}, rejects with
+ * `423 Locked`. The lock ends when it is {@link SessionStorage.unlock | unlocked}
+ * or when its {@link StorageLock.timeoutSeconds} runs out without a
+ * {@link SessionStorage.refreshLock | refresh}, so a client that disappears never
+ * blocks a path for long.
+ *
+ * The lock is a bearer token: whoever holds this value, and may write the path,
+ * can use and release the lock.
+ *
+ * Calls that take the lock may overlap: a {@link SessionStorage.refreshLock | refresh}
+ * can run while a locked write is in flight.
+ *
+ * @example
+ * const lock = await session.storage.lock("/pub/my.app/state.json", 30);
+ * const state = await session.storage.getText(lock.path);
+ * await session.storage.putTextLocked(lock, state);
+ * await session.storage.unlock(lock);
+ */
+export class StorageLock {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Value of the `If` header that presents this lock on a write.
+     */
+    ifHeader(): string;
+    /**
+     * The locked path.
+     */
+    readonly path: Path;
+    /**
+     * Lifetime the homeserver granted at the last `lock` or `refreshLock`, in seconds,
+     * counted from when that call resolved. It may be shorter than what was asked for.
+     * It is not the time remaining: note when the call resolved to know when to refresh.
+     */
+    readonly timeoutSeconds: number;
+    /**
+     * The lock token URL, `opaquelocktoken:<uuid>`.
+     */
+    readonly token: string;
+}
+
 /**
  * Metadata for a session saved in the browser session store.
  */