GenoBank.io

DNA Kit Activation System - Complete Guide

Overview
System Architecture
Magic URL System
Passkey Authentication
Implementation Details
API Endpoints
Security
Testing Guide
Troubleshooting

Overview

The GenoBank DNA Kit Activation system allows users to activate their DNA collection kits and mint BioNFTs™ on Story Protocol. The system supports two activation methods:

Magic URL Activation: Pre-registered kits shipped with secure activation URLs
Open Registration: Any DNA kit can be activated using passkey authentication

Key Features

🔐 Passkey Authentication: Biometric login (Face ID, Touch ID, Windows Hello)
🔗 Magic URL Support: Backward compatible with existing pre-shipped URLs
📷 Barcode Scanning: Camera-based or manual entry
🌐 Story Protocol Integration: Mints BioNFTs on mainnet
🏭 Multi-Manufacturer Support: Auto-detects kit manufacturer

System Architecture

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│                     │     │                     │     │                     │
│   Laboratory/Lab    │────▶│   GenoBank API     │────▶│  Story Protocol    │
│                     │     │                     │     │                     │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
         │                           │                           │
         │ 1. Create                 │ 3. Validate              │ 4. Mint
         │    Magic Link             │    & Store               │    BioNFT
         │                           │                           │
         ▼                           ▼                           ▼
┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│                     │     │                     │     │                     │
│   DNA Kit with     │────▶│  Activation Page    │────▶│     BioNFT™        │
│   Magic URL        │     │  (Passkey Auth)     │     │                     │
│                     │     │                     │     │                     │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
         │                           │
         │ 2. User Clicks           │ 
         │    Magic URL             │
         └───────────────────────────┘

Magic URL System

How Magic URLs Work

Laboratory Creates Magic Link

POST https://genobank.app/create_magic_link
   
// Request
{
  signature: "0x...", // Lab's Web3 signature
  data: {
    "prefix": "100",
    "biosampleId": "55052008714049",
    "physicalId": "10055052008714049", 
    "packageHashCode": "2xuE-AXCa-Z3D-tQb",
    "domain": "https://genobank.io"
  }
}
   
// Response
{
  "url": "https://genobank.io/activate/?biosampleId=55052008714049&laboratoryId=39&physicalId=10055052008714049#67d6516e1229eee318e5032776377b639f1c2ee2fe93531164bf5706d56fdcf1"
}

URL Structure

https://genobank.io/activate/?
  biosampleId=55052008714049&        // Kit serial number
  laboratoryId=39&                   // Lab/Permittee ID  
  physicalId=10055052008714049       // Physical kit ID
  #67d6516e1229eee3...               // HMAC-SHA256 secret

Secret Generation

# Server-side HMAC generation
secret = hmac.new(
    BIOSAMPLE_ACTIVATION_SECRET.encode('utf-8'),
    str(biosampleId).encode(),
    digestmod='sha256'
).hexdigest()

Biosample Activation Records

Pre-registered kits appear in the activation registry:

GET https://genobank.app/biosample_activations

// Response
{
  "data": [{
    "serial": 55052008714049,
    "permitteeSerial": "39",
    "physicalId": "10055052008714049",
    "createdAt": "2025-03-12 18:45:08.580000",
    "manufacturer": "DNA Genotek"
  }]
}

Passkey Authentication

Privy Integration

The system uses Privy for passkey authentication:

// Configuration
const privy = new Privy({
    appId: 'cmc5jn5sh01wel10ng0x5atlt',
    config: {
        loginMethods: ['passkey', 'email', 'google', 'apple'],
        appearance: {
            theme: 'light',
            accentColor: '#667eea'
        }
    }
});

Authentication Flow

User clicks “Continue with Passkey”
Device prompts for biometric (Face ID, Touch ID, or Windows Hello)
Privy creates embedded wallet
Signs GenoBank message: “I want to proceed”
Verifies with GenoBank API: /recover?signature={sig}

Implementation Details

Frontend Files

/activate/passkey-activation.html
- 4-step activation flow UI
- Responsive design
- Progress indicators
/activate/passkey-activate.js
- Privy SDK integration
- Magic URL detection
- Barcode scanning (ZXing library)
- API communication

Key JavaScript Functions

// Check for magic URL on page load
function checkMagicLinkActivation() {
    const urlParams = new URLSearchParams(window.location.search);
    const biosampleId = urlParams.get('biosampleId');
    const laboratoryId = urlParams.get('laboratoryId');
    const physicalId = urlParams.get('physicalId');
    const secret = window.location.hash.substring(1);
    
    if (biosampleId && secret) {
        window.magicLinkData = {
            biosampleId,
            laboratoryId,
            physicalId,
            secret
        };
    }
}

// Authenticate with passkey
async function authenticateWithPrivy() {
    const user = await privy.login();
    const wallet = await privy.getEmbeddedWallet();
    const signature = await wallet.signMessage("I want to proceed");
    // Store credentials
    localStorage.setItem('user_sign', signature);
    localStorage.setItem('user_address', wallet.address);
}

// Activate kit
async function activateKit() {
    if (window.magicLinkData) {
        // Use existing /claim endpoint
        const tokenId = generateTokenId(biosampleId, walletAddress);
        await fetch(`/claim/${tokenId}`, {
            method: 'POST',
            body: JSON.stringify({
                secret: window.magicLinkData.secret,
                physicalId: window.magicLinkData.physicalId,
                laboratoryId: window.magicLinkData.laboratoryId
            })
        });
    } else {
        // Use new activation endpoint
        await fetch(`/api_activation/`, {
            method: 'POST',
            body: JSON.stringify({
                user_signature: userSignature,
                barcode: currentBarcode,
                manufacturer: detectManufacturer(currentBarcode).name
            })
        });
    }
}

Backend Integration

The system leverages existing GenoBank infrastructure:

# /production_api/plugins/activation/api_activate_kit.py

class ApiActivateKit:
    def __init__(self):
        self.signature_service = SignatureService()
        self.biosample_service = BiosampleService()
        self.biosample_dao = BiosampleDAO()
        self.story_protocol = StoryIpManagerDAO()
        
    @cherrypy.expose
    def index(self):
        # 1. Verify signature
        wallet = self.signature_service.recover_from_signature(user_signature)
        
        # 2. Create biosample record
        biosample_data = {
            "serial": barcode,
            "owner": wallet,
            "manufacturer": manufacturer,
            "status": "ACTIVE"
        }
        
        # 3. Mint BioNFT on Story Protocol
        mint_result = self.story_protocol.mint_and_register_ip({
            "collection_address": self.biosample_collection,
            "recipient": wallet,
            "metadata_uri": metadata_uri
        })
        
        # 4. Save to database
        self.biosample_dao.create(biosample_data)

API Endpoints

1. Create Magic Link (Laboratory)

POST /create_magic_link
Headers: Content-Type: application/json
Body: {
  "signature": "0x...",
  "data": {
    "biosampleId": "55052008714049",
    "physicalId": "10055052008714049",
    "domain": "https://genobank.io"
  }
}

2. Claim Kit (With Magic URL)

POST /claim/{tokenId}
Headers: Content-Type: application/json
Body: {
  "secret": "67d6516e1229eee3...",
  "physicalId": "10055052008714049",
  "laboratoryId": "39"
}

3. Activate Kit (Open Registration)

POST /api_activation/
Headers: Content-Type: application/json
Body: {
  "user_signature": "0x...",
  "barcode": "55052008714049",
  "manufacturer": "DNA Genotek"
}

4. Verify Signature

GET /recover?signature={signature}
Response: {
  "wallet_address": "0x...",
  "user": {...}
}

5. Check Activations

GET /biosample_activations?serial={serial}
Response: {
  "data": [{
    "serial": 55052008714049,
    "permitteeSerial": "39",
    "physicalId": "10055052008714049"
  }]
}

Security

Authentication Security

Web3 Signatures: All API calls require valid signatures
Message Signing: Uses environment-configured message
Wallet Scoping: All operations scoped by wallet address

Magic URL Security

HMAC-SHA256: Secret generated server-side
One-time Use: Secrets invalidated after claiming
Time Limits: Optional expiration on magic links

Kit Activation Security

Duplicate Prevention: Cannot activate same kit twice
Ownership Verification: Kit linked to authenticating wallet
Blockchain Immutability: BioNFT minted on Story Protocol

Testing Guide

1. Test Magic URL Activation

# Visit with magic URL
https://genobank.io/activate/passkey-activation.html?biosampleId=55052008714049&laboratoryId=39&physicalId=10055052008714049#secret

# Should:
- Pre-fill barcode field
- Detect magic link
- Use /claim endpoint

2. Test Open Registration

# Visit directly
https://genobank.io/activate/passkey-activation.html

# Should:
- Show empty barcode field
- Accept any valid barcode
- Use /api_activation endpoint

3. Test Barcode Formats

// Valid formats
41221040804049  // DNA Genotek (412 prefix)
42221040804049  // Spectrum DNA (422 prefix)
43221040804049  // Mawi DNA (432 prefix)
55052008714049  // GenoBank Standard (550 prefix)

4. Test Authentication Methods

Passkey (Face ID, Touch ID, Windows Hello)
Email fallback
Google OAuth
Apple Sign In

Troubleshooting

Common Issues

“Biosample Activation Not Found”
- Kit not pre-registered
- Use open registration flow instead
“Invalid signature”
- Expired Web3 signature
- Re-authenticate with Privy
“Kit already activated”
- Check /biosamples?serial={serial}
- Kit may be claimed by another user
Camera not working
- Check browser permissions
- Use manual barcode entry
Passkey not available
- Device doesn’t support WebAuthn
- Falls back to email/social login

Debug Mode

Enable console logging:

// In browser console
localStorage.setItem('debug', 'true');

// Check stored data
console.log('Magic Link Data:', window.magicLinkData);
console.log('User Wallet:', localStorage.getItem('user_address'));
console.log('User Signature:', localStorage.getItem('user_sign'));

Error Handling

All errors display user-friendly messages:

function showError(message) {
    const errorEl = document.getElementById('error-message');
    errorEl.textContent = message;
    errorEl.style.display = 'block';
    setTimeout(() => errorEl.style.display = 'none', 5000);
}

Kit Manufacturer Support

Detected by barcode prefix (first 3 digits):

Prefix	Manufacturer	Kit Type
412	DNA Genotek	Saliva Collection
422	Spectrum DNA	Saliva Collection
432	Mawi DNA	Saliva Collection
442	Norgen Biotek	Saliva Collection
452	Zymo Research	Saliva Collection
550	GenoBank Standard	Standard Kit

Future Enhancements

QR Code Support
- Scan QR codes instead of barcodes
- Embed magic URL in QR
Bulk Activation
- Activate multiple kits at once
- CSV upload for labs
Mobile App
- Native iOS/Android apps
- Better camera integration
Analytics
- Track activation success rates
- Monitor authentication methods
- Geographic distribution
Enhanced Security
- 2FA for high-value kits
- Geofencing for region-locked kits
- Fraud detection

Support

For technical support:

API Issues: Check /static/Genobank_API_Educational_Guide.html
Frontend Issues: Check browser console for errors
Authentication: Ensure Privy app ID is configured
Blockchain: Verify Story Protocol connection

License

This implementation is part of the GenoBank platform and subject to GenoBank’s terms of service.