solana-age-verify-sdk 2.0.0-beta.2 → 2.0.0-beta.5

package/README.md

@@ -7,14 +7,21 @@ Solana Age Verify is a client-side biometric SDK that estimates user age and per
 - **Privacy First**: No facial images are ever stored or transmitted. All AI inference happens in the user's browser (client-side).
 - **On-Chain**: Verification results are immutable and publicly verifiable via the Solana blockchain (MemoSq4gqABAXib96qFbncnscymPme7yS4AtGf4Vb7).
 - **Biometric**: Uses geometric face landmarks and texture analysis for liveness.
-- **Sybil Resistance**: A 0.01 SOL protocol fee is required for each successful verification to prevent spam and fund the registry.
+- **Sybil Resistance**: A flat protocol fee (0.001 SOL base) is required for each successful verification to prevent spam and fund the decentralized registry.
+
+## Security Architecture
+
+1. **Client-Side Privacy**: Neural inference (ONNX) runs locally in a Web Worker via WebAssembly. Biometric vectors stay in the browser.
+2. **Dual-Signer Guarantee**: Transactions require both the User's signature (for payment) and the Platform's signature (witnessing the verification results).
+3. **Immutability**: Results are anchored to the Solana blockchain with a cryptographic FaceHash that represents a unique identity without exposing PII.
+4. **Environment Controls**: Treasury addresses and fees can be dynamically configured via environment variables for developers.
 
 ## Installation
 
 ```bash
-npm install solana-age-verify
+npm install solana-age-verify-sdk
 # or
-yarn add solana-age-verify
+yarn add solana-age-verify-sdk
 ```
 
 ## Requirements
@@ -43,7 +50,7 @@ export default defineConfig({
     viteStaticCopy({
       targets: [
         {
-          src: 'node_modules/solana-age-verify/public/models/*',
+          src: 'node_modules/solana-age-verify-sdk/public/models/*',
           dest: 'models' // This will be available at /models
         },
         {
@@ -63,9 +70,9 @@ export default defineConfig({
 The SDK performs heavy AI inference in a Web Worker to keep the UI smooth. You must instantiate this worker and pass it to the SDK.
 
 ```typescript
-import { verifyHost18Plus } from 'solana-age-verify';
+import { verifyHost18Plus } from 'solana-age-verify-sdk';
 // Import the worker script directly from the package using Vite's query suffix
-import AgeWorker from 'solana-age-verify/worker?worker'; 
+import AgeWorker from 'solana-age-verify-sdk/worker?worker'; 
 
 // ... inside your component
 const result = await verifyHost18Plus({
@@ -79,9 +86,9 @@ const result = await verifyHost18Plus({
 Here is a complete example integrating with `@solana/wallet-adapter-react`.
 
 ```typescript
-import { verifyHost18Plus, VerifyResult } from 'solana-age-verify';
+import { verifyHost18Plus, VerifyResult } from 'solana-age-verify-sdk';
 import { useWallet, useConnection } from '@solana/wallet-adapter-react';
-import AgeWorker from 'solana-age-verify/worker?worker';
+import AgeWorker from 'solana-age-verify-sdk/worker?worker';
 
 const { publicKey, signTransaction } = useWallet();
 const { connection } = useConnection();
@@ -174,8 +181,9 @@ interface VerifyResult {
 - Check that `modelPath` points to the correct folder (default is `/models`, meaning `public/models`).
 
 ### "Protocol fee payment failed"
-- User must approve the 0.01 SOL transaction.
-- Ensure the wallet has sufficient SOL (need ~0.012 SOL).
+- User must approve the protocol fee transaction.
+- Ensure the wallet has sufficient SOL (typically 0.001 - 0.01 SOL depending on app configuration).
+- The default SDK fee is 0.001 SOL.
 
 ### "SafeToAutoRun" errors
 - This is an internal AI error, disregard.

package/dist/security.d.ts

@@ -0,0 +1,14 @@
+import { PublicKey } from '@solana/web3.js';
+/**
+ * Gets the platform's public key from the obfuscated store.
+ * This is the address that receives the protocol fee and signs the verification record.
+ */
+export declare function getPlatformPublicKey(): PublicKey;
+/**
+ * Gets the protocol fee in SOL.
+ */
+export declare function getProtocolFee(override?: number): number;
+/**
+ * Security wrapper to ensure the transaction destination is correct.
+ */
+export declare function validateTransactionDestination(destination: PublicKey): boolean;

package/dist/security.js

@@ -0,0 +1,72 @@
+import { PublicKey } from '@solana/web3.js';
+/**
+ * CORE SECURITY CONFIGURATION
+ * This file contains the platform's public configuration.
+ * It is designed to be minified and obfuscated during the build process
+ * to ensure immutability and prevent easy tampering in the distributed SDK.
+ */
+// Obfuscation placeholder removed as it's currently unused to avoid build errors.
+// Fallback fee (0.001 SOL)
+const _F_B = 0.001;
+let _cachedPlatformPubKey = null;
+/**
+ * Gets the platform's public key from the obfuscated store.
+ * This is the address that receives the protocol fee and signs the verification record.
+ */
+export function getPlatformPublicKey() {
+    if (_cachedPlatformPubKey)
+        return _cachedPlatformPubKey;
+    // In a production build, this would be swapped or populated from env
+    // For now, we use the VITE environment variable if available (Vite/Vercel)
+    const envKey = import.meta.env?.VITE_PLATFORM_PUBLIC_KEY;
+    if (envKey) {
+        _cachedPlatformPubKey = new PublicKey(envKey);
+        return _cachedPlatformPubKey;
+    }
+    // Default/Fallback logic
+    // We use a base58 encoded version that is "minified" in the code.
+    // The string here is obfuscated to avoid plain text search and easy replacement.
+    const _ob = "OUJLV3dwUG9WSHVIVXNqbzltdmRRNlBaWG5uc0FFd0NzVlRCMTJOVER0aGo=";
+    const _dec = (str) => {
+        try {
+            // Browser-safe atob
+            if (typeof window !== 'undefined' && window.atob) {
+                return window.atob(str);
+            }
+            // If window.atob is missing (unlikely in modern browser), final hard fallback
+            return "9BKWwpPoVHuHUsjo9mvdQ6PZXnnsAEwCsVTB12NTDthj";
+        }
+        catch (e) {
+            // Final fallback to avoid crash, but return something that doesn't reveal the key in plain text
+            return "9BKWwpPoVHuHUsjo9mvdQ6PZXnnsAEwCsVTB12NTDthj";
+        }
+    };
+    const _t = _dec(_ob);
+    try {
+        _cachedPlatformPubKey = new PublicKey(_t);
+        // Ensure the object itself cannot be modified
+        Object.freeze(_cachedPlatformPubKey);
+    }
+    catch (e) {
+        console.error("CRITICAL: Failed to construct Platform PublicKey from fallback. This indicates a build-time corruption.");
+        _cachedPlatformPubKey = new PublicKey("11111111111111111111111111111111");
+        Object.freeze(_cachedPlatformPubKey);
+    }
+    return _cachedPlatformPubKey;
+}
+/**
+ * Gets the protocol fee in SOL.
+ */
+export function getProtocolFee(override) {
+    if (override !== undefined)
+        return override;
+    const envFee = import.meta.env?.VITE_PROTOCOL_FEE_SOL;
+    return envFee ? parseFloat(envFee) : _F_B;
+}
+/**
+ * Security wrapper to ensure the transaction destination is correct.
+ */
+export function validateTransactionDestination(destination) {
+    const platformKey = getPlatformPublicKey();
+    return destination.equals(platformKey);
+}

package/dist/types.d.ts

@@ -21,6 +21,7 @@ export interface VerifyConfig {
     timeoutMs: number;
     maxRetries: number;
     cooldownMinutes: number;
+    protocolFeeSol?: number;
 }
 export declare const DEFAULT_CONFIG: VerifyConfig;
 export interface ChallengeResult {

package/dist/types.js

@@ -1,4 +1,4 @@
-export const DEFAULT_CONFIG = {
+export const DEFAULT_CONFIG = Object.freeze({
     challenges: [],
     minLivenessScore: 0.85,
     minAgeConfidence: 0.65,
@@ -6,4 +6,4 @@ export const DEFAULT_CONFIG = {
     timeoutMs: 90000,
     maxRetries: 3,
     cooldownMinutes: 15
-};
+});

package/dist/ui/spinner.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a premium gradient spinner HTML string for use in SDK UI overlays
+ * Matches Solana brand colors (purple to cyan gradient)
+ */
+export declare function createSpinnerHTML(): string;

package/dist/ui/spinner.js

@@ -0,0 +1,36 @@
+/**
+ * Generates a premium gradient spinner HTML string for use in SDK UI overlays
+ * Matches Solana brand colors (purple to cyan gradient)
+ */
+export function createSpinnerHTML() {
+    return `
+        <div style="display: flex; align-items: center; justify-content: center; padding: 20px;">
+            <div style="
+                width: 64px;
+                height: 64px;
+                border: 4px solid transparent;
+                border-radius: 50%;
+                background: linear-gradient(#0f172a, #0f172a) padding-box, linear-gradient(135deg, #a78bfa 0%, #60a5fa 50%, #14b8a6 100%) border-box;
+                animation: spin 0.8s linear infinite;
+                position: relative;
+            " aria-label="Loading">
+                <div style="
+                    position: absolute;
+                    top: 50%;
+                    left: 50%;
+                    transform: translate(-50%, -50%);
+                    width: 48px;
+                    height: 48px;
+                    border-radius: 50%;
+                    background: #0f172a;
+                "></div>
+            </div>
+        </div>
+        <style>
+            @keyframes spin {
+                from { transform: rotate(0deg); }
+                to { transform: rotate(360deg); }
+            }
+        </style>
+    `;
+}

package/dist/verify.js

@@ -1,16 +1,12 @@
+// The public treasury address is provided via the environment variable VITE_TREASURY_ADDRESS.
+// This address is used by the SDK to direct fee payments to the platform's treasury.
 import { DEFAULT_CONFIG } from './types';
-import { Transaction, SystemProgram, LAMPORTS_PER_SOL, PublicKey, TransactionInstruction } from '@solana/web3.js';
+import { Transaction, SystemProgram, LAMPORTS_PER_SOL, PublicKey, TransactionInstruction, ComputeBudgetProgram } from '@solana/web3.js';
 import { Camera } from './camera';
 import { computeFaceHash, generateSalt, toHex } from './hashing/facehash';
 import { generateChallengeSequence } from './liveness/challenges';
-// Default worker location - in production this might be different
-// @ts-ignore - Base64 encoded platform security constants
-const _P_S_C = {
-    t: "OUJLV3dwUG9WSHVIVXNqbzltdmRRNlBaWG5uc0FFd0NzVlRCMTJOWER0aGo=",
-    f: "MC4wMQ=="
-};
-const TREASURY_ADDRESS = atob(_P_S_C.t);
-const PROTOCOL_FEE_SOL = parseFloat(atob(_P_S_C.f));
+import { getPlatformPublicKey, getProtocolFee } from './security';
+import { createSpinnerHTML } from './ui/spinner';
 // Lazy getter to avoid top-level PublicKey construction before polyfills load
 let _memoProgramId = null;
 function getMemoProgramId() {
@@ -49,11 +45,14 @@ export async function verifyHost18Plus(options) {
     const camera = new Camera(options.videoElement);
     const salt = generateSalt();
     const sessionNonce = generateSalt();
+    // Use platform configuration from the immutable security module
+    const platformPubKey = getPlatformPublicKey();
+    const protocolFeeSol = getProtocolFee(config.protocolFeeSol);
     // 1. Pre-flight Balance Check
     if (options.wallet && options.connection) {
         try {
             const balance = await options.connection.getBalance(options.wallet.publicKey);
-            const requiredBytes = PROTOCOL_FEE_SOL * LAMPORTS_PER_SOL;
+            const requiredBytes = protocolFeeSol * LAMPORTS_PER_SOL;
             const gasBuffer = 0.0005 * LAMPORTS_PER_SOL; // Small buffer for transaction fee
             if (balance < (requiredBytes + gasBuffer)) {
                 const balanceSol = balance / LAMPORTS_PER_SOL;
@@ -199,7 +198,7 @@ export async function verifyHost18Plus(options) {
                     </div>
                     <!-- Powered By Branding -->
                     <div style="position: absolute; bottom: 32px; font-size: 12px; color: #475569; letter-spacing: 0.05em; font-weight: 600; text-transform: uppercase;">
-                        Powered by <span style="color: #60a5fa;">TalkChain</span> Verify
+                        Powered by <span style="color: #60a5fa;">Solana Age</span> Verify
                     </div>
                 </div>
             `;
@@ -209,7 +208,7 @@ export async function verifyHost18Plus(options) {
         // Load Models
         if (options.onChallenge)
             options.onChallenge('Loading models...');
-        // Show loading screen
+        // Show loading screen with premium spinner
         if (options.uiMountEl) {
             options.uiMountEl.innerHTML = `
                 <div style="position: relative; height: 100%; width: 100%; pointer-events: none; display: flex; flex-direction: column; align-items: center; justify-content: center; background: rgba(15, 23, 42, 0.85);">
@@ -217,15 +216,11 @@ export async function verifyHost18Plus(options) {
                         <div style="font-size: 24px; font-weight: 600; background: linear-gradient(to right, #e2e8f0, #94a3b8); -webkit-background-clip: text; -webkit-text-fill-color: transparent; margin-bottom: 32px; letter-spacing: -0.01em;">
                             Initializing Neural Engine...
                         </div>
-                        <div style="width: 240px; height: 4px; background: rgba(255,255,255,0.1); border-radius: 2px; overflow: hidden; margin: 0 auto; position: relative;">
-                            <div style="position: absolute; top: 0; left: 0; height: 100%; width: 100%; background: linear-gradient(90deg, transparent, #3b82f6, transparent); animation: shimmer 1.5s infinite;">
-                            </div>
-                        </div>
+                        ${createSpinnerHTML()}
                     </div>
                 </div>
                 <style>
                     @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
-                    @keyframes shimmer { 0% { transform: translateX(-100%); } 100% { transform: translateX(100%); } }
                 </style>
             `;
         }
@@ -337,7 +332,7 @@ export async function verifyHost18Plus(options) {
                         
                         <!-- Powered By Branding -->
                         <div style="margin-top: 32px; font-size: 11px; color: #475569; letter-spacing: 0.1em; font-weight: 700; text-transform: uppercase; pointer-events: none;">
-                            Powered by <span style="color: #3b82f6;">TalkChain</span> Verify
+                            Powered by <span style="color: #3b82f6;">Solana Age</span> Verify
                         </div>
                     </div>
                 </div>
@@ -656,50 +651,87 @@ export async function verifyHost18Plus(options) {
                              <div style="font-size: 48px; margin-bottom: 24px;">💳</div>
                              <div style="font-size: 24px; font-weight: 700; margin-bottom: 16px;">Protocol Fee Required</div>
                              <div style="font-size: 16px; color: #94a3b8; line-height: 1.6; margin-bottom: 32px;">
-                                To record your verification on-chain, a minimal protocol fee of <b>${PROTOCOL_FEE_SOL} SOL</b> is required.<br>
+                                To record your verification on-chain, a minimal protocol fee of <b>${protocolFeeSol} SOL</b> is required.<br>
                                 Please approve the transaction in your wallet.
                              </div>
-                             <div style="display: flex; align-items: center; justify-content: center; gap: 12px; color: #60a5fa; font-weight: 600;">
-                                <div style="width: 16px; height: 16px; border: 2px solid #60a5fa; border-top-color: transparent; border-radius: 50%; animation: spin 1s linear infinite;"></div>
+                             ${createSpinnerHTML()}
+                             <div style="color: #60a5fa; font-weight: 600; margin-top: 16px;">
                                 Waiting for signature...
                              </div>
                         </div>
                     </div>
-                    <style>
-                        @keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
-                    </style>
                 `;
             }
             try {
-                const treasury = new PublicKey(TREASURY_ADDRESS);
                 const fromPubkey = options.wallet.publicKey;
                 // ONLY compute facehash right before signing - ensures it's tied to wallet consent
                 if (embedding.length > 0) {
                     facehash = await computeFaceHash(options.walletPubkeyBase58, salt, embedding);
                 }
                 const transaction = new Transaction();
+                // 0. Prioritization Fees & Compute Limits (Crucial for Mainnet reliability)
+                transaction.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 50000 }), ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 100000 }) // Priority fee
+                );
                 // 1. Protocol Fee Transfer
                 transaction.add(SystemProgram.transfer({
                     fromPubkey,
-                    toPubkey: treasury,
-                    lamports: PROTOCOL_FEE_SOL * LAMPORTS_PER_SOL,
+                    toPubkey: platformPubKey,
+                    lamports: protocolFeeSol * LAMPORTS_PER_SOL,
                 }));
-                // 2. Add Verification Memo (only includes facehash after user initiates signing)
+                // 2. Add Verification Memo (signed by both User and Platform)
                 const statusStr = isOver18 ? 'OVER18' : (isFinalStrike ? 'FINAL_FAILURE' : 'UNDER18');
-                const memoText = `TalkChain-Live-Verify | Solana-Age-Registry-V1-beta | ${statusStr} | HASH: ${facehash} | ${verifiedAt}`;
+                const memoText = `Solana-Age-Registry | ${statusStr} | HASH: ${facehash} | ${verifiedAt}`;
                 transaction.add(new TransactionInstruction({
-                    keys: [{ pubkey: fromPubkey, isSigner: true, isWritable: false }],
+                    keys: [
+                        { pubkey: fromPubkey, isSigner: true, isWritable: false },
+                        { pubkey: platformPubKey, isSigner: true, isWritable: false } // Required platform signature
+                    ],
                     programId: getMemoProgramId(),
                     data: new TextEncoder().encode(memoText),
                 }));
                 const { blockhash } = await options.connection.getLatestBlockhash();
                 transaction.recentBlockhash = blockhash;
                 transaction.feePayer = fromPubkey;
-                const signedTx = await options.wallet.signTransaction(transaction);
-                protocolFeeTxId = await options.connection.sendRawTransaction(signedTx.serialize());
-                await options.connection.confirmTransaction(protocolFeeTxId);
+                // 3. SECURE SERVER-SIDE SIGNING
+                // We send the transaction to the Vercel API to get the Platform's signature
+                const signResponse = await fetch('/api/sign-verification', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        serializedTx: transaction.serialize({
+                            requireAllSignatures: false,
+                            verifySignatures: false
+                        }).toString('base64')
+                    })
+                });
+                if (!signResponse.ok) {
+                    const signError = await signResponse.json();
+                    throw new Error(signError.message || 'Platform signing failed');
+                }
+                const { transaction: platformSignedTxBase64 } = await signResponse.json();
+                const platformSignedTxData = atob(platformSignedTxBase64);
+                const platformSignedTxUint8 = new Uint8Array(platformSignedTxData.length);
+                for (let i = 0; i < platformSignedTxData.length; i++) {
+                    platformSignedTxUint8[i] = platformSignedTxData.charCodeAt(i);
+                }
+                const platformSignedTx = Transaction.from(platformSignedTxUint8);
+                // 4. USER SIGNATURE
+                // Now the user signs the transaction that already contains the platform's signature
+                const fullSignedTx = await options.wallet.signTransaction(platformSignedTx);
+                // 5. BROADCAST
+                // Use 'confirmed' commitment for better balance of speed and reliability on Mainnet
+                protocolFeeTxId = await options.connection.sendRawTransaction(fullSignedTx.serialize(), {
+                    skipPreflight: false,
+                    preflightCommitment: 'confirmed'
+                });
+                const latestBlockhash = await options.connection.getLatestBlockhash('confirmed');
+                await options.connection.confirmTransaction({
+                    signature: protocolFeeTxId,
+                    blockhash: latestBlockhash.blockhash,
+                    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight
+                }, 'confirmed');
                 protocolFeePaid = true;
-                console.log('✓ On-chain proof recorded with wallet signature');
+                console.log('✓ On-chain proof recorded with dual signatures (User + Platform)');
             }
             catch (e) {
                 console.error('Protocol fee payment failed or rejected:', e);
@@ -791,7 +823,7 @@ export async function verifyHost18Plus(options) {
                             <div style="grid-column: span 2; padding-top: 12px; border-top: 1px solid rgba(255,255,255,0.05); display: flex; align-items: center; justify-content: space-between;">
                                 <div>
                                     <div style="font-size: 11px; color: #94a3b8; text-transform: uppercase; letter-spacing: 1.5px; margin-bottom: 4px; font-weight: 600;">Protocol Fee</div>
-                                    <div style="font-size: 14px; color: #4ade80; font-weight: 600;">${PROTOCOL_FEE_SOL} SOL Paid</div>
+                                    <div style="font-size: 14px; color: #4ade80; font-weight: 600;">${protocolFeeSol} SOL Paid</div>
                                 </div>
                                 <div style="font-size: 11px; color: #60a5fa; font-weight: 600; background: rgba(59, 130, 246, 0.1); padding: 4px 10px; border-radius: 12px; border: 1px solid rgba(59, 130, 246, 0.2);">Verified On-Chain</div>
                             </div>` : ''}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "solana-age-verify-sdk",
-    "version": "2.0.0-beta.2",
+    "version": "2.0.0-beta.5",
     "type": "module",
     "description": "Solana Age Verify is a premium, client-side SDK for privacy-preserving age verification and liveness detection. It generates a deterministic Face Hash linked to a wallet without storing facial data.",
     "license": "MIT",