@haneinfo/attachments 0.0.0-stage → 0.1.0

package/dist/validation.js

@@ -0,0 +1,297 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReadStream = exports.mimeTypes = exports.STAGING_ROOT = void 0;
+exports.cleanFileName = cleanFileName;
+exports.downloadHeaders = downloadHeaders;
+exports.stageUpload = stageUpload;
+exports.cleanupStaging = cleanupStaging;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+Object.defineProperty(exports, "createReadStream", { enumerable: true, get: function () { return node_fs_1.createReadStream; } });
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+const node_zlib_1 = require("node:zlib");
+const plugin_api_1 = require("@haneinfo/plugin-api");
+const config_1 = require("./config");
+exports.STAGING_ROOT = node_path_1.default.join(node_os_1.default.tmpdir(), 'haneinfo-attachments-staging');
+const dangerous = new Set([
+    'exe',
+    'dll',
+    'com',
+    'bat',
+    'cmd',
+    'ps1',
+    'psm1',
+    'sh',
+    'bash',
+    'js',
+    'mjs',
+    'cjs',
+    'vbs',
+    'vbe',
+    'wsf',
+    'wsh',
+    'hta',
+    'msi',
+    'scr',
+    'pif',
+    'jar',
+    'php',
+    'py',
+    'pl',
+    'rb',
+    'html',
+    'htm',
+    'xhtml',
+    'svg',
+    'asp',
+    'aspx',
+    'jsp',
+    'lnk',
+    'url',
+]);
+exports.mimeTypes = {
+    pdf: 'application/pdf',
+    png: 'image/png',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    csv: 'text/csv',
+    txt: 'text/plain',
+};
+const canonical = (extension) => (extension === 'jpg' ? 'jpeg' : extension);
+function cleanFileName(raw) {
+    // Keep user names as text only; storage keys never use them.
+    const name = raw
+        .replace(/[\uD800-\uDFFF]/gu, '')
+        .normalize('NFC')
+        .split(/[\\/]/)
+        .pop()
+        ?.replace(/[\p{Cc}\p{Cf}]/gu, '')
+        .trim() ?? '';
+    const parts = name.toLowerCase().split('.');
+    const extension = canonical(parts.pop() ?? '');
+    if (!name || !parts.some(Boolean) || !extension)
+        throw new plugin_api_1.MechanismError('ATTACHMENT_NAME_INVALID', 'A nonempty file name and extension are required');
+    if (dangerous.has(extension) ||
+        parts.some((part) => dangerous.has(part) || config_1.attachmentTypes.includes(canonical(part))))
+        throw new plugin_api_1.MechanismError('ATTACHMENT_TYPE_NOT_ALLOWED', 'Active content or double extensions are not allowed');
+    const suffix = name.slice(name.lastIndexOf('.'));
+    return {
+        fileName: [...name.slice(0, -suffix.length)].slice(0, 180 - [...suffix].length).join('') + suffix,
+        extension,
+    };
+}
+function downloadHeaders(record) {
+    const encoded = encodeURIComponent(record.fileName).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return {
+        'Content-Disposition': `attachment; filename*=UTF-8''${encoded}`,
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+        'Content-Type': record.detectedContentType,
+        'Content-Length': String(record.size),
+    };
+}
+function signature(bytes) {
+    if (bytes.subarray(0, 5).toString() === '%PDF-')
+        return 'pdf';
+    if (bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')))
+        return 'png';
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'jpeg';
+    if (/^GIF8[79]a/.test(bytes.subarray(0, 6).toString()))
+        return 'gif';
+    if (bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WEBP')
+        return 'webp';
+    if (bytes.subarray(0, 4).equals(Buffer.from('504b0304', 'hex')))
+        return 'zip';
+    return null;
+}
+const mismatch = () => new plugin_api_1.MechanismError('ATTACHMENT_TYPE_MISMATCH', 'File contents do not match the allowed extension');
+function checkPrefix(bytes, extension) {
+    const detected = signature(bytes);
+    if (['docx', 'xlsx', 'pptx'].includes(extension)) {
+        if (detected !== 'zip')
+            throw mismatch();
+    }
+    else if (extension === 'txt' || extension === 'csv') {
+        if (detected ||
+            /^(?:MZ|\x7fELF|#!)|^\s*(?:<!doctype\s+html|<html\b|<svg\b|<script\b|<\?php)/i.test(bytes.toString('utf8').replace(/^\uFEFF/, '')))
+            throw mismatch();
+    }
+    else if (detected !== extension)
+        throw mismatch();
+}
+/** Read bounded ZIP metadata and only the content-types XML, never unpack the document. */
+async function verifyOffice(file, size, extension) {
+    const handle = await (0, promises_1.open)(file, 'r');
+    const read = async (position, length) => {
+        if (position < 0 || length < 0 || position + length > size || length > 128 * 1024)
+            throw mismatch();
+        const buffer = Buffer.alloc(length);
+        if ((await handle.read(buffer, 0, length, position)).bytesRead !== length)
+            throw mismatch();
+        return buffer;
+    };
+    try {
+        const tail = await read(Math.max(0, size - 65557), Math.min(size, 65557));
+        let end = tail.length - 22;
+        while (end >= 0 && tail.readUInt32LE(end) !== 0x06054b50)
+            end--;
+        if (end < 0 ||
+            end + 22 + tail.readUInt16LE(end + 20) !== tail.length ||
+            tail.readUInt16LE(end + 4) ||
+            tail.readUInt16LE(end + 6))
+            throw mismatch();
+        const entries = tail.readUInt16LE(end + 10), centralSize = tail.readUInt32LE(end + 12), centralOffset = tail.readUInt32LE(end + 16);
+        if (!entries ||
+            entries > 2000 ||
+            tail.readUInt16LE(end + 8) !== entries ||
+            centralOffset + centralSize !== size - tail.length + end)
+            throw mismatch();
+        const central = await read(centralOffset, centralSize);
+        const main = {
+            docx: 'word/document.xml',
+            xlsx: 'xl/workbook.xml',
+            pptx: 'ppt/presentation.xml',
+        }[extension];
+        let offset = 0, hasMain = false, types;
+        const names = new Set();
+        for (let index = 0; index < entries; index++) {
+            if (offset + 46 > central.length || central.readUInt32LE(offset) !== 0x02014b50)
+                throw mismatch();
+            const flags = central.readUInt16LE(offset + 8), method = central.readUInt16LE(offset + 10);
+            const compressed = central.readUInt32LE(offset + 20), expanded = central.readUInt32LE(offset + 24);
+            const nameLength = central.readUInt16LE(offset + 28), extra = central.readUInt16LE(offset + 30), comment = central.readUInt16LE(offset + 32);
+            const localOffset = central.readUInt32LE(offset + 42);
+            const endOffset = offset + 46 + nameLength + extra + comment;
+            if (endOffset > central.length || flags & 1 || ![0, 8].includes(method))
+                throw mismatch();
+            const name = central.subarray(offset + 46, offset + 46 + nameLength).toString('utf8');
+            if (names.has(name) || /(?:^|\/)\.\.(?:\/|$)|\\|vbaProject\.bin$/i.test(name))
+                throw mismatch();
+            names.add(name);
+            const header = await read(localOffset, 30);
+            if (header.readUInt32LE(0) !== 0x04034b50 ||
+                header.readUInt16LE(8) !== method ||
+                header.readUInt16LE(6) !== flags)
+                throw mismatch();
+            const localName = await read(localOffset + 30, header.readUInt16LE(26));
+            if (localName.toString('utf8') !== name)
+                throw mismatch();
+            const start = localOffset + 30 + localName.length + header.readUInt16LE(28);
+            if (start + compressed > centralOffset)
+                throw mismatch();
+            if (name === main)
+                hasMain = expanded > 0;
+            if (name === '[Content_Types].xml') {
+                if (expanded > 65536 || compressed > 65536)
+                    throw mismatch();
+                const data = await read(start, compressed);
+                types = method === 8 ? (0, node_zlib_1.inflateRawSync)(data, { maxOutputLength: 65536 }) : data;
+                if (types.length !== expanded)
+                    throw mismatch();
+            }
+            offset = endOffset;
+        }
+        if (offset !== central.length ||
+            !hasMain ||
+            !types ||
+            !types.toString('utf8').includes(`PartName="/${main}"`) ||
+            !types.toString('utf8').includes(`${exports.mimeTypes[extension]}.main+xml`))
+            throw mismatch();
+    }
+    catch {
+        throw mismatch();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function stageUpload(stream, id, extension, config, signal) {
+    await (0, promises_1.mkdir)(exports.STAGING_ROOT, { recursive: true, mode: 0o700 });
+    const file = node_path_1.default.join(exports.STAGING_ROOT, id);
+    let size = 0, prefix = Buffer.alloc(0), checked = false, textTail = '';
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    const text = extension === 'txt' || extension === 'csv'
+        ? new TextDecoder('utf-8', { fatal: true })
+        : undefined;
+    const validator = new node_stream_1.Transform({
+        transform(chunk, _encoding, callback) {
+            try {
+                size += chunk.length;
+                if (size > config.maxFileBytes)
+                    throw new plugin_api_1.MechanismError('ATTACHMENT_TOO_LARGE', 'The file exceeds maxFileBytes', 413);
+                if (prefix.length < 512)
+                    prefix = Buffer.concat([prefix, chunk.subarray(0, 512 - prefix.length)]);
+                if (!checked && prefix.length >= 512) {
+                    checkPrefix(prefix, extension);
+                    checked = true;
+                }
+                if (text) {
+                    if (chunk.includes(0))
+                        throw mismatch();
+                    const decoded = textTail + text.decode(chunk, { stream: true });
+                    if (/<(?:html|svg|script)\b|<!doctype\s+html|<\?php/i.test(decoded))
+                        throw mismatch();
+                    textTail = decoded.slice(-64);
+                }
+                hash.update(chunk);
+                callback(null, chunk);
+            }
+            catch (error) {
+                callback(error instanceof plugin_api_1.MechanismError ? error : mismatch());
+            }
+        },
+    });
+    try {
+        await (0, promises_2.pipeline)(stream, validator, (0, node_fs_1.createWriteStream)(file, { flags: 'wx', mode: 0o600 }), {
+            signal,
+        });
+        if (!size)
+            throw mismatch();
+        checkPrefix(prefix, extension);
+        if (text) {
+            try {
+                text.decode();
+            }
+            catch {
+                throw mismatch();
+            }
+        }
+        if (['docx', 'xlsx', 'pptx'].includes(extension))
+            await verifyOffice(file, size, extension);
+        return { file, size, sha256: hash.digest('hex'), detectedContentType: exports.mimeTypes[extension] };
+    }
+    catch (error) {
+        await (0, promises_1.rm)(file, { force: true });
+        throw error;
+    }
+}
+async function cleanupStaging(before, limit) {
+    await (0, promises_1.mkdir)(exports.STAGING_ROOT, { recursive: true, mode: 0o700 });
+    let removed = 0;
+    const directory = await (0, promises_1.opendir)(exports.STAGING_ROOT);
+    for await (const entry of directory) {
+        if (removed >= limit)
+            break;
+        if (!entry.isFile() || !/^[0-9a-f-]{36}$/.test(entry.name))
+            continue;
+        const file = node_path_1.default.join(exports.STAGING_ROOT, entry.name);
+        if ((await (0, promises_1.stat)(file)).mtime < before) {
+            await (0, promises_1.rm)(file, { force: true });
+            removed++;
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/haneinfo.plugin.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": "haneinfo.plugin/v1",
+  "id": "attachments",
+  "displayName": "Attachments",
+  "cardinality": "singleton",
+  "distribution": "official",
+  "engine": {
+    "haneinfoPluginApi": "^1.15.0",
+    "node": ">=22.0.0",
+    "frameworks": {
+      "@nestjs/common": "^11.0.5",
+      "@nestjs/core": "^11.0.5",
+      "@prisma/client": "^6.2.0"
+    }
+  },
+  "provides": ["haneinfo.file-storage"],
+  "requires": [
+    "haneinfo.prisma",
+    "haneinfo.principal-context",
+    "haneinfo.state-machine-runtime",
+    "haneinfo.background-jobs"
+  ],
+  "optionalRequires": [
+    "haneinfo.rbac-policy",
+    "haneinfo.identity-store",
+    "haneinfo.attachment-scanner"
+  ],
+  "configSchema": {
+    "configRef": "attachments"
+  },
+  "environment": [
+    {
+      "key": "ATTACHMENTS_S3_ACCESS_KEY_ID",
+      "required": false,
+      "secret": true
+    },
+    {
+      "key": "ATTACHMENTS_S3_SECRET_ACCESS_KEY",
+      "required": false,
+      "secret": true
+    },
+    {
+      "key": "ATTACHMENTS_S3_SESSION_TOKEN",
+      "required": false,
+      "secret": true
+    }
+  ],
+  "facets": {
+    "backend": {
+      "modulePath": "./dist/module.js",
+      "exportName": "AttachmentsModule",
+      "controllerRoutes": ["state-machine-instances/:id/attachments"],
+      "providerTokens": ["haneinfo.file-storage"],
+      "mcpTools": [
+        {
+          "name": "list_instance_attachments",
+          "requiredScopes": ["{namespace}:instance:read"]
+        }
+      ],
+      "workers": ["haneinfo.attachments.cleanup-enqueuer"],
+      "agentGuide": "./agent-guide.md"
+    },
+    "prisma": {
+      "owns": ["Attachment", "AttachmentGarbage"],
+      "schemaFragment": "prisma/attachments.prisma",
+      "schemaDigest": "sha256:c279fae0fd8881a58d3dc35f48fad41900ffcf86bdc66adbb830cb3fa04444ec"
+    },
+    "permissions": {
+      "definitions": []
+    }
+  }
+}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@haneinfo/attachments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "description": "Private streaming instance attachments, storage drivers, scanning and retention.",
+  "files": [
+    "dist",
+    "prisma",
+    "agent-guide.md",
+    "haneinfo.plugin.json",
+    "plugin.js",
+    "plugin.d.ts",
+    "README.md"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./haneinfo.plugin.json": "./haneinfo.plugin.json",
+    "./agent-guide.md": "./agent-guide.md",
+    "./package.json": "./package.json",
+    "./prisma/attachments.prisma": "./prisma/attachments.prisma"
+  },
+  "dependencies": {
+    "busboy": "1.6.0",
+    "@haneinfo/plugin-api": "1.15.0"
+  },
+  "peerDependencies": {
+    "@haneinfo/common": "^0.3.4 || ^0.4.0",
+    "@haneinfo/plugin-host-nest": "^2.0.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@prisma/client": "^6.19.0",
+    "zod": "^4.4.0",
+    "@haneinfo/plugin-api": "^1.15.0",
+    "@haneinfo/state-machine": "^0.11.0 || ^0.12.0",
+    "@aws-sdk/client-s3": "^3.1154.0",
+    "@aws-sdk/lib-storage": "^3.1154.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@prisma/client": "^6.19.0",
+    "@types/node": "^24.13.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.0",
+    "@aws-sdk/client-s3": "3.1154.0",
+    "@aws-sdk/lib-storage": "3.1154.0",
+    "@types/busboy": "1.5.5",
+    "@haneinfo/plugin-host-nest": "2.1.0",
+    "@haneinfo/plugin-testkit": "2.3.0",
+    "@haneinfo/common": "0.4.0",
+    "@haneinfo/state-machine": "0.12.0"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/plugin.d.ts

@@ -0,0 +1,2 @@
+// See plugin.js for why this file exists (classic/node10 moduleResolution compatibility shim).
+export * from './dist/plugin';

package/plugin.js

@@ -0,0 +1,4 @@
+// Compatibility shim for consumers whose TypeScript config uses "classic"/"node10"
+// moduleResolution, which resolves `@haneinfo/attachments/plugin` by looking for a real file
+// at the package root -- it does not consult package.json's "exports" map at all.
+module.exports = require('./dist/plugin');

package/prisma/attachments.prisma

@@ -0,0 +1,32 @@
+/// Immutable private file metadata. Add attachments Attachment[] to StateMachineInstance in the App.
+model Attachment {
+  id                  String               @id @default(uuid())
+  instanceId          String               @map("instance_id")
+  instance            StateMachineInstance @relation(fields: [instanceId], references: [id], onDelete: Cascade)
+  fileName            String               @map("file_name")
+  declaredContentType String               @map("declared_content_type")
+  detectedContentType String               @map("detected_content_type")
+  size                BigInt
+  sha256              String
+  storageKey          String               @unique @map("storage_key")
+  /// READY, PENDING_SCAN or REJECTED.
+  status              String
+  uploadedBy          String               @map("uploaded_by")
+  createdAt           DateTime             @default(now()) @map("created_at")
+  deletedAt           DateTime?            @map("deleted_at")
+  deletedBy           String?              @map("deleted_by")
+
+  @@index([instanceId, deletedAt])
+  @@index([deletedAt])
+  @@index([status, createdAt])
+  @@map("attachments")
+}
+
+/// Write-ahead recovery marker. Created before storage writes and removed with metadata commit.
+model AttachmentGarbage {
+  storageKey String   @id @map("storage_key")
+  notBefore  DateTime @map("not_before")
+
+  @@index([notBefore])
+  @@map("attachment_garbage")
+}

package/prisma/attachments.sql

@@ -0,0 +1,13 @@
+CREATE TABLE attachments (
+ id TEXT PRIMARY KEY, instance_id TEXT NOT NULL REFERENCES state_machine_instances(id) ON DELETE CASCADE,
+ file_name TEXT NOT NULL, declared_content_type TEXT NOT NULL, detected_content_type TEXT NOT NULL,
+ size BIGINT NOT NULL CHECK (size >= 0), sha256 TEXT NOT NULL, storage_key TEXT NOT NULL UNIQUE,
+ status TEXT NOT NULL CHECK (status IN ('READY','PENDING_SCAN','REJECTED')),
+ uploaded_by TEXT NOT NULL, created_at TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ deleted_at TIMESTAMP(3), deleted_by TEXT
+);
+CREATE INDEX attachments_instance_id_deleted_at_idx ON attachments(instance_id, deleted_at);
+CREATE INDEX attachments_deleted_at_idx ON attachments(deleted_at);
+CREATE INDEX attachments_status_created_at_idx ON attachments(status, created_at);
+CREATE TABLE attachment_garbage (storage_key TEXT PRIMARY KEY, not_before TIMESTAMP(3) NOT NULL);
+CREATE INDEX attachment_garbage_not_before_idx ON attachment_garbage(not_before);