@learncard/types 5.22.0 → 5.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/types",
-    "version": "5.22.0",
+    "version": "5.23.0",
     "description": "Shared types for learn card",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -25,6 +25,7 @@
     "scripts": {
         "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
         "typecheck": "tsc --noEmit -p tsconfig.json",
+        "test": "vitest run",
         "start": "aqu watch"
     },
     "author": "Learning Economy Foundation (www.learningeconomy.io)",

package/src/__tests__/unsupportedSignInOperation.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { UnsupportedSignInOperationError } from '../auth';
+
+describe('UnsupportedSignInOperationError', () => {
+    it('preserves the operation and provider for callers', () => {
+        const error = new UnsupportedSignInOperationError('sendPhoneOtp', 'keycloak');
+        expect(error).toBeInstanceOf(Error);
+        expect(error.name).toBe('UnsupportedSignInOperationError');
+        expect(error.operation).toBe('sendPhoneOtp');
+        expect(error.providerType).toBe('keycloak');
+        expect(error.message).toContain('sendPhoneOtp');
+    });
+});

package/src/auth.ts

@@ -32,6 +32,17 @@ export class AuthSessionError extends Error {
 // Auth Provider
 // ---------------------------------------------------------------------------
 
+/** An action that the selected sign-in provider does not support. */
+export class UnsupportedSignInOperationError extends Error {
+    constructor(
+        public readonly operation: string,
+        public readonly providerType: string
+    ) {
+        super(`${operation} is not supported by ${providerType}`);
+        this.name = 'UnsupportedSignInOperationError';
+    }
+}
+
 /**
  * Auth provider identifier. Known values: 'firebase', 'supertokens', 'keycloak', 'oidc'.
  * Use any string to support custom auth providers without modifying this type.
@@ -288,10 +299,21 @@ export const EscrowPinStatusValidator = z.object({
 });
 export type EscrowPinStatus = z.infer<typeof EscrowPinStatusValidator>;
 
+/**
+ * Reason a stored escrow blob no longer matches the server's active enclave:
+ * `mode-mismatch` — blob was sealed for `software`/`nitro` but the server now
+ * runs the other backend (e.g. the P6 software→Nitro migration, or a rollback);
+ * `key-rotated` — blob's `enclaveKeyId` no longer matches the active
+ * attestation's key (e.g. a PCR/measurement rotation).
+ */
+export type EscrowBlobStaleReason = 'mode-mismatch' | 'key-rotated';
+
 /** Enrollment details for PIN-aware strategies. Legacy strategies may still return a string. */
 export interface EscrowEnrollmentState {
-    state: 'enrolled' | 'not-enrolled' | 'opted-out' | 'disabled';
+    state: 'enrolled' | 'not-enrolled' | 'opted-out' | 'disabled' | 'stale';
     escrowPin?: EscrowPinStatus;
+    /** Present only when `state === 'stale'`. */
+    staleReason?: EscrowBlobStaleReason;
 }
 
 /**
@@ -309,6 +331,7 @@ export interface ServerKeyStatus {
     maskedRecoveryEmail?: string | null;
     escrowOptedOut?: boolean;
     escrowPin?: EscrowPinStatus;
+    escrowStale?: EscrowBlobStaleReason;
     sssActivationState?: SssActivationState | null;
 }
 

package/src/clr.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+    AssociationValidator,
+    ClrCredentialValidator,
+    ClrSubjectValidator,
+    UnsignedClrCredentialValidator,
+    type Association,
+} from './clr';
+
+const association = {
+    type: 'Association' as const,
+    associationType: 'isPartOf',
+    sourceId: 'https://example.org/achievements/course',
+    targetId: 'https://example.org/achievements/program',
+};
+
+const supportedTypeNames = [
+    'Association',
+    'https://purl.imsglobal.org/spec/vc/clr/vocab.html#Association',
+    'https://example.org/ExtendedAssociation',
+    'CustomAssociation',
+];
+
+const subject = {
+    id: 'did:example:learner',
+    type: ['ClrSubject'],
+    association: [association],
+};
+
+const unsignedClr = {
+    '@context': [
+        'https://www.w3.org/ns/credentials/v2',
+        'https://purl.imsglobal.org/spec/clr/v2p0/context.json',
+        'https://purl.imsglobal.org/spec/ob/v3p0/context.json',
+    ],
+    id: 'https://example.org/credentials/clr',
+    type: ['VerifiableCredential', 'ClrCredential'],
+    issuer: { id: 'did:example:issuer', type: ['Profile'], name: 'Example University' },
+    validFrom: '2026-01-01T00:00:00Z',
+    credentialSubject: subject,
+};
+
+const proof = {
+    type: 'DataIntegrityProof',
+    cryptosuite: 'eddsa-rdfc-2022',
+    created: '2026-01-01T00:00:00Z',
+    proofPurpose: 'assertionMethod',
+    verificationMethod: 'did:example:issuer#key',
+    proofValue: 'zExampleSignature',
+};
+
+describe('CLR Association.type', () => {
+    it('accepts the canonical scalar without changing it or extension fields', () => {
+        // CLR 2.0 $defs.Association.properties.type requires the scalar "Association".
+        // https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json
+        const input = { ...association, 'ext:description': 'Course belongs to program' };
+
+        expect(AssociationValidator.parse(input)).toEqual(input);
+    });
+
+    it.each(supportedTypeNames)(
+        'preserves scalar and singleton-array type values through full CLR parsing: %s',
+        typeName => {
+            for (const type of [typeName, [typeName]]) {
+                const input = { ...association, type };
+                const credential = {
+                    ...unsignedClr,
+                    credentialSubject: { ...subject, association: [input] },
+                };
+
+                // This SDK validator checks structure; the official CLR schema is stricter.
+                expect(AssociationValidator.parse(input)).toEqual(input);
+                expect(UnsignedClrCredentialValidator.parse(credential)).toEqual(credential);
+                expect(ClrCredentialValidator.parse({ ...credential, proof })).toEqual({
+                    ...credential,
+                    proof,
+                });
+            }
+        }
+    );
+
+    it.each(
+        [
+            ['Association'],
+            ['Association', 'https://example.org/ExtendedAssociation'],
+            ['https://example.org/LegacyAssociation'],
+            [''], // Existing arrays accept every string; preserve that contract.
+        ].map(type => ({ type }))
+    )('preserves supported legacy arrays: $type', ({ type }) => {
+        const input = { ...association, type };
+
+        expect(AssociationValidator.parse(input)).toEqual(input);
+    });
+
+    it.each(
+        [undefined, null, false, 42, '', {}, [], ['Association', 42], [['Association']]].map(
+            type => ({ type })
+        )
+    )('rejects invalid values: $type', ({ type }) => {
+        expect(AssociationValidator.safeParse({ ...association, type }).success).toBe(false);
+    });
+
+    it('exposes scalar and legacy array types to callers', () => {
+        expectTypeOf<Association['type']>().toEqualTypeOf<string | string[]>();
+    });
+});
+
+describe('CLR credentials with associations', () => {
+    it('parses a subject containing both canonical and legacy associations', () => {
+        const input = {
+            ...subject,
+            association: [association, { ...association, type: ['Association'] }],
+        };
+
+        expect(ClrSubjectValidator.parse(input)).toEqual(input);
+    });
+
+    it.each([false, true])('parses unsigned and signed CLR subject arrays: %s', subjectArray => {
+        const input = {
+            ...unsignedClr,
+            credentialSubject: subjectArray ? [subject] : subject,
+        };
+
+        expect(UnsignedClrCredentialValidator.parse(input)).toEqual(input);
+        expect(ClrCredentialValidator.parse({ ...input, proof })).toEqual({ ...input, proof });
+    });
+
+    it('preserves nested CLR content and validates its associations when parsed directly', () => {
+        const nested = {
+            ...unsignedClr,
+            id: 'https://example.org/credentials/nested-clr',
+            credentialSubject: {
+                ...subject,
+                association: [{ ...association, type: supportedTypeNames[1] }],
+            },
+            proof,
+        };
+        const input = {
+            ...unsignedClr,
+            credentialSubject: { ...subject, verifiableCredential: [nested] },
+            proof,
+        };
+
+        expect(ClrCredentialValidator.parse(input)).toEqual(input);
+        // Embedded verifiableCredential values are intentionally opaque in ClrSubjectValidator.
+        expect(ClrCredentialValidator.parse(nested)).toEqual(nested);
+    });
+
+    it.each([[], '', ['Association', null]].map(type => ({ type })))(
+        'rejects invalid associations through full CLR parsing: $type',
+        ({ type }) => {
+            const invalidSubject = { ...subject, association: [{ ...association, type }] };
+
+            for (const credentialSubject of [invalidSubject, [invalidSubject]]) {
+                const input = { ...unsignedClr, credentialSubject };
+
+                expect(UnsignedClrCredentialValidator.safeParse(input).success).toBe(false);
+                expect(ClrCredentialValidator.safeParse({ ...input, proof }).success).toBe(false);
+            }
+        }
+    );
+});

package/src/clr.ts

@@ -27,7 +27,8 @@ export type AssociationType = z.infer<typeof AssociationTypeValidator>;
 
 export const AssociationValidator = z
     .object({
-        type: z.string().array().nonempty(),
+        // Accept compacted scalars while retaining the existing permissive array contract.
+        type: z.string().min(1).or(z.string().array().nonempty()),
         associationType: AssociationTypeValidator,
         sourceId: z.string().optional(),
         targetId: z.string(),

package/src/lcn.ts

@@ -714,12 +714,14 @@ export const ConsentFlowContractDetailsValidator = z.object({
     expiresAt: z.string().optional(),
     autoBoosts: z.string().array().optional(),
     writers: z.array(LCNProfileValidator).optional(),
+    recipients: z.array(LCNPublicProfileValidator.extend({ did: z.string() })).optional(),
+    audienceVersion: z.number().int().nonnegative().optional(),
 });
 export type ConsentFlowContractDetails = z.infer<typeof ConsentFlowContractDetailsValidator>;
 export type ConsentFlowContractDetailsInput = z.input<typeof ConsentFlowContractDetailsValidator>;
 
 export const ConsentFlowContractRequestStatusValidator = z
-    .enum(['pending', 'accepted', 'denied'])
+    .enum(['pending', 'accepted', 'denied', 'cancelled'])
     .nullable();
 export type ConsentFlowContractRequestStatus = z.infer<
     typeof ConsentFlowContractRequestStatusValidator
@@ -730,7 +732,51 @@ export type ConsentFlowContractRequestReadStatus = z.infer<
     typeof ConsentFlowContractRequestReadStatusValidator
 >;
 
-export const ConsentFlowContractRequestForProfileValidator = z.object({
+/** Durable referral identity captured on consent history and correlated events. */
+export const ConsentFlowReferralValidator = z.object({
+    requestId: z.string(),
+    requestedBy: z.string(),
+    externalReferenceId: z.string().max(256).optional(),
+});
+export type ConsentFlowReferral = z.infer<typeof ConsentFlowReferralValidator>;
+
+export const ContractRequestFieldsValidator = ConsentFlowReferralValidator.partial().extend({
+    requestedAt: z.string().optional(),
+    message: z.string().max(500).optional(),
+});
+export type ContractRequestFields = z.infer<typeof ContractRequestFieldsValidator>;
+
+export const SendContractRequestValidator = z.object({
+    contractUri: z.string(),
+    targetProfileId: z.string(),
+    externalReferenceId: z.string().trim().min(1).max(256).optional(),
+    message: z.string().trim().max(500).optional(),
+});
+export type SendContractRequest = z.infer<typeof SendContractRequestValidator>;
+
+export const ConsentFlowWebhookMetadataValidator = z.object({
+    eventId: z.string(),
+    deliveryKey: z.string(),
+    event: z.enum([
+        'request_sent',
+        'request_accepted',
+        'request_denied',
+        'request_cancelled',
+        'consent_created',
+        'consent_updated',
+        'consent_withdrawn',
+        'credentials_synced',
+    ]),
+    contractUri: z.string(),
+    termsUri: z.string().optional(),
+    requestId: z.string().optional(),
+    requestedBy: z.string().optional(),
+    externalReferenceId: z.string().optional(),
+    recipientRole: z.enum(['owner', 'recipient', 'requester', 'target']),
+});
+export type ConsentFlowWebhookMetadata = z.infer<typeof ConsentFlowWebhookMetadataValidator>;
+
+export const ConsentFlowContractRequestForProfileValidator = ContractRequestFieldsValidator.extend({
     profile: LCNProfileValidator,
     status: ConsentFlowContractRequestStatusValidator,
     readStatus: ConsentFlowContractRequestReadStatusValidator.optional(),
@@ -803,6 +849,7 @@ export const PaginatedConsentFlowTermsValidator = PaginationResponseValidator.ex
             expiresAt: z.string().optional(),
             oneTime: z.boolean().optional(),
             terms: ConsentFlowTermsValidator,
+            referral: ConsentFlowReferralValidator.optional(),
             contract: ConsentFlowContractDetailsValidator,
             uri: z.string(),
             consenter: LCNProfileValidator,
@@ -962,6 +1009,7 @@ export const ConsentFlowTransactionValidator = z.object({
     oneTime: z.boolean().optional(),
     terms: ConsentFlowTermsValidator.optional(),
     guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),
+    referral: ConsentFlowReferralValidator.optional(),
     id: z.string(),
     action: ConsentFlowTransactionActionValidator,
     date: z.string(),
@@ -974,6 +1022,7 @@ export const HolderExportConsentRecordValidator = z.object({
     status: ConsentFlowTermsStatusValidator,
     contract: ConsentFlowContractDetailsValidator,
     terms: ConsentFlowTermsValidator,
+    referral: ConsentFlowReferralValidator.optional(),
     transactions: ConsentFlowTransactionValidator.array(),
 });
 export type HolderExportConsentRecord = z.infer<typeof HolderExportConsentRecordValidator>;
@@ -2188,7 +2237,7 @@ export const AppStoreListingSubmitterValidator = z.object({
 
 export type AppStoreListingSubmitter = z.infer<typeof AppStoreListingSubmitterValidator>;
 
-export const AppStoreListingValidator = z.object({
+const AppStoreListingFieldsValidator = z.object({
     listing_id: z.string(),
     slug: z.string().optional(),
     display_name: z.string(),
@@ -2215,12 +2264,35 @@ export const AppStoreListingValidator = z.object({
     contact_email: z.string().email().optional(),
 });
 
+export const PendingListingUpdateStatusValidator = z.enum(['DRAFT', 'PENDING_REVIEW']);
+export type PendingListingUpdateStatus = z.infer<typeof PendingListingUpdateStatusValidator>;
+
+/** Changes to a live app that only take effect once an admin approves them. */
+export const PendingListingUpdateValidator = z.object({
+    status: PendingListingUpdateStatusValidator,
+    submitted_at: z.string().optional(),
+    changes: AppStoreListingFieldsValidator.omit({
+        listing_id: true,
+        app_listing_status: true,
+        promotion_level: true,
+        submitted_at: true,
+        submitter: true,
+    }).partial(),
+    manifest_version: z.number().int().min(1).optional(),
+});
+export type PendingListingUpdate = z.infer<typeof PendingListingUpdateValidator>;
+
+export const AppStoreListingValidator = AppStoreListingFieldsValidator.extend({
+    pending_update: PendingListingUpdateValidator.optional(),
+});
+
 export type AppStoreListing = z.infer<typeof AppStoreListingValidator>;
 
 export const AppStoreListingCreateValidator = AppStoreListingValidator.omit({
     listing_id: true,
     app_listing_status: true,
     promotion_level: true,
+    pending_update: true,
 });
 
 export type AppStoreListingCreateType = z.infer<typeof AppStoreListingCreateValidator>;
@@ -2229,6 +2301,7 @@ export const AppStoreListingUpdateValidator = AppStoreListingValidator.partial()
     listing_id: true,
     app_listing_status: true,
     promotion_level: true,
+    pending_update: true,
 });
 
 export type AppStoreListingUpdateType = z.infer<typeof AppStoreListingUpdateValidator>;
@@ -2264,13 +2337,116 @@ export const AppBoostValidator = z.object({
 export type AppBoost = z.infer<typeof AppBoostValidator>;
 
 // App Event Types (discriminated union for type safety)
-export const SendCredentialEventValidator = z.object({
+export const InlineWalletCategoryValidator = z.enum([
+    'Achievement',
+    'Skill',
+    'ID',
+    'Learning History',
+    'Work History',
+    'Social Badges',
+    'Membership',
+    'Accomplishment',
+    'Experiences',
+    'Accommodation',
+    'Family',
+]);
+
+export const InlineAlignmentValidator = z
+    .object({
+        name: z.string(),
+        url: z.string(),
+        framework: z.string().optional(),
+        code: z.string().optional(),
+    })
+    .passthrough();
+
+export const InlineEvidenceValidator = z
+    .object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        narrative: z.string().optional(),
+    })
+    .passthrough();
+
+export const InlineWalletSkillTagValidator = z
+    .object({
+        frameworkId: z.string(),
+        id: z.string(),
+        proficiencyLevel: z.string().optional(),
+    })
+    .passthrough();
+
+export const SimpleInlineCredentialTemplateValidator = z
+    .object({
+        rawCredential: z.undefined().optional(),
+        name: z.string(),
+        description: z.string().optional(),
+        image: z.string().optional(),
+        issuerName: z.string().optional(),
+        achievementType: z.string().optional(),
+        category: InlineWalletCategoryValidator.optional(),
+        criteria: z
+            .object({
+                narrative: z.string().optional(),
+                url: z.string().optional(),
+            })
+            .passthrough()
+            .optional(),
+        alignments: z.array(InlineAlignmentValidator).optional(),
+        tags: z.array(z.string()).optional(),
+        activity: z
+            .object({
+                startDate: z.string().optional(),
+                endDate: z.string().optional(),
+            })
+            .passthrough()
+            .optional(),
+        credits: z
+            .object({
+                earned: z.union([z.number(), z.string()]).optional(),
+                available: z.union([z.number(), z.string()]).optional(),
+            })
+            .passthrough()
+            .optional(),
+        validUntil: z.string().optional(),
+        evidence: z.array(InlineEvidenceValidator).optional(),
+        walletSkills: z.array(InlineWalletSkillTagValidator).optional(),
+    })
+    .passthrough();
+
+export const RawInlineCredentialTemplateValidator = z
+    .object({
+        rawCredential: z.record(z.string(), z.unknown()),
+        category: InlineWalletCategoryValidator.optional(),
+        walletSkills: z.array(InlineWalletSkillTagValidator).optional(),
+    })
+    .passthrough();
+
+export const InlineCredentialTemplateValidator = z.union([
+    RawInlineCredentialTemplateValidator,
+    SimpleInlineCredentialTemplateValidator,
+]);
+
+export const LegacySendCredentialEventValidator = z.object({
     type: z.literal('send-credential'),
     templateAlias: z.string(),
     templateData: z.record(z.string(), z.unknown()).optional(),
     preventDuplicateClaim: z.boolean().optional(),
 });
 
+export const InlineSendCredentialEventValidator = z.object({
+    type: z.literal('send-credential'),
+    alias: z.string(),
+    template: InlineCredentialTemplateValidator,
+    templateData: z.record(z.string(), z.unknown()).optional(),
+    preventDuplicateClaim: z.boolean().optional(),
+});
+
+export const SendCredentialEventValidator = z.union([
+    LegacySendCredentialEventValidator,
+    InlineSendCredentialEventValidator,
+]);
+
 export type SendCredentialEvent = z.infer<typeof SendCredentialEventValidator>;
 
 export const CheckCredentialEventValidator = z
@@ -2425,8 +2601,168 @@ export const GetCountersEventValidator = z.object({
 
 export type GetCountersEvent = z.infer<typeof GetCountersEventValidator>;
 
+export const ConsentRequestWalletCategoryValidator = z.enum([
+    'Achievement',
+    'Skill',
+    'ID',
+    'Learning History',
+    'Work History',
+    'Social Badges',
+    'Membership',
+    'Accomplishment',
+    'Experiences',
+    'Accommodation',
+    'Family',
+]);
+
+export const ConsentRequestPersonalFieldValidator = z.enum([
+    'name',
+    'email',
+    'phone',
+    'birthDate',
+    'country',
+    'avatar',
+]);
+
+export const ConsentRequestValidator = z.object({
+    read: z
+        .object({
+            credentialCategories: z.array(ConsentRequestWalletCategoryValidator).optional(),
+            personalFields: z.array(ConsentRequestPersonalFieldValidator).optional(),
+        })
+        .optional(),
+    write: z
+        .object({
+            credentialCategories: z.array(ConsentRequestWalletCategoryValidator).optional(),
+        })
+        .optional(),
+    reason: z.string().optional(),
+});
+
+export type ConsentRequest = z.infer<typeof ConsentRequestValidator>;
+
+export const NormalizedConsentScopesValidator = z.object({
+    read: z.object({
+        credentialCategories: z.array(ConsentRequestWalletCategoryValidator).default([]),
+        personalFields: z.array(ConsentRequestPersonalFieldValidator).default([]),
+    }),
+    write: z.object({
+        credentialCategories: z.array(ConsentRequestWalletCategoryValidator).default([]),
+    }),
+});
+
+export type NormalizedConsentScopes = z.infer<typeof NormalizedConsentScopesValidator>;
+
+export const CapturedTemplateRecordValidator = z
+    .object({
+        alias: z.string(),
+        template: InlineCredentialTemplateValidator,
+        version: z.number().int().min(1),
+        lastUsedAt: z.string(),
+    })
+    .passthrough();
+
+export type CapturedTemplateRecord = z.infer<typeof CapturedTemplateRecordValidator>;
+
+export const CapturedConsentRecordValidator = z
+    .object({
+        scopes: NormalizedConsentScopesValidator,
+        reason: z.string().optional(),
+        lastUsedAt: z.string(),
+    })
+    .passthrough();
+
+export type CapturedConsentRecord = z.infer<typeof CapturedConsentRecordValidator>;
+
+export const AppManifestValidator = z
+    .object({
+        manifestVersion: z.literal(1),
+        appUrl: z.string(),
+        appKey: z.string().max(200).optional(),
+        suggestedName: z.string().optional(),
+        suggestedIconUrl: z.string().optional(),
+        permissions: z.array(z.string()).default([]),
+        templates: z.array(CapturedTemplateRecordValidator).default([]),
+        consentRequests: z.array(CapturedConsentRecordValidator).default([]),
+        usedConsentContract: z.boolean().optional(),
+        featuresLaunched: z.array(z.string()).default([]),
+        counterKeys: z.array(z.string()).default([]),
+        usedLearnerContext: z.boolean(),
+        usedNotifications: z.boolean(),
+        firstCapturedAt: z.string(),
+        lastUpdatedAt: z.string(),
+    })
+    .passthrough();
+
+export type AppManifest = z.infer<typeof AppManifestValidator>;
+
+export const AppManifestVersionStatusValidator = z.enum(['draft', 'active', 'superseded']);
+export type AppManifestVersionStatus = z.infer<typeof AppManifestVersionStatusValidator>;
+
+export const AppManifestVersionValidator = z.object({
+    id: z.string(),
+    version: z.number().int().min(1),
+    manifestHash: z.string(),
+    manifest: AppManifestValidator,
+    status: AppManifestVersionStatusValidator,
+    createdAt: z.string(),
+    activatedAt: z.string().optional(),
+});
+
+export type AppManifestVersion = z.infer<typeof AppManifestVersionValidator>;
+
+const AppManifestStringDiffValidator = z.object({
+    added: z.array(z.string()),
+    removed: z.array(z.string()),
+    changed: z.array(z.string()),
+});
+
+export const AppManifestTemplateRefValidator = z.object({
+    alias: z.string(),
+    version: z.number().int().min(1),
+});
+
+export type AppManifestTemplateRef = z.infer<typeof AppManifestTemplateRefValidator>;
+
+export const AppManifestTemplateChangeValidator = z.object({
+    alias: z.string(),
+    fromVersion: z.number().int().min(1),
+    toVersion: z.number().int().min(1),
+});
+
+export type AppManifestTemplateChange = z.infer<typeof AppManifestTemplateChangeValidator>;
+
+export const AppManifestDiffValidator = z.object({
+    permissions: AppManifestStringDiffValidator,
+    templates: z.object({
+        added: z.array(AppManifestTemplateRefValidator),
+        removed: z.array(AppManifestTemplateRefValidator),
+        changed: z.array(AppManifestTemplateChangeValidator),
+    }),
+    consentScopes: AppManifestStringDiffValidator,
+    featurePaths: AppManifestStringDiffValidator,
+    counterKeys: AppManifestStringDiffValidator,
+    requiresReview: z.boolean(),
+});
+
+export type AppManifestDiff = z.infer<typeof AppManifestDiffValidator>;
+
+export const UpsertConsentContractEventValidator = z.object({
+    type: z.literal('upsert-consent-contract'),
+    scopes: ConsentRequestValidator,
+});
+
+export type UpsertConsentContractEvent = z.infer<typeof UpsertConsentContractEventValidator>;
+
+export const UpsertConsentContractResponseValidator = z.object({
+    contractUri: z.string(),
+    created: z.boolean(),
+});
+
+export type UpsertConsentContractResponse = z.infer<typeof UpsertConsentContractResponseValidator>;
+
 // Add new event types here as the union grows
-export const AppEventValidator = z.discriminatedUnion('type', [
+export const AppEventValidator = z.union([
     SendCredentialEventValidator,
     CheckCredentialEventValidator,
     CheckIssuanceStatusEventValidator,
@@ -2437,6 +2773,7 @@ export const AppEventValidator = z.discriminatedUnion('type', [
     IncrementCounterEventValidator,
     GetCounterEventValidator,
     GetCountersEventValidator,
+    UpsertConsentContractEventValidator,
 ]);
 
 export type AppEvent = z.infer<typeof AppEventValidator>;