@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,251 @@
+/**
+ * ShareManager — share-link capability tokens (#842 slice 1, #852).
+ *
+ * Issues, validates, revokes, and lists share links: unguessable tokens
+ * granting anonymous access to a typed scope of content. Routes (slice 2/3)
+ * consume ONLY the narrow issue/validate/revoke/list interface plus
+ * resolveScope — never the storage (decision 6 extraction seam).
+ *
+ * Scope is resolved live at request time, never snapshotted: tagging or
+ * untagging content immediately changes what a link exposes.
+ *
+ * Exclusions (safe by construction — decisions 1 and 3):
+ *   - content carrying the reserved `owner-only` keyword (media EXIF/XMP
+ *     keywords and page user-keywords alike)
+ *   - pages with `private: true`, and media linked to them
+ *   - pages with `audience` or per-action `access` frontmatter — a share
+ *     must not silently widen an author's chosen audience
+ *
+ * Persistence: one JSON file per share under `ngdpbase.share.storagedir`
+ * (CommentManager pattern). Revoked shares keep their file for audit;
+ * validate() treats unknown, expired, and revoked tokens identically so
+ * share existence never leaks.
+ *
+ * Enabled via config: ngdpbase.share.enabled
+ *
+ * @see docs/sharing.md — the source of truth for all sharing
+ * @see MagicLinkAuthProvider — token-lifecycle prior art
+ */
+import BaseManager, { type ManagerStats } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { MediaItem } from '../providers/BaseMediaProvider.js';
+import { OWNER_ONLY_KEYWORD, type ShareRecord, type ShareResource, type ShareScope, type VaultShareScope, type ShareTtl, type SharePageEntry } from '../types/Share.js';
+import { type PermissionSubject } from './UserManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type LinkPublicKey, type Lockbox } from '../utils/shareLockbox.js';
+export { OWNER_ONLY_KEYWORD };
+/** The most one extension may add to a link's lifetime (operator, 2026-09-29, #1388). */
+export declare const SHARE_EXTEND_MAX_HOURS = 24;
+/** The longest label an owner may give a vault link (#1388). */
+export declare const SHARE_LABEL_MAX = 100;
+/** Live content set a validated share exposes. */
+export interface ResolvedShareScope {
+    media: MediaItem[];
+    pages: SharePageEntry[];
+}
+export default class ShareManager extends BaseManager {
+    private sharesDir;
+    private enabled;
+    /** token → record (validate path) */
+    private byToken;
+    /** id → record (management path) */
+    private byId;
+    /** share id → aggregated anonymous access hits awaiting flush (decision 5) */
+    private accessCounts;
+    /** How long access counts accumulate before a lazy flush to log + audit. */
+    private static readonly ACCESS_FLUSH_MS;
+    constructor(engine: WikiEngine);
+    initialize(): Promise<void>;
+    isEnabled(): boolean;
+    /**
+     * Issue a new share: a delegation by `issuer` of `actions` over `resources`
+     * (#1221, epic #1225).
+     *
+     * The route asks policy for `share-create` before calling this (#1224, #1638).
+     * Here the delegation rule is enforced: __nobody delegates what they do not
+     * hold.__ Every action the share would carry is checked against the
+     * issuer's live authority through the PDP (`PolicyDecisionPoint.permits`), with the
+     * issuer's own context (P1) so a token-bound issuer is bounded by the token
+     * ceiling too. A share asking for an action the issuer lacks is refused
+     * outright rather than trimmed silently — trimming would issue a credential
+     * the issuer did not describe.
+     */
+    issue(scope: ShareScope, ttl: ShareTtl, issuer: PermissionSubject, options?: {
+        actions?: readonly string[];
+        resources?: readonly ShareResource[];
+    }): Promise<ShareRecord>;
+    /**
+     * Issue a link to a vault's content (#1388): chosen pages, or the whole vault.
+     *
+     * Only the vault's owner issues one — no role, admin included, shares
+     * someone else's vault. The lifetime is the owner's choice, up to the
+     * `shareMaxDays` of the vault's system-category; there is no link that never
+     * expires. Read-only, like every share.
+     *
+     * @param scope - The vault, and its page uuids or null for the whole vault
+     * @param lifetimeHours - How long the link lasts, in hours
+     * @param issuer - The owner, as the request's own subject
+     * @param options - `label`: the owner's note for the link, never logged or
+     *   audited. `lockedFor`: for an encrypted vault, the public half of the
+     *   link's key pair, made in the owner's browser — required there, refused
+     *   anywhere else.
+     */
+    issueVaultShare(scope: VaultShareScope, lifetimeHours: number, issuer: PermissionSubject, options?: {
+        label?: string;
+        lockedFor?: LinkPublicKey;
+    }): Promise<ShareRecord>;
+    /**
+     * Whether `owner`'s vault is encrypted: read from its `store.json`, the one
+     * file of a vault that is never sealed — or its kind is sealed (#1834), so a
+     * link into a sealed kind's vault is never issued as if it were plain.
+     */
+    isEncryptedVault(owner: string, vault: string): Promise<boolean>;
+    private vaultPlace;
+    /** The longest a new link to `vault` may last, in days (#1388). */
+    maxShareDays(vault: string): number;
+    /**
+     * Extend a live link by up to {@link SHARE_EXTEND_MAX_HOURS} hours (#1388).
+     * Only its issuer may, as often as they like, and past the lifetime maximum:
+     * that limits a link only when it is made. An expired, revoked or
+     * never-expiring link is not extended.
+     *
+     * @returns The new expiry, or null when there was nothing to extend
+     */
+    extend(id: string, hours: number, by: PermissionSubject): Promise<string | null>;
+    /** Does `who` hold `action` inside the vault a vault link names (#1539)? The container rule, then vault-owner. */
+    private permitsInScope;
+    /** The one place a share record is made: the issuer's delegation checked, audited, then stored. */
+    private create;
+    /**
+     * Validate a token. Returns the scope for a live share, or null.
+     *
+     * Unknown, expired, and revoked tokens are indistinguishable to the
+     * caller — routes render an identical 404 for all three so share
+     * existence never leaks.
+     */
+    validate(token: string): ShareScope | null;
+    /**
+     * Resolve a token into the subject the ordinary evaluator understands
+     * (#1222, epic #1225): nobody, carrying what the issuer delegated.
+     *
+     * The routes hand this subject to the same doors as any request; there is
+     * no second evaluator. `hasPermission` and `PolicyInformationPoint` read `viaShare` as
+     * a ceiling and re-check the issuer live. Null for an unknown, revoked or
+     * expired token — the same three the routes must not tell apart.
+     *
+     * The grant is a copy of the record's arrays, so nothing downstream can
+     * widen the share by mutating what it was handed.
+     */
+    subjectFor(token: string): PermissionSubject | null;
+    /** The record behind a token, or null when it must not open anything. */
+    private liveRecord;
+    /**
+     * Revoke a share by management id. Immediate; the record is retained
+     * (revokedAt set) for audit. Returns false for unknown or already-revoked.
+     */
+    revoke(id: string, revokedBy: string): Promise<boolean>;
+    /**
+     * List shares — all when `owner` is omitted (admin view), otherwise
+     * only those created by `owner`. Includes revoked and expired records;
+     * callers surface status from expiresAt/revokedAt.
+     */
+    /**
+     * #1006: active links, and how many of the total that is.
+     *
+     * Counts only. This manager holds capability tokens — a share link IS the
+     * credential — so the count is the most that may ever appear here.
+     */
+    getManagerStats(): Promise<ManagerStats>;
+    list(owner?: string): ShareRecord[];
+    /** Look up a share record by management id (management UI detail view). */
+    get(id: string): ShareRecord | null;
+    /**
+     * Record one anonymous access hit against the share behind `token`
+     * (decision 5: hits are logged as aggregated counts, not per-view rows).
+     * Counts flush to the log + audit trail lazily once the window elapses,
+     * and on shutdown. No-op for unknown tokens.
+     */
+    recordAccess(token: string): void;
+    /**
+     * Resolve a validated scope to its current content set, applying the
+     * safe-by-construction exclusions (decisions 1 and 3).
+     */
+    resolveScope(scope: ShareScope, ctx: ActorContext): Promise<ResolvedShareScope>;
+    /**
+     * The candidate pages of a vault link (#1388): the vault's current pages,
+     * or just the chosen ones, read as the share subject `ctx`. Whether each may
+     * be shown is still the page door's answer, asked by the route.
+     */
+    private resolveVaultScope;
+    /**
+     * Record one visit through a vault link (#1388): every page or file opened
+     * is its own `share-access` record, naming it by uuid or file id, never by
+     * title. Keyword links keep their batched counts.
+     */
+    recordVaultVisit(token: string, what: {
+        page?: string;
+        file?: string;
+        list?: true;
+    }, ipAddress?: string): Promise<void>;
+    private resolveKeywordScope;
+    /**
+     * True when a page must never appear in any share:
+     *   - `private: true` (decision 1)
+     *   - `owner-only` in user-keywords (decision 1)
+     *   - `audience` or per-action `access` frontmatter (decision 3 — a share
+     *     must not silently widen an author's chosen audience)
+     */
+    private isPageExcluded;
+    /** Prepare and lock everything a link to an encrypted vault covers. `ownerCtx` must hold the vault's key. */
+    prepareLockboxes(record: ShareRecord, ownerCtx: ActorContext): Promise<number>;
+    /**
+     * A page of `owner`'s vault changed (#1388): refresh it in every live link
+     * to that vault that covers it — or take it out, when it was deleted or
+     * moved away. Called by PageManager with the saving owner's context, which
+     * holds the vault key. Best-effort: one link's failure never stops a save.
+     */
+    refreshLockboxesForPage(ownerCtx: ActorContext, change: {
+        name: string | null;
+        uuid?: string;
+        previousName?: string | null;
+    }): Promise<void>;
+    /**
+     * A lockbox of a live link, for the recipient's browser to open — or null,
+     * the same for an unknown link, one that is not locked, and a missing item.
+     */
+    getLockbox(token: string, kind: 'manifest' | 'pages' | 'files', key?: string): Lockbox | null;
+    /** True when a link is locked for a key, and so is opened in the recipient's browser (#1388). */
+    isLockedLink(token: string): boolean;
+    private coversPage;
+    private lockboxPath;
+    private writeLockbox;
+    /**
+     * Render one page as the link's own subject — so nothing the link could not
+     * see reaches it through an include or a plugin — from the text the owner's
+     * context read, then lock it, and each vault file it uses, for the link.
+     */
+    private lockPage;
+    /** The link's list of pages, locked: titles are the owner's, so they are never served in the clear. */
+    private lockManifest;
+    private dropLockboxes;
+    /** Lockboxes of links that have expired or been revoked go at start-up, whatever was missed. */
+    private sweepLockboxes;
+    private persist;
+    private loadShares;
+    /**
+     * Flush aggregated access counts (one share, or all when `id` omitted) to
+     * the log and audit trail as a single `share-access` row each (decision 5).
+     */
+    private flushAccessCounts;
+    /** Audit create/revoke (decision 5). Never throws — shares work without audit. */
+    /**
+     * Record a share event through `recordAuditEvent`, which honours the on-failure rule
+     * configuration declares (#1202): a `refuse` event is flushed and a failure
+     * rejects, so the caller abandons the action; a `continue` one is
+     * fire-and-forget with the error counted. No catch here — swallowing the
+     * rejection is exactly what made the old `critical` claim a promise the code
+     * did not keep.
+     */
+    private audit;
+    shutdown(): Promise<void>;
+}

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

@@ -0,0 +1,176 @@
+import BaseManager from './BaseManager.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Configuration options for TemplateManager initialization
+ */
+interface TemplateConfig extends Record<string, unknown> {
+    templatesDirectory?: string;
+    themesDirectory?: string;
+}
+/**
+ * Template object structure
+ */
+interface Template {
+    name: string;
+    content: string;
+    path: string;
+}
+/**
+ * Theme object structure
+ */
+interface Theme {
+    name: string;
+    content: string;
+    path: string;
+}
+/**
+ * Variables for template substitution
+ */
+interface TemplateVariables {
+    uuid?: string;
+    date?: string;
+    timestamp?: string;
+    pageName?: string;
+    category?: string;
+    systemCategory?: string;
+    userKeywords?: string | string[];
+    [key: string]: string | string[] | undefined;
+}
+/**
+ * TemplateManager - Handles page templates and themes
+ *
+ * Similar to JSPWiki's TemplateManager, this manager provides template
+ * management for creating new pages from predefined templates and managing
+ * wiki themes for UI customization.
+ *
+ * Key features:
+ * - Page template management
+ * - Theme loading and switching
+ * - Default template creation
+ * - Template content retrieval
+ *
+ * @class TemplateManager
+ * @extends BaseManager
+ *
+ * @property {TemplateMap} templates - Loaded page templates
+ * @property {ThemeMap} themes - Loaded themes
+ * @property {string} templatesDirectory - Path to templates directory
+ * @property {string} themesDirectory - Path to themes directory
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const templateManager = engine.getManager('TemplateManager');
+ * const template = templateManager.getTemplate('Meeting Notes');
+ */
+declare class TemplateManager extends BaseManager {
+    private templates;
+    private themes;
+    private templatesDirectory;
+    private themesDirectory;
+    /**
+     * Creates a new TemplateManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the TemplateManager and load templates/themes
+     *
+     * @async
+     * @param {TemplateConfig} [config={}] - Configuration object
+     * @returns {Promise<void>}
+     */
+    initialize(config?: TemplateConfig): Promise<void>;
+    /**
+     * Load all page templates
+     *
+     * @returns {Promise<void>}
+     */
+    loadTemplates(): Promise<void>;
+    /**
+     * Load all themes
+     *
+     * @returns {Promise<void>}
+     */
+    loadThemes(): Promise<void>;
+    /**
+     * Create default page templates
+     *
+     * @returns {Promise<void>}
+     */
+    createDefaultTemplates(): Promise<void>;
+    /**
+     * Create default theme
+     *
+     * @returns {Promise<void>}
+     */
+    createDefaultTheme(): Promise<void>;
+    /**
+     * Get available templates
+     *
+     * @returns {Template[]} Available templates
+     */
+    getTemplates(): Template[];
+    /**
+     * Get a specific template
+     *
+     * @param {string} templateName - Template name
+     * @returns {Template | null} Template object or null
+     */
+    getTemplate(templateName: string): Template | null;
+    /**
+     * Apply template to create page content
+     *
+     * @param {string} templateName - Template to use
+     * @param {TemplateVariables} variables - Variables to substitute
+     * @returns {string} Generated content
+     * @throws {Error} If template is not found
+     */
+    applyTemplate(templateName: string, variables?: TemplateVariables): string;
+    /**
+     * Generate UUID for pages
+     *
+     * @returns {string} UUID
+     */
+    generateUUID(): string;
+    /**
+     * Get available themes
+     *
+     * @returns {Theme[]} Available themes
+     */
+    getThemes(): Theme[];
+    /**
+     * Get a specific theme
+     *
+     * @param {string} themeName - Theme name
+     * @returns {Theme | null} Theme object or null
+     */
+    getTheme(themeName: string): Theme | null;
+    /**
+     * Create a new template
+     *
+     * @param {string} templateName - Template name
+     * @param {string} content - Template content
+     * @returns {Promise<void>}
+     */
+    createTemplate(templateName: string, content: string): Promise<void>;
+    /**
+     * Create a new theme
+     *
+     * @param {string} themeName - Theme name
+     * @param {string} content - CSS content
+     * @returns {Promise<void>}
+     */
+    createTheme(themeName: string, content: string): Promise<void>;
+    /**
+     * Get template suggestions based on page name or category
+     *
+     * @param {string} pageName - Page name
+     * @param {string} category - Page category
+     * @returns {string[]} Suggested template names
+     */
+    suggestTemplates(pageName: string, category: string): string[];
+}
+export default TemplateManager;

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

@@ -0,0 +1,56 @@
+export interface ThemeInfo {
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    /** Optional Google Fonts (or other) stylesheet URLs to inject in <head> */
+    fonts?: string[];
+}
+export interface ThemePaths {
+    /** Active theme name (folder name under themes/) */
+    activeTheme: string;
+    /** Path to themes/core.css — structural CSS shared by all themes */
+    coreCssPath: string;
+    /** Path to the active theme's CSS variables file */
+    variablesCssPath: string;
+    /** Path to the active theme's logo image */
+    logoPath: string;
+    /** Path to the active theme's favicon */
+    faviconPath: string;
+    /** Path to the shared location plugin CSS */
+    locationCssPath: string;
+    /** Metadata from theme.json */
+    themeInfo: ThemeInfo | null;
+    /** Optional font stylesheet URLs from theme.json fonts[] */
+    fontUrls: string[];
+}
+/**
+ * Returns a cached ThemeManager for the given active theme + themes directory.
+ *
+ * Use this everywhere instead of `new ThemeManager(...)` unless you specifically
+ * need a fresh instance (e.g. tests). The cache is keyed by `${themesDir}::${activeTheme}`
+ * so cache hits only when both match. Misses produce a new instance and replace
+ * the cached one.
+ */
+export declare function getThemeManager(activeTheme: string, themesDir: string): ThemeManager;
+/** Test/admin helper — drop the cache so the next getThemeManager() rebuilds. */
+export declare function clearThemeManagerCache(): void;
+export declare class ThemeManager {
+    private themesDir;
+    private activeTheme;
+    private _paths;
+    /** Cache key — `${themesDir}::${activeTheme}` — used by getThemeManager. */
+    readonly cacheKey: string;
+    constructor(activeTheme: string, themesDir: string);
+    private loadThemeInfo;
+    private buildPaths;
+    /** Resolve variables.css path — falls back to empty placeholder if theme has no custom vars */
+    private resolveVariablesCssPath;
+    /** Resolve favicon path: prefer favicon.svg → favicon.png → public fallback */
+    private resolveFaviconPath;
+    /** Resolve logo path: prefer logo.svg → logo.png → favicon.svg → favicon.png → public fallback */
+    private resolveLogoPath;
+    get paths(): ThemePaths;
+    /** List all available themes (subdirs of themes/ that have a theme.json) */
+    static listAvailable(themesDir: string): string[];
+}