xWallet: The Credential Engine Behind Ephemeral Identity

The Problem: Credential Infrastructure Has No Cryptographic Foundation

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. Key-dependent security has a defined expiry date.

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

The Solution: Information-Theoretic Credential Infrastructure

Every credential flows through a deterministic pipeline: issue, serialize, pad, HMAC-authenticate, XorIDA-split. Each credential is independently split. No single share contains enough to reconstruct any credential.

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.

Enabling Ephemeral Identity

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 is the engine that reconstructs from shares, verifies HMAC integrity, selects requested attributes, and packages the disclosure — all before xID signs with the ephemeral key and purges. Without microsecond-grade credential infrastructure, ephemeral identity is architecturally impossible.

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

Combined xWallet + xID Pipeline

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.

Binary Credential Format

[version:1][idLen:2][id][schemaIdLen:2][schemaId][issuerLen:2][issuer]
[subjectLen:2][subject][issuedAt:8][hasExpiry:1][expiresAt:8?]
[sigLen:2][signature][attrCount:2][...attributes]

// Attribute types
string(0)  number(1)  boolean(2)  bytes(3)

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 Credential Operations

ACI Surface

Schema registration, credential issuance, split storage, retrieval, selective disclosure, and revocation. The full credential lifecycle in six functions. Every function returns a Result<T, E>.

import { issueCredential, storeCredential } from '@private.me/xwallet';

// Issue a credential with injected signing function
const issued = await issueCredential({
  schemaId: 'government-id',
  issuerDid: 'did:key:z6Mk...',
  subjectDid: 'did:key:z6Mn...',
  attributes: {
    fullName: 'Jane Doe',
    dateOfBirth: '1990-03-15',
    nationality: 'US',
  },
  signingFn,  // injected — no key management baked in
});

// Store — serializes, pads, HMACs, XorIDA-splits into k-of-n shares
const stored = await storeCredential(issued.value);

// Retrieve — reconstructs from k shares, verifies HMAC, deserializes
const credential = await retrieveCredential(stored.value);

// Present — selective disclosure of requested attributes only
const presentation = await createPresentation({
  credential: credential.value,
  request: { attributes: ['dateOfBirth', 'nationality'] },
  signingFn,
});

// Or feed into xID ephemeral presentation pipeline:
// xWallet retrieves credential shares → xID derives ephemeral DID
// → signs with ephemeral key → purges all material

// 9 built-in schemas
getBuiltInSchemas();
// → government-id, drivers-license, passport, diploma,
//   health-certificate, vaccination-record, professional-license,
//   financial-kyc, insurance-policy

// Create and register custom schemas
const schema = createSchema('Employee Badge', [
  { name: 'name', type: 'string', required: true },
  { name: 'employeeId', type: 'string', required: true },
  { name: 'department', type: 'string', required: false },
]);
if (schema.ok) registerSchema(schema.value);

Use Cases

Infrastructure-perspective use cases aligned with xID's identity verticals. xWallet is the credential layer that makes each vertical possible.

Cross-ACI Composition

xWallet is the credential layer that other ACIs build on. Identity wallets, storage backends, audit proofs, and agent transport all compose with xWallet's credential pipeline.

Enhanced Identity with Xid

xWallet can optionally integrate with Xid to enable unlinkable credential presentation — verifiable for the specific verifier context, but uncorrelatable across different presentations or verifiers.

Three Identity Modes

How Ephemeral Presentation Works

In xWallet+ mode, each credential presentation derives a unique DID via HKDF from the holder's XorIDA-split master seed:

// Verifier requests credential
const presentation = await wallet.present({
  credential: medicalLicenseVC,
  verifier: 'did:key:z6Mk...', // Hospital DID
  ephemeral: true // Enable Xid integration
});

// Result: unique DID for this verifier + credential + epoch
presentation.holder // did:key:z6MkX... (ephemeral, ~50µs derivation)
// Same doctor presenting to different hospital → different DID
// Same doctor presenting next week → different DID (epoch rotation)

Key Benefits

Developer Experience

xWallet provides comprehensive progress callbacks, field-level error attribution, and actionable guidance across 43 error codes in 11 categories. Every operation surfaces real-time progress and specific recovery paths.

Progress Callbacks

All async operations emit granular progress events, enabling real-time UI updates during credential issuance, storage, retrieval, and presentation:

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

// Create wallet with W3C VC schema
const wallet = await WalletRegistry.createWallet({
  name: 'medical-licenses',
  schemaId: 'w3c-verifiable-credential', // Built-in W3C schema
  threshold: { k: 2, n: 3 } // 2-of-3 XorIDA split
});

// Issue credential with progress tracking
const result = await wallet.issueCredential({
  subject: 'did:key:z6MkhaXg...',
  claims: {
    '@context': ['https://www.w3.org/2018/credentials/v1'],
    type: ['VerifiableCredential', 'MedicalLicense'],
    credentialSubject: {
      id: 'did:key:z6MkhaXg...',
      licenseNumber: 'MD-123456',
      state: 'CA',
      specialty: 'Cardiology',
      issuedDate: '2024-01-15',
      expiryDate: '2027-01-15'
    }
  },
  onProgress: (event) => {
    switch (event.stage) {
      case 'validating':
        console.log(`Schema validation: ${event.percent}%`);
        break;
      case 'signing':
        console.log(`Signing credential with issuer key`);
        break;
      case 'splitting':
        console.log(`XorIDA 2-of-3 split: ${event.percent}%`);
        break;
      case 'storing':
        console.log(`Storing share ${event.current} of ${event.total}`);
        break;
      case 'complete':
        console.log(`Credential issued: ${event.credentialId}`);
        break;
    }
  }
});

// Retrieve credential with progress
const credential = await wallet.retrieveCredential({
  credentialId: result.credentialId,
  onProgress: (event) => {
    console.log(`${event.stage}: ${event.percent}%`);
    // Stages: fetching → reconstructing → verifying → complete
  }
});

// Create presentation with selective disclosure (OID4VP)
const presentation = await wallet.createPresentation({
  credentials: [credential],
  verifier: 'did:key:z6Mk...', // Hospital DID
  disclose: ['licenseNumber', 'state', 'specialty'], // Exclude expiry
  onProgress: (event) => {
    if (event.stage === 'disclosing') {
      console.log(`Disclosing ${event.current} of ${event.total} fields`);
    }
  }
});

// Result: verifiable presentation with only requested fields
presentation.verifiableCredential[0].credentialSubject
// { licenseNumber: 'MD-123456', state: 'CA', specialty: 'Cardiology' }
// expiryDate NOT included — never left the wallet

Error Codes: 43 Codes Across 11 Categories

Every error includes a machine-readable code, human-readable message, field-level attribution (18 codes), and specific recovery guidance:

Field-Level Error Attribution (18 Codes)

When schema validation fails, errors pinpoint the exact field and violation:

// Invalid credential: expiryDate in the past
const result = await wallet.issueCredential({
  subject: 'did:key:z6MkhaXg...',
  claims: {
    type: ['VerifiableCredential', 'MedicalLicense'],
    credentialSubject: {
      licenseNumber: 'MD-123456',
      expiryDate: '2020-01-15' // Expired!
    }
  }
});

// Error response with field attribution
result.error
// {
//   code: 'CREDENTIAL_EXPIRED',
//   message: 'Credential expired on 2020-01-15',
//   field: 'credentialSubject.expiryDate',  // Exact field path
//   value: '2020-01-15',                     // Problematic value
//   expected: 'Date after 2026-04-06',       // Validation rule
//   recovery: 'Update expiryDate to future date or issue short-lived credential'
// }

18 field-attributable codes: REQUIRED_FIELD_MISSING, INVALID_FIELD_TYPE, FIELD_OUT_OF_RANGE, DISCLOSURE_FIELD_NOT_FOUND, REQUESTED_FIELD_EXCLUDED, ISSUANCE_DATE_FUTURE, CREDENTIAL_EXPIRED, ISSUER_SIGNATURE_INVALID, VERIFIER_DID_INVALID, SHARE_CORRUPTED, HMAC_VERIFICATION_FAILED, THRESHOLD_TOO_LOW, THRESHOLD_EXCEEDS_TOTAL, SHARE_INDEX_OUT_OF_RANGE, SCHEMA_VALIDATION_FAILED, DISCLOSURE_PROOF_FAILED, PRESENTATION_SIGNATURE_FAILED, OID4VP_PROTOCOL_ERROR.

Built-in W3C VC + OID4VP Support

xWallet includes first-class support for W3C Verifiable Credentials 1.1 and OpenID for Verifiable Presentations (OID4VP):

• W3C VC 1.1 schema built-in — supports @context, type, credentialSubject, issuer, issuanceDate, expirationDate, proof
• OID4VP presentation flow — automatic presentation request parsing, selective disclosure per verifier request, signed presentation response
• JSON-LD context validation — verify credential contexts resolve and match schema
• Proof formats — Ed25519Signature2020, JsonWebSignature2020, BbsBlsSignature2020 (selective disclosure)
• Revocation methods — RevocationList2020, StatusList2021, issuer-hosted revocation endpoints

Error Recovery Patterns

Every error code includes actionable recovery guidance:

Security Properties

xWallet inherits XorIDA's information-theoretic guarantees and adds credential-layer integrity, selective disclosure, injected signing, and HMAC-chained audit logs.

Core Guarantees

Traditional PKI vs. xWallet

Verifiable Credential Handling

Every xWallet operation produces integrity artifacts that xProve can chain into a verifiable audit trail. Prove that credentials were issued, stored, and presented correctly — without revealing the credentials themselves.

Ship Proofs, Not Source

xWallet generates cryptographic proofs of correct execution without exposing proprietary algorithms. Verify integrity using zero-knowledge proofs — no source code required.

Use Cases

Limitations

Honest engineering requires honest documentation. Five known limitations with their mitigations.

Enterprise CLI

@private.me/xwallet-cli is a self-hosted credential management server — Docker-ready, air-gapped capable, with three-role RBAC and append-only audit logging.

Endpoints

RBAC Roles

Admin — full access: create schemas, issue/verify/revoke credentials, manage API keys, read audit logs.
Operator — create schemas, issue/verify/list credentials, check revocations.
Auditor — read-only: schemas, credentials, revocations, audit logs.

docker build -t xwallet-cli -f packages/xwallet-cli/Dockerfile .
docker run -d --name xwallet -p 4600:4600 \
  -v xwallet-data:/data \
  -e XWALLET_ADMIN_KEY=your-secret-key \
  xwallet-cli

Get Started

Install xWallet, register a schema, and issue your first verifiable credential in minutes.

npm install @private.me/xwallet

import {
  issueCredential,
  storeCredential,
  retrieveCredential,
  createPresentation,
  verifyPresentation,
  getBuiltInSchemas,
} from '@private.me/xwallet';

// List available schemas
const schemas = getBuiltInSchemas();
// → government-id, drivers-license, passport, diploma, ...

// Issue a credential
const { value: credential } = await issueCredential({
  schemaId: 'diploma',
  issuerDid: universityDid,
  subjectDid: studentDid,
  attributes: {
    degree: 'B.Sc. Computer Science',
    institution: 'MIT',
    graduationDate: '2025-06-01',
    gpa: 3.92,
  },
  signingFn: universitySignFn,
});

// Store — XorIDA-split into k-of-n shares
const { value: handle } = await storeCredential(credential);

// Retrieve — HMAC-verified, reconstructed (~60µs)
const { value: restored } = await retrieveCredential(handle);

// Present — selective disclosure (degree + institution only)
const { value: presentation } = await createPresentation({
  credential: restored,
  request: { attributes: ['degree', 'institution'] },
  signingFn: studentSignFn,
});

// Verify — employer checks presentation
const { value: verified } = await verifyPresentation(
  presentation,
  universityVerifyFn,
);
// verified.attributes → { degree, institution }
// gpa and graduationDate are NEVER disclosed

Full ACI documentation, schema reference, and integration guides are available in the ACI catalog.

Ready to deploy xWallet?

Talk to Sol, our AI platform engineer, or book a live demo with our team.