| ← Back to Main Documentation | Core Systems Index |
Vercel Key Management - Initial Tier Implementation Guide
Created: Mon 17 Jul 2025 15:22:00 CEST
Document Version: 1.0 - Initial Tier Implementation
Security Classification: Internal Technical Documentation
Target Audience: Backend Developers, DevOps Engineers, Security Teams
Overview
This guide provides complete implementation details for Plings’ Initial Tier key management solution using Vercel environment variables. This approach enables immediate production deployment with zero additional infrastructure costs while maintaining security best practices.
Key Benefits
- Immediate Deployment: Production-ready in under 24 hours
- Zero Infrastructure Cost: No HSM hardware or VPS required
- Simple Architecture: Master key in environment, derive on-demand
- Secure by Design: Private keys never stored, only derived temporarily
- Migration Ready: Clear upgrade path to SoftHSM when ready
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ Vercel Key Management │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Environment Variables API Functions Database │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ │ │ │ │ │ │
│ │ PLINGS_MASTER_ │ ───► │ HD Wallet │ │ Public Keys │ │
│ │ KEY (Base58) │ │ Derivation │──►│ Only │ │
│ │ │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Private Key │ │
│ │ (Discarded) │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
HD Wallet Structure
Plings HD Wallet Hierarchy
Master Key: m/44'/501'/[wallet_version]'/
├── Manufacturer: m/44'/501'/[wallet]'/[manufacturer]'/
│ ├── Category: m/44'/501'/[wallet]'/[manufacturer]'/[category]'/
│ │ ├── Class: m/44'/501'/[wallet]'/[manufacturer]'/[category]'/[class]'/
│ │ │ ├── Batch: m/44'/501'/[wallet]'/[manufacturer]'/[category]'/[class]'/[batch]'/
│ │ │ │ └── Instance: .../[instance_number]
Example HD Paths
// Coca-Cola Classic batch -2-5847, identifier 90000
const path = "m/44'/501'/1'/2'/3'/1'/5847'/90000";
// Plings generic sticker, batch 1, identifier 1
const path = "m/44'/501'/1'/1'/1'/1'/1'/1";
// IKEA furniture category, class -3, batch 2024, identifier 158
const path = "m/44'/501'/1'/3'/2'/3'/2024'/158";
Implementation Guide
Step 1: Environment Setup
Generate Master Key
#!/bin/bash
# generate_master_key.sh - Generate a new master key for production
# Method 1: Using Node.js (recommended)
node -e "
const crypto = require('crypto');
const bs58 = require('bs58');
console.log('Generating new master key...');
const masterKey = crypto.randomBytes(32);
const base58Key = bs58.encode(masterKey);
console.log('Master Key (Base58):', base58Key);
console.log('Key Length:', base58Key.length, 'characters');
console.log('');
console.log('Add this to your Vercel environment variables:');
console.log('PLINGS_MASTER_KEY=' + base58Key);
"
# Method 2: Using OpenSSL (alternative)
# openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'
Configure Vercel Environment
# Configure production environment
vercel env add PLINGS_MASTER_KEY production
# Configure preview environment (for staging)
vercel env add PLINGS_MASTER_KEY preview
# Configure development environment
vercel env add PLINGS_MASTER_KEY development
# Verify environment variables
vercel env ls
Step 2: HD Wallet Implementation
Core HD Wallet Library
// lib/hd-wallet.js - Core HD wallet implementation
import crypto from 'crypto';
import bs58 from 'bs58';
import { ed25519 } from '@noble/curves/ed25519';
import { createHmac } from 'crypto';
class PlingsHDWallet {
constructor(masterKey) {
this.masterKey = typeof masterKey === 'string' ? bs58.decode(masterKey) : masterKey;
this.curve = ed25519;
}
/**
* Derive a key for a specific HD path
* @param {string} path - HD derivation path (e.g., "m/44'/501'/1'/1'/1'/1'/1'/1")
* @returns {Object} Key pair with private and public keys
*/
deriveKey(path) {
// Remove 'm/' prefix if present
const cleanPath = path.replace(/^m\//, '');
const components = cleanPath.split('/');
let currentKey = this.masterKey;
let currentChainCode = crypto.randomBytes(32); // In production, use proper chain code
for (const component of components) {
const isHardened = component.endsWith("'");
const index = parseInt(component.replace("'", ''));
if (isNaN(index)) {
throw new Error(`Invalid path component: ${component}`);
}
const result = this.deriveChildKey(currentKey, currentChainCode, index, isHardened);
currentKey = result.key;
currentChainCode = result.chainCode;
}
return {
privateKey: currentKey,
publicKey: this.curve.getPublicKey(currentKey),
path: path
};
}
/**
* Derive a child key using HMAC-SHA512
* @param {Uint8Array} parentKey - Parent private key
* @param {Uint8Array} chainCode - Parent chain code
* @param {number} index - Child index
* @param {boolean} hardened - Whether to use hardened derivation
* @returns {Object} Child key and chain code
*/
deriveChildKey(parentKey, chainCode, index, hardened) {
const indexBuffer = Buffer.alloc(4);
indexBuffer.writeUInt32BE(hardened ? index + 0x80000000 : index);
let data;
if (hardened) {
data = Buffer.concat([Buffer.from([0x00]), parentKey, indexBuffer]);
} else {
const publicKey = this.curve.getPublicKey(parentKey);
data = Buffer.concat([Buffer.from(publicKey), indexBuffer]);
}
const hmac = createHmac('sha512', chainCode);
hmac.update(data);
const hash = hmac.digest();
const childKey = hash.slice(0, 32);
const childChainCode = hash.slice(32, 64);
return {
key: childKey,
chainCode: childChainCode
};
}
/**
* Get public key in various formats
* @param {Uint8Array} publicKey - Raw public key
* @returns {Object} Public key in different formats
*/
formatPublicKey(publicKey) {
return {
raw: publicKey,
hex: Buffer.from(publicKey).toString('hex'),
base58: bs58.encode(publicKey),
base64: Buffer.from(publicKey).toString('base64')
};
}
/**
* Sign a message with a derived key
* @param {string} message - Message to sign
* @param {Uint8Array} privateKey - Private key to sign with
* @returns {Object} Signature in various formats
*/
signMessage(message, privateKey) {
const messageBytes = Buffer.from(message, 'utf8');
const signature = this.curve.sign(messageBytes, privateKey);
return {
signature: signature,
hex: Buffer.from(signature).toString('hex'),
base58: bs58.encode(signature),
base64: Buffer.from(signature).toString('base64')
};
}
/**
* Verify a signature
* @param {string} message - Original message
* @param {Uint8Array} signature - Signature to verify
* @param {Uint8Array} publicKey - Public key to verify against
* @returns {boolean} Whether signature is valid
*/
verifySignature(message, signature, publicKey) {
const messageBytes = Buffer.from(message, 'utf8');
return this.curve.verify(signature, messageBytes, publicKey);
}
}
export default PlingsHDWallet;
Batch Generation Service
// lib/batch-generator.js - Batch identifier generation
import PlingsHDWallet from './hd-wallet.js';
class BatchGenerator {
constructor() {
this.wallet = new PlingsHDWallet(process.env.PLINGS_MASTER_KEY);
}
/**
* Generate a batch of identifiers
* @param {Object} params - Batch generation parameters
* @returns {Array} Array of generated identifiers
*/
async generateBatch({
manufacturer,
category,
classId,
batch,
quantity,
walletVersion = 1
}) {
const identifiers = [];
console.log(`🏭 Generating batch: ${manufacturer}.${category}.C${classId}.${batch} (${quantity} items)`);
for (let i = 1; i <= quantity; i++) {
const path = `m/44'/501'/${walletVersion}'/${manufacturer}'/${category}'/${classId}'/${batch}'/${i}`;
try {
const keyPair = this.wallet.deriveKey(path);
const publicKeyFormatted = this.wallet.formatPublicKey(keyPair.publicKey);
identifiers.push({
instanceNumber: i,
hdPath: path,
publicKey: publicKeyFormatted.base58,
publicKeyHex: publicKeyFormatted.hex,
humanReadablePath: `${manufacturer}.${category}.C${classId}.${batch}.${String(i).padStart(5, '0')}`,
// Private key is NOT included - discarded after use
});
// Clear private key from memory immediately
keyPair.privateKey.fill(0);
} catch (error) {
console.error(`❌ Error generating identifier ${i}:`, error.message);
throw error;
}
}
console.log(`✅ Generated ${identifiers.length} identifiers`);
return identifiers;
}
/**
* Generate QR code data for identifiers
* @param {Array} identifiers - Array of identifier objects
* @returns {Array} Array with QR code data
*/
generateQRCodes(identifiers) {
return identifiers.map(identifier => ({
...identifier,
qrCodeData: {
version: 1,
publicKey: identifier.publicKey,
path: identifier.humanReadablePath,
verificationUrl: `https://verify.plings.io/${identifier.publicKey}`
}
}));
}
/**
* Sign batch metadata for audit trail
* @param {Array} identifiers - Generated identifiers
* @param {Object} metadata - Batch metadata
* @returns {Object} Signed batch data
*/
signBatch(identifiers, metadata) {
const batchData = {
metadata,
identifiers: identifiers.map(id => ({
instanceNumber: id.instanceNumber,
publicKey: id.publicKey,
hdPath: id.hdPath
})),
timestamp: new Date().toISOString(),
generatedBy: 'plings-vercel-key-management'
};
// Sign with first identifier's key for audit trail
const firstKeyPath = identifiers[0].hdPath;
const signingKey = this.wallet.deriveKey(firstKeyPath);
const batchSignature = this.wallet.signMessage(
JSON.stringify(batchData),
signingKey.privateKey
);
// Clear signing key from memory
signingKey.privateKey.fill(0);
return {
...batchData,
signature: batchSignature.base58,
signedWith: firstKeyPath
};
}
}
export default BatchGenerator;
Step 3: API Implementation
Identifier Generation API
// api/identifiers/generate.js - Generate identifier batch
import BatchGenerator from '../../lib/batch-generator.js';
import { storeIdentifierBatch } from '../../lib/database.js';
export default async function handler(req, res) {
if (req.method !== 'POST') {
return res.status(405).json({ error: 'Method not allowed' });
}
const { manufacturer, category, classId, batch, quantity } = req.body;
// Validate input
if (!manufacturer || !category || !classId || !batch || !quantity) {
return res.status(400).json({
error: 'Missing required fields',
required: ['manufacturer', 'category', 'classId', 'batch', 'quantity']
});
}
if (quantity > 10000) {
return res.status(400).json({
error: 'Batch too large',
maxQuantity: 10000
});
}
try {
const generator = new BatchGenerator();
// Generate identifiers
const identifiers = await generator.generateBatch({
manufacturer,
category,
classId,
batch,
quantity
});
// Generate QR codes
const identifiersWithQR = generator.generateQRCodes(identifiers);
// Sign batch for audit trail
const signedBatch = generator.signBatch(identifiersWithQR, {
manufacturer,
category,
classId,
batch,
quantity,
requestedBy: req.headers['user-id'] || 'unknown'
});
// Store in database (public keys only)
await storeIdentifierBatch(signedBatch);
return res.json({
success: true,
batch: {
manufacturer,
category,
classId,
batch,
quantity,
identifiers: identifiersWithQR
},
signature: signedBatch.signature,
generatedAt: signedBatch.timestamp
});
} catch (error) {
console.error('❌ Batch generation error:', error);
return res.status(500).json({
error: 'Internal server error',
message: error.message
});
}
}
Identifier Verification API
// api/identifiers/verify.js - Verify identifier authenticity
import PlingsHDWallet from '../../lib/hd-wallet.js';
import { getIdentifierByPublicKey } from '../../lib/database.js';
export default async function handler(req, res) {
if (req.method !== 'POST') {
return res.status(405).json({ error: 'Method not allowed' });
}
const { publicKey, signature, message } = req.body;
if (!publicKey) {
return res.status(400).json({ error: 'Public key required' });
}
try {
// Get identifier from database
const identifier = await getIdentifierByPublicKey(publicKey);
if (!identifier) {
return res.json({
valid: false,
reason: 'Unknown identifier'
});
}
// If signature and message provided, verify signature
let signatureValid = null;
if (signature && message) {
const wallet = new PlingsHDWallet(process.env.PLINGS_MASTER_KEY);
const publicKeyBytes = Buffer.from(publicKey, 'base58');
const signatureBytes = Buffer.from(signature, 'base58');
signatureValid = wallet.verifySignature(message, signatureBytes, publicKeyBytes);
}
return res.json({
valid: true,
identifier: {
publicKey: identifier.publicKey,
humanReadablePath: identifier.humanReadablePath,
hdPath: identifier.hdPath,
manufacturer: identifier.manufacturer,
category: identifier.category,
classId: identifier.classId,
batch: identifier.batch,
instanceNumber: identifier.instanceNumber
},
signatureValid,
verifiedAt: new Date().toISOString()
});
} catch (error) {
console.error('❌ Verification error:', error);
return res.status(500).json({
error: 'Internal server error',
message: error.message
});
}
}
Step 4: Database Schema
Database Tables
-- PostgreSQL schema for identifier storage
CREATE TABLE identifier_batches (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
manufacturer INTEGER NOT NULL,
category INTEGER NOT NULL,
class_id INTEGER NOT NULL,
batch INTEGER NOT NULL,
quantity INTEGER NOT NULL,
wallet_version INTEGER DEFAULT 1,
signature TEXT NOT NULL,
signed_with TEXT NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
created_by UUID,
metadata JSONB
);
CREATE TABLE identifiers (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
batch_id UUID NOT NULL REFERENCES identifier_batches(id),
instance_number INTEGER NOT NULL,
hd_path TEXT NOT NULL,
public_key TEXT NOT NULL UNIQUE,
public_key_hex TEXT NOT NULL,
human_readable_path TEXT NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
-- Constraints
CONSTRAINT unique_batch_instance
UNIQUE (batch_id, instance_number),
CONSTRAINT unique_hd_path
UNIQUE (hd_path),
-- Indexes
CREATE INDEX idx_identifiers_public_key ON identifiers(public_key),
CREATE INDEX idx_identifiers_batch_id ON identifiers(batch_id),
CREATE INDEX idx_identifiers_hd_path ON identifiers(hd_path)
);
-- Audit trail table
CREATE TABLE identifier_operations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
operation_type TEXT NOT NULL, -- 'generate', 'verify', 'sign'
identifier_id UUID REFERENCES identifiers(id),
public_key TEXT,
metadata JSONB,
created_at TIMESTAMP DEFAULT NOW(),
created_by UUID,
ip_address INET,
user_agent TEXT
);
Database Operations
// lib/database.js - Database operations
import { createClient } from '@supabase/supabase-js';
const supabase = createClient(
process.env.SUPABASE_URL,
process.env.SUPABASE_SERVICE_KEY
);
export async function storeIdentifierBatch(signedBatch) {
const { metadata, identifiers, signature, signedWith, timestamp } = signedBatch;
// Insert batch record
const { data: batch, error: batchError } = await supabase
.from('identifier_batches')
.insert({
manufacturer: metadata.manufacturer,
category: metadata.category,
class_id: metadata.classId,
batch: metadata.batch,
quantity: metadata.quantity,
wallet_version: 1,
signature: signature,
signed_with: signedWith,
metadata: metadata
})
.select()
.single();
if (batchError) {
throw new Error(`Batch creation failed: ${batchError.message}`);
}
// Insert identifiers
const identifierRows = identifiers.map(identifier => ({
batch_id: batch.id,
instance_number: identifier.instanceNumber,
hd_path: identifier.hdPath,
public_key: identifier.publicKey,
public_key_hex: identifier.publicKeyHex,
human_readable_path: identifier.humanReadablePath
}));
const { error: identifierError } = await supabase
.from('identifiers')
.insert(identifierRows);
if (identifierError) {
throw new Error(`Identifier creation failed: ${identifierError.message}`);
}
// Log operation
await supabase
.from('identifier_operations')
.insert({
operation_type: 'generate',
metadata: {
batch_id: batch.id,
quantity: metadata.quantity,
timestamp: timestamp
}
});
return batch;
}
export async function getIdentifierByPublicKey(publicKey) {
const { data, error } = await supabase
.from('identifiers')
.select(`
*,
batch:identifier_batches(*)
`)
.eq('public_key', publicKey)
.single();
if (error) {
throw new Error(`Identifier lookup failed: ${error.message}`);
}
// Log verification
await supabase
.from('identifier_operations')
.insert({
operation_type: 'verify',
public_key: publicKey,
metadata: { timestamp: new Date().toISOString() }
});
return data;
}
Security Considerations
Security Model
What’s Protected
- Master Key Security:
- Encrypted at rest by Vercel infrastructure
- Only accessible to authorized team members
- Never transmitted in API responses
- Managed through wallet versioning (not rotated quarterly)
- Private Key Security:
- Generated on-demand, never stored
- Cleared from memory immediately after use
- Not transmitted over network
- Derived using cryptographically secure methods
- Database Security:
- Contains only public keys (no private keys)
- Audit trail for all operations
- Row-level security policies
- Encrypted at rest
Security Boundaries
- Vercel Team Access:
- Only team members with environment variable access
- Audit logs of environment variable changes
- Role-based access control
- API Function Security:
- Keys exist only during function execution
- No persistent storage of private keys
- Function isolation between requests
- Network Security:
- HTTPS for all API calls
- No key material in URLs or logs
- Rate limiting on key generation
Best Practices
Key Management
// Security best practices in code
class SecureKeyManager {
constructor(masterKey) {
this.masterKey = masterKey;
// Clear master key from arguments
arguments[0] = null;
}
deriveKey(path) {
const keyPair = this.wallet.deriveKey(path);
// Use key immediately, then clear
const result = this.processKey(keyPair);
// Clear private key from memory
keyPair.privateKey.fill(0);
return result;
}
processKey(keyPair) {
// Process key (sign, generate public key, etc.)
const publicKey = keyPair.publicKey;
// Return only public information
return {
publicKey: Buffer.from(publicKey).toString('base58'),
// Private key is NOT returned
};
}
}
Environment Security
# Environment variable management
# 1. Use separate keys for different environments
PLINGS_MASTER_KEY_DEV=<dev_key>
PLINGS_MASTER_KEY_STAGING=<staging_key>
PLINGS_MASTER_KEY_PROD=<prod_key>
# 2. Enable audit logging
VERCEL_LOG_LEVEL=info
AUDIT_LOG_ENABLED=true
# 3. Rate limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=100
RATE_LIMIT_BATCH_SIZE_MAX=1000
API Security
// api/middleware/security.js - Security middleware
export function securityMiddleware(req, res, next) {
// 1. Rate limiting
const rateLimitResult = checkRateLimit(req.ip);
if (!rateLimitResult.allowed) {
return res.status(429).json({
error: 'Rate limit exceeded',
retryAfter: rateLimitResult.retryAfter
});
}
// 2. Input validation
if (!validateInput(req.body)) {
return res.status(400).json({ error: 'Invalid input' });
}
// 3. Authentication
if (!authenticateRequest(req)) {
return res.status(401).json({ error: 'Unauthorized' });
}
// 4. Audit logging
logApiCall(req);
next();
}
Monitoring and Observability
Logging Strategy
// lib/logger.js - Structured logging
import winston from 'winston';
const logger = winston.createLogger({
level: process.env.LOG_LEVEL || 'info',
format: winston.format.combine(
winston.format.timestamp(),
winston.format.json()
),
transports: [
new winston.transports.Console(),
new winston.transports.File({ filename: 'key-operations.log' })
]
});
export function logKeyOperation(operation, metadata) {
logger.info('Key operation', {
operation,
timestamp: new Date().toISOString(),
metadata: {
...metadata,
// Never log private keys
privateKey: undefined,
masterKey: undefined
}
});
}
export function logSecurityEvent(event, details) {
logger.warn('Security event', {
event,
details,
timestamp: new Date().toISOString(),
severity: 'medium'
});
}
Metrics Collection
// lib/metrics.js - Key operation metrics
class KeyManagementMetrics {
constructor() {
this.counters = {
keysGenerated: 0,
verificationsPerformed: 0,
errors: 0
};
this.timers = {
keyGenerationTime: [],
verificationTime: []
};
}
recordKeyGeneration(duration, batchSize) {
this.counters.keysGenerated += batchSize;
this.timers.keyGenerationTime.push(duration);
// Log metrics
console.log(`📊 Generated ${batchSize} keys in ${duration}ms`);
}
recordVerification(duration, success) {
this.counters.verificationsPerformed += 1;
this.timers.verificationTime.push(duration);
if (!success) {
this.counters.errors += 1;
}
}
getMetrics() {
return {
counters: this.counters,
averages: {
keyGenerationTime: this.average(this.timers.keyGenerationTime),
verificationTime: this.average(this.timers.verificationTime)
}
};
}
average(arr) {
return arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
}
}
export default new KeyManagementMetrics();
Migration Planning
Preparing for SoftHSM Migration
// lib/migration-support.js - Migration preparation
export class MigrationSupport {
constructor() {
this.currentTier = 'vercel';
this.targetTier = 'softhsm';
}
async prepareMigration() {
console.log('🔄 Preparing migration from Vercel to SoftHSM');
// 1. Export current configuration
const config = await this.exportCurrentConfig();
// 2. Validate key consistency
const validation = await this.validateKeyConsistency();
// 3. Create migration plan
const plan = await this.createMigrationPlan(config, validation);
return plan;
}
async exportCurrentConfig() {
return {
walletVersion: 1,
masterKeyExists: !!process.env.PLINGS_MASTER_KEY,
totalIdentifiers: await this.countIdentifiers(),
lastBatchGenerated: await this.getLastBatch(),
keyDerivationMethod: 'BIP32-Ed25519'
};
}
async validateKeyConsistency() {
// Test key derivation with known paths
const testPaths = [
"m/44'/501'/1'/1'/1'/1'/1'/1",
"m/44'/501'/1'/2'/3'/1'/5847'/90000"
];
const results = [];
for (const path of testPaths) {
const keyPair = new PlingsHDWallet(process.env.PLINGS_MASTER_KEY).deriveKey(path);
results.push({
path,
publicKey: Buffer.from(keyPair.publicKey).toString('base58'),
valid: true
});
}
return results;
}
}
Dual-Mode Operation
// lib/dual-mode.js - Support both Vercel and SoftHSM
export class DualModeKeyManager {
constructor() {
this.vercelMode = process.env.KEY_MANAGEMENT_MODE === 'vercel';
this.softhsmMode = process.env.KEY_MANAGEMENT_MODE === 'softhsm';
if (this.vercelMode) {
this.keyManager = new VercelKeyManager();
} else if (this.softhsmMode) {
this.keyManager = new SoftHSMKeyManager();
} else {
throw new Error('Invalid key management mode');
}
}
async deriveKey(path) {
const startTime = Date.now();
try {
const result = await this.keyManager.deriveKey(path);
// Log with mode information
console.log(`🔑 Key derived in ${this.vercelMode ? 'Vercel' : 'SoftHSM'} mode: ${Date.now() - startTime}ms`);
return result;
} catch (error) {
console.error(`❌ Key derivation failed in ${this.vercelMode ? 'Vercel' : 'SoftHSM'} mode:`, error);
throw error;
}
}
}
Testing
Unit Tests
// tests/hd-wallet.test.js - HD wallet testing
import { describe, it, expect, beforeEach } from 'vitest';
import PlingsHDWallet from '../lib/hd-wallet.js';
describe('PlingsHDWallet', () => {
let wallet;
const testMasterKey = 'test-master-key-base58-encoded';
beforeEach(() => {
wallet = new PlingsHDWallet(testMasterKey);
});
it('should derive consistent keys for same paths', () => {
const path = "m/44'/501'/1'/1'/1'/1'/1'/1";
const key1 = wallet.deriveKey(path);
const key2 = wallet.deriveKey(path);
expect(key1.publicKey).toEqual(key2.publicKey);
expect(key1.path).toBe(path);
});
it('should derive different keys for different paths', () => {
const path1 = "m/44'/501'/1'/1'/1'/1'/1'/1";
const path2 = "m/44'/501'/1'/1'/1'/1'/1'/2";
const key1 = wallet.deriveKey(path1);
const key2 = wallet.deriveKey(path2);
expect(key1.publicKey).not.toEqual(key2.publicKey);
});
it('should sign and verify messages correctly', () => {
const path = "m/44'/501'/1'/1'/1'/1'/1'/1";
const message = 'test message';
const keyPair = wallet.deriveKey(path);
const signature = wallet.signMessage(message, keyPair.privateKey);
const isValid = wallet.verifySignature(message, signature.signature, keyPair.publicKey);
expect(isValid).toBe(true);
});
});
Integration Tests
// tests/api.test.js - API integration tests
import { describe, it, expect } from 'vitest';
import request from 'supertest';
import app from '../pages/api/app.js';
describe('API Integration', () => {
it('should generate a batch of identifiers', async () => {
const response = await request(app)
.post('/api/identifiers/generate')
.send({
manufacturer: 1,
category: 1,
classId: 1,
batch: 1,
quantity: 10
});
expect(response.status).toBe(200);
expect(response.body.success).toBe(true);
expect(response.body.batch.identifiers).toHaveLength(10);
expect(response.body.batch.identifiers[0]).toHaveProperty('publicKey');
expect(response.body.batch.identifiers[0]).toHaveProperty('hdPath');
});
it('should verify identifier authenticity', async () => {
// First generate an identifier
const generateResponse = await request(app)
.post('/api/identifiers/generate')
.send({
manufacturer: 1,
category: 1,
classId: 1,
batch: 1,
quantity: 1
});
const publicKey = generateResponse.body.batch.identifiers[0].publicKey;
// Then verify it
const verifyResponse = await request(app)
.post('/api/identifiers/verify')
.send({ publicKey });
expect(verifyResponse.status).toBe(200);
expect(verifyResponse.body.valid).toBe(true);
expect(verifyResponse.body.identifier.publicKey).toBe(publicKey);
});
});
Conclusion
This Vercel Key Management implementation provides:
- Immediate Production Readiness: Deploy in under 24 hours
- Zero Infrastructure Cost: No additional services required
- Security Best Practices: Private keys never stored, audit trails maintained
- Scalability: Supports unlimited identifier generation
- Migration Ready: Clear upgrade path to SoftHSM and Hardware HSM
The implementation enables Plings to launch immediately while maintaining the architectural flexibility to upgrade security as the business scales.
For migration to the next tier, see SoftHSM Migration Guide.
Next Steps:
- Deploy to Vercel with environment variables
- Test with small identifier batches
- Monitor performance and security metrics
- Plan migration to SoftHSM when ready