@synonymdev/pubky 0.10.0-alpha.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # Pubky
 
-JS/WASM SDK for [Pubky](https://github.com/pubky/pubky-core).
+JS/WASM SDK for [Pubky](https://github.com/pubky/pubky-homeserver).
 
 Works in browsers and Node 20+.
 
@@ -33,18 +33,18 @@ const homeserver = PublicKey.from(
 const signupToken = "<your-invite-code-or-null>";
 await signer.signup(homeserver, signupToken);
 
-// 3a) Signin with the signer directly
-const session = await signer.signin("example.com");
+// 3a) Signin with the signer directly.
+let session = await signer.signin("example.com");
 
-// 3b) Alternatively if you do not have the keypair available, authenticate on a 3rd-party app 
+// 3b) Or, if you do not have the keypair available, authenticate on a 3rd-party app
 // by delegating the authentication to a signer with a QR code.
-const authFlow = pubky.startGrantAuthFlow(
+const authFlow = await pubky.startGrantAuthFlow(
   "/pub/my-cool-app/:rw",
   AuthFlowKind.signin(),
   { clientId: "my-cool-app.example" },
 );
 renderQr(authFlow.authorizationUrl); // Show to user the signin deeplink via a QR code
-const session = await authFlow.awaitApproval();
+session = await authFlow.awaitApproval();
 
 // 4) Write a public JSON file
 const path = "/pub/my-cool-app/hello.json";
@@ -56,7 +56,7 @@ const addr = `${userPk}/pub/my-cool-app/hello.json`;
 const json = await pubky.publicStorage.getJson(addr); // -> { hello: "world" }
 ```
 
-Find here [**ready-to-run examples**](https://github.com/pubky/pubky-core/tree/main/examples).
+Find here [**ready-to-run examples**](https://github.com/pubky/pubky-homeserver/tree/main/examples).
 
 ### Key formats (display vs transport)
 
@@ -93,7 +93,7 @@ const pubkyLocal = Pubky.testnet("localhost");
 const signer = pubky.signer(Keypair.random());
 
 // Grant Pubky Auth flow (with capabilities)
-const authFlow = pubky.startGrantAuthFlow(
+const authFlow = await pubky.startGrantAuthFlow(
   "/pub/my-cool-app/:rw",
   AuthFlowKind.signin(),
   { clientId: "my-cool-app.example" },
@@ -187,16 +187,37 @@ const storage = session.storage; // -> This User's storage API (absolute paths)
 **Persist a grant session**
 
 ```js
-// Save the session secret. Treat this string like a bearer token.
-const secret = await session.exportSecret();
-localStorage.setItem("pubky-session", secret);
+// Persist explicitly when your app wants reload/returning-user restore.
+// In browsers, this uses IndexedDB and supports multiple accounts.
+const stored = await pubky.browserSessionStore.save(session);
 
-// Later, restore by minting a fresh short-lived bearer.
-const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
+const accounts = await pubky.browserSessionStore.list();
+const restored = await pubky.browserSessionStore.restore(stored.id);
 ```
 
+`pubky.startGrantAuthFlow(...)` chooses delegated browser PoP keys
+when the runtime supports them, then falls back to local PoP keys. Delegated
+sessions keep the private PoP key non-extractable in browser storage; local
+sessions store bearer-equivalent secret material in IndexedDB.
+
+```js
+const flow = await pubky.startGrantAuthFlow(
+  "/pub/example.com/:rw",
+  AuthFlowKind.signin(),
+  { clientId: "example.com" },
+);
+const session = await flow.awaitApproval();
+await pubky.browserSessionStore.save(session);
+```
+
+For advanced/manual storage, local grant sessions still expose
+`exportLocalSecret()` and `pubky.restoreSession(secret)`. Treat that string
+like a bearer token. Delegated browser grant sessions should use
+`browserSessionStore` because their PoP keys are non-extractable.
+
 > `session.export()` is still available for legacy cookie sessions, but new
-> applications should use grant auth plus `exportSecret()`.
+> applications should use grant auth plus `browserSessionStore` or
+> `exportLocalSecret()`.
 
 **Approve a pubkyauth request URL**
 
@@ -204,6 +225,16 @@ const restored = await pubky.restoreSession(localStorage.getItem("pubky-session"
 await signer.approveAuthRequest("pubkyauth://signin?caps=...&secret=...&relay=...");
 ```
 
+**Handle a pubkyauth deep link**
+
+General entry point for any supported `pubkyauth://` link. Auth request links
+are approved through their relay (like `approveAuthRequest`), while a
+`direct_signup` link creates the account directly on its target homeserver:
+
+```js
+await signer.handleDeepLink("pubkyauth://direct_signup?hs=...");
+```
+
 ---
 
 ### GrantAuthFlow (pubkyauth)
@@ -221,10 +252,19 @@ const caps = "/pub/my-cool-app/:rw,/pub/another-app/folder/:w";
 const relay = "https://httprelay.pubky.app/inbox/"; // optional (defaults to this)
 
 // Start grant auth polling
-const flow = pubky.startGrantAuthFlow(
+const flow = await pubky.startGrantAuthFlow(
   caps,
   AuthFlowKind.signin(),
-  { clientId: "my-cool-app.example", relay },
+  {
+    clientId: "my-cool-app.example",
+    relay,
+    xCallback: {
+      xSource: "My Cool App",
+      xSuccess: "my-cool-app://auth/success?nonce=unique",
+      xError: "my-cool-app://auth/error?nonce=unique",
+      xCancel: "my-cool-app://auth/cancel?nonce=unique",
+    },
+  },
 );
 
 renderQr(flow.authorizationUrl); // show to user
@@ -233,6 +273,36 @@ renderQr(flow.authorizationUrl); // show to user
 const session = await flow.awaitApproval();
 ```
 
+The same callback object can be passed as the fourth argument to legacy cookie
+auth: `startCookieAuthFlow(caps, kind, relay, xCallback)`. The SDK emits
+`x-source`, `x-success`, `x-error`, and `x-cancel` using the encoding expected
+by Pubky Ring. Parsed deep-link objects expose them through `xCallback`; the
+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:
+
+```js
+const flow = pubky.startGrantAuthFlow(caps, AuthFlowKind.signin(), {
+  clientId: "my-cool-app.example",
+  relay,
+});
+sessionStorage.setItem("pubky-grant-auth", flow.save());
+
+const saved = sessionStorage.getItem("pubky-grant-auth");
+if (saved) {
+  try {
+    const resumed = pubky.resumeGrantAuthFlow(saved);
+    const session = await resumed.awaitApproval();
+  } finally {
+    sessionStorage.removeItem("pubky-grant-auth");
+  }
+}
+```
+
+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.
+
 #### Validate and normalize capabilities
 
 If you accept capability strings from user input (forms, CLI arguments, etc.),
@@ -249,7 +319,7 @@ const rawCaps = formData.get("caps");
 
 try {
   const caps = validateCapabilities(rawCaps ?? "");
-  const flow = pubky.startGrantAuthFlow(caps, AuthFlowKind.signin(), {
+  const flow = await pubky.startGrantAuthFlow(caps, AuthFlowKind.signin(), {
     clientId: "my-cool-app.example",
   });
   renderQr(flow.authorizationUrl);
@@ -264,9 +334,13 @@ try {
 }
 ```
 
-On invalid input, `validateCapabilities` throws a `PubkyError` with
-`{ name: "InvalidInput", message: "Invalid capability entries: …" }`, so you can
-surface precise feedback to the user.
+On invalid input, `validateCapabilities` throws a `PubkyError` identifying the
+first malformed entry and its position. Its `data.invalidEntries` array contains
+that entry so applications can surface precise feedback to the user.
+
+Capability scopes must be canonical absolute paths. Repeated separators and
+`.` or `..` segments are rejected rather than normalized. Percent sequences are
+literal scope characters; URL encoding is handled by the enclosing deep link.
 
 #### Http Relay & reliability
 
@@ -338,11 +412,13 @@ await s.delete("/pub/example.com/data.json");
 
 Path rules:
 
-- Session storage uses **absolute** paths like `"/pub/app/file.txt"`.
+- Session storage uses **absolute** paths under `/pub/` or `/priv/`.
 - Public storage uses **addressed** form `pubky<user>/pub/app/file.txt` (preferred) or `pubky://<user>/...`.
 
 **Convention:** put your app’s public data under a domain-like folder in `/pub`, e.g. `/pub/my-new-app/`.
 
+See [Private Storage](https://github.com/pubky/pubky-homeserver/blob/main/docs/PRIVATE_STORAGE.md) for `/priv/` access and events.
+
 ---
 
 ### PKDNS (Pkarr)
@@ -355,7 +431,8 @@ import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
 const pubky = new Pubky();
 
 // Read-only resolver
-const homeserver = await pubky.getHomeserverOf(PublicKey.from("pubky<z32>")); // string | undefined
+const homeserver = await pubky.getHomeserverOf(PublicKey.from("pubky<z32>")); // PublicKey | undefined
+// Rejects if PKARR resolution fails or the `_pubky` target is malformed.
 
 // With keys (signer-bound)
 const signer = pubky.signer(Keypair.random());