@sparkelf/dsh-knowledge-base 0.1.21 → 0.1.23

package/lib/types/index.d.ts

@@ -10,7 +10,9 @@
  *
  * It owns no authorization logic. DataOps AuthGuard and PermissionGuard resolve
  * the caller's roles and grants from the session credential; this plugin only
- * forwards requests (AGENTS.md "Managed DataOps Authorization").
+ * forwards requests (AGENTS.md "Managed DataOps Authorization"). Which model-facing
+ * tools exist is decided from that same permission projection in `toolDisclosure.ts`;
+ * path-level checks and the backend remain the enforcement boundary.
  *
  * Content retrieval is deliberately absent. Once the view tree is mounted the
  * official `grep`, `read`, `write`, and `edit` tools operate on it as an
@@ -19,6 +21,8 @@
  * @module @sparkelf/dsh-knowledge-base
  */
 import type { Context } from '@deepseek-ai/cordis';
+import { type ManagementContext } from './managementTools.ts';
+import { type ToolDisclosureCoordinator } from './toolDisclosure.ts';
 import { type WorkflowActor } from './workflowPublish.ts';
 import z from '@deepseek-ai/schemastery';
 import { type KnowledgeConfig, type KnowledgeGrant, type KnowledgeGrantRequest, type KnowledgeRevokeRequest, type KnowledgeSshView, type KnowledgeStatus } from './protocol.ts';
@@ -189,6 +193,18 @@ export declare function isTeamDeployment(config: Config): boolean;
  * "no user".
  */
 export declare const LOCAL_USER_ID = "local";
+/**
+ * The permission context a personal deployment discloses tools from.
+ *
+ * A personal deployment has no accounts, so there is nobody to ask: the local
+ * operator owns every capability the product knows about. Kept as a function rather
+ * than the inline object inside the management host so the disclosure coordinator
+ * can register the personal tool surface synchronously at startup, instead of
+ * waiting for a backend round trip that does not exist.
+ *
+ * @returns the full-capability context a local owner holds.
+ */
+export declare function localManagementContext(): ManagementContext;
 /**
  * Why a path was refused in a personal deployment.
  *
@@ -1152,6 +1168,13 @@ export interface SkillCandidateLike {
 export interface SkillDefinitionLike extends SkillCandidateLike {
     readonly content: string;
 }
+/**
+ * The permission-based tool disclosure coordinator this plugin instance registered.
+ *
+ * @param host - the Host context the plugin was applied to.
+ * @returns the coordinator, or undefined when this context has no knowledge-base plugin.
+ */
+export declare function knowledgeBaseToolDisclosure(host: object): ToolDisclosureCoordinator | undefined;
 export declare function apply(ctx: Context, deploymentConfig: Config): void;
 /** Re-exported for tests and for callers that need the host shape. */
 export type { RemoteHost, RemoteRunner };

package/lib/types/knowledgeTools.d.ts

@@ -7,11 +7,14 @@
  * bypasses all of that, so the model gets tools that go through the same host
  * operations as the HTTP routes.
  *
- * This module owns argument validation, the permission calls and the tool result
- * shape. The host object is supplied by `index.ts`; it is the seam that reuses the
- * existing `canReadPath` / `canWritePath` / `listDirectoryWithPermissions` /
- * `readKnowledgeFile` / `createKnowledgeEntry` / `moveEntry` implementations, and it
- * is what tests replace without importing the whole plugin.
+ * This module owns argument validation, path-level permission checks and the tool
+ * result shape. Which tools exist is decided once per permission context by
+ * `toolDisclosure.ts`; the path checks here decide which data a visible tool may
+ * touch and are therefore kept. The host object is supplied by `index.ts`; it is the
+ * seam that reuses the existing `canReadPath` / `canWritePath` /
+ * `listDirectoryWithPermissions` / `readKnowledgeFile` / `createKnowledgeEntry` /
+ * `moveEntry` implementations, and it is what tests replace without importing the
+ * whole plugin.
  *
  * @module @sparkelf/dsh-knowledge-base/knowledgeTools
  */
@@ -117,8 +120,6 @@ export type KnowledgeViewSync = {
 export interface KnowledgeFileToolHost {
     /** Resolve the caller (team: DataOps `/auth/me`; personal: the local operator). */
     resolveCaller(): Promise<KnowledgeToolCaller>;
-    /** Backend DSH permission for this operation, when the host has a permission context. */
-    hasPermission?(permission: string): Promise<boolean>;
     /** FTS5 search over the sidecar index, already scoped to the caller. */
     searchIndex?(input: {
         query: string;
@@ -231,9 +232,10 @@ export declare const asKnowledgeToolError: (error: unknown, path?: string) => Kn
  */
 export declare const assertToolPath: (value: unknown, allowRoot?: boolean) => string;
 /**
- * Build the five file model-facing tools.
+ * Build the knowledge-base model-facing tools.
  *
- * Returned definitions are registered by `apply`; tests call the same definitions with
- * a fake host to assert permission, path and audit behaviour without a live backend.
+ * Returned definitions are registered by `apply` through the permission-based
+ * disclosure coordinator; tests call the same definitions with a fake host to assert
+ * path, audit and result behaviour without a live backend or a permission backend.
  */
 export declare const createKnowledgeFileTools: (host: KnowledgeFileToolHost) => import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/types/managementTools.d.ts

@@ -2,11 +2,17 @@
  * Model-facing management tools for the knowledge base and the workflow plaza.
  *
  * The UI already exposes these operations. This module gives the model the same
- * operations without re-implementing authorization: every tool reads the backend
- * review context (roles + department scope) and refuses with a structured 403 before
- * touching the host. Writes additionally require an explicit human authorization flag,
- * because a model deciding on its own must never be indistinguishable from an operator
- * approving a review.
+ * operations without re-implementing authorization: which tools exist is decided
+ * once from the caller's review context by `toolDisclosure.ts`, so a tool body does
+ * not re-read the permission tree on every call. The context is still read where it
+ * decides WHICH rows a visible tool may return (department scope, own audit trail)
+ * and for the actor recorded in an audit line. Writes additionally require an
+ * explicit human authorization flag, because a model deciding on its own must never
+ * be indistinguishable from an operator approving a review.
+ *
+ * DataOps remains the final authority: every host call below reaches a backend
+ * route that enforces the JWT's current roles and grants, so a stale disclosure can
+ * cause a refusal but never an unauthorized operation.
  *
  * Secrets are write-only through the UI; these tools deliberately reject secret-shaped
  * fields and redact them on reads.
@@ -147,8 +153,6 @@ export declare const DEFAULT_DSH_PERMISSIONS: Readonly<Record<string, readonly s
 export declare function defaultPermissionsForRoles(roleKeys: readonly string[]): string[];
 /** True when the caller holds one backend permission key. */
 export declare function hasPermission(context: ManagementContext, permission: string): boolean;
-/** Require one backend permission key; a denial is a structured 403. */
-export declare function requirePermission(context: ManagementContext, permission: string, action?: string): void;
 /** Global administrators: all resources and all review queues. */
 export declare function isGlobalAdmin(context: ManagementContext): boolean;
 /** Department reviewers: their department and its descendants. */

package/lib/types/toolDisclosure.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Permission-based disclosure of the model-facing knowledge-base tools.
+ *
+ * A tool the caller may never use should not be in the model's tool list at all.
+ * Registering every tool and refusing inside `execute()` wastes a schema slot,
+ * invites a call that will fail, and hides the real capability from the surface
+ * that decides what to offer. Disclosure is therefore decided ONCE per permission
+ * context: the coordinator registers the tools a context allows and disposes the
+ * rest. Execution never re-reads the full permission tree; the backend remains the
+ * final authority for every request the tools then make.
+ *
+ * ## What is decided where
+ *
+ * - **Disclosure (this module).** A tool's group and its required permission keys
+ *   or role capability. Evaluated from the caller's `/api/ai/review/context`
+ *   projection (`ManagementContext`), the same object the Settings panel and route
+ *   gate already read.
+ * - **Data filtering (the tools themselves).** Path-level `canRead` / `canWrite`
+ *   calls stay in `execute()`: they decide WHICH rows a visible tool may touch, not
+ *   whether the tool exists. The same holds for department-scope filtering of
+ *   grants, audit entries and review queues.
+ * - **Final authorization (DataOps).** Every backend route the tools call enforces
+ *   the JWT's current roles and grants. A stale tool registration can therefore
+ *   cause a refusal, never an unauthorized read or write.
+ *
+ * ## Groups
+ *
+ * `read` tools exist for a caller with the knowledge-base read key; `write` tools
+ * for the editors; `manage` for the administrator/reviewer surfaces; `publish` for
+ * workflow publication. Groups exist so a permission change can be applied as a
+ * set, and so a fault in one group is reflected in one place rather than in every
+ * tool body.
+ *
+ * @module @sparkelf/dsh-knowledge-base/toolDisclosure
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ManagementContext } from './managementTools.ts';
+/** The four disclosure groups a knowledge-base tool can belong to. */
+export declare const TOOL_GROUPS: readonly ["read", "write", "manage", "publish"];
+/** One disclosure group. */
+export type KnowledgeToolGroup = (typeof TOOL_GROUPS)[number];
+/**
+ * One tool's disclosure rule.
+ *
+ * `permissions` lists keys that must ALL be held. `capability` names a role
+ * capability that must also be present; it is how the tools whose product
+ * description is "reviewer only" or "global admin only" are filtered without
+ * inventing a permission key the backend does not issue.
+ */
+export interface ToolAccessRule {
+    /** Which group the tool is registered and disposed with. */
+    readonly group: KnowledgeToolGroup;
+    /** Every permission key the caller must hold. */
+    readonly permissions?: readonly string[];
+    /** Reviewer/admin capability the caller must have, in addition to permissions. */
+    readonly capability?: 'reviewer' | 'admin';
+}
+/**
+ * Disclosure rules for every model-facing tool this package registers.
+ *
+ * The map is the single list of what exists; the coordinator rejects a tool
+ * definition without a rule and a rule without a definition at construction time,
+ * so a new tool cannot ship undisclosed or leave a stale policy behind.
+ */
+export declare const KB_TOOL_ACCESS: Readonly<Record<string, ToolAccessRule>>;
+/** Tool names per group, derived from {@link KB_TOOL_ACCESS}. */
+export declare const TOOL_GROUPS_OF: Readonly<Record<KnowledgeToolGroup, readonly string[]>>;
+/** Every model-facing tool name this package discloses. */
+export declare const KNOWLEDGE_TOOL_NAMES: readonly string[];
+/** One tool's disclosure decision. */
+export interface ToolAccessDecision {
+    /** Whether the tool may be registered for this context. */
+    readonly allowed: boolean;
+    /** The tool's group, when a rule exists. */
+    readonly group?: KnowledgeToolGroup;
+    /**
+     * What the context lacks, as permission keys (`kb:file:write`) or capability
+     * labels (`reviewer`, `admin`, `permission-context`). Empty when allowed.
+     */
+    readonly missing: readonly string[];
+}
+/**
+ * Decide whether one tool is visible for a permission context.
+ *
+ * An absent context is a denial: disclosure happens before execution, so an
+ * unresolved permission tree must withhold the surface rather than expose it.
+ * Unknown tool names are denied too; the coordinator rejects them at construction,
+ * and this function keeps the same fail-closed answer if one reaches it anyway.
+ *
+ * @param name - model-facing tool name.
+ * @param context - the caller's review context, or undefined while it is unavailable.
+ * @returns the decision and the requirements the context did not satisfy.
+ */
+export declare function decideToolAccess(name: string, context: ManagementContext | undefined): ToolAccessDecision;
+/** One withheld tool and the requirements that withheld it. */
+export interface ToolDenial {
+    readonly name: string;
+    readonly group?: KnowledgeToolGroup;
+    readonly missing: readonly string[];
+}
+/** The disclosure state after one pass. */
+export interface ToolDisclosureSnapshot {
+    /** Tool names registered after this pass, in definition order. */
+    readonly registered: readonly string[];
+    /** Tools withheld from the model, with the unsatisfied requirement per tool. */
+    readonly denied: readonly ToolDenial[];
+    /** Groups that currently have at least one registered tool. */
+    readonly activeGroups: readonly KnowledgeToolGroup[];
+    /** Set when the permission context could not be resolved; every tool is disposed. */
+    readonly error?: string;
+}
+/** The tool registry seam this coordinator needs. */
+export interface ToolRegistryLike {
+    /** Register one tool; returns the exact disposer that unregisters it. */
+    register(definition: ToolDefinition): () => void;
+}
+/** Construction options for a {@link ToolDisclosureCoordinator}. */
+export interface ToolDisclosureOptions {
+    /** Every model-facing tool this plugin can register. */
+    readonly tools: readonly ToolDefinition[];
+    /** The host registry to register into and dispose from. */
+    readonly registry: ToolRegistryLike;
+    /**
+     * Resolve the caller's current review context. Called on an explicit refresh,
+     * never from a tool's `execute()`.
+     */
+    readonly resolveContext: () => Promise<ManagementContext>;
+    /** Diagnostic sink; a failed refresh is reported here instead of thrown. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Register and dispose knowledge-base tools as the caller's permission context changes.
+ *
+ * The coordinator owns every tool registration. A pass computes one decision per
+ * tool, registers the newly allowed ones, disposes the newly denied ones and
+ * leaves unchanged tools untouched, so an unchanged context causes no registry
+ * churn. Concurrent refreshes share one in-flight context read; a pass that is
+ * superseded by a newer context never applies its stale answer.
+ *
+ * On a context-resolution failure every gated tool is disposed. That is the
+ * fail-closed direction: an unavailable permission tree cannot prove a capability,
+ * and a tool surface that outlives its proof is exactly the leak disclosure exists
+ * to prevent.
+ */
+export declare class ToolDisclosureCoordinator {
+    private readonly definitions;
+    /** Registered tools and their exact registry disposers. */
+    private readonly disposers;
+    private readonly options;
+    /** Monotonic pass counter; a slower older read must not overwrite a newer one. */
+    private generation;
+    private inFlight?;
+    private disposed;
+    private snapshot?;
+    constructor(options: ToolDisclosureOptions);
+    /** Tool names currently registered, in definition order. */
+    get registeredTools(): readonly string[];
+    /** The most recent disclosure pass, if one has completed. */
+    get lastSnapshot(): ToolDisclosureSnapshot | undefined;
+    /**
+     * Recompute the tool surface.
+     *
+     * @param context - a context already read by the caller (a route gate or status
+     *   request). Passing it avoids a second backend round trip. Omit it to resolve
+     *   one through {@link ToolDisclosureOptions.resolveContext}.
+     * @returns the resulting snapshot; a context failure is reported in `error`
+     *   rather than thrown, because a refresh must never fail the request that
+     *   triggered it.
+     */
+    syncToolDisclosure(context?: ManagementContext): Promise<ToolDisclosureSnapshot>;
+    /** Dispose every tool this coordinator registered; later refreshes are no-ops. */
+    dispose(): void;
+    /** Register allowed tools and dispose denied ones for one resolved context. */
+    private apply;
+    /** Dispose everything and report why the surface is empty. */
+    private fail;
+    /** Dispose every registered tool; safe to call more than once. */
+    private disposeRegistered;
+    /** Snapshot for a pass that cannot run at all. */
+    private emptySnapshot;
+}
+/**
+ * Build a coordinator.
+ *
+ * @param options - the definitions, registry, context resolver and log sink.
+ * @returns the coordinator the plugin stores and refreshes.
+ */
+export declare function createToolDisclosure(options: ToolDisclosureOptions): ToolDisclosureCoordinator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-knowledge-base",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "DataOps-backed knowledge base for DeepSeek Harness: a left-sidebar destination, Settings configuration, and index tooling over a mounted NAS view.",
   "type": "module",
   "main": "./lib/index.js",
@@ -48,6 +48,11 @@
     "skills/**/SKILL.md",
     "skills/**/i18n/*.json"
   ],
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
+    "bundle": "tsdown",
+    "prepack": "pnpm run build"
+  },
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
@@ -103,9 +108,5 @@
     "dsh-better-sidebar": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
-    "bundle": "tsdown"
   }
-}
+}