@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.
Files changed (44) hide show
  1. package/CHANGELOG.md +242 -0
  2. package/LICENSE +21 -0
  3. package/README.md +1030 -2
  4. package/dist/index.d.ts +11 -0
  5. package/dist/index.js +33 -0
  6. package/dist/prompts/auditSecurityPosture.d.ts +12 -0
  7. package/dist/prompts/auditSecurityPosture.js +52 -0
  8. package/dist/prompts/index.d.ts +12 -0
  9. package/dist/prompts/index.js +16 -0
  10. package/dist/prompts/provisionProjectEnvironment.d.ts +11 -0
  11. package/dist/prompts/provisionProjectEnvironment.js +48 -0
  12. package/dist/tools/audit.d.ts +42 -0
  13. package/dist/tools/audit.js +394 -0
  14. package/dist/tools/database.d.ts +14 -0
  15. package/dist/tools/database.js +179 -0
  16. package/dist/tools/index.d.ts +12 -0
  17. package/dist/tools/index.js +52 -0
  18. package/dist/tools/ldap.d.ts +33 -0
  19. package/dist/tools/ldap.js +252 -0
  20. package/dist/tools/mapping.d.ts +15 -0
  21. package/dist/tools/mapping.js +175 -0
  22. package/dist/tools/namespace.d.ts +14 -0
  23. package/dist/tools/namespace.js +145 -0
  24. package/dist/tools/oauth.d.ts +17 -0
  25. package/dist/tools/oauth.js +269 -0
  26. package/dist/tools/permission.d.ts +13 -0
  27. package/dist/tools/permission.js +70 -0
  28. package/dist/tools/presets.d.ts +20 -0
  29. package/dist/tools/presets.js +84 -0
  30. package/dist/tools/resource.d.ts +81 -0
  31. package/dist/tools/resource.js +402 -0
  32. package/dist/tools/role.d.ts +14 -0
  33. package/dist/tools/role.js +139 -0
  34. package/dist/tools/service.d.ts +19 -0
  35. package/dist/tools/service.js +199 -0
  36. package/dist/tools/ssl.d.ts +14 -0
  37. package/dist/tools/ssl.js +201 -0
  38. package/dist/tools/user.d.ts +20 -0
  39. package/dist/tools/user.js +326 -0
  40. package/dist/tools/webapp.d.ts +20 -0
  41. package/dist/tools/webapp.js +268 -0
  42. package/dist/tools/x509.d.ts +42 -0
  43. package/dist/tools/x509.js +224 -0
  44. package/package.json +58 -3
@@ -0,0 +1,224 @@
1
+ /**
2
+ * IRIS X.509 certificate-credentials tool for the IRIS Administration MCP
3
+ * server.
4
+ *
5
+ * Provides {@link x509ManageTool} — a single multi-action tool to list,
6
+ * inspect, import, and delete X.509 certificate credentials
7
+ * (`%SYS.X509Credentials`) via the custom REST endpoint
8
+ * `/api/executemcp/v2/security/x509`. Operations execute in the `%SYS`
9
+ * namespace on the IRIS server.
10
+ *
11
+ * **Governed write tool (Epic 15, Story 15.3).** The `mutates` classification
12
+ * map classifies all four actions: `list`/`get` are reads (enabled by default),
13
+ * while `import`/`delete` are writes that the governance layer
14
+ * default-DISABLES until an operator opts in via `IRIS_GOVERNANCE`. The tool
15
+ * does NOT declare a `server` field — the framework injects it (architecture
16
+ * decision D2).
17
+ *
18
+ * **SECURITY-CRITICAL — NO private-key material in output (AC 15.3.3):**
19
+ * `%SYS.X509Credentials` holds private-key material (`PrivateKey`,
20
+ * `PrivateKeyPassword`, and the `*Export` variants). `list`/`get` return ONLY
21
+ * public metadata: the alias, a `hasPrivateKey` boolean, and safe public
22
+ * certificate fields (subject/issuer/serial/thumbprint/subjectKeyIdentifier/
23
+ * notBefore/notAfter). They MUST NEVER return the private key in any form. The
24
+ * exclusion is enforced in BOTH the ObjectScript handler (which never reads the
25
+ * secret properties into its output) and this output mapping (which only ever
26
+ * forwards the server's already-private-key-free envelope). A deep-scan unit
27
+ * test asserts no private-key-shaped field appears at any depth of the output.
28
+ *
29
+ * **`import` mechanism (AC 15.3.4, Rule #16 live probe):** the native
30
+ * `%SYS.X509Credentials.Import(FileName, .NumImported, Flags)` reads a
31
+ * server-side XML *export* file — not agent-friendly for importing a single
32
+ * certificate. The class DOES support constructing a credential from a
33
+ * base64-encoded certificate (DER or PEM) + `Save` (mirroring what
34
+ * `LoadCertificate` does internally: base64-decode → `Certificate` setter,
35
+ * which auto-derives Thumbprint/Subject/Issuer/Serial/SubjectKeyIdentifier). So
36
+ * `import` accepts a base64 `certificate` (required) and an OPTIONAL,
37
+ * write-only base64 `privateKey` (+ optional `privateKeyPassword`). The private
38
+ * key is accepted IN only — it is never echoed back in the import response.
39
+ */
40
+ import { IrisApiError } from "@iris-mcp/shared";
41
+ import { z } from "zod";
42
+ /** Base URL for the custom ExecuteMCPv2 REST service. */
43
+ const BASE_URL = "/api/executemcp/v2";
44
+ // ── iris_x509_manage ────────────────────────────────────────────
45
+ export const x509ManageTool = {
46
+ name: "iris_x509_manage",
47
+ title: "Manage IRIS X.509 Certificate Credentials",
48
+ description: "List, inspect, import, and delete IRIS X.509 certificate credentials " +
49
+ "(backed by %SYS.X509Credentials in %SYS). Actions: 'list' (all " +
50
+ "credentials' public metadata), 'get' (one credential's public metadata — " +
51
+ "requires alias), 'import' (create a credential from a base64-encoded " +
52
+ "certificate — requires alias + certificate), 'delete' (remove a credential " +
53
+ "— requires alias). The mutating actions (import/delete) are opt-in under " +
54
+ "tool governance and are disabled by default until enabled via " +
55
+ "IRIS_GOVERNANCE. SECURITY: private-key material (PrivateKey, " +
56
+ "PrivateKeyPassword) is NEVER returned by 'list' or 'get' — only the alias, " +
57
+ "a hasPrivateKey boolean, and safe public certificate fields (subjectDN, " +
58
+ "issuerDN, serialNumber, thumbprint, subjectKeyIdentifier, notBefore, " +
59
+ "notAfter). Import mechanism: the 'certificate' field is a base64-encoded " +
60
+ "X.509 certificate (DER, or a PEM body); an OPTIONAL 'privateKey' " +
61
+ "(base64-encoded PEM) and 'privateKeyPassword' may be supplied write-only " +
62
+ "(accepted on import, NEVER echoed back). The native file-based Import API " +
63
+ "is not exposed; credentials are created via object-create + Save.",
64
+ inputSchema: z.object({
65
+ action: z
66
+ .enum(["list", "get", "import", "delete"])
67
+ .describe("Action to perform on the X.509 credential(s)"),
68
+ alias: z
69
+ .string()
70
+ .optional()
71
+ .describe("X.509 credential alias (required for get/import/delete; the unique key)"),
72
+ certificate: z
73
+ .string()
74
+ .optional()
75
+ .describe("Base64-encoded X.509 certificate (DER bytes, or a PEM certificate " +
76
+ "body) — required for 'import'"),
77
+ privateKey: z
78
+ .string()
79
+ .optional()
80
+ .describe("OPTIONAL base64-encoded PEM private key to associate with the " +
81
+ "certificate on 'import' (write-only; NEVER returned in any response)"),
82
+ privateKeyPassword: z
83
+ .string()
84
+ .optional()
85
+ .describe("OPTIONAL password for the supplied private key (write-only; NEVER " +
86
+ "returned in any response)"),
87
+ namespace: z
88
+ .string()
89
+ .optional()
90
+ .describe("Namespace override (X.509 credentials are %SYS-scoped; usually omit)"),
91
+ cursor: z
92
+ .string()
93
+ .optional()
94
+ .describe("Pagination cursor from a previous 'list' response's nextCursor field"),
95
+ }),
96
+ annotations: {
97
+ // The tool can mutate (import/delete). MCP annotations are tool-scoped; the
98
+ // per-action read/write distinction is realized through `mutates` below.
99
+ readOnlyHint: false,
100
+ destructiveHint: true,
101
+ idempotentHint: false,
102
+ openWorldHint: false,
103
+ },
104
+ scope: "SYS",
105
+ // Governance classification (Story 15.0 strict contract): EVERY action key is
106
+ // classified because none are in the frozen Epic-14 baseline. Reads default
107
+ // enabled; writes default DISABLED (opt-in via IRIS_GOVERNANCE).
108
+ mutates: {
109
+ list: "read",
110
+ get: "read",
111
+ import: "write",
112
+ delete: "write",
113
+ },
114
+ handler: async (args, ctx) => {
115
+ const { action, alias, certificate, privateKey, privateKeyPassword, cursor } = args;
116
+ const path = `${BASE_URL}/security/x509`;
117
+ try {
118
+ if (action === "list") {
119
+ const response = await ctx.http.get(path);
120
+ const rawResult = response.result;
121
+ const allCreds = Array.isArray(rawResult) ? rawResult : [];
122
+ const { page, nextCursor } = ctx.paginate(allCreds, cursor);
123
+ const result = {
124
+ credentials: page,
125
+ count: page.length,
126
+ ...(nextCursor ? { nextCursor } : {}),
127
+ };
128
+ return {
129
+ content: [
130
+ { type: "text", text: JSON.stringify(result, null, 2) },
131
+ ],
132
+ structuredContent: result,
133
+ };
134
+ }
135
+ if (action === "get") {
136
+ // `alias` is required for get. An absent ?alias= would make the server
137
+ // return the whole inventory (wrong shape under a `get` action). Reject
138
+ // up front so the caller gets a clear error.
139
+ if (alias === undefined || alias === "") {
140
+ return {
141
+ content: [
142
+ {
143
+ type: "text",
144
+ text: `Error: 'alias' is required for the '${action}' action.`,
145
+ },
146
+ ],
147
+ isError: true,
148
+ };
149
+ }
150
+ const getPath = `${path}?alias=${encodeURIComponent(alias)}`;
151
+ const response = await ctx.http.get(getPath);
152
+ const result = response.result;
153
+ return {
154
+ content: [
155
+ { type: "text", text: JSON.stringify(result, null, 2) },
156
+ ],
157
+ structuredContent: result,
158
+ };
159
+ }
160
+ // import / delete — POST a mutating request body. `alias` is required for
161
+ // every write action.
162
+ if (alias === undefined || alias === "") {
163
+ return {
164
+ content: [
165
+ {
166
+ type: "text",
167
+ text: `Error: 'alias' is required for the '${action}' action.`,
168
+ },
169
+ ],
170
+ isError: true,
171
+ };
172
+ }
173
+ if (action === "import" && (certificate === undefined || certificate === "")) {
174
+ // An import with no certificate cannot create a credential — reject up
175
+ // front rather than let the server fail on a missing required field.
176
+ return {
177
+ content: [
178
+ {
179
+ type: "text",
180
+ text: `Error: the 'import' action requires a base64 'certificate'.`,
181
+ },
182
+ ],
183
+ isError: true,
184
+ };
185
+ }
186
+ const body = { action, alias };
187
+ if (action === "import") {
188
+ body.certificate = certificate;
189
+ // Private key + password are write-only: forwarded on import, never read
190
+ // back. Only include when supplied.
191
+ if (privateKey !== undefined && privateKey !== "") {
192
+ body.privateKey = privateKey;
193
+ }
194
+ if (privateKeyPassword !== undefined && privateKeyPassword !== "") {
195
+ body.privateKeyPassword = privateKeyPassword;
196
+ }
197
+ }
198
+ const response = await ctx.http.post(path, body);
199
+ const result = response.result;
200
+ return {
201
+ content: [
202
+ { type: "text", text: JSON.stringify(result, null, 2) },
203
+ ],
204
+ structuredContent: result,
205
+ };
206
+ }
207
+ catch (error) {
208
+ if (error instanceof IrisApiError) {
209
+ const label = alias ? `X.509 credential '${alias}'` : "X.509 credentials";
210
+ return {
211
+ content: [
212
+ {
213
+ type: "text",
214
+ text: `Error performing '${action}' on ${label}: ${error.message}`,
215
+ },
216
+ ],
217
+ isError: true,
218
+ };
219
+ }
220
+ throw error;
221
+ }
222
+ },
223
+ };
224
+ //# sourceMappingURL=x509.js.map
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@iris-mcp/admin",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.0",
4
+ "description": "IRIS Administration MCP Server",
5
+ "keywords": [
6
+ "iris",
7
+ "mcp",
8
+ "model-context-protocol",
9
+ "mcp-server",
10
+ "administration",
11
+ "security",
12
+ "ai-agents"
13
+ ],
14
+ "homepage": "https://github.com/jbrandtmse/iris-execute-mcp-v2/tree/main/packages/iris-admin-mcp#readme",
15
+ "bugs": {
16
+ "url": "https://github.com/jbrandtmse/iris-execute-mcp-v2/issues"
17
+ },
18
+ "license": "MIT",
19
+ "author": "jbrandtmse (https://github.com/jbrandtmse)",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/jbrandtmse/iris-execute-mcp-v2.git",
23
+ "directory": "packages/iris-admin-mcp"
24
+ },
25
+ "type": "module",
26
+ "main": "./dist/index.js",
27
+ "types": "./dist/index.d.ts",
28
+ "bin": {
29
+ "iris-admin-mcp": "./dist/index.js"
30
+ },
31
+ "mcpName": "io.github.jbrandtmse/iris-admin-mcp",
32
+ "exports": {
33
+ ".": {
34
+ "types": "./dist/index.d.ts",
35
+ "import": "./dist/index.js"
36
+ }
37
+ },
38
+ "files": [
39
+ "dist",
40
+ "CHANGELOG.md",
41
+ "!dist/**/__tests__",
42
+ "!dist/**/*.map"
43
+ ],
44
+ "engines": {
45
+ "node": ">=22.17.0"
46
+ },
47
+ "dependencies": {
48
+ "zod": "^4.3.6",
49
+ "@iris-mcp/shared": "1.0.0"
50
+ },
51
+ "devDependencies": {
52
+ "@types/node": "^22.17.0"
53
+ },
54
+ "scripts": {
55
+ "build": "tsc --project tsconfig.json",
56
+ "test": "vitest run",
57
+ "test:integration": "vitest run --config vitest.integration.config.ts",
58
+ "lint": "eslint src/ --max-warnings 0",
59
+ "type-check": "tsc --noEmit"
60
+ }
6
61
  }