@nibgate/sdk 0.1.0

package/src/index.d.ts

@@ -0,0 +1,423 @@
+export type NibgateContentType = 'music' | 'video' | 'article' | 'image';
+export type NibgateAccessMode = 'free' | 'paid' | 'blocked';
+export type NibgateUnlockMode = 'one_time' | 'metered_stream' | 'metered_read' | 'time_pass' | 'agent_quota';
+export type NibgatePaymentRail = 'gateway' | 'transfer';
+export type NibgateAccessPolicy = {
+  humans?: NibgateAccessMode;
+  human?: NibgateAccessMode;
+  agents?: NibgateAccessMode;
+  agent?: NibgateAccessMode;
+  default?: NibgateAccessMode;
+};
+export type NibgateUnlockPolicy = {
+  mode?: NibgateUnlockMode | string;
+  type?: NibgateUnlockMode | string;
+  unit?: string;
+  pricePerUnit?: string | number;
+  duration?: string | number;
+  maxReads?: number;
+  [key: string]: unknown;
+};
+
+export type NibgateResource = {
+  id: string;
+  title?: string;
+  type?: NibgateContentType | string;
+  contentType?: NibgateContentType | string;
+  price?: string | number;
+  paymentRail?: NibgatePaymentRail | string;
+  amount?: string | number;
+  recipient?: string;
+  receiver?: string;
+  receiverAddress?: string;
+  payTo?: string;
+  creatorWallet?: string;
+  path?: string;
+  route?: string;
+  url?: string;
+  imageUrl?: string;
+  image?: string;
+  description?: string;
+  summary?: string;
+  tags?: string[] | string;
+  access?: NibgateAccessMode | NibgateAccessPolicy;
+  unlock?: NibgateUnlockMode | NibgateUnlockPolicy;
+  [key: string]: unknown;
+};
+
+export type NibgateMetadataValidation = {
+  ok: boolean;
+  score: number;
+  errors: string[];
+  warnings: string[];
+  resource: NibgateResource;
+};
+
+export type NibgatePayment = {
+  revenue?: number;
+  amount?: number;
+  currency?: string;
+  paymentId?: string;
+  paymentProvider?: 'circle-gateway' | 'arc-testnet' | 'x402' | string;
+  receiptUrl?: string;
+  txHash?: string;
+  chainId?: string | number;
+  chainExplorerUrl?: string;
+  payer?: string;
+  recipient?: string;
+  [key: string]: unknown;
+};
+
+export type NibgateRating = {
+  rating?: number;
+  stars?: number;
+  ratingValue?: number;
+  score?: number;
+  walletAddress?: string;
+  payer?: string;
+  actor?: 'human' | 'agent' | string;
+  paymentId?: string;
+  txHash?: string;
+  reviewHash?: string;
+  message?: string;
+  ratingMessage?: string;
+  signature?: string;
+  ratingSignature?: string;
+  proofType?: 'onchain' | 'attested' | string;
+  proof?: string;
+  [key: string]: unknown;
+};
+
+export type NibgateClient = {
+  gate(resource: NibgateResource | string, options?: NibgateGateOptions): NibgateGate;
+  content(resource: NibgateResource | string, extra?: Record<string, unknown>): boolean;
+  registerContent(resource: NibgateResource | string, extra?: Record<string, unknown>): boolean;
+  view(resource: NibgateResource | string, extra?: Record<string, unknown>): boolean;
+  track(eventName: string, payload?: Record<string, unknown>): boolean;
+  unlockStarted(resource: NibgateResource | string, extra?: Record<string, unknown>): boolean;
+  unlockCompleted(resource: NibgateResource | string, payment?: NibgatePayment): boolean;
+  paymentCompleted(resource: NibgateResource | string, payment?: NibgatePayment): boolean;
+  rateResource(resource: NibgateResource | string, rating?: NibgateRating | number, extra?: Record<string, unknown>): boolean;
+  trackResourcePage(resource: NibgateResource | string, options?: NibgatePageOptions): NibgateGate;
+  checkResourceAccess(resource: NibgateResource | string, options?: NibgateAccessCheckOptions): Promise<NibgateAccessCheckResult>;
+  payWithPaymentSignature(resource: NibgateResource | string, options?: NibgatePaymentSignatureOptions): Promise<NibgatePaymentSignatureResult>;
+  createWalletCheckout(resource: NibgateResource | string, options: NibgateWalletCheckoutOptions): NibgateWalletCheckoutController;
+  createCircleGatewayBrowserAdapter(options: NibgateCircleGatewayBrowserAdapterOptions): Promise<NibgateCircleGatewayBrowserAdapter>;
+  createTransferCheckout(resource: NibgateResource | string, options: NibgateTransferCheckoutOptions): NibgateTransferCheckout;
+  payWithTransfer(resource: NibgateResource | string, options: NibgateTransferCheckoutOptions & NibgateAccessCheckOptions): Promise<NibgateAccessCheckResult>;
+  createEvmGatewayUnlock(resource: NibgateResource | string, options?: NibgateEvmGatewayUnlockOptions): NibgateEvmGatewayUnlockController;
+  rateContentOnchain(resource: NibgateResource | string, options: NibgateOnchainRatingOptions): Promise<NibgateOnchainRatingResult>;
+  createOnchainRating(resource: NibgateResource | string, options?: NibgateOnchainRatingUiOptions): NibgateOnchainRatingController;
+  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;
+  normalizeResource(resource: NibgateResource | string): NibgateResource;
+  validateResourceMetadata(resource: NibgateResource | string, options?: Record<string, unknown>): NibgateMetadataValidation;
+  normalizeContentType(type?: string): NibgateContentType;
+  flush(): boolean;
+};
+
+export type NibgateGateOptions = {
+  client?: NibgateClient;
+};
+
+export type NibgateGate = {
+  resource: NibgateResource;
+  content(extra?: Record<string, unknown>): boolean;
+  view(extra?: Record<string, unknown>): boolean;
+  track(eventName: string, payload?: Record<string, unknown>): boolean;
+  unlockStarted(extra?: Record<string, unknown>): boolean;
+  unlockCompleted(payment?: NibgatePayment): boolean;
+  paymentCompleted(payment?: NibgatePayment): boolean;
+  isUnlocked(): boolean;
+  markUnlocked(payment?: NibgatePayment): boolean;
+  unlock(handlerOrPayment?: NibgatePayment | ((resource: NibgateResource) => Promise<NibgatePayment> | NibgatePayment)): Promise<{ unlocked: true; resource: NibgateResource; payment: NibgatePayment }>;
+  rate(rating?: NibgateRating | number, extra?: Record<string, unknown>): boolean;
+};
+
+export type NibgatePageOptions = {
+  source?: string;
+  path?: string;
+  referrer?: string;
+  content?: Record<string, unknown>;
+  view?: Record<string, unknown>;
+  gateOptions?: NibgateGateOptions;
+};
+
+export type NibgateAccessCheckOptions = {
+  source?: string;
+  accessPath?: string;
+  payPath?: string;
+  autoPay?: boolean;
+  retryAfterPay?: boolean;
+  paymentSignature?: string;
+  paymentRequiredHeader?: string;
+  memo?: string;
+  checkout?: NibgateCheckoutHandler;
+  createPaymentSignature?: NibgateCheckoutHandler;
+  method?: string;
+  headers?: Record<string, string>;
+  body?: BodyInit | null;
+  payment?: NibgatePayment;
+  paymentProvider?: string;
+  checkingMessage?: string;
+  challengeMessage?: string;
+  successMessage?: string;
+  errorMessage?: string;
+  gateOptions?: NibgateGateOptions;
+  onStatus?: (message: string) => void;
+};
+
+export type NibgateCheckoutInput = {
+  resource: NibgateResource;
+  challenge?: Record<string, unknown> | null;
+  paymentRequiredHeader?: string;
+  accessPath?: string;
+};
+
+export type NibgateCheckoutResult = {
+  paymentSignature?: string;
+  signature?: string;
+  payment?: string | NibgatePayment;
+  memo?: string;
+  paymentMemo?: string;
+  metadata?: NibgatePayment;
+  paymentMetadata?: NibgatePayment;
+  [key: string]: unknown;
+};
+
+export type NibgateCheckoutHandler = (input: NibgateCheckoutInput) => Promise<NibgateCheckoutResult> | NibgateCheckoutResult;
+
+export type NibgateEvmTypedDataSigner = {
+  address: `0x${string}` | string;
+  signTypedData(params: {
+    domain: {
+      name: string;
+      version: string;
+      chainId: number;
+      verifyingContract: `0x${string}` | string;
+    };
+    types: Record<string, Array<{ name: string; type: string }>>;
+    primaryType: string;
+    message: Record<string, unknown>;
+  }): Promise<`0x${string}` | string>;
+};
+
+export type NibgateCircleGatewayBrowserAdapterOptions = {
+  signer?: NibgateEvmTypedDataSigner;
+  getSigner?: () => Promise<NibgateEvmTypedDataSigner> | NibgateEvmTypedDataSigner;
+  network?: string;
+  chainId?: number | string;
+  clientModule?: Record<string, unknown>;
+  clientModuleUrl?: string;
+};
+
+export type NibgateCircleGatewayBrowserAdapter = {
+  signer: NibgateEvmTypedDataSigner;
+  network: string;
+  pay(input: NibgateCheckoutInput): Promise<NibgateCheckoutResult>;
+};
+
+export type NibgateEvmGatewayUnlockOptions = {
+  source?: string;
+  accessPath?: string;
+  network?: string;
+  paymentProvider?: string;
+  circleClientModule?: Record<string, unknown>;
+  circleClientModuleUrl?: string;
+  provider?: {
+    request(args: { method: string; params?: unknown[] }): Promise<unknown>;
+  };
+  connectButton?: string | Element | null;
+  disconnectButton?: string | Element | null;
+  unlockButton?: string | Element | null;
+  clearButton?: string | Element | null;
+  walletLabel?: string | Element | null;
+  status?: string | Element | null;
+  unlockedTarget?: string | Element | null;
+  noWalletMessage?: string;
+  challengeMessage?: string;
+  paymentMessage?: string;
+  successMessage?: string;
+  disconnectMessage?: string;
+  autoMount?: boolean;
+  gateOptions?: NibgateGateOptions;
+  onStatus?: (message: string) => void;
+  onUnlock?: (result: NibgateAccessCheckResult) => void;
+};
+
+export type NibgateEvmGatewayUnlockController = {
+  resource: NibgateResource;
+  connect(): Promise<string>;
+  disconnect(): Promise<boolean>;
+  unlock(): Promise<NibgateAccessCheckResult | { ok: false; status: number; error: string; resource: NibgateResource }>;
+  clear(): void;
+  hydrate(): Promise<void>;
+  mount(): NibgateEvmGatewayUnlockController;
+  getWalletAddress(): string;
+};
+
+export type NibgateWalletCheckoutOptions = NibgateAccessCheckOptions & {
+  button?: string | HTMLButtonElement | null;
+  status?: string | HTMLElement | null;
+  pay?: NibgateCheckoutHandler;
+};
+
+export type NibgateWalletCheckoutController = {
+  resource: NibgateResource;
+  unlock(extra?: Partial<NibgateWalletCheckoutOptions>): Promise<NibgateAccessCheckResult | NibgatePaymentSignatureResult>;
+  mount(): { unlock(extra?: Partial<NibgateWalletCheckoutOptions>): Promise<NibgateAccessCheckResult | NibgatePaymentSignatureResult> };
+};
+
+export type NibgatePaymentSignatureOptions = NibgateAccessCheckOptions & {
+  challenge?: Record<string, unknown> | null;
+  payment?: NibgatePayment;
+};
+
+export type NibgatePaymentOptions = {
+  source?: string;
+  payPath?: string;
+  payMethod?: string;
+  payHeaders?: Record<string, string>;
+  payPayload?: Record<string, unknown>;
+  paymentProvider?: string;
+  paymentMessage?: string;
+  paymentSuccessMessage?: string;
+  paymentErrorMessage?: string;
+  gateOptions?: NibgateGateOptions;
+  onStatus?: (message: string) => void;
+};
+
+export type NibgatePageSetupOptions = NibgatePageOptions & NibgateAccessCheckOptions & {
+  button?: string | HTMLButtonElement | null;
+  status?: string | HTMLElement | null;
+};
+
+export type NibgateAccessCheckResult =
+  | { ok: true; status: number; payload: Record<string, unknown>; payment: NibgatePayment | null; resource: NibgateResource; response: Response }
+  | { ok: false; status: number; challenge?: Record<string, unknown>; error?: string; payload?: Record<string, unknown>; resource: NibgateResource; response: Response };
+
+export type NibgatePaymentResult =
+  | { ok: true; status: number; payload: Record<string, unknown>; payment: NibgatePayment; resource: NibgateResource; response: Response }
+  | { ok: false; status: number; payload?: Record<string, unknown>; resource: NibgateResource; response: Response };
+
+export type NibgatePaymentSignatureResult =
+  | { ok: true; status: number; payload: Record<string, unknown>; payment: NibgatePayment; resource: NibgateResource; response: Response }
+  | { ok: false; status: number; error?: string; payload?: Record<string, unknown>; resource: NibgateResource; response?: Response };
+
+export type NibgateOnchainRatingOptions = NibgateRating & {
+  provider?: {
+    request(args: { method: string; params?: unknown[] }): Promise<unknown>;
+  };
+  contractAddress?: string;
+  reputationContract?: string;
+  siteDomain?: string;
+  domain?: string;
+  url?: string;
+  contentId?: `0x${string}` | string;
+  unlockRef?: string;
+  review?: string;
+  reviewHash?: string;
+  paymentId?: string;
+  actor?: 'human' | 'agent' | string;
+  source?: string;
+  prepareUrl?: string;
+  indexUrl?: string;
+  indexHeaders?: Record<string, string>;
+  siteId?: string;
+  token?: string;
+};
+
+export type NibgateOnchainRatingResult = {
+  txHash: string;
+  walletAddress: string;
+  contentId: string;
+  ratingValue: number;
+  reviewHash: string;
+};
+
+export type NibgateOnchainRatingUiOptions = NibgateOnchainRatingOptions & {
+  status?: string | HTMLElement | null;
+  ratingTarget?: string | HTMLElement | null;
+  ratingButtons?: string;
+  buttons?: string | HTMLElement | HTMLElement[] | null;
+  payment?: NibgatePayment | null;
+  visible?: boolean;
+  autoMount?: boolean;
+  pendingMessage?: string;
+  successMessage?: string;
+  errorMessage?: string;
+  gateOptions?: NibgateGateOptions;
+  getPaymentId?: () => string | undefined | null;
+  getUnlockRef?: () => string | undefined | null;
+  onStatus?: (message: string) => void;
+  onRated?: (result: NibgateOnchainRatingResult) => void;
+  onError?: (error: unknown) => void;
+};
+
+export type NibgateOnchainRatingController = {
+  resource: NibgateResource;
+  rate(input?: Partial<NibgateOnchainRatingOptions> & { value?: number | string }): Promise<NibgateOnchainRatingResult>;
+  mount(): NibgateOnchainRatingController;
+  setPayment(payment?: NibgatePayment | null): NibgatePayment | null;
+  setVisible(isVisible: boolean): boolean;
+};
+
+export type NibgateContentSettingField = {
+  name: string;
+  label: string;
+  type: 'boolean' | 'select' | 'text' | 'wallet' | 'textarea' | string;
+  options?: readonly string[];
+  defaultValue?: string | boolean;
+};
+export type NibgateContentSettings = {
+  publishToNibgate: boolean;
+  type: NibgateContentType;
+  humanAccess: NibgateAccessMode;
+  agentAccess: NibgateAccessMode;
+  unlockMode: NibgateUnlockMode | string;
+  paymentRail: NibgatePaymentRail | string;
+  price: string;
+  currency: string;
+  recipient: string;
+  license: string;
+};
+export declare const NIBGATE_CONTENT_SETTING_FIELDS: readonly NibgateContentSettingField[];
+export declare function createNibgateContentSettings(input?: Record<string, unknown>): NibgateContentSettings;
+export declare function settingsToAccessPolicy(settings?: Partial<NibgateContentSettings>): Required<Pick<NibgateAccessPolicy, 'humans' | 'agents'>>;
+export declare function settingsToUnlockPolicy(settings?: Partial<NibgateContentSettings>): Required<Pick<NibgateUnlockPolicy, 'mode'>> & NibgateUnlockPolicy;
+
+export declare const PAYMENT_RAILS: readonly ['gateway', 'transfer'];
+export declare function normalizePaymentRail(value?: string, fallback?: NibgatePaymentRail): NibgatePaymentRail;
+export declare const CONTENT_TYPES: readonly ['music', 'video', 'article', 'image'];
+export declare const ACCESS_MODES: readonly ['free', 'paid', 'blocked'];
+export declare const UNLOCK_MODES: readonly ['one_time', 'metered_stream', 'metered_read', 'time_pass', 'agent_quota'];
+export declare function normalizeContentType(type?: string): NibgateContentType;
+export declare function normalizeResource(resource?: NibgateResource | string): NibgateResource;
+export declare function validateResourceMetadata(resource?: NibgateResource | 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;
+export declare function createGate(resource: NibgateResource | string, options?: NibgateGateOptions): NibgateGate;
+export declare const gate: typeof createGate;
+export declare function trackResourcePage(resource: NibgateResource | string, options?: NibgatePageOptions): NibgateGate;
+export declare function checkResourceAccess(resource: NibgateResource | string, options?: NibgateAccessCheckOptions): Promise<NibgateAccessCheckResult>;
+export declare function clearPaymentProof(resource: NibgateResource | string): boolean;
+export declare function payWithPaymentSignature(resource: NibgateResource | string, options?: NibgatePaymentSignatureOptions): Promise<NibgatePaymentSignatureResult>;
+export declare function createWalletCheckout(resource: NibgateResource | string, options: NibgateWalletCheckoutOptions): NibgateWalletCheckoutController;
+export declare function createCircleGatewayBrowserAdapter(options: NibgateCircleGatewayBrowserAdapterOptions): Promise<NibgateCircleGatewayBrowserAdapter>;
+export declare function createEvmGatewayUnlock(resource: NibgateResource | string, options?: NibgateEvmGatewayUnlockOptions): NibgateEvmGatewayUnlockController;
+export declare function payAndUnlockResource(resource: NibgateResource | string, options?: NibgatePaymentOptions): Promise<NibgatePaymentResult>;
+export declare function setupResourcePage(resource: NibgateResource | string, options?: NibgatePageSetupOptions): NibgateGate;
+export declare function rateResource(resource: NibgateResource | string, rating?: NibgateRating | number, extra?: Record<string, unknown>): boolean;
+export declare const NIBGATE_REPUTATION_ABI: readonly unknown[];
+export declare const NIBGATE_CONTENT_HASH_NAMESPACE: 'nibgate:content:v1';
+export declare function contentRatingHash(resource: NibgateResource | string, options?: Record<string, unknown>): string;
+export declare function reviewTextHash(review?: string): string;
+export declare function rateContentOnchain(resource: NibgateResource | string, options: NibgateOnchainRatingOptions): Promise<NibgateOnchainRatingResult>;
+export declare function createOnchainRating(resource: NibgateResource | string, options?: NibgateOnchainRatingUiOptions): NibgateOnchainRatingController;
+export declare function ratingMessage(resource: NibgateResource | string, rating?: NibgateRating | number, options?: Record<string, unknown>): string;
+export declare function createNibgate(defaults?: { resource?: NibgateResource }): NibgateClient;
+export declare const nibgate: NibgateClient;
+
+export declare function createTransferCheckout(resource: NibgateResource | string, options: NibgateTransferCheckoutOptions): NibgateTransferCheckout;
+export declare function payWithTransfer(resource: NibgateResource | string, options: NibgateTransferCheckoutOptions & NibgateAccessCheckOptions): Promise<NibgateAccessCheckResult>;

package/src/index.js

@@ -0,0 +1 @@
+export * from './browser/index.js';

package/src/server/access.js

@@ -0,0 +1,217 @@
+import { normalizePaymentRail } from '../core/payment.js';
+import { normalizeServerResource as normalizeResource } from '../core/resource.js';
+import { actorFromRequest, accessModeFor } from './actor.js';
+import { createPaymentChallenge } from './challenge.js';
+import { jsonResponse } from './response.js';
+import { DEFAULT_UNLOCK_SECONDS, createUnlockToken, verifyUnlockToken } from './proof.js';
+import { createManifest, manifestResponse } from './manifest.js';
+import { emitHubEvent } from './hub.js';
+import { depositToGateway, getGatewayBalances, payWithGateway, runCircleGatewayRequirement, withdrawFromGateway } from './gateway.js';
+import { serverEnv } from './env.js';
+
+export function createNibgateServer(options = {}) {
+  const secret = options.secret || serverEnv('NIBGATE_SECRET') || serverEnv('NIBGATE_UNLOCK_SECRET') || 'nibgate-dev-secret';
+  const verifyPayment = options.verifyPayment || null;
+  const verifyTransfer = options.verifyTransfer || null;
+
+  async function unlock(resourceInput, payment = {}) {
+    const resource = normalizeResource(resourceInput);
+    if (verifyPayment) {
+      const verified = await verifyPayment({ resource, payment });
+      if (!verified) {
+        return { ok: false, status: 402, error: 'Payment verification failed', challenge: createPaymentChallenge(resource, options) };
+      }
+    }
+
+    const unlockProof = createUnlockToken(resource, {
+      secret,
+      paymentId: payment.paymentId || payment.id || '',
+      payment,
+      actor: payment.actor || 'human',
+      expiresInSeconds: payment.expiresInSeconds || options.expiresInSeconds
+    });
+
+    return {
+      ok: true,
+      unlockProof,
+      expiresInSeconds: payment.expiresInSeconds || options.expiresInSeconds || DEFAULT_UNLOCK_SECONDS,
+      resource,
+      payment
+    };
+  }
+
+  function isUnlocked(request, resourceInput, checkOptions = {}) {
+    const resource = normalizeResource(resourceInput);
+    const token = request?.headers?.get?.('x-nibgate-payment-proof') || '';
+    const payload = verifyUnlockToken(token, resource, { secret });
+    if (!payload) return false;
+    if (checkOptions.actor && payload.actor && payload.actor !== checkOptions.actor) return false;
+    return true;
+  }
+
+  function accessFor(request, resourceInput, accessOptions = {}) {
+    const resource = normalizeResource(resourceInput);
+    const actor = accessOptions.actor || actorFromRequest(request, accessOptions.defaultActor || 'human');
+    const mode = accessModeFor(resource, actor);
+    const unlocked = isUnlocked(request, resource, { actor });
+    return {
+      actor,
+      mode,
+      unlocked,
+      allowed: mode === 'free' || unlocked,
+      blocked: mode === 'blocked',
+      paid: mode === 'paid',
+      resource
+    };
+  }
+
+  function protect(resourceInput, handler, routeOptions = {}) {
+    const resource = normalizeResource(resourceInput);
+    return async function protectedHandler(request, context) {
+      const access = accessFor(request, resource, routeOptions);
+      if (access.allowed) {
+        return handler(request, context);
+      }
+
+      if (access.blocked) {
+        return jsonResponse({
+          status: 403,
+          error: `${access.actor} access is blocked for this resource`,
+          nibgate: {
+            contentId: resource.id,
+            actor: access.actor,
+            access: resource.access
+          }
+        }, { status: 403 });
+      }
+
+      const challenge = createPaymentChallenge(resource, { ...options, ...routeOptions, actor: access.actor });
+      return jsonResponse(challenge, { status: 402 });
+    };
+  }
+
+  async function accessResponse(request, resourceInput, allowedBody = null, routeOptions = {}) {
+    const resource = normalizeResource(resourceInput);
+    const access = accessFor(request, resource, routeOptions);
+
+    if (!access.allowed) {
+      if (access.blocked) {
+        return jsonResponse({
+          status: 403,
+          error: `${access.actor} access is blocked for this resource`,
+          resource
+        }, { status: 403 });
+      }
+
+      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') {
+        const gateway = await runCircleGatewayRequirement(request, resource, { ...options, ...routeOptions });
+        if (gateway.handled) return gateway.response;
+        const result = await unlock(resource, gateway.payment);
+        if (result.ok) {
+          return jsonResponse({ ok: true, resource, payment: gateway.payment, unlockProof: result.unlockProof, expiresInSeconds: result.expiresInSeconds });
+        }
+      }
+
+      if (rail === 'transfer') {
+        const txHash = request.headers?.get?.('x-nibgate-transfer-tx') || request.headers?.get?.('x-transfer-tx') || '';
+        if (txHash) {
+          if (!verifyTransfer) {
+            return jsonResponse({ error: 'Transfer verification is not configured', detail: 'Pass verifyTransfer({ resource, txHash, request }) to createNibgateServer/createCircleGatewayServer before using paymentRail: transfer.' }, { status: 501 });
+          }
+          const transferPayment = {
+            paymentProvider: 'direct-transfer',
+            paymentId: txHash,
+            txHash,
+            amount: Number(resource.price || 0),
+            revenue: Number(resource.price || 0),
+            currency: resource.currency || 'USDC',
+            recipient: resource.recipient || resource.payTo || routeOptions.recipient || options.recipient || serverEnv('NIBGATE_SELLER_ADDRESS') || '',
+            network: routeOptions.network || options.network || serverEnv('NIBGATE_PAYMENT_NETWORK') || 'eip155:5042002'
+          };
+          const verified = await verifyTransfer({ resource, txHash, payment: transferPayment, request });
+          if (!verified) return jsonResponse({ error: 'Transfer verification failed' }, { status: 402 });
+          const result = await unlock(resource, { ...transferPayment, verified: true });
+          if (result.ok) return jsonResponse({ ok: true, resource, payment: { ...transferPayment, verified: true }, unlockProof: result.unlockProof, expiresInSeconds: result.expiresInSeconds });
+        }
+      }
+
+      return jsonResponse(createPaymentChallenge(resource, { ...options, ...routeOptions, actor: access.actor, paymentRail: rail }), { status: 402 });
+    }
+
+    const body = typeof allowedBody === 'function'
+      ? allowedBody({ access, resource })
+      : (allowedBody || { ok: true, resource });
+
+    return body instanceof Response ? body : jsonResponse(body);
+  }
+
+  async function payAndUnlockResponse(request, resourceInput, routeOptions = {}) {
+    const resource = normalizeResource(resourceInput);
+    const origin = routeOptions.origin || options.origin || serverEnv('NIBGATE_SITE_ORIGIN') || '';
+    const accessUrl = routeOptions.accessUrl || `${origin.replace(/\/$/, '')}${routeOptions.accessPath || resource.path || '/'}`;
+
+    let payment;
+    if ((routeOptions.paymentMode || options.paymentMode || serverEnv('NIBGATE_PAYMENT_MODE') || 'circle-gateway') === 'circle-gateway') {
+      const gatewayResult = await payWithGateway(resource, { ...options, ...routeOptions, origin, accessUrl });
+      if (!gatewayResult.ok) return jsonResponse(gatewayResult, { status: gatewayResult.status || 500 });
+      payment = gatewayResult.payment;
+    } else {
+      return jsonResponse({
+        success: false,
+        error: 'Real payments are required',
+        detail: 'Set NIBGATE_PAYMENT_MODE=circle-gateway for real local payment tests.'
+      }, { status: 400 });
+    }
+
+    const result = await unlock(resource, payment);
+    if (!result.ok) return jsonResponse({ success: false, ...result }, { status: result.status || 402 });
+
+    const response = jsonResponse({
+      success: true,
+      unlockProof: result.unlockProof,
+      expiresInSeconds: result.expiresInSeconds,
+      payment,
+      resource: result.resource
+    });
+
+    emitHubEvent('payment_completed', resource, {
+      ...options,
+      ...routeOptions,
+      origin,
+      payload: payment
+    }).catch(() => {});
+    emitHubEvent('unlock_completed', resource, {
+      ...options,
+      ...routeOptions,
+      origin,
+      payload: payment
+    }).catch(() => {});
+
+    return response;
+  }
+
+  return {
+    unlock,
+    isUnlocked,
+    accessFor,
+    protect,
+    accessResponse,
+    payAndUnlockResponse,
+    manifest: (input = {}) => createManifest({ ...input, origin: input.origin || options.origin }),
+    manifestResponse: (input = {}) => manifestResponse({ ...input, origin: input.origin || options.origin }),
+    emitHubEvent: (event, resource, eventOptions = {}) => emitHubEvent(event, resource, { ...options, ...eventOptions }),
+    getGatewayBalances: (balanceOptions = {}) => getGatewayBalances({ ...options, ...balanceOptions }),
+    depositToGateway: (amount, depositOptions = {}) => depositToGateway(amount, { ...options, ...depositOptions }),
+    withdrawFromGateway: (amount, withdrawOptions = {}) => withdrawFromGateway(amount, { ...options, ...withdrawOptions }),
+    createPaymentChallenge: (resource, challengeOptions = {}) => createPaymentChallenge(resource, { ...options, ...challengeOptions }),
+    createUnlockToken: (resource, tokenOptions = {}) => createUnlockToken(resource, { ...tokenOptions, secret }),
+    verifyUnlockToken: (token, resource) => verifyUnlockToken(token, resource, { secret }),
+    actorFromRequest,
+    accessModeFor
+  };
+}
+
+export function protect(resource, handler, options = {}) {
+  return createNibgateServer(options).protect(resource, handler);
+}

package/src/server/actor.js

@@ -0,0 +1,23 @@
+import { normalizeAccessPolicy, normalizeServerResource as normalizeResource } from '../core/resource.js';
+
+export function actorFromRequest(request, fallback = 'human') {
+  const explicit = request?.headers?.get?.('x-nibgate-actor') || request?.headers?.get?.('x-actor');
+  if (explicit && String(explicit).toLowerCase() === 'agent') return 'agent';
+  if (explicit && String(explicit).toLowerCase() === 'human') return 'human';
+
+  const accept = request?.headers?.get?.('accept') || '';
+  if (accept.includes('application/json') && request?.headers?.get?.('x402') === 'true') return 'agent';
+
+  const userAgent = (request?.headers?.get?.('user-agent') || '').toLowerCase();
+  if (/(bot|crawler|spider|agent|llm|gpt|claude|perplexity|anthropic|openai|mistral|gemini|firecrawl)/i.test(userAgent)) {
+    return 'agent';
+  }
+
+  return fallback;
+}
+
+export function accessModeFor(resourceInput, actor = 'human') {
+  const resource = normalizeResource(resourceInput);
+  const access = normalizeAccessPolicy(resource.access);
+  return actor === 'agent' ? access.agents : access.humans;
+}