@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/types/Provider.d.ts

@@ -0,0 +1,810 @@
+import type { StoreFileIO } from '../utils/privateStoreFiles.js';
+import type { UserCatalogPage } from '../utils/privateStoreCatalogs.js';
+import type { StoreSearchDocument } from '../utils/storeSearchIndex.js';
+import type { ActorContext } from '../context/ActorContext.js';
+/**
+ * Provider type definitions for ngdpbase
+ *
+ * This module defines interfaces for all provider types (page, user, attachment,
+ * search, cache, audit) following JSPWiki's provider pattern for pluggable backends.
+ */
+import { WikiPage, PageFrontmatter, PageInfo, PageSaveOptions, PageSearchResult, PageListOptions } from './Page.js';
+import { VersionManifest, VersionContent, VersionDiff, VersionHistoryEntry } from './Version.js';
+import { User, UserUpdateData, UserSession } from './User.js';
+/**
+ * Provider information returned by getProviderInfo()
+ */
+export interface ProviderInfo {
+    /** Provider name */
+    name: string;
+    /** Provider version */
+    version: string;
+    /** Provider description */
+    description?: string;
+    /** Provider features */
+    features?: string[];
+}
+/**
+ * Base provider interface
+ *
+ * All providers must implement this interface.
+ */
+export interface BaseProvider {
+    /**
+     * Initialize the provider
+     * @returns Promise that resolves when initialization is complete
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown the provider (optional)
+     * @returns Promise that resolves when shutdown is complete
+     */
+    shutdown?(): Promise<void>;
+    /**
+     * Get provider information
+     * @returns Provider metadata
+     */
+    getProviderInfo?(): ProviderInfo;
+    /**
+     * Backup provider data
+     * @returns Promise resolving to backup data
+     */
+    backup?(): Promise<Record<string, unknown>>;
+    /**
+     * Restore provider data from backup
+     * @param backupData - Backup data from backup() method
+     * @returns Promise that resolves when restore is complete
+     */
+    restore?(backupData: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Options for {@link PageProvider.getRecentChanges}.
+ */
+export interface RecentChangesOptions {
+    /** Maximum number of entries to return after filtering. Default 50. */
+    limit?: number;
+    /** Only include pages modified at or after this cutoff. */
+    since?: Date | string;
+    /**
+     * Caller principals (typically `[...userContext.roles, userContext.username]`).
+     * Used to evaluate audience visibility for private pages. If omitted (anonymous),
+     * private pages are excluded.
+     *
+     * #1116: this is the ONLY visibility input. A caller supplies facts about who
+     * is asking, never the conclusion — the provider derives the admin bypass
+     * from an `admin` principal itself. The old `includeAll` boolean was the
+     * conclusion handed over, and any caller could pass `true`.
+     */
+    principals?: string[];
+}
+/**
+ * One page in a private store, as {@link PageProvider.listPrivateStorePages}
+ * reports it (#1457): where it is, and what it is called there.
+ */
+export interface PrivateStorePageRef {
+    owner: string;
+    store: string;
+    title: string;
+    uuid: string;
+}
+/**
+ * Options for {@link PageProvider.getPagesByCreator} (#640).
+ */
+export interface GetPagesByCreatorOptions {
+    /** Maximum number of entries returned. Default 1000 (intent: full per-user list). */
+    limit?: number;
+    /** Only include pages where `isPrivate === true`. */
+    onlyPrivate?: boolean;
+    /** Sort order. Default `lastModified-desc`. */
+    sortBy?: 'lastModified-desc' | 'title-asc';
+    /**
+     * Only include pages carrying at least ONE of these `system-keywords` (#1004).
+     * Matched case-insensitively. Omitted or empty means no keyword filter.
+     *
+     * Read from page frontmatter, not from a denormalised index field: the page
+     * index has no system-keywords column, and adding one would leave every
+     * pre-existing page invisible to this filter until its next save (the #1003
+     * failure mode). Frontmatter is the source of truth and needs no back-fill.
+     */
+    systemKeywords?: string[];
+}
+/**
+ * Options for {@link PageProvider.getPagesByEditor} / {@link PageProvider.getPagesSharedWith} (#640 Phase 2).
+ */
+export interface PagesScanOptions {
+    /** Maximum number of entries returned. Default 1000. */
+    limit?: number;
+    /** Sort order. Default `lastModified-desc`. */
+    sortBy?: 'lastModified-desc' | 'title-asc';
+}
+/**
+ * Single entry returned by {@link PageProvider.getRecentChanges}.
+ *
+ * Fields beyond `title`/`uuid`/`lastModified` are best-effort: providers populate what
+ * they have. Consumers should treat optional fields as advisory.
+ */
+/** Where a save put a page (#1462). */
+export interface SavedPage {
+    /** The page's name now: its title, or `private/{owner}/{store}/{title}` (#1456). */
+    name: string;
+    uuid: string;
+}
+export interface RecentChangeEntry {
+    title: string;
+    uuid: string;
+    lastModified: string;
+    author?: string;
+    editor?: string;
+    currentVersion?: number;
+    hasVersions?: boolean;
+    isPrivate?: boolean;
+    creator?: string;
+    /**
+     * The page's name, where it is not its title: a private page's
+     * `private/{owner}/{store}/{title}` (#1456). Link with it.
+     */
+    name?: string;
+}
+/**
+ * Page provider interface
+ *
+ * Defines the contract for page storage backends (filesystem, database, etc.).
+ */
+export interface PageProvider extends BaseProvider {
+    /**
+     * Get complete page with content and metadata
+     * @param identifier - Page UUID, title, or slug
+     * @returns Page object or null if not found
+     */
+    getPage(identifier: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Get only page content (without metadata)
+     * @param identifier - Page UUID, title, or slug
+     * @returns Markdown content
+     */
+    getPageContent(identifier: string, ctx: ActorContext): Promise<string>;
+    /**
+     * Get only page metadata (without content)
+     * @param identifier - Page UUID, title, or slug
+     * @returns Metadata object or null if not found
+     */
+    getPageMetadata(identifier: string, ctx: ActorContext): Promise<PageFrontmatter | null>;
+    /**
+     * Save page content and metadata
+     * @param pageName - Page title
+     * @param content - Markdown content
+     * @param metadata - Frontmatter metadata
+     * @param options - Save options
+     * @returns Where the page landed (#1462): the provider decides placement,
+     *   so it is the one that can say — a private page's name is its path.
+     */
+    savePage(pageName: string, content: string, metadata: Partial<PageFrontmatter> | undefined, ctx: ActorContext, options?: PageSaveOptions): Promise<SavedPage>;
+    /**
+     * Delete a page
+     * @param identifier - Page UUID or title
+     * @param ctx - Who is deleting (#1179): names the deleter on the tombstone
+     *              (#947) and reaches a private store's keys (#1382). Was
+     *                    providers written before soft delete stay compatible.
+     * @returns True if deleted, false if not found
+     */
+    deletePage(identifier: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * At unlock (#1456): move the owner's sealed pages from the user-level
+     * catalog into each encrypted store's own page index. Optional capability —
+     * only a provider that keeps private stores has one.
+     */
+    adoptUserPageCatalog?(ctx: ActorContext): Promise<number>;
+    /**
+     * Every private page in the stores `ctx` can read (#1457), for a migration
+     * that must visit them. `owner` narrows it to one user's stores; without it
+     * every user with a private container is walked.
+     *
+     * What comes back is what the context may already read: a sealed store
+     * whose key this context does not hold contributes nothing, so a system
+     * context sees the unencrypted stores and an owner's own context sees
+     * theirs. Optional capability, like the catalog adoption above.
+     */
+    listPrivateStorePages?(ctx: ActorContext, owner?: string): Promise<PrivateStorePageRef[]>;
+    /**
+     * One owner's private stores as `ctx` can read them (#1457), by store id.
+     *
+     * A store whose index this context cannot open — sealed, and no key — is
+     * ABSENT from the map. A store it can open but which holds no page is
+     * present and empty. That difference is the whole point of this shape:
+     * "cannot say" is not "not there", and a caller that renders an answer must
+     * not turn the first into the second.
+     */
+    readablePrivateStores?(owner: string, ctx: ActorContext): Promise<Map<string, PrivateStorePageRef[]>>;
+    /**
+     * A store's own saved search index (#1458). Optional capability, like the
+     * store page index above: only a provider that keeps private stores has one.
+     *
+     * The provider owns the store's bytes — it seals them when the store is
+     * sealed and refuses a locked one — and decides nothing about who may ask.
+     * The page door does that, with the requester's context, before calling.
+     */
+    updateStoreSearchDocument?(ctx: ActorContext, owner: string, store: string, document: StoreSearchDocument): Promise<void>;
+    removeStoreSearchDocument?(ctx: ActorContext, owner: string, store: string, uuid: string): Promise<boolean>;
+    readStoreSearchDocuments?(ctx: ActorContext, owner: string, store: string): Promise<Record<string, StoreSearchDocument>>;
+    writeStoreSearchDocuments?(ctx: ActorContext, owner: string, store: string, documents: Record<string, StoreSearchDocument>): Promise<void>;
+    /** False means the store has no search index yet and one must be built from its pages. */
+    hasStoreSearchIndex?(owner: string, store: string): Promise<boolean>;
+    /**
+     * A store's own trash (#1459). Optional capability, like the store page and
+     * search indexes above, and reached the same way: the provider owns the
+     * store's bytes and refuses a sealed store it has no key for; the page door
+     * decides who may ask, with the requester's context, before calling.
+     */
+    listStoreDeletedPages?(ctx: ActorContext, owner: string): Promise<StoreDeletedEntry[]>;
+    restoreStorePage?(ctx: ActorContext, owner: string, store: string, uuid: string): Promise<StoreRestoreResult>;
+    purgeStorePage?(ctx: ActorContext, owner: string, store: string, uuid: string): Promise<boolean>;
+    /**
+     * Expire the tombstones past the retention window in every store `ctx` can
+     * open. A background job holds no key, so it reaches the unencrypted stores
+     * only; a sealed store's trash expires in its owner's own session (#1459).
+     *
+     * Returns WHAT it purged, not how many: the provider owns the bytes and the
+     * caller owns the audit record, so the caller needs the entries.
+     */
+    purgeExpiredStoreTrash?(ctx: ActorContext, owner?: string): Promise<StoreDeletedEntry[]>;
+    /**
+     * Read a page's file exactly as stored — frontmatter and body, unparsed and
+     * unsanitised. Optional capability: only providers backed by a filesystem can
+     * offer it, so callers must feature-detect rather than assume.
+     *
+     * Declared here rather than asserted at the call site. It was previously
+     * widened inline with `as PageProvider & { getRawFile?: ... }`, which
+     * typescript-eslint 8.65 flags as an unnecessary assertion and its autofixer
+     * removes — breaking the build, because the assertion was in fact
+     * load-bearing. Putting the optional member on the interface where it belongs
+     * satisfies both the compiler and the rule, instead of picking a side.
+     *
+     * @param identifier - UUID, slug, or title
+     * @returns The file path and raw contents, or null when unsupported/unknown
+     */
+    getRawFile?(identifier: string): Promise<{
+        filePath: string;
+        content: string;
+    } | null>;
+    /**
+     * Evict a single page from the provider's in-memory content/metadata cache.
+     * @param identifier - UUID, slug, or title
+     * @returns resolved page title if an entry was evicted, null otherwise
+     */
+    invalidatePageCache(identifier: string): string | null;
+    /**
+     * Look up a page's UUID by any identifier (UUID, slug, or title).
+     * @param identifier - UUID, slug, or title
+     * @param ctx - who is asking (#1418): the owner's unlocked sealed-store pages resolve only through it
+     * @returns UUID string or null if not found
+     */
+    getPageUUID(identifier: string, ctx: ActorContext): string | null;
+    /**
+     * Check if page exists
+     * @param identifier - Page UUID or title
+     * @returns True if page exists
+     */
+    pageExists(identifier: string, ctx: ActorContext): boolean;
+    /**
+     * Whether a page uuid is in the trash (#1403). Optional: a provider without
+     * soft delete has no trash, and callers treat its absence as false.
+     *
+     * @param uuid - Page UUID
+     * @returns True if the uuid has a trash entry
+     */
+    isPageDeleted?(uuid: string): boolean;
+    /**
+     * Bring a trashed page back with its history (#947). Optional: a provider
+     * without soft delete has nothing to restore.
+     *
+     * @param uuid - Page UUID
+     */
+    restoreDeletedPage?(uuid: string): Promise<{
+        ok: true;
+        title: string;
+    } | {
+        ok: false;
+        reason: string;
+        detail?: string;
+    }>;
+    /**
+     * Get all page titles
+     * @returns Sorted array of page titles
+     */
+    getAllPages(): Promise<string[]>;
+    /**
+     * Get all page titles (explicit alias for getAllPages)
+     * Prefer this for new code that only needs page names.
+     * @returns Sorted array of page titles
+     */
+    getAllPageNames(): Promise<string[]>;
+    /**
+     * Get all page info objects
+     * @param options - List options
+     * @returns Array of page info objects
+     */
+    getAllPageInfo(options?: PageListOptions): Promise<PageInfo[]>;
+    /**
+     * Find page by various identifiers
+     * @param identifier - UUID, title, or slug
+     * @returns Canonical page title or null
+     */
+    findPage(identifier: string): string | null;
+    /**
+     * Get a page by its UUID
+     * @param uuid - Page UUID
+     * @returns Page or null if not found
+     */
+    getPageByUUID(uuid: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Get a page by its slug
+     * @param slug - URL-friendly slug
+     * @returns Page or null if not found
+     */
+    getPageBySlug(slug: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Refresh page cache
+     * @returns Promise that resolves when refresh is complete
+     */
+    refreshPageList(): Promise<void>;
+    /**
+     * Return pages most recently modified, sorted descending by lastModified.
+     *
+     * Visibility (#635): private pages are filtered out unless one of the caller's
+     * principals is the page creator OR appears in the page's frontmatter audience.
+     * An `admin` principal bypasses the filter — derived here, never passed as a
+     * flag (#1116).
+     *
+     * Source-of-truth: providers MUST read from in-memory state (e.g., pageIndex /
+     * pageCache) — direct disk reads were what motivated this API.
+     */
+    getRecentChanges(ctx: ActorContext, options?: RecentChangesOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * Return pages owned by the given user (#640).
+     *
+     * "Owned" matches by `author` or `creator` field — pageIndex keeps these in
+     * lockstep on save. The visibility filter is intentionally NOT applied here
+     * because by definition a user can see their own pages: the route handler
+     * verifies that `username === currentUser.username` before calling this.
+     *
+     * Source-of-truth: providers MUST read from in-memory state (pageIndex /
+     * pageCache). Reuses {@link RecentChangeEntry} shape since the relevant fields
+     * overlap.
+     */
+    getPagesByCreator(username: string, ctx: ActorContext, options?: GetPagesByCreatorOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * Return pages most recently edited by the given user (#640 Phase 2).
+     * Match by `editor` — separate from `author`/`creator` because edits change
+     * editor but not author. Visibility filter NOT applied (caller asks about
+     * own activity).
+     */
+    getPagesByEditor(username: string, ctx: ActorContext, options?: PagesScanOptions): Promise<RecentChangeEntry[]>;
+    /**
+     * Return pages whose frontmatter audience contains any of the given
+     * principals — i.e., pages explicitly shared with the user (#640 Phase 2).
+     * Excludes pages the user already owns (those show up under `getPagesByCreator`).
+     */
+    getPagesSharedWith(principals: string[], options?: PagesScanOptions): Promise<RecentChangeEntry[]>;
+}
+/**
+ * Versioning page provider interface
+ *
+ * Extended page provider with version history capabilities.
+ */
+export interface VersioningPageProvider extends PageProvider {
+    /**
+     * Get version history for a page
+     * @param identifier - Page UUID or title
+     * @param limit - Maximum number of versions to return
+     * @returns Array of version history entries
+     */
+    getVersionHistory(identifier: string, ctx: ActorContext, limit?: number): Promise<VersionHistoryEntry[]>;
+    /**
+     * Get specific version content
+     * @param identifier - Page UUID or title
+     * @param version - Version number
+     * @returns Version content object
+     */
+    getVersion(identifier: string, version: number): Promise<VersionContent | null>;
+    /**
+     * Get version manifest
+     * @param identifier - Page UUID or title
+     * @returns Version manifest object
+     */
+    getVersionManifest(identifier: string): Promise<VersionManifest | null>;
+    /**
+     * Compare two versions
+     * @param identifier - Page UUID or title
+     * @param fromVersion - Old version number
+     * @param toVersion - New version number
+     * @returns Version diff object
+     */
+    compareVersions(identifier: string, fromVersion: number, toVersion: number, ctx: ActorContext): Promise<VersionDiff | null>;
+    /**
+     * Delete old versions based on retention policy
+     * @param identifier - Page UUID or title
+     * @returns Number of versions deleted
+     */
+    cleanupVersions(identifier: string): Promise<number>;
+    /**
+     * Compress old versions
+     * @param identifier - Page UUID or title
+     * @param olderThanDays - Compress versions older than N days
+     * @returns Number of versions compressed
+     */
+    compressVersions(identifier: string, olderThanDays?: number): Promise<number>;
+}
+/**
+ * User provider interface
+ *
+ * Defines the contract for user storage backends.
+ */
+export interface UserProvider extends BaseProvider {
+    /**
+     * Get user by username
+     * @param username - Username
+     * @returns User object or null if not found
+     */
+    getUser(username: string): Promise<User | null>;
+    /**
+     * Get user by email
+     * @param email - Email address
+     * @returns User object or null if not found
+     */
+    getUserByEmail(email: string): Promise<User | null>;
+    /**
+     * Get all users
+     * @returns Map of username to user objects
+     */
+    getAllUsers(): Promise<Map<string, User>>;
+    /**
+     * Create new user
+     * @param userData - User object with all fields populated
+     * @returns Created user object
+     */
+    createUser(userData: User): Promise<User>;
+    /**
+     * Update user
+     * @param username - Username
+     * @param updates - Partial user data to update
+     * @returns Updated user object
+     */
+    updateUser(username: string, updates: UserUpdateData): Promise<User>;
+    /**
+     * Delete user
+     * @param username - Username
+     * @returns True if deleted, false if not found
+     */
+    deleteUser(username: string): Promise<boolean>;
+    /**
+     * Validate user credentials
+     * @param username - Username
+     * @param password - Plain text password
+     * @returns User object if valid, null if invalid
+     */
+    validateCredentials(username: string, password: string): Promise<User | null>;
+    /**
+     * Create session
+     * @param sessionId - Session ID
+     * @param sessionData - Session data object
+     * @returns Promise that resolves when session is created
+     */
+    createSession(sessionId: string, sessionData: UserSession): Promise<void>;
+    /**
+     * Get session
+     * @param sessionId - Session ID
+     * @returns Session object or null if not found/expired
+     */
+    getSession(sessionId: string): Promise<UserSession | null>;
+    /**
+     * Delete session
+     * @param sessionId - Session ID
+     * @returns True if deleted, false if not found
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Clean up expired sessions
+     * @returns Number of sessions deleted
+     */
+    cleanupExpiredSessions(): Promise<number>;
+    /**
+     * Check if user exists
+     * @param username - Username to check
+     * @returns True if user exists
+     */
+    userExists(username: string): Promise<boolean>;
+    /**
+     * Get all usernames
+     * @returns Array of usernames
+     */
+    getAllUsernames(): Promise<string[]>;
+    /**
+     * Get all active sessions
+     * @returns Map of session ID to session data
+     */
+    getAllSessions(): Promise<Map<string, UserSession>>;
+}
+/**
+ * Attachment metadata
+ */
+export interface AttachmentMetadata {
+    /** Attachment ID (UUID) */
+    id: string;
+    /** Filename */
+    filename: string;
+    /** Page UUID this attachment belongs to */
+    pageUuid: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Upload timestamp (ISO 8601) */
+    uploadedAt: string;
+    /** Uploader user ID */
+    uploadedBy: string;
+    /** File path */
+    filePath: string;
+    /** Description */
+    description?: string;
+    /** Additional metadata */
+    [key: string]: unknown;
+}
+/**
+ * A file in a private store (#1400, #1460, docs/private-stores.md
+ * "Stores are self-contained"). Listed in the store's OWN index, beside
+ * `store.json` — never in the global `attachment-metadata.json` — and sealed
+ * with the store DEK when the store is encrypted. #1460: every private store
+ * keeps its files this way, encrypted or not.
+ */
+export interface StoreFileEntry {
+    /**
+     * The file's id, and the base of its name on disk. A random UUID for a new
+     * upload; a record #1460's migration moved out of the shared index keeps the
+     * id it already had, because that id is its `/attachments/{id}` URL on every
+     * page that references it.
+     */
+    id: string;
+    /**
+     * Name on disk inside `{store}/attachments/`: `{id}{ext}` for a new upload,
+     * and for a migrated file the name it already had — #1460 moves bytes, it
+     * does not rename them. Says nothing about the file either way.
+     */
+    fileName: string;
+    /** The name it was uploaded with. Only inside the store's index. */
+    name: string;
+    encodingFormat: string;
+    contentSize: number;
+    /** SHA-256 of the plaintext: duplicate detection within this store only. */
+    fingerprint: string;
+    description: string;
+    author?: string;
+    dateCreated: string;
+    dateModified: string;
+    /** Pages the file was uploaded onto. */
+    mentions: string[];
+}
+/**
+ * A page in a private store (#1456): its entry in the store's OWN page index,
+ * beside `store.json` — never in the global `page-index.json`. The same shape
+ * the user-level sealed catalogue used (#1385), which the store index replaces.
+ */
+export type StorePageEntry = UserCatalogPage;
+/**
+ * A deleted page in a private store (#1459): its entry in the store's OWN
+ * trash record, `{store}/deleted-index.json`, beside the page index and
+ * written through the same store I/O — so it is sealed exactly when the store
+ * is, and a deleted private page is recorded nowhere else. Never in the global
+ * `page-index.json` and never in `pages/deleted/`.
+ *
+ * It is the live index entry it was, plus who removed it and when: restore
+ * puts that entry straight back, so nothing about the page has to be guessed
+ * or re-derived from the file.
+ */
+export interface StoreDeletedEntry extends StorePageEntry {
+    /** When the page was deleted (ISO 8601) */
+    deletedAt: string;
+    /** Username that deleted it */
+    deletedBy: string;
+}
+/** Why a restore from a store's trash was refused (#1459). */
+export type StoreRestoreFailure = 'not-found' | 'title-conflict' | 'file-missing' | 'error';
+export type StoreRestoreResult = {
+    ok: true;
+    title: string;
+    name: string;
+} | {
+    ok: false;
+    reason: StoreRestoreFailure;
+    detail?: string;
+};
+/**
+ * A private store as the attachment provider is handed it: whose it is, which
+ * store, and the I/O the caller's key allows (plain, or sealed with the store
+ * DEK). The provider stores and reads; it never decides who may, and never
+ * chooses whether to encrypt — the I/O already carries that.
+ */
+export interface StoreFileLocation {
+    owner: string;
+    store: string;
+    io: StoreFileIO;
+}
+/**
+ * Attachment provider interface
+ *
+ * Defines the contract for attachment storage backends.
+ */
+export interface AttachmentProvider extends BaseProvider {
+    /**
+     * Get attachment
+     * @param attachmentId - Attachment ID
+     * @returns File buffer and metadata
+     */
+    getAttachment(attachmentId: string): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
+    /**
+     * Get attachment metadata
+     * @param attachmentId - Attachment ID
+     * @returns Attachment metadata or null
+     */
+    getAttachmentMetadata(attachmentId: string): Promise<AttachmentMetadata | null>;
+    /**
+     * List attachments for a page
+     * @param pageUuid - Page UUID
+     * @returns Array of attachment metadata
+     */
+    listAttachments(pageUuid: string): Promise<AttachmentMetadata[]>;
+    /**
+     * Delete attachment
+     * @param attachmentId - Attachment ID
+     * @returns True if deleted, false if not found
+     */
+    deleteAttachment(attachmentId: string): Promise<boolean>;
+    /**
+     * Delete all attachments for a page
+     * @param pageUuid - Page UUID
+     * @returns Number of attachments deleted
+     */
+    deletePageAttachments(pageUuid: string): Promise<number>;
+}
+/**
+ * Search provider interface
+ *
+ * Defines the contract for search backends (Lunr, Elasticsearch, etc.).
+ */
+export interface SearchProvider extends BaseProvider {
+    /**
+     * Index a page
+     * @param page - Page to index
+     * @returns Promise that resolves when indexing is complete
+     */
+    indexPage(page: WikiPage): Promise<void>;
+    /**
+     * Remove page from index
+     * @param identifier - Page UUID or title
+     * @returns Promise that resolves when removal is complete
+     */
+    removePage(identifier: string): Promise<void>;
+    /**
+     * Search pages
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Array of search results
+     */
+    search(query: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PageSearchResult[]>;
+    /**
+     * Get search suggestions
+     * @param query - Partial search query
+     * @param limit - Maximum suggestions to return
+     * @returns Array of suggestions
+     */
+    getSuggestions(query: string, limit?: number): Promise<string[]>;
+    /**
+     * Rebuild entire search index
+     * @returns Promise that resolves when rebuild is complete
+     */
+    rebuildIndex(): Promise<void>;
+}
+/**
+ * Cache provider interface
+ *
+ * Defines the contract for caching backends (in-memory, Redis, etc.).
+ */
+export interface CacheProvider extends BaseProvider {
+    /**
+     * Get value from cache
+     * @param key - Cache key
+     * @returns Cached value or null if not found/expired
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set value in cache
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Time to live in seconds (optional)
+     * @returns Promise that resolves when value is cached
+     */
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete value from cache
+     * @param key - Cache key
+     * @returns True if deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cached values
+     * @returns Promise that resolves when cache is cleared
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if key exists in cache
+     * @param key - Cache key
+     * @returns True if key exists and not expired
+     */
+    has(key: string): Promise<boolean>;
+}
+/**
+ * Audit event
+ */
+export interface AuditEvent {
+    /** Event ID (UUID) */
+    id: string;
+    /** Event type */
+    type: string;
+    /** Actor (user ID or 'system') */
+    actor: string;
+    /** Target resource */
+    target: string;
+    /** Action performed */
+    action: string;
+    /** Event timestamp (ISO 8601) */
+    timestamp: string;
+    /** IP address */
+    ipAddress?: string;
+    /** User agent */
+    userAgent?: string;
+    /** Additional event data */
+    data?: Record<string, unknown>;
+    /** Event result (success, failure) */
+    result: 'success' | 'failure';
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Audit provider interface
+ *
+ * Defines the contract for audit logging backends.
+ */
+export interface AuditProvider extends BaseProvider {
+    /**
+     * Log audit event
+     * @param event - Audit event
+     * @returns Promise that resolves when event is logged
+     */
+    logEvent(event: Omit<AuditEvent, 'id' | 'timestamp'>): Promise<void>;
+    /**
+     * Query audit events
+     * @param filters - Filter criteria
+     * @returns Array of audit events
+     */
+    queryEvents(filters: {
+        type?: string;
+        actor?: string;
+        target?: string;
+        action?: string;
+        startDate?: string;
+        endDate?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<AuditEvent[]>;
+    /**
+     * Delete old audit events
+     * @param olderThanDays - Delete events older than N days
+     * @returns Number of events deleted
+     */
+    cleanupOldEvents(olderThanDays: number): Promise<number>;
+}