Skip to main content

identityClient

Import​

import {
  createIdentityResolver,
  createIdentityCommitment,
  createIdentityProofHash,
  getIdentityProfile,
  getIdentityPolicy
} from 'shyware/sdk/web/identityClient.js'

Overview​

The identity client handles commitment construction, proof hash derivation, IDV session initiation, and input normalization across all identity providers. It is used internally by every embodiment client; it can also be used directly when building custom flows.

All commitment and proof hash values are derived client-side from the shyconfig and the caller's input. No network call is required to produce a commitment.

createIdentityResolver(manifest)​

Factory that returns an object with all identity methods bound to the manifest's provider configuration.

const resolver = createIdentityResolver(shyconfig)

const { commitment } = await resolver.createIdentityCommitment({ personId: 'didit-journey-id' })
const { proofHash }  = await resolver.createIdentityProofHash({ personId: 'didit-journey-id' })

Commitment construction​

const { commitment } = await createIdentityCommitment(manifest, input, options?)

Produces a deterministic hash:

H(namespace : provider : source [:scope])

Where:

  • namespace — "stable_identity" (voting), "account" (custody/governance), or a custom value
  • provider — from manifest.identity.provider
  • source — provider-specific identifier (see below)

Provider sources​

providersourceInput field
didit (or any managed IDV)Person ID or journey ID from verified sessioninput.personId or input.journeyId
walletWallet address (normalized to lowercase)input.walletAddress
noneFallback value for dev/demoinput.value

For BYOID inputs — where the developer provides credentials directly rather than going through a managed IDV session — tag the input with sourceProvider: "byoid" and pass it through normalizeByoidIdentity:

import { normalizeByoidIdentity } from 'shyware/sdk/web/providers/byoid.js'

const normalized = normalizeByoidIdentity({ personId, journeyId, proofHash })
// → { sourceProvider: "byoid", personId, journeyId, proofHash, walletAddress, ... }

Proof hash construction​

const { proofHash } = await createIdentityProofHash(manifest, input, options?)

Produces a binding hash that ties the commitment to a specific verification workflow:

H("proof" : provider : source : workflowId : issuerDid : scope : audience : nonce)

workflowId and issuerDid are read from the manifest's identity block. nonce is a random value generated per session. The proof hash is submitted alongside the ballot or transaction as evidence that a real IDV workflow was completed for this specific commitment.

IDV session management​

The SDK does not ship an IDV session client — which IDV provider you use is a deployment choice, not an SDK primitive. Implement session initiation and status polling in your consumer app, then pass the resulting personId or journeyId to the SDK.

Example using the reference Didit helpers (ship these in your app, not the SDK):

// In your app — not imported from the SDK
import { createDiditSession, getDiditSessionStatus, extractDiditIdentity } from './providers/didit.js'

const { sessionId, sessionUrl } = await createDiditSession({
  baseUrl: 'https://api.yourdomain.com',
  idToken: bearerToken,
  verificationType: 'id_verification'
})

// poll until approved...
const raw = await getDiditSessionStatus({ baseUrl, idToken, sessionId })
const { personId, journeyId } = extractDiditIdentity(raw)

// Now pass to the SDK
await client.voteSubmission({ scopingId, payload, personId })

resolver.normalizeManagedIdentity(status) accepts the already-extracted status object and normalizes it for commitment construction. Your app is responsible for calling your IDV provider's extraction function first.

Input normalization​

const normalized = await resolver.normalizeIdentityInput(manifest, input, options?)

Normalizes provider-specific identity inputs to a canonical form before commitment derivation. Useful when building custom flows that need to accept multiple input shapes.

Identity profile​

const profile = getIdentityProfile(manifest)
// → { provider, mode, kycRequired, byoidPolicy, recommendedIdv, uiHints }

const policy = getIdentityPolicy(manifest)
// → { byoidPolicy, presentationMode }

getIdentityProfile returns provider-specific UI configuration for rendering identity flows in your application. getIdentityPolicy returns the policy constraints governing byoid (bring-your-own-identity) inputs.

KYB — house entity verification​

Individual participant IDV and house entity KYB are separate concerns. The SDK handles individual participant identity (commitment construction, proof hashes). House entity onboarding is an operator-level operation outside the SDK:

ConcernActorNotes
Individual participant IDVAll participantsAny provider that yields personId/journeyId — implement in your app
Entity beneficial-ownership attestationhouse (warehouse/vault owner)KYB via Persona or equivalent; emits a pub_key_hex for house_keys

The house-onboard CLI tool handles the KYB webhook verification and key admission flow. See the Custody Consortium Governance deployment for the complete house onboarding flow.

Oracle resistance​

The identity client enforces oracle resistance at the construction layer:

  • The person_secret (ZK tier) is never passed through this module — it is generated and retained by zkpClient exclusively on the device
  • Commitment inputs (personId, walletAddress) are hashed before any network contact
  • The IDV provider receives only commitment (a hash) — never the raw identity input, never the person_secret
  • The proofHash binds the commitment to a workflow without revealing the commitment's preimage to on-chain observers

This is the structural non-transmission guarantee: the IDV provider attests the commitment without ever being able to derive the value that produced it (for the ZK tier) or the on-chain identity hash (for all tiers).