@sd-jwt/sd-jwt-vc/dist/index.d.mts

sd-jwt draft 7 implementation in typescript

import { SDJWTConfig, Verifier, kbPayload, kbHeader, DisclosureFrame } from '@sd-jwt/types';
import { SdJwtPayload, SDJwtInstance, VerifierOptions } from '@sd-jwt/core';

/**
 * Logo metadata used in rendering a credential.
 */
type Logo = {
    /** REQUIRED. A URI pointing to the logo image. */
    uri: string;
    /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
    'uri#integrity'?: string;
    /** OPTIONAL. A string containing alternative text for the logo image. */
    alt_text?: string;
};
/**
 * The simple rendering method is intended for applications that do not support SVG.
 */
type SimpleRendering = {
    /** OPTIONAL. Logo metadata to display for the credential. */
    logo?: Logo;
    /** OPTIONAL. RGB color value for the credential background (e.g., "#FFFFFF"). */
    background_color?: string;
    /** OPTIONAL. RGB color value for the credential text (e.g., "#000000"). */
    text_color?: string;
};
/** Enum of valid values for rendering orientation. */
type Orientation = 'portrait' | 'landscape';
/** Enum of valid values for rendering color schemes. */
type ColorScheme = 'light' | 'dark';
/** Enum of valid values for rendering contrast. */
type Contrast = 'normal' | 'high';
/**
 * Properties that describe the display preferences for an SVG template rendering.
 */
type SvgTemplateProperties = {
    /** OPTIONAL. Orientation optimized for the template. */
    orientation?: Orientation;
    /** OPTIONAL. Color scheme optimized for the template. */
    color_scheme?: ColorScheme;
    /** OPTIONAL. Contrast level optimized for the template. */
    contrast?: Contrast;
};
/**
 * SVG rendering metadata containing URI and optional integrity and properties.
 */
type SvgTemplateRendering = {
    /** REQUIRED. A URI pointing to the SVG template. */
    uri: string;
    /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
    'uri#integrity'?: string;
    /** REQUIRED if more than one SVG template is present. */
    properties?: SvgTemplateProperties;
};
/**
 * Rendering metadata, either simple or SVG-based, for a credential.
 */
type Rendering = {
    /** OPTIONAL. Simple rendering metadata. */
    simple?: SimpleRendering;
    /** OPTIONAL. Array of SVG template rendering objects. */
    svg_template?: SvgTemplateRendering[];
};
/**
 * Display metadata associated with a credential type.
 */
type Display = {
    /** REQUIRED. Language tag according to RFC 5646 (e.g., "en", "de"). */
    lang: string;
    /** REQUIRED. Human-readable name for the credential type. */
    name: string;
    /** OPTIONAL. Description of the credential type for end users. */
    description?: string;
    /** OPTIONAL. Rendering information (simple or SVG) for the credential. */
    rendering?: Rendering;
};
/**
 * Claim path within the credential's JSON structure.
 * Example: ["address", "street_address"]
 */
type ClaimPath = Array<string | null>;
/**
 * Display metadata for a specific claim.
 */
type ClaimDisplay = {
    /** REQUIRED. Language tag according to RFC 5646. */
    lang: string;
    /** REQUIRED. Human-readable label for the claim. */
    label: string;
    /** OPTIONAL. Description of the claim for end users. */
    description?: string;
};
/**
 * Indicates whether a claim is selectively disclosable.
 */
type ClaimSelectiveDisclosure = 'always' | 'allowed' | 'never';
/**
 * Metadata for individual claims in the credential type.
 */
type Claim = {
    /**
     * REQUIRED. Array of one or more paths to the claim in the credential subject.
     * Each path is an array of strings (or null for array elements).
     */
    path: ClaimPath;
    /** OPTIONAL. Display metadata in multiple languages. */
    display?: ClaimDisplay[];
    /** OPTIONAL. Controls whether the claim must, may, or must not be selectively disclosed. */
    sd?: ClaimSelectiveDisclosure;
    /**
     * OPTIONAL. Unique string identifier for referencing the claim in an SVG template.
     * Must consist of alphanumeric characters or underscores and must not start with a digit.
     */
    svg_id?: string;
};
/**
 * Type metadata for a specific Verifiable Credential (VC) type.
 * Reference: https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-09.html#name-type-metadata-format
 */
type TypeMetadataFormat = {
    /** REQUIRED. A URI uniquely identifying the credential type. */
    vct: string;
    /** OPTIONAL. Human-readable name for developers. */
    name?: string;
    /** OPTIONAL. Human-readable description for developers. */
    description?: string;
    /** OPTIONAL. URI of another type that this one extends. */
    extends?: string;
    /** OPTIONAL. Integrity metadata for the 'extends' field. */
    'extends#Integrity'?: string;
    /** OPTIONAL. Array of localized display metadata for the type. */
    display?: Display[];
    /** OPTIONAL. Array of claim metadata. */
    claims?: Claim[];
    /**
     * OPTIONAL. Embedded JSON Schema describing the VC structure.
     * Must not be present if schema_uri is provided.
     */
    schema?: object;
    /**
     * OPTIONAL. URI pointing to a JSON Schema for the VC structure.
     * Must not be present if schema is provided.
     */
    schema_uri?: string;
    /** OPTIONAL. Integrity metadata for the schema_uri field. */
    'schema_uri#Integrity'?: string;
};

type VcTFetcher = (uri: string, integrity?: string) => Promise<TypeMetadataFormat>;

type StatusListFetcher = (uri: string) => Promise<string>;
type StatusValidator = (status: number) => Promise<void>;
/**
 * Configuration for SD-JWT-VC
 */
type SDJWTVCConfig = SDJWTConfig & {
    statusListFetcher?: StatusListFetcher;
    statusValidator?: StatusValidator;
    vctFetcher?: VcTFetcher;
    statusVerifier?: Verifier;
    loadTypeMetadataFormat?: boolean;
    timeout?: number;
};

interface SDJWTVCStatusReference {
    status_list: {
        idx: number;
        uri: string;
    };
}

interface SdJwtVcPayload extends SdJwtPayload {
    iss?: string;
    nbf?: number;
    exp?: number;
    cnf?: unknown;
    vct: string;
    'vct#Integrity'?: string;
    status?: SDJWTVCStatusReference;
    sub?: string;
    iat?: number;
}

type VerificationResult = {
    payload: SdJwtVcPayload;
    header: Record<string, unknown> | undefined;
    kb: {
        payload: kbPayload;
        header: kbHeader;
    } | undefined;
    typeMetadataFormat?: TypeMetadataFormat;
};

declare class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
    /**
     * The type of the SD-JWT-VC set in the header.typ field.
     */
    protected type: string;
    protected userConfig: SDJWTVCConfig;
    constructor(userConfig?: SDJWTVCConfig);
    /**
     * Validates if the disclosureFrame contains any reserved fields. If so it will throw an error.
     * @param disclosureFrame
     */
    protected validateReservedFields(disclosureFrame: DisclosureFrame<SdJwtVcPayload>): void;
    /**
     * Fetches the status list from the uri with a timeout of 10 seconds.
     * @param uri The URI to fetch from.
     * @returns A promise that resolves to a compact JWT.
     */
    private statusListFetcher;
    /**
     * Validates the status, throws an error if the status is not 0.
     * @param status
     * @returns
     */
    private statusValidator;
    /**
     * Verifies the SD-JWT-VC. It will validate the signature, the keybindings when required, the status, and the VCT.
     * @param currentDate current time in seconds
     */
    verify(encodedSDJwt: string, options?: VerifierOptions): Promise<VerificationResult>;
    /**
     * Gets VCT Metadata of the raw SD-JWT-VC. Returns the type metadata format. If the SD-JWT-VC is invalid or does not contain a vct claim, an error is thrown.
     * @param encodedSDJwt
     * @returns
     */
    getVct(encodedSDJwt: string): Promise<TypeMetadataFormat>;
    /**
     * Validates the integrity of the response if the integrity is passed. If the integrity does not match, an error is thrown.
     * @param integrity
     * @param response
     */
    private validateIntegrity;
    /**
     * Fetches the content from the url with a timeout of 10 seconds.
     * @param url
     * @returns
     */
    private fetch;
    /**
     * Loads the schema either from the object or as fallback from the uri.
     * @param typeMetadataFormat
     * @returns
     */
    private loadSchema;
    /**
     * Verifies the VCT of the SD-JWT-VC. Returns the type metadata format. If the schema does not match, an error is thrown. If it matches, it will return the type metadata format.
     * @param result
     * @returns
     */
    private verifyVct;
    /**
     * Fetches VCT Metadata of the SD-JWT-VC. Returns the type metadata format. If the SD-JWT-VC does not contain a vct claim, an error is thrown.
     * @param result
     * @returns
     */
    private fetchVct;
    /**
     * Fetches VCT Metadata from the header of the SD-JWT-VC. Returns the type metadata format. If the SD-JWT-VC does not contain a vct claim, an error is thrown.
     * @param result
     * @param
     */
    private fetchVctFromHeader;
    /**
     * Verifies the status of the SD-JWT-VC.
     * @param result
     * @param options
     */
    private verifyStatus;
}

export { type Claim, type ClaimDisplay, type ClaimPath, type ClaimSelectiveDisclosure, type Display, type Logo, type Rendering, type SDJWTVCConfig, type SDJWTVCStatusReference, SDJwtVcInstance, type SdJwtVcPayload, type SimpleRendering, type StatusListFetcher, type StatusValidator, type SvgTemplateProperties, type SvgTemplateRendering, type TypeMetadataFormat, type VcTFetcher, type VerificationResult };