@sphereon/ssi-sdk.data-store 0.36.1-next.115 → 0.36.1-next.129

package/src/issuanceBranding/IssuanceBrandingStore.ts

@@ -44,6 +44,7 @@ import {
   credentialBrandingEntityFrom,
   credentialBrandingFrom,
   credentialLocaleBrandingEntityFrom,
+  credentialLocaleBrandingFromEntity,
   issuerBrandingEntityFrom,
   issuerBrandingFrom,
   issuerLocaleBrandingEntityFrom,
@@ -83,7 +84,7 @@ export class IssuanceBrandingStore extends AbstractIssuanceBrandingStore {
   }
 
   public getCredentialBranding = async (args?: IGetCredentialBrandingArgs): Promise<Array<ICredentialBranding>> => {
-    const { filter } = args ?? {}
+    const { filter, knownStates } = args ?? {}
     if (filter) {
       filter.forEach((filter: IPartialCredentialBranding): void => {
         if (filter.localeBranding && 'locale' in filter.localeBranding && filter.localeBranding.locale === undefined) {
@@ -93,11 +94,48 @@ export class IssuanceBrandingStore extends AbstractIssuanceBrandingStore {
     }
 
     debug('Getting credential branding', args)
-    const result: Array<CredentialBrandingEntity> = await (await this.dbConnection).getRepository(CredentialBrandingEntity).find({
+    const repository: Repository<CredentialBrandingEntity> = (await this.dbConnection).getRepository(CredentialBrandingEntity)
+
+    if (knownStates && Object.keys(knownStates).length > 0) {
+      // First do a lightweight query selecting only id and state to determine which records are "dirty"
+      const stateQuery = repository
+        .createQueryBuilder('branding')
+        .select(['branding.id', 'branding.state'])
+      if (filter) {
+        stateQuery.where(filter)
+      }
+      const stateResults: Array<{ id: string; state: string }> = await stateQuery.getRawMany().then((rows) =>
+        rows.map((row) => ({
+          id: row.branding_id,
+          state: row.branding_state,
+        })),
+      )
+
+      // Filter to find dirty record ids (new or changed state)
+      const dirtyIds: Array<string> = stateResults
+        .filter((result) => {
+          const knownState: string | undefined = knownStates[result.id]
+          return !knownState || knownState !== result.state
+        })
+        .map((result) => result.id)
+
+      if (dirtyIds.length === 0) {
+        return []
+      }
+
+      // Only fetch full data for dirty records
+      const result: Array<CredentialBrandingEntity> = await repository.find({
+        where: { id: In(dirtyIds) },
+      })
+
+      return result.map((branding: CredentialBrandingEntity) => credentialBrandingFrom(branding))
+    }
+
+    const result: Array<CredentialBrandingEntity> = await repository.find({
       ...(filter && { where: filter }),
     })
 
-    return result.map((credentialBranding: CredentialBrandingEntity) => credentialBrandingFrom(credentialBranding))
+    return result.map((branding: CredentialBrandingEntity) => credentialBrandingFrom(branding))
   }
 
   public removeCredentialBranding = async (args: IRemoveCredentialBrandingArgs): Promise<void> => {
@@ -133,7 +171,7 @@ export class IssuanceBrandingStore extends AbstractIssuanceBrandingStore {
       return Promise.reject(Error(`No credential branding found for id: ${credentialBranding.id}`))
     }
 
-    const branding: Omit<ICredentialBranding, 'createdAt' | 'lastUpdatedAt'> = {
+    const branding: Omit<ICredentialBranding, 'createdAt' | 'lastUpdatedAt' | 'state'> = {
       ...credentialBranding,
       localeBranding: credentialBrandingEntity.localeBranding,
     }
@@ -218,7 +256,8 @@ export class IssuanceBrandingStore extends AbstractIssuanceBrandingStore {
 
     return credentialBrandingLocale
       ? credentialBrandingLocale.map(
-          (credentialLocaleBranding: CredentialLocaleBrandingEntity) => localeBrandingFrom(credentialLocaleBranding) as ICredentialLocaleBranding,
+          (credentialLocaleBranding: CredentialLocaleBrandingEntity) =>
+            credentialLocaleBrandingFromEntity(credentialLocaleBranding) as ICredentialLocaleBranding,
         )
       : []
   }
@@ -342,7 +381,7 @@ export class IssuanceBrandingStore extends AbstractIssuanceBrandingStore {
       return Promise.reject(Error(`No issuer branding found for id: ${issuerBranding.id}`))
     }
 
-    const branding: Omit<IIssuerBranding, 'createdAt' | 'lastUpdatedAt'> = {
+    const branding: Omit<IIssuerBranding, 'createdAt' | 'lastUpdatedAt' | 'state'> = {
       ...issuerBranding,
       localeBranding: issuerBrandingEntity.localeBranding,
     }

package/src/migrations/generic/15-AddBrandingState.ts

@@ -0,0 +1,64 @@
+import Debug from 'debug'
+import { DatabaseType, MigrationInterface, QueryRunner } from 'typeorm'
+import { AddBrandingStatePostgres1766000000000 } from '../postgres/1766000000000-AddBrandingState'
+import { AddBrandingStateSqlite1766000000000 } from '../sqlite/1766000000000-AddBrandingState'
+
+const debug: Debug.Debugger = Debug('sphereon:ssi-sdk:migrations')
+
+export class AddBrandingState1766000000000 implements MigrationInterface {
+  name = 'AddBrandingState1766000000000'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    debug('migration: adding branding state checksum columns')
+    const dbType: DatabaseType = queryRunner.connection.driver.options.type
+    switch (dbType) {
+      case 'postgres': {
+        debug('using postgres migration file')
+        const mig: AddBrandingStatePostgres1766000000000 = new AddBrandingStatePostgres1766000000000()
+        await mig.up(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      case 'sqlite':
+      case 'expo':
+      case 'react-native': {
+        debug('using sqlite/react-native migration file')
+        const mig: AddBrandingStateSqlite1766000000000 = new AddBrandingStateSqlite1766000000000()
+        await mig.up(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      default:
+        return Promise.reject(
+          `Migrations are currently only supported for sqlite, react-native, expo and postgres. Was ${dbType}. Please run your database without migrations and with 'migrationsRun: false' and 'synchronize: true' for now`,
+        )
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    debug('migration: removing branding state checksum columns')
+    const dbType: DatabaseType = queryRunner.connection.driver.options.type
+    switch (dbType) {
+      case 'postgres': {
+        debug('using postgres migration file')
+        const mig: AddBrandingStatePostgres1766000000000 = new AddBrandingStatePostgres1766000000000()
+        await mig.down(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      case 'sqlite':
+      case 'expo':
+      case 'react-native': {
+        debug('using sqlite/react-native migration file')
+        const mig: AddBrandingStateSqlite1766000000000 = new AddBrandingStateSqlite1766000000000()
+        await mig.down(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      default:
+        return Promise.reject(
+          `Migrations are currently only supported for sqlite, react-native, expo and postgres. Was ${dbType}. Please run your database without migrations and with 'migrationsRun: false' and 'synchronize: true' for now`,
+        )
+    }
+  }
+}

package/src/migrations/generic/index.ts

@@ -4,6 +4,7 @@ import { FixCredentialClaimsReferencesUuid1741895822987 } from './11-FixCredenti
 import { AddBitstringStatusListEnum1741895823000, CreateBitstringStatusList1741895823000 } from './12-CreateBitstringStatusList'
 import { CreateDcqlQueryItem1726617600000 } from './13-CreateDcqlQueryItem'
 import { AddLinkedVpFields1763387280000 } from './14-AddLinkedVpFields'
+import { AddBrandingState1766000000000 } from './15-AddBrandingState'
 import { CreateIssuanceBranding1659463079429 } from './2-CreateIssuanceBranding'
 import { CreateContacts1690925872318 } from './3-CreateContacts'
 import { CreateStatusList1693866470000 } from './4-CreateStatusList'
@@ -28,7 +29,11 @@ export const DataStoreContactMigrations = [
   CreateContacts1708525189000,
   CreateContacts1715761125000,
 ]
-export const DataStoreIssuanceBrandingMigrations = [CreateIssuanceBranding1659463079429, FixCredentialClaimsReferencesUuid1741895822987]
+export const DataStoreIssuanceBrandingMigrations = [
+  CreateIssuanceBranding1659463079429,
+  FixCredentialClaimsReferencesUuid1741895822987,
+  AddBrandingState1766000000000,
+]
 export const DataStoreStatusListMigrations = [
   CreateStatusList1693866470000,
   AddBitstringStatusListEnum1741895823000,

package/src/migrations/postgres/1766000000000-AddBrandingState.ts

@@ -0,0 +1,15 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class AddBrandingStatePostgres1766000000000 implements MigrationInterface {
+  name = 'AddBrandingState1766000000000'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "CredentialBranding" ADD "state" character varying(255) NOT NULL DEFAULT ''`)
+    await queryRunner.query(`ALTER TABLE "BaseLocaleBranding" ADD "state" character varying(255) NOT NULL DEFAULT ''`)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "BaseLocaleBranding" DROP COLUMN "state"`)
+    await queryRunner.query(`ALTER TABLE "CredentialBranding" DROP COLUMN "state"`)
+  }
+}

package/src/migrations/sqlite/1766000000000-AddBrandingState.ts

@@ -0,0 +1,87 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class AddBrandingStateSqlite1766000000000 implements MigrationInterface {
+  name = 'AddBrandingState1766000000000'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Add state column with empty string default for existing records
+    // Note: Existing records will have state='', which won't match computed hashes.
+    // This makes the knownStates optimization ineffective until records are naturally updated.
+    await queryRunner.query(`ALTER TABLE "CredentialBranding" ADD COLUMN "state" varchar(255) NOT NULL DEFAULT ''`)
+    await queryRunner.query(`ALTER TABLE "BaseLocaleBranding" ADD COLUMN "state" varchar(255) NOT NULL DEFAULT ''`)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Disable foreign key constraints during migration to avoid issues with DROP TABLE operations
+    await queryRunner.query(`PRAGMA foreign_keys = OFF`)
+
+    // Recreate CredentialBranding without the state column
+    await queryRunner.query(`
+            CREATE TABLE "CredentialBranding_old"
+            (
+                "id"                  varchar PRIMARY KEY NOT NULL,
+                "vcHash"              varchar(255)        NOT NULL,
+                "issuerCorrelationId" varchar(255)        NOT NULL,
+                "created_at"          datetime            NOT NULL DEFAULT (datetime('now')),
+                "last_updated_at"     datetime            NOT NULL DEFAULT (datetime('now'))
+            )
+        `)
+    await queryRunner.query(`
+            INSERT INTO "CredentialBranding_old" ("id", "vcHash", "issuerCorrelationId", "created_at", "last_updated_at")
+            SELECT "id", "vcHash", "issuerCorrelationId", "created_at", "last_updated_at"
+            FROM "CredentialBranding"
+        `)
+    await queryRunner.query(`DROP TABLE "CredentialBranding"`)
+    await queryRunner.query(`ALTER TABLE "CredentialBranding_old" RENAME TO "CredentialBranding"`)
+    await queryRunner.query(`CREATE INDEX "IDX_CredentialBrandingEntity_issuerCorrelationId" ON "CredentialBranding" ("issuerCorrelationId")`)
+    await queryRunner.query(`CREATE INDEX "IDX_CredentialBrandingEntity_vcHash" ON "CredentialBranding" ("vcHash")`)
+
+    // Recreate BaseLocaleBranding without the state column
+    await queryRunner.query(`
+            CREATE TABLE "BaseLocaleBranding_old"
+            (
+                "id"                  varchar PRIMARY KEY NOT NULL,
+                "alias"               varchar(255),
+                "locale"              varchar(255)        NOT NULL,
+                "description"         varchar(255),
+                "created_at"          datetime            NOT NULL DEFAULT (datetime('now')),
+                "last_updated_at"     datetime            NOT NULL DEFAULT (datetime('now')),
+                "credentialBrandingId" varchar,
+                "issuerBrandingId"    varchar,
+                "type"                varchar             NOT NULL,
+                "logoId"              varchar,
+                "backgroundId"        varchar,
+                "textId"              varchar,
+                "client_uri"          varchar,
+                "tos_uri"             varchar,
+                "policy_uri"          varchar,
+                "contacts"            varchar,
+                CONSTRAINT "UQ_logoId" UNIQUE ("logoId"),
+                CONSTRAINT "UQ_backgroundId" UNIQUE ("backgroundId"),
+                CONSTRAINT "UQ_textId" UNIQUE ("textId"),
+                CONSTRAINT "FK_BaseLocaleBranding_logoId" FOREIGN KEY ("logoId") REFERENCES "ImageAttributes" ("id") ON DELETE CASCADE ON UPDATE NO ACTION,
+                CONSTRAINT "FK_BaseLocaleBranding_backgroundId" FOREIGN KEY ("backgroundId") REFERENCES "BackgroundAttributes" ("id") ON DELETE CASCADE ON UPDATE NO ACTION,
+                CONSTRAINT "FK_BaseLocaleBranding_textId" FOREIGN KEY ("textId") REFERENCES "TextAttributes" ("id") ON DELETE CASCADE ON UPDATE NO ACTION,
+                CONSTRAINT "FK_BaseLocaleBranding_credentialBrandingId" FOREIGN KEY ("credentialBrandingId") REFERENCES "CredentialBranding" ("id") ON DELETE CASCADE ON UPDATE NO ACTION,
+                CONSTRAINT "FK_BaseLocaleBranding_issuerBrandingId" FOREIGN KEY ("issuerBrandingId") REFERENCES "IssuerBranding" ("id") ON DELETE CASCADE ON UPDATE NO ACTION
+            )
+        `)
+    await queryRunner.query(`
+            INSERT INTO "BaseLocaleBranding_old" ("id", "alias", "locale", "description", "created_at", "last_updated_at", "credentialBrandingId", "issuerBrandingId", "type", "logoId", "backgroundId", "textId", "client_uri", "tos_uri", "policy_uri", "contacts")
+            SELECT "id", "alias", "locale", "description", "created_at", "last_updated_at", "credentialBrandingId", "issuerBrandingId", "type", "logoId", "backgroundId", "textId", "client_uri", "tos_uri", "policy_uri", "contacts"
+            FROM "BaseLocaleBranding"
+        `)
+    await queryRunner.query(`DROP TABLE "BaseLocaleBranding"`)
+    await queryRunner.query(`ALTER TABLE "BaseLocaleBranding_old" RENAME TO "BaseLocaleBranding"`)
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX "IDX_CredentialLocaleBrandingEntity_credentialBranding_locale" ON "BaseLocaleBranding" ("credentialBrandingId", "locale")`,
+    )
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX "IDX_IssuerLocaleBrandingEntity_issuerBranding_locale" ON "BaseLocaleBranding" ("issuerBrandingId", "locale")`,
+    )
+    await queryRunner.query(`CREATE INDEX "IDX_BaseLocaleBranding_type" ON "BaseLocaleBranding" ("type")`)
+
+    // Re-enable foreign key constraints
+    await queryRunner.query(`PRAGMA foreign_keys = ON`)
+  }
+}

package/src/utils/issuanceBranding/HashUtils.ts

@@ -0,0 +1,30 @@
+/**
+ * Computes a compact hash suitable for change detection in branding data.
+ * Uses FNV-1a 64-bit hash algorithm with base36 encoding for a compact representation.
+ *
+ * Output format: ~11 characters (base36 encoded 64-bit hash)
+ * Example: "3qvf8n2kl9x"
+ *
+ * This is significantly smaller than SHA256+base64 (44 chars) while maintaining
+ * sufficient collision resistance for this use case.
+ *
+ * @param input - The string to hash
+ * @returns A compact hash string (~11 characters)
+ */
+
+// FNV-1a 64-bit hash constants
+const FNV_PRIME = 0x100000001b3n
+const OFFSET_BASIS = 0xcbf29ce484222325n
+
+export function computeCompactHash(input: string): string {
+  let hash = OFFSET_BASIS
+
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i))
+    hash = (hash * FNV_PRIME) & 0xffffffffffffffffn // Keep it 64-bit
+  }
+
+  // Convert to base36 for compact representation
+  // Base36 uses 0-9 and a-z, URL-safe and case-insensitive friendly
+  return hash.toString(36)
+}

package/src/utils/issuanceBranding/MappingUtils.ts

@@ -9,6 +9,7 @@ import type {
   IBasicIssuerLocaleBranding,
   IBasicTextAttributes,
   ICredentialBranding,
+  ICredentialLocaleBranding,
   IIssuerBranding,
   ILocaleBranding,
 } from '@sphereon/ssi-sdk.data-store-types'
@@ -28,7 +29,9 @@ import { replaceNullWithUndefined } from '../FormattingUtils'
 export const credentialBrandingFrom = (credentialBranding: CredentialBrandingEntity): ICredentialBranding => {
   const result: ICredentialBranding = {
     ...credentialBranding,
-    localeBranding: credentialBranding.localeBranding.map((localeBranding: BaseLocaleBrandingEntity) => localeBrandingFrom(localeBranding)),
+    localeBranding: credentialBranding.localeBranding.map((localeBranding: CredentialLocaleBrandingEntity) =>
+      credentialLocaleBrandingFromEntity(localeBranding),
+    ),
   }
 
   return replaceNullWithUndefined(result)
@@ -52,6 +55,23 @@ export const localeBrandingFrom = (localeBranding: BaseLocaleBrandingEntity): IL
   return replaceNullWithUndefined(result)
 }
 
+export const credentialLocaleBrandingFromEntity = (localeBranding: CredentialLocaleBrandingEntity): ICredentialLocaleBranding => {
+  const base: ILocaleBranding = localeBrandingFrom(localeBranding)
+  const result: ICredentialLocaleBranding = {
+    ...(base as ILocaleBranding),
+    state: localeBranding.state,
+    claims: localeBranding.claims
+      ? localeBranding.claims.map((claim: CredentialClaimsEntity) => ({
+          id: claim.id,
+          key: claim.key,
+          name: claim.name,
+        }))
+      : undefined,
+  } as ICredentialLocaleBranding
+
+  return replaceNullWithUndefined(result) as ICredentialLocaleBranding
+}
+
 export const issuerLocaleBrandingEntityFrom = (args: IBasicIssuerLocaleBranding): IssuerLocaleBrandingEntity => {
   const issuerLocaleBrandingEntity: IssuerLocaleBrandingEntity = new IssuerLocaleBrandingEntity()
   issuerLocaleBrandingEntity.alias = isEmptyString(args.alias) ? undefined : args.alias