Adapters

Pass Adapters to create in Config.adapters. A platform SDK ships its own adapters where the platform has one, such as a hardware key store and its attestation on mobile. Your application supplies the rest. Each SDK locks the device key with what the unlock adapter returns, in its own way. That locking is internal to each SDK.

Types

Adapters

interface Adapters {
  unlock: UnlockAdapter;
  signIn: SignInAdapter;
  attestation?: AttestationAdapter;
  offlineMedium?: OfflineMediumAdapter;
}

struct Adapters {
  let unlock: UnlockAdapter
  let signIn: SignInAdapter
  var attestation: AttestationAdapter? = nil
  var offlineMedium: OfflineMediumAdapter? = nil
}

data class Adapters(
  val unlock: UnlockAdapter,
  val signIn: SignInAdapter,
  val attestation: AttestationAdapter? = null,
  val offlineMedium: OfflineMediumAdapter? = null,
)

Field	Type	Description
`unlock`	`UnlockAdapter`	Obtains the person’s secret for the device key. Your application always supplies this.
`signIn`	`SignInAdapter`	Opens the identity provider in the system browser. Your application always supplies this, unless a mobile platform’s system-browser adapter covers it.
`attestation`	`AttestationAdapter`, optional	On mobile, the platform’s attestation of a session key held in hardware. The mobile SDKs ship this.
`offlineMedium`	`OfflineMediumAdapter`, optional	A hardware token a tenant issues to custodians for backup key shares, where the tenant issues one.

UnlockPurpose

The reason the SDK asks for the person’s secret. Use it to word the prompt.

type UnlockPurpose = 'connect' | 'resume' | 'sign' | 'open-offline' | 'enroll';

enum UnlockPurpose: String {
  case connect, resume, sign, openOffline, enroll
}

enum class UnlockPurpose { CONNECT, RESUME, SIGN, OPEN_OFFLINE, ENROLL }

Value	When
`connect`	`SealdHealthcare.connect` is unlocking the device key for the first time this run.
`resume`	`session.resume` is unlocking after inactivity.
`sign`	The device key is about to sign something, such as an enrollment approval.
`open-offline`	The device is opening what an offline lease covers, with no session.
`enroll`	`SealdHealthcare.enroll` is generating and protecting a new device key.

UnlockAdapter

interface UnlockAdapter {
  unlock(purpose: UnlockPurpose): Promise<unknown>;
}

protocol UnlockAdapter {
  func unlock(purpose: UnlockPurpose) async throws -> Any
}

interface UnlockAdapter {
  suspend fun unlock(purpose: UnlockPurpose): Any
}

Member	Type	Description
`unlock`	`(purpose: UnlockPurpose) => Promise<unknown>`	Obtains the person’s secret for the device key: a passphrase prompt, a platform biometric, or a hardware key store’s unlock. Each SDK types what it returns, because each SDK locks the device key under it differently.

SignInAdapter

Opens the identity provider’s authorization URL in the system browser and returns the redirect URL the browser came back with. The SDK uses PKCE and holds no client secret. A fresh multi-factor sign-in for an approval goes through here too.

interface SignInAdapter {
  authorize(url: string, redirectUri: string): Promise<string>;
}

protocol SignInAdapter {
  func authorize(url: String, redirectUri: String) async throws -> String
}

interface SignInAdapter {
  suspend fun authorize(url: String, redirectUri: String): String
}

Member	Type	Description
`authorize`	`(url: string, redirectUri: string) => Promise<string>`	Opens `url` in the system browser and returns the URL the browser was redirected back to.

AttestationAdapter

On mobile, the platform’s attestation of a session key held in hardware.

interface AttestationAdapter {
  attest(sessionKeyPublic: Bytes): Promise<Bytes>;
}

protocol AttestationAdapter {
  func attest(sessionKeyPublic: Data) async throws -> Data
}

interface AttestationAdapter {
  suspend fun attest(sessionKeyPublic: ByteArray): ByteArray
}

Member	Type	Description
`attest`	`(sessionKeyPublic: Bytes) => Promise<Bytes>`	Attests the given session public key in hardware and returns the attestation.

OfflineMediumAdapter

Reads and writes a hardware token that a tenant issues to custodians. Without a token, a backup key share is a printed code.

interface OfflineMediumAdapter {
  write(share: Bytes, fingerprint: string): Promise<void>;
  read(): Promise<Bytes>;
}

protocol OfflineMediumAdapter {
  func write(share: Data, fingerprint: String) async throws
  func read() async throws -> Data
}

interface OfflineMediumAdapter {
  suspend fun write(share: ByteArray, fingerprint: String)
  suspend fun read(): ByteArray
}

Member	Type	Description
`write`	`(share: Bytes, fingerprint: string) => Promise<void>`	Writes a custodian’s share and its fingerprint to the hardware token.
`read`	`() => Promise<Bytes>`	Reads a share back from the hardware token, for `backupKey.proveShare` or `recovery.takePart`.

The shipped mobile adapters

The mobile SDKs ship an attestation adapter and a system-browser sign-in adapter. Your application supplies only unlock.

Swift
Kotlin

Adapters(unlock: unlock, signIn: WebAuthenticationSignIn(presentationAnchor: anchor), attestation: AppAttestAdapter())

Adapters(unlock = unlock, signIn = CustomTabsSignIn(activity), attestation = KeyAttestationAdapter(context))

Adapter	Platform	Supplies
`AppAttestAdapter()`	Swift	`AttestationAdapter`, backed by the platform’s hardware attestation.
`KeyAttestationAdapter(context)`	Kotlin	`AttestationAdapter`, backed by the platform’s hardware attestation.
`WebAuthenticationSignIn(presentationAnchor:)`	Swift	`SignInAdapter`, opening the identity provider in the system browser.
`CustomTabsSignIn(activity)`	Kotlin	`SignInAdapter`, opening the identity provider in the system browser.