@nibgate/sdk 0.2.19 → 0.2.21

package/README.md

@@ -259,16 +259,88 @@ The package includes small controller UIs, not a heavy design system:
 
 Creators keep their own UI/theme. Nibgate provides the hard parts: resource normalization, metadata validation, x402/Gateway unlock, transfer fallback, event streaming, proof storage, rating tx submission, and hub sync.
 
+## Security
+
+### Premium content must NEVER be in the HTML
+
+This is the most important rule. Paid content (body, media URLs, download links) **must not exist in the initial page HTML**. Including it with `display: none` or `hidden` is not secure — anyone can view the page source or use DevTools to see it.
+
+**Correct architecture:**
+
+```
+[Browser]                  [Your Server]              [Hub]          [Circle]
+    │                            │                       │               │
+    ├── GET /api/content/:id ────┤                       │               │
+    │                            ├── returns teaser ─────┤               │
+    │    (NO body in HTML)       │  (no body for paid)   │               │
+    │                            │                       │               │
+    ├── GET /api/nibgate/access ─┤                       │               │
+    │    with stored proof       ├── verifyProof() ──────┤               │
+    │◄─── 200 { content } ───────┤                       │               │
+    │                            │                       │               │
+    │  [Content rendered from    │                       │               │
+    │   server response, never   │                       │               │
+    │   in page source]          │                       │               │
+```
+
+**Implementation pattern (backend):**
+
+```js
+// Public endpoint — NEVER returns body for paid posts
+router.get('/posts/:slug', async (req, res) => {
+  const post = await db.post.findUnique({ where: { slug: req.params.slug } });
+  if (post.price) {
+    const { body, ...teaser } = post;  // strip body
+    return res.json({ post: { ...teaser, isLocked: true } });
+  }
+  res.json({ post });
+});
+
+// Protected endpoint — returns body only after proof verification
+router.get('/nibgate/access', async (req, res) => {
+  const access = nibgateServer.accessFor(request, resource);
+  if (access.allowed) {
+    const post = await db.post.findUnique({ where: { slug } });
+    return res.json({ ok: true, content: post.body });  // body ONLY here
+  }
+  // ... 402 challenge or payment processing
+});
+```
+
+**Implementation pattern (frontend):**
+
+```js
+// The NibgateUnlock component handles everything:
+// 1. On mount: sends stored proof → gets content immediately if valid
+// 2. If 402: shows unlock button → MetaMask signs → sends proof → gets content
+// 3. Content is NEVER in the HTML, only from server response
+
+function NibgateUnlock({ resource }) {
+  const [content, setContent] = useState('');
+
+  useEffect(() => {
+    fetch('/api/nibgate/access', {
+      headers: { 'x-nibgate-payment-proof': storedProof }
+    }).then(res => res.json()).then(data => {
+      if (data.content) setContent(data.content);
+    });
+  }, []);
+
+  if (content) return <div>{content}</div>;
+  return <button onClick={handleUnlock}>Unlock</button>;
+}
+```
+
 ## FAQ / integration gotchas
 
-- `Does a creator need a server?` Yes for real paid gating. Static-only sites can register discovery events, but protected content needs a server, edge function, CMS webhook, or API route that can return `402` and verify payment proof.
+- `Does a creator need a server?` Yes for real paid gating. Static-only sites can register discovery events, but protected content needs a server, edge function, CMS webhook, or API route that can return `402` and verify payment proof. The premium body must come from a protected route, not from client-side hiding.
 - `Can every post pay a different wallet?` Yes. Set `recipient` or `payTo` per resource. The package does not force one site-wide receiver.
 - `Can this work with DB blogs, MDX, CMS, plain HTML, or custom apps?` Yes. Convert each content item into a Nibgate resource with `id`, `title`, `type`, `url`, `path`, `price`, and `recipient`.
 - `Why does content not show in Explore?` Usually the widget is missing, the site is not verified, the manifest has not synced yet, `url` is not absolute, or required metadata is missing.
 - `Why does reputation not update?` The rating wallet must have an unlock/payment proof for that content, the rating tx must be onchain, and the backend indexer must sync the tx.
 - `Are page views reputation?` No. Views, referrers, scroll depth, and time spent are analytics signals. Reputation-critical scores come from indexed onchain ratings tied to unlock proof.
 - `Do agents use a different flow?` No. Agents discover the same resource metadata, pay through the same protected route, and can emit/index reputation using the same proof model.
-- `Should hidden content live in browser HTML?` No. The browser should only receive teasers before payment. The full body/media URL should come from a protected route after proof verification.
+- `Should hidden content live in browser HTML?` **Never.** The browser should only receive teasers before payment. The full body/media URL should come from a protected route after proof verification. See the Security section above.
 - `What breaks most often locally?` Missing wallet provider, wrong chain, missing Gateway client module, CORS on the backend, wrong `NIBGATE_API_BASE`, wrong site token, or a demo route using fallback challenge mode instead of real Gateway mode.
 
 

package/SKILL.md

@@ -53,6 +53,9 @@ If the widget loads after app code, the SDK queues events and flushes them when
     <button data-nibgate-unlock-btn>Unlock for 0.01 USDC</button>
     <p data-nibgate-status></p>
   </div>
+  <!-- WARNING: This hidden pattern is NOT secure. Content is in the HTML.
+       Use only for teasers or non-sensitive content.
+       For real paid gating, serve content from a protected server endpoint. -->
   <div data-nibgate-unlocked hidden>
     Full premium content here...
   </div>
@@ -61,6 +64,8 @@ If the widget loads after app code, the SDK queues events and flushes them when
 
 No SDK import, no server access route, no env vars. The default wallet is set once in the Nibgate dashboard — or override per-post with `data-nibgate-recipient`. Custom price per-post: change `data-nibgate-premium="0.05"`.
 
+> **⚠️ Security warning:** Hosted mode puts premium content in the page HTML (hidden by CSS). Anyone can view-source and read it. For real paid content, use server-side gating with the `accessResponse` or `protect` methods. See the Security section below.
+
 ---
 
 ## 2. Resource Shape (Minimal)
@@ -311,11 +316,14 @@ For v1, treat `unlock.mode: 'one_time'` with Circle Gateway/x402 as the producti
 ### How payment works
 
 1. Browser requests access → server returns 402 challenge with creator's wallet, price, network
-2. Browser prompts user to sign a Gateway payment payload (EIP-712 typed data via `eth_signTypedData_v4`)
+2. Browser prompts user to sign a Gateway payment payload (EIP-712 typed data via viem's `walletClient.signTypedData()` through MetaMask)
 3. Signed payload sent to server as `payment-signature` header
 4. Server verifies with `createGatewayMiddleware` from `@circle-fin/x402-batching/server`
-5. On success, server creates an HMAC-signed unlock token and returns it
+5. On success, server creates an HMAC-signed unlock token and returns it directly with the **premium content body**
 6. Browser stores the token as `x-nibgate-payment-proof` for subsequent requests
+7. On return visits, browser sends stored proof → server verifies → returns content without payment
+
+> **⚠️ Important:** Use viem's `createWalletClient` + `custom(window.ethereum)` transport instead of raw `eth_signTypedData_v4`. This ensures consistent EIP-712 hashing across wallets (MetaMask, Rabby, etc.). Raw `eth_signTypedData_v4` can produce hashes that don't match what the server expects.
 
 ### Before testing locally
 
@@ -630,7 +638,89 @@ Events emitted automatically by `createNibgateServer`: `payment_completed`, `unl
 
 ---
 
-## 16. Framework Notes
+## 16. Security: Content Must Never Be in HTML
+
+This is the single most important rule for paid content:
+
+**❌ Wrong (insecure):**
+```html
+<div data-nibgate-premium>
+  <div data-nibgate-unlocked hidden>
+    <!-- Premium content visible in page source -->
+  </div>
+</div>
+```
+
+**✅ Correct (secure):**
+```
+1. Backend: Public endpoint returns post WITHOUT body for paid content
+2. Frontend: Shows unlock button (no content in HTML)
+3. After payment: Backend returns content ONLY via the protected access endpoint
+4. Frontend: Renders content from the server response (never in source)
+```
+
+### Architecture
+
+```
+[Public endpoint]              [Protected endpoint]
+GET /api/posts/:slug           GET /api/nibgate/access
+  ├── free post → return body    ├── Has valid proof → return body + unlock token
+  └── paid post → return teaser  └── No proof → 402 challenge
+       (NO body in response)          (browser signs, retries)
+```
+
+### Frontend pattern (React)
+
+```tsx
+function NibgateUnlock({ resource }) {
+  const [content, setContent] = useState('');
+
+  // On mount: check stored proof → get content or show unlock
+  useEffect(() => {
+    fetch('/api/nibgate/access', {
+      headers: { 'x-nibgate-payment-proof': storedProof }
+    }).then(r => r.json()).then(data => {
+      if (data.content) setContent(data.content);
+    });
+  }, []);
+
+  if (content) return <div>{content}</div>;   // Already paid → show content
+  return <button onClick={handleUnlock}>Pay</button>;  // Need payment
+}
+```
+
+### Backend pattern (Express)
+
+```js
+// Public — NEVER returns body for paid content
+app.get('/posts/:slug', async (req, res) => {
+  const post = await db.post.findUnique({ where: { slug } });
+  if (post.price) {
+    const { body, ...teaser } = post;
+    return res.json({ post: { ...teaser, isLocked: true } }); // NO body
+  }
+  res.json({ post }); // free post → body OK
+});
+
+// Protected — returns body after proof verification
+app.get('/nibgate/access', async (req, res) => {
+  const access = server.accessFor(request, resource);
+  if (access.allowed) {
+    const post = await db.post.findUnique({ where: { slug } });
+    return res.json({ ok: true, content: post.body }); // body ONLY here
+  }
+  // ... 402 flow
+});
+```
+
+### Key rules
+
+- **Never** include paid content in the initial HTML, even with `hidden` or `display:none`
+- **Never** return the body from a public API endpoint for paid posts
+- **Always** serve content through the protected access endpoint after proof verification
+- **Always** use viem's `walletClient.signTypedData()` with MetaMask, not raw `eth_signTypedData_v4`
+
+## 17. Framework Notes
 
 - **Next.js**: Use route handlers for `/nibgate.json` and `/api/nibgate/access`. Protect content before rendering paid payloads. Use `server-only` for private modules.
 - **Express/NestJS**: Use middleware, controllers, or guards around protected routes. Mount the admin router at `/admin/nibgate`.