Add CoinPay OAuth + x402 payments, and BYO-SQLite storage config

- packages/payments: x402 protocol primitives, CoinPay wallet contract,
  PaymentProcessor (network/asset match + maxAmount guard); 6 tests
- auth: CoinPay OAuth provider (Auth Code + PKCE), hosted defaults +
  self-hosted overrides, x402 scopes; 4 tests
- storage: resolveStorageConfig — managed Turso cloud (backups) by default,
  or bring-your-own SQLite (local file / libSQL replica / own server,
  self-hosted, user-managed backups); 6 tests
- .env.example documents DB + CoinPay config; real .env gitignored
- PRD: Payments + Storage sections, payments package added

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ralyodio

.env.example

@@ -0,0 +1,20 @@
+# Copy to .env and fill in. .env is gitignored.
+#
+# --- Storage ---------------------------------------------------------------
+# Option A: managed cloud database (Turso) — has managed backups.
+TRONBROWSER_DB_URL=libsql://your-db.turso.io
+TRONBROWSER_DB_AUTH_TOKEN=your-turso-token
+#
+# Option B: bring your own SQLite — you own your data (and your backups).
+#   Local file:
+# TRONBROWSER_DB_PATH=/home/you/.tronbrowser/db.sqlite
+#   Or your own libSQL server:
+# TRONBROWSER_DB_URL=libsql://db.your-server.example
+# TRONBROWSER_DB_AUTH_TOKEN=your-token
+#
+# --- CoinPay OAuth (x402 payments) ----------------------------------------
+COINPAY_CLIENT_ID=
+COINPAY_REDIRECT_URI=tronbrowser://oauth/coinpay
+# Override only for self-hosted CoinPay:
+# COINPAY_AUTHORIZE_URL=https://coinpay.profullstack.com/oauth/authorize
+# COINPAY_TOKEN_URL=https://coinpay.profullstack.com/oauth/token

docs/tronbrowser-prd.md

@@ -51,6 +51,7 @@ packages/
 - storage
 - sdk
 - plugins
+- payments
 - ui
 - shared
 
@@ -122,6 +123,32 @@ Lifecycle:
 - update
 - uninstall
 
+# Payments
+
+CoinPay OAuth + x402.
+
+Auth:
+- CoinPay OAuth (Authorization Code + PKCE)
+- Scopes: wallet:read, payments:x402
+- Self-hosted CoinPay overridable
+
+x402 (HTTP 402 Payment Required):
+- Parse payment requirements from 402 responses
+- Pay from the user's CoinPay global wallet addresses (match network + asset)
+- Custodial keys (never leave CoinPay)
+- Per-request maxAmount guard; budgets/ledger via agent runtime
+
+Package: packages/payments (x402 + CoinPay wallet + PaymentProcessor)
+
+# Storage
+
+SQLite/libSQL, self-hostable.
+
+- Default: managed cloud DB (Turso) — managed backups + replication
+- Bring your own: local SQLite file, local libSQL replica, or your own libSQL server (self-hosted, user-owned, user-managed backups)
+- Object storage: Cloudflare R2
+- Config via TRONBROWSER_DB_URL / TRONBROWSER_DB_AUTH_TOKEN / TRONBROWSER_DB_PATH
+
 # Sync
 
 Objects:

packages/auth/README.md

@@ -1,19 +1,27 @@
 # @tronbrowser/auth
 
-Authentication and session primitives
+Authentication and session primitives, including **CoinPay OAuth** sign-in.
 
-> Status: **stub** — interfaces defined, implementation pending. Part of milestone **M0 (Monorepo)**.
+CoinPay OAuth lets a user connect their CoinPay account so TronBrowser can
+authorize x402 payments (see [`@tronbrowser/payments`](../payments)) from their
+CoinPay global wallet addresses. Keys stay custodial in CoinPay.
 
-## Install
+```ts
+import { CoinPayOAuthProvider } from '@tronbrowser/auth';
 
-```bash
-pnpm add @tronbrowser/auth
+const provider = new CoinPayOAuthProvider({
+  clientId: process.env.COINPAY_CLIENT_ID!,
+  redirectUri: 'tronbrowser://oauth/coinpay',
+  // authorizeUrl/tokenUrl default to hosted CoinPay; override for self-hosted.
+});
+const url = provider.authorizeUrl(state, codeChallenge); // PKCE
 ```
 
-## Scripts
+## Modules
 
-- `pnpm build` — compile TypeScript to `dist/`
-- `pnpm typecheck` — type-check without emitting
-- `pnpm test` — run unit tests (vitest)
+- `oauth.ts` — generic OAuth 2.0 (Authorization Code + PKCE) contracts
+- `coinpay-oauth.ts` — `CoinPayOAuthProvider`, defaults, self-hosted overrides
 
-See the [PRD](../../docs/tronbrowser-prd.md) for the overall architecture.
+Scopes requested: `wallet:read`, `payments:x402`. Token exchange/refresh land in M2.
+
+See the [PRD](../../docs/tronbrowser-prd.md) §Payments.

packages/auth/src/coinpay-oauth.ts

@@ -0,0 +1,78 @@
+/**
+ * CoinPay OAuth provider. Lets a user sign into TronBrowser with their CoinPay
+ * account so the browser can authorize x402 payments (see @tronbrowser/payments)
+ * from their CoinPay global wallet addresses.
+ *
+ * Endpoints default to CoinPay's hosted service and are overridable for
+ * self-hosted CoinPay deployments.
+ */
+
+import {
+  isExpired,
+  type OAuthConfig,
+  type OAuthProvider,
+  type OAuthTokens,
+} from './oauth.js';
+
+export const COINPAY_DEFAULTS = {
+  authorizeUrl: 'https://coinpay.profullstack.com/oauth/authorize',
+  tokenUrl: 'https://coinpay.profullstack.com/oauth/token',
+  /** Scopes needed to read wallet addresses and authorize x402 payments. */
+  scopes: ['wallet:read', 'payments:x402'],
+} as const;
+
+export interface CoinPayOAuthConfig {
+  clientId: string;
+  redirectUri: string;
+  /** Override for self-hosted CoinPay; defaults to the hosted service. */
+  authorizeUrl?: string;
+  tokenUrl?: string;
+  scopes?: string[];
+}
+
+/** Resolves user-supplied config against CoinPay defaults. */
+export function resolveCoinPayConfig(cfg: CoinPayOAuthConfig): OAuthConfig {
+  return {
+    clientId: cfg.clientId,
+    redirectUri: cfg.redirectUri,
+    authorizeUrl: cfg.authorizeUrl ?? COINPAY_DEFAULTS.authorizeUrl,
+    tokenUrl: cfg.tokenUrl ?? COINPAY_DEFAULTS.tokenUrl,
+    scopes: cfg.scopes ?? [...COINPAY_DEFAULTS.scopes],
+  };
+}
+
+/**
+ * CoinPay OAuth provider (Authorization Code + PKCE). Network calls are stubbed
+ * until M2; URL construction is implemented and tested now.
+ */
+export class CoinPayOAuthProvider implements OAuthProvider {
+  readonly config: OAuthConfig;
+
+  constructor(config: CoinPayOAuthConfig) {
+    this.config = resolveCoinPayConfig(config);
+  }
+
+  authorizeUrl(state: string, codeChallenge: string): string {
+    const u = new URL(this.config.authorizeUrl);
+    u.searchParams.set('response_type', 'code');
+    u.searchParams.set('client_id', this.config.clientId);
+    u.searchParams.set('redirect_uri', this.config.redirectUri);
+    u.searchParams.set('scope', this.config.scopes.join(' '));
+    u.searchParams.set('state', state);
+    u.searchParams.set('code_challenge', codeChallenge);
+    u.searchParams.set('code_challenge_method', 'S256');
+    return u.toString();
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async exchangeCode(_code: string, _codeVerifier: string): Promise<OAuthTokens> {
+    throw new Error('CoinPayOAuthProvider.exchangeCode: not implemented (M2)');
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async refresh(_refreshToken: string): Promise<OAuthTokens> {
+    throw new Error('CoinPayOAuthProvider.refresh: not implemented (M2)');
+  }
+}
+
+export { isExpired };

packages/auth/src/index.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import {
+  CoinPayOAuthProvider,
+  resolveCoinPayConfig,
+  COINPAY_DEFAULTS,
+  isExpired,
+} from './index.js';
+
+describe('CoinPay OAuth', () => {
+  it('defaults to the hosted CoinPay endpoints and x402 scopes', () => {
+    const cfg = resolveCoinPayConfig({ clientId: 'abc', redirectUri: 'tronbrowser://cb' });
+    expect(cfg.authorizeUrl).toBe(COINPAY_DEFAULTS.authorizeUrl);
+    expect(cfg.scopes).toContain('payments:x402');
+  });
+
+  it('allows self-hosted CoinPay overrides', () => {
+    const cfg = resolveCoinPayConfig({
+      clientId: 'abc',
+      redirectUri: 'tronbrowser://cb',
+      authorizeUrl: 'https://pay.example.com/oauth/authorize',
+    });
+    expect(cfg.authorizeUrl).toBe('https://pay.example.com/oauth/authorize');
+  });
+
+  it('builds a PKCE authorize URL', () => {
+    const provider = new CoinPayOAuthProvider({
+      clientId: 'abc',
+      redirectUri: 'tronbrowser://cb',
+    });
+    const url = new URL(provider.authorizeUrl('state123', 'challenge456'));
+    expect(url.searchParams.get('response_type')).toBe('code');
+    expect(url.searchParams.get('client_id')).toBe('abc');
+    expect(url.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(url.searchParams.get('state')).toBe('state123');
+  });
+
+  it('detects expiry with skew', () => {
+    const tokens = { accessToken: 'x', expiresAt: 1000, tokenType: 'Bearer' };
+    expect(isExpired(tokens, 980)).toBe(true); // within 30s skew
+    expect(isExpired(tokens, 900)).toBe(false);
+  });
+});

packages/auth/src/index.ts

@@ -1,7 +1,9 @@
 /**
  * @tronbrowser/auth
- * Authentication and session primitives
- *
- * Stub — see ../../docs/tronbrowser-prd.md
+ * Authentication and session primitives, including CoinPay OAuth.
  */
+
 export const PACKAGE_NAME = '@tronbrowser/auth' as const;
+
+export * from './oauth.js';
+export * from './coinpay-oauth.js';

packages/auth/src/oauth.ts

@@ -0,0 +1,36 @@
+/**
+ * Generic OAuth 2.0 (Authorization Code + PKCE) contracts shared by providers.
+ */
+
+export interface OAuthConfig {
+  clientId: string;
+  /** Where the provider redirects after consent. */
+  redirectUri: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  scopes: string[];
+}
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  /** Unix seconds at which accessToken expires. */
+  expiresAt: number;
+  tokenType: string;
+  scope?: string;
+}
+
+/** Authorization-code provider with PKCE. */
+export interface OAuthProvider {
+  /** Builds the URL to send the user to for consent. */
+  authorizeUrl(state: string, codeChallenge: string): string;
+  /** Exchanges an authorization code for tokens. */
+  exchangeCode(code: string, codeVerifier: string): Promise<OAuthTokens>;
+  /** Refreshes an expired access token. */
+  refresh(refreshToken: string): Promise<OAuthTokens>;
+}
+
+/** True when the token is expired or within `skewSeconds` of expiring. */
+export function isExpired(tokens: OAuthTokens, nowSeconds: number, skewSeconds = 30): boolean {
+  return nowSeconds >= tokens.expiresAt - skewSeconds;
+}

packages/payments/README.md

@@ -0,0 +1,40 @@
+# @tronbrowser/payments
+
+x402 (HTTP 402 "Payment Required") payment processing over the user's **CoinPay**
+global wallet addresses.
+
+> Status: **stub** — interfaces + pure logic defined, network calls pending.
+> Added alongside M2 (AI sidebar) work; depends conceptually on CoinPay OAuth in
+> [`@tronbrowser/auth`](../auth).
+
+## How it works
+
+1. A request hits a resource that responds `402` with payment requirements.
+2. `PaymentProcessor` parses the requirements and picks one of the user's CoinPay
+   wallet addresses matching the required **network + asset**.
+3. CoinPay (custodial — keys never leave CoinPay) authorizes/signs the payment.
+4. The processor returns the `X-PAYMENT` header to retry the original request.
+
+```ts
+import { PaymentProcessor } from '@tronbrowser/payments';
+
+const processor = new PaymentProcessor(coinPayWallet);
+const { headers } = await processor.process(await res.json(), { maxAmount: 1_000_000n });
+const paid = await fetch(url, { headers: { ...headers } });
+```
+
+## Modules
+
+| File | Contents |
+| --- | --- |
+| `x402.ts` | Protocol primitives: `parsePaymentRequired`, `encode/decodePaymentHeader`, header constants |
+| `coinpay.ts` | `CoinPayWallet` contract, `CoinPayAddress`, `selectAddress()` |
+| `processor.ts` | `PaymentProcessor` — one payment end to end, with an optional `maxAmount` guard |
+
+## Privacy & safety
+
+- Keys are custodial in CoinPay; TronBrowser only holds a short-lived OAuth token.
+- `maxAmount` caps per-request spend; agent budgets/ledger live in the agent runtime.
+- Nothing is paid automatically without a wallet that matches network + asset.
+
+See the [PRD](../../docs/tronbrowser-prd.md) §Payments.

packages/payments/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tronbrowser/payments",
+  "version": "0.0.0",
+  "private": true,
+  "description": "x402 payment processing over the user's CoinPay global wallet addresses",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "echo \"[lint] payments: stub\""
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}

packages/payments/src/coinpay.ts

@@ -0,0 +1,54 @@
+/**
+ * CoinPay wallet integration for x402.
+ *
+ * The user authenticates with CoinPay (OAuth — see `@tronbrowser/auth`) and
+ * TronBrowser holds a short-lived access token. CoinPay exposes the user's
+ * "global wallet addresses" (one or more per network) and authorizes payments
+ * against them. Keys stay custodial in CoinPay; TronBrowser never sees them.
+ */
+
+import type { PaymentRequirements, PaymentPayload } from './x402.js';
+
+/** Minimal token source; satisfied by `@tronbrowser/auth` without coupling. */
+export interface AccessTokenProvider {
+  getAccessToken(): Promise<string>;
+}
+
+/** One of the user's CoinPay global wallet addresses. */
+export interface CoinPayAddress {
+  /** Network id matching x402 PaymentRequirements.network. */
+  network: string;
+  address: string;
+  /** Asset symbols this address can spend, e.g. ["USDC", "ETH"]. */
+  assets: string[];
+}
+
+/** Result of asking CoinPay to authorize a payment for an x402 requirement. */
+export interface CoinPayAuthorization {
+  payload: PaymentPayload;
+  /** CoinPay's internal reference for the authorization. */
+  reference: string;
+}
+
+/** Client over the CoinPay wallet API. Implementation lands post-stub. */
+export interface CoinPayWallet {
+  /** Lists the user's global wallet addresses across networks. */
+  listAddresses(): Promise<CoinPayAddress[]>;
+  /** Atomic-unit balance of `asset` on `network`. */
+  getBalance(network: string, asset: string): Promise<string>;
+  /** Asks CoinPay to sign/authorize a payment satisfying `req`. */
+  authorize(req: PaymentRequirements, from: CoinPayAddress): Promise<CoinPayAuthorization>;
+}
+
+/**
+ * Picks the user's wallet address that can satisfy a payment requirement
+ * (matching network + asset). Returns undefined when none qualifies. Pure.
+ */
+export function selectAddress(
+  addresses: CoinPayAddress[],
+  req: Pick<PaymentRequirements, 'network' | 'asset'>,
+): CoinPayAddress | undefined {
+  return addresses.find(
+    (a) => a.network === req.network && a.assets.includes(req.asset),
+  );
+}