wallet

In this section

Classes

WalletRequestError

Defined in: src/wallet/seal.ts:55

Thrown by parseWalletRequest where spec §8.4 says to fail: the Wallet doesn't respond.

Extends

Error

Constructors

Constructor

new WalletRequestError(message, rule): WalletRequestError;

Defined in: src/wallet/seal.ts:56

Parameters

Parameter	Type	Description
`message`	`string`	-
`rule`	`string`	The spec requirement, such as "WRQ-4".

Returns

WalletRequestError

Overrides

Error.constructor

Properties

rule

readonly rule: string;

Defined in: src/wallet/seal.ts:59

The spec requirement, such as "WRQ-4".

Type Aliases

MatchableEntry

type MatchableEntry = {
  fullUrl: string;
  resource: MatchableResource;
};

Defined in: src/wallet/match.ts:17

Properties

fullUrl

fullUrl: string;

Defined in: src/wallet/match.ts:17

resource

resource: MatchableResource;

Defined in: src/wallet/match.ts:17

MatchableResource

type MatchableResource = {
[key: string]: unknown;
  meta?: {
     profile?: ReadonlyArray<string>;
  };
  resourceType: string;
};

Defined in: src/wallet/match.ts:16

Which of a patient's records answer a selection.fhir item (spec §5.4.1, §5.5).

profiles: a resource matches when its meta.profile has the requested canonical. Unversioned requests match any version; versioned ones need that exact version.
profilesFrom: matches any profile whose URL starts with the family's URL and "/" ([SEL-5]).
profiles and profilesFrom together are additive; resourceTypes narrows either, or selects by type on its own.
No selector at all: everything.

selectEntries also brings along the resources a match references (a prescriber, a payer), so references in the returned Bundle resolve.

Indexable

[key: string]: unknown

Properties

meta?

optional meta?: {
  profile?: ReadonlyArray<string>;
};

Defined in: src/wallet/match.ts:16

profile?

optional profile?: ReadonlyArray<string>;

resourceType

resourceType: string;

Defined in: src/wallet/match.ts:16

ParsedWalletRequest

type ParsedWalletRequest = {
  deviceRequestBytes: Uint8Array;
  encryptionInfoBytes: Uint8Array;
  readerAuth?: unknown;
  smartRequest: SmartCheckinRequest;
  unsupportedItems: UnsupportedItem[];
  warnings: CheckinWarning[];
};

Defined in: src/wallet/seal.ts:39

What parseWalletRequest finds in a Digital Credentials API argument.

Properties

deviceRequestBytes

deviceRequestBytes: Uint8Array;

Defined in: src/wallet/seal.ts:49

The mdoc DeviceRequest, as sent.

encryptionInfoBytes

encryptionInfoBytes: Uint8Array;

Defined in: src/wallet/seal.ts:51

The EncryptionInfo, as sent: the Verifier's public key. Pass it to sealWalletResponse.

readerAuth?

optional readerAuth?: unknown;

Defined in: src/wallet/seal.ts:47

The DocRequest's readerAuth, if present, for Wallets that verify it ([WRQ-9]).

smartRequest

smartRequest: SmartCheckinRequest;

Defined in: src/wallet/seal.ts:41

The SMART request to show the patient and answer.

unsupportedItems

unsupportedItems: UnsupportedItem[];

Defined in: src/wallet/seal.ts:43

Request items this library can't process; answer each unsupported ([SEL-9], [SEL-10], [FORM-1]).

warnings

warnings: CheckinWarning[];

Defined in: src/wallet/seal.ts:45

Problems a Wallet continues past and reports (spec §8.4, [RCV-1]).

SelectionContent

type SelectionContent = {
  kind: "selection.fhir";
  profiles?: ReadonlyArray<string>;
  profilesFrom?: ReadonlyArray<string>;
  resourceTypes?: ReadonlyArray<string>;
};

Defined in: src/wallet/match.ts:19

Properties

kind

kind: "selection.fhir";

Defined in: src/wallet/match.ts:20

profiles?

optional profiles?: ReadonlyArray<string>;

Defined in: src/wallet/match.ts:21

profilesFrom?

optional profilesFrom?: ReadonlyArray<string>;

Defined in: src/wallet/match.ts:22

resourceTypes?

optional resourceTypes?: ReadonlyArray<string>;

Defined in: src/wallet/match.ts:23

ServeWebWalletOptions

type ServeWebWalletOptions = {
  closeAfterReply?: boolean;
  onInvalidRequest?: void;
  onRequest: Promise<WebWalletAnswer>;
};

Defined in: src/wallet/serve-web-wallet.ts:50

@smart-health-checkin/client/wallet: for building a wallet.

serveWebWallet: the web wallet's side of the hand-off.
parseWalletRequest, sealWalletResponse: read a request, seal a response (native or web).
checkWalletResponse, declineAll: check a response before sending; the all-declined response.
selects, selectEntries: which records answer a selection.fhir item.
buildSignedDeviceResponse, recipientJwkFromEncryptionInfo: lower-level pieces for wallets that seal their own responses.

Properties

closeAfterReply?

optional closeAfterReply?: boolean;

Defined in: src/wallet/serve-web-wallet.ts:55

Close the tab after replying (default true).

Methods

onInvalidRequest()?

optional onInvalidRequest(message, origin): void;

Defined in: src/wallet/serve-web-wallet.ts:53

Called when a request can't be read; the EHR also gets an error reply.

Parameters

Parameter	Type
`message`	`string`
`origin`	`string`

Returns

void

onRequest()

onRequest(context): Promise<WebWalletAnswer>;

Defined in: src/wallet/serve-web-wallet.ts:51

Parameters

Parameter	Type
`context`	`WebWalletRequestContext`

Returns

Promise<WebWalletAnswer>

WebWalletAnswer

type WebWalletAnswer = 
  | {
  response: SmartCheckinResponse;
}
  | {
  credential: {
     data: {
        response: string;
     };
     protocol: string;
  };
}
  | {
  declined: true;
}
  | {
  error: string;
};

Defined in: src/wallet/serve-web-wallet.ts:36

What the wallet answers with.

Union Members

Type Literal

{
  response: SmartCheckinResponse;
}

Seal this response for the EHR and send it. It is checked against the request first, and a mismatch becomes an error reply. If the patient reviewed the request and declined everything, send declineAll(request).

Type Literal

{
  credential: {
     data: {
        response: string;
     };
     protocol: string;
  };
}

Send a credential you sealed yourself (for example, to inject faults when testing).

Type Literal

{
  declined: true;
}

The patient closed the wallet without reviewing the request ([HOLD-4]).

Type Literal

{
  error: string;
}

Something went wrong; the EHR sees the message.

WebWalletCredential

type WebWalletCredential = {
  data: object;
  protocol: string;
};

Defined in: src/kit/web-wallet.ts:22

Properties

data

data: object;

Defined in: src/kit/web-wallet.ts:22

protocol

protocol: string;

Defined in: src/kit/web-wallet.ts:22

WebWalletRequestContext

type WebWalletRequestContext = {
  origin: string;
  parsed: ParsedWalletRequest;
  request: SmartCheckinRequest;
  unsupportedItems: ParsedWalletRequest["unsupportedItems"];
};

Defined in: src/wallet/serve-web-wallet.ts:24

@smart-health-checkin/client/wallet: for building a wallet.

serveWebWallet: the web wallet's side of the hand-off.
parseWalletRequest, sealWalletResponse: read a request, seal a response (native or web).
checkWalletResponse, declineAll: check a response before sending; the all-declined response.
selects, selectEntries: which records answer a selection.fhir item.
buildSignedDeviceResponse, recipientJwkFromEncryptionInfo: lower-level pieces for wallets that seal their own responses.

Properties

origin

origin: string;

Defined in: src/wallet/serve-web-wallet.ts:30

The EHR page's origin, from the browser. Show it to the patient; the response is bound to it.

parsed

parsed: ParsedWalletRequest;

Defined in: src/wallet/serve-web-wallet.ts:32

The parsed wire request, for wallets that seal their own responses.

request

request: SmartCheckinRequest;

Defined in: src/wallet/serve-web-wallet.ts:26

The SMART request, validated.

unsupportedItems

unsupportedItems: ParsedWalletRequest["unsupportedItems"];

Defined in: src/wallet/serve-web-wallet.ts:28

Items this library can't process; answer each unsupported.

WebWalletResponseMessage

type WebWalletResponseMessage = 
  | {
  credential: WebWalletCredential;
  outcome: "approved";
  requestId?: string;
  type: typeof WEB_WALLET_RESPONSE_MESSAGE_TYPE;
}
  | {
  outcome: "declined" | "closed";
  requestId?: string;
  type: typeof WEB_WALLET_RESPONSE_MESSAGE_TYPE;
}
  | {
  message: string;
  outcome: "error";
  requestId?: string;
  type: typeof WEB_WALLET_RESPONSE_MESSAGE_TYPE;
};

Defined in: src/kit/web-wallet.ts:24

Variables

WEB_WALLET_READY_MESSAGE_TYPE

const WEB_WALLET_READY_MESSAGE_TYPE: "digital-credentials/web-wallet/ready";

Defined in: src/kit/web-wallet.ts:20

WEB_WALLET_REQUEST_MESSAGE_TYPE

const WEB_WALLET_REQUEST_MESSAGE_TYPE: "digital-credentials/web-wallet/request";

Defined in: src/kit/web-wallet.ts:18

WEB_WALLET_RESPONSE_MESSAGE_TYPE

const WEB_WALLET_RESPONSE_MESSAGE_TYPE: "digital-credentials/web-wallet/response";

Defined in: src/kit/web-wallet.ts:19

Functions

buildSignedDeviceResponse()

function buildSignedDeviceResponse(input): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: src/wallet/seal.ts:252

A structurally real SMART Health Card: a JWS whose payload is the raw-DEFLATEd { iss, nbf, vc.credentialSubject.fhirBundle } (one Patient, one Coverage), so anything that decodes cards can show what is in it. The signature is zeros — nothing verifies it, and nothing should.

Parameters

Parameter	Type	Description
`input`	{ `now?`: `Date`; `sessionTranscript`: `Uint8Array`; `smartResponseJson`: `string`; }	-
`input.now?`	`Date`	Signing time for the MSO's validityInfo; defaults to now.
`input.sessionTranscript`	`Uint8Array`	-
`input.smartResponseJson`	`string`	-

Returns

Promise<Uint8Array<ArrayBufferLike>>

checkWalletResponse()

function checkWalletResponse(request, response): ValidationIssue[];

Defined in: src/wallet/seal.ts:196

What a Verifier would object to in this response (spec §6.4), as a Wallet checks before sending: an empty list means it's clean. A Wallet produces exactly one status per item, only accepted media types, and so on.

Parameters

Parameter	Type
`request`	`SmartCheckinRequest`
`response`	`SmartCheckinResponse`

Returns

ValidationIssue[]

declineAll()

function declineAll(request, message?): SmartCheckinResponse;

Defined in: src/wallet/seal.ts:216

The response for a Holder who reviewed the request and declined every item ([HOLD-4]): every item declined, no Artifacts. (If the Holder dismisses the Wallet without reviewing, the Wallet returns nothing.)

Parameters

Parameter	Type
`request`	`SmartCheckinRequest`
`message?`	`string`

Returns

SmartCheckinResponse

parseWalletRequest()

function parseWalletRequest(navigatorArgument): ParsedWalletRequest;

Defined in: src/wallet/seal.ts:73

Wallet side: read a request from a navigator.credentials.get argument, following spec §8.4 steps [WRQ-2]..[WRQ-7]. Throws WalletRequestError only where the spec says to fail (it can't be decoded, there's no SMART DocRequest or request text, the SMART request is invalid, or there's no usable recipient key); everything else is returned in warnings.

Parameters

Parameter	Type
`navigatorArgument`	`unknown`

Returns

ParsedWalletRequest

recipientJwkFromEncryptionInfo()

function recipientJwkFromEncryptionInfo(encryptionInfoBytes): JsonWebKey;

Defined in: src/wallet/seal.ts:227

The Verifier's public key, as a JWK, from a request's EncryptionInfo.

Parameters

Parameter	Type
`encryptionInfoBytes`	`Uint8Array`

Returns

JsonWebKey

sealWalletResponse()

function sealWalletResponse(input): Promise<{
  data: {
     response: string;
  };
  protocol: string;
}>;

Defined in: src/wallet/seal.ts:159

Wallet side: sign and HPKE-seal a SMART response for the verifier. verifierOrigin is the requesting page's origin — the SessionTranscript binds to it, so a response cannot be replayed to a different origin.

Parameters

Parameter	Type	Description
`input`	{ `encryptionInfoBytes`: `Uint8Array`; `request?`: `SmartCheckinRequest`; `smartResponse`: `SmartCheckinResponse`; `verifierOrigin`: `string`; }	-
`input.encryptionInfoBytes`	`Uint8Array`	-
`input.request?`	`SmartCheckinRequest`	The request being answered. When given, the response is checked against it first ([ACC-2], [RSP-2], [ART-1], …) and sealing throws on any problem, so a Wallet never sends a response a Verifier would set aside.
`input.smartResponse`	`SmartCheckinResponse`	-
`input.verifierOrigin`	`string`	-

Returns

Promise<{ data: { response: string; }; protocol: string; }>

selectEntries()

function selectEntries(
   content, 
   entries, 
   options?): MatchableEntry[];

Defined in: src/wallet/match.ts:61

The entries that answer the selector, plus the entries they reference. exclude names fullUrls never to pull in by reference (usually the Patient, which has its own item).

Parameters

Parameter	Type
`content`	`SelectionContent`
`entries`	readonly `MatchableEntry`[]
`options`	{ `exclude?`: readonly `string`[]; }
`options.exclude?`	readonly `string`[]

Returns

MatchableEntry[]

selects()

function selects(content, resource): boolean;

Defined in: src/wallet/match.ts:45

Does this resource answer the selector?

Parameters

Parameter	Type
`content`	`SelectionContent`
`resource`	`MatchableResource`

Returns

boolean

serveWebWallet()

function serveWebWallet(options): {
  opened: boolean;
  stop: void;
};

Defined in: src/wallet/serve-web-wallet.ts:62

Start answering. Returns { opened }: false when the page wasn't opened by an EHR (no window.opener), so the wallet can show its own landing page.

Parameters

Parameter	Type
`options`	`ServeWebWalletOptions`

Returns

opened

opened: boolean;

Whether an EHR opened this page.

stop()

stop(): void;

Stop listening for requests.

Returns

void