@gramota/status-list

IETF Token Status List + StatusResolver Strategy for revocation / suspension.

Install: pnpm add @gramota/status-list

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

Classes

StatusListResolver

Defined in: @gramota/status-list/dist/resolver.d.ts:57

IETF Token Status List resolver — the default resolver.

Pure delegation to checkCredentialStatus; the only thing this class adds is the Strategy shape so it composes through DI.

Implements

StatusResolver

Constructors

Constructor

new StatusListResolver(config: StatusListResolverConfig): StatusListResolver;

Defined in: @gramota/status-list/dist/resolver.d.ts:59

Parameters

config

StatusListResolverConfig

Returns

StatusListResolver

Methods

resolveStatus()

resolveStatus(credential: ParsedSdJwt, options?: ResolveStatusOptions): Promise<CredentialStatusResult | "skipped">;

Defined in: @gramota/status-list/dist/resolver.d.ts:60

Parameters

credential

ParsedSdJwt

options?

ResolveStatusOptions

Returns

Promise<CredentialStatusResult | "skipped">

Implementation of

StatusResolver.resolveStatus

StatusListError

Defined in: @gramota/status-list/dist/types.d.ts:73

Extends

GramotaError

Constructors

Constructor

new StatusListError(
   code: StatusListErrorCode, 
   message: string, 
   options?: {
  cause?: unknown;
}): StatusListError;

Defined in: @gramota/status-list/dist/types.d.ts:75

Parameters

code

StatusListErrorCode

message

string

options?

cause?

unknown

Returns

StatusListError

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: StatusListErrorCode;

Defined in: @gramota/status-list/dist/types.d.ts:74

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

BuildStatusListOptions

Defined in: @gramota/status-list/dist/build.d.ts:3

Properties

issuer

issuer: string;

Defined in: @gramota/status-list/dist/build.d.ts:5

Issuer URL (= iss claim).

subject

subject: string;

Defined in: @gramota/status-list/dist/build.d.ts:8

Public list URL (= sub claim, MUST equal the URL the list will be fetched from — the verifier enforces match).

length

length: number;

Defined in: @gramota/status-list/dist/build.d.ts:10

Number of statuses to encode. The packed bytes are sized to fit.

bits?

optional bits?: StatusBits;

Defined in: @gramota/status-list/dist/build.d.ts:12

Bit-width per status. Default: 1 (valid/invalid only).

issuedAt?

optional issuedAt?: number;

Defined in: @gramota/status-list/dist/build.d.ts:14

Issued-at, unix seconds. Default: now.

expiresAt?

optional expiresAt?: number;

Defined in: @gramota/status-list/dist/build.d.ts:16

Optional expiry, unix seconds.

ttl?

optional ttl?: number;

Defined in: @gramota/status-list/dist/build.d.ts:18

Optional caching TTL hint.

initial?

optional initial?: Readonly<Record<number, number>>;

Defined in: @gramota/status-list/dist/build.d.ts:20

Initial statuses — index → code. Codes default to 0 (valid).

privateKey

privateKey: JsonWebKey;

Defined in: @gramota/status-list/dist/build.d.ts:22

Issuer's signing JWK.

alg

alg: SupportedAlg;

Defined in: @gramota/status-list/dist/build.d.ts:24

JWS algorithm — must match the key.

kid?

optional kid?: string;

Defined in: @gramota/status-list/dist/build.d.ts:26

Key id for the JWS header (so verifiers can pick the right JWK).

CheckCredentialStatusOptions

Defined in: @gramota/status-list/dist/check.d.ts:5

Properties

trustedIssuers

trustedIssuers: readonly JsonWebKey[];

Defined in: @gramota/status-list/dist/check.d.ts:8

Trusted issuer JWKs — the status list's signature must verify against one. Same semantics as everywhere else in the SDK.

fetcher?

optional fetcher?: Fetcher;

Defined in: @gramota/status-list/dist/check.d.ts:10

Override fetch — for tests.

now?

optional now?: () => number;

Defined in: @gramota/status-list/dist/check.d.ts:12

Override "now" — for expiry checks.

Returns

number

list?

optional list?: StatusList;

Defined in: @gramota/status-list/dist/check.d.ts:15

Pre-fetched / cached list — skip the network if supplied. The list is still validated (sub match, expiry) before use.

FetchStatusListOptions

Defined in: @gramota/status-list/dist/fetch.d.ts:4

Properties

fetcher?

optional fetcher?: Fetcher;

Defined in: @gramota/status-list/dist/fetch.d.ts:6

Override fetch — for tests.

trustedIssuers?

optional trustedIssuers?: readonly JsonWebKey[];

Defined in: @gramota/status-list/dist/fetch.d.ts:9

Trusted issuer JWKs the list's signature must verify against. If omitted, the list is parsed but its signature is NOT checked.

now?

optional now?: () => number;

Defined in: @gramota/status-list/dist/fetch.d.ts:11

Override "now" — for expiry checks. Defaults to system time.

Returns

number

ResolveStatusOptions

Defined in: @gramota/status-list/dist/resolver.d.ts:24

Per-call options that may vary independently of resolver config.

Properties

now?

optional now?: () => number;

Defined in: @gramota/status-list/dist/resolver.d.ts:26

Override "now" — for tests + frozen-time environments.

Returns

number

StatusResolver

Defined in: @gramota/status-list/dist/resolver.d.ts:39

Strategy interface for resolving a credential's status.

Returns "skipped" when the credential carries no status reference and the resolver couldn't (or wasn't asked to) infer one. The verifier decides how to interpret "skipped" — fail or pass — based on policy (requireStatus per call).

Implementations are pure (no per-flow state); a single instance can serve many concurrent verifications.

Methods

resolveStatus()

resolveStatus(credential: ParsedSdJwt, options?: ResolveStatusOptions): Promise<CredentialStatusResult | "skipped">;

Defined in: @gramota/status-list/dist/resolver.d.ts:40

Parameters

credential

ParsedSdJwt

options?

ResolveStatusOptions

Returns

Promise<CredentialStatusResult | "skipped">

StatusListResolverConfig

Defined in: @gramota/status-list/dist/resolver.d.ts:42

Properties

trustedIssuers

trustedIssuers: readonly JsonWebKey[];

Defined in: @gramota/status-list/dist/resolver.d.ts:44

Trusted JWKs the status-list signature must verify against.

fetcher?

optional fetcher?: Fetcher;

Defined in: @gramota/status-list/dist/resolver.d.ts:46

Optional fetcher override.

list?

optional list?: StatusList;

Defined in: @gramota/status-list/dist/resolver.d.ts:49

Pre-fetched / cached list — skip the network when supplied. The sub of the list must match the credential's status URI.

StatusReference

Defined in: @gramota/status-list/dist/types.d.ts:25

A reference to a credential's status — embedded as status.status_list in the credential payload.

Properties

uri

uri: string;

Defined in: @gramota/status-list/dist/types.d.ts:27

URL where the wallet/verifier fetches the status list token.

idx

idx: number;

Defined in: @gramota/status-list/dist/types.d.ts:29

0-based index into the list.

StatusList

Defined in: @gramota/status-list/dist/types.d.ts:34

A parsed (decoded + decompressed) status list.

Properties

bits

bits: StatusBits;

Defined in: @gramota/status-list/dist/types.d.ts:36

Bit-width of each status entry.

bytes

bytes: Uint8Array;

Defined in: @gramota/status-list/dist/types.d.ts:39

Decompressed raw bitstring. Each byte holds 8/bits statuses (for bits=1, 8 statuses; bits=2, 4 statuses; etc.).

length

length: number;

Defined in: @gramota/status-list/dist/types.d.ts:41

Total number of statuses encoded — derived from bytes.length.

issuer

issuer: string;

Defined in: @gramota/status-list/dist/types.d.ts:43

Issuer of the list (iss claim of the status list token).

subject

subject: string;

Defined in: @gramota/status-list/dist/types.d.ts:46

The list's own URL / subject (sub claim — should match the URI used to fetch it).

issuedAt

issuedAt: number;

Defined in: @gramota/status-list/dist/types.d.ts:48

Issued-at, unix seconds.

expiresAt?

optional expiresAt?: number;

Defined in: @gramota/status-list/dist/types.d.ts:50

Expiry (unix seconds), if the issuer set one.

ttl?

optional ttl?: number;

Defined in: @gramota/status-list/dist/types.d.ts:52

Caching hint (seconds), if set.

CredentialStatusResult

Defined in: @gramota/status-list/dist/types.d.ts:61

Result of resolving a credential's status.

Properties

code

code: number;

Defined in: @gramota/status-list/dist/types.d.ts:63

Numeric status code.

state

state: StatusState;

Defined in: @gramota/status-list/dist/types.d.ts:65

Human-readable label.

list

list: StatusList;

Defined in: @gramota/status-list/dist/types.d.ts:67

The list that was consulted.

reference

reference: StatusReference;

Defined in: @gramota/status-list/dist/types.d.ts:69

The reference that pointed at the list.

Type Aliases

StatusBits

type StatusBits = 1 | 2 | 4 | 8;

Defined in: @gramota/status-list/dist/types.d.ts:32

Permitted bit-widths per status (RFC requires one of these).

StatusState

type StatusState = "valid" | "invalid" | "suspended" | "application_specific" | "unknown";

Defined in: @gramota/status-list/dist/types.d.ts:59

Friendly label for a status code.

StatusListErrorCode

type StatusListErrorCode = 
  | "status_list.invalid_input"
  | "status_list.invalid_token"
  | "status_list.invalid_payload"
  | "status_list.invalid_compression"
  | "status_list.invalid_bits"
  | "status_list.index_out_of_range"
  | "status_list.fetch_failed"
  | "status_list.signature_invalid"
  | "status_list.subject_mismatch"
  | "status_list.expired"
  | "status_list.no_status_reference";

Defined in: @gramota/status-list/dist/types.d.ts:72

Stable error codes for StatusListError.

Fetcher

type Fetcher = any;

Variables

STATUS_VALID

const STATUS_VALID: 0 = 0;

Defined in: @gramota/status-list/dist/types.d.ts:55

Status code values defined by the spec.

STATUS_INVALID

const STATUS_INVALID: 1 = 1;

Defined in: @gramota/status-list/dist/types.d.ts:56

STATUS_SUSPENDED

const STATUS_SUSPENDED: 2 = 2;

Defined in: @gramota/status-list/dist/types.d.ts:57

Functions

buildStatusListToken()

function buildStatusListToken(options: BuildStatusListOptions): Promise<string>;

Defined in: @gramota/status-list/dist/build.d.ts:34

Build a signed Status List token (compact JWS) per the IETF spec.

Returns the compact JWS string. Hosting it at the URL passed as subject makes it a real, fetchable status list.

Parameters

options

BuildStatusListOptions

Returns

Promise<string>

checkCredentialStatus()

function checkCredentialStatus(credential: ParsedSdJwt, options: CheckCredentialStatusOptions): Promise<CredentialStatusResult>;

Defined in: @gramota/status-list/dist/check.d.ts:30

Resolve a credential's status per IETF Token Status List.

Read the credential's status.status_list = { uri, idx }.
Fetch the list (or use one passed in via options.list).
Verify its signature against trustedIssuers.
Read the bit(s) at idx.
Return a structured result with code + state.

Throws StatusListError("status_list.no_status_reference") if the credential has no status claim — callers should treat that as "issuer didn't opt into revocation" (not as a verification failure).

Parameters

credential

ParsedSdJwt

options

CheckCredentialStatusOptions

Returns

Promise<CredentialStatusResult>

readStatusReference()

function readStatusReference(credential: ParsedSdJwt): StatusReference;

Defined in: @gramota/status-list/dist/check.d.ts:32

Pull status.status_list = { uri, idx } out of a parsed credential.

Parameters

credential

ParsedSdJwt

Returns

StatusReference

fetchStatusList()

function fetchStatusList(url: string, options?: FetchStatusListOptions): Promise<StatusList>;

Defined in: @gramota/status-list/dist/fetch.d.ts:21

Fetch a status list from url, optionally verify its JWS signature against trustedIssuers, and return the parsed list.

Per the IETF spec, the list's sub claim MUST equal the URL it was fetched from — we enforce this so a stolen list can't be presented for a different URL.

Parameters

url

string

options?

FetchStatusListOptions

Returns

Promise<StatusList>

parseStatusListToken()

function parseStatusListToken(token: string): StatusList;

Defined in: @gramota/status-list/dist/parse.d.ts:19

Parse a Status List token (compact JWS form).

Expected payload claims per the IETF spec: iss — issuer URL (string) sub — list URL (string, MUST equal the URL used to fetch it) iat — issued-at, unix seconds (number) exp — optional expiry (unix seconds) ttl — optional caching hint (seconds) status_list — { bits, lst } bits — 1 | 2 | 4 | 8 lst — base64url(zlib_compressed_bitstring)

NOTE: this function does NOT verify the JWS signature. Use verifyStatusListToken (in fetch.ts / a separate wrapper) when trust matters — i.e., before relying on the result for verification.

Parameters

token

string

Returns

StatusList

parseStatusListPayload()

function parseStatusListPayload(payload: Record<string, unknown>): StatusList;

Defined in: @gramota/status-list/dist/parse.d.ts:21

Parse a status list from an already-decoded JWT payload object.

Parameters

payload

Record<string, unknown>

Returns

StatusList

getStatus()

function getStatus(list: StatusList, index: number): number;

Defined in: @gramota/status-list/dist/parse.d.ts:30

Read the status code at index from a parsed list.

Bit ordering per spec: within a byte, the lowest-numbered indices live in the LSBs. For bits=2: byte 0 = b7 b6 b5 b4 b3 b2 b1 b0 [idx3][idx2][idx1][idx0]

Parameters

list

StatusList

index

number

Returns

number