@synonymdev/pubky 0.14.0 → 0.15.0

package/README.md

@@ -219,6 +219,18 @@ like a bearer token. Delegated browser grant sessions should use
 > applications should use grant auth plus `browserSessionStore` or
 > `exportLocalSecret()`.
 
+**Multiple browser tabs**
+
+`browserSessionStore.restore(id)` shares one bearer per grant across tabs on the
+same origin, including after reloads. It uses the existing single-session protocol.
+Browser persistence requires IndexedDB and Web Locks in a secure context.
+
+Signout revokes the grant for every tab. Separate applications should obtain
+their own grants: restoring the same exported grant outside browser coordination
+replaces its current bearer.
+See [grant session lifecycle](../../../../docs/grant-session-lifecycle.md)
+for compatibility and expiry behavior.
+
 **Approve a pubkyauth request URL**
 
 ```js
@@ -406,8 +418,23 @@ await s.list("/pub/example.com/", null, false, 100, false);
 
 // Delete
 await s.delete("/pub/example.com/data.json");
+
+// Locked writes (WebDAV LOCK/UNLOCK)
+const lock = await s.lock("/pub/example.com/state.json", 30); // seconds
+lock.path; // -> "/pub/example.com/state.json"
+lock.token; // -> "opaquelocktoken:<uuid>"
+lock.timeoutSeconds; // -> what the homeserver granted (it caps the lifetime)
+await s.putTextLocked(lock, JSON.stringify({ count: 1 })); // only the holder can write; no putJsonLocked
+await s.putBytesLocked(lock, new Uint8Array([1, 2, 3]));
+await s.deleteLocked(lock);
+await s.refreshLock(lock, 30); // restart the lifetime
+await s.unlock(lock);
 ```
 
+While a lock lives, a plain `putJson`/`putText`/`putBytes`/`delete` on that path rejects with `423 Locked`, and so does a second `lock()`. Once the lock is gone, the old value is refused with `412` (write, delete, refresh) and `409` on `unlock()`; take a new lock and read the file again. A homeserver without lock support answers `405`.
+
+`timeoutSeconds` is rounded down to whole seconds, with a minimum of 1. If `lock()` rejects without a status code (a lost connection, say), the homeserver may still have granted the lock; nothing can release it, so the path answers `423` until it times out.
+
 `get()` exposes the underlying `Response`, which is handy for streaming bodies or inspecting headers before consuming content.
 
 Path rules: