@iris-mcp/admin 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +242 -0
- package/LICENSE +21 -0
- package/README.md +1030 -2
- package/dist/index.d.ts +11 -0
- package/dist/index.js +33 -0
- package/dist/prompts/auditSecurityPosture.d.ts +12 -0
- package/dist/prompts/auditSecurityPosture.js +52 -0
- package/dist/prompts/index.d.ts +12 -0
- package/dist/prompts/index.js +16 -0
- package/dist/prompts/provisionProjectEnvironment.d.ts +11 -0
- package/dist/prompts/provisionProjectEnvironment.js +48 -0
- package/dist/tools/audit.d.ts +42 -0
- package/dist/tools/audit.js +394 -0
- package/dist/tools/database.d.ts +14 -0
- package/dist/tools/database.js +179 -0
- package/dist/tools/index.d.ts +12 -0
- package/dist/tools/index.js +52 -0
- package/dist/tools/ldap.d.ts +33 -0
- package/dist/tools/ldap.js +252 -0
- package/dist/tools/mapping.d.ts +15 -0
- package/dist/tools/mapping.js +175 -0
- package/dist/tools/namespace.d.ts +14 -0
- package/dist/tools/namespace.js +145 -0
- package/dist/tools/oauth.d.ts +17 -0
- package/dist/tools/oauth.js +269 -0
- package/dist/tools/permission.d.ts +13 -0
- package/dist/tools/permission.js +70 -0
- package/dist/tools/presets.d.ts +20 -0
- package/dist/tools/presets.js +84 -0
- package/dist/tools/resource.d.ts +81 -0
- package/dist/tools/resource.js +402 -0
- package/dist/tools/role.d.ts +14 -0
- package/dist/tools/role.js +139 -0
- package/dist/tools/service.d.ts +19 -0
- package/dist/tools/service.js +199 -0
- package/dist/tools/ssl.d.ts +14 -0
- package/dist/tools/ssl.js +201 -0
- package/dist/tools/user.d.ts +20 -0
- package/dist/tools/user.js +326 -0
- package/dist/tools/webapp.d.ts +20 -0
- package/dist/tools/webapp.js +268 -0
- package/dist/tools/x509.d.ts +42 -0
- package/dist/tools/x509.js +224 -0
- package/package.json +58 -3
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Permission check tool for the IRIS Administration MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Provides a single tool for checking whether a user or role has specific
|
|
5
|
+
* permissions on a resource:
|
|
6
|
+
* - {@link permissionCheckTool} — Check permission for a user/role on a resource
|
|
7
|
+
*
|
|
8
|
+
* Calls the custom REST service at `/api/executemcp/v2/security/permission`.
|
|
9
|
+
* Operations execute in %SYS namespace on the IRIS server.
|
|
10
|
+
*/
|
|
11
|
+
import { IrisApiError } from "@iris-mcp/shared";
|
|
12
|
+
import { z } from "zod";
|
|
13
|
+
/** Base URL for the custom ExecuteMCPv2 REST service. */
|
|
14
|
+
const BASE_URL = "/api/executemcp/v2";
|
|
15
|
+
// ── iris_permission_check ──────────────────────────────────────
|
|
16
|
+
export const permissionCheckTool = {
|
|
17
|
+
name: "iris_permission_check",
|
|
18
|
+
title: "Check Permission",
|
|
19
|
+
description: "Check whether an IRIS user or role has a specific permission on a resource. " +
|
|
20
|
+
"Returns whether the permission is granted and the actual granted permission level. " +
|
|
21
|
+
"The target is auto-detected as a user or role based on what exists in the system.",
|
|
22
|
+
inputSchema: z.object({
|
|
23
|
+
target: z
|
|
24
|
+
.string()
|
|
25
|
+
.describe("Username or role name to check permissions for (e.g., '_SYSTEM', '%Developer')"),
|
|
26
|
+
resource: z
|
|
27
|
+
.string()
|
|
28
|
+
.describe("Resource name to check permissions on (e.g., '%DB_USER', '%Development')"),
|
|
29
|
+
permission: z
|
|
30
|
+
.string()
|
|
31
|
+
.describe("Permission to check (e.g., 'R', 'W', 'U', 'RW', 'RWU')"),
|
|
32
|
+
}),
|
|
33
|
+
annotations: {
|
|
34
|
+
readOnlyHint: true,
|
|
35
|
+
destructiveHint: false,
|
|
36
|
+
idempotentHint: true,
|
|
37
|
+
openWorldHint: false,
|
|
38
|
+
},
|
|
39
|
+
scope: "SYS",
|
|
40
|
+
handler: async (args, ctx) => {
|
|
41
|
+
const { target, resource, permission } = args;
|
|
42
|
+
const body = { target, resource, permission };
|
|
43
|
+
const path = `${BASE_URL}/security/permission`;
|
|
44
|
+
try {
|
|
45
|
+
const response = await ctx.http.post(path, body);
|
|
46
|
+
const result = response.result;
|
|
47
|
+
return {
|
|
48
|
+
content: [
|
|
49
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
50
|
+
],
|
|
51
|
+
structuredContent: result,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
catch (error) {
|
|
55
|
+
if (error instanceof IrisApiError) {
|
|
56
|
+
return {
|
|
57
|
+
content: [
|
|
58
|
+
{
|
|
59
|
+
type: "text",
|
|
60
|
+
text: `Error checking permission for '${target}' on '${resource}': ${error.message}`,
|
|
61
|
+
},
|
|
62
|
+
],
|
|
63
|
+
isError: true,
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
throw error;
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
};
|
|
70
|
+
//# sourceMappingURL=permission.js.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool visibility preset rosters for iris-admin-mcp (Epic 30, architecture
|
|
3
|
+
* decision I2; Story 30.1). Transcribed EXACTLY from the product-owner-
|
|
4
|
+
* approved spec §2.5 table (approved 2026-07-12 — "implement as written").
|
|
5
|
+
*
|
|
6
|
+
* `core` = the everyday admin loop (namespaces, databases, users, webapps,
|
|
7
|
+
* permission checks) — 12 package tools = 13 runtime (+ `iris_server_profiles`).
|
|
8
|
+
* `developer` = only what devs self-serve (namespace/db/mapping/webapp
|
|
9
|
+
* config) — no user/security administration — 10 package tools.
|
|
10
|
+
*
|
|
11
|
+
* `include ∪ exclude` MUST equal the package's full 26-tool set for both
|
|
12
|
+
* presets — enforced at `McpServerBase` construction by `assertPresetCoverage`
|
|
13
|
+
* (see `index.ts`) and at test time by `presets.test.ts`.
|
|
14
|
+
*
|
|
15
|
+
* [Source: research/feature-specs/11-tool-visibility-presets.md#2.5 "iris-admin-mcp"]
|
|
16
|
+
*/
|
|
17
|
+
import type { ToolPresetRosters } from "@iris-mcp/shared";
|
|
18
|
+
/** admin-mcp's `core`/`developer` visibility rosters (§2.5). */
|
|
19
|
+
export declare const toolPresets: ToolPresetRosters;
|
|
20
|
+
//# sourceMappingURL=presets.d.ts.map
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool visibility preset rosters for iris-admin-mcp (Epic 30, architecture
|
|
3
|
+
* decision I2; Story 30.1). Transcribed EXACTLY from the product-owner-
|
|
4
|
+
* approved spec §2.5 table (approved 2026-07-12 — "implement as written").
|
|
5
|
+
*
|
|
6
|
+
* `core` = the everyday admin loop (namespaces, databases, users, webapps,
|
|
7
|
+
* permission checks) — 12 package tools = 13 runtime (+ `iris_server_profiles`).
|
|
8
|
+
* `developer` = only what devs self-serve (namespace/db/mapping/webapp
|
|
9
|
+
* config) — no user/security administration — 10 package tools.
|
|
10
|
+
*
|
|
11
|
+
* `include ∪ exclude` MUST equal the package's full 26-tool set for both
|
|
12
|
+
* presets — enforced at `McpServerBase` construction by `assertPresetCoverage`
|
|
13
|
+
* (see `index.ts`) and at test time by `presets.test.ts`.
|
|
14
|
+
*
|
|
15
|
+
* [Source: research/feature-specs/11-tool-visibility-presets.md#2.5 "iris-admin-mcp"]
|
|
16
|
+
*/
|
|
17
|
+
/** admin-mcp's `core`/`developer` visibility rosters (§2.5). */
|
|
18
|
+
export const toolPresets = {
|
|
19
|
+
core: {
|
|
20
|
+
include: [
|
|
21
|
+
"iris_namespace_manage",
|
|
22
|
+
"iris_namespace_list",
|
|
23
|
+
"iris_database_manage",
|
|
24
|
+
"iris_database_list",
|
|
25
|
+
"iris_user_manage",
|
|
26
|
+
"iris_user_get",
|
|
27
|
+
"iris_user_roles",
|
|
28
|
+
"iris_user_password",
|
|
29
|
+
"iris_role_list",
|
|
30
|
+
"iris_permission_check",
|
|
31
|
+
"iris_webapp_manage",
|
|
32
|
+
"iris_webapp_list",
|
|
33
|
+
],
|
|
34
|
+
exclude: [
|
|
35
|
+
"iris_mapping_manage",
|
|
36
|
+
"iris_mapping_list",
|
|
37
|
+
"iris_role_manage",
|
|
38
|
+
"iris_resource_manage",
|
|
39
|
+
"iris_resource_list",
|
|
40
|
+
"iris_webapp_get",
|
|
41
|
+
"iris_ssl_manage",
|
|
42
|
+
"iris_ssl_list",
|
|
43
|
+
"iris_oauth_manage",
|
|
44
|
+
"iris_oauth_list",
|
|
45
|
+
"iris_service_manage",
|
|
46
|
+
"iris_ldap_manage",
|
|
47
|
+
"iris_x509_manage",
|
|
48
|
+
"iris_audit_manage",
|
|
49
|
+
],
|
|
50
|
+
},
|
|
51
|
+
developer: {
|
|
52
|
+
include: [
|
|
53
|
+
"iris_namespace_manage",
|
|
54
|
+
"iris_namespace_list",
|
|
55
|
+
"iris_database_manage",
|
|
56
|
+
"iris_database_list",
|
|
57
|
+
"iris_mapping_manage",
|
|
58
|
+
"iris_mapping_list",
|
|
59
|
+
"iris_permission_check",
|
|
60
|
+
"iris_webapp_manage",
|
|
61
|
+
"iris_webapp_get",
|
|
62
|
+
"iris_webapp_list",
|
|
63
|
+
],
|
|
64
|
+
exclude: [
|
|
65
|
+
"iris_user_manage",
|
|
66
|
+
"iris_user_get",
|
|
67
|
+
"iris_user_roles",
|
|
68
|
+
"iris_user_password",
|
|
69
|
+
"iris_role_manage",
|
|
70
|
+
"iris_role_list",
|
|
71
|
+
"iris_resource_manage",
|
|
72
|
+
"iris_resource_list",
|
|
73
|
+
"iris_ssl_manage",
|
|
74
|
+
"iris_ssl_list",
|
|
75
|
+
"iris_oauth_manage",
|
|
76
|
+
"iris_oauth_list",
|
|
77
|
+
"iris_service_manage",
|
|
78
|
+
"iris_ldap_manage",
|
|
79
|
+
"iris_x509_manage",
|
|
80
|
+
"iris_audit_manage",
|
|
81
|
+
],
|
|
82
|
+
},
|
|
83
|
+
};
|
|
84
|
+
//# sourceMappingURL=presets.js.map
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resource management tools for the IRIS Administration MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Provides two tools for managing IRIS security resources via the custom REST endpoint:
|
|
5
|
+
* - {@link resourceManageTool} — Create, modify, or delete a security resource;
|
|
6
|
+
* AND (Story 15.5, additive) grant/revoke/list SQL object privileges
|
|
7
|
+
* (schema / table / column level).
|
|
8
|
+
* - {@link resourceListTool} — List all security resources
|
|
9
|
+
*
|
|
10
|
+
* The resource (create/modify/delete) actions call the custom REST service at
|
|
11
|
+
* `/api/executemcp/v2/security/resource` and execute in %SYS. The SQL-privilege
|
|
12
|
+
* actions (grant/revoke/listPrivileges, Story 15.5) call
|
|
13
|
+
* `/api/executemcp/v2/security/sqlprivilege` and execute in the TARGET namespace
|
|
14
|
+
* (SQL privileges are namespace-scoped).
|
|
15
|
+
*
|
|
16
|
+
* **Governed-write extension (Epic 15, Story 15.5).** The original resource
|
|
17
|
+
* actions (create/delete/modify) are pre-existing Epic-14 baseline keys and
|
|
18
|
+
* remain grandfathered-enabled — their parameters, defaults, and output shapes
|
|
19
|
+
* are UNCHANGED. The NEW SQL-privilege actions are classified via `mutates`:
|
|
20
|
+
* `grant`/`revoke` are writes (default-DISABLED until enabled via
|
|
21
|
+
* IRIS_GOVERNANCE) and `listPrivileges` is a read (enabled by default).
|
|
22
|
+
*
|
|
23
|
+
* **`listPrivileges` bounding (Story 35.4, additive parameters only — E-1: no
|
|
24
|
+
* new tool, no new action key).** `listPrivileges` was unbounded: a grantee
|
|
25
|
+
* holding `%All` (e.g. `_SYSTEM`) returned 15,341 rows / 2,900,478 characters
|
|
26
|
+
* live-measured 2026-08-17/18, exceeding the client transport limit. Two
|
|
27
|
+
* independent, additive fixes, both server-side in
|
|
28
|
+
* `ExecuteMCPv2.REST.Security:SqlPrivilegeList`:
|
|
29
|
+
* 1. `maxRows` (new optional param, default 100/max 1000, mirroring
|
|
30
|
+
* `iris_audit_manage:view`) stops the fetch loop from materializing rows
|
|
31
|
+
* past the cap — an OUTPUT bound, not a scan bound (see the handler's
|
|
32
|
+
* class-doc comment for the live timing that established this). A
|
|
33
|
+
* capped response carries `rowsCapped: true`; omitted when not capped,
|
|
34
|
+
* so an under-cap caller's shape is byte-identical to pre-35.4 (AC 35.4.5).
|
|
35
|
+
* 2. The `%All` short-circuit (Rule #6): every row whose
|
|
36
|
+
* `GRANTED_VIA = "SuperUser"` is omitted from `privileges` (that is the
|
|
37
|
+
* derived cross-product responsible for the 15,341-row blowup); any REAL
|
|
38
|
+
* non-derived grant is still enumerated. The decision is made per-ROW,
|
|
39
|
+
* off a value the query already computed — the handler never resolves
|
|
40
|
+
* the grantee's roles, so there is no role graph to walk incompletely
|
|
41
|
+
* and no principal-name matching to get wrong. An instance-wide sweep of
|
|
42
|
+
* all 46 users and roles (Story 35.4 code review) found `SuperUser` rows
|
|
43
|
+
* emitted if and only if the principal effectively holds `%All`, with
|
|
44
|
+
* powerful non-`%All` controls such as `Admin` returning 0 derived rows.
|
|
45
|
+
* A `reason` string and a `superUserPrivilegesOmitted` count are added
|
|
46
|
+
* ONLY when rows were actually omitted — a grantee with no derived rows
|
|
47
|
+
* is unaffected (verified live against the `%Developer` and `Admin`
|
|
48
|
+
* controls: byte-for-byte unchanged).
|
|
49
|
+
* `cursor` (new optional param) pages the tool-layer's already-bounded
|
|
50
|
+
* `privileges` array via `ctx.paginate`, following the `cursor` + `ctx.paginate`
|
|
51
|
+
* convention used by `audit.ts`/`database.ts`/`ldap.ts`/`mapping.ts`. Unlike
|
|
52
|
+
* `audit.ts`'s `view` handler (which rebuilds its result from only
|
|
53
|
+
* `events`/`count`/`nextCursor`, silently dropping any other wire field), this
|
|
54
|
+
* handler SPREADS the raw wire result before overriding `privileges`/`count`/
|
|
55
|
+
* `nextCursor`, so `rowsCapped`/`reason`/`superUserPrivilegesOmitted` survive
|
|
56
|
+
* into the tool's response — otherwise the truncation/short-circuit signal
|
|
57
|
+
* this story adds would be computed server-side and then thrown away here.
|
|
58
|
+
* `maxRows` is the ceiling on what the server returns at all; `cursor` pages
|
|
59
|
+
* WITHIN that ceiling at `DEFAULT_PAGE_SIZE` (50, `server-base.ts:83`). The
|
|
60
|
+
* two therefore interact, and the interaction is resolved DELIBERATELY here
|
|
61
|
+
* (`audit.ts` has the same latent one, undocumented):
|
|
62
|
+
* - Pagination is OPT-IN. A caller supplying neither `maxRows` nor `cursor`
|
|
63
|
+
* is not paginated at all and receives the raw wire result — required by
|
|
64
|
+
* AC 35.4.5, since `ctx.paginate`'s unconditional 50-row slice would
|
|
65
|
+
* otherwise silently truncate an under-cap caller holding 51-100
|
|
66
|
+
* privileges and hand them a `nextCursor` they never asked for.
|
|
67
|
+
* - Supplying either parameter opts in: pages are 50 rows, and `nextCursor`
|
|
68
|
+
* walks to the `maxRows` ceiling but never past it. To see rows beyond
|
|
69
|
+
* the ceiling, raise `maxRows`; to see rows 51..maxRows, page. Each page
|
|
70
|
+
* re-runs the server query and the cursor offset is positional, so the
|
|
71
|
+
* same `maxRows` must be resent with every `cursor`.
|
|
72
|
+
* - `maxRows` is itself clamped to 1000 server-side, so a grantee with more
|
|
73
|
+
* than 1000 REAL grants cannot be fully enumerated through this action.
|
|
74
|
+
* That is an accepted limit, not an oversight: the action exists to make
|
|
75
|
+
* privileged grantees inspectable, and the `%All` short-circuit removes
|
|
76
|
+
* the only known cause of counts that large.
|
|
77
|
+
*/
|
|
78
|
+
import { type ToolDefinition } from "@iris-mcp/shared";
|
|
79
|
+
export declare const resourceManageTool: ToolDefinition;
|
|
80
|
+
export declare const resourceListTool: ToolDefinition;
|
|
81
|
+
//# sourceMappingURL=resource.d.ts.map
|
|
@@ -0,0 +1,402 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resource management tools for the IRIS Administration MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Provides two tools for managing IRIS security resources via the custom REST endpoint:
|
|
5
|
+
* - {@link resourceManageTool} — Create, modify, or delete a security resource;
|
|
6
|
+
* AND (Story 15.5, additive) grant/revoke/list SQL object privileges
|
|
7
|
+
* (schema / table / column level).
|
|
8
|
+
* - {@link resourceListTool} — List all security resources
|
|
9
|
+
*
|
|
10
|
+
* The resource (create/modify/delete) actions call the custom REST service at
|
|
11
|
+
* `/api/executemcp/v2/security/resource` and execute in %SYS. The SQL-privilege
|
|
12
|
+
* actions (grant/revoke/listPrivileges, Story 15.5) call
|
|
13
|
+
* `/api/executemcp/v2/security/sqlprivilege` and execute in the TARGET namespace
|
|
14
|
+
* (SQL privileges are namespace-scoped).
|
|
15
|
+
*
|
|
16
|
+
* **Governed-write extension (Epic 15, Story 15.5).** The original resource
|
|
17
|
+
* actions (create/delete/modify) are pre-existing Epic-14 baseline keys and
|
|
18
|
+
* remain grandfathered-enabled — their parameters, defaults, and output shapes
|
|
19
|
+
* are UNCHANGED. The NEW SQL-privilege actions are classified via `mutates`:
|
|
20
|
+
* `grant`/`revoke` are writes (default-DISABLED until enabled via
|
|
21
|
+
* IRIS_GOVERNANCE) and `listPrivileges` is a read (enabled by default).
|
|
22
|
+
*
|
|
23
|
+
* **`listPrivileges` bounding (Story 35.4, additive parameters only — E-1: no
|
|
24
|
+
* new tool, no new action key).** `listPrivileges` was unbounded: a grantee
|
|
25
|
+
* holding `%All` (e.g. `_SYSTEM`) returned 15,341 rows / 2,900,478 characters
|
|
26
|
+
* live-measured 2026-08-17/18, exceeding the client transport limit. Two
|
|
27
|
+
* independent, additive fixes, both server-side in
|
|
28
|
+
* `ExecuteMCPv2.REST.Security:SqlPrivilegeList`:
|
|
29
|
+
* 1. `maxRows` (new optional param, default 100/max 1000, mirroring
|
|
30
|
+
* `iris_audit_manage:view`) stops the fetch loop from materializing rows
|
|
31
|
+
* past the cap — an OUTPUT bound, not a scan bound (see the handler's
|
|
32
|
+
* class-doc comment for the live timing that established this). A
|
|
33
|
+
* capped response carries `rowsCapped: true`; omitted when not capped,
|
|
34
|
+
* so an under-cap caller's shape is byte-identical to pre-35.4 (AC 35.4.5).
|
|
35
|
+
* 2. The `%All` short-circuit (Rule #6): every row whose
|
|
36
|
+
* `GRANTED_VIA = "SuperUser"` is omitted from `privileges` (that is the
|
|
37
|
+
* derived cross-product responsible for the 15,341-row blowup); any REAL
|
|
38
|
+
* non-derived grant is still enumerated. The decision is made per-ROW,
|
|
39
|
+
* off a value the query already computed — the handler never resolves
|
|
40
|
+
* the grantee's roles, so there is no role graph to walk incompletely
|
|
41
|
+
* and no principal-name matching to get wrong. An instance-wide sweep of
|
|
42
|
+
* all 46 users and roles (Story 35.4 code review) found `SuperUser` rows
|
|
43
|
+
* emitted if and only if the principal effectively holds `%All`, with
|
|
44
|
+
* powerful non-`%All` controls such as `Admin` returning 0 derived rows.
|
|
45
|
+
* A `reason` string and a `superUserPrivilegesOmitted` count are added
|
|
46
|
+
* ONLY when rows were actually omitted — a grantee with no derived rows
|
|
47
|
+
* is unaffected (verified live against the `%Developer` and `Admin`
|
|
48
|
+
* controls: byte-for-byte unchanged).
|
|
49
|
+
* `cursor` (new optional param) pages the tool-layer's already-bounded
|
|
50
|
+
* `privileges` array via `ctx.paginate`, following the `cursor` + `ctx.paginate`
|
|
51
|
+
* convention used by `audit.ts`/`database.ts`/`ldap.ts`/`mapping.ts`. Unlike
|
|
52
|
+
* `audit.ts`'s `view` handler (which rebuilds its result from only
|
|
53
|
+
* `events`/`count`/`nextCursor`, silently dropping any other wire field), this
|
|
54
|
+
* handler SPREADS the raw wire result before overriding `privileges`/`count`/
|
|
55
|
+
* `nextCursor`, so `rowsCapped`/`reason`/`superUserPrivilegesOmitted` survive
|
|
56
|
+
* into the tool's response — otherwise the truncation/short-circuit signal
|
|
57
|
+
* this story adds would be computed server-side and then thrown away here.
|
|
58
|
+
* `maxRows` is the ceiling on what the server returns at all; `cursor` pages
|
|
59
|
+
* WITHIN that ceiling at `DEFAULT_PAGE_SIZE` (50, `server-base.ts:83`). The
|
|
60
|
+
* two therefore interact, and the interaction is resolved DELIBERATELY here
|
|
61
|
+
* (`audit.ts` has the same latent one, undocumented):
|
|
62
|
+
* - Pagination is OPT-IN. A caller supplying neither `maxRows` nor `cursor`
|
|
63
|
+
* is not paginated at all and receives the raw wire result — required by
|
|
64
|
+
* AC 35.4.5, since `ctx.paginate`'s unconditional 50-row slice would
|
|
65
|
+
* otherwise silently truncate an under-cap caller holding 51-100
|
|
66
|
+
* privileges and hand them a `nextCursor` they never asked for.
|
|
67
|
+
* - Supplying either parameter opts in: pages are 50 rows, and `nextCursor`
|
|
68
|
+
* walks to the `maxRows` ceiling but never past it. To see rows beyond
|
|
69
|
+
* the ceiling, raise `maxRows`; to see rows 51..maxRows, page. Each page
|
|
70
|
+
* re-runs the server query and the cursor offset is positional, so the
|
|
71
|
+
* same `maxRows` must be resent with every `cursor`.
|
|
72
|
+
* - `maxRows` is itself clamped to 1000 server-side, so a grantee with more
|
|
73
|
+
* than 1000 REAL grants cannot be fully enumerated through this action.
|
|
74
|
+
* That is an accepted limit, not an oversight: the action exists to make
|
|
75
|
+
* privileged grantees inspectable, and the `%All` short-circuit removes
|
|
76
|
+
* the only known cause of counts that large.
|
|
77
|
+
*/
|
|
78
|
+
import { booleanParam, IrisApiError } from "@iris-mcp/shared";
|
|
79
|
+
import { z } from "zod";
|
|
80
|
+
/** Base URL for the custom ExecuteMCPv2 REST service. */
|
|
81
|
+
const BASE_URL = "/api/executemcp/v2";
|
|
82
|
+
// ── iris_resource_manage ───────────────────────────────────────
|
|
83
|
+
export const resourceManageTool = {
|
|
84
|
+
name: "iris_resource_manage",
|
|
85
|
+
title: "Manage Resource",
|
|
86
|
+
description: "Create, modify, or delete an IRIS security resource. For 'create', name is required. " +
|
|
87
|
+
"For 'modify', only provided fields are updated. For 'delete', only the name is needed. " +
|
|
88
|
+
"ALSO manages fine-grained SQL object privileges (additive, Story 15.5): " +
|
|
89
|
+
"'grant'/'revoke' a SQL privilege at schema, table, or column level, and " +
|
|
90
|
+
"'listPrivileges' to list the current grants for a user or role. For the " +
|
|
91
|
+
"SQL-privilege actions supply 'grantee' (a SQL user or role); grant/revoke " +
|
|
92
|
+
"also take 'target' (a schema, 'schema.table', or 'schema.table(col1,col2)' " +
|
|
93
|
+
"for column level) and 'privilege' (one or more of " +
|
|
94
|
+
"SELECT,INSERT,UPDATE,DELETE,REFERENCES - comma-delimited, or '*' for all). " +
|
|
95
|
+
"listPrivileges takes a 'target' of the form 'schema.table' (a column-level " +
|
|
96
|
+
"listing) or no target (an object-level listing); a bare schema name or a " +
|
|
97
|
+
"'schema.' / '.table' fragment is rejected with a validation message. " +
|
|
98
|
+
"listPrivileges also takes 'system' (default false): true includes " +
|
|
99
|
+
"system tables, which lists far more rows. SQL privileges are namespace-scoped - " +
|
|
100
|
+
"pass 'namespace' to target a non-default namespace. The grant/revoke actions " +
|
|
101
|
+
"are opt-in under tool governance and disabled by default until enabled via " +
|
|
102
|
+
"IRIS_GOVERNANCE; listPrivileges is a read and enabled by default. " +
|
|
103
|
+
"'listPrivileges' accepts 'maxRows' (default 100, max 1000 — values above " +
|
|
104
|
+
"1000 are clamped) and 'cursor'. 'maxRows' bounds OUTPUT only: the server " +
|
|
105
|
+
"stops pumping its result cursor at the cap, so rows past it are never " +
|
|
106
|
+
"materialized, but the underlying privilege computation is NOT reduced — " +
|
|
107
|
+
"this is not timeout protection. A capped response carries " +
|
|
108
|
+
"'rowsCapped: true'. Pagination is opt-in: pass 'maxRows' or 'cursor' and " +
|
|
109
|
+
"the response is paged 50 rows at a time within the 'maxRows' ceiling " +
|
|
110
|
+
"(resend the SAME 'maxRows' with each 'cursor', since every page re-runs " +
|
|
111
|
+
"the query); pass neither and you get every row the server returned, " +
|
|
112
|
+
"unpaged. The cursor cannot cross the 'maxRows' ceiling, and 'maxRows' " +
|
|
113
|
+
"itself is capped at 1000, so a grantee with more than 1000 real grants " +
|
|
114
|
+
"cannot be fully enumerated through this action. A grantee holding the " +
|
|
115
|
+
"'%All' super-role (e.g. '_SYSTEM'), directly or through a nested role " +
|
|
116
|
+
"chain, has its derived (GRANTED_VIA=SuperUser) rows omitted " +
|
|
117
|
+
"automatically — a 'reason' field and a 'superUserPrivilegesOmitted' " +
|
|
118
|
+
"count appear when rows were actually omitted; any real, non-derived " +
|
|
119
|
+
"grant is still listed. The omission keys off each row's GRANTED_VIA " +
|
|
120
|
+
"value, so it holds however the grantee acquired '%All'.",
|
|
121
|
+
inputSchema: z.object({
|
|
122
|
+
action: z
|
|
123
|
+
.enum([
|
|
124
|
+
"create",
|
|
125
|
+
"modify",
|
|
126
|
+
"delete",
|
|
127
|
+
"grant",
|
|
128
|
+
"revoke",
|
|
129
|
+
"listPrivileges",
|
|
130
|
+
])
|
|
131
|
+
.describe("Action to perform on the resource or SQL privilege"),
|
|
132
|
+
name: z
|
|
133
|
+
.string()
|
|
134
|
+
.optional()
|
|
135
|
+
.describe("Resource name (e.g., 'MyDB', '%Development') — required for create/modify/delete"),
|
|
136
|
+
description: z
|
|
137
|
+
.string()
|
|
138
|
+
.optional()
|
|
139
|
+
.describe("Description of the resource"),
|
|
140
|
+
publicPermission: z
|
|
141
|
+
.string()
|
|
142
|
+
.optional()
|
|
143
|
+
.describe("Default public permission for the resource (e.g., '', 'R', 'RW', 'RWU')"),
|
|
144
|
+
// ── SQL-privilege fields (Story 15.5 — grant/revoke/listPrivileges) ──
|
|
145
|
+
target: z
|
|
146
|
+
.string()
|
|
147
|
+
.optional()
|
|
148
|
+
.describe("SQL privilege target. grant/revoke: a schema, 'schema.table', or " +
|
|
149
|
+
"'schema.table(col1,col2)' for column-level. listPrivileges: omit for an " +
|
|
150
|
+
"object-level listing, or pass 'schema.table' for a column-level listing " +
|
|
151
|
+
"(a bare schema is rejected)."),
|
|
152
|
+
privilege: z
|
|
153
|
+
.string()
|
|
154
|
+
.optional()
|
|
155
|
+
.describe("SQL privilege(s) for grant/revoke: one or more of " +
|
|
156
|
+
"SELECT,INSERT,UPDATE,DELETE,REFERENCES (comma-delimited) or '*' for all."),
|
|
157
|
+
grantee: z
|
|
158
|
+
.string()
|
|
159
|
+
.optional()
|
|
160
|
+
.describe("SQL user or role for grant/revoke/listPrivileges (the privilege holder)."),
|
|
161
|
+
namespace: z
|
|
162
|
+
.string()
|
|
163
|
+
.optional()
|
|
164
|
+
.describe("Target namespace for the SQL-privilege actions (privileges are " +
|
|
165
|
+
"namespace-scoped). Defaults to the connection's namespace."),
|
|
166
|
+
// -- listPrivileges (Story 38.0, DW-470) --
|
|
167
|
+
system: booleanParam
|
|
168
|
+
.optional()
|
|
169
|
+
.describe("listPrivileges only: include system tables in the listing (default false). " +
|
|
170
|
+
"Sent to IRIS explicitly as 1 or 0."),
|
|
171
|
+
// ── listPrivileges bounding (Story 35.4, additive) ──
|
|
172
|
+
maxRows: z
|
|
173
|
+
.number()
|
|
174
|
+
.int()
|
|
175
|
+
.positive()
|
|
176
|
+
.optional()
|
|
177
|
+
.describe("Max privilege rows for listPrivileges (default 100; values above " +
|
|
178
|
+
"1000 are clamped server-side). Bounds OUTPUT only, not the " +
|
|
179
|
+
"privilege scan — see the action description. Passing it also " +
|
|
180
|
+
"opts into 50-row pagination."),
|
|
181
|
+
cursor: z
|
|
182
|
+
.string()
|
|
183
|
+
.optional()
|
|
184
|
+
.describe("Pagination cursor from a previous listPrivileges response's " +
|
|
185
|
+
"nextCursor field. Pages 50 rows at a time within the maxRows " +
|
|
186
|
+
"ceiling; resend the same maxRows with it, because each page " +
|
|
187
|
+
"re-runs the server query and the offset is positional."),
|
|
188
|
+
}),
|
|
189
|
+
annotations: {
|
|
190
|
+
destructiveHint: true,
|
|
191
|
+
readOnlyHint: false,
|
|
192
|
+
idempotentHint: false,
|
|
193
|
+
openWorldHint: false,
|
|
194
|
+
},
|
|
195
|
+
scope: "SYS",
|
|
196
|
+
// Governance classification (Story 15.5). Only the NEW (non-baseline) actions
|
|
197
|
+
// are classified; create/delete/modify are pre-existing Epic-14 baseline keys
|
|
198
|
+
// and stay grandfathered-enabled (baseline membership wins in defaultSeed).
|
|
199
|
+
mutates: {
|
|
200
|
+
grant: "write",
|
|
201
|
+
revoke: "write",
|
|
202
|
+
listPrivileges: "read",
|
|
203
|
+
},
|
|
204
|
+
handler: async (args, ctx) => {
|
|
205
|
+
const { action, name, description, publicPermission, target, privilege, grantee, namespace, system, maxRows, cursor, } = args;
|
|
206
|
+
// ── SQL-privilege actions (Story 15.5) ─────────────────────────
|
|
207
|
+
if (action === "grant" || action === "revoke") {
|
|
208
|
+
const sqlPath = `${BASE_URL}/security/sqlprivilege`;
|
|
209
|
+
const body = { action };
|
|
210
|
+
if (target !== undefined)
|
|
211
|
+
body.target = target;
|
|
212
|
+
if (privilege !== undefined)
|
|
213
|
+
body.privilege = privilege;
|
|
214
|
+
if (grantee !== undefined)
|
|
215
|
+
body.grantee = grantee;
|
|
216
|
+
if (namespace !== undefined)
|
|
217
|
+
body.namespace = namespace;
|
|
218
|
+
try {
|
|
219
|
+
const response = await ctx.http.post(sqlPath, body);
|
|
220
|
+
const result = response.result;
|
|
221
|
+
return {
|
|
222
|
+
content: [
|
|
223
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
224
|
+
],
|
|
225
|
+
structuredContent: result,
|
|
226
|
+
};
|
|
227
|
+
}
|
|
228
|
+
catch (error) {
|
|
229
|
+
if (error instanceof IrisApiError) {
|
|
230
|
+
return {
|
|
231
|
+
content: [
|
|
232
|
+
{
|
|
233
|
+
type: "text",
|
|
234
|
+
text: `Error performing SQL privilege '${action}' on '${target ?? ""}': ${error.message}`,
|
|
235
|
+
},
|
|
236
|
+
],
|
|
237
|
+
isError: true,
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
throw error;
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
if (action === "listPrivileges") {
|
|
244
|
+
const qs = new URLSearchParams();
|
|
245
|
+
if (grantee !== undefined)
|
|
246
|
+
qs.set("grantee", grantee);
|
|
247
|
+
if (target !== undefined && target !== "")
|
|
248
|
+
qs.set("target", target);
|
|
249
|
+
if (namespace !== undefined && namespace !== "")
|
|
250
|
+
qs.set("namespace", namespace);
|
|
251
|
+
if (maxRows !== undefined)
|
|
252
|
+
qs.set("maxRows", String(maxRows));
|
|
253
|
+
// The documented default (false) goes on the wire explicitly. IRIS reads
|
|
254
|
+
// `system` numerically (`+"true"` is 0), so it must be 1 or 0, never "true".
|
|
255
|
+
qs.set("system", system === true ? "1" : "0");
|
|
256
|
+
const sqlPath = `${BASE_URL}/security/sqlprivilege?${qs.toString()}`;
|
|
257
|
+
try {
|
|
258
|
+
const response = await ctx.http.get(sqlPath);
|
|
259
|
+
const rawResult = response.result;
|
|
260
|
+
const allPrivileges = Array.isArray(rawResult?.privileges)
|
|
261
|
+
? rawResult.privileges
|
|
262
|
+
: [];
|
|
263
|
+
// Pagination is OPT-IN (AC 35.4.5). `ctx.paginate` slices at
|
|
264
|
+
// DEFAULT_PAGE_SIZE (50, `server-base.ts:83`) unconditionally, so
|
|
265
|
+
// applying it to every call would truncate a caller who passed
|
|
266
|
+
// NOTHING and whose grantee holds 51-100 privileges — they fit under
|
|
267
|
+
// the server's 100-row default cap, yet would silently receive 50
|
|
268
|
+
// rows, a `count` of 50, and a `nextCursor` they never asked for.
|
|
269
|
+
// That is exactly the population AC 35.4.5 protects, so a caller who
|
|
270
|
+
// supplies neither `maxRows` nor `cursor` gets the raw wire result
|
|
271
|
+
// untouched — byte-identical to the pre-35.4 shape. Supplying either
|
|
272
|
+
// one opts into the sibling `cursor`/`ctx.paginate` convention
|
|
273
|
+
// (`audit.ts`/`database.ts`/`ldap.ts`/`mapping.ts`), which is how a
|
|
274
|
+
// caller obtains the first `nextCursor` at all.
|
|
275
|
+
const paginationRequested = maxRows !== undefined || cursor !== undefined;
|
|
276
|
+
// Spread the raw wire result (grantee/level/target/rowsCapped/reason/
|
|
277
|
+
// superUserPrivilegesOmitted) rather than rebuilding from scratch, so
|
|
278
|
+
// the server-side truncation/short-circuit signal this story adds
|
|
279
|
+
// survives into the tool response — see the module doc comment.
|
|
280
|
+
let result;
|
|
281
|
+
if (paginationRequested) {
|
|
282
|
+
const { page, nextCursor } = ctx.paginate(allPrivileges, cursor);
|
|
283
|
+
result = {
|
|
284
|
+
...rawResult,
|
|
285
|
+
privileges: page,
|
|
286
|
+
count: page.length,
|
|
287
|
+
...(nextCursor ? { nextCursor } : {}),
|
|
288
|
+
};
|
|
289
|
+
}
|
|
290
|
+
else {
|
|
291
|
+
result = { ...rawResult, privileges: allPrivileges };
|
|
292
|
+
}
|
|
293
|
+
return {
|
|
294
|
+
content: [
|
|
295
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
296
|
+
],
|
|
297
|
+
structuredContent: result,
|
|
298
|
+
};
|
|
299
|
+
}
|
|
300
|
+
catch (error) {
|
|
301
|
+
if (error instanceof IrisApiError) {
|
|
302
|
+
return {
|
|
303
|
+
content: [
|
|
304
|
+
{
|
|
305
|
+
type: "text",
|
|
306
|
+
text: `Error listing SQL privileges for '${grantee ?? ""}': ${error.message}`,
|
|
307
|
+
},
|
|
308
|
+
],
|
|
309
|
+
isError: true,
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
throw error;
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
// ── Resource actions (create/modify/delete) — UNCHANGED (AC 15.5.6) ──
|
|
316
|
+
const body = { action, name: name ?? "" };
|
|
317
|
+
if (description !== undefined)
|
|
318
|
+
body.description = description;
|
|
319
|
+
if (publicPermission !== undefined)
|
|
320
|
+
body.publicPermission = publicPermission;
|
|
321
|
+
const path = `${BASE_URL}/security/resource`;
|
|
322
|
+
try {
|
|
323
|
+
const response = await ctx.http.post(path, body);
|
|
324
|
+
const result = response.result;
|
|
325
|
+
return {
|
|
326
|
+
content: [
|
|
327
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
328
|
+
],
|
|
329
|
+
structuredContent: result,
|
|
330
|
+
};
|
|
331
|
+
}
|
|
332
|
+
catch (error) {
|
|
333
|
+
if (error instanceof IrisApiError) {
|
|
334
|
+
return {
|
|
335
|
+
content: [
|
|
336
|
+
{
|
|
337
|
+
type: "text",
|
|
338
|
+
text: `Error managing resource '${name}': ${error.message}`,
|
|
339
|
+
},
|
|
340
|
+
],
|
|
341
|
+
isError: true,
|
|
342
|
+
};
|
|
343
|
+
}
|
|
344
|
+
throw error;
|
|
345
|
+
}
|
|
346
|
+
},
|
|
347
|
+
};
|
|
348
|
+
// ── iris_resource_list ─────────────────────────────────────────
|
|
349
|
+
export const resourceListTool = {
|
|
350
|
+
name: "iris_resource_list",
|
|
351
|
+
title: "List Resources",
|
|
352
|
+
description: "List all IRIS security resources with their description, public permission, and type.",
|
|
353
|
+
inputSchema: z.object({
|
|
354
|
+
cursor: z
|
|
355
|
+
.string()
|
|
356
|
+
.optional()
|
|
357
|
+
.describe("Pagination cursor from a previous response's nextCursor field"),
|
|
358
|
+
}),
|
|
359
|
+
annotations: {
|
|
360
|
+
readOnlyHint: true,
|
|
361
|
+
destructiveHint: false,
|
|
362
|
+
idempotentHint: true,
|
|
363
|
+
openWorldHint: false,
|
|
364
|
+
},
|
|
365
|
+
scope: "SYS",
|
|
366
|
+
handler: async (args, ctx) => {
|
|
367
|
+
const { cursor } = args;
|
|
368
|
+
const path = `${BASE_URL}/security/resource`;
|
|
369
|
+
try {
|
|
370
|
+
const response = await ctx.http.get(path);
|
|
371
|
+
const rawResult = response.result;
|
|
372
|
+
const allResources = Array.isArray(rawResult) ? rawResult : [];
|
|
373
|
+
const { page, nextCursor } = ctx.paginate(allResources, cursor);
|
|
374
|
+
const result = {
|
|
375
|
+
resources: page,
|
|
376
|
+
count: page.length,
|
|
377
|
+
...(nextCursor ? { nextCursor } : {}),
|
|
378
|
+
};
|
|
379
|
+
return {
|
|
380
|
+
content: [
|
|
381
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
382
|
+
],
|
|
383
|
+
structuredContent: result,
|
|
384
|
+
};
|
|
385
|
+
}
|
|
386
|
+
catch (error) {
|
|
387
|
+
if (error instanceof IrisApiError) {
|
|
388
|
+
return {
|
|
389
|
+
content: [
|
|
390
|
+
{
|
|
391
|
+
type: "text",
|
|
392
|
+
text: `Error listing resources: ${error.message}`,
|
|
393
|
+
},
|
|
394
|
+
],
|
|
395
|
+
isError: true,
|
|
396
|
+
};
|
|
397
|
+
}
|
|
398
|
+
throw error;
|
|
399
|
+
}
|
|
400
|
+
},
|
|
401
|
+
};
|
|
402
|
+
//# sourceMappingURL=resource.js.map
|