agl 41.1.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 (106) hide show
  1. package/changelog.md +48 -0
  2. package/dist_serve/bundle.js +2190 -2193
  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.inferencegateway.js +4 -3
  23. package/dist_ts/classes.inferenceusage.d.ts +19 -7
  24. package/dist_ts/classes.inferenceusage.js +49 -13
  25. package/dist_ts/classes.inferenceusagetap.d.ts +15 -3
  26. package/dist_ts/classes.inferenceusagetap.js +16 -9
  27. package/dist_ts/classes.mcpcontrollerhost.js +9 -3
  28. package/dist_ts/classes.processinspection.d.ts +8 -1
  29. package/dist_ts/classes.processinspection.js +92 -2
  30. package/dist_ts/classes.proxycontrol.js +6 -1
  31. package/dist_ts/classes.proxydaemon.d.ts +2 -2
  32. package/dist_ts/classes.proxydaemon.js +1 -1
  33. package/dist_ts/classes.proxystore.d.ts +2 -11
  34. package/dist_ts/classes.proxystore.js +3 -25
  35. package/dist_ts/classes.tpmsecretcodec.d.ts +13 -0
  36. package/dist_ts/classes.tpmsecretcodec.js +28 -0
  37. package/dist_ts/classes.trustedproxysecrets.d.ts +91 -0
  38. package/dist_ts/classes.trustedproxysecrets.js +338 -0
  39. package/dist_ts/classes.upgradecoordinator.d.ts +14 -1
  40. package/dist_ts/classes.upgradecoordinator.js +21 -3
  41. package/dist_ts/classes.upgradetransaction.d.ts +32 -0
  42. package/dist_ts/classes.upgradetransaction.js +101 -4
  43. package/dist_ts/classes.usagefeed.js +3 -2
  44. package/dist_ts/functions.controlleradmission.d.ts +67 -0
  45. package/dist_ts/functions.controlleradmission.js +127 -0
  46. package/dist_ts/functions.remotecli.d.ts +27 -0
  47. package/dist_ts/functions.remotecli.js +236 -0
  48. package/dist_ts/functions.retiredenvironment.d.ts +11 -2
  49. package/dist_ts/functions.retiredenvironment.js +22 -5
  50. package/dist_ts/index.d.ts +1 -0
  51. package/dist_ts/index.js +2 -1
  52. package/dist_ts/interfaces.auth.d.ts +29 -4
  53. package/dist_ts/interfaces.auth.js +5 -1
  54. package/dist_ts/interfaces.config.d.ts +14 -0
  55. package/dist_ts/interfaces.config.js +9 -2
  56. package/dist_ts/interfaces.lifecycle.d.ts +3 -0
  57. package/dist_ts_authswitch/classes.authoritydaemon.js +6 -1
  58. package/dist_ts_interfaces/interfaces.d.ts +2 -2
  59. package/dist_ts_interfaces/interfaces.js +1 -1
  60. package/dist_ts_interfaces/management.d.ts +2 -2
  61. package/dist_ts_interfaces/management.js +2 -2
  62. package/dist_ts_interfaces/metrics.d.ts +29 -7
  63. package/dist_ts_interfaces/metrics.js +14 -1
  64. package/dist_ts_interfaces/requests.d.ts +1 -2
  65. package/dist_ts_interfaces/requests.js +1 -1
  66. package/dist_ts_interfaces/requests.upgrade.d.ts +0 -12
  67. package/package.json +12 -11
  68. package/readme.md +99 -28
  69. package/ts/00_commitinfo_data.ts +1 -1
  70. package/ts/aglapi/aglapisurface.document.ts +3 -3
  71. package/ts/classes.authmodels.ts +68 -25
  72. package/ts/classes.authstore.ts +151 -24
  73. package/ts/classes.cli.ts +38 -61
  74. package/ts/classes.config.ts +70 -21
  75. package/ts/classes.controller.ts +50 -163
  76. package/ts/classes.controllermanagement.ts +123 -49
  77. package/ts/classes.controllerservice.ts +3 -56
  78. package/ts/classes.inferencegateway.ts +3 -2
  79. package/ts/classes.inferenceusage.ts +58 -19
  80. package/ts/classes.inferenceusagetap.ts +27 -8
  81. package/ts/classes.mcpcontrollerhost.ts +10 -5
  82. package/ts/classes.processinspection.ts +84 -3
  83. package/ts/classes.proxycontrol.ts +2 -0
  84. package/ts/classes.proxydaemon.ts +3 -2
  85. package/ts/classes.proxystore.ts +4 -25
  86. package/ts/classes.tpmsecretcodec.ts +26 -0
  87. package/ts/classes.trustedproxysecrets.ts +317 -0
  88. package/ts/classes.upgradecoordinator.ts +33 -3
  89. package/ts/classes.upgradetransaction.ts +130 -1
  90. package/ts/classes.usagefeed.ts +2 -1
  91. package/ts/functions.controlleradmission.ts +168 -0
  92. package/ts/functions.remotecli.ts +264 -0
  93. package/ts/functions.retiredenvironment.ts +25 -3
  94. package/ts/index.ts +1 -0
  95. package/ts/interfaces.auth.ts +36 -3
  96. package/ts/interfaces.config.ts +15 -0
  97. package/ts/interfaces.lifecycle.ts +3 -0
  98. package/ts_authswitch/classes.authoritydaemon.ts +2 -0
  99. package/ts_interfaces/interfaces.ts +2 -2
  100. package/ts_interfaces/management.ts +2 -2
  101. package/ts_interfaces/metrics.ts +34 -7
  102. package/ts_interfaces/requests.ts +0 -10
  103. package/ts_interfaces/requests.upgrade.ts +0 -16
  104. package/ts_web/00_commitinfo_data.ts +1 -1
  105. package/ts_web/classes.controllersocketclient.ts +5 -2
  106. package/ts_web/elements.metricsboard.ts +68 -18
@@ -189,7 +189,7 @@ class ControllerMcpBoundedTypedRouter extends plugins.typedrequest.TypedRouter {
189
189
  >(
190
190
  typedRequestArg: T,
191
191
  optionsArg: plugins.typedrequest.ITypedRouterRouteOptions = {},
192
- ): Promise<T> {
192
+ ): Promise<T | null> {
193
193
  // The envelope is the only place the caller credential exists; typed handlers never see it.
194
194
  // Resolving here once and running the handler inside the caller context keeps authorization
195
195
  // out of every handler signature and needs no per-request bookkeeping to clean up.
@@ -201,7 +201,7 @@ class ControllerMcpBoundedTypedRouter extends plugins.typedrequest.TypedRouter {
201
201
  : { caller: this.resolveCaller(wireCaller?.credential), release: () => undefined };
202
202
  const caller = lease.caller.subject.kind === 'worker_launch' && !typedRequestArg.method.startsWith('agl.mcp.ticket.')
203
203
  ? anonymousControllerMcpCaller : lease.caller;
204
- let response: T;
204
+ let response: T | null;
205
205
  try {
206
206
  response = await runWithControllerMcpCaller(caller, async () => super.routeAndAddResponse(typedRequestArg, optionsArg));
207
207
  } finally {
@@ -221,17 +221,22 @@ class ControllerMcpBoundedTypedRouter extends plugins.typedrequest.TypedRouter {
221
221
  callerArg: IControllerMcpCaller,
222
222
  typedRequestArg: T,
223
223
  optionsArg: plugins.typedrequest.ITypedRouterRouteOptions,
224
- ): Promise<T> {
224
+ ): Promise<T | null> {
225
225
  return this.bounded(await runWithControllerMcpCaller(
226
226
  callerArg, async () => super.routeAndAddResponse(typedRequestArg, optionsArg),
227
227
  ));
228
228
  }
229
229
 
230
230
  /** What every answer leaves out and how large it may be. */
231
- private bounded<T extends plugins.typedrequestInterfaces.ITypedRequest>(response: T): T {
232
- if (!response) return response;
231
+ private bounded<T extends plugins.typedrequestInterfaces.ITypedRequest>(response: T | null): T | null {
232
+ // Nothing to answer: the router refused the envelope, and the transport refuses it in its own protocol.
233
+ if (response === null) return null;
233
234
  // A credential is never reflected back: the response carries exactly its documented keys.
234
235
  delete (response as unknown as Record<string, unknown>).caller;
236
+ // The private envelope's `response` is always an object, beside an `error` too: every `agl mcp` client sends `{}`
237
+ // and refuses anything else, an installed older one included. TypedRequest 9 answers `null` where TypedRequest 8
238
+ // returned the `{}` the client sent (an error, a handler that returns nothing), so the host restores it here.
239
+ if (response.response === null) (response as plugins.typedrequestInterfaces.ITypedRequest).response = {};
235
240
  if (typeof response.method === 'string' && (response.method.startsWith('agl.mcp.configuration.')
236
241
  || response.method.startsWith('agl.mcp.ticket.') || response.method.startsWith('agl.mcp.fleet.'))) {
237
242
  // TypedRequest normally echoes the request. The owner capability must not travel back in
@@ -20,7 +20,7 @@ export interface IControllerProcessCandidate {
20
20
  }
21
21
 
22
22
  export interface IControllerDataWriterProcessCandidate {
23
- kind: 'controller' | 'temp-password' | 'config' | 'flex-child';
23
+ kind: 'controller' | 'temp-password' | 'config' | 'remote' | 'flex-child';
24
24
  identity: IControllerProcessIdentity;
25
25
  /** Absolute path of the package entry file the process runs (`cli.js` or the Flex child). */
26
26
  entryPath: string;
@@ -461,7 +461,7 @@ const findInstalledControllerPackageFileArgument = (
461
461
  /** The installed `cli.js` path of a process running the given command, if any. */
462
462
  const findInstalledControllerCommandEntryPath = (
463
463
  identityArg: IControllerProcessIdentity,
464
- commandArg: '__serve' | 'foreground' | 'temp-password' | 'config',
464
+ commandArg: '__serve' | 'foreground' | 'temp-password' | 'config' | 'remote',
465
465
  ): string | undefined => {
466
466
  const cli = findInstalledControllerPackageFileArgument(identityArg.arguments, 'cli.js');
467
467
  return cli && identityArg.arguments[cli.index + 1] === commandArg ? cli.path : undefined;
@@ -595,6 +595,87 @@ export const listControllerProcessesForCli = async (
595
595
  return candidates.sort((leftArg, rightArg) => leftArg.identity.pid - rightArg.identity.pid);
596
596
  };
597
597
 
598
+ /**
599
+ * The listening sockets (their inodes) that take a connection to `127.0.0.1:<port>` on the addresses a controller
600
+ * binds: `127.0.0.1` in local mode and `0.0.0.0` behind a TLS proxy, as every release before the loopback management
601
+ * endpoint does.
602
+ */
603
+ const readLinuxControllerListenerInodes = async (portArg: number): Promise<Set<string>> => {
604
+ const port = portArg.toString(16).toUpperCase().padStart(4, '0');
605
+ const endpoints = new Set([`0100007F:${port}`, `00000000:${port}`]);
606
+ const inodes = new Set<string>();
607
+ for (const line of (await plugins.fs.promises.readFile('/proc/net/tcp', 'utf8')).split('\n').slice(1)) {
608
+ const fields = line.trim().split(/\s+/u);
609
+ if (fields.length >= 10 && endpoints.has(fields[1]) && fields[3] === '0A') inodes.add(fields[9]);
610
+ }
611
+ return inodes;
612
+ };
613
+
614
+ /** Whether the Linux process holds one of the sockets `inodesArg` names; one it cannot inspect holds none. */
615
+ const linuxProcessHoldsSocket = async (pidArg: number, inodesArg: ReadonlySet<string>): Promise<boolean> => {
616
+ const directory = `/proc/${pidArg}/fd`;
617
+ let names: string[];
618
+ try {
619
+ names = await plugins.fs.promises.readdir(directory);
620
+ } catch (errorArg) {
621
+ if (['ENOENT', 'ESRCH', 'EACCES', 'EPERM'].includes((errorArg as NodeJS.ErrnoException).code ?? '')) return false;
622
+ throw errorArg;
623
+ }
624
+ for (const name of names) {
625
+ let target: string;
626
+ try {
627
+ target = await plugins.fs.promises.readlink(plugins.path.join(directory, name));
628
+ } catch (errorArg) {
629
+ const code = (errorArg as NodeJS.ErrnoException).code ?? '';
630
+ if (code === 'ENOENT') continue;
631
+ if (['ESRCH', 'EACCES', 'EPERM'].includes(code)) return false;
632
+ throw errorArg;
633
+ }
634
+ const socket = /^socket:\[(\d+)\]$/u.exec(target);
635
+ if (socket && inodesArg.has(socket[1])) return true;
636
+ }
637
+ return false;
638
+ };
639
+
640
+ /** Whether the macOS process listens on `127.0.0.1:<port>` or on every address of that port. */
641
+ const macOsProcessHoldsControllerListener = async (pidArg: number, portArg: number): Promise<boolean> => {
642
+ const output = await execFile('/usr/sbin/lsof', [
643
+ '-nP', '-a', '-p', String(pidArg), `-iTCP:${portArg}`, '-sTCP:LISTEN', '-Fpn',
644
+ ], { emptyExitCode: 1, timeoutMs: 1_500, maxBufferBytes: 64 * 1024 });
645
+ const lines = output.split(/\r?\n/u);
646
+ return lines.includes(`p${pidArg}`)
647
+ && lines.some((lineArg) => lineArg === `n127.0.0.1:${portArg}` || lineArg === `n*:${portArg}`);
648
+ };
649
+
650
+ /**
651
+ * Whether the listener on `127.0.0.1:<port>` is an AGL controller of an installed package: a process running that
652
+ * package's `cli.js` (`node_modules/agl` or `node_modules/@modelprofile.com/harness-controller`) with the controller
653
+ * command (`__serve`, also as the service unit runs it, or `foreground`) for this port holds the port's listening
654
+ * socket. Linux reads the kernel's socket table, macOS asks `lsof`; elsewhere nothing confirms it.
655
+ */
656
+ export const installedControllerHoldsPort = async (portArg: number): Promise<boolean> => {
657
+ if (process.platform !== 'linux' && process.platform !== 'darwin') return false;
658
+ const candidates: number[] = [];
659
+ await visitProcessIdentities(async (identity) => {
660
+ const runsController = findInstalledControllerCommandEntryPath(identity, '__serve') !== undefined
661
+ || findInstalledControllerCommandEntryPath(identity, 'foreground') !== undefined;
662
+ if (runsController && readEffectiveArgvPort(identity.arguments) === portArg) candidates.push(identity.pid);
663
+ });
664
+ if (candidates.length === 0) return false;
665
+ if (process.platform === 'darwin') {
666
+ for (const pid of candidates) {
667
+ if (await macOsProcessHoldsControllerListener(pid, portArg)) return true;
668
+ }
669
+ return false;
670
+ }
671
+ const inodes = await readLinuxControllerListenerInodes(portArg);
672
+ if (inodes.size === 0) return false;
673
+ for (const pid of candidates) {
674
+ if (await linuxProcessHoldsSocket(pid, inodes)) return true;
675
+ }
676
+ return false;
677
+ };
678
+
598
679
  export const listControllerDataWriterProcessesForCli = async (
599
680
  cliPathArg: string,
600
681
  optionsArg: { includeInstalledPackagePaths?: boolean } = {},
@@ -631,7 +712,7 @@ export const listControllerDataWriterProcessesForCliPaths = async (
631
712
  ?? findInstalledControllerCommandEntryPath(identityArg, 'foreground');
632
713
  if (installedEntryPath) return { kind: 'controller', entryPath: installedEntryPath };
633
714
  }
634
- for (const command of ['temp-password', 'config'] as const) {
715
+ for (const command of ['temp-password', 'config', 'remote'] as const) {
635
716
  for (const cliPath of cliPaths) {
636
717
  if (await processIdentityHasCliCommand(identityArg, cliPath, command)) {
637
718
  return { kind: command, entryPath: cliPath };
@@ -421,6 +421,8 @@ export class AglProxyControlServer {
421
421
  void this.router.routeAndAddResponse(request, { trustedLocalData: { proxyConnection: connection },
422
422
  trustedAbortSignal: abort.signal })
423
423
  .then((responseArg) => {
424
+ // Nothing to answer (the router refused the envelope): refuse it by closing, never with a bare null.
425
+ if (responseArg === null) { socketArg.destroy(); return; }
424
426
  if (!socketArg.writable) return;
425
427
  const raw = JSON.stringify(responseArg) + '\n';
426
428
  if (Buffer.byteLength(raw) > proxyControlMaximumFrameBytes) { socketArg.destroy(); return; }
@@ -10,7 +10,8 @@ import { aglProxyConfinedClient, aglProxyConfinedOrigin, proxyClientNamePattern,
10
10
  import { AglProxyControlRefusal, AglProxyControlServer, type IAglProxyConfinedGrant, type IAglProxyConnection,
11
11
  type IAglProxyStatus, type IReq_AglProxyCatalog, type IReq_AglProxyConfined, type IReq_AglProxyReclaim,
12
12
  type TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
13
- import { ProxyStore, type IProxySecretCodec } from './classes.proxystore.js';
13
+ import { ProxyStore } from './classes.proxystore.js';
14
+ import type { ITpmSecretCodec } from './classes.tpmsecretcodec.js';
14
15
  import type { InferenceUsageStore } from './classes.inferenceusage.js';
15
16
  import { prepareProxyCredentialDirectory, proxyCredentialFile, removeProxyCredentialFile,
16
17
  writeProxyCredentialFile } from './functions.proxycredentialfile.js';
@@ -23,7 +24,7 @@ export interface IAglProxyDaemonOptions {
23
24
  credentialDirectory: string;
24
25
  authorityPaths: IAuthoritySocketPaths;
25
26
  port: number;
26
- codec?: IProxySecretCodec;
27
+ codec?: ITpmSecretCodec;
27
28
  providerFetch?: typeof fetch;
28
29
  limits?: IInferenceGatewayLimits;
29
30
  /** How long a lease kept across a restart waits for its holder; `proxyLeaseReclaimWindowMs` unless a test shortens it. */
@@ -1,5 +1,6 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import { EmbeddedControllerDatabase } from './classes.embeddeddb.js';
3
+ import { TpmSecretCodec, type ITpmSecretCodec } from './classes.tpmsecretcodec.js';
3
4
  import { InferenceAffinityModel, InferenceAffinityStore } from './classes.inferenceaffinity.js';
4
5
  import { InferenceSessionModel } from './classes.inferencesession.js';
5
6
  import { InferencePlacementModel, InferencePlacementStore } from './classes.inferenceplacement.js';
@@ -22,28 +23,6 @@ const maximumProxyClients = 32;
22
23
  /** The gateway admits 128 credentials in all; no more leases than that are ever kept. */
23
24
  const maximumProxyLeases = 128;
24
25
 
25
- /** Seals a client credential for this user and machine; only its ciphertext is stored. */
26
- export interface IProxySecretCodec {
27
- seal(nameArg: string, plaintextArg: Uint8Array): Promise<string>;
28
- unseal(nameArg: string, ciphertextArg: string): Promise<Uint8Array>;
29
- }
30
-
31
- /** TPM2-sealed credentials through `systemd-creds`, bound to their name. */
32
- export class ProxyTpmSecretCodec implements IProxySecretCodec {
33
- public async seal(nameArg: string, plaintextArg: Uint8Array): Promise<string> {
34
- const ciphertext = await plugins.smartsecret.sealSmartSecretTpm2Credential(nameArg, plaintextArg);
35
- try { return Buffer.from(ciphertext).toString('base64url'); }
36
- finally { ciphertext.fill(0); }
37
- }
38
-
39
- public async unseal(nameArg: string, ciphertextArg: string): Promise<Uint8Array> {
40
- if (!/^[A-Za-z0-9_-]{1,131072}$/.test(ciphertextArg)) throw new Error('Invalid sealed proxy credential.');
41
- const bytes = Buffer.from(ciphertextArg, 'base64url');
42
- try { return await plugins.smartsecret.unsealSmartSecretTpm2Credential(nameArg, bytes); }
43
- finally { bytes.fill(0); }
44
- }
45
- }
46
-
47
26
  export interface IProxyIdentityDocument {
48
27
  id: string;
49
28
  /** Names this proxy's authority bindings; independent of its port, so a restart reclaims exactly its own. */
@@ -215,7 +194,7 @@ let activeOwner: object | undefined;
215
194
  export interface IProxyStoreOptions {
216
195
  /** The proxy's own NoSQLDB storage root; no other process opens it. */
217
196
  dataDirectory: string;
218
- codec?: IProxySecretCodec;
197
+ codec?: ITpmSecretCodec;
219
198
  }
220
199
 
221
200
  export interface IProxyIdentity {
@@ -250,7 +229,7 @@ export interface IProxyLease {
250
229
  * is refused, so stopping the proxy never stops an engine someone else uses.
251
230
  */
252
231
  export class ProxyStore {
253
- private readonly codec: IProxySecretCodec;
232
+ private readonly codec: ITpmSecretCodec;
254
233
  private readonly owner = {};
255
234
  private embedded?: EmbeddedControllerDatabase;
256
235
  private database?: plugins.nosqldb.SmartdataDb;
@@ -258,7 +237,7 @@ export class ProxyStore {
258
237
 
259
238
  constructor(private readonly options: IProxyStoreOptions) {
260
239
  if (!plugins.path.isAbsolute(options.dataDirectory)) throw new Error('The proxy data directory must be absolute.');
261
- this.codec = options.codec ?? new ProxyTpmSecretCodec();
240
+ this.codec = options.codec ?? new TpmSecretCodec();
262
241
  }
263
242
 
264
243
  public async open(): Promise<IProxyIdentity> {
@@ -0,0 +1,26 @@
1
+ import * as plugins from './plugins.js';
2
+
3
+ /** Seals a secret for this user and machine under a name it is bound to; only its ciphertext is stored. */
4
+ export interface ITpmSecretCodec {
5
+ seal(nameArg: string, plaintextArg: Uint8Array): Promise<string>;
6
+ unseal(nameArg: string, ciphertextArg: string): Promise<Uint8Array>;
7
+ }
8
+
9
+ /**
10
+ * TPM2-sealed secrets through `systemd-creds`, bound to their name: the inference proxy's client credentials and
11
+ * signature key, and the controller's trusted-proxy secret.
12
+ */
13
+ export class TpmSecretCodec implements ITpmSecretCodec {
14
+ public async seal(nameArg: string, plaintextArg: Uint8Array): Promise<string> {
15
+ const ciphertext = await plugins.smartsecret.sealSmartSecretTpm2Credential(nameArg, plaintextArg);
16
+ try { return Buffer.from(ciphertext).toString('base64url'); }
17
+ finally { ciphertext.fill(0); }
18
+ }
19
+
20
+ public async unseal(nameArg: string, ciphertextArg: string): Promise<Uint8Array> {
21
+ if (!/^[A-Za-z0-9_-]{1,131072}$/.test(ciphertextArg)) throw new Error('Invalid sealed secret.');
22
+ const bytes = Buffer.from(ciphertextArg, 'base64url');
23
+ try { return await plugins.smartsecret.unsealSmartSecretTpm2Credential(nameArg, bytes); }
24
+ finally { bytes.fill(0); }
25
+ }
26
+ }
@@ -0,0 +1,317 @@
1
+ import * as plugins from './plugins.js';
2
+ import type { ITpmSecretCodec } from './classes.tpmsecretcodec.js';
3
+
4
+ /** One sealed generation of a controller's trusted-proxy secret. */
5
+ export interface IControllerTrustedProxySealedSecret {
6
+ /** Grows with every rotation and import; the secret is sealed under a name that binds it. */
7
+ generation: number;
8
+ /** TPM2-sealed (`TpmSecretCodec`); the plaintext exists only in the running controller and its gateway's route. */
9
+ ciphertext: string;
10
+ }
11
+
12
+ export interface IControllerTrustedProxySecretDocument {
13
+ /** The controller's id, `controller:<port>`. */
14
+ id: string;
15
+ /** The secret the controller accepts and its reverse proxy injects. */
16
+ active: IControllerTrustedProxySealedSecret;
17
+ /**
18
+ * A rotation its gateway's route does not carry yet: accepted beside `active` until `confirm` makes it the active
19
+ * one. Present only while a rotation is in progress.
20
+ */
21
+ next?: IControllerTrustedProxySealedSecret;
22
+ }
23
+
24
+ const isSealedSecret = (valueArg: unknown): valueArg is IControllerTrustedProxySealedSecret => {
25
+ const value = valueArg as Partial<IControllerTrustedProxySealedSecret> | null;
26
+ return !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 2
27
+ && Number.isSafeInteger(value.generation) && value.generation! >= 1
28
+ && typeof value.ciphertext === 'string' && /^[A-Za-z0-9_-]{1,131072}$/u.test(value.ciphertext);
29
+ };
30
+
31
+ const assertDocument: (valueArg: unknown) => asserts valueArg is IControllerTrustedProxySecretDocument = (valueArg) => {
32
+ const value = valueArg as Partial<IControllerTrustedProxySecretDocument> | null;
33
+ if (!value || typeof value !== 'object'
34
+ || Object.keys(value).length !== (Object.hasOwn(value, 'next') ? 3 : 2)
35
+ || typeof value.id !== 'string' || !/^controller:[1-9][0-9]{0,4}$/u.test(value.id)
36
+ || !isSealedSecret(value.active)
37
+ || (Object.hasOwn(value, 'next') && (!isSealedSecret(value.next) || value.next.generation !== value.active.generation + 1))) {
38
+ throw new Error('Invalid trusted-proxy secret record.');
39
+ }
40
+ };
41
+
42
+ @plugins.nosqldb.managed({ collectionName: 'agl_controller_trusted_proxy_secrets' })
43
+ @plugins.nosqldb.exactPersistence({ assertDocument })
44
+ export class ControllerTrustedProxySecretModel
45
+ extends plugins.nosqldb.SmartDataDbDoc<ControllerTrustedProxySecretModel, IControllerTrustedProxySecretDocument> {
46
+ declare static exact: plugins.nosqldb.TExact<ControllerTrustedProxySecretModel>;
47
+ @plugins.nosqldb.unI() public id!: string;
48
+ @plugins.nosqldb.svDb() public active!: IControllerTrustedProxySealedSecret;
49
+ @plugins.nosqldb.svDb() public next?: IControllerTrustedProxySealedSecret;
50
+ }
51
+
52
+ /** What a reverse proxy injects as `X-Harness-Controller-Proxy-Secret`: 32 random bytes, base64url (43 characters). */
53
+ const trustedProxySecretPattern = /^[A-Za-z0-9_-]{43}$/u;
54
+
55
+ /** The bytes a well-formed secret encodes; refused, naming the format but never the value, otherwise. */
56
+ export const decodeTrustedProxySecret = (valueArg: string): Buffer => {
57
+ const refusal = 'A trusted-proxy secret is 32 bytes, base64url-encoded (43 characters).';
58
+ if (!trustedProxySecretPattern.test(valueArg)) throw new Error(refusal);
59
+ const bytes = Buffer.from(valueArg, 'base64url');
60
+ if (bytes.byteLength !== 32 || bytes.toString('base64url') !== valueArg) {
61
+ bytes.fill(0);
62
+ throw new Error(refusal);
63
+ }
64
+ return bytes;
65
+ };
66
+
67
+ export interface IControllerTrustedProxySecretsOptions {
68
+ /** `controller:<port>`. */
69
+ controllerId: string;
70
+ /** The controller database's issuer id: the secret is sealed under a name bound to it. */
71
+ issuerId: string;
72
+ codec: ITpmSecretCodec;
73
+ }
74
+
75
+ /** The secret a gateway's route must carry, and the generation `confirm` names once the route carries it. */
76
+ export interface IControllerTrustedProxyRouteSecret {
77
+ secret: string;
78
+ generation: number;
79
+ }
80
+
81
+ interface IOpenSecret {
82
+ generation: number;
83
+ /** The base64url text's bytes, compared in constant time and wiped on close. */
84
+ text: Buffer;
85
+ }
86
+
87
+ const sealName = (optionsArg: Pick<IControllerTrustedProxySecretsOptions, 'controllerId' | 'issuerId'>, generationArg: number): string =>
88
+ `agl-controller.${optionsArg.issuerId.slice(0, 22)}.${optionsArg.controllerId.replace(':', '-')}.trusted-proxy.${generationArg}`;
89
+
90
+ const sealSecret = async (
91
+ optionsArg: IControllerTrustedProxySecretsOptions,
92
+ generationArg: number,
93
+ bytesArg: Buffer,
94
+ ): Promise<IControllerTrustedProxySealedSecret> => ({
95
+ generation: generationArg,
96
+ ciphertext: await optionsArg.codec.seal(sealName(optionsArg, generationArg), bytesArg),
97
+ });
98
+
99
+ const unsealSecret = async (
100
+ optionsArg: IControllerTrustedProxySecretsOptions,
101
+ sealedArg: IControllerTrustedProxySealedSecret,
102
+ ): Promise<IOpenSecret> => {
103
+ let bytes: Uint8Array;
104
+ try {
105
+ bytes = await optionsArg.codec.unseal(sealName(optionsArg, sealedArg.generation), sealedArg.ciphertext);
106
+ } catch (errorArg) {
107
+ throw new Error(`The trusted-proxy secret of ${optionsArg.controllerId} cannot be unsealed on this machine. Stop `
108
+ + 'the controller and import a secret with `agl remote secret import`.', { cause: errorArg });
109
+ }
110
+ try {
111
+ if (bytes.byteLength !== 32) throw new Error(`The sealed trusted-proxy secret of ${optionsArg.controllerId} is invalid.`);
112
+ return { generation: sealedArg.generation, text: Buffer.from(Buffer.from(bytes).toString('base64url'), 'utf8') };
113
+ } finally {
114
+ bytes.fill(0);
115
+ }
116
+ };
117
+
118
+ const readRecord = (controllerIdArg: string) => ControllerTrustedProxySecretModel.exact.findStoredOne({ id: controllerIdArg });
119
+
120
+ type TStoredRecord = NonNullable<Awaited<ReturnType<typeof readRecord>>>;
121
+
122
+ /**
123
+ * The trusted-proxy secret of a controller in TLS-proxy mode: AGL generates it, keeps it TPM2-sealed in the
124
+ * controller's database and hands it only to its own gateway's route (or an operator imports it for another reverse
125
+ * proxy). Admission accepts the active secret and, while a rotation is in progress, the next one: a rotation keeps
126
+ * the previous secret valid until the route carrying the new one is confirmed. One running controller owns the
127
+ * record; the offline `agl remote` commands write it only while that controller is stopped.
128
+ */
129
+ export class ControllerTrustedProxySecrets {
130
+ private mutationTail = Promise.resolve();
131
+ private closed = false;
132
+
133
+ private constructor(
134
+ private readonly options: IControllerTrustedProxySecretsOptions,
135
+ private active: IOpenSecret,
136
+ private next: IOpenSecret | undefined,
137
+ ) {}
138
+
139
+ /** Opens the record of `controllerId`, generating and sealing the first secret when it has none. */
140
+ public static async open(optionsArg: IControllerTrustedProxySecretsOptions): Promise<ControllerTrustedProxySecrets> {
141
+ let stored = await readRecord(optionsArg.controllerId);
142
+ if (!stored) {
143
+ const bytes = plugins.crypto.randomBytes(32);
144
+ let active: IControllerTrustedProxySealedSecret;
145
+ try { active = await sealSecret(optionsArg, 1, bytes); } finally { bytes.fill(0); }
146
+ const inserted = await ControllerTrustedProxySecretModel.exact.insert({ id: optionsArg.controllerId, active });
147
+ if (inserted.status !== 'inserted' && inserted.status !== 'already_committed' && inserted.status !== 'conflict') {
148
+ throw new Error('The trusted-proxy secret could not be stored.');
149
+ }
150
+ stored = await readRecord(optionsArg.controllerId);
151
+ if (!stored) throw new Error('The trusted-proxy secret could not be read back.');
152
+ }
153
+ const record = ControllerTrustedProxySecretModel.exact.toPersisted(stored);
154
+ const active = await unsealSecret(optionsArg, record.active);
155
+ try {
156
+ const next = record.next ? await unsealSecret(optionsArg, record.next) : undefined;
157
+ return new ControllerTrustedProxySecrets(optionsArg, active, next);
158
+ } catch (errorArg) {
159
+ active.text.fill(0);
160
+ throw errorArg;
161
+ }
162
+ }
163
+
164
+ /** Whether a request's header value is the active secret or the rotation's; constant time per secret. */
165
+ public accepts(valueArg: string | null): boolean {
166
+ if (valueArg === null || this.closed) return false;
167
+ const candidate = Buffer.from(valueArg, 'utf8');
168
+ let accepted = false;
169
+ for (const secret of [this.active, this.next]) {
170
+ if (secret && candidate.byteLength === secret.text.byteLength
171
+ && plugins.crypto.timingSafeEqual(candidate, secret.text)) accepted = true;
172
+ }
173
+ return accepted;
174
+ }
175
+
176
+ /** The secret the gateway's route must carry: the rotation's while one is in progress, else the active one. */
177
+ public routeSecret(): IControllerTrustedProxyRouteSecret {
178
+ this.assertOpen();
179
+ const secret = this.next ?? this.active;
180
+ return { secret: secret.text.toString('utf8'), generation: secret.generation };
181
+ }
182
+
183
+ /**
184
+ * Starts a rotation: a new secret, accepted beside the active one from now on, which the route must carry next.
185
+ * A rotation already in progress is returned again, so a sync that failed is retried with the same secret.
186
+ */
187
+ public rotate(): Promise<IControllerTrustedProxyRouteSecret> {
188
+ return this.mutate(async () => {
189
+ if (this.next) return { secret: this.next.text.toString('utf8'), generation: this.next.generation };
190
+ const current = await this.readOwnRecord();
191
+ const generation = this.active.generation + 1;
192
+ const bytes = plugins.crypto.randomBytes(32);
193
+ const text = Buffer.from(bytes.toString('base64url'), 'utf8');
194
+ let installed = false;
195
+ try {
196
+ let next: IControllerTrustedProxySealedSecret;
197
+ try {
198
+ next = await sealSecret(this.options, generation, bytes);
199
+ } finally {
200
+ bytes.fill(0);
201
+ }
202
+ this.assertOpen();
203
+ const result = await ControllerTrustedProxySecretModel.exact.transition({ current, change: (modelArg) => {
204
+ modelArg.next = next;
205
+ } });
206
+ if (result.status !== 'transitioned') throw new Error('The trusted-proxy secret changed concurrently.');
207
+ // Closed while the rotation was being stored: it is not installed here; the next open resumes it.
208
+ this.assertOpen();
209
+ this.next = { generation, text };
210
+ installed = true;
211
+ return { secret: text.toString('utf8'), generation };
212
+ } finally {
213
+ if (!installed) text.fill(0);
214
+ }
215
+ });
216
+ }
217
+
218
+ /**
219
+ * Ends a rotation once the route carries generation `generationArg`: it becomes the active secret and the previous
220
+ * one is refused from then on. Confirming the active generation again changes nothing; any other is refused.
221
+ */
222
+ public confirm(generationArg: number): Promise<void> {
223
+ return this.mutate(async () => {
224
+ if (!this.next && this.active.generation === generationArg) return;
225
+ if (!this.next || this.next.generation !== generationArg) {
226
+ throw new Error(`Generation ${generationArg} is not the trusted-proxy secret rotation in progress.`);
227
+ }
228
+ const current = await this.readOwnRecord();
229
+ const result = await ControllerTrustedProxySecretModel.exact.transition({ current, change: (modelArg) => {
230
+ modelArg.active = modelArg.next!;
231
+ delete modelArg.next;
232
+ } });
233
+ if (result.status !== 'transitioned') throw new Error('The trusted-proxy secret changed concurrently.');
234
+ // Closed while the confirmation was being stored: it stays stored, and the next open loads it as the active one.
235
+ this.assertOpen();
236
+ this.active.text.fill(0);
237
+ this.active = this.next;
238
+ this.next = undefined;
239
+ });
240
+ }
241
+
242
+ /**
243
+ * Forgets the secrets in memory; the record stays. A rotation or confirmation still running fails, and what it
244
+ * stored meanwhile is not installed: the next open resumes the rotation or loads the confirmed secret.
245
+ */
246
+ public close(): void {
247
+ this.closed = true;
248
+ this.active.text.fill(0);
249
+ this.next?.text.fill(0);
250
+ this.next = undefined;
251
+ }
252
+
253
+ private assertOpen(): void {
254
+ if (this.closed) throw new Error('The trusted-proxy secrets are closed.');
255
+ }
256
+
257
+ private mutate<T>(operationArg: () => Promise<T>): Promise<T> {
258
+ if (this.closed) return Promise.reject(new Error('The trusted-proxy secrets are closed.'));
259
+ const task = this.mutationTail.then(() => {
260
+ this.assertOpen();
261
+ return operationArg();
262
+ });
263
+ this.mutationTail = task.then(() => undefined, () => undefined);
264
+ return task;
265
+ }
266
+
267
+ /** The stored record, which must still hold exactly what this controller opened or wrote. */
268
+ private async readOwnRecord(): Promise<TStoredRecord> {
269
+ const stored = await readRecord(this.options.controllerId);
270
+ const record = stored ? ControllerTrustedProxySecretModel.exact.toPersisted(stored) : undefined;
271
+ if (!stored || record?.active.generation !== this.active.generation
272
+ || record.next?.generation !== this.next?.generation) {
273
+ throw new Error('The trusted-proxy secret changed outside this controller.');
274
+ }
275
+ return stored;
276
+ }
277
+ }
278
+
279
+ /**
280
+ * Replaces a stopped controller's trusted-proxy secret with one an operator chose for another reverse proxy; a
281
+ * rotation in progress ends with it. Returns the new generation. The secret is never logged or echoed.
282
+ */
283
+ export const importControllerTrustedProxySecret = async (
284
+ optionsArg: IControllerTrustedProxySecretsOptions & { secret: string },
285
+ ): Promise<{ generation: number }> => {
286
+ const bytes = decodeTrustedProxySecret(optionsArg.secret);
287
+ try {
288
+ const stored = await readRecord(optionsArg.controllerId);
289
+ const record = stored ? ControllerTrustedProxySecretModel.exact.toPersisted(stored) : undefined;
290
+ const generation = Math.max(record?.active.generation ?? 0, record?.next?.generation ?? 0) + 1;
291
+ const active = await sealSecret(optionsArg, generation, bytes);
292
+ if (!stored) {
293
+ const inserted = await ControllerTrustedProxySecretModel.exact.insert({ id: optionsArg.controllerId, active });
294
+ if (inserted.status !== 'inserted') throw new Error('The trusted-proxy secret changed concurrently.');
295
+ return { generation };
296
+ }
297
+ const result = await ControllerTrustedProxySecretModel.exact.transition({ current: stored, change: (modelArg) => {
298
+ modelArg.active = active;
299
+ delete modelArg.next;
300
+ } });
301
+ if (result.status !== 'transitioned') throw new Error('The trusted-proxy secret changed concurrently.');
302
+ return { generation };
303
+ } finally {
304
+ bytes.fill(0);
305
+ }
306
+ };
307
+
308
+ /** Removes a stopped controller's trusted-proxy secret; whether there was one. */
309
+ export const removeControllerTrustedProxySecret = async (controllerIdArg: string): Promise<boolean> => {
310
+ const stored = await readRecord(controllerIdArg);
311
+ if (!stored) return false;
312
+ const deleted = await ControllerTrustedProxySecretModel.exact.delete({ current: stored });
313
+ if (deleted.status !== 'deleted' && await readRecord(controllerIdArg)) {
314
+ throw new Error('The trusted-proxy secret could not be removed.');
315
+ }
316
+ return true;
317
+ };