@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/upload-inspection.js

@@ -0,0 +1,539 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * STRUCTURAL upload inspection (AGL-1475).
+ *
+ * ## What this is, and what it is emphatically not
+ *
+ * This is **not** an antivirus scanner and no code in this module should ever
+ * be described as one. It does not have malware signatures, it does not
+ * emulate, unpack or detonate anything, and a novel trojan with a correct PDF
+ * header passes it without a murmur. It is *structural validation*: it reads
+ * the first few kilobytes of an upload and answers three questions the
+ * platform previously could not ask at all.
+ *
+ * 1. **Are these bytes an executable?** A Windows PE, an ELF binary, a Mach-O
+ *    binary or an installer package is refused whatever it claims to be. This
+ *    is the single highest-value check here: the Sept-1 risk is a customer's
+ *    domain re-serving a trojan to a visitor's browser, and the overwhelming
+ *    majority of that population is a plain executable with a lying name.
+ * 2. **Do the bytes match the declared type?** Media ingress trusted the
+ *    caller's content type completely — AGL-2463 wrote that gap down. The
+ *    allowlist bounded what a file *claimed* to be and nothing bounded what it
+ *    *was*, so `Content-Type: application/pdf` over a `.exe` was stored,
+ *    hashed, given a CDN path and served. It now has to be a PDF.
+ * 3. **Does an Office document carry a macro project?** AGL-1465 kept
+ *    `.docm`/`.xlsm`/`.pptm` out **by content type**, which is a gate on a
+ *    string the uploader chooses. Renaming a macro-enabled document to
+ *    `.docx` walked straight past it. The archive is now checked for a
+ *    `vbaProject.bin` entry, which is the thing that made those extensions
+ *    worth excluding in the first place.
+ *
+ * Plus one signature, EICAR — see {@link EICAR_TEST_SIGNATURE}.
+ *
+ * ## What it therefore does not catch
+ *
+ * A malicious PDF that is a real PDF. A macro-free document that exploits a
+ * reader. Anything inside a plain `application/zip`, which is a brand kit and
+ * may legitimately contain a build tool. An obfuscated dropper in a JSON
+ * file. Real malware detection needs signatures and an engine, which needs a
+ * ClamAV service, which does not fit the budget this platform runs on — the
+ * cost work is in the issue. Nothing here should be allowed to read as though
+ * that decision went the other way.
+ *
+ * ## Why it is pure, and takes a window rather than a file
+ *
+ * Three of the four media chokepoints hold the whole file in memory and can
+ * pass it straight in. The fourth — signed direct-to-storage upload — never
+ * sees the bytes, because that is the entire reason it exists: a 200 MB video
+ * goes browser → bucket and downloading it back into the function to look at
+ * it would cost more than the feature. So that caller does two RANGED reads
+ * instead, a few KB from each end, and passes them as {@link
+ * InspectUploadInput.bytes} and {@link InspectUploadInput.tail}. Every
+ * signature this module knows lives in one of those two windows, so the
+ * signed route gets the same verdict for the price of a rounding error.
+ */ /**
+ * The EICAR standard antivirus test string.
+ *
+ * A 68-byte printable string, defined by the European Institute for Computer
+ * Antivirus Research, that every antivirus product agrees to flag and that is
+ * completely inert. It exists so that a pipeline can be tested end to end
+ * without anyone handling a live sample.
+ *
+ * It is matched here for exactly two reasons, and neither is malware
+ * detection. First, it makes this module's own tests honest without checking
+ * a real sample into the repository. Second, it is the probe a security
+ * reviewer or a customer will actually try, and answering it with silence
+ * would be a worse lie than answering it with a refusal — a refusal that says
+ * "structural check" is true, where a silent accept invites the reader to
+ * conclude nothing is checked at all.
+ *
+ * **This is a signature list of one. It is not an engine.** Do not add a
+ * second entry here and start calling the result malware scanning; if real
+ * signatures are wanted, they belong in a scanner service, not in a string
+ * constant.
+ */ export const EICAR_TEST_SIGNATURE = 'X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*';
+/**
+ * How many leading bytes an inspection needs.
+ *
+ * Every magic number checked here sits in the first 16 bytes; the window is
+ * far larger so that the EICAR match and the small-file macro scan have room,
+ * and because the signed route's ranged GET costs the same for 4 KB as for
+ * 64 bytes.
+ */ export const UPLOAD_INSPECTION_HEAD_BYTES = 4096;
+/**
+ * How many trailing bytes an inspection wants for an Office document.
+ *
+ * A ZIP's central directory — the authoritative list of what is inside it —
+ * lives at the end of the file. 64 KB covers the directory of any document
+ * archive this platform accepts (the largest ceiling is a 50 MB `.pptx`, and
+ * its directory is a few KB even with hundreds of embedded images). A
+ * document whose directory is somehow larger than this window degrades to
+ * "macro not found", which is the pre-existing behaviour, not a regression.
+ */ export const UPLOAD_INSPECTION_TAIL_BYTES = 65536;
+const at = (bytes, signature)=>{
+    var _signature_offset;
+    const offset = (_signature_offset = signature.offset) != null ? _signature_offset : 0;
+    if (bytes.length < offset + signature.magic.length) return false;
+    for(let i = 0; i < signature.magic.length; i++){
+        if (bytes[offset + i] !== signature.magic[i]) return false;
+    }
+    return true;
+};
+const ascii = (text)=>Array.from(text, (character)=>character.charCodeAt(0));
+/**
+ * Executable and installer containers, refused whatever the upload claims to
+ * be. This list is deliberately about CONTAINERS, not content: each entry is
+ * a format whose entire purpose is to be run, and none of them has any
+ * business in a media library under any content type.
+ *
+ * `#!` is NOT here on purpose. A shebang is two characters that a legitimate
+ * `text/plain` upload can genuinely open with, it is not executable in a
+ * browser, and the type-mismatch check below already refuses it under every
+ * binary type. Refusing it outright would buy nothing and cost real uploads.
+ */ const EXECUTABLE_SIGNATURES = [
+    {
+        magic: ascii('MZ'),
+        label: 'a Windows executable'
+    },
+    {
+        magic: [
+            0x7f,
+            0x45,
+            0x4c,
+            0x46
+        ],
+        label: 'a Linux executable (ELF)'
+    },
+    {
+        magic: [
+            0xfe,
+            0xed,
+            0xfa,
+            0xce
+        ],
+        label: 'a macOS executable (Mach-O)'
+    },
+    {
+        magic: [
+            0xfe,
+            0xed,
+            0xfa,
+            0xcf
+        ],
+        label: 'a macOS executable (Mach-O)'
+    },
+    {
+        magic: [
+            0xce,
+            0xfa,
+            0xed,
+            0xfe
+        ],
+        label: 'a macOS executable (Mach-O)'
+    },
+    {
+        magic: [
+            0xcf,
+            0xfa,
+            0xed,
+            0xfe
+        ],
+        label: 'a macOS executable (Mach-O)'
+    },
+    // 0xCAFEBABE is both a Java class file and a multi-architecture Mach-O
+    // binary. Both are code; the label names the likelier one for a DAM.
+    {
+        magic: [
+            0xca,
+            0xfe,
+            0xba,
+            0xbe
+        ],
+        label: 'a compiled program'
+    },
+    {
+        magic: ascii('!<arch>'),
+        label: 'an installer package'
+    },
+    {
+        magic: [
+            0xed,
+            0xab,
+            0xee,
+            0xdb
+        ],
+        label: 'an installer package (RPM)'
+    },
+    // Windows shortcut — a .lnk is a launcher, and a classic phishing payload.
+    {
+        magic: [
+            0x4c,
+            0x00,
+            0x00,
+            0x00,
+            0x01,
+            0x14,
+            0x02,
+            0x00
+        ],
+        label: 'a Windows shortcut'
+    }
+];
+/** ZIP, in its three legal opening forms. Every OOXML document is one. */ const ZIP_SIGNATURES = [
+    {
+        magic: [
+            0x50,
+            0x4b,
+            0x03,
+            0x04
+        ],
+        label: 'ZIP'
+    },
+    {
+        magic: [
+            0x50,
+            0x4b,
+            0x05,
+            0x06
+        ],
+        label: 'ZIP'
+    },
+    {
+        magic: [
+            0x50,
+            0x4b,
+            0x07,
+            0x08
+        ],
+        label: 'ZIP'
+    }
+];
+/** Microsoft's pre-2007 container: legacy `.doc`, `.xls`, `.ppt` and `.msi`. */ const OLE_SIGNATURE = {
+    magic: [
+        0xd0,
+        0xcf,
+        0x11,
+        0xe0,
+        0xa1,
+        0xb1,
+        0x1a,
+        0xe1
+    ],
+    label: 'a legacy Office document'
+};
+/** ISO base media (`....ftyp`) — mp4, QuickTime, and the modern image codecs. */ const ISO_BMFF = {
+    magic: ascii('ftyp'),
+    offset: 4,
+    label: 'ISO media'
+};
+/**
+ * Accepted content type → the signatures its bytes may legally start with.
+ *
+ * A type ABSENT from this table is not checked for a match, and that is a
+ * deliberate, load-bearing property rather than a gap to be filled with
+ * guesses. `text/plain`, `text/csv`, `text/markdown`, `application/json` and
+ * `image/svg+xml` are text: they have no magic number, any leading bytes are
+ * legal, and inventing a heuristic for them would refuse real files. They are
+ * still covered by the executable check above, which is the check that
+ * matters for them — an `.exe` renamed `notes.txt` is refused; a CSV that is
+ * merely unusual is not.
+ */ const TYPE_SIGNATURES = {
+    'application/pdf': [
+        {
+            magic: ascii('%PDF-'),
+            label: 'PDF'
+        }
+    ],
+    'application/zip': ZIP_SIGNATURES,
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ZIP_SIGNATURES,
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ZIP_SIGNATURES,
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': ZIP_SIGNATURES,
+    // Word writes RTF under a `.doc` name often enough that refusing it would
+    // be a real false positive, so both containers are legal for this type.
+    'application/msword': [
+        OLE_SIGNATURE,
+        {
+            magic: ascii('{\\rtf'),
+            label: 'RTF'
+        }
+    ],
+    'application/vnd.ms-excel': [
+        OLE_SIGNATURE
+    ],
+    'application/vnd.ms-powerpoint': [
+        OLE_SIGNATURE
+    ],
+    'application/rtf': [
+        {
+            magic: ascii('{\\rtf'),
+            label: 'RTF'
+        }
+    ],
+    'image/png': [
+        {
+            magic: [
+                0x89,
+                0x50,
+                0x4e,
+                0x47,
+                0x0d,
+                0x0a,
+                0x1a,
+                0x0a
+            ],
+            label: 'PNG'
+        }
+    ],
+    'image/jpeg': [
+        {
+            magic: [
+                0xff,
+                0xd8,
+                0xff
+            ],
+            label: 'JPEG'
+        }
+    ],
+    'image/gif': [
+        {
+            magic: ascii('GIF87a'),
+            label: 'GIF'
+        },
+        {
+            magic: ascii('GIF89a'),
+            label: 'GIF'
+        }
+    ],
+    'image/webp': [
+        {
+            magic: ascii('RIFF'),
+            label: 'WebP'
+        }
+    ],
+    'image/bmp': [
+        {
+            magic: ascii('BM'),
+            label: 'BMP'
+        }
+    ],
+    'image/tiff': [
+        {
+            magic: [
+                0x49,
+                0x49,
+                0x2a,
+                0x00
+            ],
+            label: 'TIFF'
+        },
+        {
+            magic: [
+                0x4d,
+                0x4d,
+                0x00,
+                0x2a
+            ],
+            label: 'TIFF'
+        }
+    ],
+    'image/x-icon': [
+        {
+            magic: [
+                0x00,
+                0x00,
+                0x01,
+                0x00
+            ],
+            label: 'icon'
+        }
+    ],
+    'image/vnd.microsoft.icon': [
+        {
+            magic: [
+                0x00,
+                0x00,
+                0x01,
+                0x00
+            ],
+            label: 'icon'
+        }
+    ],
+    'image/avif': [
+        ISO_BMFF
+    ],
+    'image/heic': [
+        ISO_BMFF
+    ],
+    'image/heif': [
+        ISO_BMFF
+    ],
+    'video/mp4': [
+        ISO_BMFF
+    ],
+    'video/quicktime': [
+        ISO_BMFF
+    ],
+    'video/webm': [
+        {
+            magic: [
+                0x1a,
+                0x45,
+                0xdf,
+                0xa3
+            ],
+            label: 'Matroska/WebM'
+        }
+    ]
+};
+/** The OOXML document types whose archive is scanned for a macro project. */ const OOXML_DOCUMENT_TYPES = new Set([
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+]);
+/** The pre-2007 Office types whose OLE directory is scanned for the same. */ const LEGACY_OFFICE_TYPES = new Set([
+    'application/msword',
+    'application/vnd.ms-excel',
+    'application/vnd.ms-powerpoint'
+]);
+/**
+ * Does a caller holding only a head window need to fetch the tail as well?
+ *
+ * Only the macro scan reads the end of a file, and only for document
+ * archives, so this is what lets the signed-upload route skip a second ranged
+ * GET for the 200 MB videos that route exists to carry — which is every
+ * object on it bar a handful of documents.
+ */ export function uploadInspectionNeedsTail(contentType) {
+    return OOXML_DOCUMENT_TYPES.has(contentType) || LEGACY_OFFICE_TYPES.has(contentType);
+}
+const indexOfBytes = (haystack, needle)=>{
+    if (!needle.length || haystack.length < needle.length) return -1;
+    const last = haystack.length - needle.length;
+    outer: for(let i = 0; i <= last; i++){
+        for(let j = 0; j < needle.length; j++){
+            if (haystack[i + j] !== needle[j]) continue outer;
+        }
+        return i;
+    }
+    return -1;
+};
+const contains = (haystack, needle)=>indexOfBytes(haystack, needle) >= 0;
+const EICAR_BYTES = new Uint8Array(ascii(EICAR_TEST_SIGNATURE));
+/** `vbaProject.bin` as an OOXML archive entry name. */ const VBA_ENTRY = new Uint8Array(ascii('vbaProject.bin'));
+/**
+ * `_VBA_PROJECT` as it appears in an OLE directory, which stores stream names
+ * as UTF-16LE. Matching the encoded form rather than the ASCII one is what
+ * keeps this from firing on a document that merely contains the words.
+ */ const OLE_VBA_STREAM = new Uint8Array(ascii('_VBA_PROJECT').flatMap((code)=>[
+        code,
+        0x00
+    ]));
+const describeFile = (fileName)=>{
+    const name = String(fileName != null ? fileName : '').trim();
+    return name ? `"${name}"` : 'This file';
+};
+/**
+ * Inspect an upload's bytes against the type it claims to be.
+ *
+ * Returns `null` when nothing structural is wrong — which, to be explicit, is
+ * NOT a statement that the file is safe. See the module header.
+ */ export function inspectUploadBytes(input) {
+    var _input_tail;
+    const { bytes, contentType, fileName } = input;
+    const head = bytes != null ? bytes : new Uint8Array(0);
+    // A caller that passed the whole file gets the whole file searched for the
+    // trailing structures too; only a ranged caller supplies a separate tail.
+    const tail = (_input_tail = input.tail) != null ? _input_tail : head;
+    const subject = describeFile(fileName);
+    if (!head.length) {
+        return {
+            code: 'empty_file',
+            detected: 'an empty file',
+            message: `${subject} is empty, so there is nothing to store.`
+        };
+    }
+    // 1. The signature list of one. Checked first so that a probe gets the
+    //    answer it is actually asking for, whatever else is also wrong.
+    if (contains(head, EICAR_BYTES) || contains(tail, EICAR_BYTES)) {
+        return {
+            code: 'signature_match',
+            detected: 'the EICAR antivirus test file',
+            message: `${subject} matches the EICAR test signature and was refused by the ` + `upload structure check.`
+        };
+    }
+    // 2. Executable containers, refused under every declared type.
+    for (const signature of EXECUTABLE_SIGNATURES){
+        if (at(head, signature)) {
+            return {
+                code: 'executable_bytes',
+                detected: signature.label,
+                message: `${subject} contains ${signature.label}, which cannot be uploaded ` + `whatever it is named or labeled.`
+            };
+        }
+    }
+    // 3. The declared type against what the bytes actually are.
+    const expected = TYPE_SIGNATURES[contentType];
+    if (expected && !expected.some((signature)=>at(head, signature))) {
+        return {
+            code: 'type_mismatch',
+            detected: `something other than ${expected[0].label}`,
+            message: `${subject} is labeled ${contentType} but its contents are not ` + `${expected[0].label}. Re-save it in the format it claims to be, or ` + `upload it under its real type.`
+        };
+    }
+    // 4. A macro project inside a document whose type is not supposed to have
+    //    one. This is the check the content-type allowlist could never make.
+    if (OOXML_DOCUMENT_TYPES.has(contentType)) {
+        if (contains(head, VBA_ENTRY) || contains(tail, VBA_ENTRY)) {
+            return {
+                code: 'macro_payload',
+                detected: 'an embedded macro project',
+                message: `${subject} contains an embedded macro project. Macro-enabled ` + `documents are not accepted — save it without macros and upload ` + `it again.`
+            };
+        }
+    } else if (LEGACY_OFFICE_TYPES.has(contentType)) {
+        if (contains(head, OLE_VBA_STREAM) || contains(tail, OLE_VBA_STREAM)) {
+            return {
+                code: 'macro_payload',
+                detected: 'an embedded macro project',
+                message: `${subject} contains an embedded macro project. Macro-enabled ` + `documents are not accepted — save it without macros and upload ` + `it again.`
+            };
+        }
+    }
+    return null;
+}
+export default inspectUploadBytes;
+
+//# sourceMappingURL=upload-inspection.js.map

package/src/lib/app-utils/upload-inspection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/upload-inspection.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * STRUCTURAL upload inspection (AGL-1475).\n *\n * ## What this is, and what it is emphatically not\n *\n * This is **not** an antivirus scanner and no code in this module should ever\n * be described as one. It does not have malware signatures, it does not\n * emulate, unpack or detonate anything, and a novel trojan with a correct PDF\n * header passes it without a murmur. It is *structural validation*: it reads\n * the first few kilobytes of an upload and answers three questions the\n * platform previously could not ask at all.\n *\n * 1. **Are these bytes an executable?** A Windows PE, an ELF binary, a Mach-O\n *    binary or an installer package is refused whatever it claims to be. This\n *    is the single highest-value check here: the Sept-1 risk is a customer's\n *    domain re-serving a trojan to a visitor's browser, and the overwhelming\n *    majority of that population is a plain executable with a lying name.\n * 2. **Do the bytes match the declared type?** Media ingress trusted the\n *    caller's content type completely — AGL-2463 wrote that gap down. The\n *    allowlist bounded what a file *claimed* to be and nothing bounded what it\n *    *was*, so `Content-Type: application/pdf` over a `.exe` was stored,\n *    hashed, given a CDN path and served. It now has to be a PDF.\n * 3. **Does an Office document carry a macro project?** AGL-1465 kept\n *    `.docm`/`.xlsm`/`.pptm` out **by content type**, which is a gate on a\n *    string the uploader chooses. Renaming a macro-enabled document to\n *    `.docx` walked straight past it. The archive is now checked for a\n *    `vbaProject.bin` entry, which is the thing that made those extensions\n *    worth excluding in the first place.\n *\n * Plus one signature, EICAR — see {@link EICAR_TEST_SIGNATURE}.\n *\n * ## What it therefore does not catch\n *\n * A malicious PDF that is a real PDF. A macro-free document that exploits a\n * reader. Anything inside a plain `application/zip`, which is a brand kit and\n * may legitimately contain a build tool. An obfuscated dropper in a JSON\n * file. Real malware detection needs signatures and an engine, which needs a\n * ClamAV service, which does not fit the budget this platform runs on — the\n * cost work is in the issue. Nothing here should be allowed to read as though\n * that decision went the other way.\n *\n * ## Why it is pure, and takes a window rather than a file\n *\n * Three of the four media chokepoints hold the whole file in memory and can\n * pass it straight in. The fourth — signed direct-to-storage upload — never\n * sees the bytes, because that is the entire reason it exists: a 200 MB video\n * goes browser → bucket and downloading it back into the function to look at\n * it would cost more than the feature. So that caller does two RANGED reads\n * instead, a few KB from each end, and passes them as {@link\n * InspectUploadInput.bytes} and {@link InspectUploadInput.tail}. Every\n * signature this module knows lives in one of those two windows, so the\n * signed route gets the same verdict for the price of a rounding error.\n */\n\n/**\n * The EICAR standard antivirus test string.\n *\n * A 68-byte printable string, defined by the European Institute for Computer\n * Antivirus Research, that every antivirus product agrees to flag and that is\n * completely inert. It exists so that a pipeline can be tested end to end\n * without anyone handling a live sample.\n *\n * It is matched here for exactly two reasons, and neither is malware\n * detection. First, it makes this module's own tests honest without checking\n * a real sample into the repository. Second, it is the probe a security\n * reviewer or a customer will actually try, and answering it with silence\n * would be a worse lie than answering it with a refusal — a refusal that says\n * \"structural check\" is true, where a silent accept invites the reader to\n * conclude nothing is checked at all.\n *\n * **This is a signature list of one. It is not an engine.** Do not add a\n * second entry here and start calling the result malware scanning; if real\n * signatures are wanted, they belong in a scanner service, not in a string\n * constant.\n */\nexport const EICAR_TEST_SIGNATURE =\n  'X5O!P%@AP[4\\\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*'\n\n/**\n * How many leading bytes an inspection needs.\n *\n * Every magic number checked here sits in the first 16 bytes; the window is\n * far larger so that the EICAR match and the small-file macro scan have room,\n * and because the signed route's ranged GET costs the same for 4 KB as for\n * 64 bytes.\n */\nexport const UPLOAD_INSPECTION_HEAD_BYTES = 4096\n\n/**\n * How many trailing bytes an inspection wants for an Office document.\n *\n * A ZIP's central directory — the authoritative list of what is inside it —\n * lives at the end of the file. 64 KB covers the directory of any document\n * archive this platform accepts (the largest ceiling is a 50 MB `.pptx`, and\n * its directory is a few KB even with hundreds of embedded images). A\n * document whose directory is somehow larger than this window degrades to\n * \"macro not found\", which is the pre-existing behaviour, not a regression.\n */\nexport const UPLOAD_INSPECTION_TAIL_BYTES = 65536\n\nexport type UploadInspectionCode =\n  | 'signature_match'\n  | 'executable_bytes'\n  | 'type_mismatch'\n  | 'macro_payload'\n  | 'empty_file'\n\nexport interface UploadInspectionRefusal {\n  /** Stable machine code — for the API error body, logs and tests. */\n  code: UploadInspectionCode\n  /** What the bytes turned out to be, in words rather than hex. */\n  detected: string\n  /**\n   * The sentence the uploader sees. Names the file and what was found, so\n   * that a merchant who did nothing wrong can tell which of fifty dropped\n   * files was the problem and why.\n   */\n  message: string\n}\n\nexport interface InspectUploadInput {\n  /**\n   * The whole file, or its leading {@link UPLOAD_INSPECTION_HEAD_BYTES}.\n   * Callers holding the whole file pass it and omit `tail`.\n   */\n  bytes: Uint8Array\n  /**\n   * The file's trailing bytes, supplied ONLY by a caller that passed a head\n   * window rather than the whole file. When absent, `bytes` is searched for\n   * the trailing structures too — which is correct precisely because a caller\n   * that omits it is one that handed over the entire file.\n   */\n  tail?: Uint8Array | null\n  /** The type the upload claims to be, already normalized by the caller. */\n  contentType: string\n  /** For the message only. Never used to decide anything. */\n  fileName?: string | null\n}\n\ninterface Signature {\n  /** Bytes to match. */\n  magic: readonly number[]\n  /** Where they start. */\n  offset?: number\n  /** Human name for the refusal message. */\n  label: string\n}\n\nconst at = (bytes: Uint8Array, signature: Signature): boolean => {\n  const offset = signature.offset ?? 0\n  if (bytes.length < offset + signature.magic.length) return false\n  for (let i = 0; i < signature.magic.length; i++) {\n    if (bytes[offset + i] !== signature.magic[i]) return false\n  }\n  return true\n}\n\nconst ascii = (text: string): number[] =>\n  Array.from(text, (character) => character.charCodeAt(0))\n\n/**\n * Executable and installer containers, refused whatever the upload claims to\n * be. This list is deliberately about CONTAINERS, not content: each entry is\n * a format whose entire purpose is to be run, and none of them has any\n * business in a media library under any content type.\n *\n * `#!` is NOT here on purpose. A shebang is two characters that a legitimate\n * `text/plain` upload can genuinely open with, it is not executable in a\n * browser, and the type-mismatch check below already refuses it under every\n * binary type. Refusing it outright would buy nothing and cost real uploads.\n */\nconst EXECUTABLE_SIGNATURES: readonly Signature[] = [\n  { magic: ascii('MZ'), label: 'a Windows executable' },\n  { magic: [0x7f, 0x45, 0x4c, 0x46], label: 'a Linux executable (ELF)' },\n  { magic: [0xfe, 0xed, 0xfa, 0xce], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xfe, 0xed, 0xfa, 0xcf], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xce, 0xfa, 0xed, 0xfe], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xcf, 0xfa, 0xed, 0xfe], label: 'a macOS executable (Mach-O)' },\n  // 0xCAFEBABE is both a Java class file and a multi-architecture Mach-O\n  // binary. Both are code; the label names the likelier one for a DAM.\n  { magic: [0xca, 0xfe, 0xba, 0xbe], label: 'a compiled program' },\n  { magic: ascii('!<arch>'), label: 'an installer package' },\n  { magic: [0xed, 0xab, 0xee, 0xdb], label: 'an installer package (RPM)' },\n  // Windows shortcut — a .lnk is a launcher, and a classic phishing payload.\n  { magic: [0x4c, 0x00, 0x00, 0x00, 0x01, 0x14, 0x02, 0x00], label: 'a Windows shortcut' },\n]\n\n/** ZIP, in its three legal opening forms. Every OOXML document is one. */\nconst ZIP_SIGNATURES: readonly Signature[] = [\n  { magic: [0x50, 0x4b, 0x03, 0x04], label: 'ZIP' },\n  { magic: [0x50, 0x4b, 0x05, 0x06], label: 'ZIP' },\n  { magic: [0x50, 0x4b, 0x07, 0x08], label: 'ZIP' },\n]\n\n/** Microsoft's pre-2007 container: legacy `.doc`, `.xls`, `.ppt` and `.msi`. */\nconst OLE_SIGNATURE: Signature = {\n  magic: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n  label: 'a legacy Office document',\n}\n\n/** ISO base media (`....ftyp`) — mp4, QuickTime, and the modern image codecs. */\nconst ISO_BMFF: Signature = { magic: ascii('ftyp'), offset: 4, label: 'ISO media' }\n\n/**\n * Accepted content type → the signatures its bytes may legally start with.\n *\n * A type ABSENT from this table is not checked for a match, and that is a\n * deliberate, load-bearing property rather than a gap to be filled with\n * guesses. `text/plain`, `text/csv`, `text/markdown`, `application/json` and\n * `image/svg+xml` are text: they have no magic number, any leading bytes are\n * legal, and inventing a heuristic for them would refuse real files. They are\n * still covered by the executable check above, which is the check that\n * matters for them — an `.exe` renamed `notes.txt` is refused; a CSV that is\n * merely unusual is not.\n */\nconst TYPE_SIGNATURES: Readonly<Record<string, readonly Signature[]>> = {\n  'application/pdf': [{ magic: ascii('%PDF-'), label: 'PDF' }],\n  'application/zip': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation': ZIP_SIGNATURES,\n  // Word writes RTF under a `.doc` name often enough that refusing it would\n  // be a real false positive, so both containers are legal for this type.\n  'application/msword': [OLE_SIGNATURE, { magic: ascii('{\\\\rtf'), label: 'RTF' }],\n  'application/vnd.ms-excel': [OLE_SIGNATURE],\n  'application/vnd.ms-powerpoint': [OLE_SIGNATURE],\n  'application/rtf': [{ magic: ascii('{\\\\rtf'), label: 'RTF' }],\n\n  'image/png': [{ magic: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], label: 'PNG' }],\n  'image/jpeg': [{ magic: [0xff, 0xd8, 0xff], label: 'JPEG' }],\n  'image/gif': [\n    { magic: ascii('GIF87a'), label: 'GIF' },\n    { magic: ascii('GIF89a'), label: 'GIF' },\n  ],\n  'image/webp': [{ magic: ascii('RIFF'), label: 'WebP' }],\n  'image/bmp': [{ magic: ascii('BM'), label: 'BMP' }],\n  'image/tiff': [\n    { magic: [0x49, 0x49, 0x2a, 0x00], label: 'TIFF' },\n    { magic: [0x4d, 0x4d, 0x00, 0x2a], label: 'TIFF' },\n  ],\n  'image/x-icon': [{ magic: [0x00, 0x00, 0x01, 0x00], label: 'icon' }],\n  'image/vnd.microsoft.icon': [{ magic: [0x00, 0x00, 0x01, 0x00], label: 'icon' }],\n  'image/avif': [ISO_BMFF],\n  'image/heic': [ISO_BMFF],\n  'image/heif': [ISO_BMFF],\n\n  'video/mp4': [ISO_BMFF],\n  'video/quicktime': [ISO_BMFF],\n  'video/webm': [{ magic: [0x1a, 0x45, 0xdf, 0xa3], label: 'Matroska/WebM' }],\n}\n\n/** The OOXML document types whose archive is scanned for a macro project. */\nconst OOXML_DOCUMENT_TYPES = new Set([\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation',\n])\n\n/** The pre-2007 Office types whose OLE directory is scanned for the same. */\nconst LEGACY_OFFICE_TYPES = new Set([\n  'application/msword',\n  'application/vnd.ms-excel',\n  'application/vnd.ms-powerpoint',\n])\n\n/**\n * Does a caller holding only a head window need to fetch the tail as well?\n *\n * Only the macro scan reads the end of a file, and only for document\n * archives, so this is what lets the signed-upload route skip a second ranged\n * GET for the 200 MB videos that route exists to carry — which is every\n * object on it bar a handful of documents.\n */\nexport function uploadInspectionNeedsTail(contentType: string): boolean {\n  return (\n    OOXML_DOCUMENT_TYPES.has(contentType) || LEGACY_OFFICE_TYPES.has(contentType)\n  )\n}\n\nconst indexOfBytes = (haystack: Uint8Array, needle: Uint8Array): number => {\n  if (!needle.length || haystack.length < needle.length) return -1\n  const last = haystack.length - needle.length\n  outer: for (let i = 0; i <= last; i++) {\n    for (let j = 0; j < needle.length; j++) {\n      if (haystack[i + j] !== needle[j]) continue outer\n    }\n    return i\n  }\n  return -1\n}\n\nconst contains = (haystack: Uint8Array, needle: Uint8Array): boolean =>\n  indexOfBytes(haystack, needle) >= 0\n\nconst EICAR_BYTES = new Uint8Array(ascii(EICAR_TEST_SIGNATURE))\n\n/** `vbaProject.bin` as an OOXML archive entry name. */\nconst VBA_ENTRY = new Uint8Array(ascii('vbaProject.bin'))\n\n/**\n * `_VBA_PROJECT` as it appears in an OLE directory, which stores stream names\n * as UTF-16LE. Matching the encoded form rather than the ASCII one is what\n * keeps this from firing on a document that merely contains the words.\n */\nconst OLE_VBA_STREAM = new Uint8Array(\n  ascii('_VBA_PROJECT').flatMap((code) => [code, 0x00]),\n)\n\nconst describeFile = (fileName?: string | null): string => {\n  const name = String(fileName ?? '').trim()\n  return name ? `\"${name}\"` : 'This file'\n}\n\n/**\n * Inspect an upload's bytes against the type it claims to be.\n *\n * Returns `null` when nothing structural is wrong — which, to be explicit, is\n * NOT a statement that the file is safe. See the module header.\n */\nexport function inspectUploadBytes(\n  input: InspectUploadInput,\n): UploadInspectionRefusal | null {\n  const { bytes, contentType, fileName } = input\n  const head = bytes ?? new Uint8Array(0)\n  // A caller that passed the whole file gets the whole file searched for the\n  // trailing structures too; only a ranged caller supplies a separate tail.\n  const tail = input.tail ?? head\n  const subject = describeFile(fileName)\n\n  if (!head.length) {\n    return {\n      code: 'empty_file',\n      detected: 'an empty file',\n      message: `${subject} is empty, so there is nothing to store.`,\n    }\n  }\n\n  // 1. The signature list of one. Checked first so that a probe gets the\n  //    answer it is actually asking for, whatever else is also wrong.\n  if (contains(head, EICAR_BYTES) || contains(tail, EICAR_BYTES)) {\n    return {\n      code: 'signature_match',\n      detected: 'the EICAR antivirus test file',\n      message:\n        `${subject} matches the EICAR test signature and was refused by the ` +\n        `upload structure check.`,\n    }\n  }\n\n  // 2. Executable containers, refused under every declared type.\n  for (const signature of EXECUTABLE_SIGNATURES) {\n    if (at(head, signature)) {\n      return {\n        code: 'executable_bytes',\n        detected: signature.label,\n        message:\n          `${subject} contains ${signature.label}, which cannot be uploaded ` +\n          `whatever it is named or labeled.`,\n      }\n    }\n  }\n\n  // 3. The declared type against what the bytes actually are.\n  const expected = TYPE_SIGNATURES[contentType]\n  if (expected && !expected.some((signature) => at(head, signature))) {\n    return {\n      code: 'type_mismatch',\n      detected: `something other than ${expected[0].label}`,\n      message:\n        `${subject} is labeled ${contentType} but its contents are not ` +\n        `${expected[0].label}. Re-save it in the format it claims to be, or ` +\n        `upload it under its real type.`,\n    }\n  }\n\n  // 4. A macro project inside a document whose type is not supposed to have\n  //    one. This is the check the content-type allowlist could never make.\n  if (OOXML_DOCUMENT_TYPES.has(contentType)) {\n    if (contains(head, VBA_ENTRY) || contains(tail, VBA_ENTRY)) {\n      return {\n        code: 'macro_payload',\n        detected: 'an embedded macro project',\n        message:\n          `${subject} contains an embedded macro project. Macro-enabled ` +\n          `documents are not accepted — save it without macros and upload ` +\n          `it again.`,\n      }\n    }\n  } else if (LEGACY_OFFICE_TYPES.has(contentType)) {\n    if (contains(head, OLE_VBA_STREAM) || contains(tail, OLE_VBA_STREAM)) {\n      return {\n        code: 'macro_payload',\n        detected: 'an embedded macro project',\n        message:\n          `${subject} contains an embedded macro project. Macro-enabled ` +\n          `documents are not accepted — save it without macros and upload ` +\n          `it again.`,\n      }\n    }\n  }\n\n  return null\n}\n\nexport default inspectUploadBytes\n"],"names":["EICAR_TEST_SIGNATURE","UPLOAD_INSPECTION_HEAD_BYTES","UPLOAD_INSPECTION_TAIL_BYTES","at","bytes","signature","offset","length","magic","i","ascii","text","Array","from","character","charCodeAt","EXECUTABLE_SIGNATURES","label","ZIP_SIGNATURES","OLE_SIGNATURE","ISO_BMFF","TYPE_SIGNATURES","OOXML_DOCUMENT_TYPES","Set","LEGACY_OFFICE_TYPES","uploadInspectionNeedsTail","contentType","has","indexOfBytes","haystack","needle","last","outer","j","contains","EICAR_BYTES","Uint8Array","VBA_ENTRY","OLE_VBA_STREAM","flatMap","code","describeFile","fileName","name","String","trim","inspectUploadBytes","input","head","tail","subject","detected","message","expected","some"],"mappings":"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"}

package/src/lib/app-utils/url-slug.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * One path segment of a public URL, derived from something a human typed.
+ *
+ * Lowercase, runs of non-alphanumerics collapsed to a single `-`, no leading
+ * or trailing dash. Deliberately LOSSY and IDEMPOTENT: the same subject
+ * addresses the same URL whether the caller passes a stored id, a display
+ * name, or the segment itself. `Open source` → `open-source` → `open-source`.
+ *
+ * ## Why this is one function and not two
+ *
+ * The category route (AGL-1321) and the author route (AGL-2518) both have to
+ * answer the same question twice, in two directions: BUILD a link from a
+ * record, and MATCH an incoming segment back to that record. Four call sites
+ * for one rule — and they only work because all four normalize identically.
+ * Two implementations that agree today are a bug waiting for whichever one is
+ * edited first, and the failure is silent: the archive simply comes back
+ * empty, which is also what an author with no posts looks like.
+ *
+ * Not to be confused with `slugifyDatasetFieldId` or `slugifyHeading`, which
+ * are not URL segments and have their own rules (an identifier may not start
+ * with a digit; a heading anchor keeps its own collision suffixes).
+ */
+export declare function urlSlugSegment(value: string | undefined | null): string;
+export default urlSlugSegment;

package/src/lib/app-utils/url-slug.js

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * One path segment of a public URL, derived from something a human typed.
+ *
+ * Lowercase, runs of non-alphanumerics collapsed to a single `-`, no leading
+ * or trailing dash. Deliberately LOSSY and IDEMPOTENT: the same subject
+ * addresses the same URL whether the caller passes a stored id, a display
+ * name, or the segment itself. `Open source` → `open-source` → `open-source`.
+ *
+ * ## Why this is one function and not two
+ *
+ * The category route (AGL-1321) and the author route (AGL-2518) both have to
+ * answer the same question twice, in two directions: BUILD a link from a
+ * record, and MATCH an incoming segment back to that record. Four call sites
+ * for one rule — and they only work because all four normalize identically.
+ * Two implementations that agree today are a bug waiting for whichever one is
+ * edited first, and the failure is silent: the archive simply comes back
+ * empty, which is also what an author with no posts looks like.
+ *
+ * Not to be confused with `slugifyDatasetFieldId` or `slugifyHeading`, which
+ * are not URL segments and have their own rules (an identifier may not start
+ * with a digit; a heading anchor keeps its own collision suffixes).
+ */ export function urlSlugSegment(value) {
+    return String(value != null ? value : '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export default urlSlugSegment;
+
+//# sourceMappingURL=url-slug.js.map