Use Case: HD Wallet Identifier Creation

Overview

This document describes the HD Wallet (Hierarchical Deterministic Wallet) identifier creation system that enables cryptographically secure, verifiable, and deterministic identifier generation for physical objects. The system uses a single Plings master key to ensure all identifiers are cryptographically verifiable as authentic Plings identifiers.

Three Core Scenarios

Plings Internal Testing: Generate generic tags for testing and development purposes
Manufacturer Batch Orders: Create identifiers for external manufacturers to print on their own tags
Organization Self-Service: Enable organizations to generate identifiers using delegated keys from the Plings master wallet

Business Value

Ecosystem Integrity: Single master key ensures no external generation of fake identifiers
Cryptographic Security: All identifiers cryptographically traceable to Plings master key
Batch Management: Path-based organization prevents collisions and enables audit trails
Offline Verification: Complete verification possible without network connectivity
Scalable Delegation: Organizations can generate own identifiers while maintaining Plings control

User Stories

Scenario 1: Plings Internal Testing

As a Plings admin, I want to generate generic test identifiers so that I can validate system functionality and create test objects without affecting production paths.

Scenario 2: Manufacturer Batch Orders

As a manufacturer, I want to order a batch of Plings identifiers so that I can print them on my own tags and ensure customers can verify authenticity.

Scenario 3: Organization Self-Service

As an organization member, I want to generate identifiers for my organization’s objects so that I can create authentic Plings identifiers while maintaining organizational control.

Cross-Scenario: Offline Verification

As anyone scanning a Plings identifier, I want to verify its authenticity without internet access so that I can confirm it’s a genuine Plings identifier even in remote locations.

Actors

Primary Actors

Individual User: Person creating identifiers for personal objects
Manufacturer: Company producing objects with authenticated identifiers
Consumer: Person verifying authenticity of purchased products
System Administrator: Managing organizational keys and permissions

Secondary Actors

Mobile App: Scanning and verification interface
Manufacturing System: Bulk identifier generation and integration
QR/NFC Generator: Physical identifier creation tools

Preconditions

For Basic Usage

User has valid account with organization membership
System has cryptographic libraries installed (BIP32 support)
Database has PlingsIdentifier schema with HD wallet fields

For Manufacturing

Organization has generated master key through admin interface
Manufacturer has defined ObjectClass with AnchorKey
Production system has API integration capabilities
QR/NFC generation hardware is available

For Verification

Mobile device has scanning capability (camera/NFC)
Cryptographic validation libraries are available offline
User has access to manufacturer’s public keys

Workflow Diagrams

Basic Identifier Generation

flowchart TD A[User Opens Object Creation] --> B{Need Identifier?} B -->|Yes| C[Click 'Generate Tag' Button] B -->|No| D[Create Object Without Tag] C --> E[Call createGenericTag API] E --> F[Generate Random InstanceKey] F --> G[Create 4-char ShortCode] G --> H[Store PlingsIdentifier in Neo4j] H --> I[Return InstanceKey + ShortCode] I --> J[Display Tag Info to User] J --> K[Assign Tag to Object] K --> L[Complete Object Creation] style A fill:#e1f5fe style C fill:#fff3e0 style E fill:#f3e5f5 style J fill:#e8f5e8 style L fill:#e8f5e8

HD Wallet Manufacturing Workflow

flowchart TD A[Admin Generates Master Key] --> B[Create ObjectClass with AnchorKey] B --> C[Manufacturing System Integration] C --> D[Batch Identifier Generation] D --> E[QR Code Production] E --> F[Product Assembly] F --> G[Quality Control] G --> H[Product Distribution] H --> I[Consumer Scans QR] I --> J{Offline Verification?} J -->|Yes| K[Cryptographic Validation] J -->|No| L[Database Lookup] K --> M[Display Verification Result] L --> M M --> N[Product Authentication Complete] style A fill:#ffebee style D fill:#fff3e0 style K fill:#e8f5e8 style N fill:#e8f5e8

Use Case Flows

Flow 1: Plings Internal Testing

1. Allocate Test Path

Entry Point: Plings admin needs to create test identifiers
Path Allocation: Reserve new path in testing range (e.g., 1.2.1 for test batch)
Registry Update: Record path allocation with purpose, quantity, date

2. Generate Test Batch

API Call: createBatchIdentifiers with allocated path
Derivation: All identifiers derive from Plings master key via test path
Storage: Store PlingsIdentifier nodes in Neo4j with test metadata
Output: Return array of instanceKeys, shortCodes, and QR URLs

3. Test Integration

Object Assignment: Use test identifiers for system validation
Verification Testing: Validate cryptographic chains work correctly
Cleanup: Optionally mark test identifiers as inactive after testing

Flow 2: Manufacturer Batch Orders

1. Manufacturer Onboarding

Path Registration: Allocate manufacturer-specific path range (e.g., 1.3.x)
Contract Setup: Define batch sizes, pricing, delivery methods
API Access: Provide manufacturer with batch ordering API credentials

2. Batch Order Processing

Order Placement: Manufacturer requests batch via API or admin interface
Path Assignment: Allocate unique sub-path for this batch (e.g., 1.3.5)
Identifier Generation: Create identifiers deriving from Plings master via manufacturer path
CSV Export: Generate spreadsheet with instanceKeys, shortCodes, QR URLs, paths

3. Physical Production

Tag Printing: Manufacturer prints QR codes/NFC tags using CSV data
Quality Control: Verify scannable codes and correct URL format
Distribution: Tags ready for application to manufacturer’s products

Flow 3: Organization Self-Service

1. Organization Key Delegation (Admin Setup)

Path Allocation: Assign organization to specific path range (e.g., 2.x for IKEA)
Key Derivation: Derive organization private key from Plings master
Secure Distribution: Provide organization with their derived private key
Permission Setup: Configure what sub-paths organization can use

2. Organization Identifier Generation

Internal Process: Organization generates identifiers using their delegated key
Sub-path Management: Organization creates hierarchies within their allocated space
Direct Integration: Organization’s systems directly generate without Plings API
Audit Trail: Organization reports batch creation back to Plings registry

3. Verification and Control

Cryptographic Validation: All organization identifiers still verify against Plings master
Registry Synchronization: Periodic sync of organization’s path usage
Revocation Capability: Plings can invalidate organization keys if needed

4. Quality Control and Distribution

Verification Testing: Validate QR codes scan correctly and verify authentically
Supply Chain Integration: Track identifiers through distribution
Consumer Delivery: Products reach market with authenticated identifiers

Flow 3: Consumer Authentication

1. Product Scanning

Scan Initiation: Consumer scans QR code on product
URL Resolution: QR contains HD wallet URL with classKey and instanceKey
Verification Choice: System determines online vs offline verification

2. Cryptographic Verification (Offline)

Key Extraction: Parse classKey and instanceKey from URL
Derivation Validation: Verify instanceKey derives from classKey using BIP32
Manufacturer Lookup: Identify manufacturer from public key database
Authentication Result: Display verification status and product information

3. Enhanced Verification (Online)

Database Integration: Cross-reference with product database for additional info
Audit Logging: Record verification event for anti-counterfeiting tracking
Extended Information: Display rich product information and warranty details

Alternative Flows

A1: Batch Generation for Large Production

Trigger: Manufacturing run requires 1000+ identifiers Enhanced Workflow:

Planning Phase: Estimate batch size and timeline requirements
Batch Session: Create batch session with createBatchIdentifiers API
Progress Tracking: Monitor generation progress for large batches
Quality Assurance: Validate all identifiers meet cryptographic standards
Integration: Export identifiers to manufacturing systems

A2: Anti-Counterfeiting Detection

Trigger: Multiple products claim same identifier Detection Workflow:

Conflict Detection: System identifies duplicate identifier usage
Verification Challenge: Request OTP verification from claiming parties
Authenticity Determination: Validate legitimate owner through hidden verification
Response Action: Flag counterfeit identifiers and alert authorities

A3: Key Compromise Recovery

Trigger: Potential compromise of organizational master key Recovery Workflow:

Incident Response: Immediate revocation of compromised keys
New Key Generation: Create new organizational master key
Migration Planning: Plan transition for existing products
Consumer Communication: Notify consumers of security update

Technical Implementation

GraphQL Schema Extensions

# Basic identifier generation
mutation createGenericTag($batchSize: Int, $organizationId: ID!) {
  createGenericTag(batchSize: $batchSize, organizationId: $organizationId) {
    identifiers {
      instanceKey
      shortCode
      qrUrl
    }
    batchId
    generatedCount
  }
}

# HD wallet master key generation (admin only)
mutation generateMasterKey($organizationId: ID!, $keyMetadata: KeyMetadataInput!) {
  generateMasterKey(organizationId: $organizationId, keyMetadata: $keyMetadata) {
    masterKeyId
    publicKey
    derivationTemplate
    securityLevel
  }
}

# Manufacturer anchor key derivation
mutation deriveAnchorKey($masterKeyId: ID!, $derivationPath: String!, $classMetadata: ObjectClassInput!) {
  deriveAnchorKey(masterKeyId: $masterKeyId, derivationPath: $derivationPath, classMetadata: $classMetadata) {
    anchorKey
    objectClass {
      id
      name
      anchorKey
    }
    derivationProof
  }
}

# Batch instance key generation
mutation deriveInstanceKeys($anchorKeyId: ID!, $batchSize: Int!, $startIndex: Int) {
  deriveInstanceKeys(anchorKeyId: $anchorKeyId, batchSize: $batchSize, startIndex: $startIndex) {
    identifiers {
      instanceKey
      classKey
      derivationIndex
      qrUrl
      shortCode
    }
    batchMetadata {
      anchorKey
      totalGenerated
      cryptographicProof
    }
  }
}

# Offline verification
query validateKeyChain($instanceKey: String!, $classKey: String!, $derivationPath: String) {
  validateKeyChain(instanceKey: $instanceKey, classKey: $classKey, derivationPath: $derivationPath) {
    isValid
    manufacturer {
      name
      verified
    }
    derivationProof
    offlineCapable
  }
}

Database Schema Requirements

Neo4j Enhancements

// PlingsIdentifier with HD wallet support
CREATE (id:PlingsIdentifier {
  instanceKey: "Base58_encoded_instance_key",
  classKey: "Base58_encoded_class_key",           // Optional for generic tags
  derivationIndex: 123,                          // BIP32 index for manufacturing
  derivationPath: "m/1852'/1815'/0'/0/123",     // Full derivation path
  isManufacturerTag: true,                       // HD wallet vs generic
  qrUrl: "https://scan.plings.io/s?t=q&cp=...&i=...&p=...",
  shortCode: "CuUY",
  cryptographicProof: "signature_verification_data",
  created_at: datetime(),
  batch_id: "batch_session_uuid"
})

// ObjectClass with HD wallet anchor key
CREATE (class:ObjectClass {
  name: "ACME Mountain Bike",
  anchorKey: "Base58_encoded_public_key",
  derivationPath: "m/1852'/1815'/0'/0",
  manufacturer: "ACME Inc",
  pathTemplate: "acme.bikes.mtb",
  verification_enabled: true
})

PostgreSQL Additions

-- Organizational master keys
CREATE TABLE hd_wallet_keys (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID REFERENCES organizations(id),
  public_key TEXT NOT NULL,
  derivation_template TEXT NOT NULL,
  security_level TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  is_active BOOLEAN DEFAULT TRUE
);

-- Manufacturing batches
CREATE TABLE identifier_batches (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID REFERENCES organizations(id),
  batch_size INTEGER NOT NULL,
  generated_count INTEGER DEFAULT 0,
  batch_metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  completed_at TIMESTAMP
);

Security Considerations

Cryptographic Security

Entropy Quality: Use cryptographically secure random number generation
Key Storage: Private keys stored in Hardware Security Modules (HSM)
Derivation Standards: Follow BIP32/BIP44 standards for interoperability
Offline Verification: Enable authentication without network dependencies

Access Control

Master Key Access: Restrict to super-admin roles only
Organizational Isolation: Prevent cross-organization key access
Audit Logging: Comprehensive logging of all cryptographic operations
Rate Limiting: Prevent abuse of batch generation APIs

Success Criteria

Phase 1: Basic Generation

Generate secure identifiers for personal use
Support batch creation up to 100 identifiers
Integration with existing object creation workflow
Performance meets requirements (<200ms single, <3s batch)

Phase 2: HD Wallet Foundation

BIP32 master key generation and storage
AnchorKey derivation for ObjectClass creation
InstanceKey derivation with batch support
Cryptographic verification without database lookup

Phase 3: Manufacturing Integration

Support manufacturing batches of 1000+ identifiers
QR code generation with proper HD wallet URLs
Integration with production systems via API
Quality control validation for all generated identifiers

Phase 4: Security and Anti-Counterfeiting

Offline verification of product authenticity
Anti-counterfeiting detection and response
Security audit compliance for cryptographic implementation
HSM integration for maximum security

API Requirements: API Requirements - HD Wallet endpoint specifications
Implementation Plan: Implementation TODO - Development tracking
Core Systems: Plings Identifier Specification - Technical specification
Database Schema: Neo4j Core Schema - Data model
Tag Integration: Tag Scanning Integration - Existing tag system

Implementation Status

✅ Currently Available

Documentation: Comprehensive specification and use case documentation
Basic Infrastructure: Neo4j PlingsIdentifier nodes and IDENTIFIES relationships
API Foundation: GraphQL schema structure for tag assignment

🟡 In Development

Basic APIs: createGenericTag and createBatchIdentifiers for Phase 1
Implementation Planning: Detailed development roadmap and task breakdown
Database Design: Schema planning for HD wallet integration

❌ Planned Features

HD Wallet Implementation: BIP32 cryptographic key derivation
Manufacturing Workflows: Batch production and QR generation
Offline Verification: Cryptographic validation without network
Anti-Counterfeiting: Advanced security and fraud detection

Open Items

Select and integrate BIP32 Python library
Design HSM integration for secure key storage
Define manufacturer onboarding workflow
Create QR code generation specifications
Plan security audit and penetration testing

Last Updated: Thu Jul 10 10:56:46 CEST 2025 - Initial comprehensive use case documentation for HD wallet identifier creation system

Search Results: