nibgate

# Nibgate — open protocol for paid content

[Website](https://nibgate.xyz) | [Docs](https://docs.nibgate.xyz) | [X](https://x.com/nibgate)

Nibgate is a verified content discovery, unlock, and reputation layer for creator-owned work. Creators keep their content on their own domains. Nibgate verifies the source, indexes structured public metadata, records unlock/payment signals, and helps humans and AI agents discover quality content without moving it into a closed marketplace.

Built on ARC testnet and the x402 protocol, with two payment rails: Circle Gateway (EIP-3009 facilitator) and direct USDC transfer to the creator's receiver.

**Key packages:**

- **SDK (`packages/nibgate/`)** — `@nibgate/sdk` npm package for gating paid content on any creator site. Browser and server entrypoints, x402/Gateway unlocks, event streaming, onchain ratings. Includes the shared access-control rule (`canAccess`, `normalizeWhitelist`, `paidCutoffWallets`) used by both rails and the encryption primitives (`crypto.js`).
- **Wallet (`packages/wallet/`)** — `@nibgate/wallet` npm package with a `./react` entry: shared Reown AppKit (AppKit + wagmi) wallet provider, SIWE sign-in, and the `<NibgateUnlock>`/`GatewayWallet` single-checkout used by the hub header, Nibshare, and Subblogs.
- **Subblogs (`subblogs/`)** — Full blog platform for creators at `*.nibgate.xyz`. Articles, photos, music, video, documents, free and paid posts. Next.js frontend (port 3002), Express backend (port 4000), PostgreSQL. SIWE wallet auth, whitelists/invite-only tiers, AES-256-GCM encryption at rest.
- **Hub (`frontend/` + `backend/`)** — The main `nibgate.xyz` app: public site, creator dashboard, Explore discovery, analytics, API, Nibshare quick-share rail, and widget hosting.
- **CLI (`packages/cli/`)** — Internal tooling for local dev, site verification, and hub connection.
- **Docs (`docs/`)** — Documentation site at docs.nibgate.xyz.

## Product Thesis

The open web needs a content discovery standard for paid, high-quality resources. Nibgate provides the verified layer that says:

1. this domain is controlled by this creator
2. this content exists at this route
3. this content can be unlocked by humans or agents
4. this creator has real reputation signals from verified activity
5. this payment history routes directly to the configured receiver for the resource

The creator-owned site remains the source of truth, while the hub becomes the public index, analytics surface, and reputation graph around verified content.

It consists of four connected parts:

1. **The Widget**: Creators paste one script on their site. It proves domain ownership, creates visitor/session context, and sends browser-safe page activity to Nibgate.
2. **The Package**: Creators install the `@nibgate/sdk` npm package to gate real content on their own site. The package knows the content, unlock, and payment lifecycle, then reports those events through the widget bridge.
3. **The Hub**: `nibgate.xyz` is the creator dashboard, discovery surface, and analytics layer. It verifies sites, stores content metadata, aggregates metrics, and shows profile/site/content/earnings data.
4. **The Discovery Layer**: Explore, public profiles, content metadata, receipts, and reputation signals make verified creator content readable by people and AI agents.

## Repo Layout

```txt
backend/       Express hub API — payment verification, hosted-pay resolution,
               metrics, site/manifest sync, revenue keeper (fee-wallet sweeps)
frontend/      Next.js hub UI — public site, dashboard, Explore, leaderboards
subblogs/      Subblogs — full blog platform for creators (Express+Prisma + Next.js)
packages/      @nibgate/sdk npm package + wallet package + CLI tooling
contracts/     Solidity + Foundry: reputation contracts and the per-creator
               GatewayFeeWallet / GatewayFeeWalletFactory (revenue model)
docs/          Nextra docs site for docs.nibgate.xyz
scripts/       E2E flows and deployment tooling (reputation, revenue factory)
nibgate.config.json  Sample CLI config (routes to local demo content)
```

Local-only, not tracked: `e2e/` (Playwright browser harness), `swarm/` (agent wallets), `video/`, `v2-labs/`, `revenue-model/` (research/poc). See `.gitignore`.

## Workspace Shape

### `backend/` & `frontend/` (The Hub)

The Hub is the main Nibgate app and API surface. It acts as the creator dashboard, public site, and discovery directory:

- `/explore` The discovery masonry grid indexing all creator content.
- `/ledger` Public activity feed — every unlock, payment, and onchain rating across all sites, searchable and filterable. New entries slide in live.
- `/discovery.md` Agent guidance — plain-language description of Nibgate endpoints, payment flow, and rating flow for AI agents.
- `/auth/*` Sign-In with Ethereum (SIWE) authentication.
- `/hub/*` Hub connection, sync, verification, and event ingestion.
- `/hub/ledger?domain=X` Public ledger endpoint with optional domain filter for per-site activity.

### `subblogs/` (Subblogs — Creator Blog Platform)

This is an example creator blog with paid content gating. Two services:

- **`subblogs/backend/`** (Express + Prisma) — serves content pages, handles payments via the hub, issues unlock proofs. When R2 is configured, all post bodies and media are encrypted at rest (free and paid); free content is decrypted server-side and served to anyone, paid content only after onchain proof verification. The access endpoint (`GET /api/<type>/<slug>`, a short mirror of `GET /api/nibgate/access`) is the single source of truth for premium content — returns post body only after proof verification. Each post page also self-describes for agents: `GET /api/nibgate/manifest?path=/<type>/<slug>` returns the per-post machine-readable contract (advertised via a `<link rel="alternate">` element and the `Link` response header).
- **`subblogs/frontend/`** (Next.js) — public blog UI. Premium content is **never** in the HTML. The `NibgateUnlock` component fetches content from the protected access endpoint after proof verification. Admin panel (`/admin/posts`) has a per-post stats sheet showing unlocks, revenue in USDC, and the underlying receipts for each post.

**Critical rule:** The `GET /api/blog/posts/:slug` endpoint decrypts and returns the body for **free** posts, and strips the `body` from **paid** posts. Premium body is only returned by the access endpoint (`GET /api/<type>/<slug>` or `GET /api/nibgate/access`) after valid proof. This prevents paid content from ever appearing in page source, while free content still reads publicly.

### `nibshare` (Quick-Share Gated Content)

A hosted quick-share rail inside the hub: a wallet owner publishes an encrypted payload with an optional price, wallet whitelist, and a required expiry (max 7 days out), and gets a short link at `nibgate.xyz/ns/<slug>`. No domain required. Bodies and media are always AES-256-GCM encrypted at rest in Cloudflare R2; unlock is x402 USDC on Arc via the server-side decrypt proxy (free public shares read openly, invite-only shares require a session-corroborated whitelisted wallet, paid shares after payment). This is a **private** product — it is never indexed in hub discovery, the ledger, or reputation. The share page self-describes for agents: `GET /nibshare/:slug/manifest` (also reachable at `https://api.nibgate.xyz/ns/<slug>`, the short read route) returns the machine-readable contract (advertised via `<meta name="nibgate:*">`, JSON-LD, `data-nibgate-*` attributes, a `<link rel="alternate">` element, and the `Link` response header), and the Nibgate MCP server exposes it as the `resolve_share` tool.

Server source is at `backend/src/server/nibshare/{controller,service,utils,routes}.js`; it delegates access decisions to the SDK's `access-policy.js` (possession rule, pay-before-deny, idempotent receipt granting) and exposes the same entitlement/ban/revoke finance as Subblogs.

Docs live with the implementation, not in a separate top-level folder:

- `backend/src/server/nibshare/README.md` — product, threat model, auth, env
- `backend/src/server/nibshare/API.md` — the HTTP contract
- `backend/src/server/nibshare/STORAGE.md` — R2 layout, encryption, media serving
- `backend/src/server/nibshare/STORAGE-TIER-PLAN.md` — planned Arweave/Lit tiers (not shipped)

### `packages/nibgate/`

This is the public creator package. It is intentionally tiny and framework-agnostic:

```bash
npm install @nibgate/sdk
```

Agents and coding assistants should read the compact integration guide before editing a creator site:

- package copy: `node_modules/@nibgate/sdk/SKILL.md`
- public copy: `https://nibgate.xyz/skill.md`

It owns:

- browser entrypoint: `createGate(...)`, `nibgate.content(...)`, `nibgate.view(...)`, `nibgate.unlockStarted(...)`, `nibgate.unlockCompleted(...)`, and `nibgate.paymentCompleted(...)`
- server entrypoint: `createNibgateServer(...)`, `protect(...)`, `nibgateServer.accessFor(...)`, payment challenges, and unlock token verification
- queueing events until the Hub widget is ready
- normalizing content types to `music`, `video`, `article`, `image`, and `document`
- access policies for humans and agents: `free`, `paid`, or `blocked`
- unlock policies that start with `one_time` for the MVP and leave room for metered reading, streaming, passes, and agent quotas later

### `packages/cli/`

The CLI package is private internal tooling for local development and future setup automation. It owns:

- `npx nibgate`
- local status and setup checks
- config generation helpers
- hub connection and domain verification commands
- future scaffolding around widget/package setup

The public `@nibgate/sdk` package owns route protection, payment challenge metadata, unlock tokens, and package event APIs.

### `demo/`

Local-only and not tracked in this repo. An origin app that behaves like a creator-owned site, used to validate the install flow, DB-backed content mapping, package events, and protected content flow without