@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/providers/BasicAttachmentProvider.d.ts

@@ -0,0 +1,599 @@
+import BaseAttachmentProvider, { FileInfo, User, AttachmentResult } from './BaseAttachmentProvider.js';
+import type { ProviderInfo, StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import { AttachmentMetadata } from '../types/index.js';
+import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, AssetMetadata, AssetMetadataPatch } from '../types/Asset.js';
+import type { CreativeWork } from '../types/Schema.js';
+import type { ActorContext } from '../context/ActorContext.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Schema.org Person metadata
+ */
+interface SchemaPerson {
+    '@type': 'Person';
+    name: string;
+    email?: string;
+}
+/**
+ * Schema.org mention reference
+ */
+interface SchemaMention {
+    '@type'?: 'Thing';
+    name?: string;
+    url?: string;
+}
+/**
+ * Schema.org CreativeWork metadata for attachments
+ */
+interface SchemaCreativeWork {
+    '@context': 'https://schema.org';
+    '@type': 'CreativeWork';
+    identifier: string;
+    name: string;
+    description?: string;
+    author?: SchemaPerson;
+    editor?: SchemaPerson;
+    dateCreated: string;
+    dateModified: string;
+    encodingFormat: string;
+    contentSize: number;
+    url: string;
+    storageLocation: string;
+    isFamilyFriendly?: boolean;
+    isBasedOn?: string;
+    mentions: SchemaMention[];
+    /** Whether this attachment belongs to a private page */
+    isPrivate?: boolean;
+    /** Username of the page creator; set when isPrivate is true */
+    creator?: string;
+    /** Private-store id when the file lives in the page store (#1386) */
+    store?: string;
+    /** Structured metadata extracted at upload time (EXIF via sharp) — Phase 5 #405 */
+    assetMetadata?: AssetMetadata;
+    /** Title embedded in the document (PDF /Info Title; docx core.xml dc:title). Distinct from the uploaded filename. */
+    documentTitle?: string;
+    /** Author embedded in the document (PDF /Info Author; docx dc:creator). Distinct from the uploader's user. */
+    documentAuthor?: string;
+    /** Subject / abstract embedded in the document (PDF /Info Subject; docx dc:description). */
+    documentSubject?: string;
+    /** Keywords / tags embedded in the document (PDF /Info Keywords; docx dc:subject). String array, deduplicated. */
+    documentKeywords?: string[];
+    /** Document's own CreationDate (when the file was first authored). Distinct from upload time. */
+    documentDateCreated?: string;
+    /** Document's own ModDate (last edit before upload). Distinct from upload time. */
+    documentDateModified?: string;
+    /** BCP-47 language tag from the document (PDF /Lang; docx core.xml dc:language). */
+    inLanguage?: string;
+}
+/**
+ * Backup data structure
+ */
+interface BackupData extends Record<string, unknown> {
+    providerName: string;
+    timestamp: string;
+    metadataFile: string;
+    storageDirectory: string;
+    attachments: Array<[string, SchemaCreativeWork]>;
+}
+/**
+ * The extension to store a file under, given what the uploader called it and
+ * what they said it was.
+ *
+ * A stored file is named `{generated-id}{ext}`. The id is ours; the extension
+ * used to be whatever `path.extname()` returned for the uploaded name — and
+ * that function does not promise an extension, it promises everything after
+ * the last dot in the basename. For `photo.jpg` that is `.jpg`. For a name
+ * written by hand in the request, such as `x.\..\..\etc\passwd`, it is
+ * `.\etc\passwd`, and we pasted it onto the id without ever asking whether it
+ * looked like an extension. Harmless on Linux, where `\` is an ordinary
+ * character — but it is untrusted text in a filename we construct, which it
+ * should never have been.
+ *
+ * So an extension is now defined rather than inherited: a short run of letters
+ * and digits, and nothing else. It comes from
+ *
+ *   1. the uploaded name, when that already matches the definition — which is
+ *      every real file, and keeps `.docx`, `.heic` and the rest that no table
+ *      here lists; or
+ *   2. the declared MIME type through the table above, a closed set we own; or
+ *   3. nowhere, and the file is stored as the bare id, exactly as an
+ *      extensionless upload has always been.
+ *
+ * Nothing downstream depends on this: a download's Content-Type comes from the
+ * recorded `encodingFormat`, and the only reader of the stored extension is the
+ * orphan-recovery scan, which maps it back through this same table.
+ */
+export declare function safeStoredExtension(originalName: string, mimeType?: string): string;
+/**
+ * BasicAttachmentProvider - Filesystem-based attachment storage
+ *
+ * Implements attachment storage using filesystem with Schema.org CreativeWork metadata.
+ * Attachments are stored in a shared directory structure, not tied to individual pages.
+ * Page references are tracked via the "mentions" array in metadata.
+ *
+ * Based on JSPWiki's BasicAttachmentProvider:
+ * https://github.com/apache/jspwiki/blob/master/jspwiki-main/src/main/java/org/apache/wiki/providers/BasicAttachmentProvider.java
+ *
+ * Features:
+ * - Filesystem storage with SHA-256 content hashing
+ * - Schema.org CreativeWork metadata format
+ * - Shared storage model with page mentions tracking
+ * - Automatic metadata persistence
+ * - Backup/restore support
+ */
+declare class BasicAttachmentProvider extends BaseAttachmentProvider implements AssetProvider {
+    private storageDirectory;
+    /** Pre-#1386 attachments/{legacyprivateroot}/{user}/ — migrate-FROM and read fallback only. */
+    private legacyPrivateDir;
+    private pagesDirectory;
+    private privateStoreLayout;
+    private thumbDir;
+    private metadataFile;
+    private attachmentMetadata;
+    private maxFileSize;
+    private allowedMimeTypes;
+    private hashMethod;
+    /**
+     * Lazily-instantiated ExifTool worker (Slice 5 of #755 / #759).
+     * Used to extract embedded document metadata from PDFs / docx at upload
+     * time. Created on first use to avoid spawning a perl process when the
+     * provider initialises but never sees a PDF or docx upload.
+     */
+    private _exiftool;
+    private exiftool;
+    /**
+     * MIME types that carry extractable document metadata.
+     * exiftool reads both via its PDF / OOXML modules.
+     */
+    private static readonly DOC_METADATA_MIME_TYPES;
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the provider
+     * All configuration access via ConfigurationManager
+     */
+    initialize(): Promise<void>;
+    /**
+     * Verify that the attachment storage directory is accessible.
+     *
+     * Returns false when the directory cannot be read — e.g. a NAS or SLOW_STORAGE
+     * volume that has been unmounted or an SMB share that has dropped.  AssetManager
+     * uses this to skip the provider during fan-out rather than surfacing I/O errors
+     * to end users.
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Format bytes to human-readable size
+     * @param bytes - Size in bytes
+     * @returns Formatted size
+     * @private
+     */
+    private formatSize;
+    /**
+     * Rewrite stale storageLocation paths after a data migration.
+     *
+     * Compares each entry's directory against the current storageDirectory.
+     * If they differ, the absolute path is replaced with the correct one
+     * (preserving the basename/hash filename) and metadata is saved once.
+     * Private attachments are corrected to the page store (legacy leftovers
+     * stay at attachments/{legacyprivateroot} until the file itself moves).
+     */
+    private migrateStaleStoragePaths;
+    /**
+     * On-disk path for an attachment. Private files live in the page store;
+     * a leftover under attachments/{legacyprivateroot} is read fallback only.
+     */
+    private resolveAttachmentFilePath;
+    /**
+     * Load metadata from JSON file
+     * @private
+     */
+    private loadMetadata;
+    /**
+     * Save metadata to JSON file
+     * @private
+     */
+    private saveMetadata;
+    /**
+     * Generate unique attachment ID using SHA-256 hash of content
+     * @param buffer - File data
+     * @returns Attachment ID (hash)
+     * @private
+     */
+    private generateAttachmentId;
+    /**
+     * Validate file against constraints
+     * @param fileInfo - File information
+     * @private
+     */
+    private validateFile;
+    /**
+     * Store an attachment with metadata (internal method using Schema.org format)
+     * @param fileBuffer - File data
+     * @param fileInfo - { originalName, mimeType, size }
+     * @param metadata - Schema.org CreativeWork metadata
+     * @param user - User object { name, email }
+     * @param options - Privacy-aware storage options
+     * @returns Complete attachment metadata
+     * @private
+     */
+    private storeAttachmentInternal;
+    /**
+     * Store an attachment with metadata (BaseAttachmentProvider interface method)
+     * @param fileBuffer - File data
+     * @param fileInfo - { originalName, mimeType, size }
+     * @param metadata - Attachment metadata
+     * @param user - User object
+     * @returns Attachment metadata
+     */
+    storeAttachment(fileBuffer: Buffer, fileInfo: FileInfo, metadata?: Partial<AttachmentMetadata>, user?: User | null): Promise<AttachmentMetadata>;
+    /**
+     * Get attachment file and metadata
+     *
+     * Falls back to a disk scan when metadata is missing but a file matching
+     * `{attachmentId}.*` exists in the storage directory (orphaned file). This
+     * handles the case where attachment metadata was lost without requiring a
+     * data repair before the file can be served. A warning is logged so operators
+     * know the metadata repair is still needed.
+     *
+     * @param attachmentId - Attachment identifier
+     * @returns File buffer and metadata or null
+     */
+    getAttachment(attachmentId: string): Promise<AttachmentResult | null>;
+    /**
+     * Disk-scan fallback for orphaned attachment files (file on disk, no metadata record).
+     * @param attachmentId - Attachment identifier (SHA-256 hash)
+     * @returns File buffer and synthetic metadata, or null if not found
+     * @private
+     */
+    private getOrphanedAttachment;
+    private storeIndexFile;
+    private storeFilePath;
+    private requirePagesDirectory;
+    private readStoreIndex;
+    private writeStoreIndex;
+    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>;
+    /** Everything this store lists, newest first — the store's half of a merged list (#1460). */
+    listFilesInStore(location: StoreFileLocation): Promise<StoreFileEntry[]>;
+    filesInStoreForPage(location: StoreFileLocation, pageName: string): Promise<StoreFileEntry[]>;
+    /**
+     * Add or remove `pageName` in one store file's mentions (#1460) — the store
+     * index's half of save-time mention sync. `false` when this store does not
+     * list `id`, so a caller can try the next of its own stores.
+     */
+    setFileMentionInStore(location: StoreFileLocation, id: string, pageName: string, mentioned: boolean): Promise<boolean>;
+    /**
+     * Move one record out of the global `attachment-metadata.json` and into its
+     * store's own index (#1460), bytes and all.
+     *
+     * The file KEEPS the name it has: renaming it would break nothing that is
+     * written down, but it would rewrite a file for no reason, and a store is
+     * meant to be a directory an operator can read. The entry keeps the record's
+     * identifier too — that id is the `/attachments/{id}` URL on every page that
+     * references the file.
+     *
+     * Idempotent: a record already gone from the map, or a store that already
+     * lists the id, is a no-op that answers `null`. The move itself is skipped
+     * when the bytes are already in place.
+     *
+     * @returns the store entry it wrote, or null when there was nothing to move
+     */
+    adoptRecordIntoStore(location: StoreFileLocation, id: string): Promise<StoreFileEntry | null>;
+    /**
+     * The private records still sitting in the shared index (#1460) — what the
+     * start-up migration has to move. Identifier, owner and store only: enough
+     * to place the file, and nothing of its name leaves this method.
+     *
+     * Two ways a record says it is private, in order:
+     *
+     * - `isPrivate`, #1398's flag, written by `storeAttachmentInternal` together
+     *   with `creator` and `store`. That is the record deciding from itself.
+     * - failing that, a mention naming a private page — `private/{owner}/{store}/{title}`
+     *   since #1456. The record is then placed by the page it is attached to,
+     *   with `owner: null` so the caller confirms it through PageManager, which
+     *   is what actually knows whose store a page is in.
+     *
+     * A record that is neither is a public attachment and is not listed: the
+     * shared pool is exactly what stays behind.
+     */
+    privateRecordsInSharedIndex(): Array<{
+        id: string;
+        owner: string | null;
+        store: string | null;
+        pages: string[];
+    }>;
+    deleteFileInStore(location: StoreFileLocation, id: string): Promise<StoreFileEntry | null>;
+    /**
+     * Copy a shared-pool file into a store under the same id, mentioned by
+     * `pageName` there. The shared record is left as it is. A store that already
+     * lists the id just gains the mention.
+     *
+     * @returns the store entry, or null when the pool has no such file
+     */
+    copyRecordIntoStore(location: StoreFileLocation, id: string, pageName: string): Promise<StoreFileEntry | null>;
+    /**
+     * Copy a store's file into another store under the same id, mentioned by
+     * `pageName` there. A destination that already lists the id just gains the
+     * mention.
+     *
+     * @returns the destination's entry, or null when the source does not list it
+     */
+    copyStoreFileToStore(from: StoreFileLocation, to: StoreFileLocation, id: string, pageName: string): Promise<StoreFileEntry | null>;
+    /**
+     * Copy a store's file into the shared pool under the same id, opened, and
+     * mentioned by `pageName` (a public page). A pool that already holds the id
+     * just gains the mention.
+     *
+     * @returns true when the pool holds the file afterwards
+     */
+    copyStoreFileToPool(from: StoreFileLocation, id: string, pageName: string): Promise<boolean>;
+    /**
+     * Take a file out of the shared pool: its record, its bytes and any cached
+     * thumbnails of it (#1842) — used when the file has moved into a vault and
+     * no public page uses it any more, so no public copy of it is left.
+     */
+    removeRecordFromPool(id: string): Promise<boolean>;
+    /**
+     * Set a shared-pool record's mentions to exactly `names` (#1842), keeping the
+     * mention objects it already has for those names.
+     */
+    setPoolMentions(id: string, names: string[]): Promise<boolean>;
+    /**
+     * Get attachment metadata only
+     * @param attachmentId - Attachment identifier
+     * @returns Attachment metadata or null
+     */
+    getAttachmentMetadata(attachmentId: string): Promise<AttachmentMetadata | null>;
+    /**
+     * Update attachment metadata
+     * @param attachmentId - Attachment identifier
+     * @param updates - Metadata updates
+     * @returns Success status
+     */
+    updateAttachmentMetadata(attachmentId: string, updates: Partial<AttachmentMetadata>): Promise<boolean>;
+    /**
+     * Delete an attachment
+     * @param attachmentId - Attachment identifier
+     * @returns True if deleted, false if not found
+     */
+    deleteAttachment(attachmentId: string): Promise<boolean>;
+    /**
+     * Check if attachment exists
+     * @param attachmentId - Attachment identifier
+     * @returns True if exists
+     */
+    attachmentExists(attachmentId: string): Promise<boolean>;
+    /**
+     * Get all attachments metadata
+     * @returns Array of attachment metadata
+     */
+    getAllAttachments(): Promise<AttachmentMetadata[]>;
+    /**
+     * Get attachments used by a specific page
+     * @param pageName - Page name/title
+     * @returns Array of attachment metadata
+     */
+    getAttachmentsForPage(pageName: string): Promise<AttachmentMetadata[]>;
+    /**
+     * Find an attachment by its original filename across all attachments
+     * @param filename - Original filename to search for
+     * @returns Matching attachment metadata or null
+     */
+    getAttachmentByFilename(filename: string): Promise<AttachmentMetadata | null>;
+    /**
+     * List attachments for a page (AttachmentProvider interface method)
+     * @param pageUuid - Page UUID
+     * @returns Array of attachment metadata
+     */
+    listAttachments(pageUuid: string): Promise<AttachmentMetadata[]>;
+    /**
+     * Delete all attachments for a page
+     * @param pageUuid - Page UUID
+     * @returns Number of attachments deleted
+     */
+    deletePageAttachments(pageUuid: string): Promise<number>;
+    /**
+     * Refresh attachment list (rescan storage)
+     * @returns Promise that resolves when complete
+     */
+    refreshAttachmentList(): Promise<void>;
+    /**
+     * #865 Slice 2: basenames of all stored attachment files on disk (top-level
+     * storage dir; excludes .json bookkeeping). Used by the health report to
+     * find recordless files and missing-file records.
+     */
+    listStorageFiles(): Promise<string[]>;
+    /**
+     * #865 Slice 3: move an attachment (record + stored file) into the
+     * quarantine subdirectory instead of hard-deleting. The record is removed
+     * from live metadata and appended to a per-run manifest inside quarantine/
+     * so the operation is reversible by hand. Skips (returns false) on any
+     * error — never deletes on failure (media-prune #867 precedent).
+     */
+    quarantineAttachment(identifier: string, manifestPath: string): Promise<boolean>;
+    /**
+     * #865 Slice 3: move a recordless disk file into quarantine. Skips on error.
+     */
+    quarantineFile(basename: string): Promise<boolean>;
+    /** #865 Slice 3: absolute quarantine directory path (for manifests/report). */
+    getQuarantineDir(): string | null;
+    /**
+     * Get provider information
+     * @returns Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Backup provider data
+     * @returns Backup data
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore provider data from backup
+     * @param backupData - Backup data
+     * @returns Promise that resolves when complete
+     */
+    restore(backupData: Record<string, unknown>): Promise<void>;
+    readonly id = "local";
+    readonly displayName = "Local Attachments";
+    readonly capabilities: import('../types/Asset.js').ProviderCapability[];
+    /**
+     * AssetProvider.getThumbnail() — generate (and cache) a JPEG thumbnail for image attachments.
+     * Returns null for non-image attachments or when the source file cannot be processed.
+     */
+    getThumbnail(id: string, size: string): Promise<Buffer | null>;
+    /**
+     * Extract embedded document metadata via ExifTool (Slice 5 of #755 / #759).
+     *
+     * Handles PDFs and Office Open XML (`.docx`, `.xlsx`, `.pptx`). Returns the
+     * subset of fields we map into `SchemaCreativeWork` per the schemas.md
+     * `DigitalDocument` per-source mapping. Returns null for non-document MIME
+     * types or when extraction fails (treated as non-fatal — uploads always
+     * succeed even if metadata extraction trips).
+     */
+    private extractDocMetadata;
+    /**
+     * Slice 5b of #760 (#763) — walk every stored attachment and re-extract
+     * embedded document metadata for the supported doc MIMEs. Backfills the
+     * seven Slice-5 fields (documentTitle / documentAuthor / documentSubject /
+     * documentKeywords / documentDateCreated / documentDateModified /
+     * inLanguage) on pre-v3.27.0 records that never went through the
+     * Slice-5 extraction path at upload time.
+     *
+     * Per-file failures are non-fatal (logged + counted) — mirrors the
+     * existing `extractDocMetadata` contract where uploads succeed even when
+     * exiftool trips. Non-document MIMEs are skipped without modification.
+     * Returns a summary suitable for the background-job report.
+     */
+    backfillDocMetadata(onProgress?: (processed: number, total: number) => void): Promise<{
+        scanned: number;
+        updated: number;
+        skipped: number;
+        errors: number;
+    }>;
+    /**
+     * Apply extracted doc-metadata to a stored record field-by-field. Sets each
+     * field when the extracted value exists; clears when extraction returned
+     * null/undefined for that field. Per-field mutation so a partial re-extract
+     * doesn't drop unrelated existing data. Returns true when the record
+     * changed (caller decides whether to persist).
+     *
+     * Shared by `backfillDocMetadata` (Slice 5b / #763) and
+     * `storeAttachmentInternal`'s dedup-by-hash branch (#764). Keeping the
+     * two call sites on the same helper ensures their "set vs clear stale"
+     * semantics stay in lockstep.
+     */
+    private applyDocMetadataFields;
+    /**
+     * Format an exiftool-vendored date value to ISO-ish "YYYY-MM-DD HH:MM:SS".
+     * Accepts the `ExifDateTime` shape (object with year/month/etc.) or a string
+     * passthrough. Returns undefined for anything unparseable.
+     */
+    private formatExifDate;
+    /**
+     * Convert a SchemaCreativeWork record to a schema.org-shaped CreativeWork
+     * (Slice 5 of #755 / #759).
+     *
+     * For PDF / docx / xlsx / pptx attachments → `DigitalDocument` with embedded
+     * doc-metadata fields populated. For everything else → a base CreativeWork
+     * (no subtype specialisation) — image/video attachments that need full
+     * ImageObject / VideoObject treatment are out-of-scope for this slice
+     * (they go through the media path).
+     *
+     * Public so AttachmentManager (the registered `CatalogSource`) can call it
+     * without exposing the internal SchemaCreativeWork shape.
+     */
+    toCreativeWork(schema: SchemaCreativeWork): CreativeWork;
+    /** Convert a SchemaCreativeWork record to a unified AssetRecord. */
+    private schemaToAssetRecord;
+    /**
+     * AssetProvider.search() — searches by filename and description.
+     *
+     * The shared pool only. A private store's files are in no shared index, so
+     * they are searched through {@link searchFilesInStore}, by the one caller
+     * that has the requester's context to say which stores are theirs (#1460).
+     */
+    search(query: AssetQuery): Promise<AssetPage>;
+    /**
+     * One private store's files as search results (#1460) — the store's half of
+     * an asset search, matched by the SAME rules the shared pool is, so a
+     * private file is findable the way a public one is and no filter exists in
+     * two places. Merging, sorting and paging are the caller's: it has the other
+     * halves.
+     */
+    searchFilesInStore(location: StoreFileLocation, query: AssetQuery): Promise<AssetRecord[]>;
+    /**
+     * A store file as the CreativeWork shape the rest of this provider speaks
+     * (#1460), so one converter, one filter and one record shape serve both
+     * halves of a merged list. `storageLocation` is deliberately absent: where a
+     * private file sits on disk is not something a search result carries.
+     */
+    private storeEntryToSchema;
+    /** The free-text and MIME-category rules of an asset search, in one place (#1460). */
+    private matchSchemas;
+    /**
+     * AssetProvider.updateMetadata() — edit an attachment's descriptive metadata (#999).
+     *
+     * **SIDECAR ONLY. This must never write into the file.**
+     *
+     * Attachment IDs are CONTENT HASHES — see `calculateHash`, and note the
+     * stored filename is `<sha256>.<ext>`. Media items are not content-addressed;
+     * attachments are. Writing embedded metadata (EXIF/IPTC/XMP) rewrites the
+     * file, so the id and filename stop matching the bytes they name:
+     *
+     *     id       c3939c4391744bc8006f726c4e8333...
+     *     file sha c7ae23c100d515d5...      <- after a single metadata write
+     *
+     * Nothing errors; dedup and any integrity check simply stop being true. An
+     * earlier version of this method did exactly that and was backed out
+     * (`ffe16c0d`); the failure was only caught because restoring a test file
+     * with `cmp` failed on a byte comparison.
+     *
+     * Operator decision (2026-07-28): sidecar over re-hash-and-re-key. Re-keying
+     * would be more honest — the file and its name would stay in agreement — but
+     * the id is the URL, so every existing `[{ATTACH}]` reference on every page
+     * would break on an edit. Content addressing is worth more than embedded
+     * fidelity here.
+     *
+     * **The consequence, which is real:** an attachment's ngdpbase metadata and
+     * its embedded metadata diverge after an edit, and a download carries the
+     * file's original values. Media items do not behave this way. If embedded
+     * fidelity matters for a given file, it belongs in the media library, which
+     * is not content-addressed and does write through.
+     *
+     * The tag mapping in `utils/assetMetadataTags` is deliberately NOT used here.
+     * It is correct, and it is for providers that write to files.
+     *
+     * @param id - Attachment identifier (content hash)
+     * @param patch - Fields to change; `null` clears, omission leaves alone
+     * @returns The refreshed record, or null when the attachment is unknown
+     * @throws Error when `dateTimeOriginal` is present but unparseable
+     */
+    updateMetadata(id: string, patch: AssetMetadataPatch): Promise<AssetRecord | null>;
+    /**
+     * AssetProvider.getById() — returns AssetRecord for the given attachment ID.
+     */
+    getById(id: string): Promise<AssetRecord | null>;
+    /**
+     * AssetProvider.store() — routed through the asset-upload door,
+     * AttachmentManager.uploadAttachment (#1629), so it gets the same
+     * permission check, destination rules and audit record as every upload.
+     */
+    store(buffer: Buffer, info: AssetInput, ctx: ActorContext): Promise<AssetRecord>;
+    /**
+     * AssetProvider.delete() — delegates to deleteAttachment().
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * AssetProvider.stream() — opens a read stream for the attachment file.
+     */
+    stream(id: string): Promise<NodeJS.ReadableStream | null>;
+}
+export default BasicAttachmentProvider;

package/lib/src/providers/CloudflareAccessAuthProvider.d.ts

@@ -0,0 +1,72 @@
+/**
+ * CloudflareAccessAuthProvider — JWT-based trust of Cloudflare Access (#649).
+ *
+ * Cloudflare Access is a zero-trust gateway: it authenticates users at the
+ * edge (against your IdP) and forwards a signed JWT to the origin in the
+ * `Cf-Access-Jwt-Assertion` header. This provider verifies that JWT and
+ * coordinates the identity to a local User record.
+ *
+ * Design decisions (per #649 operator-confirmed 2026-05-25):
+ *  - Q1 — User coordination by **email** (`identity.email` from the JWT).
+ *  - Q2 — Unknown user → **JIT-provision** with default-role (overridable
+ *    per CF group via `group-map`).
+ *  - Q3 — CF `identity.groups[]` → ngdpbase roles via **config-map**.
+ *
+ * Cloudflare-Access-specific — not a generalised federated-IdP abstraction.
+ *
+ * Wire-up: this provider is invoked by the request-time middleware in
+ * `src/app.ts` (header → verify → JIT-or-lookup → `req.session.username`).
+ * It does NOT participate in the explicit /login flow; routes call AuthManager
+ * with `providerId='cloudflare-access'` only from the middleware path.
+ *
+ * Token verification uses `jose.createRemoteJWKSet` against
+ * `https://<team-domain>/cdn-cgi/access/certs` — keys are fetched on demand
+ * and cached + rotated by jose internally.
+ */
+import { type JWTVerifyGetKey } from 'jose';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { AuthProvider, AuthVerifyCredentials, AuthResult, FactorDescription } from './BaseAuthProvider.js';
+export interface CloudflareAccessConfig {
+    /** Cloudflare team domain, e.g. `mjwilleke.cloudflareaccess.com`. */
+    teamDomain: string;
+    /** Application AUD tag (one per CF Access Application). */
+    applicationAud: string;
+    /** Role assigned to JIT-provisioned users when no CF group maps. */
+    defaultRole: string;
+    /**
+     * Map of CF group name → ngdpbase role name. CF groups absent from this
+     * map are silently ignored at provisioning time (user still gets defaultRole).
+     */
+    groupMap: Record<string, string>;
+}
+export declare class CloudflareAccessAuthProvider implements AuthProvider {
+    readonly id = "cloudflare-access";
+    readonly displayName = "Cloudflare Access";
+    /** An identity provider, as Google: AAL1 with no `amr` of its own (#1523). */
+    readonly factor: FactorDescription;
+    private readonly engine;
+    private readonly config;
+    private readonly jwks;
+    private readonly issuer;
+    /**
+     * @param jwksOverride optional pre-built JWKS getter for tests; production
+     *   omits this and uses `createRemoteJWKSet` against the team-domain certs
+     *   endpoint.
+     */
+    constructor(engine: WikiEngine, config: CloudflareAccessConfig, jwksOverride?: JWTVerifyGetKey);
+    /**
+     * Verify the Cloudflare Access JWT and resolve (or provision) the local user.
+     * `credentials.token` is the raw JWT lifted from the `Cf-Access-Jwt-Assertion`
+     * header by the request-time middleware.
+     */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    private resolveOrProvision;
+    /**
+     * Map CF identity.groups[] to ngdpbase role names. Groups without an
+     * entry in config.groupMap are dropped silently. Result always contains
+     * config.defaultRole — even with no group hits, user gets the default.
+     */
+    private mapGroupsToRoles;
+    private findUserByEmail;
+    private deriveUniqueUsername;
+}