@gbitx/pay-react-native 0.1.0

package/src/types.ts

@@ -0,0 +1,99 @@
+// Public type surface for @gbitx/pay-react-native.
+//
+// This module is deliberately free of any react-native import so the core
+// (types + validation + config + message parsing) stays testable in plain
+// Node and safe to import anywhere.
+
+export type Environment = 'live' | 'test';
+
+// Mirrors the server PaymentStatus enum (gatewayService prisma schema).
+export type PaymentStatus =
+  | 'PENDING'
+  | 'AWAITING_PAYMENT'
+  | 'UNDERPAID'
+  | 'CONFIRMING'
+  | 'CONFIRMED'
+  | 'EXPIRED'
+  | 'FAILED'
+  | 'CANCELLED';
+
+// EXACTLY the fields the hosted checkout emits via serializePayment
+// (gbitxpay-frontend/src/pages/PaymentPage.jsx). `address`, `txHash`,
+// `cancelToken`, and `externalRef` are intentionally absent: the page
+// strips them, and an app must never believe it can read on-chain or
+// private fields client-side. Amounts arrive as decimal-safe strings.
+export interface SanitizedPayment {
+  id: string;
+  status: PaymentStatus;
+  amount: string;
+  currency: string;
+  crypto: string | null;
+  network: string | null;
+  amountCrypto: string | null;
+  amountPaid: string | null;
+  mode: 'LIVE' | 'SANDBOX';
+  confirmedAt: string | null;
+  expiresAt: string;
+}
+
+// Why a checkout ended without a confirmation. UX/analytics only.
+export type CancelReason = 'user_closed' | 'dismissed' | 'back_button' | 'load_failed';
+export type ExpiredReason = 'expired' | 'client_backstop';
+
+// The terminal outcome of a checkout session. This is NOT an error — a
+// cancelled or expired payment is a normal, expected result. `payment` is
+// populated in practice for confirmed checkouts (the page always sends it)
+// but is typed nullable because a bridge message is device-controllable and
+// UX-only: fulfilment is driven by the signed server webhook, never by this.
+export type PaymentResult =
+  | { status: 'confirmed'; payment: SanitizedPayment | null }
+  | { status: 'cancelled'; reason?: CancelReason; payment?: SanitizedPayment | null }
+  | { status: 'expired'; reason?: ExpiredReason; payment?: SanitizedPayment | null }
+  | { status: 'failed'; payment?: SanitizedPayment | null };
+
+export interface ConfigureOptions {
+  // The merchant's PUBLISHABLE key (pk_live_… / pk_test_…). Safe to embed.
+  publishableKey: string;
+  // Optional assertion. If set it must match BOTH the key prefix and the
+  // server's reported environment, else configure() rejects with
+  // 'environment_mismatch'.
+  environment?: Environment;
+  // Bounded timeout (ms) for the GET /v1/sdk/config validation call.
+  // Default 10_000.
+  timeoutMs?: number;
+  // Override the GbitX API base (default https://gateway.gbitx.com). Must be
+  // https. For staging/testing only — never point this at an untrusted host.
+  apiBaseUrl?: string;
+  // Enable redacted debug logging (never prints a key/token/full URL).
+  debug?: boolean;
+}
+
+// Non-sensitive merchant info resolved at configure() time.
+export interface MerchantInfo {
+  name: string;
+  website: string | null;
+}
+
+export type CheckoutEventType =
+  | 'loaded'
+  | 'confirmed'
+  | 'cancelled'
+  | 'expired'
+  | 'failed'
+  | 'closed';
+
+export interface CheckoutEvent {
+  type: CheckoutEventType;
+  payment?: SanitizedPayment;
+}
+
+export interface PresentOptions {
+  // From YOUR server's POST /v1/payments response (id + clientToken). The
+  // app never creates payments; your server does, with the SECRET key.
+  paymentId: string;
+  clientToken: string;
+  // Optional progress callbacks (UX only). onLoaded fires at most once when
+  // the checkout is interactive; onEvent streams every bridge lifecycle event.
+  onLoaded?: () => void;
+  onEvent?: (event: CheckoutEvent) => void;
+}

package/src/useGbitXPay.ts

@@ -0,0 +1,16 @@
+import { useMemo } from 'react';
+import { configure } from './config';
+import { present } from './controller';
+import type { ConfigureOptions, PresentOptions, PaymentResult } from './types';
+
+export interface UseGbitXPay {
+  configure: (options: ConfigureOptions) => Promise<void>;
+  present: (options: PresentOptions) => Promise<PaymentResult>;
+}
+
+// Hook flavor of the API for components that prefer it. Thin, stable wrapper
+// over the same singleton — configure/present are module-level, so this holds
+// no state of its own; the identity is memoized for dependency arrays.
+export function useGbitXPay(): UseGbitXPay {
+  return useMemo(() => ({ configure, present }), []);
+}

package/src/validation.ts

@@ -0,0 +1,78 @@
+import { GbitXPayError } from './errors';
+import type { Environment } from './types';
+
+// A publishable key: pk_{live|test}_ + 32 random bytes hex (256-bit), exactly
+// matching generateApiKey() in gatewayService/src/utils/crypto.js.
+const PUBLISHABLE_KEY_RE = /^pk_(live|test)_[0-9a-f]{64}$/;
+
+// paymentId is a cuid from Prisma (@default(cuid())): url-safe, no
+// slash/dot/whitespace. We reject anything that could rewrite the URL
+// path/query/fragment rather than relying on encoding alone.
+const PAYMENT_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+
+// clientToken is the payment cancelToken (crypto.randomBytes(16).hex = 32 hex
+// chars today). Kept a bounded alphanumeric charset so it can never carry
+// control chars into the URL fragment; permissive on length for future-proofing.
+const CLIENT_TOKEN_RE = /^[A-Za-z0-9]{16,128}$/;
+
+// Validate the publishable key BEFORE any network call. A secret key gets its
+// own security-flavored error so an integrator immediately pulls it out of the
+// binary. The key value is NEVER included in an error message.
+export function assertPublishableKey(publishableKey: unknown): { key: string; environment: Environment } {
+  if (typeof publishableKey !== 'string' || publishableKey.trim() === '') {
+    throw new GbitXPayError('invalid_key', 'A publishableKey string is required.');
+  }
+  const key = publishableKey.trim();
+  if (key.startsWith('gk_')) {
+    throw new GbitXPayError(
+      'secret_key_used',
+      'A SECRET key (gk_) was passed to the SDK. Use a publishable key (pk_) only, and remove the secret key from your app immediately.',
+    );
+  }
+  if (!PUBLISHABLE_KEY_RE.test(key)) {
+    throw new GbitXPayError('invalid_key', 'publishableKey must look like pk_live_… or pk_test_….');
+  }
+  const environment: Environment = key.startsWith('pk_live_') ? 'live' : 'test';
+  return { key, environment };
+}
+
+// Validate present() arguments BEFORE building any URL or presenting anything.
+export function assertPaymentArgs(
+  paymentId: unknown,
+  clientToken: unknown,
+): { paymentId: string; clientToken: string } {
+  const id = typeof paymentId === 'string' ? paymentId.trim() : '';
+  const token = typeof clientToken === 'string' ? clientToken.trim() : '';
+  if (!PAYMENT_ID_RE.test(id)) {
+    throw new GbitXPayError('invalid_arguments', 'paymentId is missing or malformed.');
+  }
+  if (!CLIENT_TOKEN_RE.test(token)) {
+    throw new GbitXPayError('invalid_arguments', 'clientToken is missing or malformed.');
+  }
+  return { paymentId: id, clientToken: token };
+}
+
+// Assert an https origin and return its canonical origin form. Used for both
+// the API base and the server-returned checkout base.
+export function assertHttpsOrigin(raw: unknown, label: string): string {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new GbitXPayError('invalid_arguments', `${label} is required.`);
+  }
+  let u: URL;
+  try {
+    u = new URL(raw.trim());
+  } catch {
+    throw new GbitXPayError('invalid_arguments', `${label} is not a valid URL.`);
+  }
+  if (u.protocol !== 'https:') {
+    throw new GbitXPayError('invalid_arguments', `${label} must be https.`);
+  }
+  return u.origin;
+}
+
+// Build the checkout URL. Args are pre-validated; we still encodeURIComponent
+// as belt-and-suspenders. The clientToken rides in the fragment (#t=) exactly
+// like POST /v1/payments returns, so the page's existing hash-capture works.
+export function buildCheckoutUrl(checkoutOrigin: string, paymentId: string, clientToken: string): string {
+  return `${checkoutOrigin}/p/${encodeURIComponent(paymentId)}?embed=native#t=${encodeURIComponent(clientToken)}`;
+}

package/src/version.ts

@@ -0,0 +1,4 @@
+// Single source of truth for the SDK version. Surfaced in the WebView
+// userAgent suffix (never with any credential appended) for abuse
+// throttling and analytics. Keep in sync with package.json "version".
+export const SDK_VERSION = '0.1.0';

package/src/webviewPolicy.ts

@@ -0,0 +1,55 @@
+// Pure, unit-testable WebView security policy — the exact origin decisions the
+// SDK's trust rests on. Kept free of any react-native import so it can be
+// tested in Node and so the decisions are auditable in isolation.
+//
+// EXACT origin equality everywhere (never startsWith / includes). The library's
+// own `originWhitelist` prop is a *prefix* match (unanchored regex), so
+// `https://pay.gbitx.com` there would also match `https://pay.gbitx.com.evil.com`
+// and `https://pay.gbitx.company`. We therefore set originWhitelist to ['*'] in
+// the component and make THIS module the single authoritative gate.
+
+function parse(url: unknown): URL | null {
+  if (typeof url !== 'string' || url === '') return null;
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+
+// May a navigation load inside the WebView? In native embed mode the checkout
+// is fully self-contained — it performs NO off-origin navigation and uses NO
+// wallet deep-links (verified against PaymentPage.jsx: redirects are suppressed
+// and "return to merchant" links are swapped for close buttons). So the only
+// thing allowed to load is the pinned checkout origin over https; everything
+// else is blocked and opened nowhere (no Linking), removing the "a compromised
+// page force-opens an external URL / deep-link" vector entirely.
+export function mayLoadInWebView(checkoutOrigin: string, url: unknown): boolean {
+  const u = parse(url);
+  return !!u && u.protocol === 'https:' && u.origin === checkoutOrigin;
+}
+
+// Is a URL the pinned checkout origin over https? EXACT origin, NO path clause.
+// Used to validate the per-message authenticated sender URL, whose shape differs
+// by platform: on iOS react-native-webview reports the full frame URL, but on
+// Android it reports the sender ORIGIN only (no path). Requiring a /p/ path here
+// would reject every legitimate Android message. The /p/ path is instead asserted
+// on the committed top-frame URL (isTrustedMessageSource) — exactly how the iOS
+// native SDK splits frameInfo.securityOrigin (origin) from the committed URL (path).
+//
+// Caveat vs the native SDKs: on react-native-webview's Android path this URL is the
+// TOP-frame value, not a per-frame authenticated sender origin, so it cannot by
+// itself isolate a sub-frame. That residual is covered by the hosted page's CSP
+// (frame-src 'none' blocks injected iframes) plus the page shipping no iframes.
+export function isTrustedMessageOrigin(checkoutOrigin: string, url: unknown): boolean {
+  const u = parse(url);
+  return !!u && u.protocol === 'https:' && u.origin === checkoutOrigin;
+}
+
+// Is a URL the pinned origin over https AND on a payment path (/p/...)? Applied to
+// the committed top-frame URL (from onNavigationStateChange), which always carries
+// the full path. This is the native mirror of the page's own embed-origin boundary.
+export function isTrustedMessageSource(checkoutOrigin: string, url: unknown): boolean {
+  const u = parse(url);
+  return !!u && u.protocol === 'https:' && u.origin === checkoutOrigin && u.pathname.startsWith('/p/');
+}