# wallet

## Classes

### WalletRequestError

Defined in: [src/wallet/seal.ts:55](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L55)

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

#### Extends

- `Error`

#### Constructors

##### Constructor

```ts
new WalletRequestError(message, rule): WalletRequestError;
```

Defined in: [src/wallet/seal.ts:56](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L56)

###### Parameters

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

###### Returns

[`WalletRequestError`](#walletrequesterror)

###### Overrides

```ts
Error.constructor
```

#### Properties

##### rule

```ts
readonly rule: string;
```

Defined in: [src/wallet/seal.ts:59](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L59)

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

## Type Aliases

### MatchableEntry

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

Defined in: [src/wallet/match.ts:17](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L17)

#### Properties

##### fullUrl

```ts
fullUrl: string;
```

Defined in: [src/wallet/match.ts:17](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L17)

##### resource

```ts
resource: MatchableResource;
```

Defined in: [src/wallet/match.ts:17](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L17)

***

### MatchableResource

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

Defined in: [src/wallet/match.ts:16](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L16)

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

```ts
[key: string]: unknown
```

#### Properties

##### meta?

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

Defined in: [src/wallet/match.ts:16](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L16)

###### profile?

```ts
optional profile?: ReadonlyArray<string>;
```

##### resourceType

```ts
resourceType: string;
```

Defined in: [src/wallet/match.ts:16](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L16)

***

### ParsedWalletRequest

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

Defined in: [src/wallet/seal.ts:39](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L39)

What `parseWalletRequest` finds in a Digital Credentials API argument.

#### Properties

##### deviceRequestBytes

```ts
deviceRequestBytes: Uint8Array;
```

Defined in: [src/wallet/seal.ts:49](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L49)

The mdoc DeviceRequest, as sent.

##### encryptionInfoBytes

```ts
encryptionInfoBytes: Uint8Array;
```

Defined in: [src/wallet/seal.ts:51](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L51)

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

##### readerAuth?

```ts
optional readerAuth?: unknown;
```

Defined in: [src/wallet/seal.ts:47](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L47)

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

##### smartRequest

```ts
smartRequest: SmartCheckinRequest;
```

Defined in: [src/wallet/seal.ts:41](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L41)

The SMART request to show the patient and answer.

##### unsupportedItems

```ts
unsupportedItems: UnsupportedItem[];
```

Defined in: [src/wallet/seal.ts:43](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L43)

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

##### warnings

```ts
warnings: CheckinWarning[];
```

Defined in: [src/wallet/seal.ts:45](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L45)

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

***

### SelectionContent

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

Defined in: [src/wallet/match.ts:19](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L19)

#### Properties

##### kind

```ts
kind: "selection.fhir";
```

Defined in: [src/wallet/match.ts:20](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L20)

##### profiles?

```ts
optional profiles?: ReadonlyArray<string>;
```

Defined in: [src/wallet/match.ts:21](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L21)

##### profilesFrom?

```ts
optional profilesFrom?: ReadonlyArray<string>;
```

Defined in: [src/wallet/match.ts:22](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L22)

##### resourceTypes?

```ts
optional resourceTypes?: ReadonlyArray<string>;
```

Defined in: [src/wallet/match.ts:23](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L23)

***

### ServeWebWalletOptions

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

Defined in: [src/wallet/serve-web-wallet.ts:50](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L50)

`@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?

```ts
optional closeAfterReply?: boolean;
```

Defined in: [src/wallet/serve-web-wallet.ts:55](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L55)

Close the tab after replying (default true).

#### Methods

##### onInvalidRequest()?

```ts
optional onInvalidRequest(message, origin): void;
```

Defined in: [src/wallet/serve-web-wallet.ts:53](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L53)

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()

```ts
onRequest(context): Promise<WebWalletAnswer>;
```

Defined in: [src/wallet/serve-web-wallet.ts:51](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L51)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`WebWalletRequestContext`](#webwalletrequestcontext) |

###### Returns

`Promise`\<[`WebWalletAnswer`](#webwalletanswer)\>

***

### WebWalletAnswer

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

Defined in: [src/wallet/serve-web-wallet.ts:36](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L36)

What the wallet answers with.

#### Union Members

##### Type Literal

```ts
{
  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

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

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

***

##### Type Literal

```ts
{
  declined: true;
}
```

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

***

##### Type Literal

```ts
{
  error: string;
}
```

Something went wrong; the EHR sees the message.

***

### WebWalletCredential

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

Defined in: [src/kit/web-wallet.ts:22](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L22)

#### Properties

##### data

```ts
data: object;
```

Defined in: [src/kit/web-wallet.ts:22](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L22)

##### protocol

```ts
protocol: string;
```

Defined in: [src/kit/web-wallet.ts:22](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L22)

***

### WebWalletRequestContext

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

Defined in: [src/wallet/serve-web-wallet.ts:24](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L24)

`@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

```ts
origin: string;
```

Defined in: [src/wallet/serve-web-wallet.ts:30](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L30)

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

##### parsed

```ts
parsed: ParsedWalletRequest;
```

Defined in: [src/wallet/serve-web-wallet.ts:32](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L32)

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

##### request

```ts
request: SmartCheckinRequest;
```

Defined in: [src/wallet/serve-web-wallet.ts:26](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L26)

The SMART request, validated.

##### unsupportedItems

```ts
unsupportedItems: ParsedWalletRequest["unsupportedItems"];
```

Defined in: [src/wallet/serve-web-wallet.ts:28](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L28)

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

***

### WebWalletResponseMessage

```ts
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](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L24)

## Variables

### WEB\_WALLET\_READY\_MESSAGE\_TYPE

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

Defined in: [src/kit/web-wallet.ts:20](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L20)

***

### WEB\_WALLET\_REQUEST\_MESSAGE\_TYPE

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

Defined in: [src/kit/web-wallet.ts:18](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L18)

***

### WEB\_WALLET\_RESPONSE\_MESSAGE\_TYPE

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

Defined in: [src/kit/web-wallet.ts:19](https://github.com/smart-health-checkin/client/blob/main/src/kit/web-wallet.ts#L19)

## Functions

### buildSignedDeviceResponse()

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

Defined in: [src/wallet/seal.ts:252](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L252)

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()

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

Defined in: [src/wallet/seal.ts:196](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L196)

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`](checkin.md#smartcheckinrequest) |
| `response` | [`SmartCheckinResponse`](checkin.md#smartcheckinresponse) |

#### Returns

[`ValidationIssue`](model.md#validationissue)[]

***

### declineAll()

```ts
function declineAll(request, message?): SmartCheckinResponse;
```

Defined in: [src/wallet/seal.ts:216](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L216)

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`](checkin.md#smartcheckinrequest) |
| `message?` | `string` |

#### Returns

[`SmartCheckinResponse`](checkin.md#smartcheckinresponse)

***

### parseWalletRequest()

```ts
function parseWalletRequest(navigatorArgument): ParsedWalletRequest;
```

Defined in: [src/wallet/seal.ts:73](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L73)

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`](#parsedwalletrequest)

***

### recipientJwkFromEncryptionInfo()

```ts
function recipientJwkFromEncryptionInfo(encryptionInfoBytes): JsonWebKey;
```

Defined in: [src/wallet/seal.ts:227](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L227)

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `encryptionInfoBytes` | `Uint8Array` |

#### Returns

`JsonWebKey`

***

### sealWalletResponse()

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

Defined in: [src/wallet/seal.ts:159](https://github.com/smart-health-checkin/client/blob/main/src/wallet/seal.ts#L159)

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`](checkin.md#smartcheckinrequest); `smartResponse`: [`SmartCheckinResponse`](checkin.md#smartcheckinresponse); `verifierOrigin`: `string`; \} | - |
| `input.encryptionInfoBytes` | `Uint8Array` | - |
| `input.request?` | [`SmartCheckinRequest`](checkin.md#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`](checkin.md#smartcheckinresponse) | - |
| `input.verifierOrigin` | `string` | - |

#### Returns

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

***

### selectEntries()

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

Defined in: [src/wallet/match.ts:61](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L61)

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`](#selectioncontent) |
| `entries` | readonly [`MatchableEntry`](#matchableentry)[] |
| `options` | \{ `exclude?`: readonly `string`[]; \} |
| `options.exclude?` | readonly `string`[] |

#### Returns

[`MatchableEntry`](#matchableentry)[]

***

### selects()

```ts
function selects(content, resource): boolean;
```

Defined in: [src/wallet/match.ts:45](https://github.com/smart-health-checkin/client/blob/main/src/wallet/match.ts#L45)

Does this resource answer the selector?

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `content` | [`SelectionContent`](#selectioncontent) |
| `resource` | [`MatchableResource`](#matchableresource) |

#### Returns

`boolean`

***

### serveWebWallet()

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

Defined in: [src/wallet/serve-web-wallet.ts:62](https://github.com/smart-health-checkin/client/blob/main/src/wallet/serve-web-wallet.ts#L62)

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`](#servewebwalletoptions) |

#### Returns

##### opened

```ts
opened: boolean;
```

Whether an EHR opened this page.

##### stop()

```ts
stop(): void;
```

Stop listening for requests.

###### Returns

`void`