@learncard/network-brain-service 3.19.1 → 4.0.0

package/src/accesslayer/consentflowcontract/relationships/read.ts

@@ -1,3 +1,4 @@
+import { isServiceProfileExemptFromGuardianship } from '@helpers/profile.helpers';
 import { QueryBuilder, BindParam } from 'neogma';
 import mapValues from 'lodash/mapValues';
 import {
@@ -38,13 +39,15 @@ import { ConsentFlowGuardianApprovalValidator } from '@learncard/types';
 import { FlatBoostType } from 'types/boost';
 import { constructUri, getIdFromUri } from '@helpers/uri.helpers';
 import { flattenObject, inflateObject } from '@helpers/objects.helpers';
-import { convertDataQueryToNeo4jQuery, shouldIncludeCategory } from '@helpers/contract.helpers';
+import { shouldIncludeCategory } from '@helpers/contract.helpers';
 import { ProfileType } from 'types/profile';
 import { CredentialType } from 'types/credential';
 import { getBoostUri } from '@helpers/boost.helpers';
 import { getCredentialUri } from '@helpers/credential.helpers';
 import { getProfilesThatManageAProfile } from '@accesslayer/profile/relationships/read';
-import { getDidWeb } from '@helpers/did.helpers';
+import { getDidWeb, updateDidForProfile } from '@helpers/did.helpers';
+import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { sanitizeProfileForTier } from '@helpers/profile-privacy.helpers';
 
 export const isProfileConsentFlowContractAdmin = async (
     profile: ProfileType,
@@ -279,6 +282,7 @@ export const getConsentedContractsForProfile = async (
         owner: LCNProfile;
         terms: DbTermsType;
         autoBoosts: string[];
+        recipients: ProfileType[];
     }[]
 > => {
     let query = new QueryBuilder(
@@ -313,9 +317,19 @@ export const getConsentedContractsForProfile = async (
         owner: LCNProfile;
         terms: FlatDbTermsType;
         boost: any[];
+        recipients: { properties: ProfileType }[];
     }>(
         await query
-            .return('DISTINCT contract, owner, terms, COLLECT(boost) as boost')
+            .with('contract, owner, terms, COLLECT(boost) as boost')
+            .match({
+                optional: true,
+                related: [
+                    { identifier: 'contract' },
+                    ConsentFlowContract.getRelationshipByAlias('sharesDataWith'),
+                    { identifier: 'recipient', model: Profile },
+                ],
+            })
+            .return('contract, owner, terms, boost, COLLECT(DISTINCT recipient) as recipients')
             .orderBy('terms.updatedAt')
             .limit(limit)
             .run()
@@ -323,6 +337,7 @@ export const getConsentedContractsForProfile = async (
 
     return results.map(result => ({
         ...result,
+        recipients: result.recipients.map(recipient => recipient.properties),
         contract: inflateObject(result.contract),
         terms: inflateObject(result.terms),
         autoBoosts: result.boost.map(boost => getBoostUri(boost.properties.id, domain)),
@@ -412,11 +427,21 @@ export const getHolderExportMetadataForProfile = async (
                     createdAt: record.contract.createdAt,
                     updatedAt: record.contract.updatedAt,
                     uri: constructUri('contract', record.contract.id, domain),
-                    owner: record.owner,
+                    owner: updateDidForProfile(domain, record.owner),
                     ...(record.contract.expiresAt ? { expiresAt: record.contract.expiresAt } : {}),
                     autoBoosts: record.autoBoosts,
+                    // This is the audience at export time, not a historical consent snapshot.
+                    audienceVersion: Number(record.contract.audienceVersion ?? 0),
+                    recipients: record.recipients.map(recipient => {
+                        const publicProfile = updateDidForProfile(domain, recipient);
+                        return {
+                            ...sanitizeProfileForTier(publicProfile, 'unauthenticated'),
+                            did: publicProfile.did,
+                        };
+                    }),
                 },
                 terms: record.terms.terms,
+                ...(record.terms.referral ? { referral: record.terms.referral } : {}),
                 transactions,
             });
         }
@@ -442,103 +467,135 @@ export const getHolderExportMetadataForProfile = async (
     };
 };
 
-export const getConsentedDataForProfile = async (
-    profileId: string,
-    { query = {}, limit, cursor }: { query?: ConsentFlowDataQuery; limit: number; cursor?: string }
-): Promise<ConsentFlowContractData[]> => {
-    const _dbQuery = new QueryBuilder(
-        new BindParam({
-            params: flattenObject({ terms: convertDataQueryToNeo4jQuery(query) }),
-            cursor,
-        })
-    ).match({
-        related: [
-            { identifier: 'terms', model: ConsentFlowTerms },
-            ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
-            { model: ConsentFlowContract },
-            ConsentFlowContract.getRelationshipByAlias('createdBy'),
-            { model: Profile, where: { profileId } },
-        ],
-        // The following is custom Cypher logic that has the following behavior:
-        // If query key is true, ensure all resulting terms have that key
-        // If query key is false, ensure no resulting terms have that key
-        // If query key is not present, return all terms whether they have it or not
-    }).where(`
-all(key IN keys($params) WHERE 
-    CASE $params[key]
-        WHEN true THEN terms[key] IS NOT NULL AND terms[key] <> []
-        WHEN false THEN terms[key] IS NULL OR terms[key] = []
-    END
-)
-`);
-
-    const dbQuery = cursor ? _dbQuery.raw('terms.updatedAt < $cursor') : _dbQuery;
-
-    const results = convertQueryResultToPropertiesObjectArray<{
-        terms: FlatDbTermsType;
-    }>(await dbQuery.return('DISTINCT terms').orderBy('terms.updatedAt DESC').limit(limit).run());
-
-    const terms = results.map(result => inflateObject<any>(result.terms));
+/** Match filters against currently permitted data before counting a page. */
+const matchesConsentedDataQuery = (
+    term: DbTermsType,
+    query: ConsentFlowDataQuery,
+    now: number
+): boolean =>
+    // Legacy boolean data queries test field presence, including an explicit false value.
+    (query.anonymize === undefined || query.anonymize === (term.terms.read.anonymize != null)) &&
+    Object.entries(query.personal ?? {}).every(
+        ([key, required]) => required === (term.terms.read.personal?.[key] != null)
+    ) &&
+    Object.entries(query.credentials?.categories ?? {}).every(([name, required]) => {
+        const category = term.terms.read.credentials.categories[name];
+        const shared =
+            term.terms.read.credentials.sharing !== false &&
+            !!category?.sharing &&
+            isConsentExpiryActive(category.shareUntil, now) &&
+            !!category.shared?.length;
+        return required === shared;
+    });
 
-    return terms.map(term => ({
-        date: term.updatedAt!,
-        credentials: {
-            categories: mapValues(
-                term.terms.read.credentials.categories,
-                category => category.shared ?? []
-            ),
-        },
-        personal: term.terms.read.personal,
+const projectConsentedData = (
+    term: DbTermsType,
+    query: ConsentFlowDataQuery,
+    now: number
+): ConsentFlowContractData => ({
+    date: term.updatedAt!,
+    credentials: {
+        categories: mapValues(term.terms.read.credentials?.categories ?? {}, (category, name) =>
+            term.terms.read.credentials.sharing !== false &&
+            category.sharing &&
+            isConsentExpiryActive(category.shareUntil, now) &&
+            shouldIncludeCategory(query.credentials?.categories, name)
+                ? (category.shared ?? [])
+                : []
+        ),
+    },
+    personal: term.terms.read.personal ?? {},
+});
+
+/** Filters reduce candidates in Neo4j; batches then reject invalid/expired grants.
+ * Do not cap scanned candidates: doing so would silently hide valid matches later in a page.
+ * Expiry and negative category filters still require the authoritative JS permission check.
+ */
+const getPermittedContractData = async (
+    viewerProfileId: string,
+    { query = {}, limit, cursor }: { query?: ConsentFlowDataQuery; limit: number; cursor?: string },
+    contractId?: string
+): Promise<ConsentFlowContractData[]> => {
+    const now = Date.now();
+    const records: ConsentFlowContractData[] = [];
+    const personalFilters = Object.entries(query.personal ?? {}).map(([name, required]) => ({
+        key: `terms.read.personal.${name}`,
+        required,
     }));
+    const sharedCategories = Object.entries(query.credentials?.categories ?? {})
+        .filter(([, required]) => required)
+        .map(([name]) => ({
+            sharingKey: `terms.read.credentials.categories.${name}.sharing`,
+            sharedKey: `terms.read.credentials.categories.${name}.shared`,
+        }));
+    const batchSize = Math.max(limit, 50);
+    let offset = 0;
+    while (records.length < limit) {
+        const dbQuery = new QueryBuilder(
+            new BindParam({ cursor, personalFilters, sharedCategories })
+        )
+            .match({
+                related: [
+                    { identifier: 'terms', model: ConsentFlowTerms },
+                    ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
+                    {
+                        model: ConsentFlowContract,
+                        identifier: 'contract',
+                        ...(contractId ? { where: { id: contractId } } : {}),
+                    },
+                    '-[:CREATED_BY|SHARES_DATA_WITH]->',
+                    { model: Profile, where: { profileId: viewerProfileId } },
+                ],
+            })
+            .where(
+                "(terms.status = 'live' OR (terms.status = 'stale' AND terms.oneTime = true))" +
+                    (cursor ? ' AND terms.updatedAt < $cursor' : '') +
+                    ' AND all(filter IN $personalFilters WHERE filter.required = (terms[filter.key] IS NOT NULL))' +
+                    ' AND (size($sharedCategories) = 0 OR coalesce(terms.`terms.read.credentials.sharing`, true) = true)' +
+                    ' AND all(category IN $sharedCategories WHERE terms[category.sharingKey] = true AND' +
+                    " (terms[category.sharedKey] IS NOT NULL OR any(key IN keys(terms) WHERE key STARTS WITH category.sharedKey + '.')))"
+            );
+        const results = convertQueryResultToPropertiesObjectArray<{
+            terms: FlatDbTermsType;
+            contract: FlatDbContractType;
+        }>(
+            await dbQuery
+                .return('DISTINCT terms, contract')
+                .orderBy('terms.updatedAt DESC, terms.id ASC')
+                .skip(offset)
+                .limit(batchSize)
+                .run()
+        );
+        for (const result of results) {
+            const term = DbTermsValidator.safeParse(inflateObject(result.terms));
+            const contract = DbContractValidator.safeParse(inflateObject(result.contract));
+            if (
+                !term.success ||
+                !contract.success ||
+                !isConsentExpiryActive(term.data.expiresAt, now) ||
+                !isConsentExpiryActive(contract.data.expiresAt, now) ||
+                !matchesConsentedDataQuery(term.data, query, now)
+            )
+                continue;
+            records.push(projectConsentedData(term.data, query, now));
+            if (records.length >= limit) return records;
+        }
+        if (results.length < batchSize) break;
+        offset += batchSize;
+    }
+    return records;
 };
 
+export const getConsentedDataForProfile = async (
+    profileId: string,
+    options: { query?: ConsentFlowDataQuery; limit: number; cursor?: string }
+): Promise<ConsentFlowContractData[]> => getPermittedContractData(profileId, options);
+
 export const getConsentedDataForContract = async (
     id: string,
-    { query = {}, limit, cursor }: { query?: ConsentFlowDataQuery; limit: number; cursor?: string }
-): Promise<ConsentFlowContractData[]> => {
-    const _dbQuery = new QueryBuilder(
-        new BindParam({
-            params: flattenObject({ terms: flattenObject(convertDataQueryToNeo4jQuery(query)) }),
-            cursor,
-        })
-    ).match({
-        related: [
-            { identifier: 'terms', model: ConsentFlowTerms },
-            ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
-            { model: ConsentFlowContract, where: { id: id } },
-        ],
-        // The following is custom Cypher logic that has the following behavior:
-        // If query key is true, ensure all resulting terms have that key
-        // If query key is false, ensure no resulting terms have that key
-        // If query key is not present, return all terms whether they have it or not
-    }).where(`
-all(key IN keys($params) WHERE 
-    CASE $params[key]
-        WHEN true THEN terms[key] IS NOT NULL AND terms[key] <> []
-        WHEN false THEN terms[key] IS NULL OR terms[key] = []
-    END
-)
-`);
-
-    const dbQuery = cursor ? _dbQuery.where('terms.updatedAt < $cursor') : _dbQuery;
-
-    const results = convertQueryResultToPropertiesObjectArray<{
-        terms: FlatDbTermsType;
-    }>(await dbQuery.return('DISTINCT terms').orderBy('terms.updatedAt DESC').limit(limit).run());
-
-    const terms = results.map(result => inflateObject<any>(result.terms));
-
-    return terms.map(term => ({
-        date: term.updatedAt!,
-        credentials: {
-            categories: mapValues(
-                term.terms.read.credentials.categories,
-                category => category.shared ?? []
-            ),
-        },
-        personal: term.terms.read.personal,
-    }));
-};
+    viewerProfileId: string,
+    options: { query?: ConsentFlowDataQuery; limit: number; cursor?: string }
+): Promise<ConsentFlowContractData[]> => getPermittedContractData(viewerProfileId, options, id);
 
 // Empty expiry values historically mean no expiry. Invalid nonempty values never authorize access.
 const isConsentExpiryActive = (expiresAt: string | undefined, now: number): boolean => {
@@ -562,7 +619,17 @@ export const getConsentedDataBetweenProfiles = async (
     const { whereClause: contractWhereClause, params: contractQueryParams } =
         buildWhereForQueryBuilder('contract', convertedContractQuery as any);
     const now = Date.now();
-    const managers = await getProfilesThatManageAProfile(consenterProfileId);
+    const [managers, consenterProfile] = await Promise.all([
+        getProfilesThatManageAProfile(consenterProfileId),
+        getProfileByProfileId(consenterProfileId),
+    ]);
+    const isManagedProfile = managers.length > 0;
+    const requiresManagerApproval =
+        isManagedProfile &&
+        !isServiceProfileExemptFromGuardianship(
+            consenterProfile?.isServiceProfile,
+            consenterProfile?.type
+        );
     const records: ConsentFlowContractDataForDid[] = [];
     const batchSize = Math.max(limit, 50);
     let offset = 0;
@@ -572,9 +639,6 @@ export const getConsentedDataBetweenProfiles = async (
     while (records.length < limit) {
         const _dbQuery = new QueryBuilder(
             new BindParam({
-                params: flattenObject({
-                    terms: flattenObject(convertDataQueryToNeo4jQuery(params)),
-                }),
                 cursor,
                 ...contractQueryParams,
             })
@@ -585,7 +649,7 @@ export const getConsentedDataBetweenProfiles = async (
                 { identifier: 'terms', model: ConsentFlowTerms },
                 ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
                 { model: ConsentFlowContract, identifier: 'contract' },
-                ConsentFlowContract.getRelationshipByAlias('createdBy'),
+                '-[:CREATED_BY|SHARES_DATA_WITH]->',
                 { model: Profile, where: { profileId: ownerProfileId } },
             ],
             // The following is custom Cypher logic that has the following behavior:
@@ -594,12 +658,6 @@ export const getConsentedDataBetweenProfiles = async (
             // If query key is not present, return all terms whether they have it or not
         }).where(`
 (terms.status = 'live' OR (terms.status = 'stale' AND terms.oneTime = true))
-AND all(key IN keys($params) WHERE
-    CASE $params[key]
-        WHEN true THEN terms[key] IS NOT NULL AND terms[key] <> []
-        WHEN false THEN terms[key] IS NULL OR terms[key] = []
-    END
-)
 AND ${contractWhereClause}
 `);
 
@@ -648,12 +706,14 @@ AND ${contractWhereClause}
             )
                 continue;
 
+            if (!matchesConsentedDataQuery(term, params, now)) continue;
+
             const parsedApproval = ConsentFlowGuardianApprovalValidator.safeParse(
                 term.guardianApproval
             );
             const approval = parsedApproval.success ? parsedApproval.data : undefined;
             const required =
-                managers.length > 0 || !!term.guardianApproval || result.hadGuardianApproval;
+                requiresManagerApproval || !!term.guardianApproval || result.hadGuardianApproval;
             const approved =
                 !!approval &&
                 approval.contractUpdatedAt === contract.updatedAt &&
@@ -664,6 +724,7 @@ AND ${contractWhereClause}
                             getDidWeb(domain, manager.profileId) === approval.guardianDid)
                 );
 
+            const permittedData = projectConsentedData(term, params, now);
             records.push({
                 date: result.date,
                 ...(result.createdAt ? { createdAt: result.createdAt } : {}),
@@ -677,7 +738,22 @@ AND ${contractWhereClause}
                 termsUri: constructUri('terms', term.id, domain),
                 status: term.status,
                 ...(term.expiresAt?.trim() ? { expiresAt: term.expiresAt } : {}),
-                terms: term.terms,
+                terms: {
+                    ...term.terms,
+                    read: {
+                        ...term.terms.read,
+                        credentials: {
+                            ...term.terms.read.credentials,
+                            categories: mapValues(
+                                term.terms.read.credentials.categories,
+                                (category, name) => ({
+                                    ...category,
+                                    shared: permittedData.credentials.categories[name] ?? [],
+                                })
+                            ),
+                        },
+                    },
+                },
                 credentials: Object.entries(term.terms.read.credentials.categories).flatMap(
                     ([category, { shared, sharing, shareUntil }]) => {
                         if (

package/src/accesslayer/consentflowcontract/relationships/recipients.ts

@@ -0,0 +1,125 @@
+import { BindParam, QueryBuilder } from 'neogma';
+import { TRPCError } from '@trpc/server';
+import { ConsentFlowContract, Profile } from '@models';
+import { ProfileType } from 'types/profile';
+
+/** Lock the contract before checking its audience, in the same database statement. */
+export const lockContractAudience = (query: QueryBuilder, contractId: string): QueryBuilder =>
+    query
+        .match({ model: ConsentFlowContract, identifier: 'contract', where: { id: contractId } })
+        .set('contract.audienceLock = coalesce(contract.audienceLock, 0) + 1')
+        .with('contract');
+
+/** Retry only rolled-back transient transactions, before any notifications or issuance. */
+export const runAudienceMutation = async (query: QueryBuilder): ReturnType<QueryBuilder['run']> => {
+    for (let attempt = 0; ; attempt += 1) {
+        try {
+            return await query.run();
+        } catch (error) {
+            if (
+                attempt >= 8 ||
+                !error ||
+                typeof error !== 'object' ||
+                !('code' in error) ||
+                error.code !== 'Neo.TransientError.Transaction.DeadlockDetected'
+            )
+                throw error;
+            await new Promise(resolve =>
+                setTimeout(resolve, Math.min(1000, 25 * 2 ** attempt) + Math.random() * 25)
+            );
+        }
+    }
+};
+
+export const audienceVersionWhere = `
+(($audienceVersion IS NULL AND coalesce(contract.audienceVersion, 0) = 0)
+ OR coalesce(contract.audienceVersion, 0) = $audienceVersion)
+`;
+
+/** Checked under the contract lock; a referral accepts only the invitation the learner reviewed. */
+export const consentMutationWhere = `
+(CASE WHEN contract.expiresAt IS NULL OR trim(contract.expiresAt) = '' THEN true
+ ELSE datetime(contract.expiresAt) > datetime.realtime() END)
+AND ($expectedRequestId IS NULL OR EXISTS {
+    MATCH (contract)-[request:REQUESTED_FOR]->(:Profile {profileId: $consenterProfileId})
+    WHERE request.requestId = $expectedRequestId AND request.status = 'pending'
+})
+`;
+
+export const assertAudienceMutation = (count: number): void => {
+    if (!count)
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'The sharing audience or consent changed. Review the contract and try again.',
+        });
+};
+
+export const getRecipientsForContract = async (contractId: string): Promise<ProfileType[]> => {
+    const result = await new QueryBuilder()
+        .match({
+            related: [
+                { model: ConsentFlowContract, where: { id: contractId } },
+                ConsentFlowContract.getRelationshipByAlias('sharesDataWith'),
+                { model: Profile, identifier: 'recipient' },
+            ],
+        })
+        .return('DISTINCT recipient')
+        .run();
+    return result.records.map(record => record.get('recipient').properties);
+};
+
+export const canReadContractData = async (
+    contractId: string,
+    profileId: string
+): Promise<boolean> => {
+    const result = await new QueryBuilder(new BindParam({ contractId, profileId }))
+        .match(
+            '(contract:ConsentFlowContract {id: $contractId})-[:CREATED_BY|SHARES_DATA_WITH]->(profile:Profile {profileId: $profileId})'
+        )
+        .return('count(profile) AS count')
+        .run();
+    return Number(result.records[0]?.get('count') ?? 0) > 0;
+};
+
+/** Additions freeze after first consent; removals never restore that permission. */
+export const addRecipientToContract = async (
+    contractId: string,
+    profileId: string
+): Promise<boolean> => {
+    const query = lockContractAudience(new QueryBuilder(new BindParam({ profileId })), contractId)
+        .match('(recipient:Profile {profileId: $profileId})')
+        .where(
+            `NOT EXISTS { MATCH (contract)-[:CREATED_BY]->(recipient) }
+            AND (EXISTS { MATCH (contract)-[:SHARES_DATA_WITH]->(recipient) }
+                OR (coalesce(contract.hasConsented, false) = false
+                    AND NOT EXISTS { MATCH (:ConsentFlowTerms)-[:CONSENTS_TO]->(contract) }
+                    AND size([(contract)-[:SHARES_DATA_WITH]->(existing:Profile) | existing]) < 50))`
+        )
+        .merge('(contract)-[audience:SHARES_DATA_WITH]->(recipient)')
+        .raw(
+            'ON CREATE SET contract.audienceVersion = coalesce(contract.audienceVersion, 0) + 1, audience.addedAt = $addedAt'
+        );
+    query.getBindParam().add({ addedAt: new Date().toISOString() });
+    const result = await runAudienceMutation(query.return('count(audience) AS count'));
+    if (!Number(result.records[0]?.get('count') ?? 0))
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message:
+                'Recipients can only be added before first consent, and the owner is already in the audience.',
+        });
+    return true;
+};
+
+export const removeRecipientFromContract = async (
+    contractId: string,
+    profileId: string
+): Promise<boolean> => {
+    const result = await runAudienceMutation(
+        lockContractAudience(new QueryBuilder(new BindParam({ profileId })), contractId)
+            .match('(contract)-[audience:SHARES_DATA_WITH]->(:Profile {profileId: $profileId})')
+            .delete('audience')
+            .set('contract.audienceVersion = coalesce(contract.audienceVersion, 0) + 1')
+            .return('count(contract) AS count')
+    );
+    return Number(result.records[0]?.get('count') ?? 0) > 0;
+};

package/src/accesslayer/consentflowcontract/relationships/smartResume.ts

@@ -0,0 +1,125 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { BindParam, QueryBuilder } from 'neogma';
+import { TRPCError } from '@trpc/server';
+import type { ConsentFlowTerms } from '@learncard/types';
+import { inflateObject } from '@helpers/objects.helpers';
+import type { DbTermsType } from 'types/consentflowcontract';
+import {
+    audienceVersionWhere,
+    assertAudienceMutation,
+    lockContractAudience,
+    runAudienceMutation,
+} from './recipients';
+
+const canonicalize = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(
+            Object.entries(value)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([key, entry]) => [key, canonicalize(entry)])
+        );
+    return value;
+};
+
+/** Bind retries to the original decision without persisting the recipient token. */
+export const smartResumeFingerprint = (submission: unknown): string =>
+    createHash('sha256')
+        .update(JSON.stringify(canonicalize(submission)))
+        .digest('hex');
+
+/**
+ * Claim publication only after consent committed, under the same audience lock.
+ * A bounded lease prevents concurrent retries; completed retries reuse the redirect.
+ * A failed publication retains consent and can retry the identical submission.
+ */
+export const publishSmartResume = async ({
+    contractId,
+    profileId,
+    termsId,
+    fingerprint,
+    audienceVersion,
+    expectedRequestId,
+    upload,
+}: {
+    contractId: string;
+    profileId: string;
+    termsId: string;
+    fingerprint: string;
+    audienceVersion?: number;
+    expectedRequestId?: string;
+    upload: (terms: ConsentFlowTerms) => Promise<string | undefined>;
+}): Promise<string | undefined> => {
+    const leaseId = randomUUID();
+    // Token request and credentials POST each time out after 30s. URI resolution
+    // must also finish before this lease expires, or publication must be retried.
+    const leaseDurationMs = 120_000;
+    const result = await runAudienceMutation(
+        lockContractAudience(
+            new QueryBuilder(
+                new BindParam({
+                    profileId,
+                    termsId,
+                    fingerprint,
+                    audienceVersion: audienceVersion ?? null,
+                    expectedRequestId: expectedRequestId ?? null,
+                    leaseId,
+                    leaseDurationMs,
+                })
+            ),
+            contractId
+        )
+            .where(audienceVersionWhere)
+            .match(
+                '(profile:Profile {profileId: $profileId})-[:CREATED_BY]->(terms:ConsentFlowTerms {id: $termsId})-[:CONSENTS_TO]->(contract)'
+            )
+            .where(
+                `terms.smartResumeFingerprint = $fingerprint
+                AND ($expectedRequestId IS NULL OR EXISTS {
+                    MATCH (contract)-[request:REQUESTED_FOR]->(profile)
+                    WHERE request.requestId = $expectedRequestId AND request.status = 'accepted'
+                })
+                AND terms.smartResumeMutationVersion = coalesce(terms.mutationVersion, 0)
+                AND (terms.status = 'live' OR (terms.status = 'stale' AND terms.oneTime = true))
+                AND CASE WHEN terms.expiresAt IS NULL OR trim(terms.expiresAt) = '' THEN true ELSE datetime(terms.expiresAt) > datetime.realtime() END
+                AND CASE WHEN contract.expiresAt IS NULL OR trim(contract.expiresAt) = '' THEN true ELSE datetime(contract.expiresAt) > datetime.realtime() END
+                AND (terms.smartResumePublicationStatus IN ['pending', 'failed', 'succeeded']
+                    OR (terms.smartResumePublicationStatus = 'sending' AND terms.smartResumeLeaseUntil < datetime.realtime().epochMillis))`
+            )
+            .set(
+                `terms.smartResumeLeaseId = CASE WHEN terms.smartResumePublicationStatus = 'succeeded' THEN terms.smartResumeLeaseId ELSE $leaseId END,
+                terms.smartResumeLeaseUntil = CASE WHEN terms.smartResumePublicationStatus = 'succeeded' THEN terms.smartResumeLeaseUntil ELSE datetime.realtime().epochMillis + $leaseDurationMs END,
+                terms.smartResumePublicationStatus = CASE WHEN terms.smartResumePublicationStatus = 'succeeded' THEN 'succeeded' ELSE 'sending' END`
+            )
+            .return('terms')
+    );
+    assertAudienceMutation(result.records.length);
+    const accepted = inflateObject(result.records[0]!.get('terms').properties) as DbTermsType;
+    if (accepted.smartResumePublicationStatus === 'succeeded')
+        return accepted.smartResumeRedirectUrl;
+
+    const finish = async (status: 'failed' | 'succeeded', redirectUrl?: string): Promise<void> => {
+        await new QueryBuilder(
+            new BindParam({ termsId, leaseId, status, redirectUrl: redirectUrl ?? null })
+        )
+            .match('(terms:ConsentFlowTerms {id: $termsId})')
+            .where('terms.smartResumeLeaseId = $leaseId')
+            .set(
+                'terms.smartResumePublicationStatus = $status, terms.smartResumeRedirectUrl = $redirectUrl'
+            )
+            .run();
+    };
+    try {
+        const redirectUrl = await upload(accepted.terms);
+        await finish('succeeded', redirectUrl);
+        return redirectUrl;
+    } catch (cause) {
+        await finish('failed');
+        throw new TRPCError({
+            code: 'BAD_GATEWAY',
+            message:
+                'Your consent was saved, but the SmartResume upload failed. Retry to finish connecting.',
+            cause,
+        });
+    }
+};