@sd-jwt/core/dist/index.d.ts

sd-jwt draft 7 implementation in typescript

import * as _sd_jwt_types from '@sd-jwt/types';
import { Base64urlString, Signer, Verifier, kbHeader, kbPayload, KbVerifier, JwtPayload, SDJWTCompact, Hasher, PresentationFrame, DisclosureFrame, HasherAndAlg, SaltGenerator, SDJWTConfig, KBOptions } from '@sd-jwt/types';
import { Disclosure } from '@sd-jwt/utils';

type JwtData<Header extends Record<string, unknown>, Payload extends Record<string, unknown>> = {
    header?: Header;
    payload?: Payload;
    signature?: Base64urlString;
    encoded?: string;
};
/**
 * Options for the JWT verifier
 */
type VerifierOptions = {
    /**
     * current time in seconds since epoch
     */
    currentDate?: number;
    /**
     * allowed skew for the current time in seconds. Positive value that will lower the iat and nbf checks, and increase the exp check.
     */
    skewSeconds?: number;
    /**
     * required claim keys for the payload.
     * If the payload does not contain these keys, the verification will fail.
     */
    requiredClaimKeys?: string[];
    /**
     * nonce used to verify the key binding jwt to prevent replay attacks.
     */
    keyBindingNonce?: string;
};
declare class Jwt<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>> {
    header?: Header;
    payload?: Payload;
    signature?: Base64urlString;
    private encoded?;
    constructor(data?: JwtData<Header, Payload>);
    static decodeJWT<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>>(jwt: string): {
        header: Header;
        payload: Payload;
        signature: Base64urlString;
    };
    static fromEncode<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>>(encodedJwt: string): Jwt<Header, Payload>;
    setHeader(header: Header): Jwt<Header, Payload>;
    setPayload(payload: Payload): Jwt<Header, Payload>;
    protected getUnsignedToken(): string;
    sign(signer: Signer): Promise<string>;
    encodeJwt(): string;
    /**
     * Verify the JWT using the provided verifier function.
     * It checks the signature and validates the iat, nbf, and exp claims if they are present.
     * @param verifier
     * @param options - Options for verification, such as current date and skew seconds
     * @returns
     */
    verify(verifier: Verifier, options?: VerifierOptions): Promise<{
        payload: Payload | undefined;
        header: Header | undefined;
    }>;
}

declare class KBJwt<Header extends kbHeader = kbHeader, Payload extends kbPayload = kbPayload> extends Jwt<Header, Payload> {
    verifyKB(values: {
        verifier: KbVerifier;
        payload: JwtPayload;
        nonce: string;
    }): Promise<{
        payload: Payload;
        header: Header;
    }>;
    static fromKBEncode<Header extends kbHeader = kbHeader, Payload extends kbPayload = kbPayload>(encodedJwt: string): KBJwt<Header, Payload>;
}

type SDJwtData<Header extends Record<string, unknown>, Payload extends Record<string, unknown>, KBHeader extends kbHeader = kbHeader, KBPayload extends kbPayload = kbPayload> = {
    jwt?: Jwt<Header, Payload>;
    disclosures?: Array<Disclosure>;
    kbJwt?: KBJwt<KBHeader, KBPayload>;
};
declare class SDJwt<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>, KBHeader extends kbHeader = kbHeader, KBPayload extends kbPayload = kbPayload> {
    jwt?: Jwt<Header, Payload>;
    disclosures?: Array<Disclosure>;
    kbJwt?: KBJwt<KBHeader, KBPayload>;
    constructor(data?: SDJwtData<Header, Payload, KBHeader, KBPayload>);
    static decodeSDJwt<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>, KBHeader extends kbHeader = kbHeader, KBPayload extends kbPayload = kbPayload>(sdjwt: SDJWTCompact, hasher: Hasher): Promise<{
        jwt: Jwt<Header, Payload>;
        disclosures: Array<Disclosure>;
        kbJwt?: KBJwt<KBHeader, KBPayload>;
    }>;
    static extractJwt<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>>(encodedSdJwt: SDJWTCompact): Promise<Jwt<Header, Payload>>;
    static fromEncode<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>, KBHeader extends kbHeader = kbHeader, KBPayload extends kbPayload = kbPayload>(encodedSdJwt: SDJWTCompact, hasher: Hasher): Promise<SDJwt<Header, Payload>>;
    present<T extends Record<string, unknown>>(presentFrame: PresentationFrame<T> | undefined, hasher: Hasher): Promise<SDJWTCompact>;
    getPresentDisclosures<T extends Record<string, unknown>>(presentFrame: PresentationFrame<T> | undefined, hasher: Hasher): Promise<Disclosure<unknown>[]>;
    encodeSDJwt(): SDJWTCompact;
    keys(hasher: Hasher): Promise<string[]>;
    presentableKeys(hasher: Hasher): Promise<string[]>;
    getClaims<T>(hasher: Hasher): Promise<T>;
}
declare const listKeys: (obj: Record<string, unknown>, prefix?: string) => string[];
declare const pack: <T extends Record<string, unknown>>(claims: T, disclosureFrame: DisclosureFrame<T> | undefined, hash: HasherAndAlg, saltGenerator: SaltGenerator) => Promise<{
    packedClaims: Record<string, unknown> | Array<Record<string, unknown>>;
    disclosures: Array<Disclosure>;
}>;

type FlattenJSONData = {
    jwtData: {
        protected: string;
        payload: string;
        signature: string;
    };
    disclosures: Array<string>;
    kb_jwt?: string;
};
type FlattenJSONSerialized = {
    payload: string;
    signature: string;
    protected: string;
    header: {
        disclosures: Array<string>;
        kb_jwt?: string;
    };
};
declare class FlattenJSON {
    disclosures: Array<string>;
    kb_jwt?: string;
    payload: string;
    signature: string;
    protected: string;
    constructor(data: FlattenJSONData);
    static fromEncode(encodedSdJwt: string): FlattenJSON;
    static fromSerialized(json: FlattenJSONSerialized): FlattenJSON;
    toJson(): FlattenJSONSerialized;
    toEncoded(): string;
}

type GeneralJSONData = {
    payload: string;
    disclosures: Array<string>;
    kb_jwt?: string;
    signatures: Array<{
        protected: string;
        signature: string;
        kid?: string;
    }>;
};
type GeneralJSONSerialized = {
    payload: string;
    signatures: Array<{
        header: {
            disclosures?: Array<string>;
            kid?: string;
            kb_jwt?: string;
        };
        protected: string;
        signature: string;
    }>;
};
declare class GeneralJSON {
    payload: string;
    disclosures: Array<string>;
    kb_jwt?: string;
    signatures: Array<{
        protected: string;
        signature: string;
        kid?: string;
    }>;
    constructor(data: GeneralJSONData);
    static fromEncode(encodedSdJwt: string): GeneralJSON;
    static fromSerialized(json: GeneralJSONSerialized): GeneralJSON;
    toJson(): {
        payload: string;
        signatures: ({
            header: {
                kid: string | undefined;
                disclosures?: undefined;
                kb_jwt?: undefined;
            };
            protected: string;
            signature: string;
        } | {
            header: {
                disclosures: string[];
                kid: string | undefined;
                kb_jwt: string | undefined;
            };
            protected: string;
            signature: string;
        })[];
    };
    toEncoded(index: number): string;
    addSignature(protectedHeader: Record<string, unknown>, signer: Signer, kid?: string): Promise<void>;
}

declare const createDecoy: (hash: HasherAndAlg, saltGenerator: SaltGenerator) => Promise<string>;

type SdJwtPayload = Record<string, unknown>;
declare class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
    protected type?: string;
    static readonly DEFAULT_hashAlg = "sha-256";
    protected userConfig: SDJWTConfig;
    constructor(userConfig?: SDJWTConfig);
    private createKBJwt;
    private SignJwt;
    private VerifyJwt;
    issue<Payload extends ExtendedPayload>(payload: Payload, disclosureFrame?: DisclosureFrame<Payload>, options?: {
        header?: object;
    }): Promise<SDJWTCompact>;
    /**
     * Validates if the disclosureFrame contains any reserved fields. If so it will throw an error.
     * @param disclosureFrame
     * @returns
     */
    protected validateReservedFields<T extends ExtendedPayload>(disclosureFrame: DisclosureFrame<T>): void;
    present<T extends Record<string, unknown>>(encodedSDJwt: string, presentationFrame?: PresentationFrame<T>, options?: {
        kb?: KBOptions;
    }): Promise<SDJWTCompact>;
    verify(encodedSDJwt: string, options?: VerifierOptions): Promise<{
        payload: unknown;
        header: Record<string, unknown> | undefined;
        kb?: undefined;
    } | {
        payload: unknown;
        header: Record<string, unknown> | undefined;
        kb: {
            payload: _sd_jwt_types.kbPayload;
            header: _sd_jwt_types.kbHeader;
        };
    }>;
    private calculateSDHash;
    /**
     * This function is for validating the SD JWT
     * Checking signature, if provided the iat and exp when provided and return its the claims
     * @param encodedSDJwt
     * @param options
     * @returns
     */
    validate(encodedSDJwt: string, options?: VerifierOptions): Promise<{
        payload: unknown;
        header: Record<string, unknown> | undefined;
    }>;
    config(newConfig: SDJWTConfig): void;
    encode(sdJwt: SDJwt): SDJWTCompact;
    decode(endcodedSDJwt: SDJWTCompact): Promise<SDJwt<Record<string, unknown>, Record<string, unknown>, _sd_jwt_types.kbHeader, _sd_jwt_types.kbPayload>>;
    keys(endcodedSDJwt: SDJWTCompact): Promise<string[]>;
    presentableKeys(endcodedSDJwt: SDJWTCompact): Promise<string[]>;
    getClaims(endcodedSDJwt: SDJWTCompact): Promise<unknown>;
    toFlattenJSON(endcodedSDJwt: SDJWTCompact): FlattenJSON;
    toGeneralJSON(endcodedSDJwt: SDJWTCompact): GeneralJSON;
}
declare class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
    protected type?: string;
    static readonly DEFAULT_hashAlg = "sha-256";
    protected userConfig: SDJWTConfig;
    constructor(userConfig?: SDJWTConfig);
    private createKBJwt;
    private encodeObj;
    issue<Payload extends ExtendedPayload>(payload: Payload, disclosureFrame: DisclosureFrame<Payload> | undefined, options: {
        sigs: Array<{
            signer: Signer;
            alg: string;
            kid: string;
            header?: Record<string, unknown>;
        }>;
    }): Promise<GeneralJSON>;
    /**
     * Validates if the disclosureFrame contains any reserved fields. If so it will throw an error.
     * @param disclosureFrame
     * @returns
     */
    protected validateReservedFields<T extends ExtendedPayload>(disclosureFrame: DisclosureFrame<T>): void;
    present<T extends Record<string, unknown>>(generalJSON: GeneralJSON, presentationFrame?: PresentationFrame<T>, options?: {
        kb?: KBOptions;
    }): Promise<GeneralJSON>;
    verify(generalJSON: GeneralJSON, options?: VerifierOptions): Promise<{
        payload: unknown;
        headers: any[];
        kb?: undefined;
    } | {
        payload: unknown;
        headers: any[];
        kb: {
            payload: _sd_jwt_types.kbPayload;
            header: _sd_jwt_types.kbHeader;
        };
    }>;
    private calculateSDHash;
    validate(generalJSON: GeneralJSON): Promise<{
        payload: unknown;
        headers: any[];
    }>;
    config(newConfig: SDJWTConfig): void;
    encode(sdJwt: GeneralJSON, index: number): SDJWTCompact;
    decode(endcodedSDJwt: SDJWTCompact): GeneralJSON;
    keys(generalSdjwt: GeneralJSON): Promise<string[]>;
    presentableKeys(generalSdjwt: GeneralJSON): Promise<string[]>;
    getClaims(generalSdjwt: GeneralJSON): Promise<unknown>;
}

export { FlattenJSON, type FlattenJSONData, type FlattenJSONSerialized, GeneralJSON, type GeneralJSONData, type GeneralJSONSerialized, Jwt, type JwtData, KBJwt, SDJwt, type SDJwtData, SDJwtGeneralJSONInstance, SDJwtInstance, type SdJwtPayload, type VerifierOptions, createDecoy, listKeys, pack };