@oasisprotocol/privana-sdk 0.5.2 → 0.5.4

package/README.md

@@ -54,17 +54,7 @@ function App() {
 `accountingContract` must be the deployed Privana accounting contract address for the same
 environment as `apiUrl`.
 
-### 2. Use the PrivanaButton
-
-```tsx
-import { PrivanaButton } from '@oasisprotocol/privana-sdk'
-
-function MyComponent() {
-  return <PrivanaButton />
-}
-```
-
-### 3. Or build custom UI with hooks
+### 2. Or build custom UI with hooks
 
 ```tsx
 import {
@@ -117,6 +107,40 @@ The hooks cache the returned `X-SIWE-Token`, dedupe concurrent auth so a group o
 private-read hooks only triggers one sign prompt, and retry once on `401` by re-authenticating
 through the same shared in-flight auth request.
 
+### Direct in-app SIWE auth (`siweAuth`)
+
+For same-origin apps that want an explicit authenticated session (and JWT-authenticated writes),
+enable `siweAuth` on `PrivanaProvider`. The connected wallet signs an EIP-4361 message in-app and
+`useSiweAuth()` exposes `login`, `logout`, `session`, and the raw `tokens`:
+
+```tsx
+import { PrivanaProvider, useSiweAuth } from '@oasisprotocol/privana-sdk'
+;<PrivanaProvider siweAuth={{ autoLogin: true }}>
+  <AuthGate />
+</PrivanaProvider>
+```
+
+`siweAuth` accepts `true`, or an object with `autoLogin` (default `true`) and `persistJwt`
+(default `false`). It is mutually exclusive with `hostedAuth`.
+
+#### Persistent JWT sessions (`persistJwt`)
+
+Set `persistJwt: true` to mirror the session in `localStorage` (key scoped by API URL and chain ID)
+so a page reload restores an active session without another signature prompt:
+
+```tsx
+;<PrivanaProvider siweAuth={{ autoLogin: true, persistJwt: true }}>
+  <App />
+</PrivanaProvider>
+```
+
+Logout captures the refresh token, clears local and cross-tab state immediately, suppresses
+automatic re-login, and attempts server-side revocation.
+
+> **Security note:** storing long-lived refresh credentials in `localStorage` makes them reachable
+> from any JavaScript running on the page. An XSS vulnerability could exfiltrate them and forge a
+> session, so only enable `persistJwt` on origins you fully control.
+
 ### Hosted redirect auth for cross-domain apps
 
 For widget or cross-domain frontends, configure `hostedAuth` on `PrivanaProvider` and use
@@ -191,33 +215,6 @@ Notes:
 - staging end-to-end verification requires that registration on the staging deployment.
 - the standalone localhost popup page used during Firefox debugging was diagnostic only; it is not part of the supported SDK integration path.
 
-## Components
-
-### PrivanaButton
-
-A customizable button that opens the wallet modal.
-
-```tsx
-// Basic usage
-<PrivanaButton />
-
-// Custom text
-<PrivanaButton>Open Wallet</PrivanaButton>
-
-// Custom styling
-<PrivanaButton variant="default" size="lg" className="my-class" />
-
-// Full control with render prop
-<PrivanaButton
-  renderButton={({ onClick, isOpen }) => (
-    <MyButton onClick={onClick}>Custom Button</MyButton>
-  )}
-/>
-
-// Show when wallet disconnected (disabled state)
-<PrivanaButton hideWhenDisconnected={false} />
-```
-
 ## Hooks
 
 | Hook                     | Description                                                                                                        |