Class: Sdsdk

The Sdsdk class is the central entry point of the SDK. It holds the KAS configuration and exposes the encrypt and decrypt methods.

An Sdsdk instance is stateful: its configuration impacts encryption and decryption behavior, DEK wrapping strategies, and access control enforcement.

Constructor

new Sdsdk(configuration: SdsdkConfiguration)

SdsdkConfiguration

Object containing Sdsdk configuration.

• defaultKasId (String) The default KAS identifier. It must match one of the kasList IDs.

• kasList (Array) List of KAS, where each KAS is a RemoteKas or a LocalKas.

  RemoteKas

  • id (String) Unique identifier for the KAS. Any non-empty string of your choice. Id must be unique in the Kaslist.
  • protocols (Array) List of protocols supported by the KAS ('kas' or 'symmetric_kas').
  • url (String) URL of the remote KAS.
  • authentication (Object) RemoteKas authentication. ⚠️ secret
    • type (String) 'bearer' | 'basic'
    • value (String) The raw JWT value for 'bearer' or the Base64(user:password) for 'basic' (see: RemoteKas authentication setup)
  • optional publicKey (Object) Public key used for DEK encryption. Required when protocols includes 'kas'. (see: RemoteKas setup)
    • kid (String) Unique identifier of the asymmetric key in the Remote KAS.
    • value (String) Value of the public key in PEM format.

  LocalKas

  • id (String) Unique identifier for the KAS. Any non-empty string of your choice. Id must be unique in the Kaslist.
  • protocols (Array) List of protocols supported by the KAS ('local_symmetric_kas').
  • kek (Uint8Array) Key Encryption Key used for DEK wrapping. It must be a 32-byte Uint8Array generated with a true random number generator (TRNG). ⚠️ secret

  ⚠️ The kasList can only contain 1 LocalKas.

• mappingSections (Optional) (Array) Configuration to dynamically select some KAS in the kasList depending on dataAttributes sent during encryption. List of MappingSection.

  MappingSection

  • label (String) Label of the mapping section.
  • mapping (Array) List of mappings.
    mapping

    • attributeName (String) Name of the attribute. Will match DataAttributes with top-level-key matching the referenced value.
    • type (String) Defines how matching KAS are grouped during encryption.
      • MappingItemType.Permissive (permissive): matching KAS are grouped together (logical OR).
      • MappingItemType.Restrictive (restrictive): each matching KAS generates an independent encryption split.
    • attributeValues (Array) List of AttributeValues.
      • value (String) Value of the DataAttribute to map. Will match the top-level keys of DataAttributes objects.
      • kasIds (Array) List of KAS IDs. Each ID must exist in the kasList.

⚠️ For the moment, only one mappingSection item is allowed in the mappingSections list. Each additional mappingSections item will cause an error. However, each section may contain multiple mapping items.

Examples

Minimal configuration - single RemoteKas - Protocol kas

import { Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const config: SdsdkConfiguration = {
  defaultKasId: 'kas-1',
  kasList: [
    {
      id: 'kas-1',
      protocols: [Protocol.Kas],
      url: 'https://kas.example.com/api/v1/kas',
      publicKey: {
        kid: 'my-kid',
        value: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
      },
      // can be omitted when using only encryption, but required for decryption
      authentication: {
        type: 'bearer',
        value: 'my-jwt-token', // ⚠️ **secret**
      },
    },
  ],
};

const sdsdk = new Sdsdk(config);

Minimal configuration - single RemoteKas - Protocol symmetric_kas

import { Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const config: SdsdkConfiguration = {
  defaultKasId: 'kas-1',
  kasList: [
    {
      id: 'kas-1',
      protocols: [Protocol.SymmetricKas],
      url: 'https://kas.example.com/api/v1/kas',
      authentication: {
        type: 'bearer',
        value: 'my-jwt-token', // ⚠️ **secret**
      },
    },
  ],
};

const sdsdk = new Sdsdk(config);

Minimal configuration - single LocalKas

import { Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const kek = crypto.getRandomValues(new Uint8Array(32));

const config: SdsdkConfiguration = {
  defaultKasId: 'local-kas',
  kasList: [
    {
      id: 'local-kas',
      protocols: [Protocol.LocalSymmetricKas],
      kek, // ⚠️ **secret**
    },
  ],
};

const sdsdk = new Sdsdk(config);

Advanced multi-KAS configuration with mapping

import { MappingItemType, Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const config: SdsdkConfiguration = {
  defaultKasId: 'kas-1',
  kasList: [
    {
      id: 'kas-1',
      protocols: [Protocol.Kas, Protocol.SymmetricKas], // <- RemoteKas can support both protocols
      url: 'https://kas-1.example.com/api/v1/cb724d79-51e8-4816-b200-c0e88751bf89/kas',
      publicKey: {
        kid: 'my-kid',
        value: '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh[...]IBCgKCAQEA\n-----END PUBLIC KEY-----',
      },
      authentication: {
        type: 'basic',
        value: 'my-api-key', // ⚠️ secret
      },
    },
    {
      id: 'kas-2',
      protocols: [Protocol.Kas], // <- ... Or only one
      url: 'https://kas-2.example.com/api/v1/0f076525-684d-4289-9e09-3b2b105a6295/kas',
      publicKey: {
        kid: 'my-kid',
        value:
          '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQ[...]EFAAOCAQ8AMIIBCgKCAQEA\n-----END PUBLIC KEY-----',
      },
      authentication: {
        type: 'bearer',
        value: 'my-jwt-token', // ⚠️ secret
      },
    },
  ],
  mappingSections: [
    {
      label: 'default-mapping',
      mapping: [
        {
          attributeName: 'releasableTo',
          type: MappingItemType.Permissive,
          attributeValues: [
            { value: 'FRA', kasIds: ['kas-1', 'kas-2'] },
            { value: 'EN', kasIds: ['kas-2'] },
          ],
        },
      ],
    },
  ],
};

const sdsdk = new Sdsdk(config);

See the Dynamic KAS selection Mappings page for full behavior explanation (splits, SID, permissive vs restrictive, AND/OR model).