Xwallet: Verifiable Credential Infrastructure

Executive Summary

Xwallet is verifiable credential infrastructure designed for microsecond operations. Every credential flows through a deterministic pipeline: issue, serialize, pad, HMAC-authenticate, XorIDA-split. Reconstruction reverses the pipeline with cryptographic integrity checks at every stage.

Nine built-in credential schemas cover government, education, health, finance, and professional domains. Signing functions are injected — xWallet handles the credential crypto pipeline, not key management. Your application provides the signing function; xWallet provides everything else.

Selective disclosure operates at the attribute level. When a verifier requests specific attributes, xWallet reconstructs only the requested fields. A relying party checking age verification never sees the full credential. The holder controls what is revealed, and the verifier receives a cryptographic proof that the disclosed attributes are authentic.

xWallet's ~35 microsecond credential reconstruction is the foundation of xID's ~50 microsecond ephemeral presentation window. When xID derives a per-verifier ephemeral DID and needs to present a credential, xWallet reconstructs from shares, verifies HMAC integrity, selects requested attributes, and packages the disclosure — all before xID signs with the ephemeral key and purges.

Developer Experience

Xwallet provides real-time progress tracking and structured error codes to help developers build reliable credential systems.

Progress Callbacks

All credential operations support onProgress callbacks for tracking multi-stage operations — especially useful for XorIDA splitting and reconstruction.

const result = await wallet.storeCredential(credential, {
  onProgress: async (event) => {
    switch (event.stage) {
      case 'serializing':
        console.log('Serializing credential...');
        break;
      case 'splitting':
        console.log(`XorIDA split: share ${event.current}/${event.total}`);
        break;
      case 'storing':
        console.log('Writing shares to storage...');
        break;
      case 'complete':
        console.log('Credential stored successfully');
        break;
    }
  }
});

Structured Error Handling

Xwallet uses a Result<T, E> pattern with detailed error structures. Every error includes a machine-readable code, human-readable message, actionable hint, and field attribution.

interface ErrorDetail {
  code: string;         // e.g., 'INVALID_SCHEMA'
  message: string;      // Human-readable description
  hint?: string;        // Actionable suggestion
  field?: string;       // Field that caused the error
  docs?: string;        // Documentation URL
}

Error Categories

Xwallet organizes error codes across 6 categories:

The Problem

Digital credentials are stored in centralized databases protected by encryption keys. A single key compromise exposes millions of records. Existing credential libraries are not designed for the microsecond reconstruct-disclose-purge cycle that unlinkable identity demands.

Three Infrastructure Failures

1. Key-dependent security. Every existing credential wallet encrypts data with a single key. Compromise that key — through theft, side-channel attack, or a future quantum computer — and every credential is exposed. This is the harvest-now-decrypt-later threat: adversaries collect encrypted credential stores today and decrypt them when quantum computers arrive.

2. No tamper-evident audit trail. When a credential is issued, stored, presented, or revoked, there is no cryptographic chain linking these events. Regulated industries (healthcare, finance, government) require proof that credentials were handled correctly. Most credential systems offer server-side logs that are mutable, deletable, and disconnected from the credential crypto.

3. Not designed for microsecond operations. Ephemeral identity requires reconstructing a credential, selecting attributes, and verifying integrity within a ~50 microsecond window. Existing credential libraries are built for millisecond-to-second response times. They cannot serve as the engine for a pipeline that must reconstruct, disclose, and purge before the next presentation.

Infrastructure Comparison

Use Cases

Xwallet enables verifiable credential infrastructure across government, education, healthcare, and finance — with information-theoretic security and microsecond operations.

Architecture

Credentials flow through a deterministic pipeline: issue, serialize, pad, authenticate, split, and store. Retrieval reverses the pipeline with HMAC verification at every stage.

Credential Pipeline

Implementation: 8 Core Modules

The xWallet implementation is organized into 8 focused modules, each handling a distinct stage of the credential lifecycle:

Total: 2,405 lines of code across 8 modules. ~140 tests covering all credential lifecycle operations. All modules use the Result<T, E> pattern — no thrown exceptions. Pure functions with side effects isolated at module boundaries.

Built-in Schemas

Nine credential schemas cover common use cases across industries:

Cross-ACI Integration

Xwallet composes with Xid, Xstore, Xprove, and Xlink to enable complete verifiable credential workflows with ephemeral identity, distributed storage, and verifiable computation.

Xwallet + Xid: Ephemeral Credential Presentation

When an ephemeral presentation occurs, the xWallet retrieve pipeline feeds directly into xID's ephemeral derivation. The combined flow: xWallet reconstruct (~35µs) → HMAC verify → Unpad + deserialize → HKDF derive (~5µs) → Ed25519 keygen (~8µs) → Select attributes + sign (~2µs) → Purge (~1µs). Total: ~50µs. The credential never exists in decrypted form for longer than it takes to disclose the requested attributes.

Xwallet + Xstore: Geographic Credential Distribution

Xstore routes XorIDA credential shares to pluggable backends (local, S3, IPFS, HTTP). Share 1 → AWS us-east-1. Share 2 → Azure eu-west-1. Compromising one datacenter reveals nothing. Xwallet reconstruction works across any Xstore backend combination.

Xwallet + Xprove: Verifiable Credential Computation

Xprove generates zero-knowledge proofs that a credential meets specific criteria without revealing the credential itself. Example: prove age > 21 without disclosing birthdate. Xwallet provides the credential input; Xprove provides the cryptographic proof. Verifier receives proof of predicate satisfaction without seeing any credential attribute.

Xwallet + Xlink: Authenticated Credential Exchange

Xlink wraps Xwallet presentations in authenticated envelopes with Ed25519 signatures and hybrid PQ key exchange. Credentials transmitted between systems inherit Xlink's DID-based authentication, replay protection, and scope validation. No separate authentication layer required.

Complete Credential Flow

End-to-end credential lifecycle: issuance → storage → selective disclosure → verification → revocation. Each step cryptographically linked via HMAC-chained audit trail.

// 1. Issue credential
const credential = await wallet.issueCredential({
  schemaId: 'government-id',
  subject: did,
  attributes: {
    fullName: 'Jane Smith',
    dateOfBirth: '1990-01-15',
    nationality: 'US',
    idNumber: 'ABC123456'
  },
  signFn: async (data) => ed25519.sign(issuerKey, data)
});

// 2. Store with XorIDA split
const handle = await wallet.storeCredential(credential);

// 3. Create selective disclosure presentation
const presentation = await wallet.createPresentation(handle, {
  requestedAttributes: ['nationality'] // Only reveal nationality
});

// 4. Verifier checks presentation
const valid = await wallet.verifyPresentation(presentation);

// 5. Revoke credential if needed
await wallet.revokeCredential(credential.id);

Every operation is logged to the HMAC-chained audit trail. Query the audit log to retrieve the complete lifecycle history for any credential. Chain integrity verification detects any tampering.

Security

Xwallet's security is grounded in information-theoretic credential splitting, HMAC integrity verification at every pipeline stage, and tamper-evident audit chains. No keys required for storage security.

Information-Theoretic Storage

Every credential is XorIDA-split into k-of-n shares. An attacker who compromises fewer than k shares learns nothing about the credential — not computationally hard to break, but mathematically impossible. This is unconditional security: it holds even against adversaries with unbounded computational power.

HMAC Integrity Verification

Every credential share carries an HMAC-SHA256 tag computed over the serialized, padded payload. Before reconstruction, every share's HMAC is verified. If any HMAC fails, reconstruction aborts. Tampered shares are detected before they can corrupt the credential.

Tamper-Evident Audit Chain

Every credential lifecycle event (issued, stored, presented, revoked) is logged with a timestamp and HMAC. Each event's HMAC includes the previous event's HMAC. Breaking the chain is cryptographically detectable. Audit logs satisfy HIPAA, DORA, and eIDAS regulatory requirements.

Selective Disclosure Privacy

Only requested attributes are included in presentations. A verifier requesting age verification never sees the holder's full name, address, or ID number. The presentation includes a cryptographic proof (issuer signature) that the disclosed attributes are authentic, without revealing unrequested data.

Revocation Registry Integrity

The revocation registry is append-only with HMAC-chain tamper detection. Once a credential is revoked, it cannot be un-revoked without breaking the chain. Verifiers check the registry before accepting any presentation.

Benchmarks

At typical credential sizes (<1 KB), XorIDA splitting is 2–11x faster than AES-256-GCM. The full retrieve pipeline completes in ~60 microseconds.

XorIDA Split Performance

Full Pipeline Performance

Store pipeline breakdown: Serialize (5µs) + Pad (2µs) + HMAC (8µs) + XorIDA split (35µs) + Write shares (30µs) = ~80µs total.
Retrieve pipeline breakdown: Read shares (15µs) + XorIDA reconstruct (35µs) + HMAC verify (8µs) + Unpad (2µs) = ~60µs total.

Honest Limitations

Xwallet is credential infrastructure, not a complete consumer wallet. It provides the issuance, storage, presentation, and revocation pipeline. Consumer-facing features are delegated to products like xID.

Not a Consumer Wallet

Xwallet has no user interface, no import flows, no backup mechanisms. It is the engine that powers consumer wallets. Products like xID build UX, import flows, ephemeral identity, and backup on top of Xwallet's infrastructure.

Signing Functions Are Injected

Xwallet does not manage keys. Credential issuance requires a signing function. You are responsible for key generation, storage, and rotation. This is intentional: Xwallet focuses on credential crypto, not key management.

Schema Registry Is Not Global

The nine built-in schemas are local to your Xwallet instance. There is no global registry. If you need a custom schema, you register it locally. Interoperability between wallets requires schema coordination out-of-band.

No Automatic Revocation Checking

Verifiers must explicitly check the revocation registry when verifying presentations. Xwallet does not automatically reject revoked credentials during reconstruction. This is a design choice: reconstruction is a storage operation, not a verification operation.

XorIDA Crossover at ~1-2 KB

At credential sizes above ~1-2 KB, AES-256-GCM becomes faster than XorIDA splitting. For large credentials (e.g., diplomas with embedded high-resolution images), AES may be more performant. Xwallet defaults to XorIDA for information-theoretic security at typical credential sizes.

Full ACI Surface

Complete API reference for all 8 Xwallet modules. Every function is typed with Result<T, E> for structured error handling.

Credential Module

Schema Module

Store Module

Disclosure Module

Revocation Module

Audit Module

Error Taxonomy

Complete error code reference organized by module. Every error includes actionable hints and field attribution.

Schema Errors (SCH-xxx)

Credential Errors (CRD-xxx)

Storage Errors (STO-xxx)

Disclosure Errors (DSC-xxx)

Revocation Errors (REV-xxx)

Audit Errors (AUD-xxx)

Enterprise CLI

Self-hosted Xwallet management server for enterprise credential issuance, revocation, and audit. Part of the 21-CLI enterprise suite.

xwallet-cli Features

Endpoints

Docker Deployment

version: '3.8'
services:
  xwallet-cli:
    image: privateme/xwallet-cli:latest
    ports:
      - "4600:4600"
    environment:
      - XWALLET_PORT=4600
      - XWALLET_RATE_LIMIT=100
      - XWALLET_LOG_LEVEL=info
    volumes:
      - ./data:/data

Codebase Statistics

Xwallet is 2,405 lines of TypeScript across 8 modules. 140 tests covering all credential lifecycle operations. Zero npm dependencies.

Module Breakdown

Fast Onboarding: 3 Acceleration Levels

From zero-click code patterns to one-click deploy buttons, Xwallet offers three acceleration levels that reduce setup time from ~2 minutes to as low as ~15 seconds. Each level targets a different integration context.

Level 1: Zero-Click Accept (Lazy Wallet Initialization)

For trusted partner integrations, the lazy wallet pattern defers identity initialization until the first credential operation. No explicit init() call required — the wallet automatically generates its identity on first use and auto-accepts incoming connection requests from known partners.

import { Xwallet } from '@private.me/xwallet';

// Wallet generates identity on first operation
const wallet = await Xwallet.lazy({
  name: 'my-credentials',
  // Auto-accepts from XWALLET_INVITE_CODE env var
});

// First operation triggers identity generation automatically
const credential = await wallet.issue({
  type: 'employee-badge',
  attributes: {
    name: 'Alice Smith',
    employeeId: 'E12345',
    department: 'Engineering',
  },
});

if (credential.ok) {
  console.log('Credential issued:', credential.value.id);
}

Setup time: ~80 seconds (identity generation happens transparently during first operation)
Best for: Internal microservices, trusted partner integrations, development/testing

Level 2: One-Line CLI Setup (Invite-Based)

For new partner onboarding, the one-line CLI command accepts an invite code and automatically configures the entire Xwallet identity, schema registry, and connection in a single operation. No manual DID exchange, no configuration files.

// Partner sends you invite code: XWL-abc123def456
$ npx @private.me/xwallet-cli init --invite XWL-abc123def456

{
  "status": "initialized",
  "walletDid": "did:key:z6MksZP8ChwZYSNgozYq...",
  "name": "my-credentials",
  "schemas": [
    {
      "id": "employee-badge",
      "issuer": "did:key:z6MkIssuerDID...",
      "trusted": true
    }
  ],
  "elapsed_seconds": 2.3
}

Setup time: ~40 seconds (single command, no manual configuration)
Best for: Partner onboarding, external integrations, production deployments

Level 3: Deploy Button (One-Click Infrastructure)

For platform integrations, deploy buttons provide one-click infrastructure provisioning with Xwallet pre-configured. Clicking the button deploys a complete credential service with identity, endpoints, and schema registry already configured.

<!-- Add to your README.md or integration docs -->
[![Deploy to Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fprivate-me%2Fxwallet-starter&env=XWALLET_INVITE_CODE&envDescription=Paste%20your%20Xwallet%20invite%20code%20here&envLink=https%3A%2F%2Fdocs.private.me%2Fdocs%2Fxwallet)

// Deployed service includes:
// - Auto-generated Xwallet identity
// - Pre-configured schema registry from invite
// - Express middleware with credential endpoints
// - Health check and verification endpoints

Setup time: ~15 seconds (one click, zero configuration)
Best for: SaaS integrations, marketplace apps, rapid prototyping

Setup Time Comparison

Getting Started: Fastest Path

The recommended onboarding path depends on your integration context:

1. New to Xwallet? Start with a Deploy Button to see Xwallet running in production in ~15 seconds. Deploy the starter template, then explore the code.
2. Onboarding a partner? Send them a One-Line CLI invite code. They paste one command and are connected in ~40 seconds.
3. Internal microservices? Use Zero-Click Accept with lazy initialization. No setup time, identity generation happens transparently on first use.
4. Want full control? Follow the standard 2-minute setup flow with explicit schema registration and signing functions.

// 1. Click "Deploy to Vercel" button (~15 sec)
// 2. Paste invite code when prompted
// 3. Service deploys with Xwallet pre-configured
// 4. Clone the deployed repo to see the code:

git clone https://github.com/YOUR_USERNAME/xwallet-starter
cd xwallet-starter

// 5. Explore the three key files:
//    - api/issue.ts → Credential issuance endpoint
//    - api/verify.ts → Credential verification endpoint
//    - api/present.ts → Selective disclosure endpoint

Template Examples

All three starter templates are available in the packages/xwallet/templates/ directory: