@atcx/contract 7.6.0 → 7.7.1

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/README.md CHANGED
@@ -3,12 +3,12 @@
3
3
 
4
4
  <p>
5
5
  <a href="https://www.npmjs.com/package/@atcx/contract"><img src="https://img.shields.io/npm/v/@atcx/contract" alt="npm version"></a>
6
- <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.6.0/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
6
+ <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
7
7
  </p>
8
8
 
9
9
  <p>
10
- <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.6.0/docs/architecture/protocol/contract.md">The published contract</a> •
11
- <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.6.0/docs/architecture/protocol/protocol.md">The client protocol</a>
10
+ <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/architecture/protocol/contract.md">The published contract</a> •
11
+ <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/architecture/protocol/protocol.md">The client protocol</a>
12
12
  </p>
13
13
  </div>
14
14
 
@@ -46,15 +46,17 @@ bun add -d @opentelemetry/api
46
46
  for the session record a session's helpers read.
47
47
  - **Checking a daemon.** `checkDaemon` compares the major version in the hello answer with the
48
48
  contract's, and lists the features that differ.
49
+ - **The gateway.** `GATEWAY_PATHS`, the routes atc-gateway serves grouped as browser, machine and
50
+ probe paths, and `GATEWAY_REGISTRY_SCHEMA`, the rules of the gateway's registry file.
49
51
  - **The light entry.** `@atcx/contract/light` holds the session environment names, the state paths
50
52
  and the error codes without the request contract, for a process that starts once per event.
51
53
 
52
54
  ## Configuration
53
55
 
54
56
  `CONFIG_FILE_SCHEMA` parses the top-level keys of atc's `config.json`, and the
55
- [configuration guide](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.6.0/docs/guides/configuration.md) describes each key.
57
+ [configuration guide](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/guides/configuration.md) describes each key.
56
58
 
57
59
  ## Documentation
58
60
 
59
- [The published contract](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.6.0/docs/architecture/protocol/contract.md) covers what the package holds
61
+ [The published contract](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/architecture/protocol/contract.md) covers what the package holds
60
62
  and how its version moves with atc's.
@@ -5,6 +5,7 @@ export declare const DAEMON_CONTRACT: {
5
5
  client: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
6
6
  protocol: z.ZodOptional<z.ZodNumber>;
7
7
  principal: z.ZodOptional<z.ZodString>;
8
+ viewer: z.ZodOptional<z.ZodString>;
8
9
  session: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
9
10
  }, z.core.$strip>, z.ZodObject<{
10
11
  daemon: z.ZodString;
@@ -1,2 +1,2 @@
1
- export declare const DAEMON_FEATURES: readonly ['events.read.from-start'];
1
+ export declare const DAEMON_FEATURES: readonly ['events.read.from-start', 'daemon.hello.viewer'];
2
2
  export type DaemonFeature = (typeof DAEMON_FEATURES)[number];
@@ -0,0 +1,22 @@
1
+ export declare const GATEWAY_PATHS: {
2
+ readonly browser: {
3
+ readonly authorize: '/oauth2/authorize';
4
+ readonly login: '/login';
5
+ readonly enroll: '/enroll';
6
+ readonly consent: '/consent';
7
+ readonly error: '/error';
8
+ };
9
+ readonly machine: {
10
+ readonly mcp: '/mcp';
11
+ readonly root: '/';
12
+ readonly token: '/oauth2/token';
13
+ readonly revoke: '/oauth2/revoke';
14
+ readonly authorizationServerMetadata: '/.well-known/oauth-authorization-server';
15
+ readonly resourceMetadata: '/.well-known/oauth-protected-resource';
16
+ readonly mcpResourceMetadata: '/.well-known/oauth-protected-resource/mcp';
17
+ };
18
+ readonly probes: {
19
+ readonly health: '/healthz';
20
+ readonly ready: '/readyz';
21
+ };
22
+ };
@@ -0,0 +1,11 @@
1
+ import { z } from 'zod';
2
+ export declare const GATEWAY_REGISTRY_SCHEMA: z.ZodObject<{
3
+ daemons: z.ZodRecord<z.ZodString, z.ZodObject<{
4
+ address: z.ZodPipe<z.ZodString, z.ZodTransform<{
5
+ host: string;
6
+ port: number;
7
+ }, string>>;
8
+ daemonID: z.ZodString;
9
+ }, z.core.$strip>>;
10
+ defaultDaemon: z.ZodString;
11
+ }, z.core.$strip>;
package/dist/index.d.ts CHANGED
@@ -13,11 +13,15 @@ export * from './events-page.js';
13
13
  export type * from './daemon-id.js';
14
14
  export * from './fleet-entry-view.js';
15
15
  export * from './fleet-event.js';
16
+ export * from './gateway-paths.js';
17
+ export * from './gateway-registry-schema.js';
16
18
  export * from './git-probe-result.js';
17
19
  export * from './git-ref.js';
18
20
  export * from './grant-scope.js';
19
21
  export * from './hello-result.js';
20
22
  export * from './light/index.js';
23
+ export * from './max-events-cursor-bytes.js';
24
+ export * from './max-registry-daemons.js';
21
25
  export * from './menu-view.js';
22
26
  export * from './message-answer.js';
23
27
  export type * from './message-id.js';
package/dist/index.js CHANGED
@@ -110,10 +110,10 @@ var ANSWER_VIEW_SCHEMA = z4.object({
110
110
  complete: z4.boolean()
111
111
  });
112
112
  // packages/contract/src/contract-version.ts
113
- var CONTRACT_VERSION = "7.6.0";
113
+ var CONTRACT_VERSION = "7.7.1";
114
114
 
115
115
  // packages/contract/src/daemon-features.ts
116
- var DAEMON_FEATURES = ["events.read.from-start"];
116
+ var DAEMON_FEATURES = ["events.read.from-start", "daemon.hello.viewer"];
117
117
 
118
118
  // packages/contract/src/check-daemon.ts
119
119
  function checkDaemon(hello, contractVersion = CONTRACT_VERSION) {
@@ -694,6 +694,7 @@ var REQUEST_PARAM_SCHEMAS = {
694
694
  client: buildDefaultedString("unknown client"),
695
695
  protocol: z31.number({ error: "daemon.hello protocol must be a number" }).optional(),
696
696
  principal: z31.string({ error: "daemon.hello principal must be a non-empty string" }).min(1, "daemon.hello principal must be a non-empty string").optional(),
697
+ viewer: z31.string({ error: "daemon.hello viewer must be a non-empty string" }).min(1, "daemon.hello viewer must be a non-empty string").optional(),
697
698
  session: z31.preprocess((input) => typeof input === "string" && input !== "" ? input : undefined, z31.string().transform(toSessionID).optional())
698
699
  }),
699
700
  "daemon.ping": z31.object({}),
@@ -1034,6 +1035,82 @@ var DAEMON_CONTRACT = {
1034
1035
  get: base.meta(READ).input(PARAMS["answer.get"]).output(ANSWER_VIEW_SCHEMA)
1035
1036
  }
1036
1037
  };
1038
+ // packages/contract/src/gateway-paths.ts
1039
+ var GATEWAY_PATHS = {
1040
+ browser: {
1041
+ authorize: "/oauth2/authorize",
1042
+ login: "/login",
1043
+ enroll: "/enroll",
1044
+ consent: "/consent",
1045
+ error: "/error"
1046
+ },
1047
+ machine: {
1048
+ mcp: "/mcp",
1049
+ root: "/",
1050
+ token: "/oauth2/token",
1051
+ revoke: "/oauth2/revoke",
1052
+ authorizationServerMetadata: "/.well-known/oauth-authorization-server",
1053
+ resourceMetadata: "/.well-known/oauth-protected-resource",
1054
+ mcpResourceMetadata: "/.well-known/oauth-protected-resource/mcp"
1055
+ },
1056
+ probes: {
1057
+ health: "/healthz",
1058
+ ready: "/readyz"
1059
+ }
1060
+ };
1061
+ // packages/contract/src/gateway-registry-schema.ts
1062
+ import { z as z38 } from "zod";
1063
+
1064
+ // packages/contract/src/max-events-cursor-bytes.ts
1065
+ var MAX_EVENTS_CURSOR_BYTES = 4096;
1066
+
1067
+ // packages/contract/src/max-registry-daemons.ts
1068
+ var MAX_REGISTRY_DAEMONS = 36;
1069
+
1070
+ // packages/contract/src/gateway-registry-schema.ts
1071
+ var DAEMON_NAME_PATTERN = /^[a-z][a-z0-9-]{0,30}$/u;
1072
+ var ADDRESS_PATTERN = /^(?:\[(?<v6>[^\]]+)\]|(?<host>[^:[\]]+)):(?<port>\d{1,5})$/u;
1073
+ var ADDRESS_MESSAGE = "needs an address of <host>:<port> with a port from 1 to 65535";
1074
+ var ADDRESS_SCHEMA = z38.string({ error: ADDRESS_MESSAGE }).transform((raw, ctx) => {
1075
+ const groups = ADDRESS_PATTERN.exec(raw)?.groups;
1076
+ const host = groups?.["v6"] ?? groups?.["host"];
1077
+ const port = Number(groups?.["port"]);
1078
+ if (host === undefined || !Number.isInteger(port) || port < 1 || port > 65535) {
1079
+ ctx.issues.push({ code: "custom", message: ADDRESS_MESSAGE, input: raw });
1080
+ return z38.NEVER;
1081
+ }
1082
+ return { host, port };
1083
+ });
1084
+ var DAEMON_ID_MESSAGE = "needs the daemonID that atc daemon id prints on its host";
1085
+ var DAEMON_ID_SCHEMA2 = z38.string({ error: DAEMON_ID_MESSAGE }).regex(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/u, DAEMON_ID_MESSAGE);
1086
+ var DAEMON_SCHEMA = z38.object({ address: ADDRESS_SCHEMA, daemonID: DAEMON_ID_SCHEMA2 }, { error: "must be an object with address and daemonID" });
1087
+ var GATEWAY_REGISTRY_SCHEMA = z38.object({
1088
+ daemons: z38.record(z38.string().regex(DAEMON_NAME_PATTERN), DAEMON_SCHEMA, {
1089
+ error: (issue) => issue.code === "invalid_key" ? `must match ${DAEMON_NAME_PATTERN.source}` : "the registry must be an object whose daemons is an object"
1090
+ }),
1091
+ defaultDaemon: z38.string({
1092
+ error: "defaultDaemon is required and must name a daemon in the registry"
1093
+ })
1094
+ }, { error: "the registry must be an object whose daemons is an object" }).superRefine((registry, ctx) => {
1095
+ const count = Object.keys(registry.daemons).length;
1096
+ if (count === 0) {
1097
+ ctx.addIssue({ code: "custom", path: ["daemons"], message: "the registry lists no daemon" });
1098
+ }
1099
+ if (count > MAX_REGISTRY_DAEMONS) {
1100
+ ctx.addIssue({
1101
+ code: "custom",
1102
+ path: ["daemons"],
1103
+ message: `the registry lists ${count} daemons, over the limit of ${MAX_REGISTRY_DAEMONS}, the most whose events cursor fits ${MAX_EVENTS_CURSOR_BYTES} bytes`
1104
+ });
1105
+ }
1106
+ if (!Object.hasOwn(registry.daemons, registry.defaultDaemon)) {
1107
+ ctx.addIssue({
1108
+ code: "custom",
1109
+ path: ["defaultDaemon"],
1110
+ message: `defaultDaemon '${registry.defaultDaemon}' is not a daemon in the registry`
1111
+ });
1112
+ }
1113
+ });
1037
1114
  // packages/contract/src/light/resolve-atc-paths.ts
1038
1115
  import { join as join2 } from "node:path";
1039
1116
 
@@ -1076,11 +1153,11 @@ var SESSION_ENV_NAMES = {
1076
1153
  scopeFile: "AUTO_MODE_SCOPE_FILE"
1077
1154
  };
1078
1155
  // packages/contract/src/procedure-meta.ts
1079
- import { z as z38 } from "zod";
1080
- var PROCEDURE_META_SCHEMA = z38.object({
1081
- access: z38.enum(["owner", "principal"]),
1082
- readOnly: z38.boolean(),
1083
- keyed: z38.boolean()
1156
+ import { z as z39 } from "zod";
1157
+ var PROCEDURE_META_SCHEMA = z39.object({
1158
+ access: z39.enum(["owner", "principal"]),
1159
+ readOnly: z39.boolean(),
1160
+ keyed: z39.boolean()
1084
1161
  });
1085
1162
  export {
1086
1163
  AGENT_ENTRY_SCHEMA,
@@ -1097,10 +1174,14 @@ export {
1097
1174
  EVENTS_PAGE_SCHEMA,
1098
1175
  FLEET_ENTRY_VIEW_SCHEMA,
1099
1176
  FLEET_EVENT_SCHEMA,
1177
+ GATEWAY_PATHS,
1178
+ GATEWAY_REGISTRY_SCHEMA,
1100
1179
  GIT_PROBE_RESULT_SCHEMA,
1101
1180
  GIT_REF_SCHEMA,
1102
1181
  GRANT_SCOPES,
1103
1182
  HELLO_RESULT_SCHEMA,
1183
+ MAX_EVENTS_CURSOR_BYTES,
1184
+ MAX_REGISTRY_DAEMONS,
1104
1185
  MENU_VIEW_SCHEMA,
1105
1186
  MESSAGE_ANSWER_SCHEMA,
1106
1187
  MESSAGE_SENDER_SCHEMA,
@@ -0,0 +1 @@
1
+ export declare const MAX_EVENTS_CURSOR_BYTES = 4096;
@@ -0,0 +1 @@
1
+ export declare const MAX_REGISTRY_DAEMONS = 36;
@@ -22,6 +22,7 @@ export declare const REQUEST_PARAM_SCHEMAS: {
22
22
  client: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
23
23
  protocol: z.ZodOptional<z.ZodNumber>;
24
24
  principal: z.ZodOptional<z.ZodString>;
25
+ viewer: z.ZodOptional<z.ZodString>;
25
26
  session: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
26
27
  }, z.core.$strip>;
27
28
  readonly 'daemon.ping': z.ZodObject<{}, z.core.$strip>;
package/package.json CHANGED
@@ -18,8 +18,8 @@
18
18
  "zod": "4.6.6"
19
19
  },
20
20
  "name": "@atcx/contract",
21
- "version": "7.6.0",
22
- "description": "atc's public contract: the daemon's request contract, the event, session record, hello and config schemas, the error codes, the session env names, and the state paths",
21
+ "version": "7.7.1",
22
+ "description": "atc's public contract: the daemon's request contract, the event, session record, hello and config schemas, the error codes, the session env names, the state paths, and the gateway's routes and registry schema",
23
23
  "homepage": "https://github.com/zgeoff/atc/tree/main/packages/contract#readme",
24
24
  "bugs": "https://github.com/zgeoff/atc/issues",
25
25
  "license": "MIT",