@lenne.tech/nest-server 11.25.5 → 11.26.0

package/src/core/modules/ai/services/core-ai-tool-grant.service.ts

@@ -0,0 +1,107 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { CrudService } from '../../../common/services/crud.service';
+import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
+import { AiToolGrantDocument, CoreAiToolGrant } from '../models/core-ai-tool-grant.model';
+
+/** Mongoose injection token. */
+export const AI_TOOL_GRANT_MODEL = 'AiToolGrant';
+/** DI token for the model constructor. */
+export const AI_TOOL_GRANT_CLASS = 'AI_TOOL_GRANT_CLASS';
+
+/** Scope of a persisted permission decision. */
+export type AiToolGrantScope = 'conversation' | 'tenant' | 'user';
+
+/**
+ * Persistent permission decisions ("remember my choice") so end users do not have
+ * to re-confirm the same mutating action repeatedly. See {@link CoreAiToolGrant}
+ * for the schema and security model — grants only ever skip the confirmation gate,
+ * they never relax the permission system itself.
+ *
+ * Override via `CoreModule.forRoot(env, { ai: { toolGrantService } })`.
+ */
+@Injectable()
+export class CoreAiToolGrantService extends CrudService<CoreAiToolGrant, CoreAiToolGrant, CoreAiToolGrant> {
+  protected readonly logger = new Logger(CoreAiToolGrantService.name);
+
+  constructor(
+    @InjectModel(AI_TOOL_GRANT_MODEL) protected override readonly mainDbModel: Model<AiToolGrantDocument>,
+    @Inject(AI_TOOL_GRANT_CLASS)
+    protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiToolGrant>,
+  ) {
+    super();
+  }
+
+  /**
+   * Whether any active, non-expired grant exists in the given scope chain that
+   * allows the tool. Scope chain is evaluated in order: a hit at any level wins.
+   * Returns the matched scope (for logging/UX), or `undefined` when no grant applies.
+   */
+  async findActiveGrant(
+    tool: string,
+    scopes: { conversationId?: string; tenantId?: string; userId?: string },
+  ): Promise<AiToolGrantScope | undefined> {
+    if (!tool) {
+      return undefined;
+    }
+    const candidates: { refId: string; scope: AiToolGrantScope }[] = [];
+    if (scopes.conversationId) candidates.push({ refId: scopes.conversationId, scope: 'conversation' });
+    if (scopes.userId) candidates.push({ refId: scopes.userId, scope: 'user' });
+    if (scopes.tenantId) candidates.push({ refId: scopes.tenantId, scope: 'tenant' });
+    if (!candidates.length) {
+      return undefined;
+    }
+    const now = new Date();
+    for (const c of candidates) {
+      try {
+        const grant = await this.mainDbModel
+          .findOne({
+            $or: [{ expiresAt: { $exists: false } }, { expiresAt: null }, { expiresAt: { $gt: now } }],
+            decision: { $ne: 'deny' },
+            enabled: { $ne: false },
+            refId: c.refId,
+            scope: c.scope,
+            tool,
+          })
+          .lean<CoreAiToolGrant>()
+          .exec();
+        if (grant) {
+          return c.scope;
+        }
+      } catch {
+        // best-effort
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Persist (or refresh) a grant for the given scope. Idempotent — upserts on
+   * the unique (scope, refId, tool) compound index.
+   */
+  async grant(tool: string, scope: AiToolGrantScope, refId: string, options?: { expiresAt?: Date }): Promise<void> {
+    if (!tool || !refId) {
+      return;
+    }
+    try {
+      await this.mainDbModel
+        .updateOne(
+          { refId, scope, tool },
+          {
+            $set: {
+              decision: 'allow',
+              enabled: true,
+              expiresAt: options?.expiresAt ?? null,
+            },
+            $setOnInsert: { refId, scope, tool },
+          },
+          { upsert: true },
+        )
+        .exec();
+    } catch (err) {
+      this.logger.warn(`Could not persist tool grant (${scope}:${refId}:${tool}): ${(err as Error).message}`);
+    }
+  }
+}

package/src/core/modules/ai/services/core-ai-tool-policy.service.ts

@@ -0,0 +1,124 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { CrudService } from '../../../common/services/crud.service';
+import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
+import { AiToolPolicyDocument, CoreAiToolPolicy } from '../models/core-ai-tool-policy.model';
+
+/** Mongoose injection token. */
+export const AI_TOOL_POLICY_MODEL = 'AiToolPolicy';
+/** DI token for the model constructor. */
+export const AI_TOOL_POLICY_CLASS = 'AI_TOOL_POLICY_CLASS';
+
+export interface AiToolPolicyDecision {
+  /** Final decision: 'allow', 'deny' or 'ask'. */
+  decision: 'allow' | 'ask' | 'deny';
+  /** Human-readable reason — surfaced to the LLM (and the user via the gate). */
+  reason?: string;
+}
+
+export interface AiToolPolicyEvalContext {
+  /** Role names the caller has. */
+  roles: string[];
+  /** Tenant id (optional). */
+  tenantId?: string;
+  /** User id. */
+  userId?: string;
+}
+
+/**
+ * Fine-grained scoped permission rules against tool calls. See
+ * {@link CoreAiToolPolicy} for the schema. The orchestrator consults this service
+ * for every tool call — `deny` aborts the call, `ask` routes it through the
+ * confirmation gate, `allow` lets it run. No matching policy → fall through to
+ * the existing behaviour (tool.mutating + admin defaults decide).
+ *
+ * Override via `CoreModule.forRoot(env, { ai: { toolPolicyService } })`.
+ */
+@Injectable()
+export class CoreAiToolPolicyService extends CrudService<CoreAiToolPolicy, CoreAiToolPolicy, CoreAiToolPolicy> {
+  protected readonly logger = new Logger(CoreAiToolPolicyService.name);
+
+  constructor(
+    @InjectModel(AI_TOOL_POLICY_MODEL) protected override readonly mainDbModel: Model<AiToolPolicyDocument>,
+    @Inject(AI_TOOL_POLICY_CLASS)
+    protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiToolPolicy>,
+  ) {
+    super();
+  }
+
+  /**
+   * Resolve the effective decision for a tool call. Returns the FIRST matching
+   * decision in this precedence order across all matching policies:
+   *   `deny`  >  `ask`  >  `allow`
+   * (so a deny anywhere always wins; an ask wins over an allow). Returns
+   * `undefined` when no policy applies — the caller then falls back to the
+   * existing behaviour.
+   */
+  async evaluate(
+    tool: string,
+    args: Record<string, any>,
+    ctx: AiToolPolicyEvalContext,
+  ): Promise<AiToolPolicyDecision | undefined> {
+    if (!tool) {
+      return undefined;
+    }
+    const refCandidates: { refId?: string; scope: string }[] = [
+      { scope: 'tool' },
+      ...(ctx.userId ? [{ refId: ctx.userId, scope: 'user' }] : []),
+      ...(ctx.tenantId ? [{ refId: ctx.tenantId, scope: 'tenant' }] : []),
+      ...ctx.roles.map((r) => ({ refId: r, scope: 'role' })),
+    ];
+
+    let policies: CoreAiToolPolicy[] = [];
+    try {
+      policies = await this.mainDbModel
+        .find({
+          $or: refCandidates.map((c) => ({ refId: c.refId ?? null, scope: c.scope })),
+          enabled: { $ne: false },
+          tool,
+        })
+        .lean<CoreAiToolPolicy[]>()
+        .exec();
+    } catch {
+      return undefined;
+    }
+    if (!policies.length) {
+      return undefined;
+    }
+
+    let denyDecision: AiToolPolicyDecision | undefined;
+    let askDecision: AiToolPolicyDecision | undefined;
+    let allowDecision: AiToolPolicyDecision | undefined;
+
+    for (const policy of policies) {
+      for (const rule of policy.rules || []) {
+        if (!rule?.argument || !rule?.pattern || !rule?.action) {
+          continue;
+        }
+        const value = args?.[rule.argument];
+        if (value === undefined || value === null) {
+          continue;
+        }
+        let re: RegExp;
+        try {
+          re = new RegExp(rule.pattern, rule.flags || '');
+        } catch {
+          continue;
+        }
+        if (!re.test(String(value))) {
+          continue;
+        }
+        if (rule.action === 'deny') {
+          denyDecision = { decision: 'deny', reason: rule.reason };
+        } else if (rule.action === 'ask') {
+          askDecision ??= { decision: 'ask', reason: rule.reason };
+        } else if (rule.action === 'allow') {
+          allowDecision ??= { decision: 'allow', reason: rule.reason };
+        }
+      }
+    }
+    return denyDecision ?? askDecision ?? allowDecision;
+  }
+}