@synonymdev/pubky 0.9.3 → 0.10.0

package/README.md

@@ -31,21 +31,29 @@ const homeserver = PublicKey.from(
   "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo"
 );
 const signupToken = "<your-invite-code-or-null>";
-const session = await signer.signup(homeserver, signupToken);
+await signer.signup(homeserver, signupToken);
 
-// 3) Write a public JSON file (session-scoped storage uses cookies automatically)
-const path = "/pub/example.com/hello.json";
+// 3a) Signin with the signer directly.
+let session = await signer.signin("example.com");
+
+// 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 = 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
+session = await authFlow.awaitApproval();
+
+// 4) Write a public JSON file
+const path = "/pub/my-cool-app/hello.json";
 await session.storage.putJson(path, { hello: "world" });
 
-// 4) Read it publicly (no auth needed)
+// 5) Read it publicly (no auth needed)
 const userPk = session.info.publicKey.toString();
-const addr = `${userPk}/pub/example.com/hello.json`;
+const addr = `${userPk}/pub/my-cool-app/hello.json`;
 const json = await pubky.publicStorage.getJson(addr); // -> { hello: "world" }
-
-// 5) Authenticate on a 3rd-party app
-const authFlow = pubky.startAuthFlow("/pub/my-cool-app/:rw", AuthFlowKind::signin()); // require permissions to read and write into `my.app`
-renderQr(authFlow.authorizationUrl); // show to user
-const session = await authFlow.awaitApproval();
 ```
 
 Find here [**ready-to-run examples**](https://github.com/pubky/pubky-core/tree/main/examples).
@@ -84,8 +92,12 @@ const pubkyLocal = Pubky.testnet("localhost");
 // Signer (bind your keypair to a new Signer actor)
 const signer = pubky.signer(Keypair.random());
 
-// Pubky Auth flow (with capabilities)
-const authFlow = pubky.startAuthFlow("/pub/my-cool-app/:rw", AuthFlowKind::signin());
+// Grant Pubky Auth flow (with capabilities)
+const authFlow = await pubky.startGrantAuthFlow(
+  "/pub/my-cool-app/:rw",
+  AuthFlowKind.signin(),
+  { clientId: "my-cool-app.example" },
+);
 
 // Public storage (read-only)
 const publicStorage = pubky.publicStorage;
@@ -106,7 +118,7 @@ const client = new Client(); // or: pubky.client.fetch(); instead of constructin
 
 // Convert the identifier into a transport URL before fetching.
 const userId = PublicKey.from("pubky<z32>").toString();
-const url = resolvePubky(`${userId}/pub/example.com/file.txt`);
+const url = resolvePubky(`${userId}/pub/my-cool-app/file.txt`);
 const res = await client.fetch(url);
 ```
 
@@ -155,12 +167,12 @@ const keypair = Keypair.random();
 const signer = pubky.signer(keypair);
 
 const homeserver = PublicKey.from("8pinxxgq…");
-const session = await signer.signup(homeserver, /* invite */ null);
+await signer.signup(homeserver); // Add optional signup code here if required
 
-const session2 = await signer.signin(); // fast, prefer this; publishes PKDNS in background
-const session3 = await signer.signinBlocking(); // slower but safer; waits for PKDNS publish
+const session1 = await signer.signin("example.com"); // fast, prefer this; publishes PKDNS in background
+const session2 = await signer.signinBlocking("example.com"); // slower but safer; waits for PKDNS publish
 
-await session.signout(); // invalidates server session
+await session1.signout(); // invalidates server session
 ```
 
 **Session details**
@@ -172,29 +184,60 @@ const caps = session.info.capabilities; // -> string[] permissions and paths
 const storage = session.storage; // -> This User's storage API (absolute paths)
 ```
 
-**Persist a session across tab refreshes (browser)**
+**Persist a grant session**
 
 ```js
-// Save the session snapshot (no secrets inside; relies on the HTTP-only cookie).
-const snapshot = session.export();
-localStorage.setItem("pubky-session", snapshot);
+// 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);
+
+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.
 
-// Later (after a reload), rehydrate using the browser's stored cookie.
-const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
+```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);
 ```
 
-> The exported string contains only public session metadata. The browser must keep the
-> HTTP-only cookie alive for the restored session to remain authenticated.
+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 `browserSessionStore` or
+> `exportLocalSecret()`.
 
 **Approve a pubkyauth request URL**
 
 ```js
-await signer.approveAuthRequest("pubkyauth:///?caps=...&secret=...&relay=...");
+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=...");
 ```
 
 ---
 
-### AuthFlow (pubkyauth)
+### GrantAuthFlow (pubkyauth)
 
 End-to-end auth (3rd-party app asks a user to approve via QR/deeplink, E.g. Pubky Ring).
 
@@ -208,8 +251,21 @@ const caps = "/pub/my-cool-app/:rw,/pub/another-app/folder/:w";
 // Optional relay; defaults to Synonym-hosted relay if omitted
 const relay = "https://httprelay.pubky.app/inbox/"; // optional (defaults to this)
 
-// Start the auth polling
-const flow = pubky.startAuthFlow(caps, AuthFlowKind::signin(), relay);
+// Start grant auth polling
+const flow = await pubky.startGrantAuthFlow(
+  caps,
+  AuthFlowKind.signin(),
+  {
+    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
 
@@ -217,10 +273,40 @@ 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.),
-use `validateCapabilities` before calling `startAuthFlow`. The helper returns a
+use `validateCapabilities` before calling `startGrantAuthFlow`. The helper returns a
 normalized string (ordering actions like `:rw`) and throws a structured error
 when the input is malformed.
 
@@ -233,7 +319,9 @@ const rawCaps = formData.get("caps");
 
 try {
   const caps = validateCapabilities(rawCaps ?? "");
-  const flow = pubky.startAuthFlow(caps, AuthFlowKind::signin());
+  const flow = await pubky.startGrantAuthFlow(caps, AuthFlowKind.signin(), {
+    clientId: "my-cool-app.example",
+  });
   renderQr(flow.authorizationUrl);
   const session = await flow.awaitApproval();
   // ...
@@ -246,15 +334,18 @@ 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
 
-- If you don’t specify a relay, `PubkyAuthFlow` defaults to a Synonym-hosted relay. If that relay is down, logins won’t complete.
-- For production and larger apps, run **your own http relay** (MIT, Docker): [https://httprelay.io](https://httprelay.io).
-  The channel is derived as `base64url(hash(secret))`; the token is end-to-end encrypted with the `secret` and cannot be decrypted by the relay.
+- If you don’t specify a relay, the auth flow defaults to a Synonym-hosted relay. If that relay is down, logins won’t complete.
+- For production and larger apps, run **your own http relay** (MIT, Docker): [https://github.com/pubky/http-relay](https://github.com/pubky/http-relay).
 
 ---
 
@@ -290,7 +381,7 @@ await pub.list(
 
 Use `get()` when you need the raw `Response` for streaming or custom parsing.
 
-#### SessionStorage (read/write; uses cookies)
+#### SessionStorage (read/write)
 
 ```js
 const s = session.storage;
@@ -321,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-core/blob/main/docs/PRIVATE_STORAGE.md) for `/priv/` access and events.
+
 ---
 
 ### PKDNS (Pkarr)
@@ -338,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());
@@ -423,12 +517,6 @@ try {
 }
 ```
 
-## Browser environment notes
-
-- Keep the Pubky client UI and the homeserver on the **same origin family** (both local or both remote). Browsers partition cookies by scheme/host, and cross-site requests (e.g., http://localhost calling https://staging…​) can silently drop or cache `SameSite`/`Secure` session cookies.
-- If you must mix environments, use a reverse proxy so the browser always talks to one consistent origin (or disable caching via devtools and clear cookies between switches).
-- When troubleshooting auth/session caching: open a fresh incognito window, clear site data for the target origin, and verify the request includes credentials.
-
 ---
 
 ## Local Test & Development