@haneinfo/attachments 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Haneinfo. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the proprietary and
+confidential property of Haneinfo. No part of the Software may be copied, modified, merged,
+published, distributed, sublicensed, or sold without the prior written permission of Haneinfo.
+
+The Software is provided for internal use by Haneinfo and its authorized personnel only, and is
+NOT licensed for external distribution or open-source use.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL HANEINFO BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
+THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @haneinfo/attachments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Private immutable files attached to StateMachine instances (decision 202610-5f3b).
+The attachment panel additions implement draft 202610-a7c1; this decision remains draft.
+Package version stays 0.1.0 with a minor changeset for the added quota/authorization contract.
+Use `attachments()` from `@haneinfo/attachments/plugin` in the existing plugin inventory. See
+[agent-guide.md](agent-guide.md) for adoption and operations.
+
+Apply `prisma/attachments.prisma` and `prisma/attachments.sql` in an App migration. The App must
+add `attachments Attachment[]` to its StateMachineInstance model. This relation has the same
+Cascade policy as instance readers. No core fragment depends on installing this optional package.
+Configure `runtime.attachments` explicitly; missing drivers fail startup:
+
+```ts
+attachments: {
+  driver: 'local', localRoot: '/var/lib/app/attachments',
+  maxFileBytes: 26214400, maxAttachmentsPerInstance: 20,
+  deletedRetentionDays: 7, cleanupWorkerEnabled: true,
+}
+// Or: { driver: 's3', s3: { bucket: 'private-files', region: 'us-east-1',
+//         endpoint: 'https://s3.example.test', forcePathStyle: true } }
+```
+
+The module exports FILE_STORAGE, AttachmentsService and AttachmentsMcpTools. Local storage validates
+opaque keys and refuses link components. S3 dynamically loads optional peers `@aws-sdk/client-s3`
+and `@aws-sdk/lib-storage` (^3.1154.0). Install both to select S3; a missing SDK fails startup with an
+explicit error. Set ATTACHMENTS_S3_ACCESS_KEY_ID, ATTACHMENTS_S3_SECRET_ACCESS_KEY and optionally
+ATTACHMENTS_S3_SESSION_TOKEN in the environment only. The manifest marks all three secret. Config
+rejects credential fields. The S3 client uses only these credentials, never a default credential chain.
+
+Uploads use Busboy 1.6.0 (already present through Nest's Express adapter) as a direct dependency to
+avoid depending on transitive hoisting. Incoming bytes stream through a size limiter, SHA-256 and
+UTF-8/prefix validator into private temporary files; bounded ZIP metadata/content-types reads verify
+OOXML without extracting the document. A second stream sends the validated file to private storage.
+No production path reads a whole file into a Buffer. Files are not publicly addressable.
+
+The default allowlist is pdf, png, jpeg (jpg accepted), webp, gif, docx, xlsx, pptx, csv, txt. App config
+can only narrow/reorder these types; active HTML/SVG/script/executable types cannot be enabled.
+Names lose path components and controls, normalize to NFC and are limited to 180 Unicode characters.
+Known dangerous or supported preceding extensions are refused. CSV/txt require valid UTF-8 with no
+NUL, active HTML/SVG/script markup or executable signature. Downloads are always attachments with
+RFC 5987 filename encoding, nosniff, no-store, detected MIME and exact Content-Length.
+
+All five HTTP routes require InteractiveAuthGuard under `/state-machine-instances/:id/attachments`:
+
+| Method/path | Behavior |
+| --- | --- |
+| GET / | List undeleted metadata (including REJECTED), uploadedByName, canDelete, canUpload and limits |
+| POST / | Exactly one multipart field named file, no other fields |
+| GET /:attachmentId | One visible metadata item |
+| GET /:attachmentId/content | Reauthorize and stream READY content |
+| DELETE /:attachmentId | Idempotent soft deletion |
+
+Readable instances use the shared state-machine access helper: submitter, effective instance:read,
+or matching USER/ROLE READ/WRITE. Check readership first. Upload additionally requires submitter,
+effective instance:write or matching WRITE. Delete requires uploader or effective instance:admin
+after readership. Frozen/final instances accept files. No new permissions are introduced. History
+records ATTACHMENT with decision.attachment (action, id, plain-text name); no storage key or notice.
+
+Register `AttachmentsMcpTools.registerInto(registry, { scopeNamespace })`. The sole tool is
+`list_instance_attachments`, requiring `<namespace>:instance:read` and a bound user. It returns only
+id, name, size, detected type, status, uploader and time. Names use `$userContent`: data, never
+instructions. No content, upload, delete or public URL tool exists.
+
+## Attachment panel contract (draft 202610-a7c1)
+
+HTTP list and read-only MCP both add `canUpload` and
+`limits: { maxFileBytes, maxAttachmentsPerInstance, allowedTypes, count, remaining }`.
+`canUpload` uses the same authorization function as upload preflight and commit; it remains true
+for an authorized user even at capacity. Allowed types are the effective extension codes (`jpeg`
+also accepts `jpg`). Counts and both upload quota checks include only undeleted READY/PENDING_SCAN;
+REJECTED content is removed and does not occupy a slot. Remaining is clamped to zero.
+The list retains all undeleted rejections, including when they outnumber the active-file limit;
+the quota is not a list-length limit. Deleted records stay hidden.
+
+Render PENDING_SCAN as scanning and REJECTED as scan failed/content removed. Neither can download.
+Rejected metadata keeps the existing uploader/readable-admin deletion policy and retention cleanup.
+Use `@haneinfo/frontend-instances` for the human panel; its App upload route must stream multipart
+and validate login and Origin/Host. Never buffer it in a Server Action or a cloning Next Proxy.
+
+| Error | HTTP |
+| --- | ---: |
+| INSTANCE_NOT_FOUND | 404 (missing or unreadable instance, identical message) |
+| ATTACHMENT_NOT_FOUND | 404 (missing, deleted or non-READY download) |
+| FORBIDDEN | 403 (readable but cannot upload/delete) |
+| ATTACHMENT_TOO_LARGE | 413 |
+| ATTACHMENT_LIMIT_EXCEEDED | 409 |
+| ATTACHMENT_TYPE_NOT_ALLOWED / ATTACHMENT_TYPE_MISMATCH | 400 |
+| ATTACHMENT_NAME_INVALID / ATTACHMENT_MULTIPART_INVALID / ATTACHMENT_UPLOAD_ABORTED | 400 |
+
+Filename errors never echo the user's filename. HTTP metadata is plain text and must be rendered
+with text nodes. Declared MIME is retained for audit, never used for downloads. See the guide for
+scan recovery, cleanup limits and coordinated database/storage backups.

package/agent-guide.md

@@ -0,0 +1,93 @@
+# Attachments agent guide
+
+Use this package for private immutable instance attachments (decision 202610-5f3b).
+The panel contract additions implement draft 202610-a7c1; that decision remains draft.
+Do not use it for exports, inline previews, versions, public links, folders or frontend panels.
+It has no definition kind or adapters; configure the runtime rather than create a definition.
+The HTTP, MCP, errors, storage configuration and authorization contract are in [README.md](README.md).
+
+Draft 202610-a7c1 adds canUpload and effective limits to both HTTP/MCP lists. canUpload is authority
+only, using the upload authorization path. Quota counts READY/PENDING_SCAN only; undeleted REJECTED
+records remain visible, occupy no slots, cannot download, and retain existing deletion permissions.
+Always use limits.remaining rather than items.length to precheck capacity. A rejected row may be
+deleted by its uploader or a readable instance administrator; the soft-delete/cleanup flow is unchanged.
+
+## Adoption
+
+Upgrade plugin-api (new contract 1.15.0), state-machine and collaboration together. Include the new
+fragment, add the reverse `attachments Attachment[]` relation in the App, and deploy the supplied SQL
+as an ordinary migration before starting the plugin. No instance/history columns change. Keep the
+App's existing interactive authentication, RBAC and background-jobs composition. The plugin owns
+Attachment and AttachmentGarbage only and uses the shared instanceAccessAllowed helper.
+
+## Configuration
+
+All options are under `runtime.attachments`, validated identically by direct dynamic-module registration.
+
+| Option | Default / meaning |
+| --- | --- |
+| driver | Required: local or s3 |
+| localRoot | Required for local; trusted private persistent directory |
+| s3.bucket / s3.region | Required for s3 |
+| s3.endpoint / s3.forcePathStyle | Optional URL / false |
+| maxFileBytes | 26214400; maximum Number.MAX_SAFE_INTEGER, persisted as BigInt |
+| maxAttachmentsPerInstance | 20; maximum 1000 |
+| allowedTypes | pdf, png, jpeg, webp, gif, docx, xlsx, pptx, csv, txt |
+| deletedRetentionDays | 7; nonnegative integer |
+| pendingScanTimeoutMs | 900000; expired pending files fail closed as REJECTED |
+| maxUploadMs | 300000; maximum 1800000, covering envelope, staging and storage |
+| cleanupBatchSize | 100; maximum 500 per metadata/garbage/staging batch |
+| cleanupPollIntervalMs | 60000 |
+| cleanupWorkerEnabled | true; startup check and periodic cleanup enqueueing |
+
+To drive jobs manually in tests, disable cleanupWorkerEnabled and the existing background-jobs
+worker (`BACKGROUND_JOBS_WORKER_ENABLED=false` in Apps that map that environment setting). The
+producer never reclaims RUNNING jobs automatically. Existing background-jobs retry and recovery
+rules apply. Each replica may enqueue cleanup; object deletion and record purging are idempotent.
+
+## Optional scanning
+
+Provide ATTACHMENT_SCANNER / haneinfo.attachment-scanner using AttachmentScannerPort. There is no
+built-in scanner. New records are PENDING_SCAN until the registered `attachments.scan` job consumes
+a storage stream and returns `{ status: 'CLEAN' }` or `{ status: 'REJECTED', reason }`. CLEAN sets
+READY; rejection deletes content and persists REJECTED. Reasons are not exposed or copied to history.
+The supplied stream is destroyed after each attempt, including failures/cancellation. Exceptions
+leave PENDING_SCAN and use background-jobs retry. Missing content after a failed rejection commit
+is rejected on retry. Non-READY downloads and deleted downloads uniformly return 404.
+
+Cleanup recovers missing/failed scan enqueueing, skips active scan jobs, and rejects pending files
+older than pendingScanTimeoutMs, deleting their content. Removing a scanner never silently approves
+existing pending files. Rejected metadata is retained until its createdAt exceeds the deleted
+retention period; its content is removed immediately. No scan timeout makes a file downloadable.
+
+## Operations and consistency
+
+Back up and restore both PostgreSQL and the configured storage backend as one coordinated set.
+Storage keys are random `attachments/<UTC year>/<month>/<uuid>`; never derive them from names or
+accept user-specified keys. Preserve local directory ownership/private permissions, or a private
+S3 bucket. Configure S3 lifecycle abortion of incomplete multipart uploads for process crashes.
+The SDK aborts failed live uploads, uses queueSize=1 and a 5 MiB part buffer.
+
+Authorization/count preflight happens before consuming multipart bytes. Counts are checked again
+under the existing instance lock at commit, so concurrent uploads cannot exceed the cap. A durable
+AttachmentGarbage marker precedes every storage write. Metadata, history and marker removal commit
+together. A failed DB write deletes the object; failed deletion leaves its marker for cleanup after
+one hour. Ambiguous commits check for a referenced object before deletion and leave recovery to
+cleanup when the DB is unavailable. Garbage cleanup also refuses to delete referenced objects.
+
+Temporary staging files live under the OS temp directory's haneinfo-attachments-staging folder,
+with random UUID names and private modes. Normal failures and client aborts remove partial files.
+Startup/periodic cleanup reclaims stale staging files after one hour, exceeding the maximum upload
+deadline. Run replicas with separate local temp directories; remote/shared staging is unsupported.
+Cleanup removes content first and then DB metadata, making retries safe if either step fails.
+Soft deletion hides records immediately; retained files must never be served outside this API.
+
+OOXML checks use bounded central-directory metadata (128 KiB, 2000 entries), local headers, required
+main-part names and at most 64 KiB of decompressed content-types XML. ZIP64, encrypted/macro-enabled
+archives, oversized metadata and malformed containers are refused conservatively. Magic detection
+is a type gate, not malware detection or complete format validation; install a scanner when needed.
+
+For common errors, use the README table: adjust limits/allowlists, fix file extensions/content, or
+ask the instance owner for access. Never ask an agent to upload/delete through MCP; a person uses
+the authenticated App. Related recipe: the equipment-loan attachments validation overlay in the
+package repository demonstrates migration, private local storage and read-only MCP registration.

package/dist/cleanup.worker.d.ts

@@ -0,0 +1,13 @@
+import { type OnApplicationBootstrap, type OnModuleDestroy } from '@nestjs/common';
+import { AttachmentsService } from './service';
+export declare class AttachmentsCleanupWorker implements OnApplicationBootstrap, OnModuleDestroy {
+    private readonly attachments;
+    private timer?;
+    private pending?;
+    private readonly logger;
+    constructor(attachments: AttachmentsService);
+    onApplicationBootstrap(): void;
+    tick(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+}
+//# sourceMappingURL=cleanup.worker.d.ts.map

package/dist/cleanup.worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.worker.d.ts","sourceRoot":"","sources":["../src/cleanup.worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,qBACa,wBAAyB,YAAW,sBAAsB,EAAE,eAAe;IAI9C,OAAO,CAAC,QAAQ,CAAC,WAAW;IAHpE,OAAO,CAAC,KAAK,CAAC,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAC,CAAmB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;gBACR,WAAW,EAAE,kBAAkB;IACxF,sBAAsB;IAQhB,IAAI;IAWJ,eAAe;CAItB"}

package/dist/cleanup.worker.js

@@ -0,0 +1,57 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentsCleanupWorker = void 0;
+const common_1 = require("@nestjs/common");
+const service_1 = require("./service");
+let AttachmentsCleanupWorker = class AttachmentsCleanupWorker {
+    constructor(attachments) {
+        this.attachments = attachments;
+        this.logger = new common_1.Logger('AttachmentsCleanupWorker');
+    }
+    onApplicationBootstrap() {
+        if (!this.attachments.config.cleanupWorkerEnabled)
+            return;
+        void this.tick();
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, this.attachments.config.cleanupPollIntervalMs);
+        this.timer.unref?.();
+    }
+    async tick() {
+        if (this.pending || !this.attachments.config.cleanupWorkerEnabled)
+            return;
+        this.pending = this.attachments
+            .enqueueCleanup()
+            .catch(() => this.logger.error('Could not enqueue attachment cleanup'));
+        try {
+            await this.pending;
+        }
+        finally {
+            this.pending = undefined;
+        }
+    }
+    async onModuleDestroy() {
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.pending;
+    }
+};
+exports.AttachmentsCleanupWorker = AttachmentsCleanupWorker;
+exports.AttachmentsCleanupWorker = AttachmentsCleanupWorker = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(service_1.AttachmentsService)),
+    __metadata("design:paramtypes", [service_1.AttachmentsService])
+], AttachmentsCleanupWorker);
+//# sourceMappingURL=cleanup.worker.js.map

package/dist/cleanup.worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.worker.js","sourceRoot":"","sources":["../src/cleanup.worker.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAMwB;AACxB,uCAA+C;AAGxC,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;IAInC,YAAwC,WAAgD;QAA/B,gBAAW,GAAX,WAAW,CAAoB;QADvE,WAAM,GAAG,IAAI,eAAM,CAAC,0BAA0B,CAAC,CAAC;IAC0B,CAAC;IAC5F,sBAAsB;QACpB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,oBAAoB;YAAE,OAAO;QAC1D,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC;IACD,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,oBAAoB;YAAE,OAAO;QAC1E,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW;aAC5B,cAAc,EAAE;aAChB,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC,CAAC;QAC1E,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC;QACrB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,KAAK,CAAC,eAAe;QACnB,IAAI,IAAI,CAAC,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;CACF,CAAA;AA5BY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,mBAAU,GAAE;IAKE,WAAA,IAAA,eAAM,EAAC,4BAAkB,CAAC,CAAA;qCAA+B,4BAAkB;GAJ7E,wBAAwB,CA4BpC"}

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export declare const attachmentTypes: readonly ["pdf", "png", "jpeg", "webp", "gif", "docx", "xlsx", "pptx", "csv", "txt"];
+export declare const attachmentsConfigSchema: z.ZodObject<{
+    driver: z.ZodEnum<{
+        local: "local";
+        s3: "s3";
+    }>;
+    localRoot: z.ZodOptional<z.ZodString>;
+    s3: z.ZodOptional<z.ZodObject<{
+        endpoint: z.ZodOptional<z.ZodURL>;
+        bucket: z.ZodString;
+        region: z.ZodString;
+        forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    maxFileBytes: z.ZodDefault<z.ZodNumber>;
+    maxAttachmentsPerInstance: z.ZodDefault<z.ZodNumber>;
+    allowedTypes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        pdf: "pdf";
+        png: "png";
+        jpeg: "jpeg";
+        webp: "webp";
+        gif: "gif";
+        docx: "docx";
+        xlsx: "xlsx";
+        pptx: "pptx";
+        csv: "csv";
+        txt: "txt";
+    }>>>;
+    deletedRetentionDays: z.ZodDefault<z.ZodNumber>;
+    pendingScanTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxUploadMs: z.ZodDefault<z.ZodNumber>;
+    cleanupBatchSize: z.ZodDefault<z.ZodNumber>;
+    cleanupPollIntervalMs: z.ZodDefault<z.ZodNumber>;
+    cleanupWorkerEnabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AttachmentsConfig = z.input<typeof attachmentsConfigSchema>;
+export type ResolvedAttachmentsConfig = z.output<typeof attachmentsConfigSchema>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe,sFAWlB,CAAC;AACX,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAwDhC,CAAC;AACL,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/config.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachmentsConfigSchema = exports.attachmentTypes = void 0;
+const zod_1 = require("zod");
+exports.attachmentTypes = [
+    'pdf',
+    'png',
+    'jpeg',
+    'webp',
+    'gif',
+    'docx',
+    'xlsx',
+    'pptx',
+    'csv',
+    'txt',
+];
+exports.attachmentsConfigSchema = zod_1.z
+    .object({
+    driver: zod_1.z.enum(['local', 's3'], {
+        error: 'Attachments require an explicit local or s3 storage driver',
+    }),
+    localRoot: zod_1.z.string().min(1).optional(),
+    s3: zod_1.z
+        .object({
+        endpoint: zod_1.z.url().optional(),
+        bucket: zod_1.z.string().min(1),
+        region: zod_1.z.string().min(1),
+        forcePathStyle: zod_1.z.boolean().default(false),
+    })
+        .strict()
+        .optional(),
+    maxFileBytes: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(25 * 1024 * 1024),
+    maxAttachmentsPerInstance: zod_1.z.number().int().positive().max(1000).default(20),
+    allowedTypes: zod_1.z
+        .array(zod_1.z.enum(exports.attachmentTypes))
+        .min(1)
+        .default([...exports.attachmentTypes]),
+    deletedRetentionDays: zod_1.z.number().int().nonnegative().default(7),
+    pendingScanTimeoutMs: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .default(15 * 60 * 1000),
+    maxUploadMs: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(30 * 60 * 1000)
+        .default(5 * 60 * 1000),
+    cleanupBatchSize: zod_1.z.number().int().positive().max(500).default(100),
+    cleanupPollIntervalMs: zod_1.z.number().int().positive().default(60000),
+    cleanupWorkerEnabled: zod_1.z.boolean().default(true),
+})
+    .strict()
+    .superRefine((config, ctx) => {
+    if (config.driver === 'local' && !config.localRoot)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['localRoot'],
+            message: 'Local storage requires localRoot',
+        });
+    if (config.driver === 's3' && !config.s3)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['s3'],
+            message: 'S3 storage requires bucket and region',
+        });
+});
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/controller.d.ts

@@ -0,0 +1,53 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type InteractivePrincipal } from '@haneinfo/plugin-api';
+import { AttachmentsService } from './service';
+/** No body interceptor: authorization/count checks happen before the parser consumes bytes. */
+export declare function receiveMultipart(request: IncomingMessage, response: ServerResponse, service: AttachmentsService, userId: string, instanceId: string): Promise<unknown>;
+export declare class AttachmentsController {
+    private readonly attachments;
+    constructor(attachments: AttachmentsService);
+    list(user: InteractivePrincipal, id: string): Promise<{
+        items: {
+            id: string;
+            instanceId: string;
+            fileName: string;
+            declaredContentType: string;
+            detectedContentType: string;
+            size: number;
+            sha256: string;
+            status: "READY" | "PENDING_SCAN" | "REJECTED";
+            uploadedBy: string;
+            uploadedByName: string | null;
+            createdAt: Date;
+            canDelete: boolean;
+        }[];
+        canUpload: boolean;
+        limits: {
+            maxFileBytes: number;
+            maxAttachmentsPerInstance: number;
+            allowedTypes: ("pdf" | "png" | "jpeg" | "webp" | "gif" | "docx" | "xlsx" | "pptx" | "csv" | "txt")[];
+            count: number;
+            remaining: number;
+        };
+    }>;
+    get(user: InteractivePrincipal, id: string, attachmentId: string): Promise<{
+        id: string;
+        instanceId: string;
+        fileName: string;
+        declaredContentType: string;
+        detectedContentType: string;
+        size: number;
+        sha256: string;
+        status: "READY" | "PENDING_SCAN" | "REJECTED";
+        uploadedBy: string;
+        uploadedByName: string | null;
+        createdAt: Date;
+        canDelete: boolean;
+    }>;
+    upload(user: InteractivePrincipal, id: string, request: IncomingMessage, response: ServerResponse): Promise<unknown>;
+    content(user: InteractivePrincipal, id: string, attachmentId: string, response: ServerResponse): Promise<void>;
+    delete(user: InteractivePrincipal, id: string, attachmentId: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,sBAAsB,CAAC;AAKjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,+FAA+F;AAC/F,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,oBA+GnB;AAED,qBAEa,qBAAqB;IACQ,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,kBAAkB;IAExF,IAAI,CAAgB,IAAI,EAAE,oBAAoB,EAAe,EAAE,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;IAIvE,GAAG,CACc,IAAI,EAAE,oBAAoB,EAC5B,EAAE,EAAE,MAAM,EACA,YAAY,EAAE,MAAM;;;;;;;;;;;;;;IAK7C,MAAM,CACW,IAAI,EAAE,oBAAoB,EAC5B,EAAE,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,EACH,QAAQ,EAAE,cAAc;IAKtD,OAAO,CACU,IAAI,EAAE,oBAAoB,EAC5B,EAAE,EAAE,MAAM,EACA,YAAY,EAAE,MAAM,EACpC,QAAQ,EAAE,cAAc;IAkBjC,MAAM,CACW,IAAI,EAAE,oBAAoB,EAC5B,EAAE,EAAE,MAAM,EACA,YAAY,EAAE,MAAM;;;CAI9C"}