@jini-ai/daemon 0.3.8 → 0.5.0

package/dist/http/attachments.d.ts

@@ -0,0 +1,618 @@
+import type { Express, Request, Response } from 'express';
+import type { AdapterContext } from '@jini-ai/http-kit';
+/**
+ * A staged upload as it crosses the wire and as `claim()` returns it.
+ *
+ * Deliberately declared here rather than imported from `@jini-ai/chat/core`, whose `ChatAttachment`
+ * this mirrors field-for-field: the same reason `media.ts` declares its own `MediaTask`/
+ * `MediaDispatchEngine` port types instead of depending on `@jini-ai/media`. A transport package
+ * should not acquire a dependency on a *domain* package (`jini.domain: "chat"`) to describe an
+ * upload that has nothing chat-specific about it. `attachments.test.ts` holds a compile-time
+ * assignability check in both directions against the real `ChatAttachment`, so the mirror cannot
+ * silently drift — the drift risk is paid for with a test rather than with a dependency edge.
+ *
+ * `path` means two different things at two different times, on purpose:
+ * - as returned by `register()` / over the wire: an opaque `attachment:<uuid>` capability id;
+ * - as returned by `claim()`: the real absolute filesystem path, server-side only.
+ */
+export interface StoredAttachment {
+    path: string;
+    name: string;
+    kind: 'image' | 'file';
+    size?: number;
+    /**
+     * User-visible ordering for the turn that carries this attachment. Present for exact structural
+     * parity with `ChatAttachment`; this store never sets it, because display ordering is the
+     * renderer's concern and nothing here would be able to reconstruct it.
+     */
+    order?: number;
+}
+/** What `claim()` hands back: trusted paths plus the one directory an agent may be granted. */
+export interface AttachmentClaim {
+    attachments: StoredAttachment[];
+    /** Absent only for an empty claim — there is no directory to grant when nothing was claimed. */
+    batchDirectory?: string;
+}
+/** Why an attachment operation was refused. Maps to an HTTP status in `statusForRejection`. */
+export type AttachmentRejectionReason = 
+/** The batch id is missing or not of the accepted shape. */
+'invalid-batch'
+/** One file exceeded the per-attachment byte cap. */
+ | 'attachment-too-large'
+/** The batch already holds `maxAttachments` files. */
+ | 'batch-count-exceeded'
+/** This file would push the batch past `maxBatchBytes`. */
+ | 'batch-too-large'
+/** The store as a whole is at `maxStoredAttachments` / `maxStoredBytes`. */
+ | 'storage-full'
+/** Nothing was uploaded — a zero-byte body. */
+ | 'empty-attachment'
+/** More concurrent uploads than `maxConcurrentUploads`. */
+ | 'too-many-concurrent-uploads'
+/** The cleanup request body was not a `{ batchId, paths }` of the accepted shape. */
+ | 'invalid-cleanup-request'
+/**
+ * The request stream was already drained before this route saw it — a host body-parser ordering
+ * problem, not anything the caller did. See this module's doc.
+ */
+ | 'attachment-body-consumed'
+/**
+ * The stored file is not the canonical regular file it was registered as. Reported opaquely over
+ * HTTP: this means either a bug or an active attempt to redirect a claim.
+ */
+ | 'attachment-integrity'
+/** More attachments in one claim than `maxAttachments` allows. */
+ | 'too-many-attachments'
+/** The same capability id appeared twice in one claim. */
+ | 'duplicate-attachment'
+/** No such capability id, or a run already claimed it. */
+ | 'attachment-unknown-or-claimed'
+/** One claim spanned more than one batch. */
+ | 'mixed-batch';
+/**
+ * A refusal this module classified itself, as opposed to an unexpected filesystem/programming
+ * error. The route pack turns the `reason` into a status code and lets the `message` through only
+ * for caller-safe rejections below 500. Classified server-side failures and unexpected errors are
+ * redacted to a generic `INTERNAL_ERROR`, preserving the server-state disclosure boundary.
+ */
+export declare class AttachmentRejectedError extends Error {
+    readonly reason: AttachmentRejectionReason;
+    constructor({ reason, message }: {
+        readonly reason: AttachmentRejectionReason;
+        readonly message: string;
+    }, _optional?: Record<string, never>);
+}
+/**
+ * Registers, validates, and expires uploads staged for a run. `createDiskAttachmentStore` is the
+ * implementation this package ships; a host with its own storage (object store, tmpfs, a quota
+ * system of its own) can satisfy this port instead and keep the route pack.
+ */
+export interface AttachmentStore {
+    /** Creates (idempotently) the private directory that holds one batch's files. */
+    createBatchDirectory: ({ batchId }: {
+        readonly batchId: string;
+    }, _optional?: Record<string, never>) => Promise<string>;
+    /**
+     * Takes ownership of an already-written file and returns its opaque capability record. Rejects —
+     * and deletes the file — if it is not a canonical regular file directly inside its batch
+     * directory, or if any quota would be exceeded.
+     */
+    register: (requiredArgs: {
+        readonly input: {
+            batchId: string;
+            path: string;
+            name: string;
+            kind: StoredAttachment['kind'];
+            size: number;
+            /** See `AttachmentRecord.ownerId`'s own doc. Omitted by a host with no owner concept. */
+            ownerId?: string;
+        };
+    }, optionalArgs?: Record<string, never>) => Promise<StoredAttachment>;
+    /** Exchanges capability ids for real paths, exactly once, binding them to `runId`. */
+    claim: ({ attachments, runId }: {
+        readonly attachments: readonly StoredAttachment[];
+        readonly runId: string;
+    }, _optional?: Record<string, never>) => Promise<AttachmentClaim>;
+    /**
+     * Resolves ONE still-known attachment to its real path for `runId`, without the "exactly once
+     * across the whole batch" shape `claim()` has — the read-side counterpart for a caller that wants
+     * to look up a single attachment it may or may not already own, rather than atomically reserving a
+     * batch at run start.
+     *
+     * `ref` accepts either identifier a caller may actually be holding: the opaque `attachment:<uuid>`
+     * capability id `register()` returned, or the real absolute path this run was already told about.
+     * Both resolve to the same record. This dual form exists because `@jini-ai/daemon`'s
+     * `image-prompt-delivery.ts` narrates the resolved PATH into the run's prompt text for an
+     * already-claimed attachment — never the id — so a caller built from that prompt has the path, not
+     * the id; a caller with the id (from the original upload response) can still use it directly.
+     *
+     * Ownership is enforced here, which is new: an attachment nobody has claimed yet is claimed for
+     * `runId` on this call (identical effect to `claim()`, same integrity re-check); an attachment
+     * already claimed BY `runId` is simply re-verified and returned again (idempotent — a run may look
+     * this up more than once); an attachment claimed by any OTHER run throws the same
+     * `'attachment-unknown-or-claimed'` rejection `claim()` uses for a genuinely unknown id, so a
+     * caller cannot distinguish "no such attachment" from "a different run owns this" — the same
+     * non-disclosure `claim()` already practices for its own rejections. This is the run-ownership
+     * check `claim()`'s own FIRST reservation does not have (see this module's trust-model doc on the
+     * deliberate capability-bearer model for a brand-new claim); `resolveForRun` adds it for every
+     * lookup made through this method, so a second run/session on this same daemon can never read an
+     * attachment already bound to someone else's run by calling this method with a guessed or
+     * overheard `ref`.
+     *
+     * Returns `undefined` only for a `ref` this store has never heard of (never uploaded, or its
+     * record was already deleted by `cleanupRun`/`pruneExpired`/`dispose`).
+     */
+    resolveForRun: ({ ref, runId }: {
+        readonly ref: string;
+        readonly runId: string;
+    }, _optional?: Record<string, never>) => Promise<StoredAttachment | undefined>;
+    /**
+     * Lists every still-unclaimed attachment registered with `ownerId` — the discovery counterpart to
+     * `resolveForRun`'s single-lookup: a caller that does not yet hold a specific ref at all (an
+     * attachment uploaded in an earlier turn, never named in this run's prompt) has no id to look up
+     * with `resolveForRun` in the first place. This is what makes that attachment findable.
+     *
+     * **This is the one method in this port that widens the trust model documented at the top of this
+     * file.** `register()`/`claim()`/`resolveForRun` all work from a caller-supplied opaque id or path
+     * — the "you must already hold the unguessable capability" property that makes an unauthenticated
+     * `claim()` first-reservation safe. A listing necessarily hands back ids the caller never held, so
+     * it can only be safe if it is scoped to something the caller is actually entitled to — here, the
+     * same principal id a host recorded via `register()`'s `ownerId` for the ORIGINAL upload request.
+     *
+     * Two things make that scoping real rather than decorative:
+     * - an attachment registered with NO `ownerId` (a host that never wired `resolveOwnerId`, or any
+     *   attachment from before this method existed) is excluded from every caller's results, never
+     *   just "unscoped" — this method is not callable with `ownerId: undefined`, so there is no input
+     *   that could accidentally match an ownerless record;
+     * - a claimed attachment is excluded outright, whether or not this caller's own `runId` claimed
+     *   it, so this method can never be used to re-discover something already handed to a run — the
+     *   same "runs, not listings, are the reach here" boundary `resolveForRun` draws for a single ref.
+     *
+     * What this does NOT scope by: batch, conversation, or run — none of those are recorded on an
+     * `AttachmentRecord` today. Two different conversations run by the SAME `ownerId` will each see
+     * the other's pending attachments through this method. A host for whom that is too wide needs a
+     * finer-grained id than `ownerId` to pass into `register()` — this method does not itself assume
+     * `ownerId` means "one admin account" rather than "one conversation, one composer, one browser
+     * tab"; it only assumes the host's `ownerId` is something the CALLER of this method is authorized
+     * to see everything under.
+     *
+     * Sorted oldest-first (`createdAt` ascending) — arrival order, matching how a person would expect
+     * to review what is waiting.
+     *
+     * @complexity O(n) in the number of tracked records (bounded by `maxStoredAttachments`), matching
+     * every other method on this port.
+     */
+    listPendingForOwner: ({ ownerId }: {
+        readonly ownerId: string;
+    }, _optional?: Record<string, never>) => Promise<PendingAttachmentSummary[]>;
+    /** Deletes the named still-unclaimed uploads, then the batch directory if it is now empty. */
+    deleteUnclaimed: ({ batchId, paths }: {
+        readonly batchId: string;
+        readonly paths: readonly string[];
+    }, _optional?: Record<string, never>) => Promise<void>;
+    /** Deletes everything `runId` claimed. Safe to call for a run that claimed nothing. */
+    cleanupRun: ({ runId }: {
+        readonly runId: string;
+    }, _optional?: Record<string, never>) => Promise<void>;
+    /** Deletes unclaimed uploads older than the retention window. */
+    pruneExpired: (_required: Record<string, never>, optionalArgs?: {
+        readonly now?: number | undefined;
+    }) => Promise<void>;
+    /** Deletes every tracked upload. For host shutdown. */
+    dispose: () => Promise<void>;
+}
+export interface CreateDiskAttachmentStoreOptions {
+    /** Root directory this store owns outright — it is emptied on construction. */
+    readonly uploadDirectory: string;
+    /** Files per batch, i.e. per composer turn. Also caps one `claim()`. Defaults to 10. */
+    readonly maxAttachments?: number;
+    /** Total bytes per batch. Defaults to 50 MB. */
+    readonly maxBatchBytes?: number;
+    /** Tracked files across all batches. Defaults to 100. */
+    readonly maxStoredAttachments?: number;
+    /** Tracked bytes across all batches. Defaults to 200 MB. */
+    readonly maxStoredBytes?: number;
+    /** How long an unclaimed upload survives `pruneExpired`. Defaults to one hour. */
+    readonly retentionMs?: number;
+    /**
+     * Adopts the uploads a previous process left behind instead of emptying the directory on
+     * construction, so an attachment staged seconds before a restart is still there — and still
+     * listable — afterwards.
+     *
+     * **Defaults to `false`, which is exactly this pack's pre-existing behavior.** Opting in is a
+     * one-word change at the call site and reverting is deleting it; nothing about a store
+     * constructed without this option differs in any way from before the option existed.
+     *
+     * Adoption is authenticated, not blind: see {@link loadPersistedAttachments}.
+     */
+    readonly retainAcrossRestarts?: boolean;
+}
+/**
+ * `true` when `body` opens with an ISO-BMFF `ftyp` box whose major brand or compatible-brand list
+ * names AVIF. This is a line-for-line mirror of the CMS package's `content-type-sniffer.ts`
+ * `isAvif` (no shared dependency exists between HTTP kit and the CMS package today — see
+ * this module's handoff notes on whether extracting one is worth it): the major brand alone is not
+ * sufficient, because a great many real AVIF files declare the generic `mif1` (HEIF image) major
+ * brand and name `avif` only in the compatible-brand list, so both are checked. HEIC declares
+ * neither and is therefore never matched here — deliberate; nothing downstream of this attachment
+ * store has confirmed it can render a HEIC as an `<img>`, so labelling one `'image'` would risk the
+ * same "sniffed as a type the surface cannot actually display" failure this whole fix addresses.
+ *
+ * Must run before any generic `ftyp` check: {@link hasIsoBmffFtypTag} alone cannot tell AVIF, HEIC,
+ * and MP4 apart, so a brand-blind caller would misclassify every ISO-BMFF file it sees as one type.
+ */
+export declare function hasAvifSignature({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): boolean;
+export interface AttachmentRecord {
+    id: string;
+    filePath: string;
+    name: string;
+    kind: StoredAttachment['kind'];
+    size: number;
+    batchId: string;
+    batchDirectory: string;
+    dev: number;
+    ino: number;
+    createdAt: number;
+    claimedRunId?: string;
+    /**
+     * The principal a host's `AttachmentsHttpDeps.resolveOwnerId` reported for the request that
+     * registered this attachment. Absent when the host supplies no `resolveOwnerId` (this pack's
+     * behavior before ownership existed), which is why `listPendingForOwner` treats an absent
+     * `ownerId` as "cannot be scoped" rather than as a wildcard match — see that method's own doc.
+     */
+    ownerId?: string;
+}
+/**
+ * What `listPendingForOwner` hands back for one still-unclaimed attachment: enough for a caller to
+ * show a person what is waiting, and to name it again (`ref`) to `claim()`/`resolveForRun`.
+ */
+export interface PendingAttachmentSummary {
+    /** The same opaque `attachment:<uuid>` id `register()` returned over the wire. */
+    ref: string;
+    name: string;
+    kind: StoredAttachment['kind'];
+    size: number;
+    /** `Date.now()` at registration — when the file arrived, not when it was looked up. */
+    createdAt: number;
+}
+/** What registration recorded about a file, as `isUnchangedAttachment` needs it. */
+export interface RecordedAttachmentIdentity {
+    readonly filePath: string;
+    readonly dev: number;
+    readonly ino: number;
+    readonly size: number;
+}
+/**
+ * What the filesystem reports about a file right now — the subset of `fs.Stats` (plus `realpath`)
+ * an integrity check needs.
+ *
+ * `isRegularFile` comes from `lstat().isFile()`, which is false for a symlink *and* for a
+ * directory. There is deliberately no separate `isSymbolicLink` field: `lstat` reports exactly one
+ * file type, so `isFile()` and `isSymbolicLink()` are mutually exclusive and a symlink check after
+ * an `isFile()` check could never be the deciding one.
+ */
+export interface ObservedAttachmentIdentity {
+    readonly isRegularFile: boolean;
+    readonly dev: number;
+    readonly ino: number;
+    readonly size: number;
+    /** `realpath` of the file — differs from its own path when any path component became a symlink. */
+    readonly canonicalPath: string;
+}
+/**
+ * `true` when the file on disk is still the same file registration accepted.
+ *
+ * Every condition is a distinct real attack: a regular file swapped for a symlink or directory, a
+ * parent directory swapped for a symlink pointing elsewhere, the file replaced by a different file
+ * at the same path (new inode), the same inode truncated or appended to (new size), or the path
+ * now resolving onto a different device.
+ *
+ * Pure and exported on purpose. Staging a *device* change for a file that keeps its path is not
+ * something a test can do on a real filesystem, and a check that can only be exercised in
+ * production is a check nobody knows works — a fake identity states each case directly.
+ */
+export declare function isUnchangedAttachment({ recorded, observed }: {
+    readonly recorded: RecordedAttachmentIdentity;
+    readonly observed: ObservedAttachmentIdentity;
+}, _optional?: Record<string, never>): boolean;
+/**
+ * Phase 1 of `claim()`: synchronously reserves `attachments` for `runId`, or throws (releasing
+ * whatever it already reserved this call) the first time a requested attachment turns out to be
+ * unknown or already claimed.
+ *
+ * The reservation loop deliberately has no `await`: this store's exactly-once guarantee is what
+ * stops two runs being handed the same real path on disk, and `claim` is reachable concurrently
+ * (two run starts, one shared attachment). Nothing between `records.get` and the assignment of
+ * `record.claimedRunId` may ever become asynchronous — that window is exactly where a concurrent
+ * call would get its turn and could observe the same record as still unclaimed.
+ *
+ * Exported so this invariant can be exercised directly against a plain `Map` of fabricated
+ * records, without going through a disk-backed store.
+ */
+export declare function reserveAttachmentRecords({ attachments, records, runId, maxAttachments }: {
+    readonly attachments: readonly StoredAttachment[];
+    readonly records: ReadonlyMap<string, AttachmentRecord>;
+    readonly runId: string;
+    readonly maxAttachments: number;
+}, _optional?: Record<string, never>): AttachmentRecord[];
+/**
+ * Phase 2 of `claim()`: re-verifies every already-reserved record against the filesystem — not
+ * merely re-read, but re-checked against what registration recorded, so someone able to write into
+ * the batch directory between upload and run start cannot get the agent to read a file of their
+ * choosing — and checks every claimed attachment shares one batch. Returns the shared batch
+ * directory on success (or `''` for an empty `claimed`, which `claim()` never passes in — it
+ * returns before calling this — but which a direct caller can still treat as "no batch").
+ *
+ * Throws without releasing `claimed`'s reservations; releasing is the caller's job (`claim`'s own
+ * `catch`), so a rejected claim still leaves nothing half-claimed and the caller can retry with a
+ * corrected set.
+ *
+ * Exported so the integrity and mixed-batch checks can be exercised directly against fabricated
+ * records over real files on disk, without a full `createDiskAttachmentStore` around them.
+ */
+export declare function verifyClaimedAttachments({ claimed }: {
+    readonly claimed: readonly AttachmentRecord[];
+}, _optional?: Record<string, never>): Promise<string>;
+/**
+ * Reduces an untrusted upload filename to a display-only basename over a conservative allowlist.
+ * Never used as the name of the stored file — see this module's trust-model doc.
+ */
+export declare function sanitizeAttachmentName({ requestedName }: {
+    readonly requestedName: unknown;
+}, _optional?: Record<string, never>): string;
+/** `true` when `body`'s first 8 bytes are the PNG signature. */
+export declare function hasPngSignature({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): boolean;
+/** `true` when `body`'s first 3 bytes are the JPEG start-of-image marker. */
+export declare function hasJpegSignature({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): boolean;
+/** `true` when `body`'s first 6 bytes spell either GIF version tag. */
+export declare function hasGifSignature({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): boolean;
+/** `true` when `body` opens with a RIFF container whose form type is WEBP. */
+export declare function hasWebpSignature({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): boolean;
+/**
+ * Infers `'image'` from the leading bytes rather than from a renderer-controlled MIME type or file
+ * extension. PNG, JPEG, GIF87a/89a, WEBP, and AVIF (brand-checked ISO-BMFF, see
+ * {@link hasAvifSignature}) are recognized; everything else is `'file'` — including a plain MP4 or
+ * other non-AVIF ISO-BMFF file, which shares AVIF's `ftyp` tag but is deliberately NOT matched here
+ * (see {@link hasIsoBmffFtypTag}'s doc for why a brand-blind `ftyp` check would be wrong).
+ *
+ * `kind` decides whether a path is later passed to `AgentExecutor.run()`'s `imagePaths`, so letting
+ * a renderer assert it would let a renderer choose how the agent runtime parses the bytes.
+ */
+export declare function detectAttachmentKind({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): StoredAttachment['kind'];
+/**
+ * Streams a request body straight to a private file under a hard byte cap, keeping only the
+ * leading signature bytes in memory so an upload never costs memory proportional to its size.
+ *
+ * Opened `wx`, so this can never overwrite an existing file. A partial write is removed before the
+ * rejection propagates: the cap is enforced *during* the stream, which necessarily means some bytes
+ * already reached disk by the time it trips.
+ */
+export declare function writeBoundedAttachmentBody(requiredArgs: Omit<{
+    request: AsyncIterable<unknown>;
+    filePath: string;
+    maxBytes: number;
+    mode?: number;
+}, 'mode'>, optionalArgs?: Pick<{
+    request: AsyncIterable<unknown>;
+    filePath: string;
+    maxBytes: number;
+    mode?: number;
+}, 'mode'>): Promise<{
+    size: number;
+    signature: Uint8Array;
+}>;
+/**
+ * One attachment as it is written to its sidecar — `AttachmentRecord` minus two fields, both
+ * omitted deliberately:
+ *
+ * - **`batchDirectory`**, because it is re-derived from the upload root on read rather than trusted.
+ *   A sidecar is a file on disk; if it could name the directory a claim later hands to an agent, a
+ *   forged one would turn this store into an arbitrary-file-read primitive. Re-deriving it through
+ *   the same `BATCH_ID_PATTERN` + `resolve` containment argument `resolveBatchDirectory` uses means
+ *   a forged sidecar can only ever point inside the upload root.
+ * - **`claimedRunId`**, because no run survives the process that owned it. Everything adopted comes
+ *   back unclaimed; a file whose run died is re-listable to its own uploader (never to anyone else
+ *   — `claim`/`resolveForRun` still demand the unguessable id or path) and expires on the normal
+ *   TTL. See {@link loadPersistedAttachments} for the retention consequence that carries.
+ */
+export interface PersistedAttachmentRecord {
+    readonly id: string;
+    readonly filePath: string;
+    readonly name: string;
+    readonly kind: StoredAttachment['kind'];
+    readonly size: number;
+    readonly batchId: string;
+    readonly dev: number;
+    readonly ino: number;
+    readonly createdAt: number;
+    readonly ownerId?: string;
+}
+/**
+ * Turns one sidecar's parsed JSON back into an `AttachmentRecord`, or `undefined` for anything that
+ * is not a well-formed record naming a file inside its own batch directory.
+ *
+ * `batchDirectory` is re-derived here and `filePath`'s containment is re-checked against it with
+ * the same parent-equality test `register` uses — the two checks that make an adopted record no
+ * more trusted than one this process registered itself. Pure and exported so both can be exercised
+ * against hostile input directly, without staging files on disk.
+ */
+export declare function parsePersistedAttachment({ raw, canonicalUploadDirectory }: {
+    readonly raw: unknown;
+    readonly canonicalUploadDirectory: string;
+}, _optional?: Record<string, never>): AttachmentRecord | undefined;
+/**
+ * Sidecar filename for a record id. Reduces the id to the same `[a-zA-Z0-9-]` allowlist
+ * `BATCH_ID_PATTERN` uses before appending the extension, so no id — however this store's own id
+ * format later changes — can put a `/`, a `..`, or a second extension into the path. Ids are
+ * `attachment:<uuid>`, so the reduction stays injective in practice: the UUID is what makes it
+ * unique and the UUID survives unchanged.
+ */
+export declare function attachmentSidecarFileName({ id }: {
+    readonly id: string;
+}, _optional?: Record<string, never>): string;
+/**
+ * Rebuilds the record map from the sidecar directory, adopting only records that are (a) well
+ * formed and contained, (b) still within the retention window, and (c) still backed by the exact
+ * file registration accepted. Anything failing any of those is deleted — sidecar first, then the
+ * file it named, and the file ONLY when containment passed, so an unparseable sidecar can never
+ * make this an arbitrary-file-delete primitive for whatever the daemon can unlink.
+ *
+ * **The retention consequence, stated rather than assumed harmless.** Because `claimedRunId` is not
+ * persisted (see {@link PersistedAttachmentRecord}), a file claimed by a run that died with the
+ * process is adopted as unclaimed instead of being wiped, so it now occupies disk and quota for up
+ * to `retentionMs` rather than until the next start. Bounded by the same `maxStoredAttachments` /
+ * `maxStoredBytes` quotas as any live upload, and cleared by the `pruneExpired` every upload
+ * already runs — but it is a real change in when that disk comes back.
+ *
+ * @complexity O(n) in sidecars present, each costing one read and one `lstat`/`realpath` pair.
+ */
+export declare function loadPersistedAttachments(requiredArgs: Omit<{
+    readonly canonicalUploadDirectory: string;
+    readonly retentionMs: number;
+    readonly now?: number;
+}, 'now'>, optionalArgs?: Pick<{
+    readonly canonicalUploadDirectory: string;
+    readonly retentionMs: number;
+    readonly now?: number;
+}, 'now'>): Promise<Map<string, AttachmentRecord>>;
+/**
+ * Removes every upload the sidecar pass did not adopt. Without this, a file whose sidecar was lost
+ * (or was never written, because it predates this option) would survive forever with nothing
+ * tracking it — trading the wipe's data loss for unbounded disk growth, which is not a trade worth
+ * making. This is what keeps "never wipe on construction" bounded.
+ */
+export declare function removeUnadoptedUploads({ canonicalUploadDirectory, adopted }: {
+    readonly canonicalUploadDirectory: string;
+    readonly adopted: ReadonlyMap<string, AttachmentRecord>;
+}, _optional?: Record<string, never>): Promise<void>;
+/**
+ * Decides what a newly-constructed store starts holding: nothing (the default — empty the directory
+ * outright, this pack's behavior before `retainAcrossRestarts` existed), or the authenticated
+ * survivors of the previous process.
+ *
+ * Exported so the whole restart decision can be exercised without standing a store up around it.
+ */
+export declare function prepareAttachmentStorage(requiredArgs: Omit<{
+    readonly canonicalUploadDirectory: string;
+    readonly retainAcrossRestarts: boolean;
+    readonly retentionMs: number;
+    readonly now?: number;
+}, 'now'>, optionalArgs?: Pick<{
+    readonly canonicalUploadDirectory: string;
+    readonly retainAcrossRestarts: boolean;
+    readonly retentionMs: number;
+    readonly now?: number;
+}, 'now'>): Promise<Map<string, AttachmentRecord>>;
+/**
+ * The disk-backed `AttachmentStore` this package ships. Every default matches what a chat composer
+ * needs out of the box; a host that wants different quotas passes them rather than reimplementing
+ * the port.
+ *
+ * @complexity `register`/`claim` are O(n) in the number of tracked records (a small bounded number
+ * — `maxStoredAttachments`), which is what keeps the quota decision synchronous; see `register`.
+ */
+export declare function createDiskAttachmentStore(requiredArgs: Omit<CreateDiskAttachmentStoreOptions, 'maxAttachments' | 'maxBatchBytes' | 'maxStoredAttachments' | 'maxStoredBytes' | 'retentionMs' | 'retainAcrossRestarts'>, optionalArgs?: Pick<CreateDiskAttachmentStoreOptions, 'maxAttachments' | 'maxBatchBytes' | 'maxStoredAttachments' | 'maxStoredBytes' | 'retentionMs' | 'retainAcrossRestarts'>): Promise<AttachmentStore>;
+/**
+ * Diagnostic detail for an internal-error response the public API deliberately does not disclose
+ * (SEC-005), matching `MediaInternalErrorContext`'s precedent.
+ */
+export interface AttachmentsInternalErrorContext {
+    readonly source: 'attachment-upload' | 'attachment-cleanup';
+    readonly batchId: string | null;
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+export interface AttachmentsHttpDeps {
+    readonly store: AttachmentStore;
+    /**
+     * Uploads accepted at once before further requests are rate-limited. Bounds concurrent
+     * filesystem work, which matters because each in-flight upload holds an open handle and may be
+     * writing up to `maxAttachmentBytes`. Defaults to 4.
+     */
+    readonly maxConcurrentUploads?: number;
+    /**
+     * Hard per-request byte cap, enforced while streaming. Should be at or below the store's
+     * `maxBatchBytes`. Defaults to 20 MB.
+     */
+    readonly maxAttachmentBytes?: number;
+    /** Capability ids one `DELETE` may name. Defaults to 10, matching the store's batch cap. */
+    readonly maxCleanupPaths?: number;
+    /**
+     * Rejects a request whose `Origin`/`Host` is not the local daemon's, as every other mutating
+     * route in this package does. Defaults to `true`; a host whose browser sits on a *different*
+     * local port than the daemon (a dev-server proxy, say) either sets that port via `JINI_WEB_PORT`
+     * so the guard recognizes it, or opts out here and accepts that it has no CSRF protection on
+     * this route.
+     */
+    readonly requireSameOrigin?: boolean;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: AttachmentsInternalErrorContext) => void;
+    /**
+     * Resolves the principal id that owns this upload, if any, passed through to `store.register()`'s
+     * `ownerId` (see that field's own doc, and `AttachmentStore.listPendingForOwner`). Optional: a
+     * host with no owner concept omits it and every attachment registers ownerless, matching this
+     * pack's behavior before ownership existed — `listPendingForOwner` simply never returns those.
+     *
+     * A host is expected to read this from a header/context IT ALREADY TRUSTS (e.g. a reverse proxy's
+     * own session-verified principal header, asserted only downstream of that proxy's auth gate) —
+     * this pack has no session concept of its own and never authenticates `req` itself. Returning a
+     * caller-controlled value here (an inbound header nothing has verified) would let any uploader
+     * assert an arbitrary `ownerId` and make its files discoverable by whoever that id names.
+     */
+    readonly resolveOwnerId?: ({ req }: {
+        req: Request;
+    }) => string | undefined;
+}
+export declare const ATTACHMENTS_ROUTE_PATH = "/api/attachments";
+export interface AttachmentUploadResponse {
+    readonly attachment: StoredAttachment;
+}
+/**
+ * Handles one upload: rate-limit, batch directory, bounded stream to disk, signature sniff,
+ * register. Exported so a host mounting its own path (or its own framework) can reuse the whole
+ * body without re-deriving the ordering, which is load-bearing — see the `finally`.
+ */
+export declare function handleAttachmentUpload({ req, res, deps, state }: {
+    readonly req: Request;
+    readonly res: Response;
+    readonly deps: AttachmentsHttpDeps;
+    readonly state: {
+        activeUploads: number;
+    };
+}, _optional?: Record<string, never>): Promise<void>;
+/**
+ * Handles a client abandoning a batch (a failed multi-file upload, a cleared composer). Only
+ * *unclaimed* uploads can be deleted this way, so a caller cannot use it to pull files out from
+ * under a run that already claimed them.
+ */
+export declare function handleAttachmentCleanup({ req, res, deps }: {
+    readonly req: Request;
+    readonly res: Response;
+    readonly deps: AttachmentsHttpDeps;
+}, _optional?: Record<string, never>): Promise<void>;
+/**
+ * Mounts `POST`/`DELETE /api/attachments` on `app`. A pack's `http(app, services)` calls this
+ * directly.
+ *
+ * Hand-mounted rather than built from `defineJsonRoute`/`mountJsonRoute` for two concrete reasons:
+ * the upload reads the raw request stream (a JSON-parsed `req.body` is exactly what must not have
+ * happened), and the cleanup answers `204` with no body, which a JSON responder cannot express.
+ */
+export declare function registerAttachmentRoutes({ app, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: AttachmentsHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+//# sourceMappingURL=attachments.d.ts.map