@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/managers/AttachmentManager.d.ts

@@ -0,0 +1,1032 @@
+import BaseManager, { BackupData, type ManagerStats } from './BaseManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+/**
+ * Marks an error as "the audit record could not be written", not "the action
+ * failed" (#1183). A caller refusing a destructive action needs to say which.
+ */
+export declare const AUDIT_WRITE_FAILED = "EAUDITWRITE";
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
+import type { AssetQuery, AssetRecord } from '../types/Asset.js';
+import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+/**
+ * Base attachment provider interface
+ */
+interface BaseAttachmentProvider {
+    initialize(): Promise<void>;
+    storeAttachment(fileBuffer: Buffer, fileInfo: FileInfo, metadata: AttachmentMetadataInput, user: User | null): Promise<AttachmentMetadata>;
+    getAttachment(attachmentId: string): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
+    getAttachmentMetadata(attachmentId: string): Promise<AttachmentMetadata | null>;
+    getAttachmentsForPage(pageName: string): Promise<AttachmentMetadata[]>;
+    getAttachmentByFilename(filename: string): Promise<AttachmentMetadata | null>;
+    getAllAttachments(): Promise<AttachmentMetadata[]>;
+    deleteAttachment(attachmentId: string): Promise<boolean>;
+    updateAttachmentMetadata(attachmentId: string, updates: Partial<AttachmentMetadata>): Promise<boolean>;
+    attachmentExists(attachmentId: string): Promise<boolean>;
+    refreshAttachmentList(): Promise<void>;
+    getThumbnail?(id: string, size: string): Promise<Buffer | null>;
+    backup(): Promise<unknown>;
+    restore(backupData: unknown): Promise<void>;
+    shutdown(): Promise<void>;
+    getProviderInfo(): {
+        features: string[];
+    };
+    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: {
+        originalName: string;
+        mimeType: string;
+        description: string;
+        author?: string;
+        pageName?: string;
+    }): Promise<StoreFileEntry>;
+    getFileInStore(location: StoreFileLocation, id: string): Promise<{
+        entry: StoreFileEntry;
+        bytes: Buffer;
+    } | null>;
+    listFilesInStore(location: StoreFileLocation): Promise<StoreFileEntry[]>;
+    filesInStoreForPage(location: StoreFileLocation, pageName: string): Promise<StoreFileEntry[]>;
+    setFileMentionInStore(location: StoreFileLocation, id: string, pageName: string, mentioned: boolean): Promise<boolean>;
+    deleteFileInStore(location: StoreFileLocation, id: string): Promise<StoreFileEntry | null>;
+    searchFilesInStore(location: StoreFileLocation, query: AssetQuery): Promise<AssetRecord[]>;
+    privateRecordsInSharedIndex(): Array<{
+        id: string;
+        owner: string | null;
+        store: string | null;
+        pages: string[];
+    }>;
+    adoptRecordIntoStore(location: StoreFileLocation, id: string): Promise<StoreFileEntry | null>;
+    copyRecordIntoStore(location: StoreFileLocation, id: string, pageName: string): Promise<StoreFileEntry | null>;
+    copyStoreFileToStore(from: StoreFileLocation, to: StoreFileLocation, id: string, pageName: string): Promise<StoreFileEntry | null>;
+    copyStoreFileToPool(from: StoreFileLocation, id: string, pageName: string): Promise<boolean>;
+    removeRecordFromPool(id: string): Promise<boolean>;
+    setPoolMentions(id: string, names: string[]): Promise<boolean>;
+}
+export interface VaultPagePoolFiles {
+    owner: string;
+    vault: string;
+    page: string | null;
+    files: number;
+}
+/**
+ * File information interface
+ */
+export interface FileInfo {
+    originalName: string;
+    mimeType: string;
+    size: number;
+}
+/**
+ * Upload options interface
+ */
+export interface UploadOptions {
+    pageName?: string;
+    description?: string;
+    /** WikiContext for the current request — audit IP fallback */
+    wikiContext?: import('../context/WikiContext.js').default;
+    /**
+     * Private-store destination (#1396): the upload dialog's checkbox. Decides
+     * only when `pageName` is not a private page — an upload onto a private page
+     * is always private, in that page's author's store (#1398). Absent or false
+     * otherwise keeps the public attachments pool.
+     */
+    private?: boolean;
+    /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
+    store?: string;
+}
+/**
+ * User object interface
+ */
+export interface User {
+    name: string;
+    email?: string;
+}
+/**
+ * Mention object (WebPage reference)
+ */
+export interface Mention {
+    '@type': string;
+    name: string;
+    url: string;
+}
+/**
+ * Attachment metadata interface
+ */
+export interface AttachmentMetadata {
+    identifier: string;
+    name?: string;
+    url?: string;
+    encodingFormat?: string;
+    description?: string;
+    isFamilyFriendly?: boolean;
+    mentions?: Mention[];
+    editor?: {
+        '@type': string;
+        name: string;
+        email?: string;
+    };
+    documentTitle?: string;
+    documentAuthor?: string;
+    documentSubject?: string;
+    documentKeywords?: string[];
+    documentDateCreated?: string;
+    documentDateModified?: string;
+    inLanguage?: string;
+    [key: string]: unknown;
+}
+/**
+ * Attachment metadata input (for new uploads)
+ */
+export interface AttachmentMetadataInput {
+    description: string;
+    isFamilyFriendly: boolean;
+}
+/**
+ * Attachment backup data
+ */
+export interface AttachmentBackupData extends BackupData {
+    providerClass: string | null;
+    providerBackup?: unknown;
+    data?: null;
+}
+declare class AttachmentManager extends BaseManager implements CatalogSource {
+    /** CatalogSource identifier (Slice 5 of #755 / #759). */
+    readonly sourceId = "attachments";
+    /**
+     * Subtypes this source produces. Today only DigitalDocument (PDFs / docx /
+     * xlsx / pptx). Image and video attachments emit a `DigitalDocument` stub
+     * since the rich ImageObject / VideoObject mapper lives on the media path.
+     */
+    readonly types: readonly SchemaType[];
+    /**
+     * On-disk schema version for attachment-metadata.json (Decision 6).
+     * Bump when the persisted SchemaCreativeWork shape changes; current v1 is
+     * the post-Slice-5 (#759) shape including documentTitle / documentAuthor /
+     * documentSubject / documentKeywords / documentDateCreated /
+     * documentDateModified / inLanguage.
+     */
+    static readonly CURRENT_SCHEMA_VERSION = 1;
+    readonly currentSchemaVersion = 1;
+    private attachmentProvider;
+    private providerClass;
+    /** What the last check for vault pages using shared-pool files found, and the degraded reason it set (#1842). */
+    private poolFileFindings;
+    private poolFileReason;
+    private maxSize;
+    private allowedTypes;
+    /**
+     * Creates a new AttachmentManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /** Return the active attachment provider for use by AssetManager. */
+    get provider(): BaseAttachmentProvider | null;
+    /**
+     * Initialize AttachmentManager and load the configured provider
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available or provider fails to load
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * CatalogSource.list — query attachments and emit CreativeWork shapes.
+     *
+     * Routes `query.text` through the provider's `getAttachmentsForPage` /
+     * `getAllAttachments` surface, applies the (DigitalDocument-restricted)
+     * `types` filter, and converts each match via the provider's
+     * `toCreativeWork()`. Cursor pagination not yet implemented (initial
+     * slice); `limit` caps page size.
+     */
+    list(query: CatalogQuery): Promise<CatalogPage>;
+    /**
+     * CatalogSource.get — fetch a single attachment by stable identifier.
+     * Returns null for not-found.
+     *
+     * Note: this does NOT enforce private-page ACL. CatalogManager callers
+     * should layer ACL on top (mirroring `getAttachment()` which goes through
+     * the request path with full WikiContext).
+     */
+    get(identifier: string): Promise<CreativeWork | null>;
+    /**
+     * CatalogSource.rebuild — re-extract embedded document metadata on every
+     * stored attachment. Walks the entire metadata store, for each
+     * doc-MIME attachment re-runs exiftool extraction on the stored file and
+     * backfills the seven Slice-5 fields (documentTitle / documentAuthor /
+     * documentSubject / documentKeywords / documentDateCreated /
+     * documentDateModified / inLanguage). Backfills pre-v3.27.0 records that
+     * never went through the Slice-5 extraction path at upload time.
+     *
+     * Per-file failures are non-fatal — logged and counted. Non-document
+     * MIMEs are skipped. Wired into the `attachments.rebuild` background job
+     * for operator-triggered runs from the admin dashboard. Slice 5b of #760
+     * (#763).
+     */
+    rebuild(opts?: RebuildOpts): Promise<void>;
+    /**
+     * Re-extract embedded document metadata across every stored attachment.
+     * Same operation as {@link rebuild} but returns the summary so the
+     * `attachments.rebuild` background job can produce a per-run report.
+     * Returns `{scanned, updated, skipped, errors}` zeros when the provider
+     * isn't initialised yet (caller can branch on this).
+     */
+    backfillDocMetadata(onProgress?: (processed: number, total: number) => void): Promise<{
+        scanned: number;
+        updated: number;
+        skipped: number;
+        errors: number;
+    }>;
+    /**
+     * Get current attachment provider
+     * @returns {BaseAttachmentProvider | null} Current provider instance
+     */
+    getCurrentAttachmentProvider(): BaseAttachmentProvider | null;
+    /**
+     * Check a registry permission for an attachment operation (#1059).
+     *
+     * Evaluates through the PDP (`PolicyDecisionPoint.permits`), the same
+     * path WikiContext.hasPermission takes. Until #1059 this was a stub that
+     * ignored its argument and granted any authenticated user, which made every
+     * permission passed to it decorative — asset-delete sat on the editor role
+     * while any logged-in account could delete any attachment.
+     *
+     * Fails closed when UserManager is unavailable: an attachment mutation with
+     * no policy engine to consult is denied, not waved through.
+     *
+     * @param {string} permission - Registry permission ({target}-{action}, e.g. 'asset-upload')
+     * @param userContext - The caller's context, forwarded (#1179)
+     * @returns {Promise<boolean>} True if allowed
+     * @private
+     */
+    private checkPermission;
+    /**
+     * Localize the remote images an NCM body embeds (#728 S5a-ii, #1486): each
+     * remote `<img>`/`![](url)` is fetched, checked (size, type, ad deny-list)
+     * and stored as an attachment of `pageName`, and the body is rewritten to
+     * point at it. With `dryRun` nothing is stored: the fetch and checks run,
+     * and the result reports what would be attached.
+     *
+     * Reached through PageManager.completeNcmConversion, the NCM door, never
+     * from a route.
+     *
+     * #1133: the URL comes from page content, so this fetch is a capability the
+     * editor does not otherwise have — making the server issue a request from
+     * inside the network. guardedFetch judges the address actually resolved, on
+     * every redirect hop.
+     */
+    localizeRemoteImages(content: string, pageName: string, ctx: ActorContext, dryRun: boolean): Promise<{
+        content: string;
+        warnings: string[];
+    }>;
+    /**
+     * Every attachment write goes through here (#1751): it writes, then bumps
+     * the attachment-data version, so cached renders that list or show
+     * attachments re-render.
+     */
+    private writeAttachments;
+    /**
+     * Upload an attachment
+     *
+     * @param {Buffer} fileBuffer - File data
+     * @param {FileInfo} fileInfo - { originalName, mimeType, size }
+     * @param {UploadOptions} options - Upload options
+     * @param {string} options.pageName - Page uploaded onto (optional). A private page forces the upload private, into its author's store (#1398)
+     * @param {string} options.description - File description
+     * @param {boolean} options.private - Private-store destination for an upload with no private page (#1396)
+     * @param {string} options.store - Store id when private with no private page; else ConfigurationManager defaultstoreid
+     * @param ctx - Who is uploading (#1179): the request's subject, or a JobContext for an in-engine caller. Mandatory and positional.
+     * @returns {Promise<AttachmentMetadata>} Attachment metadata
+     */
+    uploadAttachment(fileBuffer: Buffer, fileInfo: FileInfo, ctx: ActorContext, options?: UploadOptions): Promise<AttachmentMetadata>;
+    /** A file is added to a private page only by someone who may edit it: the page's own decision (#1398). */
+    private assertMayEditPage;
+    /**
+     * One vault as a provider location, opened through `ctx` (#1842). Throws as
+     * `storeFileIO` does: a locked vault, or a sealed kind's vault not yet opened.
+     */
+    private vaultLocation;
+    /**
+     * Attach an existing attachment to a page
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @param {string} pageName - Page name to attach to
+     * @param ctx - Whose mention this is (#1179). Mandatory and positional.
+     * @returns {Promise<boolean>} Success status
+     */
+    attachToPage(attachmentId: string, pageName: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Detach an attachment from a page
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @param {string} pageName - Page name to detach from
+     * @param ctx - Whose mention this is (#1179). Mandatory and positional.
+     * @returns {Promise<boolean>} Success status
+     */
+    detachFromPage(attachmentId: string, pageName: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Get an attachment by ID
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<{buffer: Buffer, metadata: AttachmentMetadata}|null>}
+     */
+    getAttachment(attachmentId: string): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
+    /**
+     * The requester's own private stores, as provider locations (#1460).
+     *
+     * The container rule first: a context that may not act in its own container
+     * — anonymous, or a share visitor, whose `viaShare` issuer is someone else
+     * — reaches no store at all. Then every store in that container, plain or
+     * sealed: `privateStoreIdsOf` answers from the folder, because which stores
+     * EXIST does not depend on keys. `storeFileIO` refuses an encrypted store
+     * this context holds no DEK for, and that store is skipped rather than read
+     * in the clear.
+     */
+    private ownPrivateStores;
+    private mayReach;
+    /**
+     * How a store file is shown to callers that expect attachment metadata.
+     * The legacy aliases (`id`, `filename`, `mimeType`, `size`, …) are here so a
+     * merged list renders through the same templates the shared pool does
+     * (#1460); `filePath` is not, because where a private file sits on disk is
+     * not something a listing carries.
+     */
+    private static storeFileMetadata;
+    /**
+     * The requester's own store that lists `attachmentId`, with its entry — or
+     * null when none of them does, or the PIP refuses (#1460). Metadata only:
+     * the bytes are read by the caller that needs them, so a listing, a delete
+     * and a mention change do not decrypt a file to look at its name.
+     */
+    private findOwnStoreFile;
+    /**
+     * May `ctx` do `permission` to `what` in `owner`'s vault `store` (#1539)?
+     * The container rule, then the capability asked with the vault, so
+     * `vault-owner` decides — the same rule as a vault page.
+     */
+    private mayInVault;
+    /** The requester's own store file and its entry, before the capability is asked — see {@link findOwnStoreFile}. */
+    private locateOwnStoreFile;
+    /**
+     * A file from the requester's own private stores — or null when none of the
+     * stores it can open lists it, or the PIP refuses. An encrypted store's
+     * bytes come back decrypted; a plain store's come back as they are, and in
+     * both cases the caller got here only by owning the container.
+     */
+    getPrivateStoreAttachment(attachmentId: string, ctx: ActorContext): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
+    /**
+     * A file served through a vault link (#1388): from the one vault the link
+     * names, and only when a current page the link covers uses it. A file no
+     * covered page uses — including a copy nobody uses any more (#1517) — is
+     * not shared. `ctx` is the link's subject; the container rule and the share
+     * ceiling decide as for every other door.
+     */
+    getVaultShareAttachment(attachmentId: string, ctx: ActorContext): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
+    /** The container rule for one vault, as the link's subject may enter it (#1388). */
+    private mayReachVault;
+    /**
+     * The files in the requester's own vaults that no page in that vault uses
+     * (#1517) — for their profile page, so a copy kept for a page that left the vault,
+     * or a file whose page was deleted, can be seen and removed.
+     *
+     * Only the requester's own vaults, through the container rule. "Used" is a
+     * current page of that vault in the file's mentions, which every save keeps
+     * in step. An encrypted vault this session cannot open is reported as
+     * locked rather than as empty.
+     *
+     * @returns One entry per vault with unused files, or locked; `canDelete` is
+     *   whether this context may delete files there — the delete's own question
+     *   (#1539), so the page offers the button exactly when the delete would work
+     */
+    listOwnUnusedVaultFiles(ctx: ActorContext): Promise<Array<{
+        vault: string;
+        locked: boolean;
+        canDelete: boolean;
+        files: Array<{
+            id: string;
+            name: string;
+            contentSize: number;
+            dateCreated: string;
+        }>;
+    }>>;
+    /**
+     * Is `attachmentId` a file in one of the requester's own private stores?
+     * An index read, no bytes — for a caller that has to treat a private file
+     * differently without reading it twice (#1460).
+     */
+    isOwnPrivateStoreFile(attachmentId: string, ctx: ActorContext): Promise<boolean>;
+    /** The requester's own private-store files uploaded onto `pageName`. */
+    getPrivateStoreAttachmentsForPage(pageName: string, ctx: ActorContext): Promise<AttachmentMetadata[]>;
+    /**
+     * Everything the requester's own private stores hold (#1460) — the half of
+     * a browse or a list that is in no shared index. Another user's stores, and
+     * an admin's view of anyone's, are not here: this reads `ctx`'s container
+     * and no other.
+     */
+    getPrivateStoreAttachments(ctx: ActorContext): Promise<AttachmentMetadata[]>;
+    /**
+     * The requester's own private-store files as asset-search results (#1460).
+     *
+     * AssetManager fans a search out over the provider registry, and no provider
+     * can see a store it was given no context for — so the store half is merged
+     * by the one caller that holds the requester's context. The matching rules
+     * are the provider's own, applied to the store's entries, so a private file
+     * is findable exactly as a public one is.
+     */
+    searchPrivateStoreAttachments(query: AssetQuery, ctx: ActorContext): Promise<AssetRecord[]>;
+    /**
+     * Move every unencrypted private file record out of the global
+     * `attachment-metadata.json` and into its store's own index, at start-up.
+     *
+     * Best-effort: a failure is logged and never blocks start-up, the shape
+     * `migratePrivateLinksAtBoot` uses.
+     */
+    migratePrivateFilesAtBoot(): Promise<void>;
+    /**
+     * Move the private file records still in the shared index into their stores.
+     *
+     * __Which files are private__ is decided from the record itself first — the
+     * `isPrivate` / `creator` / `store` fields #1398 writes — and, where that is
+     * not enough, from the page it is attached to: a mention naming
+     * `private/{owner}/{store}/{title}` says whose store the file belongs in,
+     * confirmed through `PageManager.getPrivatePageOwner`. A record that is
+     * neither is a public attachment and stays where it is.
+     *
+     * __What moves__: the bytes, into `{store}/attachments/`, KEEPING their
+     * existing file name — nothing on disk is renamed — and the record, into
+     * the store's own index under the id it already had, because that id is its
+     * `/attachments/{id}` URL on every page that references it.
+     *
+     * __No unlock split__, unlike #1457's link migration and #1458's search
+     * indexes. Those needed one because a page's TEXT is sealed; here an
+     * unencrypted store needs no key at all, so this boot job finishes the whole
+     * job for the stores it is about. A record pointing at an ENCRYPTED store is
+     * skipped, with a line saying so: #1400 already keeps those files in their
+     * store, and one predating it cannot be re-sealed without its owner's DEK.
+     *
+     * __Idempotent__: a second run finds nothing left in the shared index, and a
+     * record whose store already lists the id moves no bytes.
+     *
+     * @param ctx - Whose reading and writing this is (#1179). Mandatory and positional.
+     * @returns how many records moved
+     */
+    migratePrivateFilesIntoStores(ctx: ActorContext): Promise<number>;
+    /**
+     * Move the files a page uses when the page changes place — into a vault, out
+     * of one, or between two — so that every file a vault page uses is in that
+     * vault (operator, 2026-10-16). Called by the page door after the page moved.
+     *
+     * __Which files__: those whose mentions name the page where it was, and
+     * those its content references (`[{Image src='…'}]`, `[{ATTACH src='…'}]`,
+     * `/attachments/{id}`), resolved in the vault it left first, then the shared
+     * pool.
+     *
+     * __How__: each file is copied to the destination under the same id (its
+     * `/attachments/{id}` URL in the page), through both sides' store I/O —
+     * sealed going into a sealed vault, opened coming out. Then the source: a
+     * file no other page there uses is removed; one another page still uses is
+     * left for it, without this page's mention. A shared-pool file is removed
+     * from the pool only when no public page that exists now is among its
+     * mentions ({@link poolFileShare}): a file other public pages use is copied
+     * in, never taken from them, and a stale mention (a page renamed, made
+     * private or deleted, often this page's own former title) keeps nothing.
+     *
+     * __Refusal__: both sides' I/O is resolved before any file moves, so a locked
+     * vault, or a sealed kind's vault not yet opened, moves nothing — the same
+     * refusal the page's own save meets first.
+     *
+     * @param previousName - The page's name before: a public title, or `vaults/{owner}/{store}/{title}`
+     * @param name - Its name now
+     * @param content - Its content
+     * @param ctx - Whose move this is (#1179): the page door already let it move the page
+     * @returns how many files moved or were copied
+     */
+    movePageAttachments(previousName: string, name: string, content: string, ctx: ActorContext): Promise<number>;
+    /** The file names (with their basenames) and `/attachments/{id}` ids `content` references. */
+    private static contentRefs;
+    /**
+     * The shared-pool files page `pageName` uses: records whose mentions name it,
+     * and those `content` references that `held` (a vault's own files) does not
+     * answer.
+     */
+    private poolFilesOfPage;
+    /**
+     * Who else uses shared-pool file `id`, besides the page itself — known by
+     * `self.names` (its name now, and before a move) and `self.uuid` (#1842).
+     *
+     * Each mention is one of:
+     *
+     * - __the page itself__: dropped from the record
+     * - __a public page that exists now__ (asked of PageManager by exact title,
+     *   slug or uuid, never by role): a sharer, for which the pool copy is kept
+     * - __another vault page__: kept until that page's own repair takes the
+     *   file (the startup check names that vault meanwhile), so its bytes are
+     *   never removed from under it
+     * - __stale__, a public name no page has any more (renamed, made private,
+     *   deleted; often this page's own former public title): dropped, and it
+     *   keeps nothing
+     *
+     * `alone` is true when the mentions name no one but the page and stale
+     * names: the pool copy should go. A record with no mentions at all, which
+     * only content references, is never `alone`, so it is never taken from a
+     * page whose mention was never recorded.
+     */
+    private poolFileShare;
+    /**
+     * Is `name` a public page that exists now, other than page `selfUuid`
+     * (#1842)? By exact title (any case), slug or uuid: a fuzzy match is not
+     * that page. Without a PageManager nothing can be told, so every name counts.
+     */
+    private isLivePublicPage;
+    /** The uuid of page `name` as `ctx` finds it; null when it can't be told. */
+    private pageUuidOf;
+    /**
+     * What taking shared-pool file `id` into a vault does (#1842): 'moved', the
+     * pool copy goes; 'copied', copied in with the pool copy left for its
+     * sharers; null, nothing, because the vault already holds it and public
+     * pages still use the pool copy.
+     */
+    private static poolPlan;
+    /**
+     * Take shared-pool file `id` into vault `to` for page `name`, under the same
+     * id, through the vault's I/O; then the pool copy: removed (record, bytes,
+     * thumbnails) when no public page uses it, otherwise left for those that do,
+     * without this page's mention or stale ones. Copy first, so a failure leaves
+     * two copies, never none. A vault that already holds the id (`held`: an
+     * earlier repair copied it) just gains the mention, so running the repair
+     * again removes a pool copy left behind.
+     *
+     * @returns 'moved' (no pool copy left), 'copied' (left for other pages), or null when nothing was copied
+     */
+    private takePoolFileIntoVault;
+    /**
+     * Bring the shared-pool files vault page `name` still uses into its vault
+     * (#1842's repair, for files a move before #1842 left in the pool): the
+     * files its mentions name and those `content` references that the vault
+     * doesn't hold, each by {@link movePageAttachments}'s rule — copied in under
+     * the same id, sealed when the vault is, and removed from the pool only
+     * when no public page that exists now uses it ({@link poolFileShare}).
+     * A file the vault already holds under the same id whose pool copy no
+     * public page uses loses that copy too, so running the repair again on a
+     * page whose files were copied in removes what was left behind.
+     *
+     * The vault's I/O is resolved first, so a locked vault, or a sealed kind's
+     * vault not yet opened, throws and nothing moves. Who may ask is the
+     * caller's (`PageManager.repairVaultPage`) to decide.
+     *
+     * @param name - The page's vault name, `vaults/{owner}/{store}/{title}`
+     * @param content - Its content; '' when only its mentions are to be followed
+     * @param ctx - Whose I/O this is: the owner's session for a sealed vault
+     * @param opts.dryRun - Count what would happen, and change nothing
+     * @returns how many files were (or would be) moved out of the pool, and copied with a pool copy left for other pages
+     */
+    movePoolFilesIntoVault(name: string, content: string, ctx: ActorContext, opts?: {
+        dryRun?: boolean;
+    }): Promise<{
+        moved: number;
+        copied: number;
+    }>;
+    /**
+     * The shared-pool files {@link movePoolFilesIntoVault} would bring into
+     * vault page `name`'s vault, by id with their file name and the URL that
+     * serves them today (#1842's repair list, for the owner to check what will
+     * move). Changes nothing and logs nothing. The vault's I/O is resolved as
+     * for the move, so a locked vault throws. Whether `ctx` may see these is the
+     * caller's (`PageManager.vaultRepairDetails`) to decide: names are shown to
+     * the page's reader only, never logged or recorded.
+     */
+    poolFilesOfVaultPage(name: string, content: string, ctx: ActorContext): Promise<Array<{
+        id: string;
+        name: string;
+        url: string;
+    }>>;
+    /**
+     * The vault page's location, and the shared-pool files it uses that the
+     * repair has work for (#1842), each with what the repair would do:
+     *
+     * - those its vault does not hold: its mentions name the page, or its
+     *   content references them
+     * - those its vault already holds under the same id (an earlier repair, or
+     *   a move, copied them in) and that still have a pool copy no public page
+     *   uses, so a repair run again removes it
+     *
+     * A file the vault holds whose pool copy public pages still use is not
+     * listed: there is nothing to do.
+     */
+    private vaultPagePoolIds;
+    /**
+     * The vault page names in `owner`'s vault `store` that shared-pool records
+     * still mention (#1842), and, in a vault that is not sealed, those its own
+     * files name whose pool copy should be gone ({@link heldPoolLeftovers}):
+     * what the startup check reports as "pages named by shared records". Used
+     * by the repair; never logged.
+     */
+    poolMentionedVaultPages(owner: string, store: string): Promise<string[]>;
+    /**
+     * A vault's own files (`own`) that the shared pool still has under the same
+     * id with no public page using that copy (#1842): an earlier repair or move
+     * copied them in and the pool copy stayed, served to anyone with the id. By
+     * {@link poolFileShare}, with the vault pages each file names as the page
+     * itself. A pool copy a public page that exists now still names is not one.
+     */
+    private heldPoolLeftovers;
+    /**
+     * Vault pages that still use files in the shared pool (#1842): left by moves
+     * into a vault before #1842, when the page went and its files stayed. Such a
+     * file is served like any public attachment. Read only, and no key is used:
+     *
+     * - a shared record whose mentions name a vault page (`page: null`, so the
+     *   title in that mention is never repeated)
+     * - in each vault that is not sealed, a page (`{uuid}.md`) whose content
+     *   references a shared-pool file the vault does not hold itself
+     * - in each vault that is not sealed, a page using a file the vault holds
+     *   whose pool copy under the same id no public page that exists now uses
+     *   (its mentions are stale, or name only vault pages): the copy an earlier
+     *   repair left behind, which a repair run again removes. Such a file no
+     *   page's content or title claims is counted for the vault (`page: null`)
+     *
+     * A sealed vault's pages can't be read without their owner's key, so they are
+     * not checked here.
+     */
+    findVaultPagesUsingPoolFiles(): Promise<VaultPagePoolFiles[]>;
+    /**
+     * The startup report for {@link findVaultPagesUsingPoolFiles}, made the way
+     * the unsealed-vault and notes checks report (#1834, #1839): an error in the
+     * log naming each owner, vault and page uuid, the degraded state (the
+     * subsystem banner) and a system notification. Nothing is moved or deleted.
+     * A failing check is logged, never thrown. Run after the boot migration, so
+     * what it moved into plain stores is not reported.
+     */
+    reportVaultPagesUsingPoolFilesAtBoot(): Promise<void>;
+    /**
+     * Run that check again (#1842): after a repair, so the subsystem banner
+     * clears once nothing is left. No notification.
+     */
+    recheckVaultPagesUsingPoolFiles(): Promise<VaultPagePoolFiles[]>;
+    /** What the last check found (#1842): owner, vault, page uuid (null: pages named by shared records), file count. */
+    vaultPagesUsingPoolFiles(): VaultPagePoolFiles[];
+    private checkVaultPagesUsingPoolFiles;
+    /**
+     * Get attachment metadata only
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<AttachmentMetadata|null>}
+     */
+    getAttachmentMetadata(attachmentId: string): Promise<AttachmentMetadata | null>;
+    /**
+     * Every file attached to a page that this requester may see: the shared
+     * pool's records, plus the requester's own private-store files that name
+     * the page (#1460). Another user's, and an admin's view of anyone's, are
+     * not merged — {@link ownPrivateStores} reads `ctx`'s container and no other.
+     *
+     * @param pageName - Page name
+     * @param ctx - Whose reading this is (#1179). Mandatory and positional.
+     */
+    getAttachmentsForPage(pageName: string, ctx: ActorContext): Promise<AttachmentMetadata[]>;
+    /**
+     * Find an attachment by its original filename.
+     *
+     * The shared pool first, then the requester's own stores (#1460): a public
+     * page's markup must resolve to the same file for everyone who can read it,
+     * so a private file of the reader's never shadows a public record of the
+     * same name. A private file uploaded ONTO a page is still found before
+     * either, by {@link resolveAttachmentSrc}, which asks the page's own files.
+     *
+     * @param filename - Original filename to search for
+     * @param ctx - Whose reading this is (#1179). Mandatory and positional.
+     */
+    getAttachmentByFilename(filename: string, ctx: ActorContext): Promise<AttachmentMetadata | null>;
+    /** #1006: how many attachments this instance holds. Count only, never metadata. */
+    getManagerStats(): Promise<ManagerStats>;
+    /**
+     * Every attachment this requester may see: the shared pool, plus their own
+     * private stores' files (#1460).
+     *
+     * @param ctx - Whose reading this is (#1179). Mandatory and positional.
+     */
+    getAllAttachments(ctx: ActorContext): Promise<AttachmentMetadata[]>;
+    /**
+     * The shared pool alone — what `attachment-metadata.json` holds (#1460).
+     *
+     * For the surfaces that have no requester to merge for: an instance count,
+     * and the CatalogSource fan-out, whose results are a shared catalogue. A
+     * surface that DOES have one asks {@link getAllAttachments} instead.
+     */
+    getSharedPoolAttachments(): Promise<AttachmentMetadata[]>;
+    /**
+     * The shared pool's record with this filename, with nothing merged (#1460).
+     *
+     * For `AssetManager.syncPageAssets`, which keeps a SHARED index of what each
+     * public page references: nothing private may enter it, so it must not be
+     * given the per-requester merge {@link getAttachmentByFilename} does.
+     */
+    getSharedPoolAttachmentByFilename(filename: string): Promise<AttachmentMetadata | null>;
+    /**
+     * Delete an attachment
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @param context - Who is acting (#1179): the request's subject, or a JobContext
+     * @returns {Promise<boolean>} Success status
+     */
+    deleteAttachment(attachmentId: string, context: ActorContext, wikiContext?: {
+        request?: {
+            ip?: string;
+        } | null;
+    }): Promise<boolean>;
+    /**
+     * Emit an attachment audit event from the manager that owns the resource.
+     *
+     * `docs/audit-posture.md` states the rule this implements: an action is
+     * "emitted through `recordAuditEvent` (or the manager door that calls it)".
+     * The door is here. Placing it at a route means every future caller has to
+     * remember, which is the thing #1120 exists to end — being audited must not
+     * depend on a producer recalling a method.
+     *
+     * `critical` decides whether a failure to record stops the action.
+     */
+    private recordAttachmentEvent;
+    /** #1204: an attachment's metadata changed; field NAMES only, at the door both edit paths pass through. */
+    private recordAssetEdit;
+    /**
+     * Update attachment metadata
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @param {Partial<AttachmentMetadata>} updates - Metadata updates
+     * @param context - Who is acting (#1179): the request's subject, or a JobContext
+     * @returns {Promise<boolean>} Success status
+     */
+    updateAttachmentMetadata(attachmentId: string, updates: Partial<AttachmentMetadata>, context: ActorContext): Promise<boolean>;
+    /**
+     * Edit an attachment's descriptive metadata (#999).
+     *
+     * Distinct from `updateAttachmentMetadata`, which takes an
+     * `AttachmentMetadata` shape and returns a boolean. This takes the same
+     * `AssetMetadataPatch` the media route uses — absent means keep, explicit
+     * `null` means clear — and returns the refreshed record.
+     *
+     * **Sidecar only for attachments.** Unlike the media equivalent, this does
+     * not write into the file: attachment IDs are content hashes, so an embedded
+     * write would break the id↔bytes invariant. See
+     * `BasicAttachmentProvider.updateMetadata` for the full reasoning.
+     *
+     * Gated on `asset-edit`, the same permission `PATCH /media/api/item/:id`
+     * uses — this is asset metadata editing, and it should not require a
+     * *different* right depending on whether the file happens to be a page
+     * attachment or a media-library item.
+     *
+     * Note the older `updateAttachmentMetadata` still gates on
+     * `asset-upload`. Two paths edit attachment metadata under two different
+     * permissions; that divergence predates this method and is left alone rather
+     * than changed as a side effect of adding a route.
+     *
+     * @param attachmentId - Attachment identifier
+     * @param patch - Fields to change; `null` clears, omission leaves alone
+     * @param context - Caller, for the permission check
+     * @returns The refreshed record, or null when the attachment is unknown
+     * @throws Error when the caller lacks `asset-edit`, or the provider cannot edit
+     */
+    updateAssetMetadata(attachmentId: string, patch: import('../types/Asset.js').AssetMetadataPatch, context: ActorContext): Promise<import('../types/Asset.js').AssetRecord | null>;
+    /**
+     * Check if an attachment exists
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<boolean>}
+     */
+    attachmentExists(attachmentId: string): Promise<boolean>;
+    /**
+     * Get attachment URL
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {string} URL path
+     */
+    getAttachmentUrl(attachmentId: string): string;
+    /**
+     * Resolve an attachment src value (from plugin syntax) to a serving URL and MIME type.
+     *
+     * This is the canonical resolution method used by all plugins (ImagePlugin,
+     * AttachPlugin, and future media plugins). Centralising here means Media
+     * Manager (#273), private folders (#122), and any other media source only
+     * need to be wired in once.
+     *
+     * Resolution order:
+     *   0. media:// URI — resolved via MediaManager.findByFilename(); never touches attachment store
+     *   1. External URL (starts with http:// or https://) — returned as-is, mimeType: ''
+     *   2. Absolute path (starts with /) — returned as-is, mimeType: ''
+     *   3. Filename lookup on the current page's attachments (exact name match)
+     *   4. Global filename search across all attachments
+     *   5. Returns null if unresolvable (caller decides how to render the error)
+     *
+     * @param {string} src - The raw src value from plugin syntax
+     * @param {string} pageName - Page name for step 3 context
+     * @returns {Promise<{ url: string; mimeType: string } | null>} Resolved result or null
+     */
+    resolveAttachmentSrc(src: string, pageName: string, ctx: ActorContext): Promise<{
+        url: string;
+        mimeType: string;
+    } | null>;
+    /**
+     * Page-scoped then global lookup for one exact name (#1051 extraction).
+     * Both call sites need the same two steps; nothing else changed.
+     */
+    private lookupAttachmentByName;
+    /**
+     * Final path segment of a reference, or '' when there is none (#1051).
+     *
+     * Returns '' for a trailing slash so callers can skip rather than searching
+     * for an empty filename, which `getAttachmentByFilename` would answer
+     * unpredictably.
+     */
+    static basenameOf(src: string): string;
+    /**
+     * Generate (or return cached) thumbnail for an image attachment.
+     *
+     * Delegates to the provider's getThumbnail() implementation.
+     * Returns null for non-image attachments or when the provider has no
+     * thumbnail capability.
+     *
+     * #1460: a file in one of the requester's own private stores has no record
+     * in the shared index and no bytes in the shared pool, so the provider's
+     * cache-on-disk path cannot make its thumbnail. It is rendered from the
+     * bytes in memory and deliberately NOT written to the shared `.thumbs`
+     * folder: a thumbnail of a private file is the private file, smaller, and
+     * putting one in a shared directory would undo the move this issue is.
+     *
+     * @param {string} attachmentId - Attachment identifier
+     * @param {string} size         - Size string e.g. "150x150"
+     * @param ctx - Whose reading this is (#1179). Mandatory and positional.
+     * @returns {Promise<Buffer|null>}
+     */
+    getThumbnail(attachmentId: string, size: string, ctx: ActorContext): Promise<Buffer | null>;
+    /**
+     * Scan page content for local attachment references and synchronise mentions.
+     *
+     * Parses [{Image src='...'}] and [{ATTACH src='...'}] directives, resolves
+     * each filename to an attachment identifier, then diffs against the current
+     * mentions stored on each attachment:
+     *   - newly referenced attachments gain a mention for pageName
+     *   - previously referenced attachments that are no longer in content lose it
+     *
+     * Replaces the lazy attachToPage() side-effect in resolveAttachmentSrc() with
+     * a deterministic, save-time update. See #405 Phase 4 / #403.
+     *
+     * @param {string} pageName - Name of the page being saved
+     * @param {string} content  - Raw wiki markup content
+     * @returns {Promise<void>}
+     */
+    /**
+     * Canonical local-attachment reference extraction — `[{Image src='…'}]` /
+     * `[{ATTACH src='…'}]` filenames, skipping media:// URIs, external URLs,
+     * and absolute paths. Shared by save-time mention sync, the batch
+     * reconciler (scripts/reconcile-attachment-mentions.ts mirrors it), and the
+     * #865 health report.
+     */
+    static extractLocalAttachmentRefs(content: string): Set<string>;
+    /**
+     * #865: identifier-URL references — `/attachments/<sha256>` anywhere in
+     * content (markdown images/links, raw URLs). Storybook-generated day pages
+     * embed route maps this way (`![Day 4 route](/attachments/<id>)`); these
+     * are real render-time references and count as mentions.
+     */
+    static extractAttachmentIdRefs(content: string): Set<string>;
+    /**
+     * @param ctx - Whose save this is (#1179). Mandatory and positional: the
+     *   requester's own private-store files take part in this too (#1460) —
+     *   a file uploaded into their store from a public page's editor is
+     *   mentioned by that page, and its mentions live in its store's own index.
+     */
+    syncPageMentions(pageName: string, content: string, ctx: ActorContext): Promise<void>;
+    /**
+     * #865 Slice 2: attachment health report — computed fresh on demand
+     * (admin-triggered; walks every page's content, a few seconds on large
+     * instances). Read-only. Trustworthy only after mentions reconciliation
+     * (run `npm run reconcile:mentions` / rely on save-time sync).
+     *
+     * Sections:
+     *  - orphans:         records no page references (empty mentions)
+     *  - recordlessFiles: disk files with no metadata record
+     *  - missingFiles:    records whose storage file is gone from disk
+     *  - brokenRefs:      page markup references naming no record (ref → pages)
+     *  - looseTextRefs:   record filenames appearing in content OUTSIDE
+     *                     canonical markup (never tracked as mentions)
+     *
+     * #1460: the requester's OWN private-store files are merged into the record
+     * set, so one of their files is not reported as a broken reference merely
+     * because it is in no shared index. `recordlessFiles` and `missingFiles`
+     * stay shared-pool questions — they compare the shared index against the
+     * shared storage folder, which a store's files are not in.
+     *
+     * @param ctx - Whose report this is (#1179). Mandatory and positional; an
+     *   admin sees their own stores merged, never anyone else's.
+     */
+    getHealthReport(ctx: ActorContext): Promise<{
+        totals: {
+            records: number;
+            diskFiles: number;
+            pagesScanned: number;
+        };
+        orphans: Array<{
+            identifier: string;
+            name?: string;
+            contentSize?: number;
+            dateCreated?: string;
+            author?: string;
+        }>;
+        recordlessFiles: string[];
+        missingFiles: Array<{
+            identifier: string;
+            name?: string;
+            storageLocation?: string;
+        }>;
+        brokenRefs: Array<{
+            ref: string;
+            pages: string[];
+        }>;
+        looseTextRefs: string[];
+    }>;
+    /**
+     * #865 Slice 3: guarded orphan cleanup — quarantine, never hard-delete.
+     *
+     * Recomputes the health report FRESH (never trusts a client-supplied list),
+     * then moves verified orphan records (+ their files) and recordless disk
+     * files into `<storage>/quarantine/`. Removed records are appended to a
+     * per-run manifest in the quarantine dir so the operation is reversible.
+     * `dryRun: true` returns exactly what WOULD move, touching nothing.
+     *
+     * #1460: only the SHARED POOL's orphans are selected. The quarantine folder
+     * is a shared directory, so moving a private-store file into it would carry
+     * it out of its store and put its name back in shared storage — the exact
+     * move this issue undoes. A store's own files are its owner's to delete,
+     * through `deleteAttachment`.
+     *
+     * @param ctx - Whose run this is (#1179). Mandatory and positional.
+     */
+    quarantineOrphans(options: {
+        dryRun: boolean;
+        includeOrphans: boolean;
+        includeRecordless: boolean;
+    }, ctx: ActorContext): Promise<{
+        dryRun: boolean;
+        orphansSelected: Array<{
+            identifier: string;
+            name?: string;
+            contentSize?: number;
+        }>;
+        recordlessSelected: string[];
+        quarantined: number;
+        skipped: number;
+        manifestPath: string | null;
+    }>;
+    /**
+     * Refresh attachment list (rescan storage)
+     *
+     * @returns {Promise<void>}
+     */
+    refreshAttachmentList(): Promise<void>;
+    /**
+     * Backup manager data
+     * Delegates to provider's backup method
+     *
+     * @returns {Promise<AttachmentBackupData>}
+     */
+    backup(): Promise<AttachmentBackupData>;
+    /**
+     * Restore manager data from backup
+     * Delegates to provider's restore method
+     *
+     * @param {AttachmentBackupData} backupData - Backup data from backup() method
+     * @returns {Promise<void>}
+     */
+    restore(backupData: AttachmentBackupData): Promise<void>;
+    /**
+     * Shutdown the manager
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Normalize provider name to PascalCase class name
+     * @param {string} providerName - Lowercase provider name (e.g., 'basicattachmentprovider')
+     * @returns {string} PascalCase class name (e.g., 'BasicAttachmentProvider')
+     * @private
+     */
+    private normalizeProviderName;
+    /**
+     * Format byte size to human-readable string
+     * @param {number} bytes - Size in bytes
+     * @returns {string} Formatted size (e.g., "10 MB")
+     * @private
+     */
+    private formatSize;
+}
+export default AttachmentManager;