@superblocksteam/shared 0.9613.2 → 0.9614.0

package/dist-esm/utils/attachment-validation.test.js

@@ -0,0 +1,169 @@
+import { PDFDocument } from 'pdf-lib';
+import { describe, expect, test } from 'vitest';
+import { AttachmentValidationError, MAX_ARCHIVE_ATTACHMENT_BYTES, MAX_IMAGE_ATTACHMENT_BYTES, MAX_PDF_ATTACHMENT_BYTES, MAX_TEXT_ATTACHMENT_BYTES, assertAttachmentSize, getAttachmentLimitsHelp, getAttachmentUploadPolicy, getAttachmentUploadLimit, validateAttachmentBytes } from './attachment-validation.js';
+const encoder = new TextEncoder();
+async function pdfWithPages(pageCount, useObjectStreams = true) {
+    const document = await PDFDocument.create();
+    for (let index = 0; index < pageCount; index += 1)
+        document.addPage();
+    return document.save({ useObjectStreams });
+}
+function expectReason(action, reason) {
+    try {
+        action();
+        throw new Error('expected validation to fail');
+    }
+    catch (error) {
+        expect(error).toBeInstanceOf(AttachmentValidationError);
+        if (error instanceof AttachmentValidationError) {
+            expect(error.code).toBe('attachment_invalid');
+            expect(error.reason).toBe(reason);
+        }
+    }
+}
+async function expectAsyncReason(action, reason) {
+    try {
+        await action();
+        throw new Error('expected validation to fail');
+    }
+    catch (error) {
+        expect(error).toBeInstanceOf(AttachmentValidationError);
+        if (error instanceof AttachmentValidationError)
+            expect(error.reason).toBe(reason);
+    }
+}
+describe('attachment size policy', () => {
+    test.each([
+        ['spec.pdf', 'application/pdf', MAX_PDF_ATTACHMENT_BYTES],
+        ['photo.jpg', 'image/jpeg', MAX_IMAGE_ATTACHMENT_BYTES],
+        ['notes.md', 'text/markdown', MAX_TEXT_ATTACHMENT_BYTES],
+        ['bundle.zip', 'application/zip', MAX_ARCHIVE_ATTACHMENT_BYTES],
+        ['bundle.tgz', 'application/octet-stream', MAX_ARCHIVE_ATTACHMENT_BYTES],
+        ['orders_prod.dump', 'application/octet-stream', MAX_ARCHIVE_ATTACHMENT_BYTES]
+    ])('allows the exact limit and rejects one byte more for %s', (fileName, mimeType, limit) => {
+        expect(getAttachmentUploadLimit({ fileName, mimeType })).toBe(limit);
+        expect(() => assertAttachmentSize({ fileName, mimeType, sizeBytes: limit })).not.toThrow();
+        expectReason(() => assertAttachmentSize({ fileName, mimeType, sizeBytes: limit + 1 }), 'too_large');
+    });
+    test.each([
+        ['spec.pdf', 'application/pdf', 4_500_001, 'This PDF is too large. The limit is 4.5 MB. Split it or attach only the pages you need.'],
+        [
+            'photo.jpg',
+            'IMAGE/JPEG; charset=binary',
+            3_750_001,
+            'This image is too large. The limit is 3.75 MB after conversion. Resize it or choose a smaller image.'
+        ],
+        ['notes.md', '', 5_242_881, 'This text/code file is too large. The limit is 5 MiB. Split it or attach only the content you need.'],
+        [
+            'bundle.zip',
+            'application/zip',
+            52_428_801,
+            'This archive is too large. The limit is 50 MiB. Remove files from it or split it into smaller archives.'
+        ]
+    ])('returns only the applicable size error for %s', (fileName, mimeType, sizeBytes, message) => {
+        expect(() => assertAttachmentSize({ fileName, mimeType, sizeBytes })).toThrow(message);
+        expect(getAttachmentUploadPolicy({ fileName, mimeType }).maxBytes).toBe(sizeBytes - 1);
+    });
+    test('uses the same policy for MIME types and extension fallback without trusting a conflicting extension', () => {
+        expect(getAttachmentUploadPolicy({ fileName: 'SPEC.PDF' })).toEqual(getAttachmentUploadPolicy({ mimeType: 'application/pdf' }));
+        expect(getAttachmentUploadPolicy({ fileName: 'spec.pdf', mimeType: 'image/png' }).maxBytes).toBe(3_750_000);
+        expect(getAttachmentLimitsHelp(false)).toBe('PDFs: 4.5 MB each, 100 pages total. Images: 3.75 MB after conversion. Text/code: 5 MiB.');
+        expect(getAttachmentLimitsHelp(true)).toBe('PDFs: 4.5 MB each, 100 pages total. Images: 3.75 MB after conversion. Text/code: 5 MiB. Supported archives and .dump files: 50 MiB.');
+    });
+    test('rejects unsupported and Office types', () => {
+        expectReason(() => getAttachmentUploadLimit({ fileName: 'logo.svg', mimeType: 'image/svg+xml' }), 'unsupported_type');
+        expectReason(() => getAttachmentUploadLimit({ fileName: 'report.docx', mimeType: 'text/plain' }), 'unsupported_type');
+        expectReason(() => getAttachmentUploadLimit({ fileName: 'notes.txt', mimeType: 'application/octet-stream' }), 'unsupported_type');
+    });
+});
+describe('attachment content validation', () => {
+    test.each([
+        ['image/jpeg', new Uint8Array([0xff, 0xd8, 0xff])],
+        ['image/png', new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])],
+        ['image/gif', encoder.encode('GIF89a')],
+        ['image/webp', encoder.encode('RIFF0000WEBP')]
+    ])('accepts valid %s magic', async (mimeType, bytes) => {
+        await expect(validateAttachmentBytes({ mimeType, bytes })).resolves.toEqual({ pdfPages: 0 });
+    });
+    test.each([
+        ['bundle.zip', 'application/zip', new Uint8Array([0x50, 0x4b, 0x05, 0x06])],
+        ['bundle.gz', 'application/gzip', new Uint8Array([0x1f, 0x8b])],
+        ['bundle.tgz', 'application/x-tgz', new Uint8Array([0x1f, 0x8b])]
+    ])('accepts valid archive magic for %s', async (fileName, mimeType, bytes) => {
+        await expect(validateAttachmentBytes({ fileName, mimeType, bytes })).resolves.toEqual({ pdfPages: 0 });
+    });
+    test('accepts postgres custom-format dump magic for .dump files', async () => {
+        const bytes = encoder.encode('PGDMP\x01\x0e\x00');
+        await expect(validateAttachmentBytes({ fileName: 'orders_prod.dump', mimeType: 'application/octet-stream', bytes })).resolves.toEqual({
+            pdfPages: 0
+        });
+        await expect(validateAttachmentBytes({ fileName: 'orders_prod.dump', mimeType: '', bytes })).resolves.toEqual({ pdfPages: 0 });
+        await expect(validateAttachmentBytes({ fileName: 'orders_prod.dump', mimeType: 'text/plain', bytes })).resolves.toEqual({
+            pdfPages: 0
+        });
+        await expectAsyncReason(() => validateAttachmentBytes({
+            fileName: 'orders_prod.dump',
+            mimeType: 'application/octet-stream',
+            bytes: encoder.encode('not a dump')
+        }), 'invalid_content');
+    });
+    test('accepts dump mime type without a .dump filename', async () => {
+        const bytes = encoder.encode('PGDMP\x01\x0e\x00');
+        await expect(validateAttachmentBytes({ fileName: 'orders', mimeType: 'application/x-postgresql-dump', bytes })).resolves.toEqual({
+            pdfPages: 0
+        });
+    });
+    test.each([
+        ['bundle.tgz', new Uint8Array([0x1f, 0x8b])],
+        ['bundle.gzip', new Uint8Array([0x1f, 0x8b])],
+        ['bundle.tar.gz', new Uint8Array([0x1f, 0x8b])],
+        ['bundle.zip', new Uint8Array([0x50, 0x4b, 0x05, 0x06])]
+    ])('accepts archive filename fallback for generic MIME on %s', async (fileName, bytes) => {
+        await expect(validateAttachmentBytes({ fileName, mimeType: 'application/octet-stream', bytes })).resolves.toEqual({ pdfPages: 0 });
+        await expectAsyncReason(() => validateAttachmentBytes({ fileName, mimeType: 'application/octet-stream', bytes: encoder.encode('not an archive') }), 'invalid_content');
+    });
+    test('does not use archive filename fallback for an incompatible declared MIME type', async () => {
+        await expectAsyncReason(() => validateAttachmentBytes({ fileName: 'bundle.tgz', mimeType: 'text/plain', bytes: new Uint8Array([0x1f, 0x8b]) }), 'invalid_content');
+    });
+    test('accepts UTF-8 text and rejects binary or disguised content', async () => {
+        await expect(validateAttachmentBytes({ fileName: 'notes.md', mimeType: 'text/markdown', bytes: encoder.encode('hello') })).resolves.toEqual({
+            pdfPages: 0
+        });
+        await expectAsyncReason(() => validateAttachmentBytes({ fileName: 'notes.txt', mimeType: 'text/plain', bytes: new Uint8Array([0xff, 0x00]) }), 'invalid_content');
+        await expectAsyncReason(() => validateAttachmentBytes({ fileName: 'notes.txt', mimeType: 'text/plain', bytes: new Uint8Array([0x50, 0x4b, 0x03, 0x04]) }), 'invalid_content');
+    });
+    test('rejects renamed random bytes for images and archives', async () => {
+        await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'image/png', bytes: encoder.encode('not png') }), 'invalid_content');
+        await expectAsyncReason(() => validateAttachmentBytes({ fileName: 'bundle.zip', mimeType: 'application/zip', bytes: encoder.encode('not zip') }), 'invalid_content');
+    });
+});
+describe('PDF validation', () => {
+    test('counts 100 pages in a compressed object stream PDF', async () => {
+        const bytes = await pdfWithPages(100);
+        await expect(validateAttachmentBytes({ fileName: 'spec.pdf', mimeType: 'application/pdf', bytes })).resolves.toEqual({ pdfPages: 100 });
+    });
+    test('rejects 101 pages', async () => {
+        const bytes = await pdfWithPages(101, false);
+        await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes }), 'too_many_pdf_pages');
+    });
+    test('rejects malformed, empty, and encrypted PDFs', async () => {
+        await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: encoder.encode('%PDF-broken') }), 'invalid_content');
+        await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: new Uint8Array() }), 'invalid_content');
+        const encrypted = await PDFDocument.create();
+        encrypted.addPage();
+        encrypted.context.trailerInfo.Encrypt = encrypted.context.register(encrypted.context.obj({ Filter: 'Standard', V: 1 }));
+        const encryptedBytes = await encrypted.save();
+        await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: encryptedBytes }), 'invalid_content');
+    });
+    test('rejects a cyclic page tree without recursive traversal', async () => {
+        const cyclic = await PDFDocument.create();
+        cyclic.addPage();
+        const pages = cyclic.catalog.Pages();
+        const pagesReference = cyclic.context.getObjectRef(pages);
+        if (!pagesReference)
+            throw new Error('expected page tree reference');
+        pages.Kids().push(pagesReference);
+        await expectAsyncReason(async () => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: await cyclic.save() }), 'invalid_content');
+    });
+});
+//# sourceMappingURL=attachment-validation.test.js.map

package/dist-esm/utils/attachment-validation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-validation.test.js","sourceRoot":"","sources":["../../src/utils/attachment-validation.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEhD,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,KAAK,UAAU,YAAY,CAAC,SAAiB,EAAE,gBAAgB,GAAG,IAAI;IACpE,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,CAAC;IAC5C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,EAAE,KAAK,IAAI,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;IACtE,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,YAAY,CAAC,MAAqB,EAAE,MAA2C;IACtF,IAAI,CAAC;QACH,MAAM,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,yBAAyB,CAAC,CAAC;QACxD,IAAI,KAAK,YAAY,yBAAyB,EAAE,CAAC;YAC/C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YAC9C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,MAA8B,EAAE,MAA2C;IAC1G,IAAI,CAAC;QACH,MAAM,MAAM,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,yBAAyB,CAAC,CAAC;QACxD,IAAI,KAAK,YAAY,yBAAyB;YAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,IAAI,CAAC,IAAI,CAAC;QACR,CAAC,UAAU,EAAE,iBAAiB,EAAE,wBAAwB,CAAC;QACzD,CAAC,WAAW,EAAE,YAAY,EAAE,0BAA0B,CAAC;QACvD,CAAC,UAAU,EAAE,eAAe,EAAE,yBAAyB,CAAC;QACxD,CAAC,YAAY,EAAE,iBAAiB,EAAE,4BAA4B,CAAC;QAC/D,CAAC,YAAY,EAAE,0BAA0B,EAAE,4BAA4B,CAAC;QACxE,CAAC,kBAAkB,EAAE,0BAA0B,EAAE,4BAA4B,CAAC;KAC/E,CAAC,CAAC,yDAAyD,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAC1F,MAAM,CAAC,wBAAwB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrE,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC3F,YAAY,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;IACtG,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC;QACR,CAAC,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,yFAAyF,CAAC;QACrI;YACE,WAAW;YACX,4BAA4B;YAC5B,SAAS;YACT,sGAAsG;SACvG;QACD,CAAC,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,qGAAqG,CAAC;QAClI;YACE,YAAY;YACZ,iBAAiB;YACjB,UAAU;YACV,yGAAyG;SAC1G;KACF,CAAC,CAAC,+CAA+C,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE;QAC7F,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvF,MAAM,CAAC,yBAAyB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qGAAqG,EAAE,GAAG,EAAE;QAC/G,MAAM,CAAC,yBAAyB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;QAChI,MAAM,CAAC,yBAAyB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5G,MAAM,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,yFAAyF,CAAC,CAAC;QACvI,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CACxC,qIAAqI,CACtI,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAChD,YAAY,CAAC,GAAG,EAAE,CAAC,wBAAwB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,EAAE,kBAAkB,CAAC,CAAC;QACtH,YAAY,CAAC,GAAG,EAAE,CAAC,wBAAwB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,EAAE,kBAAkB,CAAC,CAAC;QACtH,YAAY,CAAC,GAAG,EAAE,CAAC,wBAAwB,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,0BAA0B,EAAE,CAAC,EAAE,kBAAkB,CAAC,CAAC;IACpI,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,IAAI,CAAC,IAAI,CAAC;QACR,CAAC,YAAY,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAClD,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/E,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;KAC/C,CAAC,CAAC,wBAAwB,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QACrD,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/F,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC;QACR,CAAC,YAAY,EAAE,iBAAiB,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3E,CAAC,WAAW,EAAE,kBAAkB,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/D,CAAC,YAAY,EAAE,mBAAmB,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;KAClE,CAAC,CAAC,oCAAoC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAC3E,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,0BAA0B,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;YACpI,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/H,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;YACtH,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,MAAM,iBAAiB,CACrB,GAAG,EAAE,CACH,uBAAuB,CAAC;YACtB,QAAQ,EAAE,kBAAkB;YAC5B,QAAQ,EAAE,0BAA0B;YACpC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;SACpC,CAAC,EACJ,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QACjE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,+BAA+B,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;YAC/H,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC;QACR,CAAC,YAAY,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5C,CAAC,aAAa,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7C,CAAC,eAAe,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC,YAAY,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;KACzD,CAAC,CAAC,0DAA0D,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QACvF,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,0BAA0B,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QACnI,MAAM,iBAAiB,CACrB,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,0BAA0B,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC,EAC1H,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,+EAA+E,EAAE,KAAK,IAAI,EAAE;QAC/F,MAAM,iBAAiB,CACrB,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EACtH,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,MAAM,CACV,uBAAuB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAC7G,CAAC,QAAQ,CAAC,OAAO,CAAC;YACjB,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,MAAM,iBAAiB,CACrB,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EACrH,iBAAiB,CAClB,CAAC;QACF,MAAM,iBAAiB,CACrB,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EACjI,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,iBAAiB,CAAC,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAC;QACvI,MAAM,iBAAiB,CACrB,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,EACxH,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,IAAI,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QACpE,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1I,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,mBAAmB,EAAE,KAAK,IAAI,EAAE;QACnC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7C,MAAM,iBAAiB,CAAC,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,oBAAoB,CAAC,CAAC;IACvH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,iBAAiB,CACrB,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,EACpG,iBAAiB,CAClB,CAAC;QACF,MAAM,iBAAiB,CAAC,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,UAAU,EAAE,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAC;QAEpI,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,CAAC;QAC7C,SAAS,CAAC,OAAO,EAAE,CAAC;QACpB,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACxH,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;QAC9C,MAAM,iBAAiB,CAAC,GAAG,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACpI,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACxE,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,CAAC;QAC1C,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrC,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC1D,IAAI,CAAC,cAAc;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QACrE,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAElC,MAAM,iBAAiB,CACrB,KAAK,IAAI,EAAE,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,EAChG,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist-esm/utils/index.d.ts

@@ -1,6 +1,7 @@
 export * from './apiv2.js';
 export * from './attachment-delivery.js';
 export * from './attachment-upload.js';
+export * from './attachment-validation.js';
 export * from './bytestring.js';
 export * from './configuration.js';
 export * from './env.js';

package/dist-esm/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AAEzB,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AAEzB,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist-esm/utils/index.js

@@ -1,6 +1,7 @@
 export * from './apiv2.js';
 export * from './attachment-delivery.js';
 export * from './attachment-upload.js';
+export * from './attachment-validation.js';
 export * from './bytestring.js';
 export * from './configuration.js';
 export * from './env.js';

package/dist-esm/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AAEzB,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AAEzB,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/shared",
-  "version": "0.9613.2",
+  "version": "0.9614.0",
   "description": "Superblocks Shared Resources",
   "license": "Superblocks Community Software License",
   "repository": {
@@ -39,6 +39,7 @@
     "json5": "2.2.3",
     "lodash": "^4.17.21",
     "normalizr": "3.6.2",
+    "pdf-lib": "1.17.1",
     "semver": "^7.6.0",
     "slugify": "^1.6.6",
     "uuid": "^11.1.1"
@@ -48,7 +49,7 @@
     "@types/lodash": "^4.17.0",
     "@types/node": "^24",
     "@types/semver": "^7.5.6",
-    "@vitest/coverage-v8": "^4.0.17",
+    "@vitest/coverage-v8": "^4.1.11",
     "chokidar-cli": "3.0.0",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
@@ -59,7 +60,7 @@
     "globals": "^17.3.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.2",
-    "vitest": "^4.0.17"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=24",

package/src/database-lifecycle/destructiveMigrations.ts

@@ -23,6 +23,25 @@ export type DestructiveMigrationFile = {
   sql: string;
 };
 
+/**
+ * What publishing one version would delete, asked before anything runs.
+ *
+ * The server answers this both on its own endpoint, before a publish starts,
+ * and through the publish checklist once one is under way. Both answers come
+ * from the same scan, so they say the same thing.
+ */
+export type DestructiveMigrationGate = {
+  /** One row per change that removes something, so the user sees what goes. */
+  findings: DestructiveMigrationFinding[];
+  /**
+   * Publishing must be confirmed first: either the changes remove data, or
+   * they could not be checked and might.
+   */
+  needsConfirmation: boolean;
+  /** Nobody could check these changes, so the question has to be hedged. */
+  scanUnavailable: boolean;
+};
+
 const MAX_EXCERPT_LENGTH = 160;
 
 /**

package/src/database-lifecycle/index.ts

@@ -54,6 +54,7 @@ export function isLifecycleManagedIntegrationAllowedForApiTrigger(
 export const DATABASE_LIFECYCLE_TAG_OPERATIONS = 'databaseLifecycle:operations';
 export const DATABASE_LIFECYCLE_TAG_ENGINES = 'databaseLifecycle:engines';
 export const DATABASE_LIFECYCLE_TAG_CAPABILITIES = 'databaseLifecycle:capabilities';
+export const DATABASE_LIFECYCLE_TAG_PHYSICAL_CONFIG_FINGERPRINT = 'databaseLifecycle:physicalConfigFingerprint';
 export {
   CapacityPolicyValidationError,
   DATABASE_ENGINES,
@@ -372,6 +373,9 @@ export type PhysicalDatabaseInstance = {
   // Stable customer OPA deployment identity that owns this physical pool.
   // Absent on legacy rows (no backfill); agent-scoped lookups skip those.
   agentName?: string;
+  // Hash of the normalized physical Terraform configuration. Absent on legacy
+  // rows until registration or a successful physical-pool apply stamps it.
+  physicalConfigFingerprint?: string;
   metadata: Record<string, unknown>;
   created?: Date;
   updated?: Date;
@@ -396,7 +400,12 @@ export {
   DESTRUCTIVE_MIGRATION_ACK_REQUIRED_MESSAGE,
   DESTRUCTIVE_MIGRATION_SCAN_UNAVAILABLE
 } from './destructiveMigrations.js';
-export type { DestructiveMigrationFile, DestructiveMigrationFinding, DestructiveMigrationKind } from './destructiveMigrations.js';
+export type {
+  DestructiveMigrationFile,
+  DestructiveMigrationFinding,
+  DestructiveMigrationGate,
+  DestructiveMigrationKind
+} from './destructiveMigrations.js';
 
 export type LifecycleDispatchContinuation = {
   currentState?: string;
@@ -431,11 +440,13 @@ export type PhysicalPoolProvisioningError = {
 
 // Stable wizard/admin response for POST/GET physical-pool-provisioning.
 export type PhysicalPoolProvisioningState = {
+  applyRunId?: string;
   alreadyInProgress?: boolean;
   completedAt?: string;
   error?: PhysicalPoolProvisioningError;
   physicalDatabaseInstanceId?: string;
   provisioningId?: string;
+  retryRequestId?: string;
   startedAt?: string;
   startedBy?: PhysicalPoolProvisioningActor;
   status: PhysicalPoolProvisioningStatus;
@@ -497,6 +508,7 @@ export type LifecycleDispatchPayload = {
   // server supplies rather than anything a caller picks, and it goes away with
   // the worker's remaining shims in ENG-5127.
   environment?: string;
+  metadata?: { physicalConfigFingerprint?: string };
   migrations?: LifecycleMigration[];
   operation: LifecycleOperation;
   profile: string;

package/src/dbfs/types.ts

@@ -26,11 +26,23 @@ export type DirectoryEntryWithPath = {
   path: string;
 };
 
-export const codeModeSyncExcludedDirectories = ['.git', '.superblocks', 'build', 'integration_cache', 'node_modules'];
-
-// The CLI omits these paths from downloads, and the server rejects them at CLI upload boundaries.
+// Directory basenames skipped on DBFS upload/hash. `dist` is fullstack
+// `tsc --build` emit (`outDir: ./dist/client|server`); runtime never reads it,
+// but local-dev and in-tree typecheck can create it.
+export const codeModeSyncExcludedDirectories = ['.git', '.superblocks', 'build', 'dist', 'integration_cache', 'node_modules'];
+
+// The server rejects these names at CLI/live-edit PUT boundaries. Keep this
+// list frozen for rollout compatibility: a pinned older CLI still hashes
+// listings that include `dist`, so rejecting it would 400 the whole upload
+// and the client's local directory hash would no longer resolve.
 export const codeModeDownloadExcludedDirectories = ['.git', 'build', 'integration_cache', 'node_modules'];
 
+// Live-edit/local-dev download and archive skip these even when a historical
+// DBFS tree still contains them. `dist` is download-skipped without being
+// PUT-rejected so new sandboxes stop fetching polluted trees while old
+// clients can still persist a listing that names dist.
+export const codeModeDownloadSkippedDirectories = ['.git', 'build', 'dist', 'integration_cache', 'node_modules'];
+
 // Types for the batch put method
 
 interface PutManyItemFileContents {

package/src/errors/http.ts

@@ -1,12 +1,18 @@
+import type { ScimErrorType } from '../types/scim/index.js';
+
 export class HttpError extends Error {
   status: number;
   message: string;
   title?: string;
-  constructor(status: number, message: string, title?: string) {
+  // RFC 7644 section 3.12 keyword, set at the throw site because one error class covers several
+  // keywords. Only SCIM error rendering reads it.
+  scimType?: ScimErrorType;
+  constructor(status: number, message: string, title?: string, scimType?: ScimErrorType) {
     super(message);
     this.status = status;
     this.message = message;
     this.title = title;
+    this.scimType = scimType;
   }
 }
 
@@ -23,8 +29,8 @@ export abstract class RetryableHttpError extends HttpError {
 }
 
 export class BadRequestError extends HttpError {
-  constructor(message: string) {
-    super(400, message, 'Bad request');
+  constructor(message: string, scimType?: ScimErrorType) {
+    super(400, message, 'Bad request', scimType);
   }
 }
 
@@ -85,8 +91,8 @@ export class RbacUnauthorizedError extends UnauthorizedError {
 }
 
 export class ConflictError extends HttpError {
-  constructor(message: string) {
-    super(409, message, 'Conflict occurred.');
+  constructor(message: string, scimType?: ScimErrorType) {
+    super(409, message, 'Conflict occurred.', scimType);
   }
 }
 

package/src/types/ai/index.ts

@@ -72,6 +72,7 @@ export enum AiSystemTriggerType {
   ATTACHMENT_LABEL = 'attachment_label',
   COMMIT_MESSAGE = 'commit_message',
   DASHBOARD_CHAT = 'dashboard_chat',
+  DESTRUCTIVE_MIGRATION_SUMMARY = 'destructive_migration_summary',
   ERROR_SUMMARY = 'error_summary',
   FACT_METADATA = 'fact_metadata',
   PR_DESCRIPTION = 'pr_description'

package/src/types/audit/ocsf.ts

@@ -393,6 +393,13 @@ export interface TriageVerdict {
   verdict: 'exploitable' | 'not_exploitable' | 'uncertain';
 }
 
+export type NpmInstallTriageResult =
+  | TriageVerdict
+  | {
+      advisoryId: string;
+      unavailable: true;
+    };
+
 /**
  * Wire payload for the historical `v1.audit.npmInstallBlocked` socket method.
  *
@@ -451,11 +458,18 @@ export interface NpmInstallBlockedAuditReport {
   };
   /** Provisional install-time exploitability decision for a CVE finding. */
   triage?: TriageVerdict;
+  /** Analysis results attached to the blocked install attempt. */
+  triageVerdicts?: NpmInstallTriageResult[];
   /**
    * Builder-approved proceed-with-reason override when `reason ===
    * "vulnerability_user_override"`. Server scrubs `reason` and caps lengths.
    */
   userOverride?: {
+    advisories?: Array<{
+      advisoryId: string;
+      package: string;
+      severity?: string;
+    }>;
     packages: string[];
     reason: string;
   };

package/src/types/billing/index.ts

@@ -2,3 +2,4 @@ export * from './freeCreditsTier.js';
 export * from './pricingModel.js';
 export * from './billing.js';
 export * from './spendAlert.js';
+export * from './usageSource.js';

package/src/types/billing/usageSource.ts

@@ -0,0 +1,114 @@
+/**
+ * Where a GAU debit was drawn from. Stamped on each ai_token_usage row at
+ * recording time and never rewritten, so rows keep the source of the plan
+ * that was active when the usage happened, not the org's current plan.
+ *
+ * `topup` is the auto/manual ai_credits_topup source (TEAMS and the POC
+ * refill flow). `on_demand` is the enterprise on-demand bucket. `byo` is
+ * bring-your-own-key usage, which consumes no GAUs.
+ */
+export type UsageSource = 'byo' | 'enterprise' | 'legacy' | 'on_demand' | 'overage_unbilled' | 'pool' | 'seat' | 'topup' | 'trial';
+
+// Keyed on the UsageSource union so this is compile-time exhaustive: adding a
+// new UsageSource member fails to build here until the author decides whether
+// the Usage page shows it (add it below) or hides it (add it to the Exclude).
+// That decision can never again be made implicitly by a stale per-plan list.
+const GAU_DISPLAY_SOURCE_EXHAUSTIVE: Record<Exclude<UsageSource, 'byo'>, true> = {
+  enterprise: true,
+  legacy: true,
+  on_demand: true,
+  overage_unbilled: true,
+  pool: true,
+  seat: true,
+  topup: true,
+  trial: true
+};
+
+/**
+ * Every usage_source the Usage page's sub-banner surfaces (tiles, chart,
+ * usage table, Spending page) display: all GAU-consuming sources, excluding
+ * only `byo`.
+ */
+export const GAU_DISPLAY_USAGE_SOURCES: readonly UsageSource[] = Object.keys(GAU_DISPLAY_SOURCE_EXHAUSTIVE) as UsageSource[];
+
+// Keyed on the whole UsageSource union, so adding a source fails the build
+// until someone decides whether it draws on a contract commitment. The
+// previous rule was a denylist ("committed = everything except on_demand /
+// overage_unbilled / topup"), which made "counts against your commitment" the
+// silent default for every future source -- and swept in `trial`, which
+// debits no entitlement at all.
+const CONTRACT_COMMITTED_EXHAUSTIVE: Record<UsageSource, boolean> = {
+  // Consumes no GAUs -- the customer is paying their own model provider.
+  byo: false,
+  // Pooled enterprise / POC consumption.
+  enterprise: true,
+  // Rows predating the usage_source column; they were pool draws.
+  legacy: true,
+  // Overage beyond the commitment, invoiced separately at a premium.
+  on_demand: false,
+  // Recorded past the org cap and deliberately never billed.
+  overage_unbilled: false,
+  // The shared-pool slice for granular enterprise contracts and TEAMS.
+  pool: true,
+  // Per-seat allocation; its grants are inside the commit denominator.
+  seat: true,
+  // Separately purchased pool. The banner backs topups out of the commit
+  // denominator, so counting their spend in the numerator would push
+  // utilisation past 100%.
+  topup: false,
+  // Free trial allowance. The trial write path debits no entitlement, so this
+  // usage never drew on a commitment even when it falls inside the term.
+  // Exposure was durable on annual / contract_term cycles, where the window is
+  // the whole contract term; monthly cycles only mis-counted the conversion
+  // month and then self-healed (deriveEnterpriseCalendarPeriod).
+  trial: false
+};
+
+/**
+ * The usage_source values that count as drawing down a contract commitment.
+ *
+ * Feeds the plan banner's committed-vs-overage split. Deliberately an
+ * allowlist: see the note on {@link CONTRACT_COMMITTED_EXHAUSTIVE}.
+ */
+export const CONTRACT_COMMITTED_USAGE_SOURCES: readonly UsageSource[] = Object.entries(CONTRACT_COMMITTED_EXHAUSTIVE)
+  .filter(([, isCommitted]) => isCommitted)
+  .map(([source]) => source as UsageSource);
+
+// The sources an enterprise contract bills, used for the entitlement-window
+// math on /usage-records. Broader than CONTRACT_COMMITTED_USAGE_SOURCES: that
+// one answers "did this draw down the commitment", this one answers "is this
+// on the contract at all", so overage and top-up consumption count here and
+// trial still does not. Keyed on the union for the same reason as the others --
+// a new source must be classified rather than silently omitted from overage.
+const ENTERPRISE_CONTRACT_EXHAUSTIVE: Record<UsageSource, boolean> = {
+  byo: false,
+  enterprise: true,
+  legacy: true,
+  on_demand: true,
+  overage_unbilled: true,
+  pool: true,
+  seat: true,
+  topup: true,
+  trial: false
+};
+
+export const ENTERPRISE_CONTRACT_USAGE_SOURCES: readonly UsageSource[] = Object.entries(ENTERPRISE_CONTRACT_EXHAUSTIVE)
+  .filter(([, onContract]) => onContract)
+  .map(([source]) => source as UsageSource);
+
+// The sources that draw on a spendable balance rather than a commitment.
+// Expressed against CONTRACT_COMMITTED so the one deliberate difference stays
+// visible: top-ups are separately purchased pool, counted here because the
+// balance they feed includes them, and excluded from the commitment because
+// the banner backs them out of its denominator.
+const POOL_LIKE_EXHAUSTIVE: Record<UsageSource, boolean> = {
+  ...CONTRACT_COMMITTED_EXHAUSTIVE,
+  // Pre-column rows. They predate every current balance, so no live balance
+  // shows them.
+  legacy: false,
+  topup: true
+};
+
+export const POOL_LIKE_USAGE_SOURCES: readonly UsageSource[] = Object.entries(POOL_LIKE_EXHAUSTIVE)
+  .filter(([, isPoolLike]) => isPoolLike)
+  .map(([source]) => source as UsageSource);

package/src/types/policyGate/errors.ts

@@ -41,6 +41,7 @@ export const POLICY_GATE_ERROR_CODES = {
 
   // Server dispatch and stale-run failures.
   canceled: { category: 'user_action' }, // The user canceled the in-flight publish.
+  dependency_scan_stalled: { category: 'platform_transient' }, // The in-process dependency scan never completed.
   dev_server_unreachable: { category: 'platform_transient' }, // The dev server did not finish the run.
   dispatch_failed: { category: 'platform_transient' }, // The server could not start the run.
 

package/src/types/policyGate/index.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'vitest';
+
+import { isLockfilePath } from './index.js';
+
+describe('isLockfilePath', () => {
+  test('recognizes known lockfile basenames', () => {
+    expect(isLockfilePath('pnpm-lock.yaml')).toBe(true);
+    expect(isLockfilePath('yarn.lock')).toBe(true);
+    expect(isLockfilePath('package-lock.json')).toBe(true);
+    expect(isLockfilePath('bun.lock')).toBe(true);
+    expect(isLockfilePath('bun.lockb')).toBe(true);
+  });
+
+  test('recognizes a lockfile nested in a directory', () => {
+    expect(isLockfilePath('server/pnpm-lock.yaml')).toBe(true);
+  });
+
+  test('rejects a non-lockfile path', () => {
+    expect(isLockfilePath('server/apis/fetch-url.ts')).toBe(false);
+  });
+
+  test('rejects a path that merely contains a lockfile name as a substring', () => {
+    expect(isLockfilePath('vendor/yarn.lock.bak')).toBe(false);
+  });
+});