@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,269 @@
+/**
+ * AgentTokenManager — user-delegated agent API tokens (#946).
+ *
+ * A user mints a short-lived bearer credential for themselves and hands it to
+ * an agent. The token is a *delegation of the owner's own authority*: it can
+ * never do anything its owner could not already do.
+ *
+ * Design decisions (recorded on #946):
+ *  - **Opaque, not JWT.** A 24-hour credential must be revocable before it
+ *    expires; a self-signed JWT cannot be withdrawn.
+ *  - **SHA-256, not bcrypt.** The token is 256 bits of uniform randomness, so
+ *    there is no dictionary to attack and no work factor is warranted. bcrypt
+ *    would only add per-request latency on an endpoint agents hammer.
+ *    (Password hashing is a different problem — low-entropy human input.)
+ *  - **Persisted, not in-memory.** MagicLinkAuthProvider's in-memory map suits
+ *    its 15-minute TTL; at 24 hours a restart would silently invalidate every
+ *    live token mid-run.
+ *  - **Roles are never stored on the token.** Only `owner` is kept, and
+ *    permissions resolve live from the user record at request time — so
+ *    demoting or disabling a user immediately weakens every token they hold.
+ *  - **Scopes only narrow.** Effective permission is owner ∩ scopes, enforced
+ *    live by PolicyInformationPoint and UserManager against `viaToken.scopes`.
+ *
+ * Store: `<FAST_STORAGE>/tokens/agent-tokens.json`, a map keyed by token id,
+ * matching the map-not-array convention of `users.json`.
+ *
+ * ## Correctness rules this file is built around (#1108)
+ *
+ * A review of the original implementation found seven defects, all of which
+ * came back to three rules that were implied but never stated. They are stated
+ * here because each was violated by code that read as though it respected them:
+ *
+ *  1. **The read path does no disk IO.** `verify()` runs on every agent
+ *     request. The original stamped `lastUsedAt` and persisted synchronously —
+ *     and `persist()` took a timestamped backup copy first, so authenticating
+ *     wrote an unbounded pile of hash-bearing files into the token directory.
+ *     `lastUsedAt` is now buffered in memory and flushed by the maintenance
+ *     timer; backups are taken only on structural change, and are bounded.
+ *  2. **An unreadable date means expired, everywhere.** `Date.parse` returns
+ *     `NaN` for a malformed value, and `NaN <= now` and `NaN > now` are *both*
+ *     false — so `verify()` read a broken `expiresAt` as "not expired" while
+ *     `isLive()` read the same value as "not live". The result was a token that
+ *     authenticated forever and appeared in no listing, not even an admin's.
+ *     Every expiry comparison now goes through `expiryOf()`, which collapses
+ *     unparseable to `-Infinity`: unreadable fails closed.
+ *  3. **Nothing hands out a live reference to a stored record.** `verify()`
+ *     returned the record straight out of the Map — hash included — and
+ *     AgentTokenAuthProvider put its `scopes` array into `req.userContext`,
+ *     where the ACL layer treats it as the permission ceiling. Anything
+ *     downstream holding that array was editing the store. Every exit from this
+ *     class is now a copy via `toPublic()`.
+ *
+ * ## Extraction note
+ *
+ * The two namespace-bound values live in `CONFIG_PREFIX` and `TOKEN_PREFIX`
+ * below. When this class moves into the shared framework package, those are the
+ * parameters a derivative supplies — nothing else in the file names the host.
+ */
+import BaseManager, { type ManagerStats } from './BaseManager.js';
+import type { BackupData } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { PermissionSubject } from './UserManager.js';
+export { MINT_PERMISSION } from '../utils/delegation.js';
+export interface AgentTokenRecord {
+    id: string;
+    owner: string;
+    name: string;
+    /** `sha256:<hex>` — never the cleartext */
+    hash: string;
+    /** Leading characters, kept for display in listings */
+    prefix: string;
+    scopes: string[];
+    createdAt: string;
+    expiresAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    revokedBy: string | null;
+    /**
+     * #1762 slice 6: the person who minted it while acting for `owner` under a
+     * proxy grant. Absent when the owner minted it themselves.
+     */
+    approvedBy?: string;
+    /** The proxy grant it was minted under. Ending that grant ends this token; it works only while the grant is in force. */
+    proxyGrantId?: string;
+}
+/** A record safe to return over the API — no hash. */
+export type AgentTokenPublic = Omit<AgentTokenRecord, 'hash'>;
+export interface MintResult {
+    /** Cleartext token — returned once, never persisted. */
+    token: string;
+    record: AgentTokenPublic;
+}
+declare class AgentTokenManager extends BaseManager {
+    private storePath;
+    private tokens;
+    /**
+     * Records that failed validation on load, kept verbatim and written back.
+     *
+     * They are deliberately NOT in `tokens`, so they authenticate nothing and
+     * appear in no listing. But dropping them would rewrite the store without
+     * them on the next save — destroying the only evidence that something
+     * corrupted the file. Fail closed, keep the evidence, stay up.
+     */
+    private quarantined;
+    /** Ids whose `lastUsedAt` has moved in memory but not yet on disk. */
+    private dirtyLastUsed;
+    /**
+     * Serialises saves. `writeFileAtomic` guarantees no *partial* file, and says
+     * so in its own header — it is explicitly not a lock, and two concurrent
+     * writers still race for last-writer-wins. This is the queue the page index
+     * uses for the same reason.
+     */
+    private writeQueue;
+    private tokenConfig;
+    constructor(engine: WikiEngine);
+    initialize(): Promise<void>;
+    /**
+     * Flush buffered `lastUsedAt` stamps and purge dead records, every
+     * `sweep-interval-seconds` — a maintenance job on the scheduler (#1721).
+     *
+     * Purging used to happen only in `initialize()`, so a server up for months
+     * never applied its own retention policy again — the config promised a
+     * 30-day window that was only ever honoured at boot.
+     */
+    private startMaintenance;
+    private load;
+    /**
+     * Persist the store atomically, serialised behind the write queue.
+     *
+     * Quarantined records are written back untouched so a save never destroys
+     * evidence of corruption.
+     */
+    private persist;
+    /**
+     * Write out buffered `lastUsedAt` stamps, if any.
+     *
+     * Public so a caller — a test, or a shutdown path — can make the in-memory
+     * stamp durable on demand without waiting for the maintenance tick.
+     */
+    flushLastUsed(): Promise<number>;
+    /**
+     * Mint a token for `owner`.
+     * @throws Error with a caller-safe message on validation failure.
+     */
+    /**
+     * The audit sink, or null when no AuditManager is registered (#1111).
+     *
+     * Fire-and-forget with a caught error at the call site: the credential is the
+     * product and the log is a record of it, so losing the log is bad but
+     * refusing to mint because the log failed is worse.
+     */
+    private auditSink;
+    /**
+     * Mint a token for `subject`, the owner acting through a session (#1178).
+     *
+     * Takes the subject rather than a username because minting asks a policy
+     * question: does the owner hold every scope the token would carry? A scope
+     * the owner lacks is inert at use time (effective permission is owner ∩
+     * scopes), so refusing it here is honesty rather than security — a token
+     * that silently cannot do the thing it names is a support ticket. The
+     * refusal names the missing scopes so the caller can act on it.
+     *
+     * #1762 slice 6: a subject acting for the owner under a proxy grant mints
+     * the owner's token. The same `permits` question then asks the proxy
+     * ceiling, so every scope must be in the grant, held by the owner and held
+     * by the person acting. The token records that person (`approvedBy`) and the
+     * grant (`proxyGrantId`); it works only while that grant is in force.
+     */
+    mint(subject: PermissionSubject, name: string, scopes: string[], ttlHours?: number, now?: number): Promise<MintResult>;
+    /**
+     * Verify a presented cleartext token.
+     * Returns a COPY of the record when valid, else null. Buffers `lastUsedAt`.
+     *
+     * No disk IO: see rule 1 in the file header. The stamp lands in memory and is
+     * flushed by the maintenance tick, so a token used a thousand times a minute
+     * costs one write, not a thousand writes and a thousand backup files.
+     */
+    verify(token: string, now?: number): Promise<AgentTokenPublic | null>;
+    /** Live (not expired, not revoked) tokens for an owner. */
+    listForOwner(owner: string, now?: number): AgentTokenPublic[];
+    /** Every live token, for admin oversight (#946 open question 1). */
+    /**
+     * #1006: how many live tokens exist. Never which, and never their values.
+     *
+     * This manager is the reason the contract is counts-only rather than the
+     * `getAll()` originally asked for: it holds bearer credentials, and a
+     * generic enumeration on the base class would hand them to the first
+     * generic caller. `listAll()` returns `AgentTokenPublic`, which already
+     * excludes the secret — this reports its LENGTH and not its contents.
+     */
+    getManagerStats(): Promise<ManagerStats>;
+    listAll(now?: number): AgentTokenPublic[];
+    getById(id: string): AgentTokenPublic | null;
+    /**
+     * A token minted under a proxy grant works only while that grant is in
+     * force (#1762 slice 6): ended, past its end date, or proxy access turned
+     * off, and the token stops. Asked of AuthManager, which owns the grants; no
+     * answer is a refusal. A token its owner minted is not affected.
+     */
+    private approvalInForce;
+    /**
+     * Revoke a token. Effective immediately — verify() reads the in-memory store
+     * per request, so there is no cache to wait out. `ctx` is who revoked it:
+     * under a proxy grant (#1762 slice 6) the record names the represented
+     * person and the person acting, and `revokedBy` is the person acting.
+     */
+    revoke(id: string, ctx: PermissionSubject, now?: number): Promise<boolean>;
+    /**
+     * Extend one of the caller's own live tokens (#1734): move its expiry later
+     * by `hours` (the maximum when omitted), never beyond now + `max-ttl-hours`.
+     * The token string and its scopes do not change, so the agent holding it
+     * keeps working without a new hand-over.
+     *
+     * - Only the token's owner extends it. An admin does not extend someone
+     *   else's token: like minting, a token's lifetime traces to the person who
+     *   chose to delegate. Returns null for a token that is not the caller's, so
+     *   the route answers it as one that does not exist.
+     * - The owner must hold `token-extend`, asked of the PDP with the subject the
+     *   request carries, so step-up applies and a delegated credential is refused.
+     * - An expired or revoked token is not extended: mint a new one.
+     *
+     * Recorded before the expiry moves, like mint and revoke: `token-extend` is
+     * declared on-failure: refuse, so a lifetime change that cannot be audited
+     * does not happen.
+     *
+     * @returns The updated record, or null when the caller has no such token
+     * @throws Error with a caller-safe message when the extension is refused
+     */
+    extend(id: string, subject: PermissionSubject, hours?: number, now?: number): Promise<AgentTokenPublic | null>;
+    /**
+     * Drop expired/revoked records past the retention window.
+     *
+     * The audit log is unaffected — and since #1111 that is true rather than
+     * aspirational: `token-mint` and `token-revoke` events outlive the records
+     * here, so purging loses the credential and keeps the history of it. Before
+     * that, this comment claimed an audit trail that did not exist, which made
+     * `retention-days` load-bearing by accident.
+     */
+    purgeExpired(now?: number): Promise<number>;
+    private isLive;
+    /**
+     * A copy safe to hand out: no hash, and its own `scopes` array.
+     *
+     * The array copy is the load-bearing half. `scopes` becomes the permission
+     * ceiling in `req.userContext.viaToken`, so sharing the stored array with a
+     * caller means anything downstream can widen a token's authority in place.
+     */
+    private toPublic;
+    /**
+     * Flush pending stamps. Without this, `lastUsedAt` movement since the
+     * last sweep is lost on a clean shutdown. The sweep job itself is stopped
+     * by BackgroundJobManager's shutdown handoff (#1721).
+     */
+    shutdown(): Promise<void>;
+    backup(): Promise<BackupData>;
+    /**
+     * Refuse. A token backup carries no hashes, so there is nothing to restore
+     * from (#1111).
+     *
+     * This used to inherit `BaseManager`'s no-op default, which meant
+     * `restorable: false` was honoured because nobody had implemented the
+     * alternative rather than because anything declined. If someone later wrote a
+     * restore from that payload, records would return with NO hash, and whether
+     * they failed closed would depend entirely on how `verify()` compares. A
+     * refusal that is written down cannot be undone by accident.
+     */
+    restore(_backupData: BackupData): Promise<void>;
+}
+export default AgentTokenManager;

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

@@ -0,0 +1,116 @@
+/**
+ * AssetManager — provider registry for the unified DAM framework.
+ *
+ * Holds a registry of AssetProviders (keyed by provider.id) and exposes a
+ * single search/getById/getThumbnail API that fans out across all registered
+ * providers.  The two built-in providers (BasicAttachmentProvider via
+ * AttachmentManager, FileSystemMediaProvider via MediaManager) are registered
+ * automatically in initialize().  Addons register additional providers via
+ * registerProvider().
+ *
+ * AssetService delegates to this manager so its existing public API is
+ * unchanged — callers that already use AssetService continue to work without
+ * modification.
+ */
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { AssetProvider, AssetRecord, AssetPage, AssetQuery, ProviderHealthReport } from '../types/Asset.js';
+import type { ActorContext } from '../context/ActorContext.js';
+declare class AssetManager extends BaseManager {
+    readonly description = "Provider registry for the unified Digital Asset Management framework";
+    private registry;
+    /** Last known health status for each provider, keyed by provider.id */
+    private healthMap;
+    /** In-memory reverse index: page slug → set of composite asset keys */
+    private pageAssetsMap;
+    /** Absolute path to page-assets-index.json, set during initialize() */
+    private pageAssetsIndexPath;
+    /** Serialized write queue — prevents concurrent JSON saves from conflicting */
+    private pageAssetsWriteQueue;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Register an asset provider.  If a provider with the same id is already
+     * registered it is replaced and a warning is logged.
+     */
+    registerProvider(provider: AssetProvider): void;
+    /** Return a single provider by id, or null. */
+    getProvider(id: string): AssetProvider | null;
+    /** Return all registered providers in registration order. */
+    getProviders(): AssetProvider[];
+    /**
+     * Run healthCheck() on every registered provider that implements it.
+     *
+     * Updates the internal health map.  Providers without a healthCheck() method
+     * are marked 'healthy' (they are always assumed to be available).  Call this
+     * at startup and from the admin health-check endpoint to refresh status.
+     */
+    checkProviderHealth(): Promise<void>;
+    /**
+     * Return a health report for every registered provider.
+     * Suitable for surfacing in an admin UI or REST endpoint.
+     */
+    getProviderHealth(): ProviderHealthReport[];
+    /**
+     * Scan wiki markup content for asset references and update the reverse index
+     * for the given page.  Call this fire-and-forget at page-save time.
+     *
+     * Handles two reference formats:
+     *   [{Image src='filename.jpg'}]    → local attachment  → "local:<id>"
+     *   [{ATTACH src='filename.pdf'}]   → local attachment  → "local:<id>"
+     *   [{Image src='media://img.jpg'}] → media library     → "media-library:<id>"
+     *
+     * Runs all provider lookups concurrently; unresolvable filenames are silently
+     * skipped so a missing asset never blocks the page save.
+     */
+    syncPageAssets(pageName: string, content: string): Promise<void>;
+    /**
+     * Return all AssetRecords referenced by the given page slug.
+     *
+     * O(1) index lookup + one getById() call per referenced asset.
+     * Stale entries (asset deleted or provider removed) are silently filtered out.
+     */
+    getAssetsForPage(slug: string): Promise<AssetRecord[]>;
+    /**
+     * Remove a page's entry from the reverse index.
+     * Call this when a page is deleted or renamed.
+     */
+    removePageAssets(slug: string): void;
+    private _loadPageAssetsIndex;
+    /**
+     * Queue an atomic write of the page-assets index.
+     * Uses the same promise-chain pattern as VersioningFileProvider.savePageIndex()
+     * to prevent race conditions from concurrent page saves.
+     */
+    private _savePageAssetsIndex;
+    /** True when the provider is healthy or has no health check. */
+    private isHealthy;
+    /**
+     * Search across all registered providers (or a specific one when
+     * query.providerId is set), merge results, sort, and paginate.
+     *
+     * @param query - what to look for; `wikiContext` rides along for the media
+     *   providers' own path ACL, as it always has
+     * @param ctx - who is searching (#1179, #1460). Mandatory and positional:
+     *   the private-store half of the results is the requester's own container,
+     *   and a door that took it out of the query bag would be reading an
+     *   identity someone could leave out (#1164).
+     */
+    search(query: AssetQuery & {
+        providerId?: string;
+        wikiContext?: unknown;
+    }, ctx: ActorContext): Promise<AssetPage>;
+    /**
+     * Retrieve a single asset by id.  If providerId is given only that provider
+     * is checked; otherwise all providers are tried in registration order.
+     */
+    getById(id: string, providerId?: string): Promise<AssetRecord | null>;
+    /**
+     * Generate or retrieve a cached thumbnail.
+     * Requires the provider to declare the 'thumbnail' capability.
+     */
+    getThumbnail(id: string, providerId: string, size?: string): Promise<Buffer | null>;
+    private _mergeAggregations;
+    private _sort;
+}
+export default AssetManager;