@kici-dev/engine 0.0.0 → 0.1.1

package/dist/protocol/messages/common.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+/**
+ * Maximum decompressed WebSocket frame size accepted by every KiCI WS endpoint
+ * (Platform, orchestrator, agent — both server-side and client-side).
+ *
+ * Bounds per-frame memory allocation against `permessage-deflate`
+ * compression-bomb DoS. Without this cap, `ws@8.x` defaults to 100 MiB,
+ * which an unauthenticated attacker can exhaust on the Platform's
+ * `/ws` endpoint pre-auth via a single crafted compressed frame.
+ *
+ * 25 MiB matches `WEBHOOK_RELAY_MAX_BODY_BYTES` (and GitHub's own webhook
+ * payload cap). The chunked webhook-relay protocol breaks bodies into ~85 KiB
+ * frames anyway, so this leaves orders-of-magnitude headroom for every other
+ * legitimate WS frame in the system (log.chunk, state.replay, dashboard
+ * proxy responses, etc.).
+ *
+ * MUST be passed as `maxPayload` on every `new WebSocket(...)` constructor and
+ * on every `WebSocketServer` `options` object across the three packages.
+ */
+export declare const WS_MAX_PAYLOAD_BYTES: number;
+/**
+ * Heartbeat message sent periodically to keep WebSocket alive.
+ *
+ * FAST-PATHED: A manual validator exists in
+ * packages/orchestrator/src/ws/agent-handler.ts (isValidHeartbeat).
+ * If you change this schema, update the manual validator in the same commit.
+ * See CLAUDE.md rule: "Zod fast-path sync invariant".
+ */
+export declare const heartbeatSchema: z.ZodObject<{
+    type: z.ZodLiteral<"heartbeat">;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/** Acknowledgment of a received message. */
+export declare const ackSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    messageId: z.ZodString;
+}, z.core.$strip>;
+/** Negative acknowledgment - message received but could not be processed. */
+export declare const nackSchema: z.ZodObject<{
+    type: z.ZodLiteral<"nack">;
+    messageId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+/** Protocol-level error message. */
+export declare const errorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+/** Inferred types from schemas. */
+export type Heartbeat = z.infer<typeof heartbeatSchema>;
+export type Ack = z.infer<typeof ackSchema>;
+//# sourceMappingURL=common.d.ts.map

package/dist/protocol/messages/common.js

@@ -0,0 +1,55 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/common.ts
+/**
+* Maximum decompressed WebSocket frame size accepted by every KiCI WS endpoint
+* (Platform, orchestrator, agent — both server-side and client-side).
+*
+* Bounds per-frame memory allocation against `permessage-deflate`
+* compression-bomb DoS. Without this cap, `ws@8.x` defaults to 100 MiB,
+* which an unauthenticated attacker can exhaust on the Platform's
+* `/ws` endpoint pre-auth via a single crafted compressed frame.
+*
+* 25 MiB matches `WEBHOOK_RELAY_MAX_BODY_BYTES` (and GitHub's own webhook
+* payload cap). The chunked webhook-relay protocol breaks bodies into ~85 KiB
+* frames anyway, so this leaves orders-of-magnitude headroom for every other
+* legitimate WS frame in the system (log.chunk, state.replay, dashboard
+* proxy responses, etc.).
+*
+* MUST be passed as `maxPayload` on every `new WebSocket(...)` constructor and
+* on every `WebSocketServer` `options` object across the three packages.
+*/
+const WS_MAX_PAYLOAD_BYTES = 25 * 1024 * 1024;
+/**
+* Heartbeat message sent periodically to keep WebSocket alive.
+*
+* FAST-PATHED: A manual validator exists in
+* packages/orchestrator/src/ws/agent-handler.ts (isValidHeartbeat).
+* If you change this schema, update the manual validator in the same commit.
+* See CLAUDE.md rule: "Zod fast-path sync invariant".
+*/
+const heartbeatSchema = z.object({
+	type: z.literal("heartbeat"),
+	timestamp: z.number()
+});
+/** Acknowledgment of a received message. */
+const ackSchema = z.object({
+	type: z.literal("ack"),
+	messageId: z.string()
+});
+/** Negative acknowledgment - message received but could not be processed. */
+const nackSchema = z.object({
+	type: z.literal("nack"),
+	messageId: z.string(),
+	reason: z.string()
+});
+/** Protocol-level error message. */
+const errorSchema = z.object({
+	type: z.literal("error"),
+	code: z.string(),
+	message: z.string()
+});
+//#endregion
+export { WS_MAX_PAYLOAD_BYTES, ackSchema, errorSchema, heartbeatSchema, nackSchema };
+
+//# sourceMappingURL=common.js.map

package/dist/protocol/messages/dashboard-global-workflows.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Dashboard REST-over-WS protocol messages for org-level global workflow settings.
+ *
+ * Platform forwards these requests over the coordinator WS to the orchestrator,
+ * which owns the `org_settings` table. The orchestrator responds with the
+ * current (or patched) row projected into the shape below.
+ *
+ * Exposed via the `@kici-dev/engine/protocol/dashboard-global-workflows` subpath
+ * export (not the barrel) so server consumers can import without pulling
+ * anything unrelated into the dashboard bundle.
+ *
+ * Each repo-list entry is a `{routingKey?, pattern}` object. When
+ * `routingKey` is absent, the entry applies to events / workflows from any
+ * source in the org. When present, it qualifies the entry to a single
+ * webhook source (e.g., `github:42` vs `generic:org:abcd`).
+ *
+ * Three independent policy axes (see GlobalWorkflowPolicy in the orchestrator):
+ *   - `allowedRepos` restricts which repos may AUTHOR global workflows.
+ *   - `deniedRepos` blocks global dispatches for events FROM these SOURCE repos.
+ *   - `elevatedRepos` lists workflow-author repos with access to source secrets.
+ */
+import { z } from 'zod';
+/**
+ * One entry in any of the three repo-pattern lists. `routingKey` is the
+ * source-qualifier; when absent the entry applies to any source in the org.
+ */
+export declare const repoPatternEntrySchema: z.ZodObject<{
+    routingKey: z.ZodOptional<z.ZodString>;
+    pattern: z.ZodString;
+}, z.core.$strip>;
+export type RepoPatternEntry = z.infer<typeof repoPatternEntrySchema>;
+/** Projected org-level global workflow settings. */
+export declare const globalWorkflowSettingsSchema: z.ZodObject<{
+    customerId: z.ZodString;
+    enabled: z.ZodBoolean;
+    allowedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        routingKey: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>;
+    deniedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        routingKey: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>;
+    elevatedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        routingKey: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type GlobalWorkflowSettings = z.infer<typeof globalWorkflowSettingsSchema>;
+/** Request the current global-workflow settings row. */
+export declare const globalWorkflowsGetRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.global-workflows.get">;
+    requestId: z.ZodString;
+    actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        sub: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        keyId: z.ZodString;
+        ownerSub: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"service_account">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"platform_operator">;
+        sub: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"system">;
+        component: z.ZodString;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>;
+/**
+ * Patch the global-workflow settings row (upserts if missing).
+ *
+ * Every field is optional. `null` clears the corresponding list column
+ * (e.g., `allowedRepos: null` means "all repos pass the allow-list").
+ */
+export declare const globalWorkflowsUpdateRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.global-workflows.update">;
+    requestId: z.ZodString;
+    actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        sub: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        keyId: z.ZodString;
+        ownerSub: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"service_account">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"platform_operator">;
+        sub: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"system">;
+        component: z.ZodString;
+    }, z.core.$strip>], "type">;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    allowedRepos: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        routingKey: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>>;
+    deniedRepos: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        routingKey: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>>;
+    elevatedRepos: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        routingKey: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export declare const globalWorkflowsGetResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.global-workflows.get.response">;
+    requestId: z.ZodString;
+    settings: z.ZodOptional<z.ZodObject<{
+        customerId: z.ZodString;
+        enabled: z.ZodBoolean;
+        allowedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            routingKey: z.ZodOptional<z.ZodString>;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        deniedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            routingKey: z.ZodOptional<z.ZodString>;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        elevatedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            routingKey: z.ZodOptional<z.ZodString>;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const globalWorkflowsUpdateResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.global-workflows.update.response">;
+    requestId: z.ZodString;
+    settings: z.ZodOptional<z.ZodObject<{
+        customerId: z.ZodString;
+        enabled: z.ZodBoolean;
+        allowedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            routingKey: z.ZodOptional<z.ZodString>;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        deniedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            routingKey: z.ZodOptional<z.ZodString>;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        elevatedRepos: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            routingKey: z.ZodOptional<z.ZodString>;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GlobalWorkflowsGetRequest = z.infer<typeof globalWorkflowsGetRequestSchema>;
+export type GlobalWorkflowsUpdateRequest = z.infer<typeof globalWorkflowsUpdateRequestSchema>;
+export type GlobalWorkflowsGetResponse = z.infer<typeof globalWorkflowsGetResponseSchema>;
+export type GlobalWorkflowsUpdateResponse = z.infer<typeof globalWorkflowsUpdateResponseSchema>;
+//# sourceMappingURL=dashboard-global-workflows.d.ts.map

package/dist/protocol/messages/dashboard-global-workflows.js

@@ -0,0 +1,80 @@
+import "../../chunk-gOLHoazu.js";
+import { actorPrincipalSchema } from "./actor.js";
+import { z } from "zod";
+//#region src/protocol/messages/dashboard-global-workflows.ts
+/**
+* Dashboard REST-over-WS protocol messages for org-level global workflow settings.
+*
+* Platform forwards these requests over the coordinator WS to the orchestrator,
+* which owns the `org_settings` table. The orchestrator responds with the
+* current (or patched) row projected into the shape below.
+*
+* Exposed via the `@kici-dev/engine/protocol/dashboard-global-workflows` subpath
+* export (not the barrel) so server consumers can import without pulling
+* anything unrelated into the dashboard bundle.
+*
+* Each repo-list entry is a `{routingKey?, pattern}` object. When
+* `routingKey` is absent, the entry applies to events / workflows from any
+* source in the org. When present, it qualifies the entry to a single
+* webhook source (e.g., `github:42` vs `generic:org:abcd`).
+*
+* Three independent policy axes (see GlobalWorkflowPolicy in the orchestrator):
+*   - `allowedRepos` restricts which repos may AUTHOR global workflows.
+*   - `deniedRepos` blocks global dispatches for events FROM these SOURCE repos.
+*   - `elevatedRepos` lists workflow-author repos with access to source secrets.
+*/
+/**
+* One entry in any of the three repo-pattern lists. `routingKey` is the
+* source-qualifier; when absent the entry applies to any source in the org.
+*/
+const repoPatternEntrySchema = z.object({
+	routingKey: z.string().min(1).optional(),
+	pattern: z.string().min(1)
+});
+/** Projected org-level global workflow settings. */
+const globalWorkflowSettingsSchema = z.object({
+	customerId: z.string(),
+	enabled: z.boolean(),
+	allowedRepos: z.array(repoPatternEntrySchema).nullable(),
+	deniedRepos: z.array(repoPatternEntrySchema).nullable(),
+	elevatedRepos: z.array(repoPatternEntrySchema).nullable(),
+	createdAt: z.string().nullable(),
+	updatedAt: z.string().nullable()
+});
+/** Request the current global-workflow settings row. */
+const globalWorkflowsGetRequestSchema = z.object({
+	type: z.literal("dashboard.global-workflows.get"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema
+});
+/**
+* Patch the global-workflow settings row (upserts if missing).
+*
+* Every field is optional. `null` clears the corresponding list column
+* (e.g., `allowedRepos: null` means "all repos pass the allow-list").
+*/
+const globalWorkflowsUpdateRequestSchema = z.object({
+	type: z.literal("dashboard.global-workflows.update"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	enabled: z.boolean().optional(),
+	allowedRepos: z.array(repoPatternEntrySchema).nullable().optional(),
+	deniedRepos: z.array(repoPatternEntrySchema).nullable().optional(),
+	elevatedRepos: z.array(repoPatternEntrySchema).nullable().optional()
+});
+const globalWorkflowsGetResponseSchema = z.object({
+	type: z.literal("dashboard.global-workflows.get.response"),
+	requestId: z.string(),
+	settings: globalWorkflowSettingsSchema.optional(),
+	error: z.string().optional()
+});
+const globalWorkflowsUpdateResponseSchema = z.object({
+	type: z.literal("dashboard.global-workflows.update.response"),
+	requestId: z.string(),
+	settings: globalWorkflowSettingsSchema.optional(),
+	error: z.string().optional()
+});
+//#endregion
+export { globalWorkflowSettingsSchema, globalWorkflowsGetRequestSchema, globalWorkflowsGetResponseSchema, globalWorkflowsUpdateRequestSchema, globalWorkflowsUpdateResponseSchema, repoPatternEntrySchema };
+
+//# sourceMappingURL=dashboard-global-workflows.js.map