agl 41.2.0 → 42.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 (91) hide show
  1. package/changelog.md +35 -0
  2. package/dist_serve/bundle.js +1996 -1999
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +3 -68
  5. package/dist_serve/bundle.js.third-party-notices.txt +4 -137
  6. package/dist_ts/00_commitinfo_data.js +1 -1
  7. package/dist_ts/aglapi/aglapisurface.document.js +4 -4
  8. package/dist_ts/classes.authmodels.d.ts +2 -8
  9. package/dist_ts/classes.authmodels.js +60 -23
  10. package/dist_ts/classes.authstore.d.ts +22 -0
  11. package/dist_ts/classes.authstore.js +152 -23
  12. package/dist_ts/classes.cli.d.ts +3 -6
  13. package/dist_ts/classes.cli.js +38 -51
  14. package/dist_ts/classes.config.d.ts +17 -3
  15. package/dist_ts/classes.config.js +55 -18
  16. package/dist_ts/classes.controller.d.ts +12 -12
  17. package/dist_ts/classes.controller.js +46 -117
  18. package/dist_ts/classes.controllermanagement.d.ts +42 -9
  19. package/dist_ts/classes.controllermanagement.js +72 -23
  20. package/dist_ts/classes.controllerservice.d.ts +3 -31
  21. package/dist_ts/classes.controllerservice.js +3 -47
  22. package/dist_ts/classes.mcpcontrollerhost.js +9 -3
  23. package/dist_ts/classes.processinspection.d.ts +8 -1
  24. package/dist_ts/classes.processinspection.js +92 -2
  25. package/dist_ts/classes.proxycontrol.js +6 -1
  26. package/dist_ts/classes.proxydaemon.d.ts +2 -2
  27. package/dist_ts/classes.proxydaemon.js +1 -1
  28. package/dist_ts/classes.proxystore.d.ts +2 -11
  29. package/dist_ts/classes.proxystore.js +3 -25
  30. package/dist_ts/classes.tpmsecretcodec.d.ts +13 -0
  31. package/dist_ts/classes.tpmsecretcodec.js +28 -0
  32. package/dist_ts/classes.trustedproxysecrets.d.ts +91 -0
  33. package/dist_ts/classes.trustedproxysecrets.js +338 -0
  34. package/dist_ts/classes.upgradecoordinator.d.ts +14 -1
  35. package/dist_ts/classes.upgradecoordinator.js +21 -3
  36. package/dist_ts/classes.upgradetransaction.d.ts +32 -0
  37. package/dist_ts/classes.upgradetransaction.js +101 -4
  38. package/dist_ts/functions.controlleradmission.d.ts +67 -0
  39. package/dist_ts/functions.controlleradmission.js +127 -0
  40. package/dist_ts/functions.remotecli.d.ts +27 -0
  41. package/dist_ts/functions.remotecli.js +236 -0
  42. package/dist_ts/functions.retiredenvironment.d.ts +11 -2
  43. package/dist_ts/functions.retiredenvironment.js +22 -5
  44. package/dist_ts/index.d.ts +1 -0
  45. package/dist_ts/index.js +2 -1
  46. package/dist_ts/interfaces.auth.d.ts +29 -4
  47. package/dist_ts/interfaces.auth.js +5 -1
  48. package/dist_ts/interfaces.config.d.ts +14 -0
  49. package/dist_ts/interfaces.config.js +9 -2
  50. package/dist_ts/interfaces.lifecycle.d.ts +3 -0
  51. package/dist_ts_authswitch/classes.authoritydaemon.js +6 -1
  52. package/dist_ts_interfaces/interfaces.d.ts +2 -2
  53. package/dist_ts_interfaces/interfaces.js +1 -1
  54. package/dist_ts_interfaces/management.d.ts +2 -2
  55. package/dist_ts_interfaces/management.js +2 -2
  56. package/dist_ts_interfaces/requests.d.ts +1 -2
  57. package/dist_ts_interfaces/requests.js +1 -1
  58. package/dist_ts_interfaces/requests.upgrade.d.ts +0 -12
  59. package/package.json +12 -11
  60. package/readme.md +84 -24
  61. package/ts/00_commitinfo_data.ts +1 -1
  62. package/ts/aglapi/aglapisurface.document.ts +3 -3
  63. package/ts/classes.authmodels.ts +68 -25
  64. package/ts/classes.authstore.ts +151 -24
  65. package/ts/classes.cli.ts +38 -61
  66. package/ts/classes.config.ts +70 -21
  67. package/ts/classes.controller.ts +50 -163
  68. package/ts/classes.controllermanagement.ts +123 -49
  69. package/ts/classes.controllerservice.ts +3 -56
  70. package/ts/classes.mcpcontrollerhost.ts +10 -5
  71. package/ts/classes.processinspection.ts +84 -3
  72. package/ts/classes.proxycontrol.ts +2 -0
  73. package/ts/classes.proxydaemon.ts +3 -2
  74. package/ts/classes.proxystore.ts +4 -25
  75. package/ts/classes.tpmsecretcodec.ts +26 -0
  76. package/ts/classes.trustedproxysecrets.ts +317 -0
  77. package/ts/classes.upgradecoordinator.ts +33 -3
  78. package/ts/classes.upgradetransaction.ts +130 -1
  79. package/ts/functions.controlleradmission.ts +168 -0
  80. package/ts/functions.remotecli.ts +264 -0
  81. package/ts/functions.retiredenvironment.ts +25 -3
  82. package/ts/index.ts +1 -0
  83. package/ts/interfaces.auth.ts +36 -3
  84. package/ts/interfaces.config.ts +15 -0
  85. package/ts/interfaces.lifecycle.ts +3 -0
  86. package/ts_authswitch/classes.authoritydaemon.ts +2 -0
  87. package/ts_interfaces/interfaces.ts +2 -2
  88. package/ts_interfaces/management.ts +2 -2
  89. package/ts_interfaces/requests.ts +0 -10
  90. package/ts_interfaces/requests.upgrade.ts +0 -16
  91. package/ts_web/00_commitinfo_data.ts +1 -1
@@ -0,0 +1,264 @@
1
+ import * as plugins from './plugins.js';
2
+ import {
3
+ defaultControllerPort,
4
+ resolveMovedRuntimeConfig,
5
+ resolveStoredRuntimeConfig,
6
+ } from './classes.config.js';
7
+ import { acquireStartAdmission, withControllerAuthStore } from './classes.cli.js';
8
+ import type { SmartDataAuthStore } from './classes.authstore.js';
9
+ import { TpmSecretCodec, type ITpmSecretCodec } from './classes.tpmsecretcodec.js';
10
+ import {
11
+ decodeTrustedProxySecret,
12
+ importControllerTrustedProxySecret,
13
+ removeControllerTrustedProxySecret,
14
+ } from './classes.trustedproxysecrets.js';
15
+ import { configurationLocalCliActor } from './functions.configurationactor.js';
16
+ import { preflightAGLHomeMigration } from './functions.controllerdataroot.js';
17
+ import type { IControllerIssuerIdentity } from './interfaces.identity.js';
18
+ import type { IControllerRuntimeConfig } from './interfaces.config.js';
19
+ import type { IControllerAuditRemoteMove, TControllerAuditEventType } from './interfaces.auth.js';
20
+
21
+ export const remoteCliHelp = `Usage: agl remote set --public-origin ORIGIN [--rp-id HOST] [--gateway-source ADDRESS]... [--port PORT]
22
+ agl remote unset [--port PORT]
23
+ agl remote secret import [--port PORT] < SECRET_FILE
24
+ Every command runs against a stopped controller (agl stop first) on the port it was initialized on (default 4097),
25
+ as the local OS user, and is audited.
26
+ set moves the port to the HTTPS public origin ORIGIN behind a TLS reverse proxy, with WebAuthn RP ID HOST (default:
27
+ the origin's hostname). Each --gateway-source names an address the proxy reaches this host from; without one only a
28
+ reverse proxy on this host reaches the controller, which then listens on loopback. The controller keeps its id and
29
+ all of its data. When the origin or RP ID changes, its passkey is removed and every temporary password revoked: the
30
+ next start prints a new setup code, to enroll a passkey at the new origin. Run it again to change the gateway
31
+ sources; the passkey then stays.
32
+ unset moves the port back to http://localhost:PORT (RP ID localhost), removes the passkey, revokes every temporary
33
+ password and forgets the trusted-proxy secret.
34
+ secret import reads a 32-byte base64url secret (43 characters) from standard input, never from a terminal, and makes
35
+ it the controller's trusted-proxy secret, for a reverse proxy other than AGL's own gateway: that proxy injects it as
36
+ X-Harness-Controller-Proxy-Secret. The secret is sealed with the TPM and never printed.
37
+ `;
38
+
39
+ export type TRemoteCliArguments =
40
+ | { action: 'set'; port: number; publicOrigin: string; rpId?: string; gatewaySources: string[] }
41
+ | { action: 'unset'; port: number }
42
+ | { action: 'secret-import'; port: number };
43
+
44
+ export const parseRemoteCliArguments = (argsArg: readonly string[]): TRemoteCliArguments => {
45
+ const rest = [...argsArg];
46
+ const first = rest.shift();
47
+ const action = first === 'secret' && rest[0] === 'import' ? (rest.shift(), 'secret-import' as const)
48
+ : first === 'set' || first === 'unset' ? first : undefined;
49
+ if (!action) throw new Error(remoteCliHelp);
50
+ let port = defaultControllerPort;
51
+ let publicOrigin: string | undefined;
52
+ let rpId: string | undefined;
53
+ const gatewaySources: string[] = [];
54
+ const seen = new Set<string>();
55
+ for (let index = 0; index < rest.length; index++) {
56
+ const token = rest[index]!;
57
+ const equals = token.startsWith('--') ? token.indexOf('=') : -1;
58
+ const flag = equals > 0 ? token.slice(0, equals) : token;
59
+ if (flag !== '--gateway-source' && seen.has(flag)) throw new Error(`Duplicate remote option: ${flag}.`);
60
+ seen.add(flag);
61
+ const value = equals > 0 ? token.slice(equals + 1) : rest[++index];
62
+ if (value === undefined || value === '' || (equals < 0 && value.startsWith('--'))) {
63
+ throw new Error(`${flag} requires a value.`);
64
+ }
65
+ if (flag === '--port') { port = Number(value); continue; }
66
+ if (action === 'set' && flag === '--public-origin') { publicOrigin = value; continue; }
67
+ if (action === 'set' && flag === '--rp-id') { rpId = value; continue; }
68
+ if (action === 'set' && flag === '--gateway-source') { gatewaySources.push(value); continue; }
69
+ throw new Error(`Unknown remote option: ${flag}.`);
70
+ }
71
+ if (!/^[1-9][0-9]{0,4}$/u.test(String(port)) || port > 65_535) throw new Error('--port must be an integer between 1 and 65535.');
72
+ if (action !== 'set') return { action, port };
73
+ if (publicOrigin === undefined) throw new Error('agl remote set requires --public-origin.');
74
+ return { action, port, publicOrigin, ...(rpId === undefined ? {} : { rpId }), gatewaySources };
75
+ };
76
+
77
+ export interface IRemoteCliOptions {
78
+ /** Seals the trusted-proxy secret; TPM2 when absent. For tests. */
79
+ codec?: ITpmSecretCodec;
80
+ /** Where `secret import` reads the secret; this process's standard input when absent. */
81
+ input?: NodeJS.ReadableStream & { isTTY?: boolean };
82
+ /** Where the outcome is written; standard output when absent. */
83
+ write?: (textArg: string) => void;
84
+ }
85
+
86
+ /** A trusted-proxy secret file is a few dozen bytes; anything past this is not one. */
87
+ const maximumSecretInputBytes = 4_096;
88
+
89
+ const readSecretInput = async (inputArg: NodeJS.ReadableStream & { isTTY?: boolean }): Promise<string> => {
90
+ if (inputArg.isTTY) {
91
+ throw new Error('agl remote secret import reads the secret from a pipe or a file, never from a terminal: '
92
+ + 'run it as `agl remote secret import --port <port> < SECRET_FILE`.');
93
+ }
94
+ const chunks: Buffer[] = [];
95
+ let bytes = 0;
96
+ try {
97
+ for await (const chunk of inputArg) {
98
+ const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk as Uint8Array);
99
+ chunks.push(buffer);
100
+ bytes += buffer.byteLength;
101
+ if (bytes > maximumSecretInputBytes) throw new Error('The standard input is longer than a trusted-proxy secret.');
102
+ }
103
+ return Buffer.concat(chunks).toString('utf8').trim();
104
+ } finally {
105
+ for (const chunk of chunks) chunk.fill(0);
106
+ }
107
+ };
108
+
109
+ /**
110
+ * Holds the controller's port on loopback while a command changes its stopped configuration: a controller still
111
+ * listening there (on loopback or every interface) is found, and one starting meanwhile cannot listen until the
112
+ * command ends.
113
+ */
114
+ const holdStoppedControllerPort = async (portArg: number): Promise<plugins.net.Server> => {
115
+ const server = plugins.net.createServer((socketArg) => socketArg.destroy());
116
+ try {
117
+ await new Promise<void>((resolve, reject) => {
118
+ server.once('error', reject);
119
+ server.listen({ host: '127.0.0.1', port: portArg, exclusive: true }, () => {
120
+ server.off('error', reject);
121
+ resolve();
122
+ });
123
+ });
124
+ } catch (errorArg) {
125
+ server.close();
126
+ if ((errorArg as NodeJS.ErrnoException).code === 'EADDRINUSE') {
127
+ throw new Error(`Port ${portArg} is in use: agl remote changes a stopped controller only. Stop it with `
128
+ + `\`agl stop --port ${portArg}\` and run this again.`);
129
+ }
130
+ throw errorArg;
131
+ }
132
+ return server;
133
+ };
134
+
135
+ const releasePort = (serverArg: plugins.net.Server): Promise<void> => new Promise((resolve) => {
136
+ serverArg.close(() => resolve());
137
+ });
138
+
139
+ interface IStoppedController {
140
+ authStore: SmartDataAuthStore;
141
+ issuer: IControllerIssuerIdentity;
142
+ /** `controller:<port>`. */
143
+ controllerId: string;
144
+ config: IControllerRuntimeConfig;
145
+ }
146
+
147
+ /** Runs `actionArg` on the stored configuration of a stopped, initialized controller, under start admission. */
148
+ const withStoppedController = async <T>(
149
+ portArg: number,
150
+ actionArg: (controllerArg: IStoppedController) => Promise<T>,
151
+ ): Promise<T> => {
152
+ await preflightAGLHomeMigration();
153
+ const lease = await acquireStartAdmission('remote');
154
+ try {
155
+ const port = await holdStoppedControllerPort(portArg);
156
+ try {
157
+ return await withControllerAuthStore('The remote configuration change', async (authStoreArg, issuerArg) => {
158
+ const stored = await authStoreArg.getRuntimeConfig(portArg);
159
+ if (!stored) {
160
+ throw new Error(`No controller configuration exists for port ${portArg}. Start the controller on that port `
161
+ + 'once first, with the same AGL_HOME, AGL_DB_DIR or AGL_MONGO_URL / AGL_MONGO_DB environment.');
162
+ }
163
+ const config = await resolveStoredRuntimeConfig(stored, { controllerPort: portArg });
164
+ return actionArg({ authStore: authStoreArg, issuer: issuerArg, controllerId: `controller:${portArg}`, config });
165
+ });
166
+ } finally {
167
+ await releasePort(port);
168
+ }
169
+ } finally {
170
+ await lease?.release();
171
+ }
172
+ };
173
+
174
+ /**
175
+ * Records `typeArg` as attempted, runs the change, and records its outcome, attributed to this OS user and process;
176
+ * a move records on every event where it goes from and to (`details.remoteMove`).
177
+ */
178
+ const audited = async <T>(
179
+ authStoreArg: SmartDataAuthStore,
180
+ typeArg: TControllerAuditEventType,
181
+ actionArg: () => Promise<T>,
182
+ remoteMoveArg?: IControllerAuditRemoteMove,
183
+ ): Promise<T> => {
184
+ const localCli = await configurationLocalCliActor();
185
+ const detail = { localCli, ...(remoteMoveArg === undefined ? {} : { details: { remoteMove: remoteMoveArg } }) };
186
+ await authStoreArg.recordAuditEvent({ type: typeArg, outcome: 'attempted', ...detail });
187
+ let result: T;
188
+ try {
189
+ result = await actionArg();
190
+ } catch (errorArg) {
191
+ try {
192
+ await authStoreArg.recordAuditEvent({ type: typeArg, outcome: 'failed', ...detail });
193
+ } catch (auditErrorArg) {
194
+ throw new AggregateError([errorArg, auditErrorArg], 'The change failed and its failure could not be audited.', { cause: errorArg });
195
+ }
196
+ throw errorArg;
197
+ }
198
+ await authStoreArg.recordAuditEvent({ type: typeArg, outcome: 'succeeded', ...detail });
199
+ return result;
200
+ };
201
+
202
+ const describeConfig = (configArg: IControllerRuntimeConfig): string => configArg.tlsMode === 'local'
203
+ ? `${configArg.publicOrigin} (RP ID ${configArg.rpId}, local)`
204
+ : `${configArg.publicOrigin} (RP ID ${configArg.rpId}, behind a TLS reverse proxy, gateway sources: `
205
+ + `${configArg.gatewaySources?.join(', ') ?? 'none, only a reverse proxy on this host'})`;
206
+
207
+ const moveOutcome = (
208
+ controllerIdArg: string,
209
+ previousArg: IControllerRuntimeConfig,
210
+ targetArg: IControllerRuntimeConfig,
211
+ enrollmentResetArg: boolean,
212
+ ): string => [
213
+ `Moved ${controllerIdArg} from ${describeConfig(previousArg)} to ${describeConfig(targetArg)}.`,
214
+ ...(enrollmentResetArg
215
+ ? [`Its passkey was removed and every temporary password revoked. The next \`agl start --port ${targetArg.controllerPort}\` `
216
+ + `prints a setup code: enroll a passkey with it at ${targetArg.publicOrigin}.`]
217
+ : ['Its passkey stays: the origin and RP ID did not change.']),
218
+ ...(targetArg.gatewaySources
219
+ ? [`Let only ${targetArg.gatewaySources.join(', ')} reach port ${targetArg.controllerPort} through the host firewall.`]
220
+ : []),
221
+ ].join('\n') + '\n';
222
+
223
+ export const runRemoteCli = async (argsArg: string[], optionsArg: IRemoteCliOptions = {}): Promise<void> => {
224
+ const write = optionsArg.write ?? ((textArg: string) => { process.stdout.write(textArg); });
225
+ if (argsArg.includes('--help') || argsArg.includes('-h')) { write(remoteCliHelp); return; }
226
+ const parsed = parseRemoteCliArguments(argsArg);
227
+ if (parsed.action === 'secret-import') {
228
+ const secret = await readSecretInput(optionsArg.input ?? process.stdin);
229
+ decodeTrustedProxySecret(secret).fill(0);
230
+ const outcome = await withStoppedController(parsed.port, async (controllerArg) => {
231
+ if (controllerArg.config.tlsMode !== 'proxy') {
232
+ throw new Error(`${controllerArg.controllerId} runs on localhost, which takes no trusted-proxy secret: move it `
233
+ + 'behind the reverse proxy with `agl remote set` first.');
234
+ }
235
+ return audited(controllerArg.authStore, 'remote.secret.import', () => importControllerTrustedProxySecret({
236
+ controllerId: controllerArg.controllerId,
237
+ issuerId: controllerArg.issuer.issuerId,
238
+ codec: optionsArg.codec ?? new TpmSecretCodec(),
239
+ secret,
240
+ }));
241
+ });
242
+ write(`Imported the trusted-proxy secret of controller:${parsed.port} (generation ${outcome.generation}). `
243
+ + 'Its reverse proxy must send it as X-Harness-Controller-Proxy-Secret.\n');
244
+ return;
245
+ }
246
+ write(await withStoppedController(parsed.port, async (controllerArg) => {
247
+ const target = resolveMovedRuntimeConfig(controllerArg.config, parsed.action === 'set'
248
+ ? { publicOrigin: parsed.publicOrigin, ...(parsed.rpId === undefined ? {} : { rpId: parsed.rpId }), gatewaySources: parsed.gatewaySources }
249
+ : 'local');
250
+ const type = parsed.action === 'set' ? 'remote.set' as const : 'remote.unset' as const;
251
+ const moved = await audited(controllerArg.authStore, type, async () => {
252
+ const result = await controllerArg.authStore.moveRuntimeConfig(target);
253
+ // Local mode takes no trusted-proxy secret, and moving back behind a proxy generates a new one.
254
+ if (parsed.action === 'unset') await removeControllerTrustedProxySecret(controllerArg.controllerId);
255
+ return result;
256
+ }, {
257
+ previous: { publicOrigin: controllerArg.config.publicOrigin, rpId: controllerArg.config.rpId },
258
+ target: { publicOrigin: target.publicOrigin, rpId: target.rpId },
259
+ });
260
+ return moved.changed
261
+ ? moveOutcome(controllerArg.controllerId, moved.previous, target, moved.enrollmentReset)
262
+ : `${controllerArg.controllerId} already serves ${describeConfig(target)}; nothing changed.\n`;
263
+ }));
264
+ };
@@ -10,13 +10,26 @@ export const retiredControllerEnvironmentNames: Readonly<Record<string, string>>
10
10
  HARNESS_CONTROLLER_MONGO_DB: 'AGL_MONGO_DB',
11
11
  HARNESS_CONTROLLER_DB_DIR: 'AGL_DB_DIR',
12
12
  HARNESS_CONTROLLER_FORWARD_ENV: 'AGL_FORWARD_ENV',
13
- HARNESS_CONTROLLER_TRUSTED_PROXY_SECRET: 'AGL_TRUSTED_PROXY_SECRET',
14
13
  HARNESS_CONTROLLER_CLAUDE_EXECUTABLE: 'AGL_CLAUDE_EXECUTABLE',
15
14
  HARNESS_CONTROLLER_CODEX_EXECUTABLE: 'AGL_CODEX_EXECUTABLE',
16
15
  HARNESS_CONTROLLER_CODEX_SERVER_URL: 'AGL_CODEX_SERVER_URL',
17
16
  HARNESS_CONTROLLER_CODEX_SERVER_TOKEN: 'AGL_CODEX_SERVER_TOKEN',
18
17
  });
19
18
 
19
+ const trustedProxySecretRemedy = 'The trusted-proxy secret is generated and sealed in the controller\'s database '
20
+ + 'now; for a reverse proxy other than AGL\'s own gateway, stop the controller, pipe your secret into '
21
+ + '`agl remote secret import --port <port>` (for example `printf \'%s\' "$AGL_TRUSTED_PROXY_SECRET" | agl remote '
22
+ + 'secret import --port 4097`), then unset the variable.';
23
+
24
+ /**
25
+ * Configuration names retired without a replacement variable, each with what to do instead. A process started with
26
+ * one would silently run without it, so starting is refused here too.
27
+ */
28
+ export const retiredControllerEnvironmentRemedies: Readonly<Record<string, string>> = Object.freeze({
29
+ AGL_TRUSTED_PROXY_SECRET: trustedProxySecretRemedy,
30
+ HARNESS_CONTROLLER_TRUSTED_PROXY_SECRET: trustedProxySecretRemedy,
31
+ });
32
+
20
33
  const retiredPrefix = 'HARNESS_CONTROLLER_';
21
34
 
22
35
  export class RetiredControllerEnvironmentError extends Error {
@@ -24,6 +37,8 @@ export class RetiredControllerEnvironmentError extends Error {
24
37
  super(
25
38
  `AGL no longer reads ${names.join(', ')}. `
26
39
  + names.map((nameArg) => {
40
+ const remedy = retiredControllerEnvironmentRemedies[nameArg];
41
+ if (remedy) return `${nameArg}: ${remedy}`;
27
42
  const replacement = retiredControllerEnvironmentNames[nameArg];
28
43
  return replacement ? `Set ${replacement} instead of ${nameArg}.` : `Remove ${nameArg}.`;
29
44
  }).join(' '),
@@ -33,16 +48,23 @@ export class RetiredControllerEnvironmentError extends Error {
33
48
  }
34
49
 
35
50
  /**
36
- * Refuses an environment that still sets a retired `HARNESS_CONTROLLER_*` name. The upgrade token a
51
+ * Refuses an environment that still sets a retired `HARNESS_CONTROLLER_*` name or a name retired without a
52
+ * replacement (`retiredControllerEnvironmentRemedies`). The upgrade token a
37
53
  * pre-33 upgrade worker hands its target is the one exception: it is a process wire, not configuration.
38
54
  * Only names are reported, never values.
39
55
  */
40
56
  export const assertNoRetiredControllerEnvironment = (
41
57
  environmentArg: NodeJS.ProcessEnv = process.env,
58
+ optionsArg: {
59
+ /** `agl remote`, which migrates them: the names of `retiredControllerEnvironmentRemedies` are left alone. */
60
+ allowRemedied?: boolean;
61
+ } = {},
42
62
  ): void => {
43
63
  const names = Object.keys(environmentArg)
44
64
  .filter((nameArg) => environmentArg[nameArg] !== undefined)
45
- .filter((nameArg) => nameArg.toUpperCase().startsWith(retiredPrefix))
65
+ .filter((nameArg) => !(optionsArg.allowRemedied && Object.hasOwn(retiredControllerEnvironmentRemedies, nameArg)))
66
+ .filter((nameArg) => nameArg.toUpperCase().startsWith(retiredPrefix)
67
+ || Object.hasOwn(retiredControllerEnvironmentRemedies, nameArg))
46
68
  .filter((nameArg) => nameArg !== preAglUpgradeTokenEnvironmentVariable)
47
69
  .sort();
48
70
  if (names.length > 0) throw new RetiredControllerEnvironmentError(names);
package/ts/index.ts CHANGED
@@ -60,6 +60,7 @@ export type {
60
60
  export { buildControllerFlexCleanupCohort } from './classes.sessionidentityservice.js';
61
61
  export * from './classes.cli.js';
62
62
  export * from './classes.config.js';
63
+ export * from './functions.controlleradmission.js';
63
64
  export * from './classes.controller.js';
64
65
  export * from './classes.resourcecoordinator.js';
65
66
  export * from './classes.terminalresourcehost.js';
@@ -141,6 +141,10 @@ export const controllerAuditEventTypes = [
141
141
  'resource.browser.view.close',
142
142
  'resource.browser.view.operate',
143
143
  'resource.browser.paint.rearm',
144
+ // The offline `agl remote` commands, run by the local OS user against a stopped controller.
145
+ 'remote.set',
146
+ 'remote.unset',
147
+ 'remote.secret.import',
144
148
  ] as const;
145
149
  export type TControllerAuditEventType = (typeof controllerAuditEventTypes)[number];
146
150
  export type TControllerAuditOutcome = 'attempted' | 'succeeded' | 'denied' | 'failed';
@@ -250,6 +254,34 @@ export type TControllerAuditSessionId =
250
254
  | IControllerRuntimeId
251
255
  | plugins.browserRuntime.IBrowserClaudeSessionId;
252
256
 
257
+ /** One end of an offline `agl remote set|unset` move, as its audit events record it; never a secret. */
258
+ export interface IControllerAuditRemoteEndpoint {
259
+ publicOrigin: string;
260
+ rpId: string;
261
+ }
262
+
263
+ /** The public origin and RP ID a `remote.set` or `remote.unset` moves from and to. */
264
+ export interface IControllerAuditRemoteMove {
265
+ previous: IControllerAuditRemoteEndpoint;
266
+ target: IControllerAuditRemoteEndpoint;
267
+ }
268
+
269
+ /**
270
+ * What an audit event records beyond its envelope (bounded plain JSON). This release records `remoteMove` on
271
+ * `remote.set` and `remote.unset`; any other key is a later release's, kept and pruned as it wrote it.
272
+ */
273
+ export interface IControllerAuditEventDetails {
274
+ /** `remote.set` and `remote.unset` only: where the move goes from and to. */
275
+ remoteMove?: IControllerAuditRemoteMove;
276
+ [key: string]: unknown;
277
+ }
278
+
279
+ /** What this release records in an audit event's `details`. */
280
+ export interface IRecordAuditEventDetails {
281
+ /** `remote.set` and `remote.unset` only: where the move goes from and to. */
282
+ remoteMove: IControllerAuditRemoteMove;
283
+ }
284
+
253
285
  /**
254
286
  * A stored audit event. The audit log is shared with later releases, so a stored `type` is any audit type, also one
255
287
  * this release does not know (a later release's, read back after a rollback). This release writes only its own types
@@ -270,10 +302,10 @@ export interface IControllerAuditEvent {
270
302
  senderLabel?: string;
271
303
  localCli?: IConfigurationLocalCliActor;
272
304
  /**
273
- * What a later release's type records beyond the envelope (bounded plain JSON). This release never writes or
274
- * interprets it; it is declared so a rolled-back controller still reads and prunes such events.
305
+ * What the event records beyond the envelope (bounded plain JSON): this release's `remoteMove`, or what a later
306
+ * release's type adds, read back after a rollback.
275
307
  */
276
- details?: Record<string, unknown>;
308
+ details?: IControllerAuditEventDetails;
277
309
  }
278
310
 
279
311
  export interface IControllerTempPasswordDocument {
@@ -304,6 +336,7 @@ export interface IRecordAuditEventInput {
304
336
  /** The sender label an agent message declared (`session.message`). */
305
337
  senderLabel?: string;
306
338
  localCli?: IConfigurationLocalCliActor;
339
+ details?: IRecordAuditEventDetails;
307
340
  }
308
341
 
309
342
  export interface IConsumeCeremonyOptions {
@@ -13,8 +13,23 @@ export interface IControllerRuntimeConfig {
13
13
  projectsRoot: string;
14
14
  opencodePort: number;
15
15
  tlsMode: TControllerTlsMode;
16
+ /**
17
+ * TLS-proxy mode only: the addresses a gateway reaches this controller from (canonical IP literals, sorted, no
18
+ * duplicates). A request from any other address off loopback is refused, and without any the controller listens
19
+ * on loopback only. Present only while it names one; changed only by `agl remote set` against a stopped controller.
20
+ */
21
+ gatewaySources?: string[];
16
22
  }
17
23
 
24
+ /**
25
+ * What this release declares about gateway sources (`controllerGatewaySourcesVersion` in its `package.json`): it
26
+ * stores and enforces them as `IControllerRuntimeConfig.gatewaySources` holds them. 1 is that contract as AGL 42 ships
27
+ * it; only an incompatible change to it raises the number. A release that declares none (every release before 42)
28
+ * refuses to start on a configuration that names them, so an upgrade transaction records its source's declaration
29
+ * (`sourceGatewaySourcesVersion`) and a recovery never rolls back to a source without it while they are stored.
30
+ */
31
+ export const controllerGatewaySourcesVersion = 1 as const;
32
+
18
33
  export interface IControllerRuntimeOverrides {
19
34
  controllerPort: number;
20
35
  publicOrigin?: string;
@@ -2,6 +2,7 @@ import type { controllerServiceUnitName, IControllerStatus, TControllerProcessMo
2
2
  import type { IAuthoritySocketPaths } from './classes.authorityclient.js';
3
3
  import type { IControllerRuntimeOverrides } from './interfaces.config.js';
4
4
  import type * as plugins from './plugins.js';
5
+ import type { ITpmSecretCodec } from './classes.tpmsecretcodec.js';
5
6
 
6
7
  export interface IControllerStartOptions {
7
8
  processMode: TControllerProcessMode;
@@ -24,6 +25,8 @@ export interface IControllerStartOptions {
24
25
  codexAppServerScope?: plugins.authswitch.ICodexAppServerScopeOptions;
25
26
  /** Operator-provided first-start setup code; a random code is minted when absent. */
26
27
  setupCode?: string;
28
+ /** Seals the trusted-proxy secret in TLS-proxy mode; TPM2 (`TpmSecretCodec`) when absent. For tests. */
29
+ trustedProxySecretCodec?: ITpmSecretCodec;
27
30
  /** Private upgrade transaction token received over parent IPC. */
28
31
  upgradeToken?: string;
29
32
  upgradeGlobalRoot?: string;
@@ -1363,6 +1363,8 @@ export class AuthSwitchAuthorityDaemon {
1363
1363
  const answered: Promise<void> = router.routeAndAddResponse(request, { trustedLocalData: { authoritySocket: socket },
1364
1364
  trustedAbortSignal: abort.signal })
1365
1365
  .then(async response => {
1366
+ // Nothing to answer (the router refused the envelope): refuse it by closing, never with a bare null.
1367
+ if (response === null) { socket.destroy(); return; }
1366
1368
  // A client that is already gone is owed no answer.
1367
1369
  if (!socket.writable) return;
1368
1370
  const raw = JSON.stringify(response);
@@ -5,7 +5,7 @@ import type {
5
5
  TControllerBrowserPaintAvailability,
6
6
  TControllerBrowserPaintTermination,
7
7
  } from './browserpaint.js';
8
- export const controllerProtocolVersion = 47 as const;
8
+ export const controllerProtocolVersion = 48 as const;
9
9
  export const controllerUpgradeManagementVersion = 2 as const;
10
10
  export const controllerPackageName = 'agl' as const;
11
11
  /** The systemd user unit `agl service install` writes; a controller it runs reports it in its status. */
@@ -327,7 +327,7 @@ export interface IControllerStatus {
327
327
  upgradeManagementVersion: number;
328
328
  /**
329
329
  * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent
330
- * from a controller older than the endpoint, which is reached over its socket.
330
+ * from a controller older than the endpoint, which this release refuses to manage.
331
331
  */
332
332
  managementProtocolVersion?: number;
333
333
  controllerPid: number;
@@ -20,8 +20,8 @@ export const controllerManagementTypedRequestPath = '/management/typedrequest' a
20
20
  * shapes. 1 is the endpoint as its first release ships it; only an incompatible change to that contract raises it.
21
21
  * A release declares it twice: as `controllerManagementProtocolVersion` in its `package.json`, which a client reads
22
22
  * before the release's controller runs, and as `managementProtocolVersion` in that controller's status. A client
23
- * reaches a controller over this endpoint only when it declares 1 or more, and over the controller socket otherwise
24
- * (an older release has no endpoint).
23
+ * manages a controller over this endpoint only when it declares 1 or more; since AGL 42 a client refuses one that
24
+ * declares none (an older release has no endpoint, and its socket speaks TypedSocket 8).
25
25
  *
26
26
  * It is not `controllerUpgradeManagementVersion` (2), the upgrade contract: every upgrade worker requires exactly
27
27
  * that number in its target's `package.json` and status, and upgrade transactions record it, so it cannot move
@@ -46,12 +46,6 @@ import type {
46
46
  IReq_ControllerAccountsCodexRelease,
47
47
  } from './requests.accounts.js';
48
48
  import type { IReq_ControllerOpenCodeRestart, IReq_ControllerProxyStatusGet, IReq_ControllerRestart, IReq_ControllerStatus } from './requests.status.js';
49
- import type {
50
- IReq_ControllerUpgradeLaunch,
51
- IReq_ControllerUpgradePrepare,
52
- IReq_ControllerUpgradePrepareBegin,
53
- IReq_ControllerUpgradeFinalize,
54
- } from './requests.upgrade.js';
55
49
  import type {
56
50
  IReq_ControllerDriverGet,
57
51
  IReq_ControllerDriverEnsure,
@@ -253,10 +247,6 @@ export type TControllerRequest =
253
247
  | IReq_ControllerProxyStatusGet
254
248
  | IReq_ControllerOpenCodeRestart
255
249
  | IReq_ControllerRestart
256
- | IReq_ControllerUpgradeLaunch
257
- | IReq_ControllerUpgradePrepare
258
- | IReq_ControllerUpgradePrepareBegin
259
- | IReq_ControllerUpgradeFinalize
260
250
  | IReq_ControllerDriverGet
261
251
  | IReq_ControllerDriverEnsure
262
252
  | IReq_ControllerDriverSeen
@@ -16,22 +16,6 @@ export interface IReq_ControllerUpgradeLaunch extends plugins.typedrequestInterf
16
16
  };
17
17
  }
18
18
 
19
- export interface IReq_ControllerUpgradePrepare extends plugins.typedrequestInterfaces.implementsTR<
20
- plugins.typedrequestInterfaces.ITypedRequest,
21
- IReq_ControllerUpgradePrepare
22
- > {
23
- method: 'controller.upgrade.prepare';
24
- request: {
25
- token: string;
26
- targetVersion: string;
27
- gracePeriodMs: number;
28
- };
29
- response: {
30
- prepared: true;
31
- sessionCount: number;
32
- };
33
- }
34
-
35
19
  export interface IReq_ControllerUpgradePrepareBegin extends plugins.typedrequestInterfaces.implementsTR<
36
20
  plugins.typedrequestInterfaces.ITypedRequest,
37
21
  IReq_ControllerUpgradePrepareBegin
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '41.2.0',
6
+ version: '42.0.0',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }