@camstack/system 1.0.2

package/dist/auth/auth-manager.d.ts

@@ -0,0 +1,109 @@
+import { TokenPayload, IScopedLogger, TokenScope } from '@camstack/types';
+export type { TokenPayload };
+export type AuthConfigReader = {
+    get<T>(path: string): T;
+    update(section: string, data: Record<string, unknown>): void;
+};
+export declare class AuthManager {
+    private readonly config;
+    private readonly jwtSecret;
+    private readonly logger;
+    constructor(config: AuthConfigReader, logger?: IScopedLogger);
+    signToken(payload: Omit<TokenPayload, 'iat' | 'exp'>): string;
+    verifyToken(token: string): TokenPayload;
+    hashPassword(password: string): Promise<string>;
+    comparePassword(password: string, hash: string): Promise<boolean>;
+    generateApiKey(): {
+        token: string;
+        hash: string;
+        prefix: string;
+    };
+    validateApiKey(token: string, storedHash: string): boolean;
+    /**
+     * Create a service token for agent/worker authentication.
+     * Used when forking workers or when agents register.
+     */
+    createServiceToken(opts: {
+        readonly agentId: string;
+        readonly expiresIn?: string;
+    }): string;
+    /**
+     * Mint a short-lived HMAC-signed bridge token used by SSO-style auth
+     * providers (OIDC, SAML, magic-link, …) to hand the post-callback
+     * claims to `/api/auth/sso/finish` without trusting unsigned query
+     * parameters. The endpoint verifies the token signature with the same
+     * `jwtSecret` and only then mints the user session JWT. This closes
+     * the privilege-escalation gap where any client could craft a
+     * `?isAdmin=1` link to `/sso/finish` and become admin.
+     *
+     * The payload carries `kind: 'sso-bridge'` so `verifySsoBridgeToken`
+     * can reject session tokens reused as bridge tokens (and vice versa).
+     * TTL defaults to 5 minutes — long enough to survive the IdP
+     * redirect bounce, short enough that a leaked URL stops being useful
+     * before the operator notices.
+     */
+    signSsoBridgeToken(payload: SsoBridgeClaims, ttlSec?: number): string;
+    /**
+     * Verify + decode a bridge token minted by `signSsoBridgeToken`.
+     * Returns `null` for invalid signature, expired token, or wrong
+     * `kind` claim. Never throws — the consumer ( `/sso/finish`) treats
+     * `null` as 400 Bad Request.
+     */
+    verifySsoBridgeToken(token: string): SsoBridgeClaims | null;
+    /**
+     * Mint a TOTP challenge token bridging the two-step login flow:
+     *
+     *   1. POST /login → password OK + user has 2FA  →  returns
+     *      `{requiresTotp: true, challengeToken: '...'}` (this token).
+     *   2. POST /login/totp-verify → operator types 6-digit code →
+     *      server verifies challenge token + code → mints the real
+     *      session JWT.
+     *
+     * The token carries `kind: 'totp-challenge'` so it can't be confused
+     * with a regular session token, plus the `userId` + `username` +
+     * `isAdmin` claims that will end up in the final session if the code
+     * verifies. TTL defaults to 5 minutes — long enough to type the code,
+     * short enough that an abandoned login can't be picked up later.
+     */
+    signTotpChallengeToken(payload: TotpChallengeClaims, ttlSec?: number): string;
+    /**
+     * Verify + decode a TOTP challenge token. Returns `null` for any
+     * failure (invalid signature, expired, wrong `kind`, missing
+     * claims). The caller MUST also verify the 6-digit code against
+     * `totpManager.verify(userId, code)` before minting the real
+     * session — this method validates the bridge transport only.
+     */
+    verifyTotpChallengeToken(token: string): TotpChallengeClaims | null;
+}
+export interface SsoBridgeClaims {
+    readonly userId: string;
+    readonly username: string;
+    readonly isAdmin: boolean;
+    readonly provider: string;
+    readonly email?: string;
+    readonly displayName?: string;
+    /**
+     * Public HTTPS URL of the hub that minted the token. Carried verbatim
+     * through sign/verify; consumed by cloud-mode OAuth proxies (e.g. the
+     * Alexa Lambda) which need to know which hub to forward to without
+     * keeping per-user routing state. Optional — only the cloud-mode
+     * issuers set it.
+     */
+    readonly hubUrl?: string;
+    /** Permission scopes baked into the token by the OAuth account-linking
+     *  grant. Absent on ordinary SSO-login bridge tokens. */
+    readonly scopes?: readonly TokenScope[];
+    /** OAuth authorization-code binding — set only on `oauth-code` tokens. */
+    readonly redirectUri?: string;
+    readonly integrationId?: string;
+    /** JWT ID — unique per issued code; consumed-set enforces single-use. */
+    readonly jti?: string;
+    /** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
+     *  tokens so the verify path can check the session is not revoked. */
+    readonly sessionId?: string;
+}
+export interface TotpChallengeClaims {
+    readonly userId: string;
+    readonly username: string;
+    readonly isAdmin: boolean;
+}

package/dist/auth/parse-record.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wrap a Zod schema parse with an actionable error message. The
+ * settings-store regression that broke local-auth in May 2026 surfaced
+ * as an opaque Zod error listing every required field as `undefined`
+ * — confusing because the data IS in the DB, just exposed through the
+ * wrong shape by `queryDeclared`. This helper makes the failure mode
+ * obvious: it explicitly mentions the kind, the offending value's top-
+ * level keys, and a hint about the most common cause.
+ *
+ * `schema` is typed loosely (any with a `parse` method) to avoid the
+ * generic ZodTypeAny variance error across Zod major versions when this
+ * helper is reused by callers that import schemas from `@camstack/types`.
+ */
+interface ZodLikeSchema<T> {
+    parse(data: unknown): T;
+}
+export declare function parseRecord<T>(kind: string, schema: ZodLikeSchema<T>, data: unknown): T;
+export {};

package/dist/auth/scope-matcher.d.ts

@@ -0,0 +1,7 @@
+import { TokenScope, MethodAccess } from '@camstack/types';
+/**
+ * True if the scope set grants `access` on device-scoped capabilities.
+ * A `category:device` grant covers every device cap (the broad grant).
+ * Mirrors the OR-semantics of the existing token scope matcher.
+ */
+export declare function scopesAllowDeviceCap(scopes: readonly TokenScope[], access: MethodAccess): boolean;

package/dist/auth/scoped-token-manager.d.ts

@@ -0,0 +1,40 @@
+import { ScopedToken, TokenScope, SettingsStoreClient } from '@camstack/types';
+/**
+ * Manages scoped API tokens with restricted addon/route/capability access.
+ */
+export declare class ScopedTokenManager {
+    private readonly store;
+    constructor(store: SettingsStoreClient);
+    create(userId: string, name: string, scopes: TokenScope[], expiresAt?: number): Promise<{
+        token: string;
+        record: ScopedToken;
+    }>;
+    validate(rawToken: string): Promise<ScopedToken | null>;
+    /**
+     * Coarse scope match — checks only `addonId` / `capability` (no
+     * `route-prefix` after the caps-only migration). Used by addon-route
+     * HTTP handlers that need a quick allow/deny before the per-method
+     * `access` check kicks in via `METHOD_ACCESS_MAP` in
+     * `protectedProcedure`.
+     */
+    matchesScope(token: ScopedToken, addonId?: string, capability?: string): boolean;
+    revoke(tokenId: string): Promise<void>;
+    listForUser(userId: string): Promise<ScopedToken[]>;
+    updateLastUsed(tokenId: string): Promise<void>;
+    /**
+     * One-shot migration: drop tokens whose owner can't be resolved.
+     *
+     * Two ways a token can end up orphan:
+     *   • Pre-fix tokens minted via the CLI were owned by the literal
+     *     string `"system"` (provider hardcode, fixed 2026-05-11).
+     *   • A user gets deleted but their tokens were not cascade-revoked.
+     *
+     * Either way the UI's `listScopedTokens({ userId: u.id })` never
+     * returns them, so the operator can't revoke through the normal flow.
+     * We sweep both classes by passing the live user-id set in.
+     *
+     * Idempotent: if no orphans exist the method is a no-op.
+     * Returns the number of tokens removed.
+     */
+    cleanupOrphans(validUserIds: ReadonlySet<string>): Promise<number>;
+}

package/dist/auth/totp-manager.d.ts

@@ -0,0 +1,51 @@
+import { SettingsStoreClient } from '@camstack/types';
+export interface TotpSetupResult {
+    readonly secret: string;
+    readonly otpauthUrl: string;
+}
+export interface TotpStatus {
+    readonly enabled: boolean;
+    readonly confirmedAt: number | null;
+}
+export declare class TotpManager {
+    private readonly store;
+    constructor(store: SettingsStoreClient, opts?: {
+        /** ±N 30-second windows tolerated. Default 1 = ±30 s clock skew. */
+        readonly window?: number;
+    });
+    /**
+     * Begin enrollment. Always generates a fresh secret — calling `setup`
+     * a second time on the same user replaces any pending half-enrollment
+     * (the user must rescan the QR / re-enter the secret).
+     *
+     * The user identity (`label`) is what an authenticator displays as
+     * the account name; we use the supplied `username` for human-readable
+     * recognition. `ISSUER` is the CamStack brand.
+     */
+    setup(userId: string, username: string): Promise<TotpSetupResult>;
+    /**
+     * Confirm enrollment by checking a code from the authenticator
+     * against the pending secret. On success, flips `confirmedAt` so
+     * `verify()` starts accepting codes. Idempotent on already-confirmed
+     * rows: re-confirming a valid code just succeeds with no state
+     * change.
+     */
+    confirm(userId: string, code: string): Promise<boolean>;
+    /**
+     * Remove enrollment. Idempotent — no error if the user had no row.
+     */
+    disable(userId: string): Promise<void>;
+    /**
+     * Verify a code against the confirmed secret. Returns `false` when:
+     *   - The user has no row (not set up).
+     *   - The row is pending (`confirmedAt === null`).
+     *   - The code doesn't match within the configured window.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * Read the user's enrollment status. Pending half-enrollments are
+     * reported as `enabled: false` — only a confirmed row counts.
+     */
+    getStatus(userId: string): Promise<TotpStatus>;
+    private find;
+}

package/dist/auth/user-manager.d.ts

@@ -0,0 +1,34 @@
+import { AuthManager } from './auth-manager.js';
+import { UserRecord, TokenScope, SettingsStoreClient } from '@camstack/types';
+export type { UserRecord };
+interface CreateUserInput {
+    username: string;
+    password: string;
+    isAdmin?: boolean;
+    allowedProviders?: string[] | '*';
+    allowedDevices?: Record<string, string[] | '*'>;
+    scopes?: TokenScope[];
+}
+type UpdatableUserFields = Partial<Pick<UserRecord, 'isAdmin' | 'allowedProviders' | 'allowedDevices' | 'scopes'>>;
+export interface UserStorageAccess {
+    getStore(): SettingsStoreClient;
+}
+export interface UserConfigReader {
+    get<T>(path: string): T;
+}
+export declare class UserManager {
+    private readonly storageAccess;
+    private readonly auth;
+    private readonly config;
+    constructor(storageAccess: UserStorageAccess, auth: AuthManager, config: UserConfigReader);
+    private get store();
+    create(input: CreateUserInput): Promise<UserRecord>;
+    findByUsername(username: string): Promise<UserRecord | null>;
+    findById(id: string): Promise<UserRecord | null>;
+    validateCredentials(username: string, password: string): Promise<UserRecord | null>;
+    listAll(): Promise<Omit<UserRecord, 'passwordHash'>[]>;
+    update(id: string, data: UpdatableUserFields): Promise<void>;
+    delete(id: string): Promise<void>;
+    resetPassword(id: string, newPassword: string): Promise<void>;
+    ensureAdminExists(): Promise<void>;
+}

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.d.ts

@@ -0,0 +1,53 @@
+import { BaseAddon, ProviderRegistration } from '@camstack/types';
+export declare class AddonPagesAggregatorAddon extends BaseAddon {
+    readonly id = "addon-pages-aggregator";
+    private resolvedPaths;
+    /**
+     * Last successful `listPages()` snapshot per source. Used as the
+     * "stale-but-valid" fallback when a source transiently fails — drops
+     * happen often enough during boot (Moleculer service-discovery
+     * window) that swallowing the error and returning empty leaves the
+     * sidebar with nothing for several seconds. Keeping the previous
+     * good entry means a flake is invisible to the operator.
+     */
+    private readonly lastGood;
+    /** In-flight retry guards keyed by sourceId. Avoids double-scheduling. */
+    private readonly retryTimers;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    private aggregate;
+    /**
+     * Schedule background re-call of `listPages()` on a source that just
+     * failed. Walks `RETRY_BACKOFF_MS` from index 0 — each successful
+     * call updates the cache and emits `AddonPageReady` so the admin UI
+     * invalidates its query. Stops on first success or after the schedule
+     * is exhausted.
+     */
+    private scheduleRetry;
+    private retrySource;
+    /**
+     * Build `/api/addon-pages/<addonId>/<bundle>?v=<mtime>`. Falls back
+     * to `Date.now()` when the bundle path can't be stat'd (remote addon
+     * with no local file, addon not yet on disk, etc.) — the browser
+     * just gets a fresh URL on each call instead of cache-friendly mtime.
+     */
+    private makeBundleUrl;
+    /**
+     * Resolve the local filesystem path for an addon's bundle. Mirrors
+     * `AddonPagesService.resolveBundle` (server-side), but without the
+     * existence / traversal checks — those still live on the server's
+     * static file route. We only need a stat-able path here for the
+     * `mtime` cache-buster.
+     */
+    private resolveBundlePath;
+    /**
+     * Read `server.dataPath` from the cluster yml-backed sections (same
+     * source the server uses at boot), then derive the addons directory
+     * from it. Falls back to `camstack-data/addons` when no settings API
+     * is available — agents and isolated tests don't see this addon, so
+     * the fallback is purely defensive.
+     */
+    private resolvePaths;
+}
+export default AddonPagesAggregatorAddon;

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.js

@@ -0,0 +1,259 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+const require_chunk = require("../../chunk-Cek0wNdY.js");
+const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
+let node_fs = require("node:fs");
+node_fs = require_chunk.__toESM(node_fs);
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+let _camstack_types = require("@camstack/types");
+let node_crypto = require("node:crypto");
+//#region src/builtins/addon-pages-aggregator/dedupe-pages.ts
+/** Stable identity for an addon page, independent of which node reported it. */
+function pageKey(info) {
+	return `${info.addonId}::${info.page.id}`;
+}
+/**
+* Return a new list with duplicate `(addonId, page.id)` entries removed,
+* preserving first-seen order. Pure — never mutates the input.
+*/
+function dedupePages(pages) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const info of pages) {
+		const key = pageKey(info);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(info);
+	}
+	return out;
+}
+//#endregion
+//#region src/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.ts
+/**
+* Addon Pages Aggregator — hub-local builtin that owns the singleton
+* `addon-pages` cap.
+*
+* Walks every registered `addon-pages-source` (collection) provider and
+* emits an enriched `AddonPageInfo[]` list with versioned `bundleUrl`s
+* pointing at `/api/addon-pages/<addonId>/<bundle>?v=<mtime>`. The
+* filesystem `mtime` cache-buster lets the browser pick up addon
+* rebuilds without manual reload — same scheme the original
+* hand-written `AddonPagesService.listPages` used before this split.
+*
+* The static file endpoint (`/api/addon-pages/:addonId/*`) is still
+* served by `AddonPagesService.resolveBundle()` on the server side; this
+* addon only owns the listing surface.
+*
+* Why a builtin rather than a cap-providers helper:
+*   - The aggregator is conceptually the "addon-pages provider" — addons
+*     own caps, not the server. Living in `@camstack/system/builtins` keeps
+*     the surface symmetrical with `system-config`, `local-auth`, etc.
+*   - Lets the aggregator subscribe to source readiness without piping a
+*     CapabilityRegistry handle through `RouterServices`.
+*/
+/**
+* Backoff schedule (ms) used to retry sources that failed during a
+* `listPages()` round-trip — typically because the cap was just
+* registered (provider connected via Moleculer) but the worker-side
+* action registration hadn't propagated yet, so `Service '...listPages'
+* is not found on '<node>'` raced ahead of the call.
+*
+* We schedule one retry per entry; if every retry fails we stop
+* (the next aggregate() run will pick the source up again). On
+* success we re-emit `AddonPageReady` so admin-ui invalidates its
+* `addonPages.listPages` query and the sidebar populates without a
+* page reload.
+*/
+var RETRY_BACKOFF_MS = [
+	500,
+	1500,
+	4e3
+];
+/**
+* Per-source ceiling for a single `listPages()` round-trip. A healthy
+* source answers in well under this (hub-local UDS <100ms, a reachable
+* remote agent <1s). A source that's unreachable — e.g. an agent-hosted
+* addon whose cap routes through a Moleculer `waitForServices` that waits
+* its full 30s discovery timeout for a node that will never appear — must
+* NOT block the whole listing: we time it out fast, serve its cached
+* snapshot, and let the background retry recover it. Combined with the
+* parallel fan-out below, one slow/dead source can no longer stall the
+* sidebar query (which otherwise hangs long enough to trip the WS
+* keepalive → "server unreachable").
+*/
+var PER_SOURCE_TIMEOUT_MS = 2500;
+var AddonPagesAggregatorAddon = class extends _camstack_types.BaseAddon {
+	id = "addon-pages-aggregator";
+	resolvedPaths = null;
+	/**
+	* Last successful `listPages()` snapshot per source. Used as the
+	* "stale-but-valid" fallback when a source transiently fails — drops
+	* happen often enough during boot (Moleculer service-discovery
+	* window) that swallowing the error and returning empty leaves the
+	* sidebar with nothing for several seconds. Keeping the previous
+	* good entry means a flake is invisible to the operator.
+	*/
+	lastGood = /* @__PURE__ */ new Map();
+	/** In-flight retry guards keyed by sourceId. Avoids double-scheduling. */
+	retryTimers = /* @__PURE__ */ new Map();
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		this.resolvedPaths = await this.resolvePaths();
+		const provider = { listPages: async () => this.aggregate() };
+		this.ctx.logger.info("Initialized — aggregating addon-pages-source providers");
+		return [{
+			capability: _camstack_types.addonPagesCapability,
+			provider
+		}];
+	}
+	async onShutdown() {
+		for (const t of this.retryTimers.values()) clearTimeout(t);
+		this.retryTimers.clear();
+		this.lastGood.clear();
+	}
+	async aggregate() {
+		const sources = this.capabilities?.getCollection("addon-pages-source") ?? [];
+		const out = [];
+		const seenIds = /* @__PURE__ */ new Set();
+		const settled = await require_settle_sources.settleSourcesWithTimeout(sources.map((source) => [source.id, () => Promise.resolve(source.listPages())]), PER_SOURCE_TIMEOUT_MS);
+		for (const [sourceId, result] of settled) {
+			seenIds.add(sourceId);
+			if (result.ok) {
+				const enriched = result.value.map((page) => ({
+					addonId: sourceId,
+					page,
+					bundleUrl: this.makeBundleUrl(sourceId, page.bundle)
+				}));
+				for (const item of enriched) out.push(item);
+				this.lastGood.set(sourceId, enriched);
+			} else {
+				this.ctx.logger.warn("addon-pages-source provider failed", { meta: {
+					sourceId,
+					error: result.error.message
+				} });
+				const cached = this.lastGood.get(sourceId);
+				if (cached !== void 0) {
+					for (const item of cached) out.push(item);
+					this.ctx.logger.info("addon-pages-source falling back to cached snapshot", { meta: {
+						sourceId,
+						cachedPages: cached.length
+					} });
+				}
+				this.scheduleRetry(sourceId);
+			}
+		}
+		for (const cachedId of this.lastGood.keys()) if (!seenIds.has(cachedId)) this.lastGood.delete(cachedId);
+		return dedupePages(out);
+	}
+	/**
+	* Schedule background re-call of `listPages()` on a source that just
+	* failed. Walks `RETRY_BACKOFF_MS` from index 0 — each successful
+	* call updates the cache and emits `AddonPageReady` so the admin UI
+	* invalidates its query. Stops on first success or after the schedule
+	* is exhausted.
+	*/
+	scheduleRetry(sourceId, attempt = 0) {
+		if (attempt >= RETRY_BACKOFF_MS.length) return;
+		if (this.retryTimers.has(sourceId)) return;
+		const delayMs = RETRY_BACKOFF_MS[attempt] ?? RETRY_BACKOFF_MS[RETRY_BACKOFF_MS.length - 1];
+		const timer = setTimeout(() => {
+			this.retryTimers.delete(sourceId);
+			this.retrySource(sourceId, attempt);
+		}, delayMs);
+		this.retryTimers.set(sourceId, timer);
+	}
+	async retrySource(sourceId, attempt) {
+		const source = (this.capabilities?.getCollection("addon-pages-source") ?? []).find((s) => s.id === sourceId);
+		if (!source) return;
+		try {
+			const enriched = (await Promise.resolve(source.listPages())).map((page) => ({
+				addonId: source.id,
+				page,
+				bundleUrl: this.makeBundleUrl(source.id, page.bundle)
+			}));
+			this.lastGood.set(source.id, enriched);
+			this.ctx.logger.info("addon-pages-source recovered after retry", { meta: {
+				sourceId,
+				attempt: attempt + 1,
+				pages: enriched.length
+			} });
+			this.ctx.eventBus.emit({
+				id: (0, node_crypto.randomUUID)(),
+				timestamp: /* @__PURE__ */ new Date(),
+				source: {
+					type: "addon",
+					id: this.id
+				},
+				category: _camstack_types.EventCategory.AddonPageReady,
+				data: {
+					addonId: sourceId,
+					recovered: true
+				}
+			});
+		} catch (err) {
+			this.ctx.logger.debug("addon-pages-source retry failed", { meta: {
+				sourceId,
+				attempt: attempt + 1,
+				error: (0, _camstack_types.errMsg)(err)
+			} });
+			this.scheduleRetry(sourceId, attempt + 1);
+		}
+	}
+	/**
+	* Build `/api/addon-pages/<addonId>/<bundle>?v=<mtime>`. Falls back
+	* to `Date.now()` when the bundle path can't be stat'd (remote addon
+	* with no local file, addon not yet on disk, etc.) — the browser
+	* just gets a fresh URL on each call instead of cache-friendly mtime.
+	*/
+	makeBundleUrl(addonId, bundle) {
+		const bundlePath = this.resolveBundlePath(addonId, bundle);
+		let mtime = Date.now();
+		if (bundlePath !== null) try {
+			mtime = node_fs.statSync(bundlePath).mtimeMs;
+		} catch {}
+		return `/api/addon-pages/${addonId}/${bundle}?v=${Math.floor(mtime)}`;
+	}
+	/**
+	* Resolve the local filesystem path for an addon's bundle. Mirrors
+	* `AddonPagesService.resolveBundle` (server-side), but without the
+	* existence / traversal checks — those still live on the server's
+	* static file route. We only need a stat-able path here for the
+	* `mtime` cache-buster.
+	*/
+	resolveBundlePath(addonId, bundle) {
+		const paths = this.resolvedPaths;
+		if (!paths) return null;
+		const addonDistPath = node_path.join(paths.addonsDir, "@camstack", `addon-${addonId}`, "dist");
+		const resolvedBase = node_path.resolve(addonDistPath);
+		const resolvedFile = node_path.resolve(addonDistPath, bundle);
+		if (!resolvedFile.startsWith(resolvedBase + node_path.sep) && resolvedFile !== resolvedBase) return null;
+		return resolvedFile;
+	}
+	/**
+	* Read `server.dataPath` from the cluster yml-backed sections (same
+	* source the server uses at boot), then derive the addons directory
+	* from it. Falls back to `camstack-data/addons` when no settings API
+	* is available — agents and isolated tests don't see this addon, so
+	* the fallback is purely defensive.
+	*/
+	async resolvePaths() {
+		const fallback = { addonsDir: node_path.resolve("camstack-data", "addons") };
+		if (!this.ctx.settings) return fallback;
+		try {
+			const server = await this.ctx.settings.getSection("server");
+			const dataPath = typeof server["dataPath"] === "string" && server["dataPath"] ? server["dataPath"] : "camstack-data";
+			return { addonsDir: node_path.resolve(dataPath, "addons") };
+		} catch (err) {
+			this.ctx.logger.debug("Failed to read server.dataPath — falling back", { meta: { error: (0, _camstack_types.errMsg)(err) } });
+			return fallback;
+		}
+	}
+};
+//#endregion
+exports.AddonPagesAggregatorAddon = AddonPagesAggregatorAddon;
+exports.default = AddonPagesAggregatorAddon;