@learncard/network-brain-service 3.19.0 → 4.0.0

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

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+    canonicalizeJson,
+    computeCleanupBackoffMs,
+    computeLeaseExpiry,
+    computeShareLinkRequestHash,
+    getShareLinkRequestHashSecret,
+    isLeaseActive,
+} from '@helpers/share-link-lifecycle';
+
+const mocks = vi.hoisted(() => ({
+    run: vi.fn(),
+}));
+
+vi.mock('@instance', () => ({
+    neogma: {
+        queryRunner: {
+            run: mocks.run,
+        },
+    },
+}));
+
+beforeEach(() => {
+    vi.resetModules();
+    mocks.run.mockReset();
+});
+
+describe('share-link canonical request hash', () => {
+    it('is stable across object key insertion order', () => {
+        const first = computeShareLinkRequestHash('update', {
+            id: 'share-id',
+            envelope: { iv: 'nonce', ct: 'ciphertext' },
+            ownerEncryptedRecovery: { protected: 'header', ciphertext: 'recovery' },
+        });
+        const second = computeShareLinkRequestHash('update', {
+            ownerEncryptedRecovery: { ciphertext: 'recovery', protected: 'header' },
+            envelope: { ct: 'ciphertext', iv: 'nonce' },
+            id: 'share-id',
+        });
+
+        expect(first).toBe(second);
+    });
+
+    it('covers the encrypted owner recovery', () => {
+        const first = computeShareLinkRequestHash('create', {
+            id: 'share-id',
+            ownerEncryptedRecovery: { ciphertext: 'recovery-a' },
+        });
+        const second = computeShareLinkRequestHash('create', {
+            id: 'share-id',
+            ownerEncryptedRecovery: { ciphertext: 'recovery-b' },
+        });
+
+        expect(first).not.toBe(second);
+    });
+
+    it('binds the operation kind', () => {
+        const payload = { id: 'share-id', title: 'Shared' };
+
+        expect(computeShareLinkRequestHash('create', payload)).not.toBe(
+            computeShareLinkRequestHash('update', payload)
+        );
+    });
+
+    it('excludes the client request id that forms the operation key', () => {
+        const first = computeShareLinkRequestHash('create', {
+            id: 'share-id',
+            clientRequestId: '11111111-1111-4111-8111-111111111111',
+        });
+        const second = computeShareLinkRequestHash('create', {
+            id: 'share-id',
+            clientRequestId: '22222222-2222-4222-8222-222222222222',
+        });
+
+        expect(first).toBe(second);
+    });
+
+    it('binds different passcodes while making the stored fingerprint secret-keyed', () => {
+        const request = { id: 'share-id', title: 'Shared', passcode: '1234' };
+        const first = computeShareLinkRequestHash('create', request);
+        expect(computeShareLinkRequestHash('create', request)).toBe(first);
+        expect(computeShareLinkRequestHash('create', { ...request, passcode: '1235' })).not.toBe(
+            first
+        );
+        expect(first).not.toBe(
+            createHash('sha256')
+                .update(canonicalizeJson({ opKind: 'create', request }))
+                .digest('hex')
+        );
+    });
+
+    it('keeps the existing fingerprint for unprotected in-flight retries', () => {
+        const request = { id: 'share-id', title: 'Shared' };
+        expect(computeShareLinkRequestHash('create', request)).toBe(
+            createHash('sha256')
+                .update(canonicalizeJson({ opKind: 'create', request }))
+                .digest('hex')
+        );
+    });
+
+    it('requires an independently provisioned secret outside tests', () => {
+        vi.stubEnv('NODE_ENV', 'production');
+        vi.stubEnv('SHARE_LINK_REQUEST_HASH_SECRET', '');
+        try {
+            expect(getShareLinkRequestHashSecret).toThrow('SHARE_LINK_REQUEST_HASH_SECRET');
+            vi.stubEnv('SHARE_LINK_REQUEST_HASH_SECRET', 'x'.repeat(32));
+            expect(getShareLinkRequestHashSecret()).toBe('x'.repeat(32));
+        } finally {
+            vi.unstubAllEnvs();
+        }
+    });
+
+    it('rejects values that cannot be encoded unambiguously', () => {
+        expect(() => canonicalizeJson({ bad: () => undefined })).toThrow();
+        expect(() => canonicalizeJson({ bad: Number.NaN })).toThrow();
+        expect(() => canonicalizeJson({ bad: new Date() })).toThrow();
+        expect(() => canonicalizeJson({ bad: new Array(2) })).toThrow();
+        const cyclic: Record<string, unknown> = {};
+        cyclic.self = cyclic;
+        expect(() => canonicalizeJson(cyclic)).toThrow();
+        expect(() => canonicalizeJson({ bad: 0.5 })).toThrow();
+        expect(canonicalizeJson({ keep: 1, drop: undefined })).toBe('{"keep":1}');
+    });
+});
+
+describe('share-link lease and backoff helpers', () => {
+    it('treats a lease as inactive at the exact expiry instant', () => {
+        const now = new Date('2026-01-01T00:00:00.000Z');
+        const expiry = computeLeaseExpiry(now, 1000);
+
+        expect(expiry).toBe('2026-01-01T00:00:01.000Z');
+        expect(isLeaseActive(expiry, new Date('2026-01-01T00:00:00.999Z'))).toBe(true);
+        expect(isLeaseActive(expiry, new Date('2026-01-01T00:00:01.000Z'))).toBe(false);
+        expect(isLeaseActive(null, now)).toBe(false);
+        expect(isLeaseActive('not-a-date', now)).toBe(false);
+    });
+
+    it('backs off exponentially and caps at one day', () => {
+        expect(computeCleanupBackoffMs(0)).toBe(30_000);
+        expect(computeCleanupBackoffMs(1)).toBe(60_000);
+        expect(computeCleanupBackoffMs(-5)).toBe(30_000);
+        expect(computeCleanupBackoffMs(100)).toBe(24 * 60 * 60 * 1000);
+    });
+});
+
+describe('share-link constraint readiness', () => {
+    it('creates every constraint and index once across concurrent callers', async () => {
+        let releaseFirst!: () => void;
+        const gate = new Promise<void>(resolve => {
+            releaseFirst = resolve;
+        });
+
+        mocks.run.mockReturnValueOnce(gate).mockResolvedValue(undefined);
+
+        const { ensureShareLinkConstraints, SHARE_LINK_SCHEMA_QUERIES } =
+            await import('../src/models/share-link-constraints');
+
+        const first = ensureShareLinkConstraints();
+        const second = ensureShareLinkConstraints();
+
+        expect(second).toBe(first);
+        expect(mocks.run).toHaveBeenCalledTimes(1);
+
+        releaseFirst();
+        await Promise.all([first, second]);
+
+        expect(mocks.run).toHaveBeenCalledTimes(SHARE_LINK_SCHEMA_QUERIES.length);
+        expect(mocks.run.mock.calls.map(([query]) => query)).toEqual([
+            ...SHARE_LINK_SCHEMA_QUERIES,
+        ]);
+
+        const queries = mocks.run.mock.calls.map(([query]) => String(query));
+        expect(queries.some(query => query.includes('share_link_operation_key_unique'))).toBe(true);
+        expect(queries.some(query => query.includes('share_link_reservation_share_unique'))).toBe(
+            true
+        );
+        expect(queries.some(query => query.includes('share_content_cleanup_object_unique'))).toBe(
+            true
+        );
+    });
+
+    it('accepts an equivalent-schema-rule race as ready', async () => {
+        mocks.run
+            .mockRejectedValueOnce({
+                code: 'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists',
+            })
+            .mockResolvedValue(undefined);
+
+        const { ensureShareLinkConstraints } = await import('../src/models/share-link-constraints');
+
+        await expect(ensureShareLinkConstraints()).resolves.toBeUndefined();
+    });
+
+    it('clears failed readiness so a later request can retry', async () => {
+        const failure = new Error('neo4j unavailable');
+        mocks.run.mockRejectedValueOnce(failure).mockResolvedValue(undefined);
+
+        const { ensureShareLinkConstraints } = await import('../src/models/share-link-constraints');
+
+        await expect(ensureShareLinkConstraints()).rejects.toBe(failure);
+        await expect(ensureShareLinkConstraints()).resolves.toBeUndefined();
+    });
+});

package/test/share-link-list-cursor.unit.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import { SHARE_LINK_ID_BYTES } from '@learncard/types';
+
+import {
+    decodeShareLinkListCursor,
+    encodeShareLinkListCursor,
+} from '../src/accesslayer/share-link/list';
+
+/**
+ * Canonical, versioned owner-list cursor codec (DB-free).
+ *
+ * The cursor is an ordering hint over exactly `(createdAt, id)`; it must reject
+ * everything malformed, non-canonical, oversized or from another version without
+ * throwing.
+ */
+
+const ID = Buffer.alloc(SHARE_LINK_ID_BYTES, 7).toString('base64url');
+
+describe('share-link list cursor codec', () => {
+    it('round-trips exactly the two ordering fields', () => {
+        const cursor = { createdAt: '2026-09-20T00:00:00.000Z', id: ID };
+        const encoded = encodeShareLinkListCursor(cursor);
+
+        expect(encoded.startsWith('v1.')).toBe(true);
+        expect(decodeShareLinkListCursor(encoded)).toEqual(cursor);
+    });
+
+    it('rejects non-string, empty and oversized input', () => {
+        expect(decodeShareLinkListCursor(undefined)).toBeNull();
+        expect(decodeShareLinkListCursor(123)).toBeNull();
+        expect(decodeShareLinkListCursor('')).toBeNull();
+        expect(decodeShareLinkListCursor(`v1.${'A'.repeat(600)}`)).toBeNull();
+    });
+
+    it('rejects an unknown version prefix', () => {
+        expect(
+            decodeShareLinkListCursor(`v2.${Buffer.from('["a","b"]').toString('base64url')}`)
+        ).toBeNull();
+        expect(decodeShareLinkListCursor('list.abc')).toBeNull();
+    });
+
+    it('rejects non-canonical base64url and non-JSON payloads', () => {
+        expect(decodeShareLinkListCursor('v1.@@@@')).toBeNull();
+        expect(decodeShareLinkListCursor('v1.====')).toBeNull();
+        expect(
+            decodeShareLinkListCursor(`v1.${Buffer.from('not json', 'utf8').toString('base64url')}`)
+        ).toBeNull();
+    });
+
+    it('rejects wrong arity or non-string fields', () => {
+        const payload = (value: unknown) =>
+            `v1.${Buffer.from(JSON.stringify(value), 'utf8').toString('base64url')}`;
+
+        expect(decodeShareLinkListCursor(payload(['2026-09-20T00:00:00.000Z']))).toBeNull();
+        expect(
+            decodeShareLinkListCursor(payload(['2026-09-20T00:00:00.000Z', ID, 'extra']))
+        ).toBeNull();
+        expect(decodeShareLinkListCursor(payload([1, ID]))).toBeNull();
+        expect(decodeShareLinkListCursor(payload(['2026-09-20T00:00:00.000Z', 1]))).toBeNull();
+        expect(decodeShareLinkListCursor(payload({ createdAt: 'x', id: ID }))).toBeNull();
+    });
+
+    it('rejects impossible timestamps and non-canonical ISO spellings', () => {
+        const payload = (value: unknown) =>
+            `v1.${Buffer.from(JSON.stringify(value), 'utf8').toString('base64url')}`;
+
+        expect(decodeShareLinkListCursor(payload(['not-a-date', ID]))).toBeNull();
+        expect(decodeShareLinkListCursor(payload(['2026-13-40T00:00:00.000Z', ID]))).toBeNull();
+        // Valid instant but not the exact canonical `toISOString` spelling.
+        expect(decodeShareLinkListCursor(payload(['2026-09-20T00:00:00Z', ID]))).toBeNull();
+    });
+
+    it('rejects an id that is not canonical base64url for exactly 16 bytes', () => {
+        const payload = (createdAt: string, id: string) =>
+            `v1.${Buffer.from(JSON.stringify([createdAt, id]), 'utf8').toString('base64url')}`;
+
+        expect(decodeShareLinkListCursor(payload('2026-09-20T00:00:00.000Z', 'short'))).toBeNull();
+        expect(decodeShareLinkListCursor(payload('2026-09-20T00:00:00.000Z', `${ID}=`))).toBeNull();
+        expect(
+            decodeShareLinkListCursor(
+                payload('2026-09-20T00:00:00.000Z', Buffer.alloc(8, 1).toString('base64url'))
+            )
+        ).toBeNull();
+    });
+});

package/test/share-link-list.neo4j.spec.ts

@@ -0,0 +1,324 @@
+import { randomBytes } from 'node:crypto';
+
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+
+import { neogma } from '@instance';
+
+import { decodeShareLinkListCursor, listShareLinks } from '../src/accesslayer/share-link/list';
+import { ensureShareLinkConstraints } from '../src/models/share-link-constraints';
+
+/**
+ * LC-2187 bounded owner-list repository against a REAL Neo4j (disposable
+ * testcontainer through the shared harness).
+ *
+ * The graph ordering, keyset `WHERE` clause, limit+1 fetch and namespace/owner
+ * scoping are real. There is no remote store, policy network or route here.
+ * Every seeded share id is a canonical 16-byte base64url value so the cursor
+ * codec accepts it exactly as production does.
+ */
+
+const NAMESPACE = 'list-test-ns';
+const OTHER_NAMESPACE = 'list-test-ns-2';
+const OWNER = 'owner-1';
+const OTHER_OWNER = 'owner-2';
+
+const newId = (): string => randomBytes(16).toString('base64url');
+
+type SeedInput = {
+    id?: string;
+    namespace?: string;
+    ownerProfileId?: string;
+    createdAt?: string;
+    status?: 'pending' | 'active' | 'stopped';
+    contentState?: 'staging' | 'finalized' | 'content_missing';
+    expiresAt?: string | null;
+};
+
+const seedShare = async (input: SeedInput = {}): Promise<string> => {
+    const id = input.id ?? newId();
+
+    const props: Record<string, unknown> = {
+        id,
+        namespace: input.namespace ?? NAMESPACE,
+        ownerProfileId: input.ownerProfileId ?? OWNER,
+        version: 1,
+        contentVersion: 1,
+        generation: 1,
+        status: input.status ?? 'active',
+        contentState: input.contentState ?? 'finalized',
+        title: 'Shared credentials',
+        note: null,
+        selectedCount: 1,
+        expiresAt: input.expiresAt ?? null,
+        stoppedAt: null,
+        viewCount: 0,
+        lastViewedAt: null,
+        minorPolicyIsMinor: null,
+        minorPolicyResolved: false,
+        minorPolicyDefaultExpiryDays: 30,
+        minorPolicyViewCountingEnabled: false,
+        createdAt: input.createdAt ?? '2026-09-20T00:00:00.000Z',
+        updatedAt: input.createdAt ?? '2026-09-20T00:00:00.000Z',
+    };
+
+    await neogma.queryRunner.run('MERGE (s:ShareLink {id: $id}) SET s = $props', { id, props });
+
+    return id;
+};
+
+const clearGraph = async (): Promise<void> => {
+    await neogma.queryRunner.run('MATCH (n:ShareLink) DETACH DELETE n');
+};
+
+const collectAll = async ({
+    namespace = NAMESPACE,
+    ownerProfileId = OWNER,
+    limit = 2,
+}: {
+    namespace?: string;
+    ownerProfileId?: string;
+    limit?: number;
+} = {}): Promise<{ ids: string[]; pages: number }> => {
+    const ids: string[] = [];
+    let pages = 0;
+    let cursor: { createdAt: string; id: string } | null = null;
+
+    do {
+        const page = await listShareLinks({
+            namespace,
+            ownerProfileId,
+            limit,
+            cursor,
+        });
+
+        ids.push(...page.records.map(record => record.id));
+        pages += 1;
+        cursor = page.nextCursor ? decodeShareLinkListCursor(page.nextCursor) : null;
+
+        if (page.nextCursor) expect(cursor).not.toBeNull();
+    } while (cursor !== null);
+
+    return { ids, pages };
+};
+
+describe('share-link owner list repository (real Neo4j)', () => {
+    beforeAll(async () => {
+        await ensureShareLinkConstraints();
+    });
+
+    beforeEach(async () => {
+        await clearGraph();
+    });
+
+    afterAll(async () => {
+        await clearGraph();
+    });
+
+    it('paginates by the immutable (createdAt, id) key with limit+1 and a next cursor', async () => {
+        const older = await seedShare({ createdAt: '2026-09-19T00:00:00.000Z' });
+        const middle = await seedShare({ createdAt: '2026-09-20T00:00:00.000Z' });
+        const newest = await seedShare({ createdAt: '2026-09-21T00:00:00.000Z' });
+
+        const first = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 2,
+            cursor: null,
+        });
+
+        expect(first.records.map(record => record.id)).toEqual([newest, middle]);
+        expect(first.hasMore).toBe(true);
+        expect(first.nextCursor).not.toBeNull();
+
+        const decoded = decodeShareLinkListCursor(first.nextCursor);
+        expect(decoded).toEqual({ createdAt: '2026-09-20T00:00:00.000Z', id: middle });
+
+        const second = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 2,
+            cursor: decoded,
+        });
+
+        expect(second.records.map(record => record.id)).toEqual([older]);
+        expect(second.hasMore).toBe(false);
+        expect(second.nextCursor).toBeNull();
+    });
+
+    it('does not duplicate or skip records when createdAt ties', async () => {
+        const createdAt = '2026-09-20T00:00:00.000Z';
+        const seeded = await Promise.all(Array.from({ length: 7 }, () => seedShare({ createdAt })));
+
+        const { ids, pages } = await collectAll({ limit: 2 });
+
+        expect(ids).toHaveLength(seeded.length);
+        expect(new Set(ids).size).toBe(seeded.length);
+        expect(ids.every(id => seeded.includes(id))).toBe(true);
+        // Deterministic descending id tie-break, independent of seed order.
+        expect(ids).toEqual([...seeded].sort((a, b) => (a < b ? 1 : -1)));
+        expect(pages).toBe(4);
+    });
+
+    it('returns every page exactly once across page boundaries', async () => {
+        const seeded: string[] = [];
+
+        for (let index = 0; index < 10; index += 1) {
+            seeded.push(
+                await seedShare({
+                    createdAt: new Date(Date.UTC(2026, 8, 1, 0, 0, index)).toISOString(),
+                })
+            );
+        }
+
+        const { ids } = await collectAll({ limit: 3 });
+
+        expect(new Set(ids).size).toBe(seeded.length);
+        expect(ids).toHaveLength(seeded.length);
+    });
+
+    it('lists pending, stopped and retained-expired records without triggering cleanup', async () => {
+        const pending = await seedShare({ status: 'pending', contentState: 'staging' });
+        const stopped = await seedShare({ status: 'stopped' });
+        const expired = await seedShare({
+            status: 'active',
+            expiresAt: '2020-01-01T00:00:00.000Z',
+        });
+
+        const result = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 25,
+            cursor: null,
+        });
+
+        expect(new Set(result.records.map(record => record.id))).toEqual(
+            new Set([pending, stopped, expired])
+        );
+        // Read-only: no cleanup jobs are created by listing.
+        const jobs = await neogma.queryRunner.run(
+            'MATCH (c:ShareContentCleanupJob) RETURN count(c) AS count'
+        );
+        expect(Number(jobs.records[0]?.get('count') ?? 0)).toBe(0);
+    });
+
+    it('isolates owners in the same namespace', async () => {
+        const mine = await seedShare({ createdAt: '2026-09-20T00:00:00.000Z' });
+        await seedShare({
+            ownerProfileId: OTHER_OWNER,
+            createdAt: '2026-09-21T00:00:00.000Z',
+        });
+
+        const result = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 25,
+            cursor: null,
+        });
+
+        expect(result.records.map(record => record.id)).toEqual([mine]);
+    });
+
+    it('isolates namespaces for the same owner', async () => {
+        const mine = await seedShare({ createdAt: '2026-09-20T00:00:00.000Z' });
+        await seedShare({
+            namespace: OTHER_NAMESPACE,
+            createdAt: '2026-09-21T00:00:00.000Z',
+        });
+
+        const result = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 25,
+            cursor: null,
+        });
+
+        expect(result.records.map(record => record.id)).toEqual([mine]);
+    });
+
+    it('never reveals records through another owner cursor', async () => {
+        const mineNew = await seedShare({
+            ownerProfileId: OWNER,
+            createdAt: '2026-09-25T00:00:00.000Z',
+        });
+        const mineOld = await seedShare({
+            ownerProfileId: OWNER,
+            createdAt: '2026-09-01T00:00:00.000Z',
+        });
+        const foreignNew = await seedShare({
+            ownerProfileId: OTHER_OWNER,
+            createdAt: '2026-09-30T00:00:00.000Z',
+        });
+        const foreignOld = await seedShare({
+            ownerProfileId: OTHER_OWNER,
+            createdAt: '2026-09-02T00:00:00.000Z',
+        });
+
+        // A cursor minted from the other owner's page.
+        const otherOwnerPage = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OTHER_OWNER,
+            limit: 1,
+            cursor: null,
+        });
+        const foreignCursor = decodeShareLinkListCursor(otherOwnerPage.nextCursor);
+
+        const page = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 25,
+            cursor: foreignCursor,
+        });
+
+        // The cursor is only an ordering hint: the caller's own scope is still
+        // applied, so the foreign cursor cannot surface foreign records, and no
+        // foreign id appears.
+        expect(page.records.map(record => record.id)).not.toContain(foreignNew);
+        expect(page.records.map(record => record.id)).not.toContain(foreignOld);
+        expect(page.records.every(record => [mineNew, mineOld].includes(record.id))).toBe(true);
+    });
+
+    it('bounds an oversized limit to the shared maximum without unbounded fetch', async () => {
+        for (let index = 0; index < 5; index += 1) {
+            await seedShare({
+                createdAt: new Date(Date.UTC(2026, 8, 1, 0, 0, index)).toISOString(),
+            });
+        }
+
+        const result = await listShareLinks({
+            namespace: NAMESPACE,
+            ownerProfileId: OWNER,
+            limit: 500,
+            cursor: null,
+        });
+
+        expect(result.records).toHaveLength(5);
+        expect(result.hasMore).toBe(false);
+        expect(result.nextCursor).toBeNull();
+    });
+
+    it('treats namespace/owner as literal bound parameters', async () => {
+        const trickyNamespace = "weird'ns--";
+        const trickyOwner = "o'wner--";
+        const id = await seedShare({
+            namespace: trickyNamespace,
+            ownerProfileId: trickyOwner,
+            createdAt: '2026-09-20T00:00:00.000Z',
+        });
+
+        const hit = await listShareLinks({
+            namespace: trickyNamespace,
+            ownerProfileId: trickyOwner,
+            limit: 25,
+            cursor: null,
+        });
+        expect(hit.records.map(record => record.id)).toEqual([id]);
+
+        const miss = await listShareLinks({
+            namespace: `${trickyNamespace}x`,
+            ownerProfileId: trickyOwner,
+            limit: 25,
+            cursor: null,
+        });
+        expect(miss.records).toHaveLength(0);
+    });
+});