@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/helpers/status-list.helpers.ts

@@ -1,6 +1,9 @@
-import { environment } from '@environment';
+import { environment, getCredentialRefreshRuntimeEnvironment } from '@environment';
 import { gzipSync, gunzipSync } from 'node:zlib';
+import { isDeepStrictEqual } from 'node:util';
+import type { Transaction } from 'neo4j-driver';
 import { v4 as uuid } from 'uuid';
+import { TRPCError } from '@trpc/server';
 import type {
     AllocatedBitstringStatusListEntry,
     BitstringStatusListEntry,
@@ -20,10 +23,17 @@ import {
 } from '@learncard/helpers';
 
 import { neogma } from '@instance';
-import { Credential } from '@models';
 import type { StatusListPurpose, StatusListType } from '@models';
 import { getDidWebLearnCard, getLearnCard } from '@helpers/learnCard.helpers';
 
+/** Resolve original deliveries and versions through anchored refresh lookups. */
+export const CREDENTIAL_STATUS_ROOT_QUERY = `MATCH (credential:Credential {id: $credentialId})
+    OPTIONAL MATCH (rootRefresh:CredentialRefresh)-[:ROOT]->(credential)
+    OPTIONAL MATCH (versionRefresh:CredentialRefresh {refreshId: credential.refreshId})
+    WITH credential, coalesce(rootRefresh, versionRefresh) AS refresh
+    OPTIONAL MATCH (refresh)-[:ROOT]->(managedRoot:Credential)
+    WITH credential, refresh, coalesce(managedRoot, credential) AS root`;
+
 const hasToNumber = (value: unknown): value is { toNumber: () => number } =>
     !!value &&
     typeof value === 'object' &&
@@ -35,6 +45,111 @@ const asNumber = (value: unknown): number => {
     return Number(value);
 };
 
+/** Reserve local coordinates for an ordinary delivery under the same locks as managed binding. */
+export const reserveCredentialStatusEntries = async (
+    entries: BitstringStatusListEntry[],
+    ownerProfileId: string,
+    credentialId: string,
+    transaction: Transaction,
+    options: { lenient?: boolean; credential?: VC | UnsignedVC } = {}
+): Promise<void> => {
+    const domain = getCredentialRefreshRuntimeEnvironment().DOMAIN_NAME || 'localhost%3A3000';
+    for (const entry of [...entries].sort((a, b) =>
+        a.statusListCredential.localeCompare(b.statusListCredential)
+    )) {
+        const result = await transaction.run(
+            `MATCH (list:BitstringStatusList {statusListCredential: $url})
+             SET list._statusBindingLock = true REMOVE list._statusBindingLock
+             WITH list
+             OPTIONAL MATCH (list)-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding {index: $index})
+             RETURN list, binding.refreshId AS refreshId, binding.credentialId AS credentialId`,
+            { url: entry.statusListCredential, index: String(entry.statusListIndex) }
+        );
+        const row = result.records[0];
+        const list = row ? nodeToStatusList(row.get('list')) : null;
+        if (!list) {
+            if (
+                entry.statusListCredential.startsWith(
+                    `${getStatusListBaseUrl(domain)}/status-lists/`
+                )
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Local status list does not exist',
+                });
+            }
+            continue; // External status lists are not managed by this network.
+        }
+        // Forwarding does not confer authority over another issuer's local list.
+        if (options.lenient && list.ownerProfileId !== ownerProfileId) continue;
+        const index = Number(entry.statusListIndex);
+        if (
+            entry.statusListCredential !== getStatusListCredentialUrl(list.id, domain) ||
+            list.ownerProfileId !== ownerProfileId ||
+            list.statusPurpose !== entry.statusPurpose ||
+            !Number.isSafeInteger(index) ||
+            index < 0 ||
+            index >= list.size ||
+            index >= list.nextIndex ||
+            (typeof entry.statusListIndex === 'string' && String(index) !== entry.statusListIndex)
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Invalid local credential status coordinates',
+            });
+        }
+        if (
+            row?.get('refreshId') ||
+            (row?.get('credentialId') && row.get('credentialId') !== credentialId)
+        ) {
+            const boundId: unknown = row?.get('credentialId');
+            if (
+                options.lenient &&
+                !row?.get('refreshId') &&
+                typeof boundId === 'string' &&
+                options.credential?.proof &&
+                (!Array.isArray(options.credential.proof) || options.credential.proof.length > 0)
+            ) {
+                const existing = await transaction.run(
+                    'MATCH (credential:Credential {id: $id}) RETURN credential.credential AS body',
+                    { id: boundId }
+                );
+                const body: unknown = existing.records[0]?.get('body');
+                if (
+                    typeof body === 'string' &&
+                    isDeepStrictEqual(
+                        JSON.parse(body),
+                        JSON.parse(JSON.stringify(options.credential))
+                    )
+                ) {
+                    await transaction.run(
+                        `MATCH (:BitstringStatusList {statusListCredential: $url})-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding {index: $index})
+                         WITH binding, coalesce(binding.credentialIds, [binding.credentialId]) AS ids
+                         SET binding.credentialIds = CASE WHEN $credentialId IN ids THEN ids ELSE ids + $credentialId END`,
+                        {
+                            url: entry.statusListCredential,
+                            index: String(entry.statusListIndex),
+                            credentialId,
+                        }
+                    );
+                    continue; // Retain every delivery under the list lock, including legacy bindings.
+                }
+            }
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list index is already bound to another credential',
+            });
+        }
+        await transaction.run(
+            `MATCH (list:BitstringStatusList {statusListCredential: $url})
+             MERGE (list)-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding {index: $index})
+             SET binding.credentialId = $credentialId,
+                 binding.credentialIds = coalesce(binding.credentialIds, [$credentialId])`,
+            { url: entry.statusListCredential, index: String(entry.statusListIndex), credentialId }
+        );
+    }
+};
+
 const nodeToStatusList = (node: unknown): StatusListType | null => {
     const properties = (node as { properties?: Record<string, unknown> } | undefined)?.properties;
     if (!properties) return null;
@@ -338,15 +453,25 @@ export const appendBitstringStatusListEntries = async (
 
 export const setStatusListEntryBit = async (
     entry: BitstringStatusListEntry,
-    value: boolean
+    value: boolean,
+    ownerProfileId: string,
+    transaction?: Transaction
 ): Promise<boolean> => {
     const statusListIndex = Number(entry.statusListIndex);
 
-    if (!Number.isInteger(statusListIndex) || statusListIndex < 0) {
-        throw new Error('Bitstring status list index is out of range');
+    if (
+        !Number.isSafeInteger(statusListIndex) ||
+        statusListIndex < 0 ||
+        (typeof entry.statusListIndex === 'string' &&
+            String(statusListIndex) !== entry.statusListIndex)
+    ) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Bitstring status list index is out of range',
+        });
     }
 
-    return neogma.getTransaction(null, async tx => {
+    return neogma.getTransaction(transaction ?? null, async tx => {
         const record = (
             await tx.run(
                 `MATCH (list:BitstringStatusList {statusListCredential: $statusListCredential})
@@ -364,8 +489,43 @@ export const setStatusListEntryBit = async (
         const list = record ? nodeToStatusList(record.get('list')) : null;
         if (!list) return false;
 
-        if (statusListIndex >= list.size) {
-            throw new Error('Bitstring status list index is out of range');
+        const url = new URL(entry.statusListCredential);
+        if (
+            entry.statusListCredential !==
+                getStatusListCredentialUrl(
+                    list.id,
+                    getCredentialRefreshRuntimeEnvironment().DOMAIN_NAME || 'localhost%3A3000'
+                ) ||
+            url.pathname !== `/status-lists/${list.id}` ||
+            url.search ||
+            url.hash ||
+            url.username ||
+            url.password
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list URL must be canonical and local',
+            });
+        }
+
+        if (list.ownerProfileId !== ownerProfileId) {
+            throw new TRPCError({
+                code: 'FORBIDDEN',
+                message: 'Status list owner does not match the credential',
+            });
+        }
+        if (list.statusPurpose !== entry.statusPurpose) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list purpose does not match the credential',
+            });
+        }
+
+        if (statusListIndex >= list.size || statusListIndex >= list.nextIndex) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Bitstring status list index is out of range',
+            });
         }
 
         const bitstring = decodeBitstring(list.encodedList, list.size);
@@ -397,18 +557,9 @@ export const setCredentialBitstringStatus = async (
     statusPurpose: BitstringStatusPurpose,
     value: boolean
 ): Promise<boolean> => {
-    const credential = await Credential.findOne({ where: { id: credentialId } });
-    if (!credential) return false;
-
-    // Encrypted SA credentials retain only public status coordinates separately.
-    // Legacy plaintext/wrapped credentials continue using their embedded entries.
     let statusEntries: BitstringStatusListEntry[];
     try {
-        statusEntries = BitstringStatusListEntryValidator.array().parse(
-            credential.statusEntries
-                ? JSON.parse(credential.statusEntries)
-                : getBitstringStatusListEntries(JSON.parse(credential.credential))
-        );
+        statusEntries = await getStatusEntriesForCredential(credentialId);
         if (
             statusEntries.some(
                 entry =>
@@ -424,14 +575,172 @@ export const setCredentialBitstringStatus = async (
         });
         return false;
     }
-    const entries = statusEntries.filter(entry => entry.statusPurpose === statusPurpose);
+    if (statusEntries.length === 0) return false;
 
+    const owner = (
+        await neogma.queryRunner.run(
+            `${CREDENTIAL_STATUS_ROOT_QUERY}
+         OPTIONAL MATCH (issuer:Profile)-[:CREDENTIAL_SENT]->(root)
+         RETURN coalesce(refresh.issuerProfileId, root.statusOwnerProfileId, issuer.profileId) AS owner LIMIT 1`,
+            { credentialId }
+        )
+    ).records[0]?.get('owner');
+    if (typeof owner !== 'string') return false;
+    const entries = statusEntries.filter(entry => entry.statusPurpose === statusPurpose);
     if (entries.length === 0) return false;
 
-    const updated = await Promise.all(entries.map(entry => setStatusListEntryBit(entry, value)));
+    const updated = await Promise.all(
+        entries.map(entry => setStatusListEntryBit(entry, value, owner))
+    );
     return updated.every(Boolean);
 };
 
+/** Public coordinates are shared by every immutable version of a managed credential. */
+export const getStatusEntriesForCredential = async (
+    credentialId: string,
+    transaction?: Transaction
+): Promise<BitstringStatusListEntry[]> => {
+    const query = `${CREDENTIAL_STATUS_ROOT_QUERY}
+         RETURN credential.statusEntries AS direct, credential.credential AS body,
+                refresh.statusEntries AS entries LIMIT 1`;
+    const result = transaction
+        ? await transaction.run(query, { credentialId })
+        : await neogma.queryRunner.run(query, { credentialId });
+    const row = result.records[0];
+    if (!row) return [];
+    const direct: unknown = row.get('direct');
+    const body: unknown = row.get('body');
+    const directEntries = BitstringStatusListEntryValidator.array().parse(
+        typeof direct === 'string'
+            ? JSON.parse(direct)
+            : typeof body === 'string'
+              ? getBitstringStatusListEntries(JSON.parse(body))
+              : []
+    );
+    if (directEntries.length > 0) return directEntries;
+    const entries: unknown = row.get('entries');
+    return typeof entries === 'string'
+        ? BitstringStatusListEntryValidator.array().parse(JSON.parse(entries))
+        : [];
+};
+
+/** Resolve lifecycle requests for any immutable version to its original delivery. */
+export const getCredentialStatusRootId = async (credentialId: string): Promise<string> => {
+    const result = await neogma.queryRunner.run(
+        `${CREDENTIAL_STATUS_ROOT_QUERY}
+         RETURN root.id AS id LIMIT 1`,
+        { credentialId }
+    );
+    return String(result.records[0]?.get('id') ?? credentialId);
+};
+
+/** Own-host URLs must pass local validation, even with a wrong path, port or scheme. */
+export const isNetworkStatusEntry = (
+    entry: BitstringStatusListEntry,
+    domain = getCredentialRefreshRuntimeEnvironment().DOMAIN_NAME || 'localhost%3A3000'
+): boolean => {
+    const base = getStatusListBaseUrl(domain);
+    let url: URL;
+    try {
+        url = new URL(entry.statusListCredential);
+    } catch (cause) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Invalid credential status URL',
+            cause,
+        });
+    }
+    return (
+        entry.statusListCredential.startsWith(`${base}/status-lists/`) ||
+        url.hostname === new URL(base).hostname
+    );
+};
+
+/** Issuer-facing information, separate from the signed refresh receipt. */
+export const getStatusManagement = (
+    entries: BitstringStatusListEntry[],
+    domain: string
+): 'network' | 'external' | 'mixed' | 'none' => {
+    if (!entries.length) return 'none';
+    const local = entries.filter(entry => isNetworkStatusEntry(entry, domain)).length;
+    return local === entries.length ? 'network' : local === 0 ? 'external' : 'mixed';
+};
+
+/** Validate external shapes and local, issuer-owned, allocated coordinates. */
+export const validateStatusEntries = async (
+    entries: BitstringStatusListEntry[],
+    ownerProfileId: string,
+    domain: string
+): Promise<void> => {
+    for (const entry of entries) {
+        if (!BitstringStatusListEntryValidator.safeParse(entry).success) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Invalid credential status entry',
+            });
+        }
+        if (!isNetworkStatusEntry(entry, domain)) {
+            const index = Number(entry.statusListIndex);
+            if (
+                new URL(entry.statusListCredential).protocol !== 'https:' ||
+                !Number.isSafeInteger(index) ||
+                index < 0 ||
+                (typeof entry.statusListIndex === 'string' && !/^\d+$/.test(entry.statusListIndex))
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Invalid external credential status entry',
+                });
+            }
+            continue;
+        }
+        const prefix = `${getStatusListBaseUrl(domain)}/status-lists/`;
+        const id = entry.statusListCredential.slice(prefix.length);
+        if (!entry.statusListCredential.startsWith(prefix)) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list URL must be canonical and local',
+            });
+        }
+        if (!/^[a-zA-Z0-9-]+$/.test(id)) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list URL must be canonical and local',
+            });
+        }
+        const list = await getStatusListById(id);
+        const index = Number(entry.statusListIndex);
+        if (
+            !list ||
+            list.statusListCredential !== entry.statusListCredential ||
+            list.statusPurpose !== entry.statusPurpose
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list URL or purpose does not match the credential',
+            });
+        }
+        if (list.ownerProfileId !== ownerProfileId) {
+            throw new TRPCError({
+                code: 'FORBIDDEN',
+                message: 'Status list owner does not match the credential',
+            });
+        }
+        if (
+            !Number.isSafeInteger(index) ||
+            index < 0 ||
+            index >= list.size ||
+            index >= list.nextIndex ||
+            (typeof entry.statusListIndex === 'string' && String(index) !== entry.statusListIndex)
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Status list index is out of range',
+            });
+        }
+    }
+};
+
 export const getSignedStatusListCredential = async (id: string): Promise<VC | null> => {
     const list = await getStatusListById(id);
     if (!list) return null;

package/src/models/ConsentFlowContract.ts

@@ -58,6 +58,9 @@ export const ConsentFlowContract = ModelFactory<FlatDbContractType, ConsentFlowR
             createdAt: { type: 'string', required: true },
             updatedAt: { type: 'string', required: true },
             expiresAt: { type: 'string', required: false },
+            currentVersion: { type: 'number', required: false },
+            status: { type: 'string', required: false },
+            latestUpdate: { type: 'string', required: false },
             audienceVersion: { type: 'number', required: false },
             hasConsented: { type: 'boolean', required: false },
         } as any,

package/src/models/ConsentFlowContractVersion.ts

@@ -0,0 +1,50 @@
+import { ModelFactory, NeogmaInstance } from 'neogma';
+import { neogma } from '@instance';
+import type { DbContractVersionType } from 'types/consentflowcontract';
+
+type StoredVersionProperties = Omit<
+    DbContractVersionType,
+    'contract' | 'autoboosts' | 'writers'
+> & {
+    contract: string;
+    autoboosts?: string;
+    writers?: string;
+};
+type ContractVersionRelationships = Record<string, never>;
+export type ConsentFlowContractVersionInstance = NeogmaInstance<
+    StoredVersionProperties,
+    ContractVersionRelationships
+>;
+
+export const ConsentFlowContractVersion = ModelFactory<
+    StoredVersionProperties,
+    ContractVersionRelationships
+>(
+    {
+        label: 'ConsentFlowContractVersion',
+        schema: {
+            id: { type: 'string', required: true },
+            version: { type: 'number', required: true },
+            createdAt: { type: 'string', required: true },
+            contract: { type: 'string', required: true },
+            name: { type: 'string', required: true },
+            subtitle: { type: 'string', required: false },
+            description: { type: 'string', required: false },
+            reasonForAccessing: { type: 'string', required: false },
+            image: { type: 'string', required: false },
+            needsGuardianConsent: { type: 'boolean', required: false },
+            redirectUrl: { type: 'string', required: false },
+            frontDoorBoostUri: { type: 'string', required: false },
+            expiresAt: { type: 'string', required: false },
+            autoboosts: { type: 'string', required: false },
+            writers: { type: 'string', required: false },
+            reason: { type: 'string', required: false },
+            kind: { type: 'string', required: false },
+        },
+        relationships: {},
+        primaryKeyField: 'id',
+    },
+    neogma
+);
+
+export default ConsentFlowContractVersion;

package/src/models/ConsentFlowTerms.ts

@@ -33,6 +33,10 @@ export const ConsentFlowTerms = ModelFactory<FlatDbTermsType, ConsentFlowTermsRe
             createdAt: { type: 'string', required: false },
             updatedAt: { type: 'string', required: false },
             mutationVersion: { type: 'number', required: false },
+            consentedVersion: { type: 'number', required: false },
+            lastReviewedVersion: { type: 'number', required: false },
+            reconsentDeadline: { type: 'string', required: false },
+            newOptionsUntil: { type: 'string', required: false },
             expiresAt: { type: 'string', required: false },
             oneTime: { type: 'boolean', required: false },
             deniedWriters: { type: 'string[]', required: false },

package/src/models/Credential.ts

@@ -34,6 +34,8 @@ export const Credential = ModelFactory<CredentialType, CredentialRelationships>(
             id: { type: 'string', required: true, uniqueItems: true },
             credential: { type: 'string', required: true },
             statusEntries: { type: 'string', required: false },
+            statusOwnerProfileId: { type: 'string', required: false },
+            statusReservationMode: { type: 'string', enum: ['strict', 'lenient'], required: false },
         },
         primaryKeyField: 'id',
     },

package/src/models/CredentialRefresh.ts

@@ -54,6 +54,7 @@ export const CredentialRefresh = ModelFactory<
             materialDigest: { type: 'string', required: false },
             rootMaterialDigest: { type: 'string', required: false },
             credentialStatusDigest: { type: 'string', required: false },
+            statusEntries: { type: 'string', required: false },
             credentialSubjectDigest: { type: 'string', required: false },
             boostId: { type: 'string', required: false },
             signingMode: {
@@ -63,6 +64,7 @@ export const CredentialRefresh = ModelFactory<
             },
             idempotencyKey: { type: 'string', required: false },
             updateSummary: { type: 'string', required: false },
+            updateReason: { type: 'string', required: false },
             lastPublishedAt: { type: 'string', required: false },
             notificationWindowKey: { type: 'string', required: false },
             lastNotificationId: { type: 'string', required: false },

package/src/models/Profile.ts

@@ -126,6 +126,8 @@ export const Profile: any = ModelFactory<FlatProfileType, ProfileRelationships>(
             notificationsWebhook: { type: 'string', required: false },
             highlightedCredentials: { type: 'array', items: { type: 'string' }, required: false },
             dob: { type: 'string', required: false },
+            announcementEmailOptOut: { type: 'boolean', required: false },
+            announcementPushOptOut: { type: 'boolean', required: false },
             country: { type: 'string', required: false },
             role: {
                 type: 'string',

package/src/models/campaign-constraints.ts

@@ -4,17 +4,22 @@ let readiness: Promise<void> | undefined;
 
 /** Await uniqueness before accepting creates, even during concurrent cold starts. */
 export const ensureCampaignConstraints = (): Promise<void> => {
-    readiness ??= neogma.queryRunner
-        .run(
-            'CREATE CONSTRAINT campaign_id_unique IF NOT EXISTS FOR (c:Campaign) REQUIRE c.id IS UNIQUE'
+    readiness ??= Promise.all(
+        [
+            'CREATE CONSTRAINT campaign_id_unique IF NOT EXISTS FOR (c:Campaign) REQUIRE c.id IS UNIQUE',
+            'CREATE CONSTRAINT campaign_unsubscribe_id_unique IF NOT EXISTS FOR (p:Profile) REQUIRE p.campaignUnsubscribeId IS UNIQUE',
+        ].map(query =>
+            neogma.queryRunner.run(query).catch((error: unknown) => {
+                if (
+                    (error as { code?: string })?.code !==
+                    'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists'
+                )
+                    throw error;
+            })
         )
+    )
         .then(() => undefined)
         .catch((error: unknown) => {
-            if (
-                (error as { code?: string })?.code ===
-                'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists'
-            )
-                return;
             readiness = undefined;
             throw error;
         });

package/src/models/index.ts

@@ -183,6 +183,7 @@ const indexQueries = [
     'CREATE INDEX contract_updated_idx IF NOT EXISTS FOR (c:ConsentFlowContract) ON (c.updatedAt)',
     'CREATE INDEX terms_updated_idx IF NOT EXISTS FOR (t:ConsentFlowTerms) ON (t.updatedAt)',
     'CREATE INDEX terms_status_idx IF NOT EXISTS FOR (t:ConsentFlowTerms) ON (t.status)',
+    'CREATE INDEX consent_autoboost_claim_identity_idx IF NOT EXISTS FOR (c:ConsentFlowAutoBoostClaim) ON (c.termsId, c.boostId)',
     'CREATE INDEX claim_hook_updated_idx IF NOT EXISTS FOR (c:ClaimHook) ON (c.updatedAt)',
     'CREATE INDEX integration_id_idx IF NOT EXISTS FOR (i:Integration) ON (i.id)',
     'CREATE INDEX integration_publishablekey_idx IF NOT EXISTS FOR (i:Integration) ON (i.publishableKey)',
@@ -306,6 +307,7 @@ export * from './DidMetadata';
 export * from './SigningAuthority';
 export * from './ConsentFlowTerms';
 export * from './ConsentFlowContract';
+export * from './ConsentFlowContractVersion';
 export * from './ConsentFlowTransaction';
 export * from './ContactMethod';
 export * from './InboxCredential';

package/src/openapi.ts

@@ -57,6 +57,7 @@ if (publishRequestBody && !('$ref' in publishRequestBody)) {
             refreshId: properties.refreshId,
             notifyHolder: properties.notifyHolder!,
             updateSummary: properties.updateSummary!,
+            updateReason: properties.updateReason!,
             idempotencyKey: properties.idempotencyKey!,
         };
         // Generator 7.25.0 loses the OpenAPI 3.1 closed-object flag. Keep the
@@ -96,6 +97,26 @@ if (publishRequestBody && !('$ref' in publishRequestBody)) {
     }
 }
 
+// Preserve the existing Python allocation identity contract without changing
+// None/default serialization for unrelated optional request fields.
+const allocationBody = openApiDocument.paths?.['/credential-refresh/allocate']?.post?.requestBody;
+const allocationSchema =
+    allocationBody && !('$ref' in allocationBody)
+        ? allocationBody.content?.['application/json']?.schema
+        : undefined;
+const allocationHolder =
+    allocationSchema && !('$ref' in allocationSchema)
+        ? allocationSchema.properties?.holder
+        : undefined;
+const allocationProfile =
+    allocationHolder && !('$ref' in allocationHolder)
+        ? allocationHolder.properties?.profileId
+        : undefined;
+if (!allocationProfile || '$ref' in allocationProfile) {
+    throw new Error('Managed refresh allocation schema is missing its holder profile input');
+}
+Object.assign(allocationProfile, { 'x-python-preserve-explicit-null': true });
+
 const SCALAR_HTML = `<!DOCTYPE html>
 <html lang="en">
 <head>

package/src/routes/app-store.ts

@@ -1721,11 +1721,12 @@ const handleRequestLearnerContextEvent = async (
 
         // Use the same live/expiry/category/guardian evaluation as data-provider reads.
         // An app's contract is not interchangeable with another app's or AI's grant.
-        const [consent] = await getConsentedDataBetweenProfiles(
+        const consentPage = await getConsentedDataBetweenProfiles(
             owner.profileId,
             profile.profileId,
             { query: { id: contractDetails.contract.id }, limit: 1, domain: ctx.domain }
         );
+        const consent = consentPage.records[0];
         if (
             !consent ||
             consent.status !== 'live' ||