@learncard/network-brain-service 3.19.0 → 4.0.0

package/test/share-link-owner-runtime.unit.spec.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createRetryableLazyInitializer } from '@helpers/share-link-owner/lazy-initializer';
+import { mergeShareLinkPolicyConservatively } from '@helpers/share-link-policy/resolver';
+import { DEFAULT_SHARE_LINK_POLICY } from '@helpers/share-link-policy/types';
+import type { ShareLinkPolicySnapshot } from '@helpers/share-link-policy/types';
+
+const adultPolicy: ShareLinkPolicySnapshot = {
+    isMinor: false,
+    policyResolved: true,
+    defaultExpiryDays: 365,
+    viewCountingEnabled: true,
+};
+
+describe('createRetryableLazyInitializer', () => {
+    it('shares one in-flight build across concurrent callers', async () => {
+        const build = vi.fn(async () => {
+            await new Promise(resolve => setTimeout(resolve, 5));
+            return { ready: true };
+        });
+        const initialize = createRetryableLazyInitializer(build);
+
+        const [first, second] = await Promise.all([initialize(), initialize()]);
+
+        expect(build).toHaveBeenCalledTimes(1);
+        expect(first).toEqual({ ready: true });
+        expect(second).toBe(first);
+    });
+
+    it('retries after a transient failure and caches the later success', async () => {
+        const build = vi
+            .fn<() => Promise<string>>()
+            .mockRejectedValueOnce(new Error('constraint setup failed'))
+            .mockResolvedValue('ready');
+        const initialize = createRetryableLazyInitializer(build);
+
+        await expect(initialize()).rejects.toThrow('constraint setup failed');
+        await expect(initialize()).resolves.toBe('ready');
+        await expect(initialize()).resolves.toBe('ready');
+
+        // The failed attempt is never cached; the successful one is.
+        expect(build).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not poison the cache when concurrent callers fail', async () => {
+        const build = vi
+            .fn<() => Promise<number>>()
+            .mockRejectedValueOnce(new Error('down'))
+            .mockResolvedValue(7);
+        const initialize = createRetryableLazyInitializer(build);
+
+        const firstRound = await Promise.allSettled([initialize(), initialize()]);
+        expect(firstRound.every(settled => settled.status === 'rejected')).toBe(true);
+        // The two concurrent callers shared one failed attempt.
+        expect(build).toHaveBeenCalledTimes(1);
+
+        await expect(initialize()).resolves.toBe(7);
+    });
+});
+
+describe('mergeShareLinkPolicyConservatively', () => {
+    it('never re-enables view counting from a stale permissive reservation', () => {
+        const managedAdult: ShareLinkPolicySnapshot = {
+            isMinor: false,
+            policyResolved: true,
+            defaultExpiryDays: 30,
+            viewCountingEnabled: false,
+        };
+
+        expect(mergeShareLinkPolicyConservatively(managedAdult, adultPolicy)).toEqual({
+            isMinor: false,
+            policyResolved: true,
+            defaultExpiryDays: 30,
+            viewCountingEnabled: false,
+        });
+    });
+
+    it('applies a new restrictive reservation over a permissive committed policy', () => {
+        const merged = mergeShareLinkPolicyConservatively(adultPolicy, DEFAULT_SHARE_LINK_POLICY);
+
+        expect(merged.viewCountingEnabled).toBe(false);
+        expect(merged.policyResolved).toBe(false);
+        expect(merged.isMinor).toBeNull();
+        expect(merged.defaultExpiryDays).toBe(30);
+    });
+
+    it('treats a known minor on either side as a minor', () => {
+        const minor: ShareLinkPolicySnapshot = {
+            isMinor: true,
+            policyResolved: true,
+            defaultExpiryDays: 30,
+            viewCountingEnabled: false,
+        };
+
+        expect(mergeShareLinkPolicyConservatively(adultPolicy, minor).isMinor).toBe(true);
+        expect(mergeShareLinkPolicyConservatively(minor, adultPolicy).isMinor).toBe(true);
+    });
+
+    it('keeps both-adult known and both-resolved only', () => {
+        expect(mergeShareLinkPolicyConservatively(adultPolicy, adultPolicy)).toEqual(adultPolicy);
+    });
+});

package/test/share-link-passcode.unit.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    hashSharePasscode,
+    SharePasscodeCapacityError,
+    verifySharePasscode,
+} from '../src/helpers/share-link-passcode';
+
+describe('share-link passcodes', () => {
+    it('stores an Argon2id PHC hash and verifies without retaining plaintext', async () => {
+        const passcode = 'correct horse battery staple';
+        const hash = await hashSharePasscode(passcode);
+
+        expect(hash).toMatch(/^\$argon2id\$/);
+        expect(hash).not.toContain(passcode);
+        await expect(verifySharePasscode(hash, passcode)).resolves.toBe(true);
+        await expect(verifySharePasscode(hash, 'wrong passcode')).resolves.toBe(false);
+    });
+
+    it('rejects excess concurrent verifications without starting another Argon2 job', async () => {
+        const hash = await hashSharePasscode('2468');
+        const inFlight = Array.from({ length: 4 }, () => verifySharePasscode(hash, '2468'));
+        await expect(verifySharePasscode(hash, '2468')).rejects.toBeInstanceOf(
+            SharePasscodeCapacityError
+        );
+        await expect(Promise.all(inFlight)).resolves.toEqual([true, true, true, true]);
+        await expect(verifySharePasscode(hash, '2468')).resolves.toBe(true);
+    });
+});

package/test/share-link-policy.unit.spec.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+    composeShareLinkPolicy,
+    createShareLinkPolicyResolver,
+    resolveShareLinkExpiry,
+} from '@helpers/share-link-policy/resolver';
+import { DEFAULT_SHARE_LINK_POLICY } from '@helpers/share-link-policy/types';
+import { resolveShareLinkOwnerApiConfig } from '@helpers/share-link-owner/config';
+
+describe('share-link policy decision table', () => {
+    it('gives a known unmanaged adult 365 days and view counting', () => {
+        expect(composeShareLinkPolicy('adult', false)).toEqual({
+            isMinor: false,
+            policyResolved: true,
+            defaultExpiryDays: 365,
+            viewCountingEnabled: true,
+        });
+    });
+
+    it('treats a managed adult as no-views/30-days', () => {
+        expect(composeShareLinkPolicy('adult', true)).toEqual({
+            isMinor: false,
+            policyResolved: true,
+            defaultExpiryDays: 30,
+            viewCountingEnabled: false,
+        });
+    });
+
+    it('treats a known minor as no-views/30-days regardless of management', () => {
+        for (const managed of [true, false]) {
+            expect(composeShareLinkPolicy('minor', managed)).toEqual({
+                isMinor: true,
+                policyResolved: true,
+                defaultExpiryDays: 30,
+                viewCountingEnabled: false,
+            });
+        }
+    });
+
+    it('treats unknown age as no-views/30-days and never infers adult from absence of a manager', () => {
+        expect(composeShareLinkPolicy('unknown', false)).toEqual(DEFAULT_SHARE_LINK_POLICY);
+        expect(composeShareLinkPolicy('unknown', true)).toEqual(DEFAULT_SHARE_LINK_POLICY);
+    });
+
+    it.each(['unknown', 'minor'] as const)(
+        'allows service tracking with %s age without changing the expiry default',
+        age => {
+            expect(composeShareLinkPolicy(age, true, true)).toEqual({
+                isMinor: false,
+                policyResolved: true,
+                defaultExpiryDays: 30,
+                viewCountingEnabled: true,
+            });
+        }
+    );
+});
+
+describe('createShareLinkPolicyResolver', () => {
+    it('fails closed to the conservative default when a source throws', async () => {
+        const resolver = createShareLinkPolicyResolver({
+            resolveOwner: vi.fn().mockRejectedValue(new Error('profile source down')),
+        });
+
+        await expect(resolver.resolve('owner-1')).resolves.toEqual(DEFAULT_SHARE_LINK_POLICY);
+    });
+
+    it('never returns an adult policy when the age source is unknown', async () => {
+        const resolver = createShareLinkPolicyResolver({
+            resolveOwner: vi.fn().mockResolvedValue({
+                age: 'unknown',
+                isManaged: false,
+                isServiceProfile: false,
+            }),
+        });
+
+        const policy = await resolver.resolve('owner-1');
+        expect(policy.viewCountingEnabled).toBe(false);
+        expect(policy.defaultExpiryDays).toBe(30);
+    });
+});
+
+describe('resolveShareLinkExpiry', () => {
+    const now = new Date('2026-09-21T00:00:00.000Z');
+
+    it('derives the policy default only when expiresAt is omitted', () => {
+        expect(resolveShareLinkExpiry(DEFAULT_SHARE_LINK_POLICY, undefined, now)).toBe(
+            '2026-10-21T00:00:00.000Z'
+        );
+        expect(resolveShareLinkExpiry(composeShareLinkPolicy('adult', false), undefined, now)).toBe(
+            '2027-09-21T00:00:00.000Z'
+        );
+    });
+
+    it('preserves an explicit null (no expiry) and an explicit date', () => {
+        expect(resolveShareLinkExpiry(DEFAULT_SHARE_LINK_POLICY, null, now)).toBeNull();
+        expect(
+            resolveShareLinkExpiry(DEFAULT_SHARE_LINK_POLICY, '2030-01-01T00:00:00.000Z', now)
+        ).toBe('2030-01-01T00:00:00.000Z');
+    });
+});
+
+describe('resolveShareLinkOwnerApiConfig (fail closed)', () => {
+    const enabledRaw = (overrides: Record<string, unknown> = {}) => ({
+        SHARE_LINK_MAINTENANCE_NAMESPACE: 'deployment-ns',
+        SHARE_LINK_MAINTENANCE_ORIGIN: 'https://learncloud.test',
+        SHARE_LINK_MAINTENANCE_AUDIENCE: 'did:web:brain.test',
+        ...overrides,
+    });
+
+    it('does no setup without service wiring', () => {
+        expect(resolveShareLinkOwnerApiConfig({})).toEqual({ status: 'disabled' });
+        expect(resolveShareLinkOwnerApiConfig({ SHARE_LINK_MAINTENANCE_NAMESPACE: '' })).toEqual({
+            status: 'disabled',
+        });
+    });
+
+    it('rejects incomplete service-client configuration', () => {
+        expect(resolveShareLinkOwnerApiConfig({ SHARE_LINK_MAINTENANCE_NAMESPACE: 'ns' })).toEqual({
+            status: 'invalid',
+        });
+    });
+
+    it('is invalid when the owner namespace disagrees with the service client namespace', () => {
+        expect(
+            resolveShareLinkOwnerApiConfig(
+                enabledRaw({ SHARE_LINK_OWNER_API_NAMESPACE: 'other-ns' })
+            )
+        ).toEqual({ status: 'invalid' });
+    });
+
+    it('ignores the retired owner rollout flag', () => {
+        expect(
+            resolveShareLinkOwnerApiConfig(enabledRaw({ SHARE_LINK_OWNER_API_ENABLED: 'false' }))
+        ).toMatchObject({ status: 'enabled', namespace: 'deployment-ns' });
+    });
+
+    it('enables with the trusted service-client namespace when it matches', () => {
+        expect(resolveShareLinkOwnerApiConfig(enabledRaw())).toMatchObject({
+            status: 'enabled',
+            namespace: 'deployment-ns',
+        });
+        expect(
+            resolveShareLinkOwnerApiConfig(
+                enabledRaw({ SHARE_LINK_OWNER_API_NAMESPACE: 'deployment-ns' })
+            )
+        ).toMatchObject({ status: 'enabled', namespace: 'deployment-ns' });
+    });
+});

package/test/share-link-presentation-metadata.unit.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    assertPresentationMetadataRecipient,
+    PresentationMetadataValidator,
+} from '../src/helpers/presentation-metadata';
+
+const metadata = {
+    type: 'learncard.share-link.v1',
+    shareId: 'A'.repeat(22),
+    title: 'Career highlights',
+    note: 'Selected credentials',
+    sharer: { profileId: 'alex', displayName: 'Alex' },
+};
+
+describe('saved share presentation metadata', () => {
+    it('accepts bounded self-save labels and preserves generic callers', () => {
+        expect(PresentationMetadataValidator.safeParse(metadata).success).toBe(true);
+        expect(() => assertPresentationMetadataRecipient(metadata, 'me', 'me')).not.toThrow();
+        expect(PresentationMetadataValidator.safeParse({ category: 'course' }).success).toBe(true);
+    });
+
+    it('rejects spoofed labels sent to another recipient', () => {
+        expect(() =>
+            assertPresentationMetadataRecipient(metadata, 'attacker', 'recipient')
+        ).toThrow();
+    });
+
+    it('rejects oversized, malformed or remote-avatar metadata', () => {
+        expect(
+            PresentationMetadataValidator.safeParse({ ...metadata, title: 'x'.repeat(121) }).success
+        ).toBe(false);
+        expect(
+            PresentationMetadataValidator.safeParse({
+                ...metadata,
+                avatar: 'https://attacker/pixel.png',
+            }).success
+        ).toBe(false);
+        expect(
+            PresentationMetadataValidator.safeParse({
+                ...metadata,
+                sharer: { ...metadata.sharer, avatar: 'https://attacker/pixel.png' },
+            }).success
+        ).toBe(false);
+        expect(PresentationMetadataValidator.safeParse({ other: 'x'.repeat(4097) }).success).toBe(
+            false
+        );
+    });
+});

package/test/share-link-production-policy.unit.spec.ts

@@ -0,0 +1,126 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@accesslayer/profile/read', () => ({ getProfileByProfileId: vi.fn() }));
+vi.mock('@accesslayer/profile/relationships/read', () => ({ isProfileManaged: vi.fn() }));
+vi.mock('@helpers/profile.helpers', () => ({
+    transformProfileId: (id: string) => id.toLowerCase(),
+    isServiceProfileExemptFromGuardianship: (isServiceProfile: unknown, type: unknown) =>
+        isServiceProfile === true && type !== 'child',
+}));
+
+import {
+    ageFromPersistedProfile,
+    createProductionShareLinkPolicySource,
+    productionShareViewEligibilitySource,
+    resolveCurrentShareLinkPolicy,
+} from '@helpers/share-link-policy/production';
+import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { isProfileManaged } from '@accesslayer/profile/relationships/read';
+import type { ShareLinkTransaction } from '@accesslayer/share-link/transaction';
+import { createShareLinkPolicyResolver } from '@helpers/share-link-policy/resolver';
+
+const NOW = new Date('2026-09-25T12:00:00.000Z');
+
+const transactionWith = (profile?: {
+    dob: unknown;
+    type: unknown;
+    isManaged: unknown;
+    isServiceProfile?: unknown;
+}): ShareLinkTransaction => ({
+    run: vi.fn(async () => ({
+        records: profile
+            ? [
+                  {
+                      get: (key: string) =>
+                          key === 'profileType'
+                              ? profile.type
+                              : profile[key as keyof typeof profile],
+                  },
+              ]
+            : [],
+    })),
+});
+
+describe('production share-link age policy', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+
+    it('requires a valid birthdate and an eighteenth birthday before allowing adulthood', () => {
+        expect(ageFromPersistedProfile({ dob: '2008-09-25' }, NOW)).toBe('adult');
+        expect(ageFromPersistedProfile({ dob: '2008-09-26' }, NOW)).toBe('minor');
+        expect(ageFromPersistedProfile({ dob: '2010-02-29' }, NOW)).toBe('unknown');
+        expect(ageFromPersistedProfile({ dob: 'not-a-date' }, NOW)).toBe('unknown');
+        expect(ageFromPersistedProfile({ dob: '2030-01-01' }, NOW)).toBe('unknown');
+        expect(ageFromPersistedProfile({ dob: '1990-01-01', type: 'child' }, NOW)).toBe('minor');
+        expect(ageFromPersistedProfile(null, NOW)).toBe('unknown');
+    });
+
+    it('uses the persisted profile instead of inferring adulthood from no manager', async () => {
+        vi.mocked(getProfileByProfileId).mockResolvedValueOnce({ dob: '1990-01-01' } as never);
+        vi.mocked(isProfileManaged).mockResolvedValueOnce(false);
+
+        const resolver = createShareLinkPolicyResolver(createProductionShareLinkPolicySource());
+        expect((await resolver.resolve('owner')).viewCountingEnabled).toBe(true);
+    });
+    it.each([
+        { dob: undefined, type: undefined, isServiceProfile: true, eligible: true },
+        { dob: 'not-a-date', type: undefined, isServiceProfile: true, eligible: true },
+        { dob: '2020-01-01', type: undefined, isServiceProfile: true, eligible: true },
+        { dob: '1990-01-01', type: undefined, isServiceProfile: true, eligible: true },
+        { dob: undefined, type: 'child', isServiceProfile: true, eligible: false },
+        { dob: undefined, type: undefined, isServiceProfile: 'true', eligible: false },
+    ])(
+        'uses persisted service classification in preflight and locked policy: $dob / $type / $isServiceProfile',
+        async ({ dob, type, isServiceProfile, eligible }) => {
+            vi.mocked(getProfileByProfileId).mockResolvedValue({
+                dob,
+                type,
+                isServiceProfile,
+            } as never);
+            vi.mocked(isProfileManaged).mockResolvedValue(true);
+            const resolver = createShareLinkPolicyResolver(createProductionShareLinkPolicySource());
+            const preflight = await resolver.resolve('owner');
+            const locked = await resolveCurrentShareLinkPolicy(
+                transactionWith({ dob, type, isServiceProfile, isManaged: true }),
+                'owner',
+                NOW
+            );
+            expect(preflight.viewCountingEnabled).toBe(eligible);
+            expect(locked).toEqual({ ...preflight, isServiceProfile: eligible });
+            expect(locked.defaultExpiryDays).toBe(30);
+        }
+    );
+
+    it('rechecks persisted age and management inside the receipt transaction', async () => {
+        const adult = transactionWith({ dob: '1990-01-01', type: null, isManaged: false });
+        const managed = transactionWith({ dob: '1990-01-01', type: null, isManaged: true });
+        const unknown = transactionWith();
+        const managedService = transactionWith({
+            dob: null,
+            type: null,
+            isManaged: true,
+            isServiceProfile: true,
+        });
+        const input = {
+            namespace: 'test',
+            ownerProfileId: 'OWNER',
+            shareId: 'share',
+            shareVersion: 1,
+            contentVersion: 1,
+            objectRef: 'object',
+            operationId: 'operation',
+            now: NOW,
+        };
+
+        expect(await productionShareViewEligibilitySource.isEligible(adult, input)).toBe(true);
+        expect(await productionShareViewEligibilitySource.isEligible(managed, input)).toBe(false);
+        expect(await productionShareViewEligibilitySource.isEligible(unknown, input)).toBe(false);
+        expect(await productionShareViewEligibilitySource.isEligible(managedService, input)).toBe(
+            true
+        );
+        expect(
+            (await resolveCurrentShareLinkPolicy(unknown, 'owner', NOW)).viewCountingEnabled
+        ).toBe(false);
+    });
+});

package/test/share-link-public-config.unit.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { resolveShareLinkPublicApiConfig } from '../src/helpers/share-link-public/config';
+
+const configuredEnv = {
+    SHARE_LINK_MAINTENANCE_NAMESPACE: 'deployment-ns',
+    SHARE_LINK_MAINTENANCE_ORIGIN: 'https://learncloud.example',
+    SHARE_LINK_MAINTENANCE_AUDIENCE: 'did:web:learncloud.example',
+};
+
+describe('resolveShareLinkPublicApiConfig', () => {
+    it('does no setup without service wiring', () => {
+        expect(resolveShareLinkPublicApiConfig({})).toEqual({ status: 'disabled' });
+        expect(
+            resolveShareLinkPublicApiConfig({
+                SHARE_LINK_MAINTENANCE_NAMESPACE: '',
+                SHARE_LINK_MAINTENANCE_ORIGIN: '',
+                SHARE_LINK_MAINTENANCE_AUDIENCE: '',
+            })
+        ).toEqual({ status: 'disabled' });
+    });
+    it('rejects partial or malformed transport', () => {
+        expect(resolveShareLinkPublicApiConfig({ SHARE_LINK_MAINTENANCE_NAMESPACE: 'ns' })).toEqual(
+            { status: 'invalid' }
+        );
+        expect(
+            resolveShareLinkPublicApiConfig({
+                ...configuredEnv,
+                SHARE_LINK_MAINTENANCE_ORIGIN: 'not-a-url',
+            })
+        ).toEqual({ status: 'invalid' });
+        expect(
+            resolveShareLinkPublicApiConfig({
+                ...configuredEnv,
+                SHARE_LINK_MAINTENANCE_NAMESPACE: '',
+            })
+        ).toEqual({ status: 'invalid' });
+    });
+    it('is available with valid service wiring and no rollout flag', () => {
+        expect(resolveShareLinkPublicApiConfig(configuredEnv)).toEqual({
+            status: 'enabled',
+            namespace: 'deployment-ns',
+            origin: 'https://learncloud.example',
+            audience: 'did:web:learncloud.example',
+            allowInsecureLoopback: false,
+        });
+    });
+    it('ignores a retired rollout flag rather than disabling configured APIs', () => {
+        expect(
+            resolveShareLinkPublicApiConfig({
+                ...configuredEnv,
+                SHARE_LINK_PUBLIC_API_ENABLED: 'false',
+            }).status
+        ).toBe('enabled');
+    });
+    it('never echoes malformed values', () => {
+        expect(
+            JSON.stringify(
+                resolveShareLinkPublicApiConfig({
+                    SHARE_LINK_MAINTENANCE_NAMESPACE: 'secret namespace',
+                })
+            )
+        ).not.toContain('secret namespace');
+    });
+});