@nibgate/sdk 0.1.7 → 0.1.9

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nibgate-sdk
-description: Use when integrating, auditing, documenting, or modifying creator-owned paid content flows with the @nibgate/sdk package. Covers installing the package, adding the Nibgate widget, defining resources, protecting server routes, emitting content/unlock events, creating nibgate.json discovery metadata, wiring Circle Gateway/x402 one-time unlocks, and avoiding fake payment or client-only gating patterns.
+description: Complete guide for integrating @nibgate/sdk into a creator-owned site. Covers widget installation, resource definition, server gating, payments (Circle Gateway/x402 on Arc Testnet), browser unlock UI, admin panel for managing gating settings, onchain reputation/ratings, manifest/discovery metadata, and common gotchas.
 ---
 
 # Nibgate SDK
 
-Use `@nibgate/sdk` in the creator-owned site that actually serves the content. Nibgate Hub verifies the site, indexes public metadata, and records events; the creator site keeps the protected payload and payment receiver logic.
+Use `@nibgate/sdk` in the creator-owned site that serves the content. The Nibgate Hub verifies the site, indexes public metadata, and records events. The creator site keeps the protected payload, payment receiver logic, and admin configuration.
 
 ## Install
 
@@ -20,16 +20,11 @@ When an AI agent is helping install Nibgate, give it this file first:
 - package copy: `node_modules/@nibgate/sdk/SKILL.md`
 - public copy: `https://nibgate.xyz/skill.md`
 
-The guide is intentionally compact so agents can follow the correct package, widget, server gating, payment, and event patterns without guessing. If an agent is modifying a creator site, tell it to read `SKILL.md` before editing routes or checkout code.
+Read this entire file before editing any routes or checkout code. The guide follows the full integration order.
 
-Use browser helpers from `@nibgate/sdk` and access enforcement from `@nibgate/sdk/server`:
-
-```ts
-import { checkResourceAccess, setupResourcePage, trackResourcePage } from '@nibgate/sdk'
-import { createCircleGatewayServer, manifestResponse } from '@nibgate/sdk/server'
-```
+---
 
-## Site Widget
+## 1. Site Widget (Analytics & Ownership Proof)
 
 Paste the dashboard widget into the verified site layout:
 
@@ -41,9 +36,13 @@ Paste the dashboard widget into the verified site layout:
 </script>
 ```
 
-The widget proves ownership and receives browser-side content, view, unlock, receipt, and reputation events. If the widget loads after app code, package events queue and flush when ready.
+**The widget is ONLY for analytics.** It proves domain ownership, detects resources from `data-nibgate-resource` attributes or meta tags, tracks page views, scroll depth, and time spent. It does NOT pop up a wallet or handle checkout. Wallet/payment logic comes from the SDK browser helpers.
 
-## Resource Shape
+If the widget loads after app code, the SDK queues events and flushes them when the widget is ready.
+
+---
+
+## 2. Resource Shape
 
 Define one stable resource per paid route, CMS row, media item, file, or API product:
 
@@ -64,11 +63,15 @@ const resource = {
 }
 ```
 
-Allowed public content types are `article`, `image`, `music`, and `video`. Use stable external ids; changing ids breaks continuity for Explore, receipts, and reputation.
+Allowed types: `article`, `image`, `music`, `video` (aliases like `audio→music`, `photo→image` are normalized). Use stable IDs — changing IDs breaks continuity for Explore, receipts, and reputation.
+
+**Important:** The `image`, `description`, and `title` fields become the public thumbnail and card copy on the Explore page. Use a teaser preview, not the actual paid file.
+
+---
 
-## Discovery Metadata
+## 3. Discovery Metadata (nibgate.json)
 
-Expose public metadata at `/nibgate.json`:
+Expose public metadata at `/nibgate.json` so the Hub can index your content:
 
 ```ts
 import { manifestResponse } from '@nibgate/sdk/server'
@@ -83,9 +86,49 @@ export function GET() {
 
 Never include the protected payload in `nibgate.json`. It is only for public cards, indexing, and agent-readable discovery.
 
-## Browser Page Wiring
+---
+
+## 4. Server Access Route (Payment Challenge & Unlock)
+
+Protect paid content in a server route, API handler, or middleware:
+
+```ts
+import { createCircleGatewayServer } from '@nibgate/sdk/server'
+
+const nibgate = createCircleGatewayServer({
+  origin: process.env.NIBGATE_SITE_ORIGIN,
+  secret: process.env.NIBGATE_SECRET,
+  network: process.env.NIBGATE_PAYMENT_NETWORK || 'eip155:5042002'
+})
+
+export function GET(request: Request) {
+  return nibgate.accessResponse(request, resource, {
+    getContent: async () => new Response(protectedHtml, {
+      headers: { 'content-type': 'text/html; charset=utf-8' }
+    })
+  })
+}
+```
+
+**How `accessResponse` works:**
+1. Checks for an existing unlock proof via `x-nibgate-payment-proof` header
+2. If valid → returns content (200)
+3. If not and `humans: 'blocked'` → returns 403
+4. If not and `humans: 'paid'` → returns a `402 Payment Required` challenge with the creator's wallet, price, and network
+5. If the request has a `payment-signature` header AND `NIBGATE_PAYMENT_MODE=circle-gateway` is set → verifies the payment and returns unlock proof + content
+
+**The `accessPath` is queried exactly as-is.** The SDK does not auto-append `?id=` or route params. If your access route needs a content identifier, include it in the path (e.g., `/api/nibgate/access/my-content-id`) or pass it as a query param in the resource's `accessPath` field.
+
+**Custom backends:** If you build your own access route instead of using `accessResponse()`, your route must:
+- Return 402 with the challenge JSON when no payment proof is present
+- Check for `payment-signature` header — if present and valid, return 200 with `{ ok: true, unlockProof: "...", payment: {...} }`
+- Check for `x-nibgate-payment-proof` header — if present and valid, return 200 with the protected content
+
+---
+
+## 5. Browser Page Wiring (Unlock UI)
 
-Track the resource page and wire unlock UI:
+Track the resource page and wire the unlock button:
 
 ```ts
 import { setupResourcePage, trackResourcePage } from '@nibgate/sdk'
@@ -102,52 +145,244 @@ setupResourcePage(resource, {
 })
 ```
 
-For custom flows, use `checkResourceAccess(resource, options)` directly. The browser can start checkout and report state, but the server must verify payment and issue unlock proof before returning protected content.
+For the browser wallet checkout flow (user signs with MetaMask):
+
+```ts
+import { createEvmGatewayUnlock } from '@nibgate/sdk'
+
+createEvmGatewayUnlock(resource, {
+  accessPath: '/api/nibgate/access',
+  unlockButton: '#unlock-btn',
+  status: '#status',
+  connectButton: '#connect-btn'
+})
+```
+
+The browser flow:
+1. `checkResourceAccess()` calls the access route
+2. If 402 → prompts wallet to sign the Gateway payment
+3. Sends signature back to access route
+4. Server verifies and returns unlock proof
+5. Proof stored in localStorage → subsequent requests include it as `x-nibgate-payment-proof`
 
-## Server Access Route
+For custom flows, use `checkResourceAccess(resource, options)` directly.
 
-Protect paid content in a server route, API handler, middleware, guard, or signed file endpoint:
+---
+
+## 6. Server-Side Pay Route (Alternative to Browser Wallet)
+
+For testing or server-driven payments, add a pay endpoint that uses the server's buyer key:
 
 ```ts
-import { createCircleGatewayServer } from '@nibgate/sdk/server'
+import { nibgateServer } from './nibgate-resource'
 
-const nibgate = createCircleGatewayServer({
-  origin: process.env.NIBGATE_SITE_ORIGIN,
-  secret: process.env.NIBGATE_SECRET,
-  network: process.env.NIBGATE_PAYMENT_NETWORK || 'eip155:5042002'
+export function POST({ request }) {
+  return nibgateServer.payAndUnlockResponse(request, resource, {
+    origin: process.env.NIBGATE_SITE_ORIGIN,
+    accessPath: '/api/nibgate/access'
+  })
+}
+```
+
+This requires `NIBGATE_BUYER_PRIVATE_KEY` to be set. In production, prefer browser wallet checkout so the user pays from their own wallet.
+
+---
+
+## 7. Admin Panel (Manage Gating Settings From Your Site)
+
+The SDK ships a ready-to-use admin panel that lets creators manage gating, pricing, and settings from the creator's own site instead of editing code.
+
+### Setup
+
+```ts
+import { createFileStore, createAdminApi } from '@nibgate/sdk/server'
+import express from 'express'
+
+const store = createFileStore({ path: './nibgate-settings.json' })
+const admin = createAdminApi({ store })
+
+const app = express()
+app.use(express.json())
+
+// Mount admin API routes (list, get, update, delete resource settings)
+app.use(admin.router(express))
+
+// Or use individual handlers for non-Express frameworks:
+// app.get('/admin/nibgate/resources', admin.handleList)
+// app.post('/admin/nibgate/resources/:id', admin.handleUpdate)
+```
+
+### Protect the admin route
+
+Pass an `authorize` function to `createAdminApi`:
+
+```ts
+const admin = createAdminApi({
+  store,
+  authorize: (req) => {
+    // Check session, API key, admin token, etc.
+    return req.headers['x-admin-key'] === process.env.ADMIN_KEY
+  }
 })
+```
 
-export function GET(request: Request) {
-  return nibgate.accessResponse(request, resource, {
-    getContent: async () => new Response(protectedHtml, {
-      headers: { 'content-type': 'text/html; charset=utf-8' }
-    })
-  })
+### Using settings in your resource definitions
+
+The admin panel stores per-resource settings. Build resource objects from stored settings:
+
+```ts
+import { settingsToAccessPolicy, settingsToUnlockPolicy } from '@nibgate/sdk/server'
+
+function getResource(id) {
+  const settings = store.get(id) || {}
+  return {
+    id,
+    title: settings.title || post.title,
+    type: settings.type || 'article',
+    price: settings.price || '0.01',
+    currency: settings.currency || 'USDC',
+    recipient: settings.recipient || process.env.NIBGATE_SELLER_ADDRESS,
+    access: settingsToAccessPolicy(settings),
+    unlock: settingsToUnlockPolicy(settings),
+    ratingsEnabled: settings.ratingsEnabled !== false
+  }
 }
 ```
 
-The route should return a real `402 Payment Required` challenge until the request has a valid payment proof or signed unlock proof.
+### Admin page
 
-## Hardcoded Or File-Based Content
+Visit `/admin/nibgate` in your browser. The page shows all configured resources with controls for:
+- Human access (free / paid / blocked)
+- Agent access (free / paid / blocked)
+- Unlock mode
+- Payment rail
+- Price & currency
+- Recipient wallet
+- Ratings toggle
+- Content type
+- Publish to discovery toggle
 
-Hardcoded content, MDX files, Markdown files, static JSON files, and repo-local media metadata can be gated when the protected payload stays server-side until access is allowed.
+---
 
-Safe pattern:
+## 8. Payments (Circle Gateway / x402 on Arc Testnet)
 
-1. keep the public teaser, title, price, and metadata in the page;
-2. keep the full paid body in a server-only module, route handler, CMS fetch, DB row, private file, or signed URL endpoint;
-3. run `accessResponse(...)`, `accessFor(...)`, middleware, or a framework guard before returning the full payload.
+For v1, treat `unlock.mode: 'one_time'` with Circle Gateway/x402 as the production path. All payments settle on Arc Testnet (chain ID 5042002) in USDC.
 
-Unsafe pattern:
+### How payment works
 
-- rendering the paid body into public HTML and hiding it with CSS;
-- bundling the paid body into client JavaScript;
-- putting private text into `nibgate.json`, JSON-LD, meta tags, page source, or static exports;
-- exposing an open API route that returns the protected body without checking payment proof.
+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`)
+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
+6. Browser stores the token as `x-nibgate-payment-proof` for subsequent requests
 
-## Required Env Vars
+### Before testing locally
+
+Deposit testnet USDC from your wallet into the Gateway facilitator so transactions can settle:
+
+```bash
+npx nibgate deposit 10
+```
 
-Creator site:
+Check your Gateway balance:
+
+```bash
+npx nibgate balance
+```
+
+### Env vars
+
+```bash
+NIBGATE_PAYMENT_MODE=circle-gateway
+NIBGATE_PAYMENT_NETWORK=eip155:5042002
+NIBGATE_SELLER_ADDRESS=0xCreatorReceiver
+NIBGATE_BUYER_PRIVATE_KEY=0x...   # Only for local testing
+```
+
+### Important
+
+- A Gateway/x402 payment signature is a valid payment proof. A normal wallet message signature (`eth_sign` / `personal_sign`) is NOT payment — do not accept it.
+- Use `NIBGATE_BUYER_PRIVATE_KEY` only in local demos. In production, the visitor or agent wallet signs the payment challenge.
+- The `NIBGATE_SECRET` used by `createNibgateServer()` MUST match the secret used by your access and pay routes. If they diverge, unlock tokens signed by one route fail verification on the other. Set once, use everywhere.
+
+### For plain HTML/JS sites without a bundler
+
+The SDK relies on bare module imports (`viem`, `@x402/core`). These won't work in the browser without a bundler. Compile a browser-ready bundle:
+
+```bash
+esbuild --bundle --format=iife --global-name=Nibgate \
+  --outfile=nibgate-bundle.js \
+  node_modules/@nibgate/sdk/src/browser/index.js
+```
+
+Then load it:
+
+```html
+<script src="/nibgate-bundle.js"></script>
+<script>
+  const { nibgate, gate } = Nibgate
+</script>
+```
+
+### Smart Contract Wallets
+
+Some smart contract wallets (Gnosis Safe, Argent, etc.) may not support `eth_signTypedData_v4` required by the Gateway payment signing. Test with an EOA (MetaMask, Rabby, Coinbase Wallet) first. If your users primarily use smart contract wallets, use the server-side pay route (`payAndUnlockResponse`) with `NIBGATE_BUYER_PRIVATE_KEY` instead.
+
+---
+
+## 9. Onchain Reputation & Ratings
+
+After a verified unlock, users can rate content onchain via the `NibgateReputation.sol` contract deployed on Arc Testnet.
+
+### How it works
+
+1. User unlocks content (has a valid unlock proof)
+2. rating UI calls `rateContentOnchain(resource, { rating, paymentId })`
+3. User signs an onchain transaction with their rating
+4. Transaction indexed by Nibgate's reputation indexer (polls every 30s)
+5. Rating contributes to content/creator reputation scores on Explore and leaderboards
+
+### Browser rating UI
+
+```ts
+import { createOnchainRating } from '@nibgate/sdk'
+
+createOnchainRating(resource, {
+  ratingButtons: '[data-rating]',
+  status: '#rating-status',
+  payment: latestPayment  // from the unlock result
+})
+```
+
+Or buttons with `data-nibgate-rating-value="4"` attributes. Ratings are 1-5.
+
+### Reputation requirements
+
+- Only ratings from wallets that have an unlock receipt for the same content are counted
+- Ratings are onchain (requires gas on Arc Testnet)
+- Content reputation (0-5 stars) and creator reputation (0-100 score) update after indexing
+
+---
+
+## 10. Hardcoded Or File-Based Content
+
+Hardcoded content, MDX files, Markdown files, static JSON files, and repo-local media can be gated when the protected payload stays server-side until access is allowed.
+
+**Safe pattern:**
+1. Keep the public teaser, title, price, and metadata in the page
+2. Keep the full paid body in a server-only module, route handler, CMS fetch, DB row, private file, or signed URL endpoint
+3. Run `accessResponse()`, `accessFor()`, middleware, or a framework guard before returning the full payload
+
+**Unsafe pattern (will not protect your content):**
+- Rendering the paid body into public HTML and hiding it with CSS
+- Bundling the paid body into client JavaScript
+- Putting private text into `nibgate.json`, JSON-LD, meta tags, page source, or static exports
+- Exposing an open API route that returns the protected body without checking payment proof
+
+---
+
+## 11. Required Env Vars
 
 ```bash
 NIBGATE_SITE_ORIGIN=https://creator.example
@@ -160,30 +395,38 @@ NIBGATE_PAYMENT_NETWORK=eip155:5042002
 NIBGATE_SELLER_ADDRESS=0xCreatorReceiver
 ```
 
-Only expose values with `NEXT_PUBLIC_` or client-side env names when they are intentionally public, such as site id, public token, API base, or reputation contract address. Never ship `NIBGATE_SECRET`, private keys, R2 credentials, Resend keys, database URLs, or privileged payment credentials to browser code.
+Only expose values with `NEXT_PUBLIC_` or client-side env names when they are intentionally public (site id, public token, API base, reputation contract address). Never ship `NIBGATE_SECRET`, private keys, R2 credentials, Resend keys, database URLs, or privileged payment credentials to browser code.
 
-## Payments
+---
 
-For v1, treat `unlock.mode: 'one_time'` with Circle Gateway/x402 as the production path. A Gateway/x402 payment signature is a payment proof. A normal wallet message signature is not payment.
+## 12. Common Gotchas
 
-Use `NIBGATE_BUYER_PRIVATE_KEY` only in local demos or controlled tests. In production, the visitor or agent wallet signs/pays the returned `PAYMENT-REQUIRED` challenge.
+- **Widget is only for analytics.** It does not pop up wallets or handle checkout. Use the SDK browser helpers for that.
+- **accessPath is literal.** The SDK does not append `?id=` or route params. Include identifiers in the path or query string manually.
+- **Custom backends must handle `payment-signature` header.** If you build your own access route without `accessResponse()`, your route must detect `payment-signature` header and return 200 on valid proof, not 402.
+- **Cookie `[object Object]` bug.** The unlock proof must be a string (the token from `createUnlockToken`), not an object. `storePaymentProof` now handles both, but ensure your server returns `unlockProof` as a string.
+- **Secrets must match.** `NIBGATE_SECRET` must be the same in `createNibgateServer()`, the access route, and the pay route. Mismatch causes unlock tokens to fail verification silently.
+- **Smart contract wallets** may not support `eth_signTypedData_v4`. Use an EOA or the server-side pay route.
+- **Wallet extension conflicts** can cause signature corruption if multiple wallets are installed. Advise users to disable other wallet extensions when testing.
+- **Deposit before testing locally.** Run `npx nibgate deposit 10` to fund the Gateway facilitator balance.
 
-## Reputation
+---
 
-After a verified unlock, rating UI can submit onchain ratings for the same resource. Reputation-critical inputs should be tied to unlock/payment proof and indexed from chain activity. Page views, scroll depth, and referrers are analytics signals, not trust by themselves.
+## 13. Never Do These
 
-## Never Do These
+- Do not hide paid HTML with CSS or client state after rendering it publicly
+- Do not fake payment IDs, receipts, unlocks, or successful access
+- Do not replace Gateway/x402 payment signatures with ordinary wallet message signatures
+- Do not store backend secrets in browser env vars
+- Do not let mutable titles or slugs be the only resource identity
+- Do not expose private content in `nibgate.json`, meta tags, JSON-LD, page source, or static builds
 
-- Do not hide paid HTML with CSS or client state after rendering it publicly.
-- Do not fake payment ids, receipts, unlocks, or successful access.
-- Do not replace Gateway/x402 payment signatures with ordinary wallet message signatures.
-- Do not store backend secrets in browser env vars.
-- Do not let mutable titles or slugs be the only resource identity.
-- Do not expose private content in `nibgate.json`, meta tags, JSON-LD, page source, or static builds.
+---
 
-## Framework Notes
+## 14. Framework Notes
 
-- **Next.js**: use route handlers for `/nibgate.json` and `/api/nibgate/access`; protect content before rendering paid payloads.
-- **Express/NestJS**: use middleware, controllers, or guards around protected routes.
-- **Astro/SvelteKit/Remix**: use SSR/server routes or endpoints; plain static builds need a protected API or signed URL for private payloads.
-- **CMS apps**: save Nibgate resource settings beside each content record, including type, price, currency, receiver wallet, access policy, unlock mode, and discovery preference.
+- **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`.
+- **Astro/SvelteKit/Remix**: Use SSR/server routes or endpoints. Plain static builds need a protected API or signed URL for private payloads.
+- **CMS apps**: Save Nibgate resource settings beside each content record. Use `settingsToAccessPolicy()` and `settingsToUnlockPolicy()` to convert stored settings to resource shapes. Mount the admin panel for easy management.
+- **Static/vanilla HTML/JS**: Compile the SDK into a bundle with esbuild (see section 8). Use `gate()` and `nibgate` from the global `Nibgate` namespace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nibgate/sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Framework-agnostic browser and server package for creator-owned gated content, unlock events, and receipts.",
   "type": "module",
   "sideEffects": false,

package/src/browser/index.js

@@ -556,6 +556,66 @@ export function createOnchainRating(resource, options = {}) {
   return controller;
 }
 
+export function mountRatingUI(resource, options = {}) {
+  const item = createGate(resource, options.gateOptions || {});
+  const win = browserWindow();
+  if (!win) return null;
+  const target = typeof options.target === 'string' ? win.document.querySelector(options.target) : options.target;
+  if (!target) return null;
+
+  const stars = [1, 2, 3, 4, 5];
+  let selectedRating = 0;
+
+  const container = win.document.createElement('div');
+  container.className = 'nibgate-rating-ui';
+  container.style.cssText = 'display:flex;align-items:center;gap:4px;padding:8px 0';
+
+  const starButtons = stars.map((value) => {
+    const btn = win.document.createElement('button');
+    btn.type = 'button';
+    btn.dataset.nibgateRatingValue = String(value);
+    btn.setAttribute('aria-label', `${value} star${value > 1 ? 's' : ''}`);
+    btn.innerHTML = '☆';
+    btn.style.cssText = 'background:none;border:none;font-size:24px;cursor:pointer;color:#ccc;transition:color 0.15s;padding:2px;line-height:1';
+    btn.addEventListener('mouseenter', () => {
+      starButtons.forEach((b, i) => b.style.color = i < value ? '#f5b342' : '#ccc');
+    });
+    btn.addEventListener('mouseleave', () => {
+      starButtons.forEach((b, i) => b.style.color = i < selectedRating ? '#f5b342' : '#ccc');
+    });
+    btn.addEventListener('click', () => {
+      selectedRating = value;
+      starButtons.forEach((b, i) => b.style.color = i < value ? '#f5b342' : '#ccc');
+      rate(item.resource, { rating: value }).catch(() => {});
+    });
+    container.appendChild(btn);
+    return btn;
+  });
+
+  const statusEl = win.document.createElement('span');
+  statusEl.style.cssText = 'font-size:13px;color:#888;margin-left:8px';
+  statusEl.textContent = options.label || 'Rate this content';
+  container.appendChild(statusEl);
+
+  target.appendChild(container);
+
+  function rate(r, input = {}) {
+    return item.rate({ ...input, rating: r });
+  }
+
+  function setRating(value) {
+    selectedRating = value;
+    starButtons.forEach((b, i) => b.style.color = i < value ? '#f5b342' : '#ccc');
+  }
+
+  return {
+    resource: item.resource,
+    container,
+    setRating,
+    rate
+  };
+}
+
 export async function payAndUnlockResource(resource, options = {}) {
   const item = createGate(resource, options.gateOptions || {});
   const payPath = options.payPath || item.resource.payPath || '/api/nibgate/pay';
@@ -690,6 +750,9 @@ export function createNibgate(defaults = {}) {
     createOnchainRating(resource, options = {}) {
       return createOnchainRating(resourceWithDefaults(resource), options);
     },
+    mountRatingUI(resource, options = {}) {
+      return mountRatingUI(resourceWithDefaults(resource), options);
+    },
     payAndUnlockResource(resource, options = {}) {
       return payAndUnlockResource(resourceWithDefaults(resource), options);
     },

package/src/browser/storage.js

@@ -27,7 +27,8 @@ export function storePaymentProof(resource, proof) {
   const win = browserWindow();
   if (!win || !proof) return false;
   try {
-    win.localStorage.setItem(proofStorageKey(resource), String(proof));
+    const value = typeof proof === 'string' ? proof : JSON.stringify(proof);
+    win.localStorage.setItem(proofStorageKey(resource), value);
     return true;
   } catch (_error) {
     return false;

package/src/index.d.ts

@@ -114,6 +114,7 @@ export type NibgateClient = {
   createEvmGatewayUnlock(resource: NibgateResource | string, options?: NibgateEvmGatewayUnlockOptions): NibgateEvmGatewayUnlockController;
   rateContentOnchain(resource: NibgateResource | string, options: NibgateOnchainRatingOptions): Promise<NibgateOnchainRatingResult>;
   createOnchainRating(resource: NibgateResource | string, options?: NibgateOnchainRatingUiOptions): NibgateOnchainRatingController;
+  mountRatingUI(resource: NibgateResource | string, options?: NibgateRatingUiOptions): NibgateRatingUiController | null;
   payAndUnlockResource(resource: NibgateResource | string, options?: NibgatePaymentOptions): Promise<NibgatePaymentResult>;
   setupResourcePage(resource: NibgateResource | string, options?: NibgatePageSetupOptions): NibgateGate;
   ratingMessage(resource: NibgateResource | string, rating?: NibgateRating | number, options?: Record<string, unknown>): string;
@@ -430,5 +431,18 @@ export declare function ratingMessage(resource: NibgateResource | string, rating
 export declare function createNibgate(defaults?: { resource?: NibgateResource }): NibgateClient;
 export declare const nibgate: NibgateClient;
 
+export interface NibgateRatingUiOptions {
+  target?: string | HTMLElement;
+  label?: string;
+  gateOptions?: Record<string, unknown>;
+}
+export interface NibgateRatingUiController {
+  resource: NibgateResource;
+  container: HTMLElement;
+  setRating(value: number): void;
+  rate(resource: NibgateResource | string, input?: Record<string, unknown>): ReturnType<typeof rateContentOnchain>;
+}
+export declare function mountRatingUI(resource: NibgateResource | string, options?: NibgateRatingUiOptions): NibgateRatingUiController | null;
+
 export declare function createTransferCheckout(resource: NibgateResource | string, options: NibgateTransferCheckoutOptions): NibgateTransferCheckout;
 export declare function payWithTransfer(resource: NibgateResource | string, options: NibgateTransferCheckoutOptions & NibgateAccessCheckOptions): Promise<NibgateAccessCheckResult>;

package/src/server/access.js

@@ -104,7 +104,7 @@ export function createNibgateServer(options = {}) {
       }
 
       const rail = normalizePaymentRail(resource.paymentRail || routeOptions.paymentRail || options.paymentRail || routeOptions.paymentMode || options.paymentMode);
-      if (rail === 'gateway' && (routeOptions.paymentMode || options.paymentMode || serverEnv('NIBGATE_PAYMENT_MODE') || 'circle-gateway') === 'circle-gateway') {
+      if (rail === 'gateway' && (routeOptions.paymentMode || options.paymentMode || serverEnv('NIBGATE_PAYMENT_MODE')) === 'circle-gateway') {
         const gateway = await runCircleGatewayRequirement(request, resource, { ...options, ...routeOptions });
         if (gateway.handled) return gateway.response;
         const result = await unlock(resource, gateway.payment);

package/src/server/admin-store.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { serverEnv } from './env.js';
+
+export function createFileStore(options = {}) {
+  const filePath = path.resolve(options.path || serverEnv('NIBGATE_ADMIN_STORE_PATH') || './nibgate-settings.json');
+
+  function read() {
+    try {
+      if (!fs.existsSync(filePath)) return {};
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch {
+      return {};
+    }
+  }
+
+  function write(data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+  }
+
+  return {
+    list() {
+      const data = read();
+      return Object.entries(data).map(([id, settings]) => ({ id, ...settings }));
+    },
+    get(id) {
+      const data = read();
+      return data[id] || null;
+    },
+    set(id, settings) {
+      const data = read();
+      data[id] = { ...(data[id] || {}), ...settings, updatedAt: new Date().toISOString() };
+      write(data);
+      return data[id];
+    },
+    remove(id) {
+      const data = read();
+      delete data[id];
+      write(data);
+      return true;
+    }
+  };
+}
+
+export function createMemoryStore() {
+  const store = {};
+  return {
+    list() {
+      return Object.entries(store).map(([id, settings]) => ({ id, ...settings }));
+    },
+    get(id) { return store[id] || null; },
+    set(id, settings) {
+      store[id] = { ...(store[id] || {}), ...settings, updatedAt: new Date().toISOString() };
+      return store[id];
+    },
+    remove(id) { delete store[id]; return true; }
+  };
+}

package/src/server/admin.js

@@ -0,0 +1,261 @@
+import { jsonResponse } from './response.js';
+import { createNibgateContentSettings, settingsToAccessPolicy, settingsToUnlockPolicy, NIBGATE_CONTENT_SETTING_FIELDS } from '../core/settings.js';
+import { normalizeServerResource as normalizeResource } from '../core/resource.js';
+
+export function createAdminApi(options = {}) {
+  const store = options.store;
+  if (!store) throw new Error('Admin API requires a store. Pass one from createFileStore() or createMemoryStore().');
+
+  function requireAdmin(req, _res) {
+    if (typeof options.authorize === 'function') return options.authorize(req);
+    return true;
+  }
+
+  async function handleList(req, res) {
+    if (!requireAdmin(req, res)) return jsonResponse({ error: 'Unauthorized' }, { status: 403 });
+    const all = store.list();
+    return jsonResponse({ success: true, fields: NIBGATE_CONTENT_SETTING_FIELDS, items: all });
+  }
+
+  async function handleGet(req, res) {
+    if (!requireAdmin(req, res)) return jsonResponse({ error: 'Unauthorized' }, { status: 403 });
+    const item = store.get(req.params.id);
+    if (!item) return jsonResponse({ error: 'Not found' }, { status: 404 });
+    return jsonResponse({ success: true, fields: NIBGATE_CONTENT_SETTING_FIELDS, item });
+  }
+
+  async function handleUpdate(req, res) {
+    if (!requireAdmin(req, res)) return jsonResponse({ error: 'Unauthorized' }, { status: 403 });
+    const settings = createNibgateContentSettings(req.body || {});
+    const saved = store.set(req.params.id, settings);
+    return jsonResponse({ success: true, item: saved });
+  }
+
+  async function handleDelete(req, res) {
+    if (!requireAdmin(req, res)) return jsonResponse({ error: 'Unauthorized' }, { status: 403 });
+    store.remove(req.params.id);
+    return jsonResponse({ success: true });
+  }
+
+  function buildResourceFromSettings(id, settings) {
+    const access = settingsToAccessPolicy(settings);
+    const unlock = settingsToUnlockPolicy(settings);
+    return normalizeResource({
+      id,
+      type: settings.type,
+      price: settings.price,
+      currency: settings.currency,
+      recipient: settings.recipient,
+      access,
+      unlock,
+      ratingsEnabled: settings.ratingsEnabled,
+      license: settings.license
+    });
+  }
+
+  function router(express) {
+    const Route = express?.Router ? express.Router() : null;
+    if (!Route) return null;
+
+    Route.get('/admin/nibgate/resources', handleList);
+    Route.get('/admin/nibgate/resources/:id', handleGet);
+    Route.post('/admin/nibgate/resources/:id', handleUpdate);
+    Route.delete('/admin/nibgate/resources/:id', handleDelete);
+    Route.get('/admin/nibgate', (_req, res) => {
+      const html = adminPageHtml({ title: options.title || 'Nibgate Admin' });
+      res.setHeader('content-type', 'text/html; charset=utf-8');
+      res.end(html);
+    });
+
+    return Route;
+  }
+
+  return {
+    handleList,
+    handleGet,
+    handleUpdate,
+    handleDelete,
+    buildResourceFromSettings,
+    router,
+    store,
+    settingsFields: NIBGATE_CONTENT_SETTING_FIELDS
+  };
+}
+
+function adminPageHtml(options = {}) {
+  const title = options.title || 'Nibgate Admin';
+  const apiBase = options.apiBase || '/admin/nibgate';
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${title}</title>
+<style>
+  *,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+  body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f5f5f0;color:#1a1a18;padding:24px;max-width:960px;margin:0 auto}
+  h1{font-size:28px;font-weight:700;margin-bottom:8px}
+  p.sub{color:#666;margin-bottom:24px}
+  .card{background:#fff;border-radius:12px;padding:20px;margin-bottom:16px;box-shadow:0 1px 3px rgba(0,0,0,0.08)}
+  .card-header{display:flex;justify-content:space-between;align-items:center;margin-bottom:12px}
+  .card-header h3{font-size:18px;font-weight:600}
+  .status{font-size:12px;padding:3px 10px;border-radius:99px;font-weight:600}
+  .status-gated{background:#fef3c7;color:#92400e}
+  .status-open{background:#d1fae5;color:#065f46}
+  .status-hidden{background:#fce4ec;color:#c62828}
+  .field-row{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin-bottom:12px}
+  .field{display:flex;flex-direction:column;gap:4px}
+  .field label{font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.05em;color:#555}
+  .field input,.field select{font-size:14px;padding:8px 10px;border:1px solid #ddd;border-radius:6px;background:#fff}
+  .field input:focus,.field select:focus{outline:2px solid #7c9a6d;border-color:transparent}
+  .field .checkbox-row{display:flex;align-items:center;gap:8px;padding-top:6px}
+  .field .checkbox-row input[type="checkbox"]{width:18px;height:18px}
+  .empty{text-align:center;padding:48px;color:#888}
+  .toast{position:fixed;bottom:24px;right:24px;background:#1a1a18;color:#fff;padding:12px 20px;border-radius:8px;font-size:14px;opacity:0;transition:opacity 0.3s;z-index:100}
+  .toast.show{opacity:1}
+  .toast.error{background:#c62828}
+  .header-bar{display:flex;justify-content:space-between;align-items:center;margin-bottom:24px}
+  .header-bar a{color:#7c9a6d;text-decoration:none;font-size:14px;font-weight:600}
+  .header-bar a:hover{text-decoration:underline}
+  .help-text{font-size:12px;color:#888;margin-top:2px}
+</style>
+</head>
+<body>
+<div class="header-bar">
+  <div>
+    <h1>Nibgate Admin</h1>
+    <p class="sub">Manage gating, pricing, and settings for your content.</p>
+  </div>
+  <a href="/nibgate.json" target="_blank">View manifest →</a>
+</div>
+<div id="app"><div class="empty">Loading resources...</div></div>
+<div id="toast" class="toast"></div>
+<script>
+const API = '${apiBase}';
+let fields = [];
+let items = [];
+
+async function load() {
+  try {
+    const res = await fetch(API + '/resources');
+    const data = await res.json();
+    if (!data.success) throw new Error(data.error || 'Failed to load');
+    fields = data.fields || [];
+    items = data.items || [];
+    render();
+  } catch (err) {
+    document.getElementById('app').innerHTML = '<div class="empty">Error loading: ' + err.message + '</div>';
+  }
+}
+
+function statusLabel(item) {
+  if (item.humanAccess === 'paid') return '<span class="status status-gated">Gated</span>';
+  if (item.humanAccess === 'blocked') return '<span class="status status-hidden">Blocked</span>';
+  return '<span class="status status-open">Open</span>';
+}
+
+function render() {
+  const app = document.getElementById('app');
+  if (!items.length) {
+    app.innerHTML = '<div class="empty">No resources configured yet. Add resources through the Nibgate SDK and they will appear here after the next manifest sync.</div>';
+    return;
+  }
+  app.innerHTML = items.map(item => {
+    const humanAccess = fields.find(f => f.name==='humanAccess');
+    const agentAccess = fields.find(f => f.name==='agentAccess');
+    const unlockMode = fields.find(f => f.name==='unlockMode');
+    return '<div class="card" data-id="' + item.id + '">' +
+      '<div class="card-header">' +
+        '<h3>' + escapeHtml(item.title || item.id) + '</h3>' +
+        statusLabel(item) +
+      '</div>' +
+      '<div class="field-row">' +
+        selectField('humanAccess', 'Human access', humanAccess?.options || ['free','paid','blocked'], item.humanAccess) +
+        selectField('agentAccess', 'Agent access', agentAccess?.options || ['free','paid','blocked'], item.agentAccess) +
+      '</div>' +
+      '<div class="field-row">' +
+        selectField('unlockMode', 'Unlock mode', unlockMode?.options || ['one_time'], item.unlockMode) +
+        selectField('paymentRail', 'Payment rail', ['gateway','transfer'], item.paymentRail || 'gateway') +
+      '</div>' +
+      '<div class="field-row">' +
+        textField('price', 'Price (' + (item.currency || 'USDC') + ')', item.price) +
+        textField('currency', 'Currency', item.currency || 'USDC') +
+      '</div>' +
+      '<div class="field-row">' +
+        textField('recipient', 'Recipient wallet', item.recipient || '') +
+        checkboxField('ratingsEnabled', 'Enable onchain ratings', item.ratingsEnabled !== false) +
+      '</div>' +
+      '<div class="field-row">' +
+        selectField('type', 'Content type', ['article','music','video','image'], item.type || 'article') +
+        checkboxField('publishToNibgate', 'Publish to discovery', item.publishToNibgate !== false) +
+      '</div>' +
+      '<div><button class="save-btn" onclick="save(this)">Save</button></div>' +
+    '</div>';
+  }).join('');
+}
+
+function textField(name, label, value) {
+  return '<div class="field"><label>' + label + '</label><input type="text" name="' + name + '" value="' + escapeAttr(value || '') + '" /></div>';
+}
+
+function selectField(name, label, options, value) {
+  const opts = (options || []).map(o => '<option value="' + o + '"' + (o === value ? ' selected' : '') + '>' + o + '</option>').join('');
+  return '<div class="field"><label>' + label + '</label><select name="' + name + '">' + opts + '</select></div>';
+}
+
+function checkboxField(name, label, checked) {
+  return '<div class="field"><label>' + label + '</label><div class="checkbox-row"><input type="checkbox" name="' + name + '"' + (checked ? ' checked' : '') + ' /></div></div>';
+}
+
+function escapeHtml(str) {
+  const div = document.createElement('div');
+  div.textContent = str;
+  return div.innerHTML;
+}
+
+function escapeAttr(str) {
+  return String(str).replace(/"/g,'&quot;').replace(/'/g,'&#39;');
+}
+
+async function save(btn) {
+  const card = btn.closest('.card');
+  const id = card.dataset.id;
+  const inputs = card.querySelectorAll('[name]');
+  const body = {};
+  inputs.forEach(inp => {
+    if (inp.type === 'checkbox') body[inp.name] = inp.checked;
+    else body[inp.name] = inp.value;
+  });
+  btn.disabled = true;
+  btn.textContent = 'Saving...';
+  try {
+    const res = await fetch(API + '/resources/' + encodeURIComponent(id), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body)
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(data.error || 'Save failed');
+    toast('Saved ' + (data.item.title || id), 'success');
+    load();
+  } catch (err) {
+    toast(err.message, 'error');
+    btn.disabled = false;
+    btn.textContent = 'Save';
+  }
+}
+
+function toast(msg, type) {
+  const el = document.getElementById('toast');
+  el.textContent = msg;
+  el.className = 'toast ' + (type==='error'?'error':'') + ' show';
+  setTimeout(() => { el.classList.remove('show'); }, 3000);
+}
+
+load();
+</script>
+</body>
+</html>`;
+}
+
+export { adminPageHtml };

package/src/server/index.js

@@ -13,3 +13,5 @@ export { normalizeServerResource as normalizeResource, normalizeAccessPolicy, no
 export const server = createNibgateServer();
 export { NIBGATE_CONTENT_SETTING_FIELDS, createNibgateContentSettings, settingsToAccessPolicy, settingsToUnlockPolicy } from '../core/settings.js';
 export { PAYMENT_RAILS, normalizePaymentRail } from '../core/payment.js';
+export { createAdminApi, adminPageHtml } from './admin.js';
+export { createFileStore, createMemoryStore } from './admin-store.js';

package/src/server.d.ts

@@ -218,3 +218,25 @@ export declare function normalizeResource(resource?: NibgateServerResource | str
 export declare function validateResourceMetadata(resource?: NibgateServerResource | string, options?: Record<string, unknown>): NibgateMetadataValidation;
 export declare function normalizeAccessPolicy(access?: NibgateAccessMode | NibgateAccessPolicy): Required<Pick<NibgateAccessPolicy, 'humans' | 'agents'>>;
 export declare function normalizeUnlockPolicy(unlock?: NibgateUnlockMode | NibgateUnlockPolicy): Required<Pick<NibgateUnlockPolicy, 'mode'>> & NibgateUnlockPolicy;
+
+// Admin API
+export interface NibgateAdminStore {
+  list(): Record<string, unknown>[];
+  get(id: string): Record<string, unknown> | null;
+  set(id: string, settings: Record<string, unknown>): Record<string, unknown>;
+  remove(id: string): boolean;
+}
+export interface NibgateAdminApi {
+  handleList(req: Request, res: Record<string, unknown>): Promise<Response>;
+  handleGet(req: Request, res: Record<string, unknown>): Promise<Response>;
+  handleUpdate(req: Request, res: Record<string, unknown>): Promise<Response>;
+  handleDelete(req: Request, res: Record<string, unknown>): Promise<Response>;
+  buildResourceFromSettings(id: string, settings: Record<string, unknown>): NibgateServerResource;
+  router(expressModule: Record<string, unknown>): unknown;
+  store: NibgateAdminStore;
+  settingsFields: Record<string, unknown>[];
+}
+export declare function createAdminApi(options: { store: NibgateAdminStore; title?: string; authorize?: (req: Request) => boolean }): NibgateAdminApi;
+export declare function createFileStore(options?: { path?: string }): NibgateAdminStore;
+export declare function createMemoryStore(): NibgateAdminStore;
+export declare function adminPageHtml(options?: { title?: string; apiBase?: string }): string;