@learncard/network-brain-service 3.19.0 → 4.0.0

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

@@ -0,0 +1,262 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { beforeAll, beforeEach, afterAll, describe, expect, it } from 'vitest';
+import { neogma } from '@instance';
+import { ensureShareLinkConstraints } from '../src/models/share-link-constraints';
+import {
+    beginShareAttachmentChunk,
+    completeShareAttachmentChunk,
+    deleteUnreferencedShareAttachment,
+    expireShareAttachmentStages,
+    shareAttachmentObjectId,
+    type ShareAttachmentBinding,
+} from '../src/accesslayer/share-link/attachment';
+import {
+    reserveCreate,
+    reserveReplacement,
+    finalizeReservation,
+    revokeShareLink,
+    abandonReservation,
+    getShareLink,
+    listCleanupJobsForShare,
+} from '../src/accesslayer/share-link';
+import { contentBinding } from './helpers/share-link-fixtures';
+import type { ShareLinkReservationRecord } from '../src/accesslayer/share-link/types';
+
+// Only this suite's random namespace is cleaned; no shared/user graph is touched.
+const namespace = `attachment-tests-${randomUUID()}`;
+const clear = async (): Promise<void> => {
+    await neogma.queryRunner.run('MATCH (n) WHERE n.namespace = $namespace DETACH DELETE n', {
+        namespace,
+    });
+};
+beforeAll(async () => {
+    await ensureShareLinkConstraints();
+});
+beforeEach(clear);
+afterAll(async () => {
+    await clear();
+    await neogma.queryRunner.getDriver().close();
+});
+
+const binding = (count = 2, owner = 'owner'): ShareAttachmentBinding => ({
+    namespace,
+    ownerProfileId: owner,
+    shareId: randomBytes(16).toString('base64url'),
+    contentVersion: 1,
+    attachmentId: randomUUID(),
+    chunkCount: count,
+});
+const stage = async (
+    value: ShareAttachmentBinding,
+    indices = Array.from({ length: value.chunkCount }, (_, i) => i)
+) => {
+    for (const index of indices) {
+        await beginShareAttachmentChunk(value, index);
+        await completeShareAttachmentChunk(value, index);
+    }
+};
+const createInput = (value: ShareAttachmentBinding) => ({
+    ...value,
+    clientRequestId: randomUUID(),
+    title: 'Synthetic resume',
+    selectedCount: 1,
+    content: contentBinding(value.attachmentId),
+    attachment: { id: value.attachmentId, chunkCount: value.chunkCount },
+    requestHash: 'a'.repeat(64),
+    leaseOwner: 'worker',
+});
+const reserve = async (value: ShareAttachmentBinding): Promise<ShareLinkReservationRecord> => {
+    const result = await reserveCreate(createInput(value));
+    if (result.outcome !== 'reserved') throw new Error('expected reserved operation');
+    return result.reservation;
+};
+const finish = async (record: ShareLinkReservationRecord, verified = true) =>
+    finalizeReservation({
+        namespace,
+        ownerProfileId: record.ownerProfileId,
+        shareId: record.shareId,
+        operationId: record.operationId,
+        objectRef: record.objectRef,
+        generation: record.generation,
+        leaseOwner: record.leaseOwner,
+        verifiedContentHash: record.contentHash ?? undefined,
+        verifiedAttachmentId: verified ? (record.attachmentId ?? undefined) : undefined,
+    });
+
+describe('managed attachment graph fences', () => {
+    it.each([
+        [0, 0],
+        [17, 0],
+        [2.5, 0],
+        [2, -1],
+        [2, 2],
+        [2, 0.5],
+        [2, NaN],
+    ])(
+        'rejects invalid chunk bounds before persisting staging/quota nodes: %#',
+        async (count, index) => {
+            await expect(beginShareAttachmentChunk(binding(count), index)).rejects.toMatchObject({
+                code: 'INVALID_INPUT',
+            });
+            const result = await neogma.queryRunner.run(
+                'MATCH (n) WHERE n.namespace = $namespace RETURN count(n) AS count',
+                { namespace }
+            );
+            expect(result.records[0].get('count').toNumber()).toBe(0);
+        }
+    );
+    it('refuses incomplete staged PDFs and rolls back the pending share', async () => {
+        const value = binding();
+        await stage(value, [0]);
+        await expect(reserve(value)).rejects.toMatchObject({ code: 'PRECONDITION_FAILED' });
+        expect(
+            await getShareLink({
+                shareId: value.shareId,
+                namespace,
+                ownerProfileId: value.ownerProfileId,
+            })
+        ).toBeNull();
+        await completeShareAttachmentChunk(value, 1);
+        const pending = await reserve(value);
+        await expect(finish(pending, false)).rejects.toMatchObject({ code: 'PRECONDITION_FAILED' });
+        const committed = await finish(pending);
+        expect(committed.share.attachmentId).toBe(value.attachmentId);
+        expect(committed.share.attachmentChunkCount).toBe(2);
+    });
+
+    it('supports idempotent same asset staging but rejects foreign owners and mismatched count', async () => {
+        const value = binding();
+        await stage(value);
+        const pending = await reserve(value);
+        await finish(pending);
+        await beginShareAttachmentChunk(value, 0);
+        await completeShareAttachmentChunk(value, 0);
+        await expect(
+            beginShareAttachmentChunk({ ...value, ownerProfileId: 'foreign' }, 0)
+        ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+        await expect(
+            beginShareAttachmentChunk({ ...value, chunkCount: 1 }, 0)
+        ).rejects.toMatchObject({ code: 'CONFLICT' });
+        expect(await deleteUnreferencedShareAttachment(value)).toBe(false);
+    });
+
+    it('serializes cleanup versus pinning so exactly one can acquire the asset', async () => {
+        const value = binding();
+        await stage(value);
+        const [reserved, deleted] = await Promise.allSettled([
+            reserve(value),
+            deleteUnreferencedShareAttachment(value),
+        ]);
+        expect(deleted.status).toBe('fulfilled');
+        if (reserved.status === 'fulfilled') {
+            expect(deleted.status === 'fulfilled' && deleted.value).toBe(false);
+            await finish(reserved.value);
+        } else {
+            expect(deleted.status === 'fulfilled' && deleted.value).toBe(true);
+            expect(reserved.reason.code).toBe('PRECONDITION_FAILED');
+            await expect(beginShareAttachmentChunk(value, 0)).rejects.toMatchObject({
+                code: 'CONFLICT',
+            });
+        }
+    });
+
+    it('abandonment permanently withdraws asset commit authority and queues every exact chunk', async () => {
+        const value = binding(3);
+        await stage(value);
+        const pending = await reserve(value);
+        const abandoned = await abandonReservation({
+            namespace,
+            ownerProfileId: value.ownerProfileId,
+            shareId: value.shareId,
+            operationId: pending.operationId,
+        });
+        expect(abandoned.outcome).toBe('abandoned');
+        await expect(finish(pending)).rejects.toMatchObject({ code: 'CONFLICT' });
+        await expect(beginShareAttachmentChunk(value, 0)).rejects.toMatchObject({
+            code: 'CONFLICT',
+        });
+        const jobs = await listCleanupJobsForShare(value.shareId);
+        expect(
+            jobs
+                .filter(job => job.operationId === value.attachmentId)
+                .map(job => job.objectRef)
+                .sort()
+        ).toEqual(
+            [0, 1, 2].map(index => shareAttachmentObjectId(value.attachmentId, index)).sort()
+        );
+        expect(
+            jobs.every(
+                job => job.ownerProfileId === value.ownerProfileId && job.namespace === namespace
+            )
+        ).toBe(true);
+    });
+
+    it('content replacement preserves the share and queues old chunks, then stopping queues current chunks', async () => {
+        const old = binding();
+        await stage(old);
+        const first = await finish(await reserve(old));
+        const next = { ...old, attachmentId: randomUUID(), contentVersion: 2, chunkCount: 3 };
+        await stage(next);
+        const updated = await reserveReplacement({
+            namespace,
+            ownerProfileId: old.ownerProfileId,
+            shareId: old.shareId,
+            expectedVersion: first.share.version,
+            clientRequestId: randomUUID(),
+            requestHash: 'b'.repeat(64),
+            leaseOwner: 'worker',
+            content: {
+                ...contentBinding(next.attachmentId),
+                contentVersion: 2,
+                selectedCount: 1,
+                attachment: { id: next.attachmentId, chunkCount: next.chunkCount },
+            },
+        });
+        if (updated.outcome !== 'reserved') throw new Error('expected update');
+        const second = await finish(updated.reservation);
+        expect(second.share.id).toBe(first.share.id);
+        expect(second.share.contentVersion).toBe(2);
+        expect(second.share.attachmentId).toBe(next.attachmentId);
+        let jobs = await listCleanupJobsForShare(old.shareId);
+        expect(jobs.filter(job => job.operationId === old.attachmentId)).toHaveLength(2);
+        expect(jobs.filter(job => job.operationId === next.attachmentId)).toHaveLength(0);
+        await revokeShareLink({
+            namespace,
+            ownerProfileId: old.ownerProfileId,
+            shareId: old.shareId,
+        });
+        jobs = await listCleanupJobsForShare(old.shareId);
+        expect(jobs.filter(job => job.operationId === next.attachmentId)).toHaveLength(3);
+        expect(jobs.filter(job => job.operationId === old.attachmentId)).toHaveLength(2);
+    });
+
+    it('bounds concurrent never-committed stages to eight and collects expired orphans', async () => {
+        const stages = Array.from({ length: 9 }, () => binding(1));
+        const results = await Promise.allSettled(
+            stages.map(value => beginShareAttachmentChunk(value, 0))
+        );
+        expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(8);
+        expect(results.filter(result => result.status === 'rejected')).toHaveLength(1);
+        const queued = await expireShareAttachmentStages({
+            namespace,
+            now: new Date(Date.now() + 25 * 60 * 60 * 1000),
+        });
+        expect(queued).toBe(8);
+        const completed = stages[results.findIndex(result => result.status === 'fulfilled')];
+        await expect(completeShareAttachmentChunk(completed!, 0)).rejects.toMatchObject({
+            code: 'CONFLICT',
+        });
+        await expect(beginShareAttachmentChunk(binding(1), 0)).resolves.toBeUndefined();
+    }, 60_000);
+
+    it('prevents cross-owner attachment UUID reuse from poisoning global immutable object cleanup', async () => {
+        const first = binding(1);
+        await stage(first);
+        const attacker = { ...binding(1, 'attacker'), attachmentId: first.attachmentId };
+        await expect(beginShareAttachmentChunk(attacker, 0)).rejects.toMatchObject({
+            code: 'CONFLICT',
+        });
+        expect(await deleteUnreferencedShareAttachment(attacker)).toBe(false);
+        expect(await listCleanupJobsForShare(first.shareId)).toHaveLength(0);
+    });
+});

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

@@ -0,0 +1,244 @@
+import { describe, expect, it, vi } from 'vitest';
+import { randomUUID } from 'node:crypto';
+import { createShareLinkAttachmentOwnerApi } from '../src/helpers/share-link-attachment';
+import { verifyShareAttachmentStats } from '../src/helpers/share-link-coordinator/attachment-stat';
+import {
+    mintShareAttachmentAccessToken,
+    verifyShareAttachmentAccessToken,
+} from '../src/helpers/share-link-attachment-access';
+import { computeShareLinkRequestHash } from '../src/helpers/share-link-lifecycle';
+import type { ShareLinkReservationRecord } from '../src/accesslayer/share-link/types';
+import type { ShareLinkRecord } from '../src/models/ShareLink';
+import type { ShareContentTuple } from '../src/helpers/share-content-client/types';
+import { ShareLinkRepositoryError } from '../src/accesslayer/share-link/errors';
+
+const shareId = Buffer.alloc(16, 7).toString('base64url');
+const attachmentId = randomUUID();
+const owner = { namespace: 'deployment', ownerProfileId: 'owner' };
+const envelope = {
+    v: 1 as const,
+    alg: 'A256GCM' as const,
+    iv: Buffer.alloc(12, 1).toString('base64url'),
+    ct: Buffer.alloc(32, 2).toString('base64url'),
+};
+const input = {
+    id: shareId,
+    contentVersion: 1,
+    attachmentId,
+    chunkIndex: 0,
+    chunkCount: 1,
+    envelope,
+    ownerEncryptedRecovery: { protected: 'p', iv: 'i', ciphertext: 'c', tag: 't' },
+};
+const summary = (tuple: ShareContentTuple) => ({
+    kind: 'active' as const,
+    ...tuple,
+    contentHash: 'a'.repeat(64),
+    payloadHash: 'b'.repeat(64),
+    ciphertextBytes: 32,
+    recoveryBytes: 4,
+    createdAt: '2026-10-03T00:00:00Z',
+});
+
+describe('attachment owner transport and immutable commit binding', () => {
+    it('retains incomplete stage after lost put acknowledgement and safely retries the same tuple', async () => {
+        const repository = {
+            begin: vi.fn(async () => undefined),
+            complete: vi.fn(async () => undefined),
+            deleteUnreferenced: vi.fn(async () => true),
+        };
+        const client = {
+            put: vi.fn(async (value: ShareContentTuple) => ({
+                ok: true as const,
+                value: { status: 'idempotent' as const, record: summary(value) },
+            })),
+            delete: vi.fn(async (tuple: ShareContentTuple) => ({
+                ok: true as const,
+                value: {
+                    kind: 'tombstone' as const,
+                    ...tuple,
+                    deletedAt: '2026-10-03T00:00:00Z',
+                },
+            })),
+        };
+        client.put.mockResolvedValueOnce({ ok: false, error: 'NETWORK_ERROR' } as never);
+        const api = createShareLinkAttachmentOwnerApi(client, repository);
+        await expect(api.put(input, owner)).rejects.toMatchObject({ code: 'UNAVAILABLE' });
+        expect(repository.complete).not.toHaveBeenCalled();
+        await expect(api.put(input, owner)).resolves.toEqual({ ok: true });
+        expect(client.put).toHaveBeenCalledTimes(2);
+        expect(client.put.mock.calls[0]![0]).toEqual(client.put.mock.calls[1]![0]);
+        expect(repository.complete).toHaveBeenCalledOnce();
+    });
+
+    it('preserves definitive staging failures so callers can discard an expired attempt', async () => {
+        const repository = {
+            begin: vi
+                .fn()
+                .mockRejectedValue(
+                    new ShareLinkRepositoryError('PRECONDITION_FAILED', 'private detail')
+                ),
+            complete: vi.fn(),
+            deleteUnreferenced: vi.fn(),
+        };
+        const client = { put: vi.fn(), delete: vi.fn() };
+        const api = createShareLinkAttachmentOwnerApi(client, repository);
+        await expect(api.put(input, owner)).rejects.toMatchObject({
+            code: 'PRECONDITION_FAILED',
+            message: 'attachment upload unavailable',
+        });
+        expect(client.put).not.toHaveBeenCalled();
+    });
+
+    it('never deletes a referenced/ambiguous stage and reports physical cleanup failure while durable jobs remain', async () => {
+        const client = {
+            put: vi.fn(),
+            delete: vi.fn().mockResolvedValue({ ok: false, error: 'UNAVAILABLE' }),
+        };
+        const repository = {
+            begin: vi.fn(),
+            complete: vi.fn(),
+            deleteUnreferenced: vi.fn(async () => false),
+        };
+        const api = createShareLinkAttachmentOwnerApi(client, repository);
+        const key = { id: shareId, contentVersion: 1, attachmentId, chunkCount: 2 };
+        await expect(api.delete(key, owner)).resolves.toEqual({ ok: false });
+        expect(client.delete).not.toHaveBeenCalled();
+        repository.deleteUnreferenced.mockResolvedValueOnce(true);
+        await expect(api.delete(key, owner)).resolves.toEqual({ ok: false });
+        expect(client.delete).toHaveBeenCalledTimes(2);
+        expect(client.delete.mock.calls[1]![0]).toEqual({
+            ...owner,
+            shareId,
+            contentVersion: 1,
+            objectId: `resume-pdf-${attachmentId}-1`,
+            operationId: attachmentId,
+        });
+    });
+
+    it('requires all staged objects stat-present under exactly the committed owner/version/asset tuple', async () => {
+        const reservation = {
+            ...owner,
+            shareId,
+            contentVersion: 1,
+            attachmentId,
+            attachmentChunkCount: 2,
+        } as ShareLinkReservationRecord;
+        const client = {
+            stat: vi.fn(async (tuple: ShareContentTuple) => ({
+                ok: true as const,
+                value: summary(tuple),
+            })),
+        };
+        await expect(verifyShareAttachmentStats(client, reservation)).resolves.toBe(true);
+        expect(client.stat).toHaveBeenCalledTimes(2);
+        client.stat.mockResolvedValueOnce({ ok: false, error: 'NOT_FOUND' } as never);
+        await expect(verifyShareAttachmentStats(client, reservation)).resolves.toBe(false);
+        client.stat.mockImplementationOnce(async tuple => ({
+            ok: true as const,
+            value: summary({ ...tuple, ownerProfileId: 'foreign' }),
+        }));
+        await expect(verifyShareAttachmentStats(client, reservation)).resolves.toBe(false);
+        await expect(
+            verifyShareAttachmentStats(client, reservation, {
+                exhausted: () => true,
+                remainingMs: () => 0,
+            })
+        ).resolves.toBe(false);
+    });
+
+    it('binds attachment identity and count into client-request idempotency intent', () => {
+        const base = { id: shareId, attachment: { id: attachmentId, chunkCount: 2 } };
+        const hash = computeShareLinkRequestHash('create', base);
+        expect(
+            computeShareLinkRequestHash('create', {
+                ...base,
+                attachment: { id: randomUUID(), chunkCount: 2 },
+            })
+        ).not.toBe(hash);
+        expect(
+            computeShareLinkRequestHash('create', {
+                ...base,
+                attachment: { id: attachmentId, chunkCount: 1 },
+            })
+        ).not.toBe(hash);
+    });
+
+    it('reserves the bounded remote call and finalization time before each chunk stat', async () => {
+        const reservation = {
+            ...owner,
+            shareId,
+            contentVersion: 1,
+            attachmentId,
+            attachmentChunkCount: 2,
+        } as ShareLinkReservationRecord;
+        let remaining = 1600;
+        const client = {
+            stat: vi.fn(async (tuple: ShareContentTuple) => {
+                remaining = 1499;
+                return { ok: true as const, value: summary(tuple) };
+            }),
+        };
+        const budget = {
+            remainingMs: () => remaining,
+            reserveMs: () => 500,
+            exhausted: () => false,
+        };
+        await expect(verifyShareAttachmentStats(client, reservation, budget, 1000)).resolves.toBe(
+            false
+        );
+        expect(client.stat).toHaveBeenCalledOnce();
+    });
+});
+
+describe('short-lived attachment password grant', () => {
+    const record = {
+        id: shareId,
+        ownerProfileId: 'owner',
+        contentVersion: 1,
+        attachmentId,
+        attachmentChunkCount: 16,
+        passcodeHash: '$argon2id$password-verifier',
+    } as ShareLinkRecord;
+    const now = new Date('2026-10-03T00:00:00Z');
+    it('exposes neither password verifier nor identity scope and rejects changed bindings', () => {
+        const token = mintShareAttachmentAccessToken(record, 'deployment', '203.0.113.1', now);
+        const body = Buffer.from(token.split('.')[0]!, 'base64url').toString('utf8');
+        expect(body).not.toContain('password-verifier');
+        expect(body).not.toContain('owner');
+        expect(body).not.toContain('deployment');
+        expect(body).not.toContain('203.0.113.1');
+        expect(
+            verifyShareAttachmentAccessToken(token, record, 'deployment', '203.0.113.1', now)
+        ).toBe(true);
+        for (const changed of [
+            { ...record, contentVersion: 2 },
+            { ...record, attachmentId: randomUUID() },
+            { ...record, attachmentChunkCount: 15 },
+            { ...record, ownerProfileId: 'someone-else' },
+            { ...record, passcodeHash: 'changed' },
+        ]) {
+            expect(
+                verifyShareAttachmentAccessToken(token, changed, 'deployment', '203.0.113.1', now)
+            ).toBe(false);
+        }
+        expect(verifyShareAttachmentAccessToken(token, record, 'foreign', '203.0.113.1', now)).toBe(
+            false
+        );
+        expect(
+            verifyShareAttachmentAccessToken(token, record, 'deployment', '203.0.113.2', now)
+        ).toBe(false);
+        expect(
+            verifyShareAttachmentAccessToken(
+                token,
+                record,
+                'deployment',
+                '203.0.113.1',
+                new Date(now.getTime() + 60_000)
+            )
+        ).toBe(false);
+        expect(
+            verifyShareAttachmentAccessToken(`${token}x`, record, 'deployment', '203.0.113.1', now)
+        ).toBe(false);
+    });
+});