@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/handlers/WikiTagHandler.d.ts

@@ -0,0 +1,125 @@
+import BaseSyntaxHandler, { InitializationContext } from './BaseSyntaxHandler.js';
+import ParseContext from '../context/ParseContext.js';
+/**
+ * Wiki engine interface
+ */
+interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * WikiTagHandler - JSP-like tag processing for conditional content and page inclusion
+ *
+ * Supports JSPWiki WikiTags:
+ * - <wiki:If test="condition">content</wiki:If> - Conditional display
+ * - <wiki:Include page="PageName" /> - Page inclusion
+ * - <wiki:UserCheck status="authenticated">content</wiki:UserCheck> - User validation
+ *
+ * Related Issue: #59 - WikiTag Handler (If, Include, UserCheck)
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+declare class WikiTagHandler extends BaseSyntaxHandler {
+    handlerId: string;
+    private engine;
+    private config;
+    private supportedTags;
+    constructor(engine?: WikiEngine | null);
+    /**
+     * Initialize handler with configuration
+     * @param context - Initialization context
+     */
+    protected onInitialize(context: InitializationContext): Promise<void>;
+    /**
+     * Process content by finding and executing all WikiTag instances
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Content with WikiTags processed
+     */
+    process(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Handle a specific WikiTag match
+     * @param matchInfo - WikiTag match information
+     * @param context - Parse context
+     * @returns Tag output HTML
+     */
+    private handleTag;
+    /**
+     * Handle wiki:If tag - conditional content display
+     * @param attributes - Tag attributes
+     * @param content - Tag content
+     * @param context - Parse context
+     * @returns Conditional content or empty string
+     */
+    private handleIfTag;
+    /**
+     * Handle wiki:Include tag - page inclusion
+     * @param attributes - Tag attributes
+     * @param context - Parse context
+     * @returns Included page content
+     */
+    private handleIncludeTag;
+    /**
+     * Handle wiki:UserCheck tag - user authentication and authorization checks
+     * @param attributes - Tag attributes
+     * @param content - Tag content
+     * @param context - Parse context
+     * @returns Content if user check passes, empty otherwise
+     */
+    private handleUserCheckTag;
+    /**
+     * Evaluate conditional expression for wiki:If tags
+     * @param condition - Condition expression to evaluate
+     * @param context - Parse context
+     * @returns True if condition passes
+     */
+    private evaluateCondition;
+    /**
+     * Evaluate complex boolean conditions with && and || operators
+     * @param condition - Complex condition expression
+     * @param context - Parse context
+     * @returns Evaluation result
+     */
+    private evaluateComplexCondition;
+    /**
+     * Resolve context variable for conditions
+     * @param varName - Variable name
+     * @param context - Parse context
+     * @returns Variable value
+     */
+    private resolveContextVariable;
+    /**
+     * Check for recursive inclusion to prevent infinite loops
+     * @param pageName - Page being included
+     * @param context - Parse context
+     * @returns True if recursive inclusion detected
+     */
+    private isRecursiveInclusion;
+    /**
+     * Extract specific section from page content
+     * @param content - Full page content
+     * @param sectionName - Section name to extract
+     * @returns Section content or full content if section not found
+     */
+    private extractSection;
+    /**
+     * Parse tag attributes from attribute string
+     * @param attributeString - Attribute string to parse
+     * @returns Parsed attributes
+     */
+    private parseTagAttributes;
+    /**
+     * Get supported WikiTag patterns
+     * @returns Array of supported patterns
+     */
+    getSupportedPatterns(): string[];
+    /**
+     * Get supported conditions for wiki:If tags
+     * @returns Array of supported conditions
+     */
+    getSupportedConditions(): string[];
+    /**
+     * Get handler information for debugging and documentation
+     * @returns Handler information
+     */
+    getInfo(): Record<string, unknown>;
+}
+export default WikiTagHandler;

package/lib/src/parsers/jspwikiTableRow.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One JSPWiki table row, read the way JSPWiki reads it (#1338).
+ *
+ * The one implementation for both table paths: a table inside a `%%` style
+ * block (`MarkupParser.createTableNode`) and a bare one
+ * (`JSPWikiPreprocessor`). They had a copy each, and the bare one dropped the
+ * last cell of every row without a trailing delimiter — 4,442 rows on 475
+ * jimstest pages — because it always cut the last split piece.
+ *
+ * - A row starting with `||` is a header row, split on `||`; otherwise on `|`.
+ * - The piece before the leading delimiter is empty and is dropped.
+ * - The trailing delimiter is optional. The piece after the last delimiter is
+ *   dropped only when it is empty, as JSPWiki does; otherwise it is a cell.
+ * - A delimiter inside `[...]` belongs to a wiki link (`[Text|Page]`), not
+ *   to the table.
+ */
+export interface JspwikiTableRow {
+    isHeader: boolean;
+    cells: string[];
+}
+export declare function parseJspwikiTableRow(line: string): JspwikiTableRow;
+/**
+ * Split text on a delimiter, except inside `[...]` bracket groups: the pipe
+ * in `[wiki link|PageName]` is not a cell boundary.
+ */
+export declare function splitCellsBracketAware(text: string, delimiter: string): string[];
+/**
+ * A GFM table's separator row: `|---|:---:|` (#1352). Cells of dashes, each
+ * optionally colon-edged for alignment; leading and trailing pipes optional.
+ */
+export declare function isGfmSeparatorRow(line: string): boolean;
+/**
+ * The rows of a table block, with a GFM table read as one (#1352): the row
+ * above a separator row is the header, and the separator itself is not a
+ * row. Without this a pasted GFM table rendered its `|---|` line as a row of
+ * dashes and had no header. A JSPWiki table has no separator row and comes
+ * through unchanged.
+ */
+export declare function parseTableRows(lines: readonly string[]): JspwikiTableRow[];

package/lib/src/parsers/styleBlockSyntax.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The opener of a block-form `%%` style block, on its own line (#1345).
+ *
+ * One or more class names, separated by spaces or dots — `%%information`,
+ * `%%btn btn-sm`, `%%size-20.bg-silver`. A dot is a class separator, as in
+ * the inline form (`%%btn.btn-info … /%`) and in Apache JSPWiki
+ * (`JSPWikiMarkupParser.handleDiv`). Shared by the markup parser's
+ * extraction and the JSPWiki preprocessor, which each had their own copy and
+ * had drifted: neither accepted a dot, and the preprocessor accepted only one
+ * class.
+ */
+export declare const STYLE_BLOCK_OPENER: RegExp;
+/** The class attribute for an opener's captured names: dots and runs of spaces become one space. */
+export declare function styleBlockClasses(captured: string): string;

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

@@ -0,0 +1,79 @@
+/**
+ * Plugin types for ngdpbase plugins
+ *
+ * These types provide proper TypeScript definitions for plugins
+ * that use the object-with-execute pattern.
+ */
+import type { PluginFormatters } from '../managers/PluginManager.js';
+export type { PluginFormatters };
+/**
+ * Wiki engine interface for plugins
+ */
+export interface WikiEngine {
+    getManager(name: string): unknown;
+    startTime?: number;
+    logger?: {
+        error: (...args: unknown[]) => void;
+    };
+    getConfig?(): {
+        get?: (key: string, defaultValue: unknown) => unknown;
+    };
+}
+/**
+ * Plugin context passed to plugins during execution
+ */
+export interface PluginContext {
+    engine?: WikiEngine;
+    pageName: string;
+    linkGraph: Record<string, unknown>;
+    /** Query-string parameters from the current HTTP request (e.g. { page: '2' }) */
+    query?: Record<string, string>;
+    /** #1820: PluginManager's formatter helpers, e.g. `context.formatters.escapeHtml(s)`. */
+    formatters: PluginFormatters;
+    /**
+     * #1751: this render reads `topic`'s data (by convention the owning
+     * manager's name, e.g. 'LedgerManager'). Call before reading; the cached
+     * page is re-rendered once the manager bumps that topic.
+     */
+    dependsOn?: (topic: string) => void;
+    /** #1751: this render's output changes on its own; do not cache the page. */
+    markVolatile?: () => void;
+    [key: string]: unknown;
+}
+/**
+ * Plugin parameters (parsed from plugin syntax)
+ */
+export interface PluginParams {
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Simple plugin interface for plugins that use the execute method pattern
+ * (does not require the callable function signature)
+ */
+export interface SimplePlugin {
+    name?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    initialize?: (engine: unknown) => Promise<void> | void;
+    fetch?: (engine: unknown) => Promise<void> | void;
+    execute?: (context: PluginContext, params: PluginParams) => Promise<string> | string;
+    /**
+     * Its output changes with nothing written (a clock): a page that runs it is
+     * not kept in the page cache (#1751). Data a plugin reads from a manager is
+     * declared with `context.dependsOn(topic)` instead, which keeps the page
+     * cached until that data changes.
+     */
+    volatile?: boolean;
+}
+/**
+ * Callable plugin type for plugins that can be called directly
+ * (like referringPagesPlugin)
+ */
+export type CallablePlugin = ((pageName: string, params: PluginParams, linkGraph: Record<string, string[]>) => string | Promise<string>) & {
+    name: string;
+    description: string;
+    author: string;
+    version: string;
+    initialize?: (engine: unknown) => void;
+};

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

@@ -0,0 +1,40 @@
+/**
+ * AgentTokenAuthProvider — verify a user-delegated agent API token presented
+ * on the `Authorization: Bearer <token>` header (#946).
+ *
+ * Counterpart to AuthentikBearerAuthProvider, but with no external IdP: the
+ * credential is minted in-app by the user it belongs to. Both providers can be
+ * enabled at once — the bearer middleware tries each registered bearer-capable
+ * provider in turn.
+ *
+ * The provider only answers "which user, and with which scopes". Permissions
+ * are resolved live from that user's record by the middleware, so a token
+ * never carries a snapshot of its owner's authority.
+ *
+ * Wire-up: request-time middleware in `src/app.ts` (header → verify →
+ * set req.userContext). Stateless — no session is created for API calls. It
+ * does NOT participate in the /login flow.
+ */
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { AuthProvider, AuthVerifyCredentials, AuthResult, ViaToken } from './BaseAuthProvider.js';
+/**
+ * Extra detail this provider returns alongside the username.
+ *
+ * `viaToken` is optional on `AuthResult` (#1048) because most providers have
+ * none; here it is REQUIRED. A successful agent-token verify without token
+ * detail would be a credential with no scope ceiling attached, so narrowing it
+ * is the point of this type rather than a formality.
+ */
+export interface AgentTokenAuthResult extends AuthResult {
+    viaToken: ViaToken;
+}
+export declare class AgentTokenAuthProvider implements AuthProvider {
+    readonly id = "agent-token";
+    readonly displayName = "Agent API Token";
+    /** Marks this provider as usable by the bearer middleware. */
+    readonly acceptsBearer = true;
+    private engine;
+    constructor(engine: WikiEngine);
+    verify(credentials: AuthVerifyCredentials): Promise<AgentTokenAuthResult | null>;
+}
+export default AgentTokenAuthProvider;

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

@@ -0,0 +1,75 @@
+/**
+ * AuthentikBearerAuthProvider — verify an Authentik-issued OAuth/OIDC bearer
+ * JWT presented on the `Authorization: Bearer <token>` header (#818).
+ *
+ * Unlike the interactive Google-OIDC code-exchange flow, this provider trusts
+ * a token an automated client (e.g. an AI agent) already holds — minted in
+ * Authentik via the `client_credentials` grant against a per-person service
+ * account. It verifies the JWT signature against Authentik's JWKS, checks
+ * issuer + audience, then coordinates the identity to a local User record.
+ *
+ * Design mirrors CloudflareAccessAuthProvider (#649):
+ *  - User coordination by **email** (`email` claim).
+ *  - Unknown user → **JIT-provision** with default-role (overridable per
+ *    Authentik group via `group-map`).
+ *  - `groups[]` claim → ngdpbase roles via config-map.
+ *
+ * Author attribution (epic decision A): the service account's email is set to
+ * match the human's ngdpbase account, so `findUserByEmail` resolves to that
+ * user and pages are authored under their existing username (the UI renders
+ * their displayName, e.g. "Jim Willeke").
+ *
+ * Wire-up: invoked by the request-time middleware in `src/app.ts` (header →
+ * verify → resolve-or-provision → set req.userContext, stateless — no session
+ * is created for API calls). It does NOT participate in the /login flow.
+ *
+ * Token verification uses `jose.createRemoteJWKSet` against the configured
+ * JWKS URL — keys are fetched on demand and cached + rotated by jose.
+ */
+import { type JWTVerifyGetKey } from 'jose';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { AuthProvider, AuthVerifyCredentials, AuthResult } from './BaseAuthProvider.js';
+export interface AuthentikBearerConfig {
+    /** OIDC issuer, e.g. `https://auth.example.com/application/o/ngdpbase/`. */
+    issuer: string;
+    /** JWKS URI, e.g. `<issuer>jwks/`. */
+    jwksUrl: string;
+    /** Expected audience (the Authentik provider's client-id). */
+    audience: string;
+    /** Role assigned to JIT-provisioned users when no group maps. */
+    defaultRole: string;
+    /**
+     * Map of Authentik group name → ngdpbase role name. Groups absent from this
+     * map are silently ignored (user still gets defaultRole).
+     */
+    groupMap: Record<string, string>;
+}
+export declare class AuthentikBearerAuthProvider implements AuthProvider {
+    readonly id = "authentik-bearer";
+    readonly displayName = "Authentik (Bearer)";
+    /** Marks this provider as usable by the bearer middleware. */
+    readonly acceptsBearer = true;
+    private readonly engine;
+    private readonly config;
+    private readonly jwks;
+    /**
+     * @param jwksOverride optional pre-built JWKS getter for tests; production
+     *   omits this and uses `createRemoteJWKSet` against the configured JWKS URL.
+     */
+    constructor(engine: WikiEngine, config: AuthentikBearerConfig, jwksOverride?: JWTVerifyGetKey);
+    /**
+     * Verify the bearer JWT and resolve (or provision) the local user.
+     * `credentials.token` is the raw JWT lifted from the `Authorization: Bearer`
+     * header by the request-time middleware.
+     */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    private resolveOrProvision;
+    /**
+     * Map Authentik 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;
+}

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

@@ -0,0 +1,197 @@
+import { AttachmentMetadata, AttachmentProvider } from '../types/index.js';
+import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { ProviderInfo } from './BasePageProvider.js';
+import BaseProvider from './BaseProvider.js';
+/**
+ * File information for attachment uploads
+ */
+interface FileInfo {
+    /** Original filename */
+    originalName: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * User information
+ */
+interface User {
+    /** User identifier */
+    id?: string;
+    /** Username */
+    username?: string;
+    /** Email address */
+    email?: string;
+    [key: string]: unknown;
+}
+/**
+ * Attachment retrieval result
+ */
+interface AttachmentResult {
+    /** File buffer */
+    buffer: Buffer;
+    /** Attachment metadata */
+    metadata: AttachmentMetadata;
+}
+/**
+ * BaseAttachmentProvider - Abstract interface for attachment storage providers
+ *
+ * All attachment storage providers must extend this class and implement its methods.
+ * Providers handle the actual storage and retrieval of wiki attachments (files, images, etc.),
+ * whether from filesystem, database, cloud storage, or other backends.
+ *
+ * Following JSPWiki's attachment provider pattern.
+ *
+ * @class BaseAttachmentProvider
+ * @abstract
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {boolean} initialized - Whether provider has been initialized
+ *
+ * @see {@link BasicAttachmentProvider} for filesystem implementation
+ * @see {@link AttachmentManager} for usage
+ */
+declare abstract class BaseAttachmentProvider extends BaseProvider implements AttachmentProvider {
+    /** Reference to the wiki engine */
+    protected engine: WikiEngine;
+    /** Whether provider has been initialized */
+    protected initialized: boolean;
+    /**
+     * Create a new attachment provider
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The WikiEngine instance
+     * @throws {Error} If engine is not provided
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the provider
+     *
+     * IMPORTANT: Providers MUST access configuration via ConfigurationManager:
+     *   const configManager = this.engine.getManager('ConfigurationManager');
+     *   const value = configManager.getProperty('key', 'default');
+     *
+     * Do NOT read configuration files directly.
+     *
+     * @returns {Promise<void>}
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Upload/store an attachment with metadata (legacy method for backward compatibility)
+     * @param {Buffer} fileBuffer - File data
+     * @param {FileInfo} fileInfo - File information (originalName, mimeType, size)
+     * @param {Partial<AttachmentMetadata>} _metadata - Attachment metadata
+     * @param {User} _user - User uploading the attachment
+     * @returns {Promise<AttachmentMetadata>} Attachment metadata with ID
+     */
+    storeAttachment(_fileBuffer: Buffer, _fileInfo: FileInfo, _metadata?: Partial<AttachmentMetadata>, _user?: User | null): Promise<AttachmentMetadata>;
+    /**
+     * Get attachment file data
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<AttachmentResult|null>} File buffer and metadata
+     */
+    abstract getAttachment(attachmentId: string): Promise<AttachmentResult | null>;
+    /**
+     * Get attachment metadata only (no file data)
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<AttachmentMetadata|null>} Attachment metadata
+     */
+    abstract getAttachmentMetadata(attachmentId: string): Promise<AttachmentMetadata | null>;
+    /**
+     * Update attachment metadata (e.g., add page reference)
+     * @param {string} attachmentId - Attachment identifier
+     * @param {Partial<AttachmentMetadata>} metadata - Updated metadata
+     * @returns {Promise<boolean>} Success status
+     */
+    abstract updateAttachmentMetadata(attachmentId: string, metadata: Partial<AttachmentMetadata>): Promise<boolean>;
+    /**
+     * Delete an attachment
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<boolean>} True if deleted, false if not found
+     */
+    abstract deleteAttachment(attachmentId: string): Promise<boolean>;
+    /**
+     * Check if attachment exists
+     * @param {string} attachmentId - Attachment identifier
+     * @returns {Promise<boolean>}
+     */
+    abstract attachmentExists(attachmentId: string): Promise<boolean>;
+    /**
+     * Get all attachments metadata (without file data)
+     * @returns {Promise<AttachmentMetadata[]>} Array of attachment metadata
+     */
+    abstract getAllAttachments(): Promise<AttachmentMetadata[]>;
+    /**
+     * Get attachments used by a specific page
+     * @param {string} pageName - Page name/title
+     * @returns {Promise<AttachmentMetadata[]>} Array of attachment metadata
+     */
+    abstract getAttachmentsForPage(pageName: string): Promise<AttachmentMetadata[]>;
+    /**
+     * List attachments for a page (AttachmentProvider interface method)
+     * @param {string} pageUuid - Page UUID
+     * @returns {Promise<AttachmentMetadata[]>} Array of attachment metadata
+     */
+    abstract listAttachments(pageUuid: string): Promise<AttachmentMetadata[]>;
+    /**
+     * Delete all attachments for a page
+     * @param {string} pageUuid - Page UUID
+     * @returns {Promise<number>} Number of attachments deleted
+     */
+    abstract deletePageAttachments(pageUuid: string): Promise<number>;
+    /**
+     * Find an attachment by its original filename across all attachments
+     * @param {string} filename - Original filename to search for
+     * @returns {Promise<AttachmentMetadata|null>} Matching attachment metadata or null
+     */
+    getAttachmentByFilename(_filename: string): Promise<AttachmentMetadata | null>;
+    /** Store a file in a store. The same bytes already in THAT store return the existing entry. */
+    storeFileInStore(_location: StoreFileLocation, _bytes: Buffer, _file: {
+        originalName: string;
+        mimeType: string;
+        description: string;
+        author?: string;
+        pageName?: string;
+    }): Promise<StoreFileEntry>;
+    /** One file of a store, with its bytes; null when the store does not list it. */
+    getFileInStore(_location: StoreFileLocation, _id: string): Promise<{
+        entry: StoreFileEntry;
+        bytes: Buffer;
+    } | null>;
+    /** A store's files that were uploaded onto `pageName`. */
+    filesInStoreForPage(_location: StoreFileLocation, _pageName: string): Promise<StoreFileEntry[]>;
+    /** Delete a file from a store: its bytes and its index entry. Null when the store does not list it. */
+    deleteFileInStore(_location: StoreFileLocation, _id: string): Promise<StoreFileEntry | null>;
+    /**
+     * Refresh internal cache/index
+     * Re-scans storage and rebuilds indexes
+     * @returns {Promise<void>}
+     */
+    abstract refreshAttachmentList(): Promise<void>;
+    /**
+     * Get provider information
+     * @returns {ProviderInfo} Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Backup provider data
+     * Returns all metadata needed to restore attachments
+     * @returns {Promise<Record<string, unknown>>} Backup data
+     */
+    abstract backup(): Promise<Record<string, unknown>>;
+    /**
+     * Restore provider data from backup
+     * @param {Record<string, unknown>} backupData - Backup data from backup()
+     * @returns {Promise<void>}
+     */
+    abstract restore(backupData: Record<string, unknown>): Promise<void>;
+    /**
+     * Shutdown the provider (cleanup resources)
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+}
+export default BaseAttachmentProvider;
+export { FileInfo, User, AttachmentResult };