Skip to main content

​
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
diditDidit person ID or journey IDinput.personId or input.journeyId
identusDID subject or credential IDinput.subjectId or input.credentialId
walletWallet address (normalized to lowercase)input.walletAddress
noneFallback valueinput.value

​
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

​
Initiate a session

const session = await resolver.createRecommendedIdvSession(manifest, sessionOptions?, providerOptions?)
// → { sessionId, redirectUrl, ... }   (provider-specific)
For Didit (recommended_idv: "didit"), this creates a biometric verification session. Returns the session URL for redirect.

​
Check session status

const status = await resolver.getRecommendedIdvSessionStatus(manifest, { sessionId }, providerOptions?)
// → { status: "pending" | "approved" | "rejected", personId?, journeyId? }
Poll this after the user completes the IDV flow to obtain the personId or journeyId to pass to buildBallot / castBallot.

​
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.

​
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).