@gramota/trust

TrustResolver Strategy — Static, JwksUrl, SdJwtVcIssuer (.well-known/jwt-vc-issuer).

Install: pnpm add @gramota/trust

Source: github.com/gramota-org/gramota/tree/main/packages/trust

Classes

JwksUrlTrustResolver

Defined in: @gramota/trust/dist/jwks-url.d.ts:20

Resolve issuer keys by fetching a JWK Set (RFC 7517 §5) from the issuer's well-known URL. Caches per-issuer for cacheMs.

Implements

• TrustResolver

Constructors

Constructor

new JwksUrlTrustResolver(options?: JwksUrlResolverOptions): JwksUrlTrustResolver;

Defined in: @gramota/trust/dist/jwks-url.d.ts:26

Parameters

options?

JwksUrlResolverOptions

Returns

JwksUrlTrustResolver

Methods

resolveIssuerKeys()

resolveIssuerKeys(context: TrustContext): Promise<readonly JsonWebKey[]>;

Defined in: @gramota/trust/dist/jwks-url.d.ts:27

Return all candidate JWKs that might verify this issuer's JWS. The verifier will try each in order until one succeeds. Throw if no candidate can be produced — that's a trust-resolution failure.

Parameters

context

TrustContext

Returns

Promise<readonly JsonWebKey[]>

Implementation of

TrustResolver.resolveIssuerKeys

invalidate()

invalidate(iss: string): void;

Defined in: @gramota/trust/dist/jwks-url.d.ts:30

Manually invalidate the cache for a given issuer. Useful when keys rotate and the consumer knows about it out of band.

Parameters

iss

string

Returns

void

---

SdJwtVcIssuerTrustResolver

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:47

A pluggable strategy for figuring out which JWK(s) should verify an issuer's JWS. Strategy + Repository pattern: implementations can be a static list, a JWKS URL fetch, an EU Trusted List, or anything custom.

Implements

• TrustResolver

Constructors

Constructor

new SdJwtVcIssuerTrustResolver(options?: SdJwtVcIssuerResolverOptions): SdJwtVcIssuerTrustResolver;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:53

Parameters

options?

SdJwtVcIssuerResolverOptions

Returns

SdJwtVcIssuerTrustResolver

Methods

resolveIssuerKeys()

resolveIssuerKeys(context: TrustContext): Promise<readonly JsonWebKey[]>;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:54

Return all candidate JWKs that might verify this issuer's JWS. The verifier will try each in order until one succeeds. Throw if no candidate can be produced — that's a trust-resolution failure.

Parameters

context

TrustContext

Returns

Promise<readonly JsonWebKey[]>

Implementation of

TrustResolver.resolveIssuerKeys

invalidate()

invalidate(iss: string): void;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:56

Force-clear cache for one issuer.

Parameters

iss

string

Returns

void

---

StaticTrustResolver

Defined in: @gramota/trust/dist/static.d.ts:23

Trust a fixed set of public keys, optionally keyed by issuer URL.

Two configuration shapes:

// Flat list — every key is trusted for every issuer. new StaticTrustResolver([key1, key2])

// Per-issuer map — strict isolation between issuers. new StaticTrustResolver({ "https://issuer-a.example.com": [keyA1, keyA2], "https://issuer-b.example.com": [keyB], })

kid matching: if both the JWT header and a configured key carry a kid, the resolver returns only matching keys; otherwise it returns all keys for the issuer (verifier will try them in order).

Implements

• TrustResolver

Constructors

Constructor

new StaticTrustResolver(input: StaticTrustInput): StaticTrustResolver;

Defined in: @gramota/trust/dist/static.d.ts:27

Parameters

input

StaticTrustInput

Returns

StaticTrustResolver

Methods

resolveIssuerKeys()

resolveIssuerKeys(context: TrustContext): Promise<readonly JsonWebKey[]>;

Defined in: @gramota/trust/dist/static.d.ts:28

Return all candidate JWKs that might verify this issuer's JWS. The verifier will try each in order until one succeeds. Throw if no candidate can be produced — that's a trust-resolution failure.

Parameters

context

TrustContext

Returns

Promise<readonly JsonWebKey[]>

Implementation of

TrustResolver.resolveIssuerKeys

---

TrustResolutionError

Defined in: @gramota/trust/dist/types.d.ts:23

Extends

• GramotaError

Constructors

Constructor

new TrustResolutionError(
   code: TrustErrorCode, 
   message: string, 
   options?: {
  cause?: unknown;
}): TrustResolutionError;

Defined in: @gramota/trust/dist/types.d.ts:25

Parameters

code

TrustErrorCode

message

string

options?

cause?

unknown

Returns

TrustResolutionError

Overrides

GramotaError.constructor

Properties

cause?

readonly optional cause?: unknown;

Defined in: .pnpm/@gramota+core@0.2.1/node_modules/@gramota/core/dist/error.d.ts:44

Optional original error that caused this one. Always set when the Gramota package is wrapping a thrown exception from a dependency (Web Crypto, JOSE, fetch). Survives JSON.stringify(err) only via the cause property — Node 16.9+ logs it natively.

Inherited from

GramotaError.cause

code

readonly code: TrustErrorCode;

Defined in: @gramota/trust/dist/types.d.ts:24

Stable string that identifies the failure mode. Subclasses narrow the type; at runtime it's always a string. Use for branching, logs, and metrics labels — never serialize GramotaError.message for that purpose, message strings drift across versions.

Overrides

GramotaError.code

name

name: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

GramotaError.name

message

message: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

GramotaError.message

stack?

optional stack?: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

GramotaError.stack

Interfaces

JwksUrlResolverOptions

Defined in: @gramota/trust/dist/jwks-url.d.ts:4

Properties

jwksUrl?

optional jwksUrl?: (iss: string) => string;

Defined in: @gramota/trust/dist/jwks-url.d.ts:8

Build the JWKS URL from the issuer's iss claim. Default: appends /.well-known/jwks.json. SD-JWT-VC §5.1 also defines a different scheme via /.well-known/jwt-issuer/...; pass a custom builder for that.

Parameters

iss

string

Returns

string

cacheMs?

optional cacheMs?: number;

Defined in: @gramota/trust/dist/jwks-url.d.ts:10

Cache TTL in milliseconds. Default: 5 minutes.

fetcher?

optional fetcher?: Fetcher;

Defined in: @gramota/trust/dist/jwks-url.d.ts:12

Override the global fetch — useful for tests + custom transports.

now?

optional now?: () => number;

Defined in: @gramota/trust/dist/jwks-url.d.ts:14

Override Date.now() — used for cache expiry tests.

Returns

number

---

SdJwtVcIssuerResolverOptions

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:37

Properties

metadataUrl?

optional metadataUrl?: (iss: string) => string;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:39

Override the well-known URL builder. Default: /.well-known/jwt-vc-issuer.

Parameters

iss

string

Returns

string

cacheMs?

optional cacheMs?: number;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:41

Cache TTL in milliseconds. Default: 5 minutes.

fetcher?

optional fetcher?: Fetcher;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:43

Override fetch.

now?

optional now?: () => number;

Defined in: @gramota/trust/dist/sd-jwt-vc-issuer.d.ts:45

Override Date.now() — for tests.

Returns

number

---

TrustContext

Defined in: @gramota/trust/dist/types.d.ts:4

Inputs the resolver gets to make a decision.

Properties

iss

iss: string;

Defined in: @gramota/trust/dist/types.d.ts:6

The iss claim from the JWT payload, if any.

kid

kid: string;

Defined in: @gramota/trust/dist/types.d.ts:8

The kid claim from the JWT protected header, if any.

header

header: Readonly<Record<string, unknown>>;

Defined in: @gramota/trust/dist/types.d.ts:10

The full protected header — useful for x5c, jwk, custom params.

---

TrustResolver

Defined in: @gramota/trust/dist/types.d.ts:15

A pluggable strategy for figuring out which JWK(s) should verify an issuer's JWS. Strategy + Repository pattern: implementations can be a static list, a JWKS URL fetch, an EU Trusted List, or anything custom.

Methods

resolveIssuerKeys()

resolveIssuerKeys(context: TrustContext): Promise<readonly JsonWebKey[]>;

Defined in: @gramota/trust/dist/types.d.ts:19

Return all candidate JWKs that might verify this issuer's JWS. The verifier will try each in order until one succeeds. Throw if no candidate can be produced — that's a trust-resolution failure.

Parameters

context

TrustContext

Returns

Promise<readonly JsonWebKey[]>

Type Aliases

StaticTrustInput

type StaticTrustInput = 
  | readonly JsonWebKey[]
| Readonly<Record<string, readonly JsonWebKey[]>>;

Defined in: @gramota/trust/dist/static.d.ts:4

Constructor input forms for StaticTrustResolver.

---

TrustErrorCode

type TrustErrorCode = 
  | "trust.iss_required"
  | "trust.issuer_not_configured"
  | "trust.fetch_failed"
  | "trust.http_error"
  | "trust.malformed_jwks"
  | "trust.invalid_input";

Defined in: @gramota/trust/dist/types.d.ts:22

Stable codes for TrustResolutionError.

---

Fetcher

type Fetcher = any;