@sd-jwt/sd-jwt-vc 0.1.0

package/src/sd-jwt-vc-type-metadata-format.ts

@@ -0,0 +1,271 @@
+import { z } from 'zod';
+
+export const BackgroundImageSchema = z.looseObject({
+  /** REQUIRED. A URI pointing to the background image. */
+  uri: z.string(),
+  /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
+  'uri#integrity': z.string().optional(),
+});
+export type BackgroundImage = z.infer<typeof BackgroundImageSchema>;
+
+/**
+ * Logo metadata used in rendering a credential.
+ */
+export const LogoSchema = z.looseObject({
+  /** REQUIRED. A URI pointing to the logo image. */
+  uri: z.string(),
+  /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
+  'uri#integrity': z.string().optional(),
+  /** OPTIONAL. A string containing alternative text for the logo image. */
+  alt_text: z.string().optional(),
+});
+
+export type Logo = z.infer<typeof LogoSchema>;
+
+/**
+ * The simple rendering method is intended for applications that do not support SVG.
+ */
+export const SimpleRenderingSchema = z.looseObject({
+  /** OPTIONAL. Logo metadata to display for the credential. */
+  logo: LogoSchema.optional(),
+  /** OPTIONAL. RGB color value for the credential background (e.g., "#FFFFFF"). */
+  background_color: z.string().optional(),
+  /** OPTIONAL. RGB color value for the credential text (e.g., "#000000"). */
+  text_color: z.string().optional(),
+  /** OPTIONAL. An object containing information about the background image to be displayed for the type. */
+  background_image: BackgroundImageSchema.optional(),
+});
+
+export type SimpleRendering = z.infer<typeof SimpleRenderingSchema>;
+
+/** Enum of valid values for rendering orientation. */
+export const OrientationSchema = z.enum(['portrait', 'landscape']);
+
+/** Enum of valid values for rendering color schemes. */
+export const ColorSchemeSchema = z.enum(['light', 'dark']);
+
+/** Enum of valid values for rendering contrast. */
+export const ContrastSchema = z.enum(['normal', 'high']);
+
+/**
+ * Properties that describe the display preferences for an SVG template rendering.
+ */
+export const SvgTemplatePropertiesSchema = z.looseObject({
+  /** OPTIONAL. Orientation optimized for the template. */
+  orientation: OrientationSchema.optional(),
+  /** OPTIONAL. Color scheme optimized for the template. */
+  color_scheme: ColorSchemeSchema.optional(),
+  /** OPTIONAL. Contrast level optimized for the template. */
+  contrast: ContrastSchema.optional(),
+});
+
+export type SvgTemplateProperties = z.infer<typeof SvgTemplatePropertiesSchema>;
+
+/**
+ * SVG rendering metadata containing URI and optional integrity and properties.
+ */
+export const SvgTemplateRenderingSchema = z.looseObject({
+  /** REQUIRED. A URI pointing to the SVG template. */
+  uri: z.string(),
+  /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
+  'uri#integrity': z.string().optional(),
+  /** REQUIRED if more than one SVG template is present. */
+  properties: SvgTemplatePropertiesSchema.optional(),
+});
+
+export type SvgTemplateRendering = z.infer<typeof SvgTemplateRenderingSchema>;
+
+/**
+ * Rendering metadata, either simple or SVG-based, for a credential.
+ */
+export const RenderingSchema = z
+  .looseObject({
+    /** OPTIONAL. Simple rendering metadata. */
+    simple: SimpleRenderingSchema.optional(),
+    /** OPTIONAL. Array of SVG template rendering objects. */
+    svg_templates: z.array(SvgTemplateRenderingSchema).optional(),
+    /**
+     * OPTIONAL. Array of SVG template rendering objects.
+     * @deprecated use `svg_templates` (plural) instead.
+     */
+    svg_template: z.array(SvgTemplateRenderingSchema).optional(),
+  })
+  .transform(({ svg_template, svg_templates, ...rest }) => ({
+    ...rest,
+    svg_templates: svg_templates ?? svg_template,
+  }));
+
+export type Rendering = z.infer<typeof RenderingSchema>;
+
+/**
+ * Display metadata associated with a credential type.
+ */
+export const DisplaySchema = z
+  .looseObject({
+    /**
+     * Language tag according to RFC 5646 (e.g., "en", "de").
+     * @deprecated - use `locale` instead
+     */
+    lang: z.string().optional(),
+
+    /**
+     * REQUIRED (preferred). Language tag according to RFC 5646.
+     * Alias for `lang` - either `lang` or `locale` must be provided.
+     */
+    locale: z.string().optional(),
+
+    /** REQUIRED. Human-readable name for the credential type. */
+    name: z.string(),
+    /** OPTIONAL. Description of the credential type for end users. */
+    description: z.string().optional(),
+    /** OPTIONAL. Rendering information (simple or SVG) for the credential. */
+    rendering: RenderingSchema.optional(),
+  })
+  .transform(({ lang, locale, ...rest }) => ({
+    ...rest,
+    locale: locale ?? lang,
+  }))
+  .refine(({ locale }) => locale !== undefined, {
+    message:
+      'Either locale (preferred) or lang (spec name, deprecated) MUST be defined on claim display entry.',
+  });
+
+export type Display = z.infer<typeof DisplaySchema>;
+
+/**
+ * Claim path within the credential's JSON structure.
+ * Example: ["address", "street_address"]
+ */
+export const ClaimPathSchema = z.array(z.string().nullable());
+
+export type ClaimPath = z.infer<typeof ClaimPathSchema>;
+
+/**
+ * Display metadata for a specific claim.
+ */
+export const ClaimDisplaySchema = z
+  .looseObject({
+    /**
+     * Language tag according to RFC 5646.
+     * @deprecated - use `locale` instead
+     */
+    lang: z.string().optional(),
+
+    /**
+     * REQUIRED (preferred). Language tag according to RFC 5646.
+     * Alias for `lang` - either `lang` or `locale` must be provided.
+     */
+    locale: z.string().optional(),
+
+    /** REQUIRED. Human-readable label for the claim. */
+    label: z.string().optional(),
+
+    /**
+     * Human-readable label for the claim.
+     * @deprecated - use `label` instead
+     */
+    name: z.string().optional(),
+
+    /** OPTIONAL. Description of the claim for end users. */
+    description: z.string().optional(),
+  })
+  .transform(({ lang, name, label, locale, ...rest }) => ({
+    ...rest,
+    locale: locale ?? lang,
+    label: label ?? name,
+  }))
+  .refine(({ locale }) => locale !== undefined, {
+    message:
+      'Either locale (preferred) or lang (deprecated) MUST be defined on claim display entry.',
+  })
+  .refine(({ label }) => label !== undefined, {
+    message:
+      'Either label (preferred) or name (deprecated) MUST be defined on claim display entry.',
+  });
+
+export type ClaimDisplay = z.infer<typeof ClaimDisplaySchema>;
+
+/**
+ * Indicates whether a claim is selectively disclosable.
+ */
+export const ClaimSelectiveDisclosureSchema = z.enum([
+  'always',
+  'allowed',
+  'never',
+]);
+
+export type ClaimSelectiveDisclosure = z.infer<
+  typeof ClaimSelectiveDisclosureSchema
+>;
+
+/**
+ * Metadata for individual claims in the credential type.
+ */
+export const ClaimSchema = z.looseObject({
+  /**
+   * 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: ClaimPathSchema,
+  /** OPTIONAL. Display metadata in multiple languages. */
+  display: z.array(ClaimDisplaySchema).optional(),
+  /** OPTIONAL. Controls whether the claim must, may, or must not be selectively disclosed. */
+  sd: ClaimSelectiveDisclosureSchema.optional(),
+  /**
+   * OPTIONAL. A boolean indicating whether the claim must be present in the Unsecured Payload
+   * of the SD-JWT VC. Default is false if not specified.
+   */
+  mandatory: z.boolean().optional(),
+  /**
+   * 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: z.string().optional(),
+});
+
+export type Claim = z.infer<typeof ClaimSchema>;
+
+/**
+ * Type metadata for a specific Verifiable Credential (VC) type.
+ * Reference: https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-13.html#name-type-metadata-format
+ */
+export const TypeMetadataFormatSchema = z.looseObject({
+  /** REQUIRED. A URI uniquely identifying the credential type. */
+  vct: z.string(),
+  /** OPTIONAL. Human-readable name for developers. */
+  name: z.string().optional(),
+  /** OPTIONAL. Human-readable description for developers. */
+  description: z.string().optional(),
+  /** OPTIONAL. URI of another type that this one extends. */
+  extends: z.string().optional(),
+  /** OPTIONAL. Integrity metadata for the 'extends' field. */
+  'extends#integrity': z.string().optional(),
+  /** OPTIONAL. Array of localized display metadata for the type. */
+  display: z.array(DisplaySchema).optional(),
+  /** OPTIONAL. Array of claim metadata. */
+  claims: z.array(ClaimSchema).optional(),
+});
+
+/**
+ * The resolved type metadata. If you just want to use the type metadata, you should use `typeMetadata`.
+ * In case additional processing is needed (e.g. for extensions in type metadata), you can use the `typeMetadataChain`
+ */
+export type ResolvedTypeMetadata = {
+  /**
+   * The merged type metadata based on the resolved `vct` document and all `extends` values.
+   */
+  mergedTypeMetadata: TypeMetadataFormat;
+
+  /**
+   * The original type metadata documents, ordered from the extending type to the last extended type.
+   */
+  typeMetadataChain: [TypeMetadataFormat, ...TypeMetadataFormat[]];
+
+  /**
+   * The vct values present in the type metadata chain. This can be used for matching against e.g.
+   * DCQL queries which can query an underlying type.
+   */
+  vctValues: [string, ...string[]];
+};
+
+export type TypeMetadataFormat = z.infer<typeof TypeMetadataFormatSchema>;

package/src/sd-jwt-vc-vct.ts

@@ -0,0 +1,6 @@
+import type { TypeMetadataFormat } from './sd-jwt-vc-type-metadata-format';
+
+export type VCTFetcher = (
+  uri: string,
+  integrity?: string,
+) => Promise<TypeMetadataFormat | undefined>;

package/src/test/index.spec.ts

@@ -0,0 +1,180 @@
+import Crypto from 'node:crypto';
+import { hasher as digest, generateSalt } from '@owf/crypto';
+import {
+  createHeaderAndPayload,
+  StatusList,
+  type StatusListJWTHeaderParameters,
+} from '@owf/token-status-list';
+import type {
+  DisclosureFrame,
+  JwtPayload,
+  Signer,
+  Verifier,
+} from '@sd-jwt/core';
+import { SignJWT } from 'jose';
+import { describe, expect, test } from 'vitest';
+import { SDJwtVcInstance } from '..';
+import type { SdJwtVcPayload } from '../sd-jwt-vc-payload';
+
+const iss = 'ExampleIssuer';
+const vct = 'ExampleCredentialType';
+const iat = Math.floor(Date.now() / 1000);
+
+const { privateKey, publicKey } = Crypto.generateKeyPairSync('ed25519');
+
+//create a separate keypair for the status list
+const { privateKey: statusListPrivateKey, publicKey: statusListPublicKey } =
+  Crypto.generateKeyPairSync('ed25519');
+
+//TODO: to simulate a hosted status list, use the same appraoch as in vct.spec.ts
+
+const createSignerVerifier = () => {
+  const signer: Signer = async (data: string) => {
+    const sig = Crypto.sign(null, Buffer.from(data), privateKey);
+    return Buffer.from(sig).toString('base64url');
+  };
+  const verifier: Verifier = async (data: string, sig: string) => {
+    return Crypto.verify(
+      null,
+      Buffer.from(data),
+      publicKey,
+      Buffer.from(sig, 'base64url'),
+    );
+  };
+  return { signer, verifier };
+};
+
+const generateStatusList = async (): Promise<string> => {
+  const statusList = new StatusList([0, 1, 0, 0, 0, 0, 1, 1], 1);
+  const payload: JwtPayload = {
+    iss: 'https://example.com',
+    sub: 'https://example.com/status/1',
+    iat: Math.floor(Date.now() / 1000),
+  };
+  const header: StatusListJWTHeaderParameters = {
+    alg: 'EdDSA',
+    typ: 'statuslist+jwt',
+  };
+  const values = createHeaderAndPayload(statusList, payload, header);
+  return new SignJWT(values.payload)
+    .setProtectedHeader(values.header)
+    .sign(statusListPrivateKey);
+};
+
+const statusListJWT = await generateStatusList();
+
+describe('App', () => {
+  test('Example', async () => {
+    const { signer, verifier } = createSignerVerifier();
+    const sdjwt = new SDJwtVcInstance({
+      signer,
+      signAlg: 'EdDSA',
+      verifier,
+      hasher: digest,
+      hashAlg: 'sha-256',
+      saltGenerator: generateSalt,
+    });
+
+    const claims = {
+      firstname: 'John',
+    };
+    const disclosureFrame = {
+      _sd: ['firstname', 'iss'],
+    };
+
+    const expectedPayload: SdJwtVcPayload = { iat, iss, vct, ...claims };
+    const encodedSdjwt = sdjwt.issue(
+      expectedPayload,
+      disclosureFrame as unknown as DisclosureFrame<SdJwtVcPayload>,
+    );
+    await expect(encodedSdjwt).rejects.toThrowError();
+  });
+});
+
+describe('Revocation', () => {
+  const { signer, verifier } = createSignerVerifier();
+  const sdjwt = new SDJwtVcInstance({
+    signer,
+    signAlg: 'EdDSA',
+    verifier,
+    hasher: digest,
+    hashAlg: 'sha-256',
+    saltGenerator: generateSalt,
+    statusListFetcher(_uri: string) {
+      // we emulate fetching the status list from the uri. Validation of the JWT is not done here in the test but should be done in the implementation.
+      return Promise.resolve(statusListJWT);
+    },
+    // statusValidator(status: number) {
+    //   // we are only accepting status 0
+    //   if (status === 0) return Promise.resolve();
+    //   throw new Error('Status is not valid');
+    // },
+    statusVerifier: async (data: string, sig: string) => {
+      //we could also look into the data to extract the public key from the x5c when provided
+      return Crypto.verify(
+        null,
+        Buffer.from(data),
+        statusListPublicKey,
+        Buffer.from(sig, 'base64url'),
+      );
+    },
+  });
+
+  test('Test with a non revoked credential', async () => {
+    const claims = {
+      firstname: 'John',
+      status: {
+        status_list: {
+          uri: 'https://example.com/status-list',
+          idx: 0,
+        },
+      },
+    };
+    const expectedPayload: SdJwtVcPayload = { iat, iss, vct, ...claims };
+    const encodedSdjwt = await sdjwt.issue(expectedPayload);
+    const result = await sdjwt.verify(encodedSdjwt);
+    expect(result).toBeDefined();
+  });
+
+  test('Test with a revoked credential', async () => {
+    const claims = {
+      firstname: 'John',
+      status: {
+        status_list: {
+          uri: 'https://example.com/status-list',
+          idx: 1,
+        },
+      },
+    };
+    const expectedPayload: SdJwtVcPayload = { iat, iss, vct, ...claims };
+    const encodedSdjwt = await sdjwt.issue(expectedPayload);
+    const result = sdjwt.verify(encodedSdjwt);
+    await expect(result).rejects.toThrowError('Status is not valid');
+  });
+
+  test('Test with a revoked credential but status verification disabled', async () => {
+    const claims = {
+      firstname: 'John',
+      status: {
+        status_list: {
+          uri: 'https://example.com/status-list',
+          idx: 1,
+        },
+      },
+    };
+    const expectedPayload: SdJwtVcPayload = { iat, iss, vct, ...claims };
+    const encodedSdjwt = await sdjwt.issue(expectedPayload);
+    const result = await sdjwt.verify(encodedSdjwt, {
+      disableStatusVerification: true,
+    });
+    expect(result).toBeDefined();
+  });
+
+  test('test to fetch the statuslist', async () => {
+    //TODO: not implemented yet since we need to either mock the fetcher or use a real fetcher
+  });
+
+  test('test with an expired status list', async () => {
+    //TODO: needs to be implemented
+  });
+});