@spare-technologies/spare-link 0.1.0-beta.0 → 1.0.0

package/src/internal/hosted/bridge-message.ts

@@ -0,0 +1,106 @@
+import { parseUrlParts } from '../url-parts';
+
+/**
+ * Messages the hosted payment page sends to this SDK.
+ *
+ * The contract is one-way. The page never waits on a reply, so a message this
+ * version does not recognise is dropped rather than treated as a failure — the
+ * page continues, and a newer page stays usable by an older app.
+ *
+ * The page posts to `window.ReactNativeWebView.postMessage` as a JSON string,
+ * which arrives here as `event.nativeEvent.data`.
+ */
+export type HostedBridgeMessage = HostedReady | HostedOpenUrl | HostedCancel | HostedError;
+
+/** The payable page is interactive. */
+export interface HostedReady {
+  readonly type: 'ready';
+}
+
+/**
+ * A consent exists and the bank must now be opened outside the WebView.
+ *
+ * Banks commonly refuse to serve their authorization pages inside an embedded
+ * browser, and the address bar is what lets a payer tell a real bank page from
+ * a convincing copy.
+ */
+export interface HostedOpenUrl {
+  readonly type: 'openUrl';
+  readonly url: string;
+}
+
+/** The payer cancelled, and the request is already rejected server-side. */
+export interface HostedCancel {
+  readonly type: 'cancel';
+}
+
+/** The flow cannot continue. [code] is the key the page itself renders. */
+export interface HostedError {
+  readonly type: 'error';
+  readonly code: string;
+}
+
+/**
+ * Parses a message posted by the hosted page.
+ *
+ * Returns null for anything unrecognised. The message crosses a boundary the
+ * SDK does not control, so nothing here trusts its shape — the WebView message
+ * channel is shared with every script on the page.
+ */
+export function parseHostedBridgeMessage(raw: unknown): HostedBridgeMessage | null {
+  const message = asRecord(raw);
+  if (!message) return null;
+
+  const type = message.type;
+  if (typeof type !== 'string') return null;
+
+  switch (type) {
+    case 'spare.ready':
+      return { type: 'ready' };
+    case 'spare.open_url': {
+      const url = message.url;
+      if (typeof url !== 'string' || !isHttpsUrl(url)) return null;
+      return { type: 'openUrl', url };
+    }
+    case 'spare.cancel':
+      return { type: 'cancel' };
+    case 'spare.error': {
+      const code = message.code;
+      if (typeof code !== 'string' || code.trim().length === 0) return null;
+      return { type: 'error', code };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Reads the message out of whatever the WebView handed over.
+ *
+ * The page stringifies its payload, but a plain object is accepted too so the
+ * transport is not the thing that decides whether a valid message is understood.
+ */
+function asRecord(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw === 'string') {
+    try {
+      return asRecord(JSON.parse(raw) as unknown);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return null;
+  return raw as Record<string, unknown>;
+}
+
+/**
+ * Whether [url] is an absolute https URL.
+ *
+ * Required before handing a URL to the OS browser: the page is trusted to name
+ * a bank, not to name a scheme that could reach something else on the device.
+ * Parsed rather than pattern-matched so `https:/\/evil` and friends cannot pass
+ * for an absolute URL.
+ */
+function isHttpsUrl(url: string): boolean {
+  const parts = parseUrlParts(url);
+  return parts !== null && parts.scheme === 'https' && parts.host.length > 0;
+}

package/src/internal/hosted/hosted-url.ts

@@ -0,0 +1,33 @@
+import { isSameOrigin } from '../url-parts';
+
+/**
+ * Origin channel this SDK identifies as to the hosted page.
+ *
+ * The same value must be recorded on the payment request by the merchant's
+ * backend, because the bank redirect that completes a payment carries no query
+ * string of ours and the return path is decided from the stored row.
+ */
+export const HOSTED_ORIGIN_CHANNEL = 'sdk_react_native';
+
+/**
+ * Builds the hosted payment page URL for a payment request reference.
+ *
+ * The reference is the only credential the page needs; everything else is
+ * resolved server-side from the row it names.
+ */
+export function buildHostedPaymentUrl(args: { baseUrl: string; reference: string }): string {
+  const base = args.baseUrl.trim().replace(/\/+$/, '');
+  const reference = encodeURIComponent(args.reference.trim());
+  return `${base}/link/payment/${reference}?channel=${HOSTED_ORIGIN_CHANNEL}`;
+}
+
+/**
+ * Whether [url] belongs to the hosted origin derived from [baseUrl].
+ *
+ * The WebView loads only the hosted origin. Bank authentication deliberately
+ * happens outside it, so anything else navigating in-frame is refused rather
+ * than followed.
+ */
+export function isHostedOriginUrl(args: { baseUrl: string; url: string }): boolean {
+  return isSameOrigin(args.baseUrl, args.url);
+}

package/src/internal/index.ts

@@ -1,4 +1,3 @@
-export { collectTelemetry } from './telemetry-collector';
 export { launchBankRedirect, type BankRedirectArgs } from './bank-redirect';
 export { SecureStorePendingSessionStore } from './secure-store-pending-session-store';
 export { useSpareLinkDeepLinks } from './deep-link-listener';

package/src/internal/redact-uri.ts

@@ -1,18 +1,72 @@
-const SENSITIVE_QUERY_KEYS = new Set(['exchange_code', 'error_description']);
+/**
+ * Redacts the query of a bank-return URI before it is logged.
+ *
+ * Every value goes except the few that describe the outcome rather than identify
+ * anyone — see {@link KEPT_KEYS}. Redaction is a denylist by default rather than
+ * an allowlist of names to remove: an earlier version named the two keys to
+ * redact, so anything else the return ever carried was logged in full, and one of
+ * the names it knew (`exchange_code`) is not even in the contract any more.
+ *
+ * What is worth keeping in a log is the shape of the URI — its scheme, its path,
+ * which parameters were present — plus enough to explain the outcome.
+ *
+ * It also cannot use the global `URL`. React Native's is a stub whose
+ * `searchParams` returns a fresh empty instance, so `has()` was always false and
+ * this function returned the URI untouched on a device while redacting correctly
+ * under Jest, which runs on Node.
+ *
+ * The query is split here rather than read through `parseQueryParams`, because
+ * that decodes values and keeps only the first of a repeated key — fine for
+ * reading an outcome, wrong for reproducing a URI whose shape is the point.
+ */
+
+const REDACTED = '[REDACTED]';
+
+/**
+ * Parameters whose values are kept, because they say what happened rather than to
+ * whom.
+ *
+ * Redacting these made the log useless for the one question it gets asked. A
+ * return that resolves as unresolved does so because of its `status`, and a log
+ * reading `status=[REDACTED]` cannot tell anyone which value was not recognised.
+ *
+ * None of these identifies a payer, a payment or a request: `status` is one of a
+ * fixed vocabulary, and `errorCode` and `error` are keys from a fixed list. The
+ * identifiers — `reference`, `merchantRef`, `paymentId` — and the signature stay
+ * redacted, as does `error_description`, which is prose and could name a person.
+ */
+const KEPT_KEYS: ReadonlySet<string> = new Set(['status', 'errorCode', 'error']);
 
-/** Redacts sensitive query params before logging bank-return URIs. */
 export function redactPaymentReturnUri(uri: string): string {
-  try {
-    const parsed = new URL(uri);
-    let changed = false;
-    for (const key of SENSITIVE_QUERY_KEYS) {
-      if (parsed.searchParams.has(key)) {
-        parsed.searchParams.set(key, '[REDACTED]');
-        changed = true;
-      }
-    }
-    return changed ? parsed.toString() : uri;
-  } catch {
-    return '[invalid-uri]';
-  }
+  const queryStart = uri.indexOf('?');
+  const fragmentStart = uri.indexOf('#');
+
+  // No query and no fragment: nothing here carries a value.
+  if (queryStart === -1 && fragmentStart === -1) return uri;
+
+  const queryEnd = fragmentStart !== -1 && fragmentStart > queryStart ? fragmentStart : uri.length;
+
+  const beforeQuery = queryStart === -1 ? uri.slice(0, fragmentStart) : uri.slice(0, queryStart);
+  const query = queryStart === -1 ? '' : uri.slice(queryStart + 1, queryEnd);
+
+  // A fragment is dropped whole. Nothing in this SDK reads one, so its shape is
+  // not worth keeping, and a return that ever carried a token in one — as OAuth
+  // implicit flows do — must not put it in a log.
+  const hadFragment = fragmentStart !== -1;
+
+  const redactedQuery = query
+    .split('&')
+    .filter((pair) => pair.length > 0)
+    .map((pair) => {
+      const eq = pair.indexOf('=');
+      const key = eq === -1 ? pair : pair.slice(0, eq);
+      if (KEPT_KEYS.has(key)) return pair;
+      return `${key}=${REDACTED}`;
+    })
+    .join('&');
+
+  const rebuiltQuery = redactedQuery.length > 0 ? `?${redactedQuery}` : '';
+  const rebuiltFragment = hadFragment ? `#${REDACTED}` : '';
+
+  return `${beforeQuery}${rebuiltQuery}${rebuiltFragment}`;
 }

package/src/internal/secure-store-pending-session-store.ts

@@ -1,6 +1,7 @@
 /**
- * Production `PendingSessionStore` backed by expo-secure-store. Persists a
- * single in-flight payment session so the SDK can recover after cold start.
+ * Production `PendingSessionStore` backed by expo-secure-store. Persists the
+ * reference of a single in-flight payment so a cold start knows which payment
+ * was under way.
  */
 
 import type { PendingSessionRecord } from '../core/models';
@@ -9,14 +10,24 @@ import { createLogger } from './logger';
 
 const log = createLogger('SecureStorePendingSessionStore');
 
-const KEYS = {
-  sessionId: 'spare_link_session_id',
-  bankId: 'spare_link_bank_id',
-  authUrl: 'spare_link_auth_url',
-  consentAt: 'spare_link_consent_at',
-  recoveryAttempts: 'spare_link_recovery_attempts',
-  merchantRef: 'spare_link_merchant_ref',
-} as const;
+const KEY_REFERENCE = 'spare_link_reference';
+
+/**
+ * Keys earlier versions wrote, cleared alongside our own.
+ *
+ * An app upgrading mid-payment would otherwise keep a token and session it can
+ * never resolve — the endpoints they addressed are gone — and the secure store
+ * outlives the version that wrote to it.
+ */
+const RETIRED_KEYS = [
+  'spare_link_token',
+  'spare_link_session_id',
+  'spare_link_bank_id',
+  'spare_link_auth_url',
+  'spare_link_consent_at',
+  'spare_link_recovery_attempts',
+  'spare_link_merchant_ref',
+] as const;
 
 export interface SecureStoreModule {
   getItemAsync(key: string): Promise<string | null>;
@@ -71,18 +82,7 @@ export class SecureStorePendingSessionStore implements PendingSessionStore {
   save(record: PendingSessionRecord): Promise<void> {
     return this.enqueueWrite(async () => {
       const s = await this.module;
-      await Promise.all([
-        s.setItemAsync(KEYS.sessionId, record.sessionId),
-        s.setItemAsync(KEYS.bankId, record.selectedBankId),
-        s.setItemAsync(KEYS.authUrl, record.authorizationUrl),
-        record.consentAt !== undefined
-          ? s.setItemAsync(KEYS.consentAt, String(record.consentAt))
-          : s.deleteItemAsync(KEYS.consentAt),
-        s.setItemAsync(KEYS.recoveryAttempts, String(record.recoveryAttempts)),
-        record.merchantRef
-          ? s.setItemAsync(KEYS.merchantRef, record.merchantRef)
-          : s.deleteItemAsync(KEYS.merchantRef),
-      ]);
+      await s.setItemAsync(KEY_REFERENCE, record.reference);
     });
   }
 
@@ -90,41 +90,20 @@ export class SecureStorePendingSessionStore implements PendingSessionStore {
     // Wait for any pending writes to settle so we read a consistent snapshot.
     await this.writeQueue.catch(() => undefined);
     const s = await this.module;
-    const [sessionId, bankId, authUrl, consentAtRaw, attemptsRaw, merchantRef] = await Promise.all([
-      s.getItemAsync(KEYS.sessionId),
-      s.getItemAsync(KEYS.bankId),
-      s.getItemAsync(KEYS.authUrl),
-      s.getItemAsync(KEYS.consentAt),
-      s.getItemAsync(KEYS.recoveryAttempts),
-      s.getItemAsync(KEYS.merchantRef),
-    ]);
-    if (!sessionId || !bankId || !authUrl) {
-      log.fine('load: no pending session found');
+    const reference = await s.getItemAsync(KEY_REFERENCE);
+    if (!reference) {
+      log.fine('load: no pending payment found');
       return null;
     }
-    const consentAt = consentAtRaw ? Number(consentAtRaw) : undefined;
-    const recoveryAttempts = attemptsRaw ? Number(attemptsRaw) : 0;
-    const record: PendingSessionRecord = {
-      sessionId,
-      selectedBankId: bankId,
-      authorizationUrl: authUrl,
-      recoveryAttempts: Number.isFinite(recoveryAttempts) ? recoveryAttempts : 0,
-    };
-    if (consentAt !== undefined && Number.isFinite(consentAt)) record.consentAt = consentAt;
-    if (merchantRef) record.merchantRef = merchantRef;
-    return record;
+    return { reference };
   }
 
   clear(): Promise<void> {
     return this.enqueueWrite(async () => {
       const s = await this.module;
       await Promise.all([
-        s.deleteItemAsync(KEYS.sessionId),
-        s.deleteItemAsync(KEYS.bankId),
-        s.deleteItemAsync(KEYS.authUrl),
-        s.deleteItemAsync(KEYS.consentAt),
-        s.deleteItemAsync(KEYS.recoveryAttempts),
-        s.deleteItemAsync(KEYS.merchantRef),
+        s.deleteItemAsync(KEY_REFERENCE),
+        ...RETIRED_KEYS.map((key) => s.deleteItemAsync(key)),
       ]);
     });
   }

package/src/internal/url-parts.ts

@@ -0,0 +1,134 @@
+/**
+ * Minimal URL parsing that does not go through the global `URL`.
+ *
+ * React Native ships a stub: every component accessor — `protocol`, `hostname`,
+ * `port`, `origin`, `search`, `pathname` — throws "not implemented", and
+ * `searchParams` returns a fresh empty instance that never reads the URL it was
+ * constructed from (`react-native/Libraries/Blob/URL.js`, installed globally by
+ * `setUpXHR.js`). Code written against the standard therefore behaves correctly
+ * under Jest, which runs on Node's real `URL`, and silently reads nothing on a
+ * device.
+ *
+ * The SDK parses what it needs itself rather than asking the host app to install
+ * a polyfill whose presence it cannot verify — an origin check that quietly
+ * stops comparing hosts is worse than one that was never written.
+ */
+
+/** The parts of a URL this SDK compares origins on. */
+export interface UrlParts {
+  /** Lower-cased, without the trailing colon. */
+  scheme: string;
+  /** Lower-cased host, without userinfo. IPv6 hosts keep their brackets. */
+  host: string;
+  /** The explicit port, or the scheme's default where it has one. */
+  port: number | undefined;
+}
+
+/** Scheme plus authority. Anything without an authority has no origin to compare. */
+const SCHEME_AND_AUTHORITY = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)/;
+
+const DEFAULT_PORTS: Readonly<Record<string, number>> = { http: 80, https: 443 };
+
+/**
+ * Splits [url] into the parts an origin comparison needs, or null if it has no
+ * authority to compare.
+ */
+export function parseUrlParts(url: string): UrlParts | null {
+  const match = SCHEME_AND_AUTHORITY.exec(url.trim());
+  if (!match?.[1] || match[2] === undefined) return null;
+
+  const scheme = match[1].toLowerCase();
+
+  // Everything up to the last `@` is userinfo, not host. `https://api.real.example@evil.example`
+  // is a request to evil.example, and reading the left half would accept it as the real one.
+  const authority = match[2].slice(match[2].lastIndexOf('@') + 1);
+
+  const hostAndPort = splitHostAndPort(authority);
+  if (!hostAndPort) return null;
+
+  const { host, portText } = hostAndPort;
+  if (host.length === 0) return null;
+
+  // An empty port (`https://host:/x`) means the scheme's default, as does no port.
+  if (portText === undefined || portText.length === 0) {
+    return { scheme, host: host.toLowerCase(), port: DEFAULT_PORTS[scheme] };
+  }
+
+  if (!/^\d+$/.test(portText)) return null;
+  const port = Number.parseInt(portText, 10);
+  if (port > 65535) return null;
+
+  return { scheme, host: host.toLowerCase(), port };
+}
+
+/**
+ * Whether two URLs share a scheme, host and port.
+ *
+ * Both must carry an authority, so a relative path never matches an absolute
+ * URL: `/link/payment/x` names no origin and must not be read as naming this one.
+ */
+export function isSameOrigin(a: string, b: string): boolean {
+  const left = parseUrlParts(a);
+  const right = parseUrlParts(b);
+  if (!left || !right) return false;
+  return left.scheme === right.scheme && left.host === right.host && left.port === right.port;
+}
+
+/**
+ * Reads the query string of [url] into a plain object.
+ *
+ * The first occurrence of a repeated key wins, matching `URLSearchParams.get`.
+ * A value the SDK cannot decode is kept in its raw form rather than dropping the
+ * parameter: callers compare against known literals, and a mangled value should
+ * fail that comparison rather than read as absent.
+ */
+export function parseQueryParams(url: string): Record<string, string> {
+  const params: Record<string, string> = {};
+
+  const start = url.indexOf('?');
+  if (start === -1) return params;
+
+  const fragment = url.indexOf('#', start);
+  const query = fragment === -1 ? url.slice(start + 1) : url.slice(start + 1, fragment);
+
+  for (const pair of query.split('&')) {
+    if (pair.length === 0) continue;
+    const eq = pair.indexOf('=');
+    const rawKey = eq === -1 ? pair : pair.slice(0, eq);
+    const rawValue = eq === -1 ? '' : pair.slice(eq + 1);
+
+    const key = decodeFormComponent(rawKey);
+    if (key.length === 0 || Object.hasOwn(params, key)) continue;
+    params[key] = decodeFormComponent(rawValue);
+  }
+
+  return params;
+}
+
+function splitHostAndPort(
+  authority: string,
+): { host: string; portText: string | undefined } | null {
+  // An IPv6 literal carries colons of its own, so its brackets close the host.
+  if (authority.startsWith('[')) {
+    const close = authority.indexOf(']');
+    if (close === -1) return null;
+    const host = authority.slice(0, close + 1);
+    const rest = authority.slice(close + 1);
+    if (rest.length === 0) return { host, portText: undefined };
+    if (!rest.startsWith(':')) return null;
+    return { host, portText: rest.slice(1) };
+  }
+
+  const colon = authority.indexOf(':');
+  if (colon === -1) return { host: authority, portText: undefined };
+  return { host: authority.slice(0, colon), portText: authority.slice(colon + 1) };
+}
+
+function decodeFormComponent(value: string): string {
+  const plusesAsSpaces = value.replace(/\+/g, ' ');
+  try {
+    return decodeURIComponent(plusesAsSpaces);
+  } catch {
+    return plusesAsSpaces;
+  }
+}

package/src/public/index.ts

@@ -2,11 +2,9 @@ export {
   type PaymentEnvironment,
   type SpareApiTenant,
   type SpareLinkConfig,
-  type SpareLinkResumeConfig,
   defaultBaseUrlFor,
   tenantCountryCode,
   resolvedBaseUrl,
-  resolvedResumeBaseUrl,
   assertValidConfig,
 } from './spare-link-config';
 
@@ -14,8 +12,7 @@ export {
   type SpareLinkEvent,
   type SpareLinkEventType,
   type SpareLinkInitialized,
-  type SpareLinkSessionLoaded,
-  type SpareLinkConsentStarted,
+  type SpareLinkPageReady,
   type SpareLinkRedirectToBank,
   type SpareLinkBankCallbackReceived,
   type SpareLinkSucceeded,
@@ -40,36 +37,17 @@ export {
   paymentAbandoned,
 } from './payment-result';
 
-export type {
-  SpareLinkCallbacks,
-  SpareLinkSuccessCallback,
-  SpareLinkExitCallback,
-  SpareLinkEventCallback,
-} from './spare-link-callbacks';
-
 export type {
   RecoveryResult,
   NoRecoveryReason,
   NoRecoveryNeeded,
   SessionRecovered,
-  RecoveryAwaitingUser,
-} from './recovery-result';
-export {
-  isSessionRecovered,
-  isNoRecoveryNeeded,
-  isRecoveryAwaitingUser,
 } from './recovery-result';
+export { isSessionRecovered, isNoRecoveryNeeded } from './recovery-result';
 
 export { SpareLinkSession } from './spare-link-session';
 export { SpareLink, type SpareLinkOptions } from './spare-link-instance';
 
-export {
-  kMaxRecoveryAttempts,
-  DEFAULT_REQUEST_TIMEOUT_MS,
-  DEFAULT_AWAITING_CALLBACK_TIMEOUT_MS,
-  DEFAULT_AWAITING_CALLBACK_POLL_MS,
-} from './constants';
-
 export {
   configureSpareLinkLogging,
   createLogger,

package/src/public/payment-result.ts

@@ -1,28 +1,61 @@
 /**
  * Terminal outcome of a payment flow — narrow on the `status` field.
+ *
+ * Every result here is read off a deep link, which is interceptable by design
+ * and names no bank identifiers. It reports what happened rather than attesting
+ * to it: confirm with your backend via `GET /payment-requests/{reference}`
+ * before acting on one.
  */
 export type PaymentStatus = 'success' | 'cancelled' | 'failed' | 'abandoned';
 
 interface PaymentResultBase {
   status: PaymentStatus;
-  /** The `link_token` JWS that identifies this payment flow. Mirrors Flutter's `linkToken`. */
-  linkToken: string;
-  bankId?: string;
-  linkSessionId?: string;
+  /** The payment request this flow was paying, and what your backend reads the
+   *  authoritative result by. */
+  reference: string;
+  /** The merchant's own reference for the attempt, when the return named one. */
+  merchantRef?: string;
+  /**
+   * Spare's identifier for the payment, present on a reported success.
+   *
+   * Distinct from `reference`, which names the request. This is what an order
+   * records.
+   */
+  paymentId?: string;
+  /**
+   * Spare's identifier for a mandate, present when the flow created one.
+   *
+   * A return names a payment or a mandate, never both. Read whichever is set
+   * rather than assuming which the flow produced.
+   */
+  mandateId?: string;
+  /**
+   * The return's signature: an ES256 JWS whose payload is the return URL, every
+   * parameter included.
+   *
+   * The only part of the return that cannot be forged. Verify it against Spare's
+   * public key on your backend before acting on the outcome — the SDK holds no
+   * keys and passes it through unchecked.
+   */
+  signature?: string;
+  /**
+   * The machine-readable reason a payment did not complete, e.g. `user_cancelled`.
+   *
+   * Alongside `errorCode`, which is often generic where this is not.
+   */
+  errorReason?: string;
   message?: string;
   errorCode?: string;
   resolvedAtMs?: number;
 }
 
-/** Payment completed at the bank. `exchangeCode` may be null when recovered
- * via status polling (the bank delivered the code straight to the merchant
- * backend, bypassing the SDK). */
+/**
+ * The return reported a completed payment.
+ *
+ * Treat this as a prompt to confirm with your backend, not as settlement.
+ */
 export interface PaymentSuccess extends PaymentResultBase {
   status: 'success';
-  exchangeCode?: string;
-  merchantRef?: string;
-  /** API payment type string (e.g. `FixedPeriodicSchedule`), when available. Mirrors Flutter's `paymentType`. */
-  paymentType?: string;
 }
 
 export interface PaymentCancelled extends PaymentResultBase {
@@ -35,7 +68,12 @@ export interface PaymentFailed extends PaymentResultBase {
   errorCode: string;
 }
 
-/** Flow abandoned mid-flight (app killed, host removed the SDK navigator). */
+/**
+ * The payer left before the flow resolved either way.
+ *
+ * A payment already at the bank may still complete after this, so it is not a
+ * failure — only your backend knows how it ended.
+ */
 export interface PaymentAbandoned extends PaymentResultBase {
   status: 'abandoned';
 }