@learncard/network-brain-service 3.19.1 → 4.0.1

package/src/routes/contracts.ts

@@ -1,9 +1,22 @@
+import { SendContractRequestValidator, ContractRequestFieldsValidator } from '@learncard/types';
+import {
+    sendGenericContractRequest,
+    decideGenericContractRequest,
+    markGenericContractRequestSeen,
+    assertGenericRequestWriteScope,
+    canManageContractRequests,
+    resolveContractRequest,
+} from '@helpers/contract-requests.helpers';
 import { environment } from '@environment';
+import {
+    smartResumeFingerprint,
+    publishSmartResume,
+} from '@accesslayer/consentflowcontract/relationships/smartResume';
+import { uploadSmartResume } from '@helpers/smartResume.helpers';
 import { TRPCError } from '@trpc/server';
 import { z } from 'zod';
 
 import { t, profileRoute, openRoute, guardianGatedRoute } from '@routes';
-import { ConsentFlowContract } from '@models';
 
 import {
     ConsentFlowContractValidator,
@@ -47,10 +60,11 @@ import {
     isProfileConsentFlowContractAdmin,
     getWritersForContract,
 } from '@accesslayer/consentflowcontract/relationships/read';
-import { constructUri, getIdFromUri, resolveUri } from '@helpers/uri.helpers';
+import { inflateObject } from '@helpers/objects.helpers';
+import { constructUri, getIdFromUri } from '@helpers/uri.helpers';
 import {
     getContractByUri,
-    getConsentFlowContractById,
+    getStoredContractRequest,
     getRequestedForList,
     getRequestedForForUser,
     getContractById,
@@ -64,17 +78,12 @@ import { areTermsValid } from '@helpers/contract.helpers';
 import { updateDidForProfile, getProfileIdFromString } from '@helpers/did.helpers';
 import {
     syncCredentialsToContract,
-    updateRequestedForStatusIfExists,
     updateTerms,
     pruneDeletedUrisFromConsentTerms,
     upsertRequestedForRelationship,
     withdrawTerms,
 } from '@accesslayer/consentflowcontract/relationships/update';
-import {
-    consentToContract,
-    setAutoBoostForContract,
-    setCreatorForContract,
-} from '@accesslayer/consentflowcontract/relationships/create';
+import { consentToContract } from '@accesslayer/consentflowcontract/relationships/create';
 import { getProfileByDid, getProfileByProfileId } from '@accesslayer/profile/read';
 import { sendBoost, isDraftBoost } from '@helpers/boost.helpers';
 import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
@@ -105,6 +114,24 @@ import { addNotificationToQueue } from '@helpers/notifications.helpers';
 import { getNotificationMessage } from '@helpers/notificationMessages';
 import { resolveRecipientLocale } from '@helpers/getRecipientLocale.helpers';
 import { ProfileType } from 'types/profile';
+import {
+    getRecipientsForContract,
+    addRecipientToContract,
+    removeRecipientFromContract,
+    canReadContractData,
+} from '@accesslayer/consentflowcontract/relationships/recipients';
+
+const publicContractRecipient = (domain: string, recipient: ProfileType) => {
+    const profile = updateDidForProfile(domain, recipient);
+    return { ...sanitizeProfileForTier(profile, 'unauthenticated'), did: profile.did };
+};
+
+const resolveRecipientProfileId = async (identifier: string, domain: string): Promise<string> => {
+    const profileId = await getProfileIdFromString(identifier, domain);
+    if (!profileId)
+        throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid recipient identifier' });
+    return profileId;
+};
 
 export const contractsRouter = t.router({
     createConsentFlowContract: profileRoute
@@ -133,6 +160,7 @@ export const contractsRouter = t.router({
                 expiresAt: z.string().optional(),
                 autoboosts: z.array(AutoBoostConfigValidator).optional(),
                 writers: z.array(z.string()).optional(),
+                recipients: z.array(z.string()).max(50).optional(),
             })
         )
         .output(z.string())
@@ -150,26 +178,31 @@ export const contractsRouter = t.router({
                 expiresAt,
                 autoboosts,
                 writers,
+                recipients,
             } = input;
 
-            // Create ConsentFlow instance
-            const createdContract = await createConsentFlowContract({
-                contract,
-                name,
-                subtitle,
-                description,
-                reasonForAccessing,
-                needsGuardianConsent,
-                redirectUrl,
-                frontDoorBoostUri,
-                image,
-                expiresAt,
-            });
+            const recipientIds = [
+                ...new Set(
+                    await Promise.all(
+                        (recipients ?? []).map(id => resolveRecipientProfileId(id, ctx.domain))
+                    )
+                ),
+            ].filter(id => id !== ctx.user.profile.profileId);
+            const recipientProfiles = await getProfilesByProfileIds(recipientIds);
+            if (recipientProfiles.length !== recipientIds.length) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Could not find all recipient profiles',
+                });
+            }
 
-            // Get profile by profileId
-            await setCreatorForContract(createdContract, ctx.user.profile);
+            const preparedAutoBoosts: {
+                id: string;
+                signingAuthorityEndpoint: string;
+                signingAuthorityName: string;
+            }[] = [];
 
-            // Add specified writers
+            // Validate specified writers before creating the contract.
             if (writers && writers.length > 0) {
                 const writerProfiles = await getProfilesByProfileIds(writers);
 
@@ -184,17 +217,6 @@ export const contractsRouter = t.router({
                         )}`,
                     });
                 }
-
-                // Create CAN_WRITE relationship for each writer using static relateTo
-                for (const writerProfile of writerProfiles) {
-                    await ConsentFlowContract.relateTo({
-                        alias: 'canWrite',
-                        where: {
-                            source: { id: createdContract.id }, // Specify source contract by id
-                            target: { profileId: writerProfile.profileId }, // Specify target profile by profileId
-                        },
-                    });
-                }
             }
 
             if (autoboosts && autoboosts.length > 0) {
@@ -243,18 +265,94 @@ export const contractsRouter = t.router({
                         });
                     }
 
-                    await setAutoBoostForContract(
-                        createdContract,
-                        boost,
-                        normalizedSigningAuthority,
-                        ctx.user.profile.profileId
-                    );
+                    preparedAutoBoosts.push({
+                        id: boost.id,
+                        signingAuthorityEndpoint: normalizedSigningAuthority.endpoint,
+                        signingAuthorityName: normalizedSigningAuthority.name,
+                    });
                 }
             }
 
+            // All validation precedes the single atomic creation statement.
+            const createdContract = await createConsentFlowContract({
+                contract,
+                ownerProfileId: ctx.user.profile.profileId,
+                recipientIds,
+                writerIds: writers,
+                autoboosts: preparedAutoBoosts,
+                name,
+                subtitle,
+                description,
+                reasonForAccessing,
+                needsGuardianConsent,
+                redirectUrl,
+                frontDoorBoostUri,
+                image,
+                expiresAt,
+            });
+
             return constructUri('contract', createdContract.id, ctx.domain);
         }),
 
+    addContractRecipient: profileRoute
+        .meta({
+            requiredScope: 'contracts:write',
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/consent-flow-contract/recipient/add',
+                tags: ['Contracts'],
+                summary: 'Add a data recipient before first consent',
+            },
+        })
+        .input(z.object({ contractUri: z.string(), recipient: z.string() }))
+        .output(z.boolean())
+        .mutation(async ({ ctx, input }) => {
+            const contract = await getContractByUri(input.contractUri);
+            if (!contract)
+                throw new TRPCError({ code: 'NOT_FOUND', message: 'Could not find contract' });
+            if (!(await isProfileConsentFlowContractAdmin(ctx.user.profile, contract)))
+                throw new TRPCError({
+                    code: 'UNAUTHORIZED',
+                    message: 'Profile does not own contract',
+                });
+            const profileId = await resolveRecipientProfileId(input.recipient, ctx.domain);
+            if (!(await getProfileByProfileId(profileId)))
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Could not find recipient profile',
+                });
+            return addRecipientToContract(contract.id, profileId);
+        }),
+
+    removeContractRecipient: profileRoute
+        .meta({
+            requiredScope: 'contracts:write',
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/consent-flow-contract/recipient/remove',
+                tags: ['Contracts'],
+                summary: 'Remove a data recipient',
+            },
+        })
+        .input(z.object({ contractUri: z.string(), recipient: z.string() }))
+        .output(z.boolean())
+        .mutation(async ({ ctx, input }) => {
+            const contract = await getContractByUri(input.contractUri);
+            if (!contract)
+                throw new TRPCError({ code: 'NOT_FOUND', message: 'Could not find contract' });
+            if (!(await isProfileConsentFlowContractAdmin(ctx.user.profile, contract)))
+                throw new TRPCError({
+                    code: 'UNAUTHORIZED',
+                    message: 'Profile does not own contract',
+                });
+            return removeRecipientFromContract(
+                contract.id,
+                await resolveRecipientProfileId(input.recipient, ctx.domain)
+            );
+        }),
+
     getConsentFlowContract: openRoute
         .meta({
             openapi: {
@@ -280,6 +378,7 @@ export const contractsRouter = t.router({
             }
 
             const autoboosts = await getAutoBoostsForContract(result.contract.id, ctx.domain);
+            const recipients = await getRecipientsForContract(result.contract.id);
 
             return {
                 owner: updateDidForProfile(ctx.domain, result.contractOwner),
@@ -297,6 +396,10 @@ export const contractsRouter = t.router({
                 uri: constructUri('contract', result.contract.id, ctx.domain),
                 ...(result.contract.expiresAt ? { expiresAt: result.contract.expiresAt } : {}),
                 autoBoosts: autoboosts,
+                recipients: recipients.map(recipient =>
+                    publicContractRecipient(ctx.domain, recipient)
+                ),
+                audienceVersion: Number(result.contract.audienceVersion ?? 0),
             };
         }),
 
@@ -426,16 +529,16 @@ export const contractsRouter = t.router({
                 throw new TRPCError({ code: 'NOT_FOUND', message: 'Could not find contract' });
             }
 
-            if (!(await isProfileConsentFlowContractAdmin(profile, contract))) {
+            if (!(await canReadContractData(contract.id, profile.profileId))) {
                 throw new TRPCError({
                     code: 'UNAUTHORIZED',
-                    message: 'Profile does not own contract',
+                    message: 'Profile is not in the contract data audience',
                 });
             }
 
             const contractId = getIdFromUri(uri);
 
-            const results = await getConsentedDataForContract(contractId, {
+            const results = await getConsentedDataForContract(contractId, profile.profileId, {
                 query,
                 limit: limit + 1,
                 cursor,
@@ -892,6 +995,8 @@ export const contractsRouter = t.router({
                 contractUri: z.string(),
                 expiresAt: z.string().optional(),
                 oneTime: z.boolean().optional(),
+                audienceVersion: z.number().int().nonnegative().optional(),
+                expectedRequestId: z.string().min(1).optional(),
                 recipientToken: z.string().optional(), // SmartResume recipientToken needed for API call
             })
         )
@@ -907,7 +1012,15 @@ export const contractsRouter = t.router({
                 });
             }
 
-            const { terms, contractUri, expiresAt, oneTime, recipientToken } = input;
+            const {
+                terms,
+                contractUri,
+                expiresAt,
+                oneTime,
+                recipientToken,
+                audienceVersion,
+                expectedRequestId,
+            } = input;
 
             const contractDetails = await getContractDetailsByUri(contractUri);
 
@@ -915,7 +1028,37 @@ export const contractsRouter = t.router({
                 throw new TRPCError({ code: 'NOT_FOUND', message: 'Could not find contract' });
             }
 
-            if (await hasProfileConsentedToContract(profile, contractDetails.contract)) {
+            if (
+                contractDetails.contract.expiresAt?.trim() &&
+                (!Number.isFinite(Date.parse(contractDetails.contract.expiresAt)) ||
+                    Date.parse(contractDetails.contract.expiresAt) <= Date.now())
+            ) {
+                throw new TRPCError({ code: 'CONFLICT', message: 'This contract has expired.' });
+            }
+            const isSmartResume =
+                contractUri === environment.SMART_RESUME_CONTRACT_URI ||
+                contractUri ===
+                    'lc:network:network.learncard.com/trpc:contract:55b738f0-49f4-4b33-b6c1-afa99b605cd6';
+            if (isSmartResume && !recipientToken) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Missing recipientToken for SmartResume',
+                });
+            }
+            const previousTerms = await getContractTermsForProfile(
+                profile,
+                contractDetails.contract
+            );
+            const retrySmartResume =
+                isSmartResume &&
+                Boolean(previousTerms?.smartResumeFingerprint) &&
+                (previousTerms?.status === 'live' ||
+                    (previousTerms?.status === 'stale' && previousTerms.oneTime));
+
+            if (
+                !retrySmartResume &&
+                (await hasProfileConsentedToContract(profile, contractDetails.contract))
+            ) {
                 try {
                     await upsertRequestedForRelationship(
                         contractDetails.contract.id,
@@ -930,10 +1073,6 @@ export const contractsRouter = t.router({
             }
 
             if (!guardianIdentity) {
-                const previousTerms = await getContractTermsForProfile(
-                    profile,
-                    contractDetails.contract
-                );
                 if (previousTerms && (await hasGuardianApprovalHistory(previousTerms))) {
                     throw new TRPCError({
                         code: 'FORBIDDEN',
@@ -954,156 +1093,46 @@ export const contractsRouter = t.router({
                 );
             }
 
-            let redirectUrl: string | undefined;
-            // SmartResume handling
-            const isSmartResume =
-                contractUri === environment.SMART_RESUME_CONTRACT_URI ||
-                contractUri ===
-                    'lc:network:network.learncard.com/trpc:contract:55b738f0-49f4-4b33-b6c1-afa99b605cd6'; // hardcode for quick fix purposes
-            if (isSmartResume) {
-                if (!recipientToken) {
-                    throw new Error('Missing recipientToken for SmartResume');
-                }
-
-                const isProduction = !environment.IS_OFFLINE;
-
-                const srUrl = isProduction
-                    ? 'https://my.smartresume.com/'
-                    : 'https://mystage.smartresume.com/';
-                const clientId = environment.SMART_RESUME_CLIENT_ID;
-                const accessKey = environment.SMART_RESUME_ACCESS_KEY;
-
-                const accessTokenResponse = (await fetch(`${srUrl}api/v1/token`, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/x-www-form-urlencoded',
-                        Authorization: `Basic ${btoa(`${clientId}:${accessKey}`)}`,
-                    },
-                    body: new URLSearchParams({
-                        grant_type: 'client_credentials',
-                        scope: 'delete readonly replace',
-                    }),
-                }).then(res => res.json())) as { access_token?: string };
-
-                const accessToken = accessTokenResponse.access_token;
-                if (!accessToken) throw new Error('Missing access_token for SmartResume');
-
-                const parsedTerms = ConsentFlowTermsValidator.parse(terms);
-
-                const categories = parsedTerms.read.credentials.categories;
-                const categoryValues = Object.values(categories) as Array<{ shared?: string[] }>;
-
-                const allSharedCredentialUris = [
-                    // filter out duplicates
-                    ...new Set(categoryValues.flatMap(({ shared }) => shared ?? [])),
-                ];
-
-                const resolvedCredentials = await Promise.all(
-                    allSharedCredentialUris.map(async uri => {
-                        try {
-                            return await resolveUri(uri);
-                        } catch (error) {
-                            console.error(`Error resolving URI ${uri}:`, error);
-                            return undefined;
-                        }
-                    })
-                );
-
-                type ResolvedCredential = {
-                    issuer?: string | { id: string };
-                    id?: string;
-                    boostCredential?: Record<string, unknown>;
-                } & Record<string, unknown>;
-
-                const credentials = resolvedCredentials
-                    .filter(
-                        (cred): cred is ResolvedCredential =>
-                            typeof cred === 'object' && cred !== null
-                    )
-                    .map(cred =>
-                        cred.boostCredential && typeof cred.boostCredential === 'object'
-                            ? ({ ...cred.boostCredential, id: cred.id } as ResolvedCredential) // unwrap credential, preserve id
-                            : cred
-                    );
-
-                const transformedCredentials = credentials.map(cred => {
-                    const issuer =
-                        typeof cred.issuer === 'string'
-                            ? { id: cred.issuer }
-                            : cred.issuer || { id: '' };
-
-                    return {
-                        ...cred,
-                        issuer,
-                    };
-                });
-
-                const { name, email } = parsedTerms.read.personal;
-
-                const body = JSON.stringify({
-                    '@context': [
-                        'https://www.w3.org/ns/credentials/v2',
-                        'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
-                        'https://w3id.org/security/suites/ed25519-2020/v1',
-                    ],
-                    recipienttoken: recipientToken,
-                    recipient: {
-                        id: ctx.user.did,
-                        givenName: name && name !== 'Anonymous' ? name : '',
-                        familyName: '', // this is neecessary in order for givenName to be respected
-                        email: email && email !== 'anonymous@hidden.com' ? email : '',
+            const fingerprint = isSmartResume
+                ? smartResumeFingerprint({
+                      terms,
+                      expiresAt,
+                      oneTime,
+                      audienceVersion,
+                      recipientToken,
+                      expectedRequestId,
+                  })
+                : undefined;
+            // A completed one-time snapshot can be followed by a new reviewed decision.
+            // Identical submissions still replay the completed upload instead.
+            const newDecisionAfterOneTime =
+                retrySmartResume &&
+                previousTerms?.status === 'stale' &&
+                previousTerms.oneTime &&
+                previousTerms.smartResumePublicationStatus === 'succeeded' &&
+                fingerprint !== previousTerms.smartResumeFingerprint;
+            if (!retrySmartResume || newDecisionAfterOneTime)
+                await consentToContract(
+                    profile,
+                    contractDetails,
+                    {
+                        terms,
+                        expiresAt,
+                        oneTime,
+                        audienceVersion,
+                        expectedRequestId,
+                        smartResumeFingerprint: fingerprint,
+                        guardianApproval: guardianIdentity
+                            ? {
+                                  guardianProfileId: guardianIdentity.profileId,
+                                  guardianDid: guardianIdentity.did,
+                                  approvedAt: new Date().toISOString(),
+                                  contractUpdatedAt: contractDetails.contract.updatedAt,
+                              }
+                            : undefined,
                     },
-                    credentials: transformedCredentials,
-                });
-
-                try {
-                    const response = await fetch(`${srUrl}api/v1/credentials`, {
-                        method: 'POST',
-                        headers: {
-                            Authorization: `Bearer ${accessToken}`,
-                            'Content-Type': 'application/json',
-                        },
-                        body,
-                    });
-
-                    if (!response.ok) {
-                        throw new Error(`Error (${response.status}): ${await response.text()}`);
-                    }
-
-                    const result = (await response.json()) as { redirect_url?: string };
-                    redirectUrl = result.redirect_url;
-                } catch (error) {
-                    console.error('Error uploading credentials to SmartResume:', error);
-                    throw error;
-                }
-            }
-
-            await consentToContract(
-                profile,
-                contractDetails,
-                {
-                    terms,
-                    expiresAt,
-                    oneTime,
-                    guardianApproval: guardianIdentity
-                        ? {
-                              guardianProfileId: guardianIdentity.profileId,
-                              guardianDid: guardianIdentity.did,
-                              approvedAt: new Date().toISOString(),
-                              contractUpdatedAt: contractDetails.contract.updatedAt,
-                          }
-                        : undefined,
-                },
-                ctx.domain
-            );
-
-            try {
-                await updateRequestedForStatusIfExists(
-                    contractDetails.contract.id,
-                    profile.profileId,
-                    'accepted'
+                    ctx.domain
                 );
-            } catch {}
 
             const relationship = await getContractTermsForProfile(
                 profile,
@@ -1117,6 +1146,18 @@ export const contractsRouter = t.router({
                 });
             }
 
+            const redirectUrl = isSmartResume
+                ? await publishSmartResume({
+                      contractId: contractDetails.contract.id,
+                      profileId: profile.profileId,
+                      termsId: relationship.id,
+                      fingerprint: fingerprint!,
+                      audienceVersion,
+                      expectedRequestId,
+                      upload: acceptedTerms =>
+                          uploadSmartResume(acceptedTerms, ctx.user.did, recipientToken!),
+                  })
+                : undefined;
             return { termsUri: constructUri('terms', relationship.id, ctx.domain), redirectUrl };
         }),
 
@@ -1178,9 +1219,14 @@ export const contractsRouter = t.router({
                             ? { expiresAt: record.contract.expiresAt }
                             : {}),
                         autoBoosts: record.autoBoosts,
+                        audienceVersion: Number(record.contract.audienceVersion ?? 0),
+                        recipients: record.recipients.map(recipient =>
+                            publicContractRecipient(ctx.domain, recipient)
+                        ),
                     },
                     uri: constructUri('terms', record.terms.id, ctx.domain),
                     terms: record.terms.terms,
+                    ...(record.terms.referral ? { referral: record.terms.referral } : {}),
                     ...(record.terms.expiresAt ? { expiresAt: record.terms.expiresAt } : {}),
                     ...(record.terms.oneTime ? { oneTime: record.terms.oneTime } : {}),
                     consenter: updateDidForProfile(ctx.domain, profile),
@@ -1207,6 +1253,7 @@ export const contractsRouter = t.router({
                 terms: ConsentFlowTermsValidator,
                 expiresAt: z.string().optional(),
                 oneTime: z.boolean().optional(),
+                audienceVersion: z.number().int().nonnegative().optional(),
             })
         )
         .output(z.boolean())
@@ -1222,7 +1269,7 @@ export const contractsRouter = t.router({
                 });
             }
 
-            const { uri, terms, expiresAt, oneTime } = input;
+            const { uri, terms, expiresAt, oneTime, audienceVersion } = input;
 
             const decodedUri = decodeURIComponent(uri);
             const relationship = await getContractTermsByUri(decodedUri);
@@ -1271,6 +1318,7 @@ export const contractsRouter = t.router({
                         terms,
                         expiresAt,
                         oneTime,
+                        audienceVersion,
                         guardianApproval: guardianIdentity
                             ? {
                                   guardianProfileId: guardianIdentity.profileId,
@@ -1396,7 +1444,7 @@ export const contractsRouter = t.router({
                 });
             }
 
-            await Promise.all([withdrawTerms(relationship), deleteStorageForUri(uri)]);
+            await Promise.all([withdrawTerms(relationship, ctx.domain), deleteStorageForUri(uri)]);
 
             return true;
         }),
@@ -1528,13 +1576,14 @@ export const contractsRouter = t.router({
         .input(
             z.object({
                 termsUri: z.string(),
+                audienceVersion: z.number().int().nonnegative().optional(),
                 categories: z.record(z.string(), z.string().array()),
             })
         )
         .output(z.boolean())
         .mutation(async ({ ctx, input }) => {
             const { profile } = ctx.user;
-            const { termsUri, categories } = input;
+            const { termsUri, categories, audienceVersion } = input;
 
             // Verify the terms exist and belong to this profile
             const relationship = await getContractTermsByUri(termsUri);
@@ -1604,7 +1653,12 @@ export const contractsRouter = t.router({
             }
 
             // Sync the credentials
-            const result = await syncCredentialsToContract(relationship, categories);
+            const result = await syncCredentialsToContract(
+                relationship,
+                categories,
+                audienceVersion,
+                ctx.domain
+            );
 
             return result;
         }),
@@ -1824,6 +1878,49 @@ export const contractsRouter = t.router({
             return true;
         }),
 
+    sendContractRequest: profileRoute
+        .meta({
+            requiredScope: 'contracts:write',
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/consent-flow-contracts/request',
+                tags: ['Contracts'],
+                summary: 'Send an attributed contract request',
+            },
+        })
+        .input(SendContractRequestValidator)
+        .output(z.boolean())
+        .mutation(async ({ ctx, input }) =>
+            sendGenericContractRequest(input, ctx.user.profile, ctx.domain)
+        ),
+
+    denyContractRequest: profileRoute
+        .meta({
+            requiredScope: 'contracts:write',
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/consent-flow-contracts/deny-request',
+                tags: ['Contracts'],
+                summary: 'Deny a pending contract request as its target',
+            },
+        })
+        .input(z.object({ contractUri: z.string() }))
+        .output(z.boolean())
+        .mutation(async ({ ctx, input }) => {
+            const contract = await getContractByUri(input.contractUri);
+            if (!contract)
+                throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
+            return decideGenericContractRequest({
+                contract,
+                targetProfileId: ctx.user.profile.profileId,
+                actorProfileId: ctx.user.profile.profileId,
+                status: 'denied',
+                domain: ctx.domain,
+            });
+        }),
+
     sendAiInsightsContractRequest: profileRoute
         .meta({
             openapi: {
@@ -1848,43 +1945,14 @@ export const contractsRouter = t.router({
             const { profile } = ctx.user;
             const { contractUri, targetProfileId, shareLink } = input;
 
-            const resolvedTargetProfileId = await getProfileIdFromString(
+            const { contract: contractByUri, target: targetProfile } = await resolveContractRequest(
+                contractUri,
                 targetProfileId,
-                ctx.domain
+                profile,
+                ctx.domain,
+                false
             );
-            if (!resolvedTargetProfileId) {
-                throw new TRPCError({ code: 'NOT_FOUND', message: 'Profile not found' });
-            }
-
-            const contractByUri = await getContractByUri(contractUri);
-
-            if (!contractByUri)
-                throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
-
-            const contract = await getConsentFlowContractById(contractByUri.id); // model instance
-
-            if (!contract) {
-                throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
-            }
-
-            const writers = await getWritersForContract(contractByUri);
-            const isAuthorized = writers.some(writer => writer.profileId === profile.profileId);
-
-            if (!isAuthorized) {
-                throw new TRPCError({
-                    code: 'UNAUTHORIZED',
-                    message: 'You do not have permission to send requests for this contract.',
-                });
-            }
-
-            const targetProfile = await getProfileByProfileId(resolvedTargetProfileId);
-
-            if (!targetProfile) {
-                throw new TRPCError({
-                    code: 'NOT_FOUND',
-                    message: 'Target profile not found.',
-                });
-            }
+            const resolvedTargetProfileId = targetProfile.profileId;
 
             try {
                 await upsertRequestedForRelationship(
@@ -1894,6 +1962,7 @@ export const contractsRouter = t.router({
                     null
                 );
             } catch (error) {
+                if (error instanceof TRPCError && error.code === 'CONFLICT') throw error;
                 throw new TRPCError({
                     code: 'BAD_REQUEST',
                     message: 'Unable to send request',
@@ -2026,9 +2095,9 @@ export const contractsRouter = t.router({
         )
         .output(
             z.array(
-                z.object({
+                ContractRequestFieldsValidator.extend({
                     profile: LCNProfileValidator,
-                    status: z.enum(['pending', 'accepted', 'denied']).nullable(),
+                    status: z.enum(['pending', 'accepted', 'denied', 'cancelled']).nullable(),
                     readStatus: z.enum(['unseen', 'seen']).nullable().optional(),
                 })
             )
@@ -2041,17 +2110,19 @@ export const contractsRouter = t.router({
 
             if (!contractByUri)
                 throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
-            const writers = await getWritersForContract(contractByUri);
-            const isAuthorized = writers.some(w => w.profileId === profile.profileId);
+            const isAuthorized = await canManageContractRequests(contractByUri, profile.profileId);
 
-            if (!isAuthorized) {
+            if (
+                !isAuthorized &&
+                !(await canReadContractData(contractByUri.id, profile.profileId))
+            ) {
                 throw new TRPCError({
                     code: 'UNAUTHORIZED',
                     message: 'You do not have permissions to view requests made for this contract.',
                 });
             }
 
-            const requests = await getRequestedForList(contractByUri.id);
+            const requests = await getRequestedForList(contractByUri.id, profile.profileId);
 
             return Promise.all(
                 requests.map(async request => {
@@ -2086,13 +2157,11 @@ export const contractsRouter = t.router({
             })
         )
         .output(
-            z
-                .object({
-                    profile: LCNProfileValidator,
-                    status: z.enum(['pending', 'accepted', 'denied']).nullable(),
-                    readStatus: z.enum(['unseen', 'seen']).nullable().optional(),
-                })
-                .nullable()
+            ContractRequestFieldsValidator.extend({
+                profile: LCNProfileValidator,
+                status: z.enum(['pending', 'accepted', 'denied', 'cancelled']).nullable(),
+                readStatus: z.enum(['unseen', 'seen']).nullable().optional(),
+            }).nullable()
         )
         .query(async ({ ctx, input }) => {
             const { profile } = ctx.user;
@@ -2119,10 +2188,9 @@ export const contractsRouter = t.router({
             const isCheckingOwnStatus = profile.profileId === resolvedTargetProfileId;
 
             if (!isCheckingOwnStatus) {
-                const writers = await getWritersForContract(contract);
-                const isAuthorized = writers.some(w => w.profileId === profile.profileId);
+                const isAuthorized = await canManageContractRequests(contract, profile.profileId);
 
-                if (!isAuthorized) {
+                if (!isAuthorized && !(await canReadContractData(contract.id, profile.profileId))) {
                     throw new TRPCError({
                         code: 'UNAUTHORIZED',
                         message:
@@ -2131,7 +2199,11 @@ export const contractsRouter = t.router({
                 }
             }
 
-            const requests = await getRequestedForForUser(contract.id, resolvedTargetProfileId);
+            const requests = await getRequestedForForUser(
+                contract.id,
+                resolvedTargetProfileId,
+                profile.profileId
+            );
 
             if (!requests?.[0]) return null;
 
@@ -2154,7 +2226,7 @@ export const contractsRouter = t.router({
                 tags: ['Contracts'],
                 summary: 'Marks a contract request as seen',
                 description:
-                    'Updates the read status of a contract request to "seen" for the specified target profile. Only contract writers are authorized to perform this action.',
+                    'Updates the read status of a contract request to "seen" for the specified target profile. Targets can mark their existing requests seen. Legacy writer behavior is retained for legacy requests.',
             },
         })
         .input(
@@ -2181,6 +2253,31 @@ export const contractsRouter = t.router({
             if (!contractByUri)
                 throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
 
+            const request = await getStoredContractRequest(
+                contractByUri.id,
+                resolvedTargetProfileId
+            );
+            if (request?.requestId) {
+                assertGenericRequestWriteScope(ctx.user.scope);
+                if (profile.profileId !== resolvedTargetProfileId)
+                    throw new TRPCError({
+                        code: 'UNAUTHORIZED',
+                        message: 'Only the target can mark this request seen',
+                    });
+                return markGenericContractRequestSeen(contractByUri.id, resolvedTargetProfileId);
+            }
+            if (profile.profileId === resolvedTargetProfileId) {
+                if (!request)
+                    throw new TRPCError({ code: 'NOT_FOUND', message: 'Request not found' });
+                await upsertRequestedForRelationship(
+                    contractByUri.id,
+                    resolvedTargetProfileId,
+                    undefined,
+                    'seen'
+                );
+                return true;
+            }
+
             const writers = await getWritersForContract(contractByUri);
             const isAuthorized = writers.some(w => w.profileId === profile.profileId);
 
@@ -2217,7 +2314,7 @@ export const contractsRouter = t.router({
                 tags: ['Contracts'],
                 summary: 'Cancels/removes a contract request',
                 description:
-                    'Removes a REQUESTED_FOR relationship, cancelling the request sent to the specified target profile. Only contract writers are authorized to perform this action.',
+                    'Cancels a pending generic request while retaining its history. Owner/writers, the requesting recipient, or the target may cancel. Legacy requests retain deletion behavior.',
             },
         })
         .input(
@@ -2244,6 +2341,21 @@ export const contractsRouter = t.router({
             if (!contractByUri)
                 throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
 
+            const request = await getStoredContractRequest(
+                contractByUri.id,
+                resolvedTargetProfileId
+            );
+            if (request?.requestId) {
+                assertGenericRequestWriteScope(ctx.user.scope);
+                return decideGenericContractRequest({
+                    contract: contractByUri,
+                    targetProfileId: resolvedTargetProfileId,
+                    actorProfileId: profile.profileId,
+                    status: 'cancelled',
+                    domain: ctx.domain,
+                });
+            }
+
             const isDenyingRequest = profile.profileId === resolvedTargetProfileId;
 
             if (!isDenyingRequest) {
@@ -2302,10 +2414,15 @@ export const contractsRouter = t.router({
         )
         .output(
             z.array(
-                z.object({
-                    contract: ConsentFlowContractValidator.extend({ uri: z.string() }),
+                ContractRequestFieldsValidator.extend({
+                    contract: ConsentFlowContractValidator.extend({
+                        uri: z.string(),
+                        name: z.string().optional(),
+                        image: z.string().optional(),
+                        description: z.string().optional(),
+                    }),
                     profile: LCNProfileValidator,
-                    status: z.enum(['pending', 'accepted', 'denied']).nullable(),
+                    status: z.enum(['pending', 'accepted', 'denied', 'cancelled']).nullable(),
                     readStatus: z.enum(['unseen', 'seen']).nullable().optional(),
                 })
             )
@@ -2345,7 +2462,10 @@ export const contractsRouter = t.router({
                             sanitizeProfileForTier(updatedProfile, 'authenticated')
                         ),
                         contract: {
-                            ...request.contract,
+                            ...inflateObject(request.contract).contract,
+                            name: request.contract.name,
+                            image: request.contract.image,
+                            description: request.contract.description,
                             uri: constructUri('contract', request.contract.id, ctx.domain),
                         },
                     };
@@ -2372,7 +2492,7 @@ export const contractsRouter = t.router({
         )
         .output(
             z.array(
-                z.object({
+                ContractRequestFieldsValidator.extend({
                     profile: LCNProfileValidator,
                     status: z.enum(['pending', 'accepted', 'denied']).nullable(),
                     readStatus: z.enum(['unseen', 'seen']).nullable().optional(),