@synonymdev/pubky 0.14.0 → 0.16.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
@@ -281,19 +293,31 @@ legacy `callback` parameter is accepted as an `xSuccess` fallback.
 
 #### Resume an auth flow after page refresh
 
-Grant auth flows are resumable by saving the pending flow state before refresh and restoring it afterwards:
+Save pending grant auth state before a refresh, then restore it afterwards.
+The browser example below uses a delegated signing key stored in IndexedDB.
+It requires a secure context with WebCrypto Ed25519 support and IndexedDB.
+
+For signed approvals, saved flow state includes a temporary HPKE private key
+that decrypts the signer's response. The authorization URL carries the matching
+public key in `epk`; a domain-separated hash of that key identifies the relay
+channel. Keep the saved state confidential and delete it when the flow
+completes or is abandoned.
 
 ```js
-const flow = pubky.startGrantAuthFlow(caps, AuthFlowKind.signin(), {
+import { GrantAuthFlow } from "@synonymdev/pubky";
+
+// Before refreshing:
+const flow = await GrantAuthFlow.startDelegated(caps, AuthFlowKind.signin(), {
   clientId: "my-cool-app.example",
   relay,
 });
-sessionStorage.setItem("pubky-grant-auth", flow.save());
+sessionStorage.setItem("pubky-grant-auth", flow.saveDelegated());
 
+// After reloading:
 const saved = sessionStorage.getItem("pubky-grant-auth");
 if (saved) {
   try {
-    const resumed = pubky.resumeGrantAuthFlow(saved);
+    const resumed = await pubky.resumeDelegatedGrantAuthFlow(saved);
     const session = await resumed.awaitApproval();
   } finally {
     sessionStorage.removeItem("pubky-grant-auth");
@@ -301,7 +325,96 @@ if (saved) {
 }
 ```
 
-Legacy cookie auth flows can be resumed with `pubky.resumeCookieAuthFlow(authorizationUrl)`. Store pending auth state in `sessionStorage`, not `localStorage`, and delete it once the flow completes or is abandoned.
+For local signing keys, use `GrantAuthFlow.start()`, `flow.saveLocal()`, and
+`pubky.resumeGrantAuthFlow(saved)`.
+
+Legacy cookie auth flows can be resumed with
+`pubky.resumeCookieAuthFlow(authorizationUrl)`. Store pending auth state in
+`sessionStorage`, not `localStorage`, and delete it once the flow completes or
+is abandoned.
+
+#### Request encryption keys
+
+Apps can also ask the signer for encryption keys scoped to storage paths. Set
+`approvalFormat: "signedApprovalV1"` and add the `e` action to each scope that
+needs keys. Storage actions `r` and `w` don't deliver keys.
+
+Keys stay usable after the grant expires or is revoked, and older homeservers
+reject grants containing `e`. Read the
+[scoped encryption keys guide](../../../../docs/scoped-encryption-keys.md)
+before you use them.
+
+```js
+const flow = await pubky.startGrantAuthFlow("/pub/chat/:rwe", AuthFlowKind.signin(), {
+  clientId: "chat.example",
+  approvalFormat: "signedApprovalV1",
+});
+renderQr(flow.authorizationUrl);
+const session = await flow.awaitApproval();
+
+const keys = session.grant.encryptionKeys; // undefined for bare grants
+let key;
+try {
+  // The signer may narrow scopes or decline `e`.
+  if (!keys.scopes.includes("/pub/chat/")) {
+    throw new Error("The signer didn't approve chat keys.");
+  }
+  key = await keys.deriveCryptoKeyForPath("/pub/chat/message");
+} finally {
+  keys.free(); // The CryptoKey stays usable.
+}
+
+const iv = crypto.getRandomValues(new Uint8Array(12)); // Fresh IV every time.
+const ciphertext = await crypto.subtle.encrypt(
+  { name: "AES-GCM", iv }, key, new TextEncoder().encode("Hello"),
+);
+```
+
+`EncryptionKeys` has these members:
+
+| API | Returns |
+| --- | --- |
+| `keys.scopes` | Approved scope paths as `string[]` |
+| `keys.deriveForPath(path)` | Raw key bytes as `Uint8Array`. Clear them after use. |
+| `await keys.deriveCryptoKeyForPath(path)` | Non-extractable AES-GCM-256 `CryptoKey`. Requires WebCrypto in a secure context. |
+
+Both derivation methods take a canonical file path and reject directories and
+paths outside the approved scopes. Each read of `session.grant.encryptionKeys`
+returns a separate copy; call `free()` when you're done with it. Signed
+approvals without `e` scopes return an object with empty scopes.
+
+`exportLocalSecret()` and `browserSessionStore.save()` keep the keys. The
+browser store saves them as plaintext in IndexedDB, readable by any script on
+the same origin. You can recover keys offline, even after the grant expires or
+is revoked. Recovery creates no session:
+
+```js
+import { EncryptionKeys } from "@synonymdev/pubky";
+
+const recovered = EncryptionKeys.fromLocalSecret(savedToken);
+if (recovered) {
+  try {
+    if (recovered.publicKey !== expectedUser.z32() ||
+        recovered.grantId !== expectedGrantId) {
+      throw new Error("This backup belongs to a different account or grant");
+    }
+    const key = await recovered.keys.deriveCryptoKeyForPath("/pub/chat/message");
+    // Use key with WebCrypto for locally saved ciphertext.
+  } finally {
+    recovered.keys.free();
+  }
+}
+```
+
+`fromLocalSecret()` returns `{ publicKey, grantId, keys }`, or `undefined` for
+bare-grant tokens. `publicKey` is the authenticated account's z-base-32 key.
+Compare it with the account you expect; also check `grantId` when restoring a
+specific grant. Callers that previously received keys directly must now read
+`recovered.keys` after checking the identity.
+
+For a browser record, use
+`await pubky.browserSessionStore.restoreEncryptionKeys(storedId)`. It checks
+the account and grant against the record ID and returns the keys directly.
 
 #### Validate and normalize capabilities
 
@@ -406,8 +519,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:
@@ -445,6 +573,15 @@ await signer.pkdns.publishHomeserverForce(/* optional override homeserver*/);
 await signer.pkdns.getHomeserver();
 ```
 
+### Custom proofs
+
+Use `session.grant.createCustomPop(data)` to sign JSON and return both the proof
+and its root-signed grant. Use `verifyCustomGrantPop(credentials)` to verify the bundle
+offline.
+
+See [Sign and verify custom data](https://github.com/pubky/pubky-homeserver/blob/main/docs/CUSTOM_POP.md) for Rust and
+JavaScript examples and the verification contract.
+
 ## Logging
 
 The SDK ships with a WASM logger that bridges Rust `log` output into the browser or Node console. Call `setLogLevel` **once at application start**, before constructing `Pubky` or other SDK actors, to choose how verbose the logs should be.