@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/share-link-policy/production.ts

@@ -0,0 +1,108 @@
+import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { isProfileManaged } from '@accesslayer/profile/relationships/read';
+import type { ShareViewEligibilitySource } from '@accesslayer/share-link/types';
+import type { ShareLinkTransaction } from '@accesslayer/share-link/transaction';
+import {
+    isServiceProfileExemptFromGuardianship,
+    transformProfileId,
+} from '@helpers/profile.helpers';
+
+import { composeShareLinkPolicy } from './resolver';
+import type { CurrentShareLinkPolicy, ShareLinkOwnerAge, ShareLinkPolicySource } from './types';
+
+const ADULT_AGE = 18;
+
+/** Classify persisted human age without inventing a birthdate for service profiles. */
+export const ageFromPersistedProfile = (
+    profile: { dob?: unknown; type?: unknown } | null,
+    now: Date = new Date()
+): ShareLinkOwnerAge => {
+    if (!profile) return 'unknown';
+    if (profile.type === 'child') return 'minor';
+    if (typeof profile.dob !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(profile.dob)) {
+        return 'unknown';
+    }
+
+    const year = Number(profile.dob.slice(0, 4));
+    const month = Number(profile.dob.slice(5, 7));
+    const day = Number(profile.dob.slice(8, 10));
+    const birthday = new Date(Date.UTC(year, month - 1, day));
+    if (
+        birthday.getUTCFullYear() !== year ||
+        birthday.getUTCMonth() !== month - 1 ||
+        birthday.getUTCDate() !== day ||
+        birthday.getTime() > now.getTime()
+    ) {
+        return 'unknown';
+    }
+
+    const age =
+        now.getUTCFullYear() -
+        year -
+        (now.getUTCMonth() + 1 < month ||
+        (now.getUTCMonth() + 1 === month && now.getUTCDate() < day)
+            ? 1
+            : 0);
+
+    return age >= ADULT_AGE ? 'adult' : 'minor';
+};
+
+/**
+ * Personal profiles require a valid persisted birthdate for tracking. Service
+ * profiles are age-exempt, but an explicit child type always keeps protections.
+ */
+export const createProductionShareLinkPolicySource = (): ShareLinkPolicySource => ({
+    resolveOwner: async profileId => {
+        const profile = await getProfileByProfileId(profileId);
+        const isServiceProfile = isServiceProfileExemptFromGuardianship(
+            profile?.isServiceProfile,
+            profile?.type
+        );
+        const isManaged = await isProfileManaged(profileId);
+        return {
+            age: ageFromPersistedProfile(profile),
+            isServiceProfile,
+            isManaged,
+        };
+    },
+});
+
+/** Read current eligibility within the share lock; no request values or network I/O. */
+export const resolveCurrentShareLinkPolicy = async (
+    tx: ShareLinkTransaction,
+    ownerProfileId: string,
+    now: Date
+): Promise<CurrentShareLinkPolicy> => {
+    const result = await tx.run(
+        `MATCH (p:Profile {profileId: $profileId})
+         OPTIONAL MATCH (p)-[:MANAGED_BY]->(directManager:Profile)
+         OPTIONAL MATCH (manager:ProfileManager)-[:MANAGES]->(p)
+         RETURN p.dob AS dob, p.type AS profileType,
+                p.isServiceProfile AS isServiceProfile,
+                (directManager IS NOT NULL OR manager IS NOT NULL) AS isManaged
+         LIMIT 1`,
+        { profileId: transformProfileId(ownerProfileId) }
+    );
+    const record = result.records[0];
+    if (!record) return { ...composeShareLinkPolicy('unknown', true), isServiceProfile: false };
+
+    const profileType = record.get('profileType');
+    const isServiceProfile = isServiceProfileExemptFromGuardianship(
+        record.get('isServiceProfile'),
+        profileType
+    );
+    return {
+        ...composeShareLinkPolicy(
+            ageFromPersistedProfile({ dob: record.get('dob'), type: profileType }, now),
+            record.get('isManaged') !== false,
+            isServiceProfile
+        ),
+        isServiceProfile,
+    };
+};
+
+export const productionShareViewEligibilitySource: ShareViewEligibilitySource = {
+    isEligible: async (tx, input) =>
+        (await resolveCurrentShareLinkPolicy(tx, input.ownerProfileId, input.now))
+            .viewCountingEnabled,
+};

package/src/helpers/share-link-policy/resolver.ts

@@ -0,0 +1,113 @@
+import { DEFAULT_SHARE_LINK_POLICY } from './types';
+import type {
+    ShareLinkOwnerAge,
+    ShareLinkPolicyResolver,
+    ShareLinkPolicySnapshot,
+    ShareLinkPolicySource,
+} from './types';
+
+/**
+ * Pure policy decision table.
+ *
+ * - personal known minor, managed or unknown age => no views, 30 days
+ * - known unmanaged adult => views enabled, 365 days
+ * - service profile => views enabled without changing the age-derived expiry
+ */
+export const composeShareLinkPolicy = (
+    age: ShareLinkOwnerAge,
+    isManaged: boolean,
+    isServiceProfile = false
+): ShareLinkPolicySnapshot => {
+    // Service age exemption does not establish that the owner is an adult.
+    const isMinor = isServiceProfile
+        ? false
+        : age === 'minor'
+          ? true
+          : age === 'adult'
+            ? false
+            : null;
+    const policyResolved = isServiceProfile || age !== 'unknown';
+    const isUnmanagedAdult = age === 'adult' && !isManaged;
+
+    return {
+        isMinor,
+        policyResolved,
+        defaultExpiryDays: isUnmanagedAdult ? 365 : 30,
+        viewCountingEnabled: isServiceProfile || isUnmanagedAdult,
+    };
+};
+
+/**
+ * Build an injectable resolver over an authoritative source. Any source failure
+ * fails closed to the conservative default rather than assuming adult.
+ */
+export const createShareLinkPolicyResolver = (
+    source: ShareLinkPolicySource
+): ShareLinkPolicyResolver => ({
+    resolve: async (profileId: string): Promise<ShareLinkPolicySnapshot> => {
+        try {
+            const { age, isManaged, isServiceProfile } = await source.resolveOwner(profileId);
+
+            return composeShareLinkPolicy(age, isManaged, isServiceProfile);
+        } catch {
+            return DEFAULT_SHARE_LINK_POLICY;
+        }
+    },
+});
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Effective expiry: an explicit caller value (including explicit `null`) is
+ * preserved; only an omitted value receives the policy default. The default is
+ * derived from the policy at first reservation and then persisted, so a retry on
+ * a later clock replays the original value.
+ */
+export const resolveShareLinkExpiry = (
+    policy: ShareLinkPolicySnapshot,
+    expiresAt: string | null | undefined,
+    now: Date
+): string | null => {
+    if (expiresAt !== undefined) return expiresAt;
+
+    return new Date(now.getTime() + policy.defaultExpiryDays * DAY_MS).toISOString();
+};
+
+/**
+ * Conservatively merge a share's currently committed policy with the policy a
+ * reservation intends to apply at finalization.
+ *
+ * A reservation can be created before the owner's authoritative policy changes
+ * and then finalized later by a replay or a recovery worker. Applying the stale
+ * reservation policy verbatim could re-enable view counting for an owner who has
+ * since become managed/minor. The merge therefore only ever tightens:
+ *
+ * - view counting stays enabled only if BOTH policies allow it;
+ * - a known minor on either side is a minor, an unknown on either side is
+ *   unknown (never inferred adult);
+ * - the default expiry is the shorter of the two.
+ *
+ * Production finalization also rechecks current graph policy under the share
+ * lock before an explicit update can replace an old unknown snapshot.
+ */
+export const mergeShareLinkPolicyConservatively = (
+    current: ShareLinkPolicySnapshot,
+    incoming: ShareLinkPolicySnapshot
+): ShareLinkPolicySnapshot => {
+    const isMinor =
+        current.isMinor === true || incoming.isMinor === true
+            ? true
+            : current.isMinor === false && incoming.isMinor === false
+              ? false
+              : null;
+
+    return {
+        isMinor,
+        policyResolved: current.policyResolved && incoming.policyResolved,
+        defaultExpiryDays:
+            current.defaultExpiryDays <= incoming.defaultExpiryDays
+                ? current.defaultExpiryDays
+                : incoming.defaultExpiryDays,
+        viewCountingEnabled: current.viewCountingEnabled && incoming.viewCountingEnabled,
+    };
+};

package/src/helpers/share-link-policy/types.ts

@@ -0,0 +1,56 @@
+/**
+ * LC-2187 owner share-link policy types.
+ *
+ * Policy is always derived server-side from trusted persisted state; nothing in
+ * this module reads the request body. The conservative default (unknown age,
+ * 30-day expiry, no view counting) is what an unavailable or untrustworthy age
+ * source produces — absence of a manager is NOT evidence of adulthood.
+ */
+
+/** Result of consulting the authoritative server-side age source. */
+export type ShareLinkOwnerAge = 'adult' | 'minor' | 'unknown';
+
+/** Immutable policy snapshot persisted with the share under the write lock. */
+export type ShareLinkPolicySnapshot = {
+    /** `true` known minor, `false` known adult/service profile, `null` unknown. */
+    isMinor: boolean | null;
+    /** `true` when age is known or a persisted service profile is age-exempt. */
+    policyResolved: boolean;
+    defaultExpiryDays: 30 | 365;
+    viewCountingEnabled: boolean;
+};
+
+/** Fresh graph-local classification; never persisted or inferred from an old snapshot. */
+export type CurrentShareLinkPolicy = ShareLinkPolicySnapshot & {
+    isServiceProfile: boolean;
+};
+
+/**
+ * Authoritative server-side sources. Implementations must read persisted server
+ * state only; no request-derived value may be used as authority.
+ */
+export type ShareLinkPolicySource = {
+    /**
+     * Read age, service classification and management from persisted state.
+     * Service profiles may bypass tracking age checks; explicitly typed children
+     * must never be classified as service profiles here.
+     */
+    resolveOwner: (profileId: string) => Promise<{
+        age: ShareLinkOwnerAge;
+        isManaged: boolean;
+        isServiceProfile: boolean;
+    }>;
+};
+
+/** Injectable server-side policy resolver used by the coordinator. */
+export type ShareLinkPolicyResolver = {
+    resolve: (profileId: string) => Promise<ShareLinkPolicySnapshot>;
+};
+
+/** Fail-closed policy: no views, 30 days, age unknown. */
+export const DEFAULT_SHARE_LINK_POLICY: ShareLinkPolicySnapshot = Object.freeze({
+    isMinor: null,
+    policyResolved: false,
+    defaultExpiryDays: 30,
+    viewCountingEnabled: false,
+});

package/src/helpers/share-link-public/config.ts

@@ -0,0 +1,41 @@
+import {
+    hasShareLinkServiceTransportConfig,
+    resolveShareLinkServiceTransportConfig,
+} from '../share-link-maintenance/config';
+
+/**
+ * Available automatically once trusted service configuration is complete.
+ * Namespace, origin and audience come only from server configuration. Missing
+ * wiring is inactive; partial or invalid wiring fails closed.
+ */
+
+export type ShareLinkPublicApiConfigResolution =
+    | { status: 'disabled' }
+    | { status: 'invalid' }
+    | {
+          status: 'enabled';
+          namespace: string;
+          origin: string;
+          audience: string;
+          allowInsecureLoopback: boolean;
+      };
+
+export const resolveShareLinkPublicApiConfig = (
+    raw: unknown
+): ShareLinkPublicApiConfigResolution => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return { status: 'invalid' };
+
+    const source = raw as Record<string, unknown>;
+    if (!hasShareLinkServiceTransportConfig(source)) return { status: 'disabled' };
+
+    const transport = resolveShareLinkServiceTransportConfig(source);
+    if (transport.status !== 'enabled') return { status: 'invalid' };
+
+    return {
+        status: 'enabled',
+        namespace: transport.config.namespace,
+        origin: transport.config.origin,
+        audience: transport.config.audience,
+        allowInsecureLoopback: transport.config.allowInsecureLoopback,
+    };
+};

package/src/helpers/share-link-view-notification.ts

@@ -0,0 +1,18 @@
+import cache from '@cache';
+import { environment } from '@environment';
+
+const WINDOW_SECONDS = 10 * 60;
+
+/** One owner alert per share per window, claimed atomically across Brain workers. */
+export const claimShareViewNotification = async (
+    namespace: string,
+    shareId: string
+): Promise<boolean> => {
+    if (environment.NODE_ENV === 'production' && !cache.redis) return false;
+    const count = await cache.incr(
+        `share-link-view-notification:${namespace}:${shareId}`,
+        WINDOW_SECONDS
+    );
+    // A cache failure suppresses alerts, never privacy enforcement or view counts.
+    return count === 1;
+};

package/src/helpers/signingAuthority.helpers.ts

@@ -1,6 +1,10 @@
 import { environment } from '@environment';
 import { Agent, fetch as undiciFetch, type Response as UndiciResponse } from 'undici';
-import { getDidWebLearnCard, getLearnCard } from '@helpers/learnCard.helpers';
+import {
+    createDagJweForRecipients,
+    getDidWebLearnCard,
+    getLearnCard,
+} from '@helpers/learnCard.helpers';
 import { getDidWeb } from '@helpers/did.helpers';
 import { VCValidator, JWEValidator } from '@learncard/types';
 import type { UnsignedVC, VC, JWE } from '@learncard/types';
@@ -113,9 +117,17 @@ const getSaAgent = (): Agent => {
     return _saAgent;
 };
 
-const _mockIssueCredentialWithSigningAuthority = async (credential: UnsignedVC): Promise<VC> => {
+const _mockIssueCredentialWithSigningAuthority = async (
+    credential: UnsignedVC,
+    recipients?: string[]
+): Promise<VC | JWE> => {
     const learnCard = await getLearnCard();
-    return learnCard.invoke.issueCredential({ ...credential, issuer: learnCard.id.did() });
+    const signedCredential = await learnCard.invoke.issueCredential({
+        ...credential,
+        issuer: learnCard.id.did(),
+    });
+
+    return recipients ? createDagJweForRecipients(signedCredential, recipients) : signedCredential;
 };
 
 export async function issueCredentialWithSigningAuthority(
@@ -151,6 +163,10 @@ export async function issueCredentialWithSigningAuthority(
             retryable: false,
         });
     }
+    // The validation above excludes undefined subject IDs on the encrypted path.
+    const encryptionRecipients = encrypt
+        ? [...new Set([...(subjectIds as string[]), ownerDid, ...additionalEncryptionRecipients])]
+        : undefined;
     const credentialToIssue = appendCredentialStatus
         ? await appendBitstringStatusListEntries(credential, ownerProfile.profileId, domain)
         : credential;
@@ -177,7 +193,8 @@ export async function issueCredentialWithSigningAuthority(
             try {
                 if (IS_TEST_ENVIRONMENT) {
                     return await _mockIssueCredentialWithSigningAuthority(
-                        JSON.parse(serializedCredential)
+                        JSON.parse(serializedCredential),
+                        encryptionRecipients
                     );
                 }
 
@@ -189,16 +206,8 @@ export async function issueCredentialWithSigningAuthority(
                 perf.mark('initDid');
 
                 // Brain authenticates the request but must not be able to decrypt the response.
-                const encryption = encrypt
-                    ? {
-                          recipients: [
-                              ...new Set([
-                                  ...subjectIds,
-                                  ownerDid,
-                                  ...additionalEncryptionRecipients,
-                              ]),
-                          ],
-                      }
+                const encryption = encryptionRecipients
+                    ? { recipients: encryptionRecipients }
                     : undefined;
 
                 const didJwt = await traceCrypto('getDidAuthVp', () =>

package/src/helpers/smartResume.helpers.ts

@@ -0,0 +1,123 @@
+import { environment } from '@environment';
+import { ConsentFlowTermsValidator, type ConsentFlowTerms } from '@learncard/types';
+import { resolveUri } from '@helpers/uri.helpers';
+
+/** Publish only the terms returned by the locked consent/publication claim. */
+export const uploadSmartResume = async (
+    terms: ConsentFlowTerms,
+    did: string,
+    recipientToken: string
+): Promise<string | undefined> => {
+    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',
+        signal: AbortSignal.timeout(30_000),
+        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 => {
+        if (!res.ok) throw new Error(`SmartResume token request failed (${res.status})`);
+        return 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 => {
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            try {
+                return await Promise.race([
+                    resolveUri(uri),
+                    new Promise<never>((_, reject) => {
+                        timer = setTimeout(
+                            () => reject(new Error('Credential resolution timed out')),
+                            30_000
+                        );
+                    }),
+                ]);
+            } finally {
+                clearTimeout(timer);
+            }
+        })
+    );
+
+    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: did,
+            givenName: name && name !== 'Anonymous' ? name : '',
+            familyName: '', // this is necessary in order for givenName to be respected
+            email: email && email !== 'anonymous@hidden.com' ? email : '',
+        },
+        credentials: transformedCredentials,
+    });
+
+    const response = await fetch(`${srUrl}api/v1/credentials`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(30_000),
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            'Content-Type': 'application/json',
+        },
+        body,
+    });
+
+    if (!response.ok) {
+        throw new Error(`SmartResume upload failed (${response.status})`);
+    }
+
+    const result = (await response.json()) as { redirect_url?: string };
+    return result.redirect_url;
+};

package/src/models/AppManifestVersion.ts

@@ -0,0 +1,43 @@
+import { ModelFactory, ModelRelatedNodesI, NeogmaInstance } from 'neogma';
+
+import { neogma } from '@instance';
+
+import { FlatAppManifestVersionType } from 'types/app-manifest';
+import { Integration, IntegrationInstance } from './Integration';
+import { AppStoreListing, AppStoreListingInstance } from './AppStoreListing';
+
+export type AppManifestVersionRelationships = {
+    integration: ModelRelatedNodesI<typeof Integration, IntegrationInstance>;
+    listing: ModelRelatedNodesI<typeof AppStoreListing, AppStoreListingInstance>;
+};
+
+export type AppManifestVersionInstance = NeogmaInstance<
+    FlatAppManifestVersionType,
+    AppManifestVersionRelationships
+>;
+
+export const AppManifestVersion = ModelFactory<
+    FlatAppManifestVersionType,
+    AppManifestVersionRelationships
+>(
+    {
+        label: 'AppManifestVersion',
+        schema: {
+            id: { type: 'string', required: true, uniqueItems: true },
+            version: { type: 'number', required: true },
+            manifestHash: { type: 'string', required: true },
+            manifestJson: { type: 'string', required: true },
+            status: { type: 'string', enum: ['draft', 'active', 'superseded'], required: true },
+            createdAt: { type: 'string', required: true },
+            activatedAt: { type: 'string', required: false },
+        },
+        relationships: {
+            integration: { model: Integration, direction: 'in', name: 'HAS_MANIFEST_VERSION' },
+            listing: { model: AppStoreListing, direction: 'in', name: 'USES_MANIFEST_VERSION' },
+        },
+        primaryKeyField: 'id',
+    },
+    neogma
+);
+
+export default AppManifestVersion;

package/src/models/AppStoreListing.ts

@@ -6,13 +6,16 @@ import { Integration, IntegrationInstance } from './Integration';
 import { Profile, ProfileInstance } from './Profile';
 import { Boost, BoostInstance } from './Boost';
 import { Credential, CredentialInstance } from './Credential';
+import { ConsentFlowContract, ConsentFlowInstance } from './ConsentFlowContract';
 import { SigningAuthority, SigningAuthorityInstance } from './SigningAuthority';
+import type { AppManifestVersion, AppManifestVersionInstance } from './AppManifestVersion';
 import {
     FlatAppStoreListingType,
     AppListingStatus,
     LaunchType,
     PromotionLevel,
     AgeRating,
+    PendingListingUpdateStatus,
 } from 'types/app-store-listing';
 
 export type AppStoreListingRelationships = {
@@ -73,6 +76,13 @@ export type AppStoreListingRelationships = {
         { name: string; did: string; isPrimary?: boolean },
         { name: string; did: string; isPrimary?: boolean }
     >;
+    hasConsentContract: ModelRelatedNodesI<
+        typeof ConsentFlowContract,
+        ConsentFlowInstance,
+        { scopeHash: string; createdAt: string },
+        { scopeHash: string; createdAt: string }
+    >;
+    usesManifestVersion: ModelRelatedNodesI<typeof AppManifestVersion, AppManifestVersionInstance>;
 };
 
 export type AppStoreListingInstance = NeogmaInstance<
@@ -114,6 +124,13 @@ export const AppStoreListing = ModelFactory<FlatAppStoreListingType, AppStoreLis
             min_age: { type: 'number', required: false },
             age_rating: { type: 'string', enum: AgeRating.options, required: false },
             contact_email: { type: 'string', required: false },
+            pending_update_json: { type: 'string', required: false },
+            pending_update_status: {
+                type: 'string',
+                enum: PendingListingUpdateStatus.options,
+                required: false,
+            },
+            pending_update_submitted_at: { type: 'string', required: false },
         } as any,
         relationships: {
             publishedBy: { model: Integration, direction: 'in', name: 'PUBLISHES_LISTING' },
@@ -204,6 +221,21 @@ export const AppStoreListing = ModelFactory<FlatAppStoreListingType, AppStoreLis
                     },
                 },
             },
+            hasConsentContract: {
+                model: ConsentFlowContract,
+                direction: 'out',
+                name: 'HAS_CONSENT_CONTRACT',
+                properties: {
+                    scopeHash: {
+                        property: 'scopeHash',
+                        schema: { type: 'string', required: true },
+                    },
+                    createdAt: {
+                        property: 'createdAt',
+                        schema: { type: 'string', required: true },
+                    },
+                },
+            },
         },
         primaryKeyField: 'listing_id',
     },