@emkaylabs/realnode-sdk 1.1.5

package/README.md

@@ -0,0 +1,132 @@
+# @emkaylabs/realnode-sdk
+
+RealNode Anti-Scalper & Bot Protection SDK.
+Hardware-backed bot protection and fraud prevention for high-demand environments.
+
+---
+
+## Overview
+
+The RealNode SDK provides an isomorphic, SSR-safe integration for the RealNode Security Protocol. It is designed specifically for ticketing platforms, flash sales, and high-demand e-commerce environments where preventing automated hoarding is critical.
+
+The SDK allows modern web platforms (Next.js, React, Vue, Vanilla JS) to integrate hardware-attested biometric security (such as WebAuthn, FIDO2, and security keys) into transaction flows, establishing proof of human presence.
+
+## Live Sandbox
+
+A sandbox environment is available for testing: [https://realnode.emkaylabs.tech/sandbox](https://realnode.emkaylabs.tech/sandbox)
+
+---
+
+## Installation
+
+Install the package via your preferred package manager:
+
+```bash
+npm install @emkaylabs/realnode-sdk
+# or
+yarn add @emkaylabs/realnode-sdk
+# or
+pnpm add @emkaylabs/realnode-sdk
+```
+
+## Usage (React / Next.js)
+
+The SDK exports fully typed React hooks and components that are strictly Server-Side Rendering (SSR) safe.
+
+### 1. Setup the Provider
+
+Wrap your application or checkout flow with the `RealNodeProvider`:
+
+```tsx
+import { RealNodeProvider } from '@emkaylabs/realnode-sdk/react';
+
+export default function App({ children }) {
+  return (
+    <RealNodeProvider 
+      apiKey="pk_live_YOUR_PUBLIC_KEY" 
+      plan="sentinel" 
+    >
+      {children}
+    </RealNodeProvider>
+  );
+}
+```
+
+### 2. Implement the Checkout Component
+
+Integrate the secure checkout button within your transaction flow:
+
+```tsx
+import { RealNodeCheckoutButton } from '@emkaylabs/realnode-sdk/react';
+
+export default function CheckoutPage() {
+  const handleSuccess = (proof) => {
+    // Transmit the cryptographic proof to your backend for validation
+    fetch('/api/process-payment', {
+      method: 'POST',
+      body: JSON.stringify(proof)
+    });
+  };
+
+  return (
+    <div>
+      <h2>Complete your purchase</h2>
+      <RealNodeCheckoutButton quantity={2} onSuccess={handleSuccess}>
+        Confirm Order
+      </RealNodeCheckoutButton>
+    </div>
+  );
+}
+```
+
+### 3. Account Device Management (Optional)
+
+Provide users with the ability to manage their authorized hardware devices, revoke access, or transfer ownership from their profile page:
+
+```tsx
+import { RealNodeDeviceManager } from '@emkaylabs/realnode-sdk/react';
+
+export default function UserProfile() {
+  return (
+    <RealNodeDeviceManager 
+      apiKey="pk_live_YOUR_PUBLIC_KEY" 
+      plan="sentinel" 
+    />
+  );
+}
+```
+
+## Usage (Vanilla JS / Node.js)
+
+For non-React environments or edge functions, the core client can be imported directly. The core module has zero DOM dependencies and is environment-agnostic.
+
+```javascript
+import { RealNodeClient } from '@emkaylabs/realnode-sdk';
+
+const client = new RealNodeClient({
+  apiKey: 'pk_live_YOUR_PUBLIC_KEY',
+  plan: 'insight'
+});
+
+// Passive validation
+const result = await client.verify();
+console.log('Validation Status:', result.status);
+```
+
+## Technical Architecture
+
+- **SSR Compatibility:** The core client and components contain strict guards against `window`, `document`, and `localStorage` invocation during server-side execution.
+- **Fail-Open Strategy:** In the event of network timeouts or service unavailability, the SDK is designed to gracefully degrade, ensuring transaction continuity.
+- **Type Definitions:** The package includes comprehensive TypeScript definitions (`.d.ts`) for strict typing and IDE autocomplete support.
+
+## Support & Enterprise Contact
+
+For integration assistance and enterprise deployments, please contact our technical team.
+
+- **B2B Inquiries & Enterprise Architecture:** [realnode@emkaylabs.tech](mailto:realnode@emkaylabs.tech)
+- **Security & Developer Support:** [security@emkaylabs.tech](mailto:security@emkaylabs.tech)
+- **Documentation:** [https://realnode.emkaylabs.tech/blog](https://realnode.emkaylabs.tech/blog)
+
+## License
+
+MIT © EMKAY LABS

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@emkaylabs/realnode-sdk",
+  "version": "1.1.5",
+  "description": "RealNode Anti-Scalper SDK — Hardware-backed bot protection and fraud prevention using FIDO2/WebAuthn",
+  "author": "EMKAY LABS <security@emkaylabs.tech>",
+  "license": "MIT",
+  "homepage": "https://realnode.emkaylabs.tech",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Emkay-Labs/realnode-client-sdk.git"
+  },
+  "bugs": {
+    "email": "security@emkaylabs.tech"
+  },
+  "keywords": [
+    "anti-bot",
+    "fraud-prevention",
+    "anti-scalper",
+    "webauthn",
+    "fido2",
+    "passkey",
+    "checkout-security",
+    "bot-protection",
+    "woocommerce",
+    "nextjs",
+    "react"
+  ],
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    },
+    "./react": {
+      "import": "./src/react/index.jsx"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
+  },
+  "devDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/browser/hanko.js

@@ -0,0 +1,114 @@
+/**
+ * @realnode/sdk — Hanko Browser Integration
+ * Contains ALL DOM interactions. Never imported server-side.
+ * Called only after isBrowser guard passes.
+ */
+
+import { isBrowser } from './storage.js';
+
+const HANKO_ELEMENTS_URL = 'https://api.emkaylabs.tech/sdk/elements.js';
+
+let _hankoRegisterPromise = null;
+
+/**
+ * Load and register the Hanko Web Component.
+ * Cached so it only registers once per page.
+ * @param {string} proxyUrl
+ * @returns {Promise<void>}
+ */
+export async function registerHanko(proxyUrl) {
+  if (!isBrowser) return;
+  if (_hankoRegisterPromise) return _hankoRegisterPromise;
+
+  _hankoRegisterPromise = (async () => {
+    const { register } = await import(HANKO_ELEMENTS_URL);
+    const timeout = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('[RealNode] Hanko load timeout')), 30000)
+    );
+    await Promise.race([
+      register(proxyUrl, { methods: ['passkey', 'password'] }),
+      timeout,
+    ]);
+  })();
+
+  return _hankoRegisterPromise;
+}
+
+/**
+ * Reset Hanko registration (used when re-initializing the modal).
+ */
+export function resetHankoRegistration() {
+  _hankoRegisterPromise = null;
+}
+
+/**
+ * Inject RealNode styles into a Hanko element's Shadow DOM.
+ * @param {HTMLElement} hankoElement
+ */
+export function injectHankoStyles(hankoElement) {
+  if (!isBrowser || !hankoElement) return;
+
+  const tryInject = () => {
+    if (!hankoElement.shadowRoot) {
+      setTimeout(tryInject, 100);
+      return;
+    }
+    const style = document.createElement('style');
+    style.textContent = `
+      .hg-btn-processing {
+        pointer-events: none !important;
+        opacity: 0.6 !important;
+        filter: grayscale(0.5) !important;
+        cursor: wait !important;
+      }
+      button:active { transform: scale(0.98); }
+      @keyframes hg-quota-flash {
+        0%   { box-shadow: 0 0 0 0 rgba(0, 255, 136, 0.4); }
+        50%  { box-shadow: 0 0 20px 10px rgba(0, 255, 136, 0.6); }
+        100% { box-shadow: 0 0 0 0 rgba(0, 255, 136, 0); }
+      }
+      .hg-quota-restored {
+        animation: hg-quota-flash 0.8s ease-out 2 !important;
+        border-color: #00ff88 !important;
+        color: #fff !important;
+      }
+    `;
+    hankoElement.shadowRoot.appendChild(style);
+  };
+
+  tryInject();
+}
+
+/**
+ * Attach the auth-flow listener to a Hanko element.
+ * @param {HTMLElement} hankoElement
+ * @param {function} onAuthFlowCompleted
+ */
+export function attachAuthListener(hankoElement, onAuthFlowCompleted) {
+  if (!isBrowser || !hankoElement || hankoElement._rnListenerAttached) return;
+  hankoElement.addEventListener('onAuthFlowCompleted', onAuthFlowCompleted);
+  hankoElement.addEventListener('hanko-auth-flow-completed', onAuthFlowCompleted);
+  hankoElement._rnListenerAttached = true;
+}
+
+/**
+ * Remove the auth-flow listener from a Hanko element (cleanup).
+ * @param {HTMLElement} hankoElement
+ * @param {function} onAuthFlowCompleted
+ */
+export function detachAuthListener(hankoElement, onAuthFlowCompleted) {
+  if (!isBrowser || !hankoElement) return;
+  hankoElement.removeEventListener('onAuthFlowCompleted', onAuthFlowCompleted);
+  hankoElement.removeEventListener('hanko-auth-flow-completed', onAuthFlowCompleted);
+  hankoElement._rnListenerAttached = false;
+}
+
+/**
+ * Dispatch a custom event on window (browser only).
+ * @param {string} eventName
+ * @param {object} detail
+ */
+export function dispatchRealNodeEvent(eventName, detail) {
+  if (!isBrowser) return;
+  window.dispatchEvent(new CustomEvent(eventName, { detail, bubbles: true }));
+}

package/src/browser/storage.js

@@ -0,0 +1,74 @@
+/**
+ * @realnode/sdk — Browser Storage Utilities
+ * All DOM/browser APIs encapsulated with SSR guards.
+ * Import this module ONLY from browser-side code.
+ */
+
+/** True only when running in a real browser environment */
+export const isBrowser = typeof window !== 'undefined';
+
+// ---------------------------------------------------------------------------
+// localStorage
+// ---------------------------------------------------------------------------
+
+export function getFromStorage(key) {
+  if (!isBrowser) return null;
+  try { return localStorage.getItem(key); } catch { return null; }
+}
+
+export function setInStorage(key, value) {
+  if (!isBrowser) return;
+  try { localStorage.setItem(key, value); } catch { /* quota exceeded — silent */ }
+}
+
+export function removeFromStorage(key) {
+  if (!isBrowser) return;
+  try { localStorage.removeItem(key); } catch { /* silent */ }
+}
+
+// ---------------------------------------------------------------------------
+// Cookies
+// ---------------------------------------------------------------------------
+
+export function getCookie(name) {
+  if (!isBrowser) return null;
+  try {
+    const match = document.cookie.match(new RegExp(`(^| )${name}=([^;]+)`));
+    return match ? decodeURIComponent(match[2]) : null;
+  } catch { return null; }
+}
+
+export function clearAllCookies() {
+  if (!isBrowser) return;
+  try {
+    document.cookie.split(';').forEach((c) => {
+      document.cookie = c.replace(/^ +/, '').replace(/=.*/, `=;expires=${new Date().toUTCString()};path=/`);
+    });
+  } catch { /* silent */ }
+}
+
+// ---------------------------------------------------------------------------
+// sessionStorage
+// ---------------------------------------------------------------------------
+
+export function getFromSession(key) {
+  if (!isBrowser) return null;
+  try { return sessionStorage.getItem(key); } catch { return null; }
+}
+
+export function clearSession() {
+  if (!isBrowser) return;
+  try { sessionStorage.clear(); } catch { /* silent */ }
+}
+
+// ---------------------------------------------------------------------------
+// Device Token
+// ---------------------------------------------------------------------------
+
+export function getDeviceToken() {
+  return getFromStorage('rn_device_token');
+}
+
+export function setDeviceToken(token) {
+  setInStorage('rn_device_token', token);
+}

package/src/core/RealNodeClient.js

@@ -0,0 +1,299 @@
+/**
+ * @realnode/sdk — Core API Client
+ * 
+ * This module contains ONLY business logic and HTTP calls.
+ * It has ZERO references to window, document, localStorage, or navigator.
+ * It can be safely imported in Node.js, Next.js SSR, and Vercel Edge Functions.
+ */
+
+import { REALNODE_API_BASE, TIMEOUTS } from './constants.js';
+
+export class RealNodeClient {
+  /**
+   * @param {object} config
+   * @param {string} config.apiKey       — Public key (pk_live_...)
+   * @param {'insight'|'sentinel'|'vault'} [config.plan]
+   * @param {string} [config.eventId]    — Required for Vault plan
+   * @param {string} [config.apiBase]    — Override API base URL
+   * @param {string} [config.clientId]   — Identifier for your store
+   * @param {function} [config.onSuccess]
+   * @param {function} [config.onError]
+   * @param {function} [config.onStatusChange]
+   */
+  constructor(config = {}) {
+    this.apiKey   = config.apiKey || '';
+    this.apiBase  = config.apiBase || REALNODE_API_BASE;
+    this.plan     = config.plan || 'insight';
+    this.eventId  = config.eventId || '';
+    this.clientId = config.clientId || 'realnode-sdk-client';
+
+    // State
+    this.currentIdh           = null;
+    this.currentDeviceHash    = null;
+    this.currentDeviceToken   = null;
+    this._lastKnownRemaining  = null;
+    this._syncIntervalId      = null;
+    this._destroyed           = false;
+
+    // Callbacks
+    this.onSuccess      = config.onSuccess      || (() => {});
+    this.onError        = config.onError        || (() => {});
+    this.onStatusChange = config.onStatusChange || (() => {});
+  }
+
+  // -------------------------------------------------------------------------
+  // HTTP Helpers
+  // -------------------------------------------------------------------------
+
+  _buildHeaders(includeSecret = false) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (this.apiKey) headers['X-RealNode-API-Key'] = this.apiKey;
+    return headers;
+  }
+
+  async _fetchWithTimeout(url, options = {}, timeoutMs = TIMEOUTS.API_CALL) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, { ...options, signal: controller.signal });
+      clearTimeout(id);
+      return res;
+    } catch (err) {
+      clearTimeout(id);
+      throw err;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Session Management
+  // -------------------------------------------------------------------------
+
+  /**
+   * Attempts to restore an existing session from the server.
+   * Safe to call on SSR — returns false immediately if no apiKey.
+   * @returns {Promise<boolean>}
+   */
+  async restoreSession() {
+    if (!this.apiKey) return false;
+    try {
+      const res = await this._fetchWithTimeout(
+        `${this.apiBase}/check-session`,
+        { headers: this._buildHeaders() }
+      );
+      if (!res || !res.ok) return false;
+      const data = await res.json();
+      if (!data || (data.status !== 'restored' && data.status !== 'authorized')) return false;
+
+      this.currentIdh         = String(data.idh || '');
+      this.currentDeviceHash  = String(data.device_hash || '');
+      this._lastKnownRemaining = Number(data.remaining ?? 0);
+
+      this.onStatusChange('[SUCCESS] PROFILE_ACTIVE');
+      this.onSuccess({
+        status:     String(data.status),
+        idh:        this.currentIdh,
+        device_hash: this.currentDeviceHash,
+        remaining:  this._lastKnownRemaining,
+        max_limit:  Number(data.max_limit ?? 0),
+      });
+
+      this._startSync();
+      return true;
+    } catch {
+      return false; // Network error — fail gracefully
+    }
+  }
+
+  /**
+   * Passive verification (Insight plan). Does not block or show a modal.
+   * @returns {Promise<object|null>}
+   */
+  async verify() {
+    if (!this.apiKey) return null;
+    try {
+      const res = await this._fetchWithTimeout(
+        `${this.apiBase}/verify`,
+        {
+          method: 'POST',
+          headers: this._buildHeaders(),
+          body: JSON.stringify({
+            idh:        this.currentIdh,
+            client_id:  this.clientId,
+            event_id:   this.eventId || undefined,
+          }),
+        }
+      );
+      if (!res || !res.ok) return null;
+      const data = await res.json();
+      if (data.idh) this.currentIdh = data.idh;
+      if (data.device_hash) this.currentDeviceHash = data.device_hash;
+      return data;
+    } catch {
+      return null; // Fail-open
+    }
+  }
+
+  /**
+   * Consume a quota slot (Sentinel / Vault). Call this after biometric success.
+   * @param {object} proof — The result from the biometric modal
+   * @param {number} [quantity=1]
+   * @returns {Promise<object|null>}
+   */
+  async consume(proof = {}, quantity = 1) {
+    if (!this.apiKey) return null;
+    try {
+      const payload = {
+        quantity,
+        idh:          proof.idh         || this.currentIdh,
+        device_hash:  proof.device_hash  || this.currentDeviceHash,
+        device_token: proof.device_token || this.currentDeviceToken,
+        client_id:    this.clientId,
+      };
+      if (this.eventId) payload.event_id = this.eventId;
+
+      const res = await this._fetchWithTimeout(
+        `${this.apiBase}/consume`,
+        {
+          method: 'POST',
+          headers: this._buildHeaders(),
+          body: JSON.stringify(payload),
+        }
+      );
+      if (!res || !res.ok) return null;
+      const data = await res.json();
+      if (data.remaining !== undefined) this._lastKnownRemaining = data.remaining;
+      return data;
+    } catch {
+      return null; // Fail-open
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Device Management (Sentinel / Vault)
+  // -------------------------------------------------------------------------
+
+  async listDevices(idh) {
+    if (!this.apiKey || !idh) return { data: [] };
+    try {
+      const res = await this._fetchWithTimeout(
+        `${this.apiBase}/devices?idh=${encodeURIComponent(idh)}`,
+        { headers: this._buildHeaders() }
+      );
+      if (!res || !res.ok) return { data: [] };
+      return await res.json();
+    } catch { return { data: [] }; }
+  }
+
+  async revokeDevice(deviceHash) {
+    if (!this.apiKey) return false;
+    try {
+      const res = await this._fetchWithTimeout(
+        `${this.apiBase}/devices/revoke`,
+        {
+          method: 'POST',
+          headers: this._buildHeaders(),
+          body: JSON.stringify({ device_hash: deviceHash }),
+        }
+      );
+      return res?.ok ?? false;
+    } catch { return false; }
+  }
+
+  async requestResale(idh) {
+    if (!this.apiKey) return false;
+    try {
+      const res = await this._fetchWithTimeout(
+        `${this.apiBase}/devices/resale`,
+        {
+          method: 'POST',
+          headers: this._buildHeaders(),
+          body: JSON.stringify({ idh }),
+        }
+      );
+      return res?.ok ?? false;
+    } catch { return false; }
+  }
+
+  async transferDevice(recipientId) {
+    if (!this.apiKey || !this.currentIdh) throw new Error('No active session to transfer.');
+    const res = await this._fetchWithTimeout(
+      `${this.apiBase}/devices/transfer`,
+      {
+        method: 'POST',
+        headers: this._buildHeaders(),
+        body: JSON.stringify({ idh: this.currentIdh, recipient_id: recipientId }),
+      }
+    );
+    if (!res?.ok) throw new Error('Transfer failed.');
+    return await res.json();
+  }
+
+  async recover(code) {
+    if (!code) throw new Error('Recovery code required.');
+    const res = await this._fetchWithTimeout(
+      `${this.apiBase}/recover`,
+      {
+        method: 'POST',
+        headers: this._buildHeaders(),
+        body: JSON.stringify({ recovery_code: code }),
+      }
+    );
+    if (!res?.ok) throw new Error('Invalid recovery code.');
+    return await res.json();
+  }
+
+  async requestRescue(email) {
+    if (!email) throw new Error('Email required.');
+    const res = await this._fetchWithTimeout(
+      `${this.apiBase}/rescue`,
+      {
+        method: 'POST',
+        headers: this._buildHeaders(),
+        body: JSON.stringify({ email }),
+      }
+    );
+    if (!res?.ok) throw new Error('Rescue request failed.');
+    return true;
+  }
+
+  async requestQuotaExtension() {
+    if (!this.apiKey || !this.currentIdh) return false;
+    const res = await this._fetchWithTimeout(
+      `${this.apiBase}/quota/extend`,
+      {
+        method: 'POST',
+        headers: this._buildHeaders(),
+        body: JSON.stringify({ idh: this.currentIdh }),
+      }
+    );
+    return res?.ok ?? false;
+  }
+
+  // -------------------------------------------------------------------------
+  // Sync (keep quota up to date)
+  // -------------------------------------------------------------------------
+
+  _startSync() {
+    if (this._destroyed || this._syncIntervalId) return;
+    this._syncIntervalId = setInterval(async () => {
+      if (this._destroyed) { this._stopSync(); return; }
+      await this.restoreSession();
+    }, TIMEOUTS.SESSION_POLL);
+  }
+
+  _stopSync() {
+    if (this._syncIntervalId) {
+      clearInterval(this._syncIntervalId);
+      this._syncIntervalId = null;
+    }
+  }
+
+  /**
+   * Must be called when unmounting a React component or destroying the instance.
+   * Stops all intervals to prevent memory leaks.
+   */
+  destroy() {
+    this._destroyed = true;
+    this._stopSync();
+  }
+}

package/src/core/constants.js

@@ -0,0 +1,26 @@
+/**
+ * @realnode/sdk — Core Constants
+ * Shared across all environments (Node.js, browser, edge).
+ */
+
+export const REALNODE_API_BASE = 'https://api.emkaylabs.tech';
+export const REALNODE_SDK_VERSION = '1.0.0';
+
+export const PLANS = {
+  INSIGHT:  'insight',
+  SENTINEL: 'sentinel',
+  VAULT:    'vault',
+};
+
+export const EVENTS = {
+  SENSOR_READY:     'rn:v2:sensor-ready',
+  PURCHASE_SUCCESS: 'rn-purchase-success',
+  VERIFIED:         'rn:verified',
+};
+
+export const TIMEOUTS = {
+  API_CALL:   5000,   // 5s — fail-open if RealNode unreachable
+  MODAL:      30000,  // 30s — fail-open if user closes modal
+  SDK_LOAD:   10000,  // 10s — SDK polling timeout
+  SESSION_POLL: 60000, // 1min — session keep-alive interval
+};

package/src/index.js

@@ -0,0 +1,7 @@
+/**
+ * @realnode/sdk — Vanilla JS entry point
+ * For use with plain HTML, PHP, and non-React projects.
+ */
+export { RealNodeClient } from './core/RealNodeClient.js';
+export { PLANS, EVENTS, TIMEOUTS, REALNODE_API_BASE } from './core/constants.js';
+export { isBrowser, getDeviceToken, setDeviceToken } from './browser/storage.js';

package/src/react/index.jsx

@@ -0,0 +1,423 @@
+/**
+ * @realnode/sdk — React Hook & Components
+ * 
+ * Usage:
+ *   import { useRealNode, RealNodeCheckoutButton, RealNodeDeviceManager }
+ *     from '@realnode/sdk/react';
+ */
+
+'use client'; // Next.js App Router directive — safe to include always
+
+import { useEffect, useRef, useCallback, useState, createContext, useContext } from 'react';
+import { RealNodeClient } from '../core/RealNodeClient.js';
+import { isBrowser, getDeviceToken } from '../browser/storage.js';
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const RealNodeContext = createContext(null);
+
+/**
+ * Provider — wrap your app or checkout layout with this.
+ *
+ * @example
+ * <RealNodeProvider apiKey="pk_live_xxx" plan="sentinel">
+ *   <CheckoutPage />
+ * </RealNodeProvider>
+ */
+export function RealNodeProvider({ children, apiKey, plan = 'insight', eventId, clientId }) {
+  const hook = useRealNode({ apiKey, plan, eventId, clientId });
+  return (
+    <RealNodeContext.Provider value={hook}>
+      {children}
+    </RealNodeContext.Provider>
+  );
+}
+
+/**
+ * Use the RealNode context from a child component.
+ * Must be inside <RealNodeProvider>.
+ */
+export function useRealNodeContext() {
+  const ctx = useContext(RealNodeContext);
+  if (!ctx) throw new Error('[RealNode] useRealNodeContext must be used inside <RealNodeProvider>');
+  return ctx;
+}
+
+// ============================================================================
+// Core Hook
+// ============================================================================
+
+/**
+ * useRealNode — the main integration hook.
+ *
+ * @example
+ * const { status, quota, verify, showModal, client } = useRealNode({
+ *   apiKey: 'pk_live_xxx',
+ *   plan: 'sentinel',
+ * });
+ *
+ * @param {object} config
+ * @returns {{ status, quota, verify, showModal, client }}
+ */
+export function useRealNode({ apiKey, plan = 'insight', eventId, clientId } = {}) {
+  const clientRef = useRef(null);
+  const [status, setStatus]   = useState('idle');
+  const [quota,  setQuota]    = useState({ remaining: null, max: null });
+  const [proof,  setProof]    = useState(null);
+
+  useEffect(() => {
+    // SSR Guard: do nothing on the server
+    if (!isBrowser) return;
+    if (!apiKey)    return;
+
+    const client = new RealNodeClient({
+      apiKey,
+      plan,
+      eventId,
+      clientId,
+      onSuccess: (data) => {
+        setQuota({ remaining: data.remaining ?? null, max: data.max_limit ?? null });
+        setProof(data);
+        setStatus('authorized');
+      },
+      onError: (err) => {
+        console.warn('[RealNode]', err);
+        setStatus('error');
+      },
+      onStatusChange: (s) => setStatus(s),
+    });
+
+    clientRef.current = client;
+
+    // Try to restore an existing session silently
+    client.restoreSession().catch(() => {});
+
+    // Cleanup: stop sync intervals when component unmounts
+    return () => {
+      client.destroy();
+      clientRef.current = null;
+    };
+  }, [apiKey, plan, eventId, clientId]);
+
+  /** Passive verification — Insight plan */
+  const verify = useCallback(async () => {
+    if (!clientRef.current) return null;
+    setStatus('verifying');
+    const result = await clientRef.current.verify();
+    if (result) {
+      setStatus('authorized');
+      setProof(result);
+    } else {
+      setStatus('idle'); // fail-open
+    }
+    return result;
+  }, []);
+
+  /**
+   * Trigger biometric modal (Sentinel / Vault).
+   * Resolves when the user completes or dismisses the modal.
+   * Always fail-open on timeout.
+   */
+  const showModal = useCallback(async () => {
+    if (!clientRef.current || !isBrowser) return null;
+    setStatus('verifying');
+
+    return new Promise((resolve) => {
+      // Listen for the verified event emitted by the Hanko element
+      const onVerified = (e) => {
+        window.removeEventListener('rn:verified', onVerified);
+        clearTimeout(fallback);
+        const result = e.detail;
+        setProof(result);
+        setStatus('authorized');
+        resolve(result);
+      };
+
+      // Fail-open timeout — never block the user forever
+      const fallback = setTimeout(() => {
+        window.removeEventListener('rn:verified', onVerified);
+        setStatus('idle');
+        resolve(null);
+      }, 30000);
+
+      window.addEventListener('rn:verified', onVerified, { once: true });
+
+      // Trigger the modal
+      if (clientRef.current?.showModal) {
+        clientRef.current.showModal();
+      } else {
+        // If showModal not available (e.g. Insight plan), fallback to verify()
+        clientRef.current?.verify().then(resolve);
+      }
+    });
+  }, []);
+
+  return {
+    status,       // 'idle' | 'verifying' | 'authorized' | 'error'
+    quota,        // { remaining: number|null, max: number|null }
+    proof,        // Last verified result object
+    verify,
+    showModal,
+    client: clientRef.current,
+  };
+}
+
+// ============================================================================
+// RealNodeCheckoutButton
+// ============================================================================
+
+/**
+ * Drop-in secure purchase button.
+ * Automatically handles biometric verification before calling onSuccess.
+ *
+ * @example
+ * // Sentinel/Vault — shows biometric modal
+ * <RealNodeCheckoutButton
+ *   quantity={2}
+ *   onSuccess={(proof) => sendToServer(proof)}
+ *   plan="sentinel"
+ * >
+ *   Buy Tickets
+ * </RealNodeCheckoutButton>
+ *
+ * @example
+ * // Insight — passive, no modal
+ * <RealNodeCheckoutButton plan="insight" onSuccess={handleBuy}>
+ *   Purchase
+ * </RealNodeCheckoutButton>
+ */
+export function RealNodeCheckoutButton({
+  children      = 'Secure Purchase',
+  quantity      = 1,
+  plan          = 'insight',
+  onSuccess,
+  onDenied,
+  style         = {},
+  className     = '',
+  ...rest
+}) {
+  const { status, verify, showModal, proof } = useRealNode(
+    useContext(RealNodeContext) || {}
+  );
+
+  const isVerifying = status === 'verifying';
+
+  const handleClick = async (e) => {
+    e.preventDefault();
+    let result = null;
+
+    if (plan === 'insight') {
+      result = await verify();
+    } else {
+      result = await showModal();
+    }
+
+    // Fail-open: if result is null (timeout/network), let it through
+    if (result === null) {
+      onSuccess?.({ status: 'fail-open', quantity });
+      return;
+    }
+
+    if (result.status === 'authorized' || result.status === 'restored') {
+      // Attach device token from localStorage if available
+      result.device_token = getDeviceToken() || result.device_token;
+      result.quantity = quantity;
+      onSuccess?.(result);
+    } else {
+      onDenied?.(result);
+    }
+  };
+
+  const buttonStyle = {
+    cursor: isVerifying ? 'wait' : 'pointer',
+    opacity: isVerifying ? 0.7 : 1,
+    transition: 'opacity 0.2s',
+    ...style,
+  };
+
+  return (
+    <button
+      onClick={handleClick}
+      disabled={isVerifying}
+      style={buttonStyle}
+      className={className}
+      aria-busy={isVerifying}
+      {...rest}
+    >
+      {isVerifying ? 'Verifying…' : children}
+    </button>
+  );
+}
+
+// ============================================================================
+// RealNodeQuotaBadge
+// ============================================================================
+
+/**
+ * Displays real-time quota information for the Vault plan.
+ *
+ * @example
+ * <RealNodeQuotaBadge />
+ * // Renders: "Tickets remaining: 3 / 5"
+ */
+export function RealNodeQuotaBadge({ label = 'Tickets remaining', style = {} }) {
+  const { quota } = useContext(RealNodeContext) || { quota: { remaining: null, max: null } };
+
+  if (quota.remaining === null) return null;
+
+  const badgeStyle = {
+    display: 'inline-block',
+    padding: '4px 10px',
+    borderRadius: '4px',
+    fontSize: '0.9rem',
+    fontWeight: 600,
+    background: 'rgba(0, 200, 100, 0.1)',
+    color: '#15803d',
+    border: '1px solid rgba(0, 200, 100, 0.3)',
+    ...style,
+  };
+
+  return (
+    <span style={badgeStyle} aria-live="polite">
+      {label}: <strong>{quota.remaining}</strong> / {quota.max}
+    </span>
+  );
+}
+
+// ============================================================================
+// RealNodeDeviceManager
+// ============================================================================
+
+/**
+ * Full device management panel for "My Account" pages.
+ * Handles device listing, revocation, resale, transfer, and recovery.
+ *
+ * @example
+ * <RealNodeDeviceManager
+ *   apiKey="pk_live_xxx"
+ *   plan="sentinel"
+ * />
+ */
+export function RealNodeDeviceManager({ apiKey, plan = 'sentinel' }) {
+  const { client, status } = useRealNode({ apiKey, plan });
+  const [devices,      setDevices]      = useState([]);
+  const [loading,      setLoading]      = useState(true);
+  const [transferId,   setTransferId]   = useState('');
+  const [recoveryCode, setRecoveryCode] = useState('');
+  const [rescueEmail,  setRescueEmail]  = useState('');
+  const [message,      setMessage]      = useState('');
+
+  const notify = (msg) => { setMessage(msg); setTimeout(() => setMessage(''), 4000); };
+
+  useEffect(() => {
+    if (!client || status !== 'authorized') return;
+    client.listDevices(client.currentIdh).then((res) => {
+      setDevices(res?.data || []);
+      setLoading(false);
+    });
+  }, [client, status]);
+
+  if (plan === 'insight') return null; // Not applicable to Insight plan
+
+  const inputStyle = {
+    padding: '8px 12px', border: '1px solid #cbd5e1', borderRadius: '6px',
+    width: '100%', maxWidth: '320px', marginBottom: '8px', fontSize: '14px',
+  };
+  const btnStyle = {
+    padding: '8px 16px', borderRadius: '6px', border: '1px solid #cbd5e1',
+    background: '#f8fafc', cursor: 'pointer', fontSize: '14px', marginRight: '8px',
+  };
+  const dangerBtnStyle = {
+    ...btnStyle, background: 'transparent',
+    border: '1px solid #ef4444', color: '#ef4444',
+  };
+
+  return (
+    <div style={{ padding: '24px', border: '1px solid #e2e8f0', borderRadius: '8px', background: '#f8fafc' }}>
+      <h3 style={{ marginTop: 0, fontSize: '18px', color: '#0f172a' }}>RealNode Security</h3>
+      <p style={{ color: '#64748b', fontSize: '14px' }}>
+        Manage the hardware-secured devices linked to your account.
+      </p>
+
+      {message && (
+        <div style={{ padding: '8px 12px', background: '#d4edda', borderRadius: '6px', marginBottom: '12px', fontSize: '14px', color: '#155724' }}>
+          {message}
+        </div>
+      )}
+
+      {/* Device List */}
+      <div style={{ marginBottom: '20px' }}>
+        {loading && <p style={{ color: '#64748b', fontSize: '14px' }}>Loading devices…</p>}
+        {!loading && devices.length === 0 && (
+          <p style={{ color: '#64748b', fontSize: '14px' }}>No devices registered yet.</p>
+        )}
+        {devices.map((dev) => (
+          <div key={dev.device_hash} style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', padding: '10px', background: '#fff', border: '1px solid #cbd5e1', borderRadius: '6px', marginBottom: '8px' }}>
+            <span style={{ fontFamily: 'monospace', fontSize: '14px' }}>
+              Device: {dev.device_hash.substring(0, 8)}…
+            </span>
+            <button
+              style={dangerBtnStyle}
+              onClick={async () => {
+                if (window.confirm('Block this device from the network?')) {
+                  await client.revokeDevice(dev.device_hash);
+                  setDevices((d) => d.filter((x) => x.device_hash !== dev.device_hash));
+                  notify('Device blocked successfully.');
+                }
+              }}
+            >
+              Block (Stolen)
+            </button>
+          </div>
+        ))}
+      </div>
+
+      {/* Resale */}
+      <button style={btnStyle} onClick={async () => {
+        if (window.confirm('Clean this device of your identity before reselling?')) {
+          await client.requestResale(client.currentIdh);
+          notify('Device freed for resale.');
+        }
+      }}>
+        Free device (For Resale)
+      </button>
+
+      <hr style={{ margin: '20px 0', border: 0, borderTop: '1px solid #e2e8f0' }} />
+
+      {/* Transfer */}
+      <h4 style={{ margin: '0 0 8px', fontSize: '15px' }}>Transfer Account</h4>
+      <input style={inputStyle} placeholder="Recipient ID" value={transferId} onChange={(e) => setTransferId(e.target.value)} />
+      <button style={btnStyle} onClick={async () => {
+        if (!transferId) return;
+        if (window.confirm('Irreversibly transfer your account to this user?')) {
+          try { await client.transferDevice(transferId); notify('Transfer successful.'); }
+          catch { notify('Transfer failed. Please check the recipient ID.'); }
+        }
+      }}>
+        Confirm Transfer
+      </button>
+
+      <hr style={{ margin: '20px 0', border: 0, borderTop: '1px solid #e2e8f0' }} />
+
+      {/* Recovery */}
+      <h4 style={{ margin: '0 0 8px', fontSize: '15px' }}>Emergency Recovery</h4>
+      <div style={{ display: 'flex', gap: '8px', marginBottom: '12px', flexWrap: 'wrap' }}>
+        <input style={{ ...inputStyle, marginBottom: 0 }} placeholder="Recovery Code (RN-REC-…)" value={recoveryCode} onChange={(e) => setRecoveryCode(e.target.value)} />
+        <button style={btnStyle} onClick={async () => {
+          try { await client.recover(recoveryCode); notify('Identity restored!'); }
+          catch { notify('Invalid recovery code.'); }
+        }}>Restore</button>
+      </div>
+      <p style={{ fontSize: '13px', color: '#64748b', margin: '0 0 6px' }}>Lost your code?</p>
+      <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+        <input style={{ ...inputStyle, marginBottom: 0 }} type="email" placeholder="your@email.com" value={rescueEmail} onChange={(e) => setRescueEmail(e.target.value)} />
+        <button style={btnStyle} onClick={async () => {
+          try { await client.requestRescue(rescueEmail); notify('Recovery link sent to your email.'); }
+          catch { notify('Request failed. Please check your email address.'); }
+        }}>Request Link</button>
+      </div>
+    </div>
+  );
+}

package/types/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @realnode/sdk — TypeScript Definitions
+ * Provides full autocomplete and type checking for consumers.
+ */
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export type RealNodePlan = 'insight' | 'sentinel' | 'vault';
+
+export interface RealNodeConfig {
+  /** Public API key (starts with pk_live_ or pk_test_) */
+  apiKey: string;
+  /** Service tier. Defaults to 'insight'. */
+  plan?: RealNodePlan;
+  /** Event ID — required when plan is 'vault' */
+  eventId?: string;
+  /** Identifier for your store, used in RealNode analytics */
+  clientId?: string;
+  /** Override the RealNode API base URL (advanced) */
+  apiBase?: string;
+  onSuccess?: (result: RealNodeResult) => void;
+  onError?: (error: Error) => void;
+  onStatusChange?: (status: string) => void;
+}
+
+// ============================================================================
+// Results
+// ============================================================================
+
+export interface RealNodeResult {
+  status: 'authorized' | 'restored' | 'denied' | 'fail-open';
+  idh?: string;
+  device_hash?: string;
+  device_token?: string;
+  remaining?: number;
+  max_limit?: number;
+  quantity?: number;
+}
+
+export interface RealNodeDevice {
+  device_hash: string;
+  created_at?: string;
+  last_seen?: string;
+}
+
+export interface RealNodeQuota {
+  remaining: number | null;
+  max: number | null;
+}
+
+// ============================================================================
+// Core Client
+// ============================================================================
+
+export declare class RealNodeClient {
+  currentIdh: string | null;
+  currentDeviceHash: string | null;
+
+  constructor(config: RealNodeConfig);
+
+  restoreSession(): Promise<boolean>;
+  verify(): Promise<RealNodeResult | null>;
+  consume(proof?: Partial<RealNodeResult>, quantity?: number): Promise<RealNodeResult | null>;
+
+  listDevices(idh: string): Promise<{ data: RealNodeDevice[] }>;
+  revokeDevice(deviceHash: string): Promise<boolean>;
+  requestResale(idh: string): Promise<boolean>;
+  transferDevice(recipientId: string): Promise<object>;
+  recover(code: string): Promise<object>;
+  requestRescue(email: string): Promise<boolean>;
+  requestQuotaExtension(): Promise<boolean>;
+
+  /** Must be called when unmounting to prevent memory leaks */
+  destroy(): void;
+}
+
+// ============================================================================
+// React Hook
+// ============================================================================
+
+export interface UseRealNodeReturn {
+  /** Current status of the verification flow */
+  status: 'idle' | 'verifying' | 'authorized' | 'error';
+  /** Real-time quota data (Vault plan) */
+  quota: RealNodeQuota;
+  /** The last successful verification proof */
+  proof: RealNodeResult | null;
+  /** Passive verification — Insight plan */
+  verify: () => Promise<RealNodeResult | null>;
+  /** Opens biometric modal — Sentinel / Vault plan */
+  showModal: () => Promise<RealNodeResult | null>;
+  /** Direct access to the underlying RealNodeClient */
+  client: RealNodeClient | null;
+}
+
+export declare function useRealNode(config: RealNodeConfig): UseRealNodeReturn;
+
+// ============================================================================
+// React Components
+// ============================================================================
+
+import type { ReactNode, CSSProperties } from 'react';
+
+export interface RealNodeProviderProps extends RealNodeConfig {
+  children: ReactNode;
+}
+export declare function RealNodeProvider(props: RealNodeProviderProps): JSX.Element;
+export declare function useRealNodeContext(): UseRealNodeReturn;
+
+export interface RealNodeCheckoutButtonProps {
+  children?: ReactNode;
+  quantity?: number;
+  plan?: RealNodePlan;
+  onSuccess?: (result: RealNodeResult) => void;
+  onDenied?: (result: RealNodeResult) => void;
+  style?: CSSProperties;
+  className?: string;
+  [key: string]: unknown;
+}
+export declare function RealNodeCheckoutButton(props: RealNodeCheckoutButtonProps): JSX.Element;
+
+export interface RealNodeQuotaBadgeProps {
+  label?: string;
+  style?: CSSProperties;
+}
+export declare function RealNodeQuotaBadge(props: RealNodeQuotaBadgeProps): JSX.Element | null;
+
+export interface RealNodeDeviceManagerProps {
+  apiKey: string;
+  plan?: RealNodePlan;
+}
+export declare function RealNodeDeviceManager(props: RealNodeDeviceManagerProps): JSX.Element | null;