@kici-dev/engine 0.0.0 → 0.1.0

package/dist/protocol/messages/access-log.js

@@ -0,0 +1,175 @@
+import "../../chunk-gOLHoazu.js";
+import { ActorType, actorPrincipalSchema } from "./actor.js";
+import { z } from "zod";
+//#region src/protocol/messages/access-log.ts
+/**
+* Access log enums + dashboard protocol schemas.
+*
+* The orchestrator `access_log` table captures every read AND
+* orchestrator-admin mutation attributable to an ActorPrincipal. These enums
+* are the single source of truth for the column values; SQL, CLI filters,
+* dashboard UI, and tests all import from here.
+*
+* secret_audit_log stays as-is for secret *mutations* (create/update/delete).
+* access_log covers secret *reveals* (read-side attribution) and all other
+* reads/mutations surfaced via Platform proxy or orchestrator admin HTTP.
+*/
+/** Where the access-log entry was originated from. */
+const AccessLogSource = z.enum([
+	"platform_proxy",
+	"admin_http",
+	"admin_cli"
+]);
+/** Outcome of the attempted action. */
+const AccessLogOutcome = z.enum([
+	"allowed",
+	"denied",
+	"error"
+]);
+/** Target object category. */
+const AccessLogTargetType = z.enum([
+	"run",
+	"job",
+	"step",
+	"payload",
+	"event_log",
+	"event_log_payload",
+	"secret_scope",
+	"environment",
+	"registration",
+	"backend",
+	"diagnostics",
+	"scaler",
+	"held_run",
+	"access_log",
+	"event_dlq"
+]);
+/**
+* Dotted-namespace action names. Every handler that writes an access_log
+* row uses one of these values; a new handler means adding a new entry here.
+*/
+const AccessLogAction = z.enum([
+	"run.detail.read",
+	"run.payload.read",
+	"run.orch_logs.read",
+	"step.logs.read",
+	"run.cancel",
+	"run.rerun",
+	"run.manual_schedule",
+	"job.cancel",
+	"event_log.list.read",
+	"event_log.detail.read",
+	"event_log.payload.read",
+	"environment.list.read",
+	"environment.get.read",
+	"environment.create",
+	"environment.update",
+	"environment.delete",
+	"env_var.list.read",
+	"env_var.set",
+	"env_var.delete",
+	"source_override.list.read",
+	"source_override.set",
+	"source_override.delete",
+	"env_binding.list.read",
+	"env_binding.set",
+	"secret.list.read",
+	"secret.set",
+	"secret.delete",
+	"secret.reveal",
+	"secret_scope.create",
+	"secret_scope.rename",
+	"secret_scope.delete",
+	"environment.history.read",
+	"held_run.list.read",
+	"held_run.approve",
+	"held_run.reject",
+	"registration.list.read",
+	"registration.disable",
+	"registration.delete",
+	"diagnostics.read",
+	"scaler.capacity.read",
+	"scaler.agents.read",
+	"backend.list.read",
+	"backend.get.read",
+	"backend.sync",
+	"backend.sync.one",
+	"backend.test",
+	"global_workflows.get.read",
+	"global_workflows.update",
+	"access_log.list.read",
+	"event_dlq.list.read",
+	"event_dlq.retry",
+	"event_dlq.discard",
+	"archive_chunk"
+]);
+/**
+* Single row as surfaced to the dashboard / CLI. Includes optional
+* displayName/email for `user` and `platform_operator` actors — those are
+* resolved Platform-side by joining `actor_id` against the ZITADEL-backed
+* `users` table. The orchestrator never returns them; it emits a minimal
+* row and Platform enriches before forwarding to the browser.
+*/
+const accessLogItemSchema = z.object({
+	id: z.string(),
+	orgId: z.string().nullable(),
+	routingKey: z.string().nullable(),
+	actorType: ActorType,
+	actorId: z.string(),
+	actorMeta: z.record(z.string(), z.unknown()).nullable(),
+	/** Resolved by Platform when actor_type is user / platform_operator. */
+	actorEmail: z.string().nullable().optional(),
+	actorDisplayName: z.string().nullable().optional(),
+	action: AccessLogAction,
+	targetType: AccessLogTargetType.nullable(),
+	targetId: z.string().nullable(),
+	requestId: z.string().nullable(),
+	source: AccessLogSource,
+	outcome: AccessLogOutcome,
+	errorMessage: z.string().nullable(),
+	createdAt: z.string()
+});
+/** Shared filter shape reused by Platform proxy + orchestrator HTTP + CLI. */
+const accessLogFilterSchema = z.object({
+	actorType: ActorType.optional(),
+	actorId: z.string().optional(),
+	action: AccessLogAction.optional(),
+	source: AccessLogSource.optional(),
+	outcome: AccessLogOutcome.optional(),
+	targetType: AccessLogTargetType.optional(),
+	targetId: z.string().optional(),
+	fromTimestamp: z.string().optional(),
+	toTimestamp: z.string().optional(),
+	limit: z.number().int().positive().max(200).optional(),
+	cursor: z.string().optional()
+});
+const dashboardAccessLogListRequestSchema = z.object({
+	type: z.literal("dashboard.access-log.list"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	orgId: z.string(),
+	actorType: ActorType.optional(),
+	actorId: z.string().optional(),
+	action: AccessLogAction.optional(),
+	source: AccessLogSource.optional(),
+	outcome: AccessLogOutcome.optional(),
+	targetType: AccessLogTargetType.optional(),
+	targetId: z.string().optional(),
+	fromTimestamp: z.string().optional(),
+	toTimestamp: z.string().optional(),
+	/** Full-text search over `error_message` (trigram-indexed via migration 009). */
+	q: z.string().optional(),
+	limit: z.number().int().positive().max(200).optional(),
+	cursor: z.string().optional()
+});
+const dashboardAccessLogListResponseSchema = z.object({
+	type: z.literal("dashboard.access-log.list.response"),
+	requestId: z.string(),
+	items: z.array(accessLogItemSchema).optional(),
+	nextCursor: z.string().nullable().optional(),
+	error: z.string().optional()
+});
+//#endregion
+export { AccessLogAction, AccessLogOutcome, AccessLogSource, AccessLogTargetType, accessLogFilterSchema, accessLogItemSchema, dashboardAccessLogListRequestSchema, dashboardAccessLogListResponseSchema };
+
+//# sourceMappingURL=access-log.js.map

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

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+/**
+ * Typed actor principal for attributable reads, writes, and admin operations
+ * across the Platform → orchestrator and orchestrator → agent boundaries.
+ *
+ * Every dashboard.* / run.* proxy message carries an `actor` field so the
+ * orchestrator can write an `access_log` row attributable to a specific
+ * principal. The discriminated union prevents string-shape drift between
+ * tiers and encodes the reason for break-glass operator access at the
+ * protocol level rather than in free-text metadata.
+ */
+export declare const ActorType: z.ZodEnum<{
+    user: "user";
+    api_key: "api_key";
+    service_account: "service_account";
+    platform_operator: "platform_operator";
+    system: "system";
+}>;
+export type ActorType = z.infer<typeof ActorType>;
+export declare const userActorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    sub: z.ZodString;
+}, z.core.$strip>;
+export type UserActor = z.infer<typeof userActorSchema>;
+export declare const apiKeyActorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"api_key">;
+    keyId: z.ZodString;
+    ownerSub: z.ZodString;
+}, z.core.$strip>;
+export type ApiKeyActor = z.infer<typeof apiKeyActorSchema>;
+export declare const serviceAccountActorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"service_account">;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type ServiceAccountActor = z.infer<typeof serviceAccountActorSchema>;
+export declare const platformOperatorActorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"platform_operator">;
+    sub: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type PlatformOperatorActor = z.infer<typeof platformOperatorActorSchema>;
+export declare const systemActorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"system">;
+    component: z.ZodString;
+}, z.core.$strip>;
+export type SystemActor = z.infer<typeof systemActorSchema>;
+export declare const actorPrincipalSchema: 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">;
+export type ActorPrincipal = z.infer<typeof actorPrincipalSchema>;
+/**
+ * Convert an ActorPrincipal to a colon-prefixed string suitable for DB
+ * persistence in columns like `execution_runs.triggered_by` / `.cancelled_by`.
+ * The inverse of parseActor().
+ *
+ * Format: `${type}:${id}` where id is the variant's natural identifier.
+ * Extra metadata (api_key.ownerSub, platform_operator.reason) is NOT
+ * round-tripped through the string form — callers that need full fidelity
+ * must persist the actor object separately (e.g. in `access_log.actor_meta`).
+ */
+export declare function stringifyActor(actor: ActorPrincipal): string;
+/**
+ * Parse a `${type}:${id}` string back into a partial ActorPrincipal.
+ * Because the string form drops metadata, api_key.ownerSub and
+ * platform_operator.reason are null when the source is a string.
+ *
+ * Returns null for unrecognized inputs; callers that need strict parsing
+ * should throw on null.
+ */
+export declare function parseActor(value: string | null | undefined): {
+    type: ActorType;
+    id: string;
+} | null;
+/**
+ * Flatten an ActorPrincipal into the three columns the orchestrator
+ * `access_log` table uses: (actor_type, actor_id, actor_meta).
+ * actor_meta preserves the variant-specific extras that are lost in
+ * stringifyActor().
+ */
+export declare function flattenActor(actor: ActorPrincipal): {
+    actorType: ActorType;
+    actorId: string;
+    actorMeta: Record<string, unknown> | null;
+};
+//# sourceMappingURL=actor.d.ts.map

package/dist/protocol/messages/actor.js

@@ -0,0 +1,139 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/actor.ts
+/**
+* Typed actor principal for attributable reads, writes, and admin operations
+* across the Platform → orchestrator and orchestrator → agent boundaries.
+*
+* Every dashboard.* / run.* proxy message carries an `actor` field so the
+* orchestrator can write an `access_log` row attributable to a specific
+* principal. The discriminated union prevents string-shape drift between
+* tiers and encodes the reason for break-glass operator access at the
+* protocol level rather than in free-text metadata.
+*/
+const ActorType = z.enum([
+	"user",
+	"api_key",
+	"service_account",
+	"platform_operator",
+	"system"
+]);
+const userActorSchema = z.object({
+	type: z.literal(ActorType.enum.user),
+	/** ZITADEL subject. */
+	sub: z.string().min(1)
+});
+const apiKeyActorSchema = z.object({
+	type: z.literal(ActorType.enum.api_key),
+	/** Opaque key identifier (not the secret). */
+	keyId: z.string().min(1),
+	/** ZITADEL sub of the human who owns this key. */
+	ownerSub: z.string().min(1)
+});
+const serviceAccountActorSchema = z.object({
+	type: z.literal(ActorType.enum.service_account),
+	/** Service-account identifier (orchestrator admin tokens, CI bot tokens, etc.). */
+	id: z.string().min(1)
+});
+const platformOperatorActorSchema = z.object({
+	type: z.literal(ActorType.enum.platform_operator),
+	/** ZITADEL sub of the SaaS operator performing break-glass access. */
+	sub: z.string().min(1),
+	/**
+	* Free-text justification recorded in `access_log.actor_meta.reason`.
+	* Length bounds reject empty / obviously-bad-faith values; not a ticket
+	* pattern (we support multiple incident systems).
+	*/
+	reason: z.string().min(10).max(200)
+});
+const systemActorSchema = z.object({
+	type: z.literal(ActorType.enum.system),
+	/** Subsystem initiating the action (e.g. 'scheduler', 'retry', 'cleanup'). */
+	component: z.string().min(1)
+});
+const actorPrincipalSchema = z.discriminatedUnion("type", [
+	userActorSchema,
+	apiKeyActorSchema,
+	serviceAccountActorSchema,
+	platformOperatorActorSchema,
+	systemActorSchema
+]);
+/**
+* Convert an ActorPrincipal to a colon-prefixed string suitable for DB
+* persistence in columns like `execution_runs.triggered_by` / `.cancelled_by`.
+* The inverse of parseActor().
+*
+* Format: `${type}:${id}` where id is the variant's natural identifier.
+* Extra metadata (api_key.ownerSub, platform_operator.reason) is NOT
+* round-tripped through the string form — callers that need full fidelity
+* must persist the actor object separately (e.g. in `access_log.actor_meta`).
+*/
+function stringifyActor(actor) {
+	switch (actor.type) {
+		case "user": return `user:${actor.sub}`;
+		case "api_key": return `api_key:${actor.keyId}`;
+		case "service_account": return `service_account:${actor.id}`;
+		case "platform_operator": return `platform_operator:${actor.sub}`;
+		case "system": return `system:${actor.component}`;
+	}
+}
+/**
+* Parse a `${type}:${id}` string back into a partial ActorPrincipal.
+* Because the string form drops metadata, api_key.ownerSub and
+* platform_operator.reason are null when the source is a string.
+*
+* Returns null for unrecognized inputs; callers that need strict parsing
+* should throw on null.
+*/
+function parseActor(value) {
+	if (value == null || value === "") return null;
+	const idx = value.indexOf(":");
+	if (idx < 1 || idx === value.length - 1) return null;
+	const prefix = value.slice(0, idx);
+	const id = value.slice(idx + 1);
+	const parsed = ActorType.safeParse(prefix);
+	if (!parsed.success) return null;
+	return {
+		type: parsed.data,
+		id
+	};
+}
+/**
+* Flatten an ActorPrincipal into the three columns the orchestrator
+* `access_log` table uses: (actor_type, actor_id, actor_meta).
+* actor_meta preserves the variant-specific extras that are lost in
+* stringifyActor().
+*/
+function flattenActor(actor) {
+	switch (actor.type) {
+		case "user": return {
+			actorType: "user",
+			actorId: actor.sub,
+			actorMeta: null
+		};
+		case "api_key": return {
+			actorType: "api_key",
+			actorId: actor.keyId,
+			actorMeta: { ownerSub: actor.ownerSub }
+		};
+		case "service_account": return {
+			actorType: "service_account",
+			actorId: actor.id,
+			actorMeta: null
+		};
+		case "platform_operator": return {
+			actorType: "platform_operator",
+			actorId: actor.sub,
+			actorMeta: { reason: actor.reason }
+		};
+		case "system": return {
+			actorType: "system",
+			actorId: actor.component,
+			actorMeta: null
+		};
+	}
+}
+//#endregion
+export { ActorType, actorPrincipalSchema, apiKeyActorSchema, flattenActor, parseActor, platformOperatorActorSchema, serviceAccountActorSchema, stringifyActor, systemActorSchema, userActorSchema };
+
+//# sourceMappingURL=actor.js.map

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

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+/** Auth request sent by orchestrator to Platform when connecting via WebSocket. */
+export declare const authRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.request">;
+    token: z.ZodString;
+    protocolVersion: z.ZodNumber;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        orchRole: z.ZodOptional<z.ZodEnum<{
+            coordinator: "coordinator";
+            worker: "worker";
+        }>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+/** Auth success response sent by Platform to orchestrator after successful authentication. */
+export declare const authSuccessSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.success">;
+    connectionId: z.ZodString;
+    orgPublicAlias: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Auth failure response sent by Platform to orchestrator when authentication fails. */
+export declare const authFailureSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.failure">;
+    reason: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/protocol/messages/auth.js

@@ -0,0 +1,36 @@
+import "../../chunk-gOLHoazu.js";
+import { orchCapabilitiesSchema } from "./capabilities.js";
+import { z } from "zod";
+//#region src/protocol/messages/auth.ts
+/** Auth request sent by orchestrator to Platform when connecting via WebSocket. */
+const authRequestSchema = z.object({
+	type: z.literal("auth.request"),
+	token: z.string().min(1),
+	protocolVersion: z.number().int().positive(),
+	/** Orchestrator capabilities (optional for backward compat with pre-capability orchestrators). */
+	capabilities: orchCapabilitiesSchema.optional()
+});
+/** Auth success response sent by Platform to orchestrator after successful authentication. */
+const authSuccessSchema = z.object({
+	type: z.literal("auth.success"),
+	connectionId: z.string(),
+	/**
+	* Public alias of the authenticated orchestrator's owning org
+	* (`oal_<12-char>`). Used by the orchestrator's check-run emitter to
+	* build a `details_url` that points at the dashboard's resolver
+	* route, so the canonical `org_<12-char>` id never appears in URLs
+	* that reach public surfaces. Optional for back-compat with Platforms
+	* that don't yet supply it; when absent, the orchestrator skips
+	* `details_url` (preserving today's behaviour).
+	*/
+	orgPublicAlias: z.string().optional()
+});
+/** Auth failure response sent by Platform to orchestrator when authentication fails. */
+const authFailureSchema = z.object({
+	type: z.literal("auth.failure"),
+	reason: z.string()
+});
+//#endregion
+export { authFailureSchema, authRequestSchema, authSuccessSchema };
+
+//# sourceMappingURL=auth.js.map