@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/config/environment.test.ts

@@ -83,18 +83,23 @@ describe('credential refresh configuration', () => {
         }
     );
 
-    it.each(['serverless.yml', 'serverless-local.yml'])(
-        'passes all refresh settings into functions in %s',
-        manifestName => {
-            const manifestPath = fileURLToPath(new URL(`../../${manifestName}`, import.meta.url));
-            const manifest = parse(readFileSync(manifestPath, 'utf8'));
-
-            expect(manifest.provider.environment).toMatchObject({
-                CREDENTIAL_REFRESH_ENABLED: '${env:CREDENTIAL_REFRESH_ENABLED, "false"}',
-                CREDENTIAL_REFRESH_DIGEST_SECRET: '${env:CREDENTIAL_REFRESH_DIGEST_SECRET, ""}',
-                CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS:
-                    '${env:CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS, "24"}',
-            });
+    it('resolves the deployed function environment through the shared provider file', () => {
+        const manifestPath = fileURLToPath(new URL('../../serverless.yml', import.meta.url));
+        const manifest = parse(readFileSync(manifestPath, 'utf8'));
+
+        expect(manifest.provider.environment).toBe(
+            '${file(./serverless.function-env.cjs):provider}'
+        );
+    });
+
+    it.each(['config.dev.json', 'config.production.json'])(
+        'delivers non-secret refresh settings through checked-in stage config in %s',
+        stageFile => {
+            const configPath = fileURLToPath(new URL(`../../config/${stageFile}`, import.meta.url));
+            const config = JSON.parse(readFileSync(configPath, 'utf8'));
+
+            expect(config.CREDENTIAL_REFRESH_ENABLED).toBeDefined();
+            expect(config.CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS).toBeDefined();
         }
     );
 });

package/src/config/environment.ts

@@ -27,6 +27,7 @@ export const brainServiceEnvironmentShape = {
     CLIENT_APP_DOMAIN_NAME: optionalEnvironmentString,
     CLIENT_APP_PORT: optionalEnvironmentPort,
     LOGIN_PROVIDER_DID: optionalEnvironmentString,
+    SIGNING_AUTHORITY_ENDPOINT: optionalEnvironmentUrl,
     APP_STORE_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_SEED_OWNER_PROFILE_ID: optionalEnvironmentString,
@@ -77,6 +78,7 @@ export const brainServiceEnvironmentShape = {
     SKILL_SEMANTIC_SEARCH_RATE_LIMIT_PER_MIN: optionalEnvironmentPort,
     BITSTRING_STATUS_LIST_SIZE: optionalEnvironmentPort,
     CREDENTIAL_REFRESH_DIGEST_SECRET: optionalEnvironmentString,
+    SHARE_LINK_REQUEST_HASH_SECRET: optionalEnvironmentString,
     CREDENTIAL_REFRESH_ENABLED: optionalEnvironmentBoolean.default(false),
     CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS: credentialRefreshNotificationWindowHours,
     IS_OFFLINE: optionalEnvironmentBoolean.default(false),
@@ -211,6 +213,19 @@ export const getCredentialRefreshRuntimeEnvironment = (): CredentialRefreshRunti
         examplePath: 'services/learn-card-network/brain-service/.env.example',
     });
 
+const shareLinkRequestHashRuntimeEnvironmentSchema = z.object({
+    NODE_ENV: brainServiceEnvironmentShape.NODE_ENV,
+    SHARE_LINK_REQUEST_HASH_SECRET: brainServiceEnvironmentShape.SHARE_LINK_REQUEST_HASH_SECRET,
+});
+
+/** Reads the dedicated fingerprint secret at call time for enabled share-link APIs. */
+export const getShareLinkRequestHashRuntimeEnvironment = () =>
+    parseEnvironment(shareLinkRequestHashRuntimeEnvironmentSchema, process.env, {
+        project: 'brain-service share links',
+        source: 'process environment',
+        examplePath: 'services/learn-card-network/brain-service/.env.example',
+    });
+
 const inboxBatchRuntimeEnvironmentSchema = z.object({
     INBOX_QUEUE_URL: brainServiceEnvironmentShape.INBOX_QUEUE_URL,
     INBOX_DEAD_LETTER_QUEUE_URL: brainServiceEnvironmentShape.INBOX_DEAD_LETTER_QUEUE_URL,

package/src/config/serverlessFunctionEnv.test.ts

@@ -0,0 +1,105 @@
+import { createRequire } from 'node:module';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const require = createRequire(import.meta.url);
+const functions: {
+    provider: (input?: {
+        options?: Record<string, unknown>;
+        env?: NodeJS.ProcessEnv;
+    }) => Record<string, unknown>;
+} = require('../../serverless.function-env.cjs');
+
+const INFRA_KEYS = {
+    LAMBDA_STAGE: 'dev',
+    PORT: '3000',
+    REDIS_HOST: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'] },
+    REDIS_PORT: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'] },
+    NOTIFICATIONS_QUEUE_URL: '${construct:notifications-queue.queueUrl}',
+    INBOX_QUEUE_URL: '${construct:inbox-queue.queueUrl}',
+};
+
+beforeEach(() => {
+    vi.stubEnv('RUNTIME_SECRETS_ID', '');
+    vi.stubEnv('GIT_SHA', '');
+    vi.stubEnv('SEED', 'seed');
+    vi.stubEnv('NEO4J_PASSWORD', 'neo4j-password');
+    vi.stubEnv('SHARE_LINK_REQUEST_HASH_SECRET', 'hash-secret');
+    vi.stubEnv('SENTRY_AUTH_TOKEN', 'build-token');
+    vi.stubEnv('TRUSTED_ISSUERS_WHITELIST', 'did:web:issuer');
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe('brain-service serverless provider environment', () => {
+    it('always emits Redis and queue infrastructure as unresolved references', () => {
+        expect(functions.provider({ options: { stage: 'dev' } })).toMatchObject(INFRA_KEYS);
+    });
+
+    it('derives LAMBDA_STAGE and PORT from the CLI options, never a stage passthrough', () => {
+        const result = functions.provider({ options: { stage: 'production', httpPort: 4000 } });
+        expect(result.LAMBDA_STAGE).toBe('production');
+        expect(result.PORT).toBe('4000');
+    });
+
+    it('defaults LAMBDA_STAGE and PORT when no CLI options are supplied', () => {
+        const result = functions.provider();
+        expect(result.LAMBDA_STAGE).toBe('dev');
+        expect(result.PORT).toBe('3000');
+    });
+
+    it('emits GIT_SHA only when it is set to a non-empty value', () => {
+        expect(functions.provider()).not.toHaveProperty('GIT_SHA');
+        vi.stubEnv('GIT_SHA', 'deadbeef');
+        expect(functions.provider()).toMatchObject({ GIT_SHA: 'deadbeef' });
+    });
+
+    it('omits every fallback credential and the pointer stays set in bundle mode', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'brain-service/dev/runtime-secrets');
+        const result = functions.provider({ options: { stage: 'dev' } });
+        expect(result).toMatchObject({
+            ...INFRA_KEYS,
+            RUNTIME_SECRETS_ID: 'brain-service/dev/runtime-secrets',
+        });
+        expect(result).not.toHaveProperty('SEED');
+        expect(result).not.toHaveProperty('NEO4J_PASSWORD');
+        expect(result).not.toHaveProperty('SHARE_LINK_REQUEST_HASH_SECRET');
+    });
+
+    it('retains only the approved fallback credentials when no bundle is configured', () => {
+        const result = functions.provider();
+        expect(result.SEED).toBe('seed');
+        expect(result.NEO4J_PASSWORD).toBe('neo4j-password');
+        expect(result.SHARE_LINK_REQUEST_HASH_SECRET).toBe('hash-secret');
+        expect(result.RUNTIME_SECRETS_ID).toBeUndefined();
+    });
+
+    it('never forwards Sentry build credentials or non-secret allowlists as fallbacks', () => {
+        const result = functions.provider();
+        expect(result).not.toHaveProperty('SENTRY_AUTH_TOKEN');
+        expect(result).not.toHaveProperty('SENTRY_ORG');
+        expect(result).not.toHaveProperty('SENTRY_PROJECT');
+        expect(result).not.toHaveProperty('TRUSTED_ISSUERS_WHITELIST');
+        expect(result).not.toHaveProperty('TRUSTED_BRAIN_SERVICES');
+        expect(result).not.toHaveProperty('BRAIN_SERVICE_REGISTRY_URL');
+        expect(result).not.toHaveProperty('DCC_KNOWN_REGISTRIES_URL');
+    });
+
+    it('resolves the provider through Serverless v3, preserving nested references in both modes', async () => {
+        const source = require('serverless/lib/configuration/variables/sources/file');
+        for (const bundle of ['', 'bundle']) {
+            vi.stubEnv('RUNTIME_SECRETS_ID', bundle);
+            const result = await source.resolve({
+                serviceDir: new URL('../../', import.meta.url).pathname,
+                params: [new URL('../../serverless.function-env.cjs', import.meta.url).pathname],
+                address: 'provider',
+                options: { stage: 'dev' },
+                resolveConfigurationProperty: vi.fn(),
+                resolveVariable: vi.fn(),
+            });
+            expect(result.value).toEqual(functions.provider({ options: { stage: 'dev' } }));
+            expect(result.value.NOTIFICATIONS_QUEUE_URL).toBe(
+                '${construct:notifications-queue.queueUrl}'
+            );
+            expect(result.value.INBOX_QUEUE_URL).toBe('${construct:inbox-queue.queueUrl}');
+        }
+    });
+});

package/src/config/stageConfig.test.ts

@@ -0,0 +1,25 @@
+import { afterEach, expect, it, vi } from 'vitest';
+
+vi.mock('dotenv/config', () => {
+    vi.stubEnv('SENTRY_ENV', 'self-hosted');
+    return {};
+});
+
+afterEach(() => vi.unstubAllEnvs());
+
+it('loads local env before applying statically imported stage defaults', async () => {
+    const { applyBrainServiceStageConfig, stages } = await import('./stageConfig');
+    for (const key of Object.keys(stages.dev)) {
+        if (key !== 'SENTRY_ENV') vi.stubEnv(key, '');
+    }
+    applyBrainServiceStageConfig('dev');
+    expect(process.env.SENTRY_ENV).toBe('self-hosted');
+    expect(process.env.DOMAIN_NAME).toBe(stages.dev.DOMAIN_NAME);
+});
+
+it('does not select a deployed stage for an unknown local stage', async () => {
+    const { applyBrainServiceStageConfig } = await import('./stageConfig');
+    vi.stubEnv('DOMAIN_NAME', '');
+    applyBrainServiceStageConfig('unregistered-self-hosted-stage');
+    expect(process.env.DOMAIN_NAME).toBe('');
+});

package/src/config/stageConfig.ts

@@ -0,0 +1,24 @@
+import 'dotenv/config';
+import { applyStageConfig } from '@learncard/service-config';
+
+import baseConfig from '../../config/config.json';
+import devConfig from '../../config/config.dev.json';
+import productionConfig from '../../config/config.production.json';
+import scoutsDevConfig from '../../config/config.scouts.dev.json';
+import scoutsProductionConfig from '../../config/config.scouts.production.json';
+
+export const base: Record<string, string> = baseConfig;
+
+export const stages = {
+    dev: devConfig,
+    production: productionConfig,
+    // ScoutPass deploys the same services and stage names; CONFIG_TENANT=scouts selects these.
+    'scouts.dev': scoutsDevConfig,
+    'scouts.production': scoutsProductionConfig,
+} satisfies Record<string, Record<string, string>>;
+
+// Must run before any module that reads configuration on import (e.g. @environment):
+// merges base + the selected stage into process.env; explicit non-empty env still wins.
+export const applyBrainServiceStageConfig = (stage: string | undefined): void => {
+    applyStageConfig({ base, stages, stage });
+};

package/src/constants/auth-grant.ts

@@ -45,3 +45,8 @@ export const AUTH_GRANT_CREDENTIAL_MANAGEMENT_SCOPE = 'credential:* presentation
 export const AUTH_GRANT_CONTRACTS_SCOPE = 'contracts:*';
 export const AUTH_GRANT_DID_METADATA_SCOPE = 'didMetadata:*';
 export const AUTH_GRANT_AUTH_GRANTS_SCOPE = 'authGrants:*';
+
+// LC-2187 owner share-link APIs. Least privilege: owner metadata/recovery reads
+// use `shareLinks:read`; create/update/revoke/retry use `shareLinks:write`.
+export const AUTH_GRANT_SHARE_LINKS_READ_SCOPE = 'shareLinks:read';
+export const AUTH_GRANT_SHARE_LINKS_WRITE_SCOPE = 'shareLinks:write';

package/src/docker-entry.ts

@@ -1,3 +1,6 @@
+import './config/applyDockerStageConfig';
+
+import { dispatchContractEvents } from '@helpers/contract-events.helpers';
 import { configureInboxBatchBodyLimit } from '@helpers/inbox-batch-http.helpers';
 import { environment } from '@environment';
 import Fastify from 'fastify';
@@ -15,6 +18,8 @@ import {
 
 import { neogma } from '@instance';
 import { appRouter, type AppRouter, createContext } from './app';
+import { publicShareLinkCacheControlHeaders } from './routes';
+import { registerPublicShareLinkNoStore } from './public-share-link-http';
 import { openApiDocument } from './openapi';
 import { inboxBatchResponseMeta } from './helpers/inbox-batch-http.helpers';
 import { didFastifyPlugin } from './dids';
@@ -23,10 +28,45 @@ import { statusListsFastifyPlugin } from './status-lists';
 import { credentialRefreshFastifyPlugin } from './credential-refresh';
 import { deliverQueuedNotification } from '@helpers/notificationQueue.helpers';
 import { startSkillEmbeddingBackfill } from '@helpers/skill-embedding.helpers';
+import {
+    createConsoleMaintenanceLogger,
+    createShareLinkMaintenanceRuntime,
+    createShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceScheduler,
+} from '@helpers/share-link-maintenance';
 import { maybeAutoSeedSkillFrameworks } from './seed/seedSkillFrameworks';
 
 const server = Fastify({ routerOptions: { maxParamLength: 5000 } });
 
+/**
+ * The scheduled maintenance runtime is created only after the server is ready.
+ * When its config is disabled/invalid it is inert, so no interval and no
+ * graph/remote/signing dependency is initialized at all.
+ */
+let shareLinkMaintenanceScheduler: ShareLinkMaintenanceScheduler | null = null;
+let contractEventTimer: ReturnType<typeof setTimeout> | null = null;
+let contractEventPass: Promise<unknown> | null = null;
+let contractEventsStopped = false;
+
+const runContractEventPass = (): void => {
+    if (contractEventsStopped) return;
+    contractEventPass = dispatchContractEvents()
+        .catch(() => {
+            console.warn('contract_events: recovery_pending');
+        })
+        .finally(() => {
+            contractEventPass = null;
+            if (!contractEventsStopped)
+                contractEventTimer = setTimeout(runContractEventPass, 60_000);
+        });
+};
+
+server.addHook('onClose', async () => {
+    contractEventsStopped = true;
+    if (contractEventTimer) clearTimeout(contractEventTimer);
+    await contractEventPass;
+    await shareLinkMaintenanceScheduler?.stop();
+});
 // Register before either OpenAPI or tRPC registers its wildcard route. The hook raises the
 // parser ceiling for those shared routes, then narrows it back to 4 MiB only for batch issuance.
 // Registering this later would leave the already-created adapter routes at Fastify's 1 MiB limit.
@@ -78,6 +118,9 @@ server.register(fastifyTRPCPlugin, {
         allowMethodOverride: true,
         router: appRouter,
         createContext,
+        responseMeta: ({ paths }) => ({
+            headers: publicShareLinkCacheControlHeaders(paths),
+        }),
         onError({ path, error }) {
             // report to error monitoring
             console.error(`Error in tRPC handler on path '${path}':`, error);
@@ -96,6 +139,13 @@ server.register(fastifyTRPCOpenApiPlugin, {
     },
 } satisfies CreateOpenApiFastifyPluginOptions<AppRouter>);
 
+/**
+ * LC-2187: the Fastify OpenAPI adapter has no `responseMeta` hook, so the
+ * no-store contract for the anonymous public share-link routes is applied at
+ * the adapter boundary itself. It never depends on a cache layer above.
+ */
+registerPublicShareLinkNoStore(server);
+
 server.get('/docs/openapi.json', () => openApiDocument);
 
 const SCALAR_HTML = `<!DOCTYPE html>
@@ -138,12 +188,43 @@ server.register(credentialRefreshFastifyPlugin);
         } catch (error) {
             console.error('Skill embedding backfill failed', error);
         }
+
+        contractEventTimer = setTimeout(runContractEventPass, 60_000);
+
+        // Explicit startup after readiness. Disabled/invalid config stays inert.
+        const maintenanceRuntime = createShareLinkMaintenanceRuntime();
+
+        if (maintenanceRuntime.resolution.status === 'enabled') {
+            shareLinkMaintenanceScheduler = createShareLinkMaintenanceScheduler({
+                runOnce: () => maintenanceRuntime.runOnce(),
+                intervalMs: maintenanceRuntime.resolution.config.intervalMs,
+                logger: createConsoleMaintenanceLogger(),
+            });
+            shareLinkMaintenanceScheduler.start();
+        }
     } catch (err) {
         console.error(err);
         process.exit(1);
     }
 })();
 
+const shutdown = async (signal: NodeJS.Signals): Promise<void> => {
+    console.log(`Received ${signal}; closing server and draining maintenance`);
+    try {
+        await server.close();
+    } catch (error) {
+        console.error('Server shutdown failed', error);
+    }
+    process.exit(0);
+};
+
+process.once('SIGTERM', () => {
+    void shutdown('SIGTERM');
+});
+process.once('SIGINT', () => {
+    void shutdown('SIGINT');
+});
+
 const pollUrl = environment.NOTIFICATIONS_QUEUE_POLL_URL;
 
 if (pollUrl) {

package/src/helpers/app-manifest.helpers.ts

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto';
+
+import { canonicalConsentScopeString, canonicalJsonString } from '@learncard/partner-connect-core';
+import type { NormalizedConsentScopes } from '@learncard/partner-connect-core';
+import type { AppManifest, AppManifestDiff, AppManifestTemplateRef } from '@learncard/types';
+
+const sortStrings = <T extends string>(values: T[]): T[] =>
+    Array.from(new Set(values)).sort() as T[];
+
+const normalizeTemplateRecord = (template: AppManifest['templates'][number]) => ({
+    alias: template.alias,
+    template: template.template,
+    version: template.version,
+});
+
+const normalizeConsentRecord = (
+    record: AppManifest['consentRequests'][number]
+): { scopes: NormalizedConsentScopes; reason?: string } => ({
+    scopes: {
+        read: {
+            credentialCategories: sortStrings(record.scopes.read.credentialCategories),
+            personalFields: sortStrings(record.scopes.read.personalFields),
+        },
+        write: {
+            credentialCategories: sortStrings(record.scopes.write.credentialCategories),
+        },
+    },
+    ...(record.reason ? { reason: record.reason } : {}),
+});
+
+const normalizeManifestForHash = (manifest: AppManifest): Record<string, unknown> => ({
+    manifestVersion: manifest.manifestVersion,
+    appUrl: manifest.appUrl,
+    ...(manifest.suggestedName ? { suggestedName: manifest.suggestedName } : {}),
+    ...(manifest.suggestedIconUrl ? { suggestedIconUrl: manifest.suggestedIconUrl } : {}),
+    permissions: sortStrings(manifest.permissions),
+    templates: [...manifest.templates]
+        .map(normalizeTemplateRecord)
+        .sort((a, b) => a.alias.localeCompare(b.alias) || a.version - b.version),
+    consentRequests: [...manifest.consentRequests]
+        .map(normalizeConsentRecord)
+        .sort((a, b) =>
+            canonicalConsentScopeString(a.scopes).localeCompare(
+                canonicalConsentScopeString(b.scopes)
+            )
+        ),
+    featuresLaunched: sortStrings(manifest.featuresLaunched),
+    counterKeys: sortStrings(manifest.counterKeys),
+    usedLearnerContext: manifest.usedLearnerContext,
+    usedNotifications: manifest.usedNotifications,
+});
+
+const buildStringDiff = (current: string[], next: string[]) => {
+    const currentSet = new Set(current);
+    const nextSet = new Set(next);
+
+    return {
+        added: sortStrings(next.filter(value => !currentSet.has(value))),
+        removed: sortStrings(current.filter(value => !nextSet.has(value))),
+        changed: [] as string[],
+    };
+};
+
+const templateSignature = (template: AppManifest['templates'][number]): string => {
+    return canonicalJsonString({ template: template.template, version: template.version });
+};
+
+const toTemplateRef = (template: AppManifest['templates'][number]): AppManifestTemplateRef => ({
+    alias: template.alias,
+    version: template.version,
+});
+
+const getConsentExpansionSurface = (
+    manifest: AppManifest
+): {
+    readCredentialCategories: Set<string>;
+    readPersonalFields: Set<string>;
+    writeCredentialCategories: Set<string>;
+} => {
+    const readCredentialCategories = new Set<string>();
+    const readPersonalFields = new Set<string>();
+    const writeCredentialCategories = new Set<string>();
+
+    for (const request of manifest.consentRequests) {
+        request.scopes.read.credentialCategories.forEach(category =>
+            readCredentialCategories.add(category)
+        );
+        request.scopes.read.personalFields.forEach(field => readPersonalFields.add(field));
+        request.scopes.write.credentialCategories.forEach(category =>
+            writeCredentialCategories.add(category)
+        );
+    }
+
+    return {
+        readCredentialCategories,
+        readPersonalFields,
+        writeCredentialCategories,
+    };
+};
+
+const isConsentExpanded = (current: AppManifest, next: AppManifest): boolean => {
+    const currentSurface = getConsentExpansionSurface(current);
+    const nextSurface = getConsentExpansionSurface(next);
+
+    return (
+        [...nextSurface.readCredentialCategories].some(
+            category => !currentSurface.readCredentialCategories.has(category)
+        ) ||
+        [...nextSurface.readPersonalFields].some(
+            field => !currentSurface.readPersonalFields.has(field)
+        ) ||
+        [...nextSurface.writeCredentialCategories].some(
+            category => !currentSurface.writeCredentialCategories.has(category)
+        )
+    );
+};
+
+export const canonicalizeManifest = (manifest: AppManifest): string => {
+    return canonicalJsonString(normalizeManifestForHash(manifest));
+};
+
+export const hashManifest = (manifest: AppManifest): string => {
+    return createHash('sha256').update(canonicalizeManifest(manifest)).digest('hex');
+};
+
+export const diffManifests = (current: AppManifest, next: AppManifest): AppManifestDiff => {
+    const currentTemplates = new Map(current.templates.map(template => [template.alias, template]));
+    const nextTemplates = new Map(next.templates.map(template => [template.alias, template]));
+
+    const addedTemplates: AppManifestTemplateRef[] = [];
+    const removedTemplates: AppManifestTemplateRef[] = [];
+    const changedTemplates: AppManifestDiff['templates']['changed'] = [];
+
+    for (const [alias, template] of nextTemplates.entries()) {
+        const existing = currentTemplates.get(alias);
+
+        if (!existing) {
+            addedTemplates.push(toTemplateRef(template));
+            continue;
+        }
+
+        if (templateSignature(existing) !== templateSignature(template)) {
+            changedTemplates.push({
+                alias,
+                fromVersion: existing.version,
+                toVersion: template.version,
+            });
+        }
+    }
+
+    for (const [alias, template] of currentTemplates.entries()) {
+        if (!nextTemplates.has(alias)) {
+            removedTemplates.push(toTemplateRef(template));
+        }
+    }
+
+    const permissionDiff = buildStringDiff(current.permissions, next.permissions);
+    const consentScopeDiff = buildStringDiff(
+        current.consentRequests.map(record =>
+            canonicalConsentScopeString(normalizeConsentRecord(record).scopes)
+        ),
+        next.consentRequests.map(record =>
+            canonicalConsentScopeString(normalizeConsentRecord(record).scopes)
+        )
+    );
+
+    return {
+        permissions: permissionDiff,
+        templates: {
+            added: addedTemplates.sort(
+                (a, b) => a.alias.localeCompare(b.alias) || a.version - b.version
+            ),
+            removed: removedTemplates.sort(
+                (a, b) => a.alias.localeCompare(b.alias) || a.version - b.version
+            ),
+            changed: changedTemplates.sort(
+                (a, b) => a.alias.localeCompare(b.alias) || a.toVersion - b.toVersion
+            ),
+        },
+        consentScopes: consentScopeDiff,
+        featurePaths: buildStringDiff(current.featuresLaunched, next.featuresLaunched),
+        counterKeys: buildStringDiff(current.counterKeys, next.counterKeys),
+        requiresReview: permissionDiff.added.length > 0 || isConsentExpanded(current, next),
+    };
+};

package/src/helpers/boost.helpers.ts

@@ -22,6 +22,7 @@ import {
     parseRenderedTemplate,
     shouldAutoAppendTemplateEvidence,
 } from '@helpers/template.helpers';
+import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
 
 import { getBoostOwner } from '@accesslayer/boost/relationships/read';
 import { BoostInstance } from '@models';
@@ -95,15 +96,7 @@ export const convertCredentialToBoostTemplateJSON = (
     delete template.proof;
     template.issuer = defaultIssuerDid ?? 'did:example:123';
 
-    if (Array.isArray(template.credentialSubject)) {
-        template.credentialSubject = template.credentialSubject.map(subject => {
-            subject.id = 'did:example:123';
-
-            return subject;
-        });
-    } else {
-        template.credentialSubject.id = 'did:example:123';
-    }
+    setCredentialSubjectIds(template, 'did:example:123');
     return JSON.stringify(template);
 };
 
@@ -262,14 +255,7 @@ export const issueClaimLinkBoost = async (
 
     boostCredential.issuer = signingAuthorityForUser.relationship.did;
 
-    if (Array.isArray(boostCredential.credentialSubject)) {
-        boostCredential.credentialSubject = boostCredential.credentialSubject.map(subject => ({
-            ...subject,
-            id: getDidWeb(domain, to.profileId),
-        }));
-    } else {
-        boostCredential.credentialSubject.id = getDidWeb(domain, to.profileId);
-    }
+    setCredentialSubjectIds(boostCredential, getDidWeb(domain, to.profileId));
 
     // Embed the boostURI into the boost credential for verification purposes.
     if (boostCredential.type.includes('BoostCredential')) {
@@ -362,20 +348,7 @@ export const prepareCredentialFromBoost = async (
         credential.issuer = issuerDid;
     }
 
-    // Set recipient DID in credentialSubject if provided
-    if (recipientDid) {
-        if (Array.isArray(credential.credentialSubject)) {
-            credential.credentialSubject = credential.credentialSubject.map(subject => ({
-                ...subject,
-                id: recipientDid,
-            }));
-        } else {
-            credential.credentialSubject = {
-                ...(credential.credentialSubject || {}),
-                id: recipientDid,
-            };
-        }
-    }
+    if (recipientDid) setCredentialSubjectIds(credential, recipientDid);
 
     // Embed boostId for BoostCredential types
     if (credential?.type?.includes('BoostCredential')) {