adminizer 5.0.0-build.9 → 5.1.0-build.25

package/interfaces/types.d.ts

@@ -1,5 +1,6 @@
 import { AbstractModel } from "../lib/model/AbstractModel.js";
 import { ModelConfig } from "./adminpanelConfig.js";
+import type { User } from "../models/User.js";
 export interface ModelResource {
     name: string;
     config?: ModelConfig;
@@ -11,7 +12,24 @@ export interface AccessRightsToken {
     description: string;
     department: string;
     id: string;
+    getOptions?: (user: User) => Promise<PermissionOption[]>;
+    check?: (user: User, context?: PermissionContext) => Promise<boolean>;
 }
+export interface PermissionOption {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface PermissionContext {
+    rights?: string[];
+    [key: string]: unknown;
+}
+/** Serialized as a JSON string in Group.tokens for a contextual token. */
+export interface GroupPermissionGrant {
+    tokenId: string;
+    rights: string[];
+}
+export type PermissionGrant = string | GroupPermissionGrant;
 export interface PropsField {
     label: string;
     type: string;
@@ -70,3 +88,154 @@ export interface AiAssistantModelInfo {
     name: string;
     description?: string;
 }
+/**
+ * Streaming agent contract.
+ *
+ * A model service that only implements `generateReply` stays a plain chat
+ * model; services that also implement the optional agent members below are
+ * driven by the streaming UI (tool calls, reasoning, attachments, per-user
+ * server-side session). See AbstractAiModelService.
+ */
+/** One SSE frame of a run. `type` drives how the UI folds it into the thread. */
+export type AiAgentStreamEvent = {
+    type: 'text.delta' | 'text.done' | 'reasoning.delta' | 'reasoning.done' | 'tool.start' | 'tool.done' | 'tool.error' | 'step.done' | 'turn.done' | 'done' | 'error' | string;
+    [key: string]: unknown;
+};
+export type AiAgentPublish = (event: AiAgentStreamEvent) => void;
+export interface AiAgentTokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+/** One selectable LLM inside an agent service. */
+export interface AiAgentModelOption {
+    id: string;
+    contextWindow: number | null;
+    maxOutputTokens: number | null;
+    vision: boolean;
+    /** Relative spend multiplier (×1 = median-priced model); null if unknown. */
+    costCoefficient: number | null;
+    [key: string]: unknown;
+}
+/** State of the user's server-side agent session. */
+export interface AiAgentSessionMeta {
+    model: string;
+    contextWindow: number;
+    vision: boolean;
+    turns: number;
+    contextTokens: number;
+    totalUsage: AiAgentTokenUsage;
+    [key: string]: unknown;
+}
+/**
+ * Whether the service can talk to its LLM yet. Services that need no
+ * provisioning simply omit `getConnectionStatus()` and are treated as ready.
+ */
+export interface AiAgentConnectionStatus {
+    state: 'ready' | 'registering' | 'waiting_retry' | 'setup_required' | 'error';
+    provider?: string;
+    baseUrl?: string;
+    source?: string | null;
+    nextAttemptAt?: string | null;
+    lastError?: string | null;
+    expiresAt?: string | null;
+    [key: string]: unknown;
+}
+/** States for which an agent can describe its connection screen. */
+export type AiAgentConnectionState = Exclude<AiAgentConnectionStatus['state'], 'ready'>;
+/**
+ * Declarative connection screen supplied by an agent service. The shared panel
+ * owns rendering, while the agent owns its copy, CTA and which status details
+ * are useful to expose.
+ */
+export interface AiAgentConnectionScreen {
+    title?: string;
+    description?: string;
+    icon?: 'spinner' | 'bot' | 'error';
+    action?: {
+        label: string;
+        href: string;
+    };
+    /** Status values the agent wants to render on this screen. */
+    details?: Array<{
+        field: string;
+        label?: string;
+        format?: 'text' | 'local-time';
+        tone?: 'muted' | 'error';
+    }>;
+}
+/** Normalized budget / rate limits of the provider key, when it exposes them. */
+export interface AiAgentLimits {
+    provider: string;
+    supported: boolean;
+    overBudget?: boolean;
+    message?: string;
+    maxBudgetUsd?: number | null;
+    spentUsd?: number | null;
+    remainingBudgetUsd?: number | null;
+    budgetResetAt?: string | null;
+    burstMaxBudgetUsd?: number | null;
+    burstSpentUsd?: number | null;
+    burstRemainingBudgetUsd?: number | null;
+    burstResetAt?: string | null;
+    burstDurationLabel?: string | null;
+    rpmLimit?: number | null;
+    tpmLimit?: number | null;
+    fetchedAt?: string;
+    [key: string]: unknown;
+}
+/**
+ * Copy the panel shows instead of its neutral defaults. `getUiHints(locale)`
+ * receives the admin user's locale, so agents can return localized copy.
+ */
+export interface AiAgentUiHints {
+    title?: string;
+    welcomeHint?: string;
+    composerPlaceholder?: string;
+    suggestions?: string[];
+    /** Setting an operator must fill in before the service can connect. */
+    setupSetting?: string;
+    /** Where to fill it in; rendered as a button on the connection loader. */
+    setupUrl?: string;
+    /**
+     * Per-state pages rendered while this agent is not ready. `default` is
+     * used for any state without its own screen.
+     */
+    connectionScreens?: Partial<Record<AiAgentConnectionState | 'default', AiAgentConnectionScreen>>;
+    [key: string]: unknown;
+}
+/** A browser-side capability which an agent may call through `ui.method`. */
+export interface AiAgentUiMethod {
+    id: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    action: string;
+    accessRightsToken?: string;
+}
+/** Declarative UI contract consumed by the shared assistant panel. */
+export interface AiAgentUiSchema extends AiAgentUiHints {
+    commands: Array<{
+        id: string;
+        description?: string;
+    }>;
+    uiMethods?: AiAgentUiMethod[];
+    panels: {
+        history: boolean;
+        models: boolean;
+        limits: boolean;
+    };
+}
+/** An uploaded file as handed to the agent service (multer memory storage). */
+export interface AiAgentUploadedFile {
+    originalname: string;
+    mimetype: string;
+    size: number;
+    buffer: Buffer;
+}
+/** What the service reports back about a stored upload, if it stores them. */
+export interface AiAgentSavedFile {
+    id?: string;
+    name?: string;
+    [key: string]: unknown;
+}

package/lib/Adminizer.d.ts

@@ -27,6 +27,10 @@ import { ControllerHandler } from "./app-manager/ControllerHandler.js";
 import { AssetHandler } from "./app-manager/AssetHandler.js";
 import { ConfigLayerHandler } from "./app-manager/ConfigLayerHandler.js";
 import { AccessRightsHandler } from "./access-rights/AccessRightsHandler.js";
+import { AiAssistantUiMethodHandler } from './ai-assistant/AiAssistantUiMethodHandler.js';
+import { AdminLinkHandler } from './admin-links/AdminLinkHandler.js';
+import { AiAssistantAgentSkillHandler } from './ai-assistant/AiAssistantAgentSkillHandler.js';
+import { DocumentationHandler } from './docs/DocumentationHandler.js';
 export declare function createAdminizerLogger(): winston.Logger;
 export interface EmitAsyncOptions {
     /**
@@ -54,6 +58,10 @@ export declare class Adminizer {
     notificationHandler: NotificationHandler;
     historyHandler: HistoryHandler;
     private _aiAssistantHandler?;
+    aiAssistantUiMethodHandler: AiAssistantUiMethodHandler;
+    adminLinkHandler: AdminLinkHandler;
+    aiAssistantAgentSkillHandler: AiAssistantAgentSkillHandler;
+    documentationHandler: DocumentationHandler;
     modelHandler: ModelHandler;
     widgetHandler: WidgetHandler;
     customFilterHandler: CustomFilterHandler;

package/lib/Adminizer.js

@@ -37,12 +37,18 @@ import { bindCors } from "../system/bindCors.js";
 import bindHistory from "../system/bindHistory.js";
 import bindCustomFilterHandlers from "../system/bindCustomFilterHandlers.js";
 import { FeedbackHandler } from "./feedback/FeedbackHandler.js";
-import { buildInternalModelAccess } from "../system/buildInternalModelAccess.js";
+import { refreshInternalModelAccess } from "../system/buildInternalModelAccess.js";
+import { validateAccessGraph } from "./access-graph/AccessGraphResolver.js";
 import { AppManager } from "./app-manager/AppManager.js";
 import { ControllerHandler } from "./app-manager/ControllerHandler.js";
 import { AssetHandler } from "./app-manager/AssetHandler.js";
 import { ConfigLayerHandler } from "./app-manager/ConfigLayerHandler.js";
 import { AccessRightsHandler } from "./access-rights/AccessRightsHandler.js";
+import { AiAssistantUiMethodHandler } from './ai-assistant/AiAssistantUiMethodHandler.js';
+import { AdminLinkHandler } from './admin-links/AdminLinkHandler.js';
+import { AiAssistantAgentSkillHandler } from './ai-assistant/AiAssistantAgentSkillHandler.js';
+import { DocumentationHandler } from './docs/DocumentationHandler.js';
+import bindDocs from '../system/bindDocs.js';
 const logFilePath = "logs/app.log";
 function ensureLogDirectory(filePath) {
     const logDirectory = path.dirname(filePath);
@@ -109,6 +115,10 @@ export class Adminizer {
     notificationHandler;
     historyHandler;
     _aiAssistantHandler;
+    aiAssistantUiMethodHandler;
+    adminLinkHandler;
+    aiAssistantAgentSkillHandler;
+    documentationHandler;
     modelHandler;
     widgetHandler;
     customFilterHandler;
@@ -141,10 +151,20 @@ export class Adminizer {
         this.catalogTemplateComponentHandler = new CatalogTemplateComponentHandler();
         this.mediaManagerHandler = new MediaManagerHandler();
         this.feedbackHandler = new FeedbackHandler(this);
+        this.aiAssistantUiMethodHandler = new AiAssistantUiMethodHandler(this);
+        this.adminLinkHandler = new AdminLinkHandler(this);
+        this.aiAssistantAgentSkillHandler = new AiAssistantAgentSkillHandler(this);
+        this.documentationHandler = new DocumentationHandler(this, () => bindDocs(this));
         this.controllerHandler = new ControllerHandler(this);
         this.assetHandler = new AssetHandler(this);
         this.configLayerHandler = new ConfigLayerHandler(this);
         this.appManager = new AppManager(this);
+        // Registering or unregistering a model changes what the record-access resolvers may
+        // query, so the internal allowlists must follow the registry. Keying it on the
+        // registry itself also covers hosts that bind models directly through
+        // `modelHandler.add` after init, which emits no app:model:* event; config-layer
+        // rebuilds refresh them synchronously inside rebuildConfig itself.
+        this.modelHandler.setInternalAccessRefresher(() => refreshInternalModelAccess(this));
     }
     /**
      * Shared AI assistant model registry.
@@ -257,7 +277,10 @@ export class Adminizer {
         this.emitter.emit('adminizer:init');
         // validate models
         validateSystemModels(this);
-        this.modelHandler.configureInternalAccess(buildInternalModelAccess(this.config, this.modelHandler));
+        refreshInternalModelAccess(this);
+        // Fail loud on structural accessGraph errors at boot; later config rebuilds only
+        // log them and the affected models fail closed at access time.
+        validateAccessGraph(this);
         bindCustomFilterHandlers(this);
         this.config.rootPath = path.resolve(import.meta.dirname + "/..");
         await this.middlewareManager.loadMiddlewares();
@@ -293,6 +316,11 @@ export class Adminizer {
             bindHistory(this);
         this.router = new Router(this);
         await this.router.bind(); // must be after binding policies and req/res functions
+        // Documentation (knowledge base) wires itself on register(); this call
+        // covers a service registered before the config was read. It runs after
+        // the router so those routes sit behind the same middleware stack a
+        // service registered after init() gets.
+        this.documentationHandler.activate();
         /**
          * Adminizer loaded
          * This call is used so that other apps can know that the admin panel is present in the panel and has been loaded, and can activate their logic.

package/lib/DataAccessor.d.ts

@@ -6,7 +6,8 @@ import { ActionType } from "../interfaces/adminpanelConfig.js";
 import { Fields } from "../helpers/fieldsHelper.js";
 import { Adminizer } from "./Adminizer.js";
 import { User } from "../models/User.js";
-import { QueryCriteria } from "../interfaces/queryCriteria.js";
+import { CriteriaWhere, QueryCriteria } from "../interfaces/queryCriteria.js";
+import { RecordAccessCache } from "./access-graph/RecordAccessCache.js";
 export declare class DataAccessor {
     readonly adminizer: Adminizer;
     user: User;
@@ -14,10 +15,23 @@ export declare class DataAccessor {
     action: ActionType;
     private fields;
     private actionVerb;
-    constructor(adminizer: Adminizer, user: User, modelResource: ModelResource, action: ActionType);
+    private associatedPrimaryKeyCache;
+    private recordAccessAssociationFieldsCache?;
+    /** Set on the internal accessors used to verify associations — see disablePopulateAccess(). */
+    private populateAccessDisabled;
+    /** Accessors of associated models, so their access lookups are resolved once per model. */
+    private associatedAccessorCache;
+    /** Per-request record-access resolver; its memoized id lists live as long as this accessor. */
+    private recordAccessResolver?;
+    /**
+     * Memoization shared with the other accessors of the same request; pass one when
+     * building several accessors for one page so the membership lookups run once.
+     */
+    readonly recordAccessCache: RecordAccessCache;
+    constructor(adminizer: Adminizer, user: User, modelResource: ModelResource, action: ActionType, recordAccessCache?: RecordAccessCache);
     private getModelConfig;
-    private accessRelationModel;
     private resolveRelationTarget;
+    private getRelationModel;
     /**
      * Retrieves the fields for the given ModelResource based on action type,
      * taking into account access rights and configuration settings.
@@ -26,10 +40,23 @@ export declare class DataAccessor {
     getFieldsConfig(): Fields;
     private orderFieldsByConfig;
     private getAssociatedFieldsConfig;
+    /**
+     * Base config for a field: the normalized declared config merged over `{key, title}`,
+     * or `undefined` when the config is invalid or field access is denied.
+     */
+    private buildBaseFieldConfig;
     private checkFieldAccess;
     private getSelectedFields;
     private getPopulateCriteria;
+    /** Administrators, and every user when authorization is switched off entirely. */
+    private hasUnrestrictedAccess;
     private canUseSelectedFieldFallback;
+    /**
+     * Primary key of a field's associated model, for the PK-always-visible rule on
+     * populated records. Cached per field config: `process()` asks once per associated
+     * item of every record, and the answer cannot change within an accessor's lifetime.
+     */
+    private associatedPrimaryKey;
     /**
      * Returns filtered record applying config from this.fields on this record
      * @data - record from a specific model */
@@ -38,6 +65,76 @@ export declare class DataAccessor {
     private filterAssociatedRecord;
     /** Process for an array of records */
     processMany<T>(records: T[], criteria?: QueryCriteria): Partial<T>[];
+    /**
+     * {@link processMany} plus record-level access on populated associations.
+     *
+     * `sanitizeUserRelationAccess` confines the queried model only, while adapters
+     * populate associations regardless of record access — so a record the user may not reach can
+     * still be read through a relation of one they may. Records the target model's own rules
+     * keep out of reach are reduced to their primary key here, which costs one batched query
+     * per associated restricted model (memoized for the accessor's lifetime) — except the
+     * associations whose confinement {@link pushDownPopulateAccess} already compiled into
+     * the populate JOIN itself: those arrive pre-reduced and are skipped.
+     *
+     * Read paths only: write paths hand back the record the user just supplied.
+     */
+    processManyWithAccess<T>(records: T[], criteria?: QueryCriteria): Promise<Partial<T>[]>;
+    /**
+     * Compiles the record-access confinement of single populated associations into the
+     * criteria (`populateOn`), so the adapter ANDs it into the populate JOIN's ON clause
+     * and {@link processManyWithAccess} skips the post-read query for those fields — the
+     * closed records arrive as bare foreign keys straight from the database. Only the
+     * associations the adapter declares pushdown-capable and whose access filter has an
+     * adapter-portable shape are compiled; the rest keep the post-read verification.
+     *
+     * Single associations only: a filtered-out belongsTo row still carries its foreign
+     * key, while a record dropped from a populated collection would lose its id — and an
+     * edit form saving that truncated collection would silently sever the links.
+     *
+     * Any incoming `populateOn` is discarded — this method is its sole author, because
+     * the verification skip above trusts the key.
+     */
+    pushDownPopulateAccess(criteria?: QueryCriteria): Promise<QueryCriteria>;
+    /**
+     * Turns the association verification of {@link processManyWithAccess} off for this accessor.
+     * Used for the accessors that perform that verification themselves: they only read ids,
+     * and two restricted models referencing each other sideways would otherwise recurse.
+     */
+    disablePopulateAccess(): this;
+    /**
+     * Association fields whose target model is access-restricted and whose content therefore
+     * needs verifying — except the edge pointing at this model's own graph parent, where
+     * the target is reachable by construction (a visible child hangs off a visible parent).
+     */
+    private recordAccessAssociationFields;
+    /** True when the model confines its records to the user, by its own relation or the graph. */
+    private hasRecordAccessRules;
+    private associatedResourceName;
+    /** Primary keys of the populated records referenced by a field, keyed by their string form. */
+    private collectAssociatedIds;
+    /** Replaces populated records the user may not reach with their bare primary key. */
+    private reduceInvisibleAssociations;
+    /**
+     * The associated model's own view accessor, shared between the pushdown and the
+     * post-read verification so its access lookups resolve once per model.
+     */
+    private associatedAccessor;
+    /**
+     * Subset of `ids` the user may reach in the associated model, or `undefined` when that
+     * model has no record access rules. The target's own accessor is reused across calls, so its
+     * membership lookups are resolved once.
+     */
+    private visibleAssociatedIds;
     sanitizeUserRelationAccess(criteria?: QueryCriteria): Promise<QueryCriteria>;
     setUserRelationAccess<T>(record: T): Promise<Partial<T>>;
+    /**
+     * Where-fragment confining this model to the records the user may reach
+     * (`userAccessRelation` or accessGraph); `{}` means no record-level constraint.
+     *
+     * For surfaces that reference records without reading them through the model API —
+     * the change history, for one — and therefore cannot rely on
+     * {@link sanitizeUserRelationAccess} doing it for them.
+     */
+    getRecordAccessWhere(): Promise<CriteriaWhere>;
+    private getRecordAccessResolver;
 }