@airctrl/cli 0.4.0 → 0.6.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/dist/cli.js CHANGED
@@ -15,6 +15,7 @@ import { resolveClient, resolveHumanClient } from './resolve-client.js';
15
15
  import { CliError, ReconcileError } from './cli-error.js';
16
16
  import { runSaCommand, buildSaDeps } from './sa-commands.js';
17
17
  import { runGatewayCommand } from './gateway-commands.js';
18
+ import { runMcpGatewayCommand } from './mcp-gateway-commands.js';
18
19
  import { runRecordCommand } from './record-commands.js';
19
20
  import { runProjectCommand } from './project-commands.js';
20
21
  import { runGroupCommand } from './group-commands.js';
@@ -125,6 +126,7 @@ export const USAGE = `airctrl — inject AIRCTRL secrets into your process (clie
125
126
  airctrl new <format> --name <n> [--project <id>] [--opt value …] [--env development|staging|production] [--profile <name>]
126
127
  airctrl import env <file> --name <n> [--project <id>] [--target-env <e>] [--env development|staging|production] [--profile <name>]
127
128
  airctrl gateway <command> [args] [--profile <name>] (run: airctrl gateway help)
129
+ airctrl mcp-gateway <command> [args] [--profile <name>] (run: airctrl mcp-gateway help)
128
130
  airctrl record <command> [args] [--profile <name>] (run: airctrl record help)
129
131
  airctrl project <command> [args] [--profile <name>] (run: airctrl project help)
130
132
  airctrl group <command> [args] [--profile <name>] (run: airctrl group help)
@@ -446,6 +448,12 @@ export async function runCli(argv, deps = {}) {
446
448
  env: deps.env,
447
449
  stdout: deps.stdout,
448
450
  });
451
+ case 'mcp-gateway':
452
+ return runMcpGatewayCommand(rest, {
453
+ resolve: resolveClientDeps(deps),
454
+ env: deps.env,
455
+ stdout: deps.stdout,
456
+ });
449
457
  case 'record':
450
458
  return runRecordCommand(rest, {
451
459
  resolve: resolveClientDeps(deps),
@@ -81,16 +81,16 @@ export const GATEWAY_SPECS = {
81
81
  },
82
82
  logs: {
83
83
  positionals: ['gatewayId'],
84
- flags: ['since', 'provider', 'model', 'status', 'cursor', 'limit', 'offset', ...profile],
84
+ flags: ['since', 'until', 'provider', 'model', 'status', 'status-class', 'search', 'cursor', 'limit', 'offset', ...profile],
85
85
  },
86
86
  log: { positionals: ['gatewayId', 'logId'], flags: profile },
87
87
  'key-access': {
88
88
  positionals: ['gatewayId'],
89
- flags: ['outcome', 'since', 'cursor', 'limit', 'offset', ...profile],
89
+ flags: ['outcome', 'since', 'until', 'cursor', 'limit', 'offset', ...profile],
90
90
  },
91
91
  'usage-logs': {
92
92
  positionals: [],
93
- flags: ['project', 'since', 'provider', 'model', 'status', 'gateway', 'cursor', 'limit', 'offset', ...profile],
93
+ flags: ['project', 'since', 'until', 'provider', 'model', 'status', 'gateway', 'cursor', 'limit', 'offset', ...profile],
94
94
  requiredFlags: ['project'],
95
95
  },
96
96
  'usage-log': {
@@ -100,12 +100,12 @@ export const GATEWAY_SPECS = {
100
100
  },
101
101
  'usage-spend': {
102
102
  positionals: [],
103
- flags: ['project', ...profile],
103
+ flags: ['project', 'gateway', ...profile],
104
104
  requiredFlags: ['project'],
105
105
  },
106
106
  'usage-metrics': {
107
107
  positionals: [],
108
- flags: ['project', 'since', 'bucket', ...profile],
108
+ flags: ['project', 'since', 'until', 'bucket', 'gateway', 'provider', 'model', 'status-class', 'search', ...profile],
109
109
  requiredFlags: ['project'],
110
110
  },
111
111
  otel: {
@@ -386,9 +386,12 @@ export async function runGatewayCommand(argv, deps) {
386
386
  case 'logs':
387
387
  result = await client.listGatewayLogs(id, {
388
388
  since: parsed.flags.since,
389
+ until: parsed.flags.until,
389
390
  provider: parsed.flags.provider,
390
391
  model: parsed.flags.model,
391
392
  status: numberFlag(parsed.flags.status, true, 100, 599),
393
+ statusClass: enumFlag(parsed.flags['status-class'], ['2xx', '4xx', '5xx', 'other']),
394
+ search: parsed.flags.search,
392
395
  cursor: parsed.flags.cursor,
393
396
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
394
397
  offset: numberFlag(parsed.flags.offset, true),
@@ -401,6 +404,7 @@ export async function runGatewayCommand(argv, deps) {
401
404
  result = await client.listGatewayKeyAccess(id, {
402
405
  outcome: enumFlag(parsed.flags.outcome, ['granted', 'denied', 'error']),
403
406
  since: parsed.flags.since,
407
+ until: parsed.flags.until,
404
408
  cursor: parsed.flags.cursor,
405
409
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
406
410
  offset: numberFlag(parsed.flags.offset, true),
@@ -410,6 +414,7 @@ export async function runGatewayCommand(argv, deps) {
410
414
  result = await client.listUsageLogs({
411
415
  projectId: parsed.flags.project,
412
416
  since: parsed.flags.since,
417
+ until: parsed.flags.until,
413
418
  provider: parsed.flags.provider,
414
419
  model: parsed.flags.model,
415
420
  status: numberFlag(parsed.flags.status, true, 100, 599),
@@ -423,12 +428,20 @@ export async function runGatewayCommand(argv, deps) {
423
428
  result = await client.getUsageLogDetail(parsed.flags.project, id);
424
429
  break;
425
430
  case 'usage-spend':
426
- result = await client.getUsageSpend(parsed.flags.project);
431
+ result = parsed.flags.gateway
432
+ ? await client.getUsageSpend(parsed.flags.project, parsed.flags.gateway)
433
+ : await client.getUsageSpend(parsed.flags.project);
427
434
  break;
428
435
  case 'usage-metrics':
429
436
  result = await client.getUsageMetrics(parsed.flags.project, {
430
437
  since: parsed.flags.since,
438
+ until: parsed.flags.until,
431
439
  bucket: enumFlag(parsed.flags.bucket, ['hour', 'day']),
440
+ gatewayId: parsed.flags.gateway,
441
+ provider: parsed.flags.provider,
442
+ model: parsed.flags.model,
443
+ statusClass: enumFlag(parsed.flags['status-class'], ['2xx', '4xx', '5xx', 'other']),
444
+ search: parsed.flags.search,
432
445
  });
433
446
  break;
434
447
  case 'otel':
@@ -0,0 +1,185 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { parseArgv, ParseError } from './parser.js';
3
+ import { resolveClient, resolveHumanClient } from './resolve-client.js';
4
+ const profile = ['profile'];
5
+ export const MCP_GATEWAY_SPECS = {
6
+ list: { positionals: [], flags: ['project', ...profile], requiredFlags: ['project'] },
7
+ get: { positionals: ['gatewayId'], flags: profile },
8
+ catalog: { positionals: [], flags: profile },
9
+ create: { positionals: [], flags: ['project', 'name', 'slug', ...profile], requiredFlags: ['project', 'name'] },
10
+ update: { positionals: ['gatewayId'], flags: ['name', 'active', ...profile] },
11
+ runtime: { positionals: ['gatewayId'], flags: ['timeout-ms', 'max-result-bytes', 'max-concurrent', 'rate-limit-per-min', 'ip-allowlist', 'discovery-mode', ...profile] },
12
+ delete: { positionals: ['gatewayId'], flags: profile },
13
+ servers: { positionals: ['gatewayId'], flags: profile },
14
+ 'server-create': { positionals: ['gatewayId'], flags: ['name', 'namespace', 'transport', 'endpoint', 'connector', 'auth', 'auth-secret-env', 'catalog', ...profile], requiredFlags: ['name', 'namespace', 'transport', 'auth'] },
15
+ 'server-update': { positionals: ['gatewayId', 'serverId'], flags: ['name', 'endpoint', 'enabled', ...profile] },
16
+ 'server-delete': { positionals: ['gatewayId', 'serverId'], flags: profile },
17
+ 'server-sync': { positionals: ['gatewayId', 'serverId'], flags: profile },
18
+ 'server-health': { positionals: ['gatewayId', 'serverId'], flags: profile },
19
+ tools: { positionals: ['gatewayId'], flags: profile },
20
+ clients: { positionals: ['gatewayId'], flags: profile },
21
+ 'client-create': { positionals: ['gatewayId'], flags: ['name', 'type', ...profile], requiredFlags: ['name', 'type'] },
22
+ 'client-update': { positionals: ['gatewayId', 'clientId'], flags: ['name', ...profile], requiredFlags: ['name'] },
23
+ 'client-revoke': { positionals: ['gatewayId', 'clientId'], flags: profile },
24
+ keys: { positionals: ['gatewayId', 'clientId'], flags: profile },
25
+ 'key-create': { positionals: ['gatewayId', 'clientId'], flags: ['scopes', 'servers', ...profile] },
26
+ 'key-revoke': { positionals: ['gatewayId', 'clientId', 'keyId'], flags: profile },
27
+ policies: { positionals: ['gatewayId'], flags: profile },
28
+ 'policy-create': { positionals: ['gatewayId'], flags: ['name', 'server', 'pattern', 'effect', 'access', 'priority', ...profile], requiredFlags: ['name', 'pattern', 'effect', 'access'] },
29
+ 'policy-delete': { positionals: ['gatewayId', 'policyId'], flags: profile },
30
+ 'policy-export': { positionals: ['gatewayId'], flags: profile },
31
+ 'policy-apply': { positionals: ['gatewayId', 'file'], flags: ['prune', ...profile] },
32
+ calls: { positionals: ['gatewayId'], flags: ['since', 'until', 'server', 'tool', 'outcome', 'limit', ...profile] },
33
+ metrics: { positionals: ['gatewayId'], flags: profile },
34
+ payload: { positionals: ['gatewayId', 'callId'], flags: profile },
35
+ 'calls-export': { positionals: ['gatewayId'], flags: ['since', 'until', 'server', 'tool', 'outcome', ...profile] },
36
+ grants: { positionals: ['gatewayId'], flags: profile },
37
+ 'grant-create': { positionals: ['gatewayId'], flags: ['subject-type', 'subject-id', 'access', ...profile], requiredFlags: ['subject-type', 'subject-id', 'access'] },
38
+ 'grant-revoke': { positionals: ['gatewayId', 'grantId'], flags: profile },
39
+ };
40
+ export const SERVICE_ACCOUNT_MCP_GATEWAY_COMMANDS = ['list', 'get', 'catalog', 'servers', 'server-health', 'tools', 'clients', 'keys', 'policies', 'calls', 'metrics', 'calls-export', 'grants'];
41
+ const READS = new Set(SERVICE_ACCOUNT_MCP_GATEWAY_COMMANDS);
42
+ export const MCP_GATEWAY_USAGE = `airctrl mcp-gateway commands
43
+
44
+ list --project <id> | get <gatewayId> | catalog | create --project <id> --name <name>
45
+ update|delete <gatewayId>
46
+ servers <gatewayId> | server-create|server-update|server-delete|server-sync|server-health …
47
+ tools <gatewayId> | clients|client-create|client-update|client-revoke|keys|key-create|key-revoke …
48
+ policies|policy-create|policy-delete|policy-export|policy-apply … | grants|grant-create|grant-revoke …
49
+ calls|metrics|payload|calls-export <gatewayId> …
50
+ `;
51
+ function csv(value) { return value?.split(',').map((item) => item.trim()).filter(Boolean); }
52
+ function bool(value) { if (value === undefined)
53
+ return false; if (value === 'true')
54
+ return true; if (value === 'false')
55
+ return false; throw new ParseError('cli_flag_invalid_value'); }
56
+ function integer(value) { if (value === undefined)
57
+ return undefined; const parsed = Number(value); if (!Number.isInteger(parsed) || parsed < 1)
58
+ throw new ParseError('cli_flag_invalid_value'); return parsed; }
59
+ function optionalLimit(value) { return value === 'none' ? null : integer(value); }
60
+ function apiKeyClientType(value) { if (value !== 'api_key')
61
+ throw new ParseError('cli_flag_invalid_value'); return value; }
62
+ function secretFromEnv(name, env) { if (!name)
63
+ return undefined; if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !env[name])
64
+ throw new ParseError('cli_env_value_required'); return env[name]; }
65
+ function output(value, deps) { (deps.stdout ?? ((text) => process.stdout.write(text)))(`${typeof value === 'string' ? value : JSON.stringify(value ?? { ok: true }, null, 2)}\n`); }
66
+ function sdk(command, profileFlag, deps) {
67
+ return (READS.has(command) ? resolveClient : resolveHumanClient)({ ...deps.resolve, profileFlag }).client;
68
+ }
69
+ export async function runMcpGatewayCommand(argv, deps) {
70
+ const [command, ...rest] = argv;
71
+ if (!command || command === 'help' || command === '--help') {
72
+ output(MCP_GATEWAY_USAGE.trimEnd(), deps);
73
+ return 0;
74
+ }
75
+ if (!Object.hasOwn(MCP_GATEWAY_SPECS, command))
76
+ throw new ParseError('cli_unknown_command');
77
+ const parsed = parseArgv(rest, MCP_GATEWAY_SPECS[command]);
78
+ const api = sdk(command, parsed.flags.profile, deps).mcpGateways();
79
+ const [gatewayId, childId, thirdId] = parsed.positionals;
80
+ let result;
81
+ switch (command) {
82
+ case 'list':
83
+ result = await api.list(parsed.flags.project);
84
+ break;
85
+ case 'get':
86
+ result = await api.get(gatewayId);
87
+ break;
88
+ case 'catalog':
89
+ result = await api.catalog();
90
+ break;
91
+ case 'create':
92
+ result = await api.create({ projectId: parsed.flags.project, name: parsed.flags.name, slug: parsed.flags.slug });
93
+ break;
94
+ case 'update':
95
+ result = await api.update(gatewayId, { name: parsed.flags.name, isActive: parsed.flags.active === undefined ? undefined : bool(parsed.flags.active) });
96
+ break;
97
+ case 'runtime':
98
+ result = await api.updateRuntime(gatewayId, { requestTimeoutMs: integer(parsed.flags['timeout-ms']), maxResultBytes: integer(parsed.flags['max-result-bytes']), maxConcurrentCalls: integer(parsed.flags['max-concurrent']), rateLimitPerMin: optionalLimit(parsed.flags['rate-limit-per-min']), ipAllowlist: csv(parsed.flags['ip-allowlist']), toolDiscoveryMode: parsed.flags['discovery-mode'] });
99
+ break;
100
+ case 'delete':
101
+ result = await api.remove(gatewayId);
102
+ break;
103
+ case 'servers':
104
+ result = await api.listServers(gatewayId);
105
+ break;
106
+ case 'server-create':
107
+ result = await api.createServer(gatewayId, { name: parsed.flags.name, namespace: parsed.flags.namespace, transport: parsed.flags.transport, endpointUrl: parsed.flags.endpoint, connectorId: parsed.flags.connector, authMode: parsed.flags.auth, authSecret: secretFromEnv(parsed.flags['auth-secret-env'], deps.env ?? process.env), catalogSlug: parsed.flags.catalog });
108
+ break;
109
+ case 'server-update':
110
+ result = await api.updateServer(gatewayId, childId, { name: parsed.flags.name, endpointUrl: parsed.flags.endpoint, enabled: parsed.flags.enabled === undefined ? undefined : bool(parsed.flags.enabled) });
111
+ break;
112
+ case 'server-delete':
113
+ result = await api.removeServer(gatewayId, childId);
114
+ break;
115
+ case 'server-sync':
116
+ result = await api.syncServer(gatewayId, childId);
117
+ break;
118
+ case 'server-health':
119
+ result = await api.serverHealth(gatewayId, childId);
120
+ break;
121
+ case 'tools':
122
+ result = await api.listTools(gatewayId);
123
+ break;
124
+ case 'clients':
125
+ result = await api.listClients(gatewayId);
126
+ break;
127
+ case 'client-create':
128
+ result = await api.createClient(gatewayId, { name: parsed.flags.name, clientType: apiKeyClientType(parsed.flags.type) });
129
+ break;
130
+ case 'client-update':
131
+ result = await api.updateClient(gatewayId, childId, { name: parsed.flags.name });
132
+ break;
133
+ case 'client-revoke':
134
+ result = await api.revokeClient(gatewayId, childId);
135
+ break;
136
+ case 'keys':
137
+ result = await api.listKeys(gatewayId, childId);
138
+ break;
139
+ case 'key-create':
140
+ result = await api.createKey(gatewayId, childId, { scopes: csv(parsed.flags.scopes), serverIds: csv(parsed.flags.servers) });
141
+ break;
142
+ case 'key-revoke':
143
+ result = await api.revokeKey(gatewayId, childId, thirdId);
144
+ break;
145
+ case 'policies':
146
+ result = await api.listPolicies(gatewayId);
147
+ break;
148
+ case 'policy-create':
149
+ result = await api.createPolicy(gatewayId, { name: parsed.flags.name, serverId: parsed.flags.server, toolPattern: parsed.flags.pattern, effect: parsed.flags.effect, accessMode: parsed.flags.access, priority: integer(parsed.flags.priority) });
150
+ break;
151
+ case 'policy-delete':
152
+ result = await api.removePolicy(gatewayId, childId);
153
+ break;
154
+ case 'policy-export':
155
+ result = (await api.exportPolicy(gatewayId)).yaml;
156
+ break;
157
+ case 'policy-apply':
158
+ result = await api.importPolicy(gatewayId, { yaml: readFileSync(childId, 'utf8'), apply: true, prune: bool(parsed.flags.prune), confirmed: true });
159
+ break;
160
+ case 'calls':
161
+ result = await api.listCalls(gatewayId, { since: parsed.flags.since, until: parsed.flags.until, serverId: parsed.flags.server, tool: parsed.flags.tool, outcome: parsed.flags.outcome, limit: integer(parsed.flags.limit) });
162
+ break;
163
+ case 'metrics':
164
+ result = await api.callMetrics(gatewayId);
165
+ break;
166
+ case 'payload':
167
+ result = await api.callPayload(gatewayId, childId);
168
+ break;
169
+ case 'calls-export':
170
+ result = (await api.callsCsv(gatewayId, { since: parsed.flags.since, until: parsed.flags.until, serverId: parsed.flags.server, tool: parsed.flags.tool, outcome: parsed.flags.outcome })).csv;
171
+ break;
172
+ case 'grants':
173
+ result = await api.listGrants(gatewayId);
174
+ break;
175
+ case 'grant-create':
176
+ result = await api.createGrant(gatewayId, { subjectType: parsed.flags['subject-type'], subjectId: parsed.flags['subject-id'], accessMode: parsed.flags.access });
177
+ break;
178
+ case 'grant-revoke':
179
+ result = await api.revokeGrant(gatewayId, childId);
180
+ break;
181
+ default: throw new ParseError('cli_unknown_command');
182
+ }
183
+ output(result, deps);
184
+ return 0;
185
+ }
@@ -13,7 +13,7 @@
13
13
  * lease-holding paths, not to that fast path.
14
14
  */
15
15
  import { homedir } from 'node:os';
16
- import { generateSaClaimTicketPlaintext, BootstrapContext, createBootstrapClaimClient, createClient, prepareCapability, runCredentialLifecycle, isSaCoordinatorError, SaCoordinatorError, } from '@airctrl/sdk';
16
+ import { generateSaClaimTicketPlaintext, BootstrapContext, createBootstrapClaimClient, createClient, prepareCapability, AirctrlError, runCredentialLifecycle, isSaCoordinatorError, SaCoordinatorError, } from '@airctrl/sdk';
17
17
  import { join } from 'node:path';
18
18
  import { acquireHandoffLease, createProvisionalHandoff, createRotationArtifact, loadRotationArtifact, deleteRotationArtifact, createReceipt, loadReceipt, createProfile, loadProfile, replaceProfile, deleteProfileUnderLock, canonicalJson, acquireProfileLock, evidenceSecure, deleteEvidenceSecure, confirmDurableAbsence, assertBaseUrlMatch, assertRegularFile, assertHandoffChain, assertHandoffId, normalizeBaseUrl, handoffDir, handoffFile, StoreError, REAL_FS, } from './store/index.js';
19
19
  import { resolveHumanClient, resolveClient, resolveHolderProfile } from './resolve-client.js';
@@ -198,12 +198,29 @@ function commitRotation(lease, ctx, meta, deps) {
198
198
  }
199
199
  /** Run the durable authorize HTTP under the lease, persist by mode, gate expiry, and return the output. */
200
200
  async function authorizeAndPersist(lease, human, ctx, deps) {
201
- const meta = await human.client.saAuthorizeCredential(ctx.serviceAccountId, {
201
+ const durableInput = {
202
202
  accountId: ctx.accountId,
203
203
  operationId: ctx.operationId,
204
204
  bootstrapClaimTicketCandidate: ctx.claimTicket,
205
205
  idempotencyKey: ctx.operationId, // stable per logical op → server dedup consistent across retries
206
- });
206
+ };
207
+ let meta;
208
+ try {
209
+ meta = await human.client.saAuthorizeCredential(ctx.serviceAccountId, durableInput);
210
+ }
211
+ catch (error) {
212
+ // The server is the authoritative classifier for bootstrap vs rotation. A bootstrap must select at least
213
+ // one environment scope, while a rotation must inherit the active credential and therefore rejects an
214
+ // explicit selection. Retry the same durable operation exactly once with the least-privileged legacy
215
+ // scope only when the server proves this is a bootstrap. The first request fails before any DB write, and
216
+ // the stable operation/idempotency UUID keeps the retry crash-safe.
217
+ if (!(error instanceof AirctrlError) || error.message !== 'secret_access_scopes_required')
218
+ throw error;
219
+ meta = await human.client.saAuthorizeCredential(ctx.serviceAccountId, {
220
+ ...durableInput,
221
+ secretAccessScopes: ['general'],
222
+ });
223
+ }
207
224
  if (meta.mode === 'bootstrap')
208
225
  finalizeBootstrap(lease, ctx, meta, deps);
209
226
  else
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@airctrl/cli",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "type": "module",
5
5
  "description": "AIRCTRL CLI for encrypted records, process injection, projects, gateways and Service Accounts.",
6
6
  "license": "UNLICENSED",
@@ -39,6 +39,6 @@
39
39
  "dev": "tsx src/index.ts"
40
40
  },
41
41
  "dependencies": {
42
- "@airctrl/sdk": "0.4.0"
42
+ "@airctrl/sdk": "0.6.0"
43
43
  }
44
44
  }