@a5c-ai/krate 5.0.1-staging.660d2b90f → 5.0.1-staging.69cb593ea

package/src/async-controller.js

@@ -0,0 +1,207 @@
+/**
+ * Async controller utilities for event batching, retry policies, delivery queues,
+ * and checkpoint persistence.
+ */
+
+// ---------------------------------------------------------------------------
+// Event batcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Accumulates events and flushes them in batches either when the batch is full
+ * or when the flush interval expires.
+ *
+ * @param {(events: any[]) => void | Promise<void>} handler - Called with each flushed batch.
+ * @param {{ maxBatchSize?: number, flushIntervalMs?: number }} [options]
+ * @returns {{ push(event: any): void, flush(): Promise<void>, stop(): void }}
+ */
+export function createEventBatcher(handler, { maxBatchSize = 50, flushIntervalMs = 1000 } = {}) {
+  let batch = [];
+  let timer = null;
+
+  function scheduleFlush() {
+    if (timer !== null) return;
+    timer = setTimeout(async () => {
+      timer = null;
+      await flushNow();
+    }, flushIntervalMs);
+  }
+
+  async function flushNow() {
+    if (batch.length === 0) return;
+    const toFlush = batch;
+    batch = [];
+    await handler(toFlush);
+  }
+
+  return {
+    push(event) {
+      batch.push(event);
+      if (batch.length >= maxBatchSize) {
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        // Fire-and-forget the synchronous portion; handler may return a Promise
+        const toFlush = batch;
+        batch = [];
+        Promise.resolve(handler(toFlush)).catch(() => {});
+      } else {
+        scheduleFlush();
+      }
+    },
+    async flush() {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      await flushNow();
+    },
+    stop() {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      batch = [];
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Retry policy
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a retry policy with exponential backoff and optional jitter.
+ *
+ * @param {{ maxRetries?: number, baseDelayMs?: number, maxDelayMs?: number, jitter?: boolean }} [options]
+ * @returns {{ shouldRetry(attempt: number, error: any): boolean, getDelay(attempt: number): number }}
+ */
+export function createRetryPolicy({ maxRetries = 3, baseDelayMs = 1000, maxDelayMs = 30000, jitter = true } = {}) {
+  return {
+    /**
+     * Returns true if another attempt should be made.
+     * @param {number} attempt - 0-based number of the attempt that just failed.
+     */
+    shouldRetry(attempt, _error) {
+      return attempt < maxRetries;
+    },
+    /**
+     * Returns the delay in ms to wait before the next attempt.
+     * @param {number} attempt - 0-based number of the attempt that just failed.
+     */
+    getDelay(attempt) {
+      const exponential = baseDelayMs * Math.pow(2, attempt);
+      const capped = Math.min(exponential, maxDelayMs);
+      if (!jitter) return capped;
+      // Full-jitter: random value in [0, capped]
+      return Math.floor(Math.random() * (capped + 1));
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Delivery queue
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory ordered queue with configurable concurrency and optional retry support.
+ *
+ * @param {(item: any) => Promise<void>} processor - Called for each dequeued item.
+ * @param {{ concurrency?: number, retryPolicy?: ReturnType<typeof createRetryPolicy> }} [options]
+ * @returns {{ enqueue(item: any): void, drain(): Promise<void>, size(): number, stop(): void }}
+ */
+export function createDeliveryQueue(processor, { concurrency = 5, retryPolicy } = {}) {
+  const queue = [];
+  let active = 0;
+  let stopped = false;
+  /** @type {Array<() => void>} */
+  let drainResolvers = [];
+
+  function checkDrain() {
+    if (active === 0 && queue.length === 0) {
+      for (const resolve of drainResolvers) resolve();
+      drainResolvers = [];
+    }
+  }
+
+  async function processItem(item) {
+    let attempt = 0;
+    while (true) {
+      try {
+        await processor(item);
+        return;
+      } catch (err) {
+        if (retryPolicy && retryPolicy.shouldRetry(attempt, err)) {
+          const delay = retryPolicy.getDelay(attempt);
+          attempt++;
+          if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+        } else {
+          // Swallow the error; callers can handle via processor rejections externally
+          return;
+        }
+      }
+    }
+  }
+
+  function tick() {
+    while (!stopped && queue.length > 0 && active < concurrency) {
+      const item = queue.shift();
+      active++;
+      processItem(item).finally(() => {
+        active--;
+        tick();
+        checkDrain();
+      });
+    }
+    if (!stopped) checkDrain();
+  }
+
+  return {
+    enqueue(item) {
+      if (stopped) return;
+      queue.push(item);
+      tick();
+    },
+    drain() {
+      if (active === 0 && queue.length === 0) return Promise.resolve();
+      return new Promise((resolve) => drainResolvers.push(resolve));
+    },
+    size() {
+      return queue.length + active;
+    },
+    stop() {
+      stopped = true;
+      queue.length = 0;
+      for (const resolve of drainResolvers) resolve();
+      drainResolvers = [];
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Checkpointer
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple key-value checkpoint persistence backed by any Map-like storage.
+ *
+ * @param {Map<string, any>} [storage]
+ * @returns {{ save(key: string, value: any): void, load(key: string): any, clear(key: string): void, listKeys(): string[] }}
+ */
+export function createCheckpointer(storage = new Map()) {
+  return {
+    save(key, value) {
+      storage.set(key, value);
+    },
+    load(key) {
+      return storage.has(key) ? storage.get(key) : undefined;
+    },
+    clear(key) {
+      storage.delete(key);
+    },
+    listKeys() {
+      return Array.from(storage.keys());
+    },
+  };
+}

package/src/audit-controller.js

@@ -0,0 +1,191 @@
+/**
+ * Audit Controller — Org-scoped audit log, event streaming, smart polling with
+ * exponential backoff, replay on reconnect, and metrics aggregation.
+ *
+ * @module audit-controller
+ */
+
+export const AUDIT_CONTROLLER_BOUNDARY = {
+  role: 'audit-controller',
+  scope: 'Org-scoped audit log — event recording, streaming, replay, metrics',
+  owns: ['audit events', 'event streaming', 'event polling', 'audit metrics'],
+  delegatesTo: [],
+  mustNotOwn: ['identity management', 'resource storage', 'git operations'],
+};
+
+// ─── AuditController ─────────────────────────────────────────────────────────
+
+/**
+ * Create an in-memory audit controller.
+ *
+ * @returns {{
+ *   log: Function,
+ *   query: Function,
+ *   getStream: Function,
+ *   getMetrics: Function,
+ * }}
+ */
+export function createAuditController() {
+  /** @type {Array<AuditEvent>} */
+  const store = [];
+  let seq = 0;
+
+  return {
+    role: 'audit-controller',
+
+    /**
+     * Record an audit event.
+     *
+     * @param {{ org: string, actor?: string, action: string, resource?: object, timestamp?: string }} params
+     * @returns {AuditEvent}
+     */
+    log({ org, actor = 'system', action, resource = {}, timestamp } = {}) {
+      if (!org || typeof org !== 'string') {
+        throw new Error('audit.log: org is required');
+      }
+      if (!action || typeof action !== 'string') {
+        throw new Error('audit.log: action is required');
+      }
+
+      const event = {
+        id: ++seq,
+        org,
+        actor,
+        action,
+        resource: Object.assign({}, resource),
+        timestamp: timestamp || new Date().toISOString(),
+      };
+
+      store.push(event);
+      return Object.assign({}, event);
+    },
+
+    /**
+     * Query audit events with filtering and pagination.
+     *
+     * @param {{ org?: string, action?: string, since?: string, until?: string, limit?: number, offset?: number }} params
+     * @returns {{ events: AuditEvent[], total: number }}
+     */
+    query({ org, action, since, until, limit, offset = 0 } = {}) {
+      let filtered = store.slice();
+
+      if (org) filtered = filtered.filter(e => e.org === org);
+      if (action) filtered = filtered.filter(e => e.action === action);
+
+      if (since) {
+        const sinceMs = new Date(since).getTime();
+        filtered = filtered.filter(e => new Date(e.timestamp).getTime() >= sinceMs);
+      }
+      if (until) {
+        const untilMs = new Date(until).getTime();
+        filtered = filtered.filter(e => new Date(e.timestamp).getTime() <= untilMs);
+      }
+
+      // reverse chronological
+      filtered = filtered.slice().sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+      const total = filtered.length;
+      filtered = filtered.slice(offset);
+      if (limit != null) filtered = filtered.slice(0, limit);
+
+      return { events: filtered.map(e => Object.assign({}, e)), total };
+    },
+
+    /**
+     * Return all events after the given sequence number for a given org (event replay).
+     *
+     * @param {{ org?: string, afterSeq: number }} params
+     * @returns {{ events: AuditEvent[], lastSeq: number }}
+     */
+    getStream({ org, afterSeq = 0 } = {}) {
+      let filtered = store.filter(e => e.id > afterSeq);
+      if (org) filtered = filtered.filter(e => e.org === org);
+      // chronological order for stream replay
+      filtered = filtered.slice().sort((a, b) => a.id - b.id);
+      return {
+        events: filtered.map(e => Object.assign({}, e)),
+        lastSeq: filtered.length > 0 ? filtered[filtered.length - 1].id : afterSeq,
+      };
+    },
+
+    /**
+     * Aggregate audit metrics for an org.
+     *
+     * @param {{ org?: string }} params
+     * @returns {{ byAction: object, byOrg: object, byHour: object, total: number }}
+     */
+    getMetrics({ org } = {}) {
+      let events = store.slice();
+      if (org) events = events.filter(e => e.org === org);
+
+      const byAction = {};
+      const byOrg = {};
+      const byHour = {};
+
+      for (const event of events) {
+        byAction[event.action] = (byAction[event.action] || 0) + 1;
+        byOrg[event.org] = (byOrg[event.org] || 0) + 1;
+        // hour key: "2026-05-13T10" (drop minutes/seconds)
+        const hourKey = event.timestamp.slice(0, 13);
+        byHour[hourKey] = (byHour[hourKey] || 0) + 1;
+      }
+
+      return { byAction, byOrg, byHour, total: events.length };
+    },
+  };
+}
+
+// ─── EventPoller ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a smart event poller with exponential backoff.
+ *
+ * When polls return no new events the backoff interval doubles (up to maxBackoff).
+ * When new events arrive the backoff resets to initialBackoff.
+ *
+ * @param {{ controller: object, org?: string, initialBackoff?: number, maxBackoff?: number }} options
+ * @returns {{ poll: Function, getBackoff: Function, reset: Function }}
+ */
+export function createEventPoller({ controller, org, initialBackoff = 1000, maxBackoff = 30000 } = {}) {
+  let lastSeq = 0;
+  let currentBackoff = initialBackoff;
+
+  return {
+    /**
+     * Poll for new events.  Updates backoff state.
+     * @returns {{ events: AuditEvent[], lastSeq: number }}
+     */
+    poll() {
+      const result = controller.getStream({ org, afterSeq: lastSeq });
+      if (result.events.length > 0) {
+        // New events — reset backoff and advance cursor
+        lastSeq = result.lastSeq;
+        currentBackoff = initialBackoff;
+      } else {
+        // No new events — double the backoff, capped at maxBackoff
+        currentBackoff = Math.min(currentBackoff * 2, maxBackoff);
+      }
+      return result;
+    },
+
+    /**
+     * Get the current backoff interval in milliseconds.
+     * @returns {number}
+     */
+    getBackoff() {
+      return currentBackoff;
+    },
+
+    /**
+     * Reset the poller cursor and backoff to their initial states.
+     */
+    reset() {
+      lastSeq = 0;
+      currentBackoff = initialBackoff;
+    },
+  };
+}
+
+/**
+ * @typedef {{ id: number, org: string, actor: string, action: string, resource: object, timestamp: string }} AuditEvent
+ */

package/src/auth.js

@@ -1,3 +1,4 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import { createResource, clone } from './resource-model.js';
 import { mapOidcIdentity } from './identity-policy.js';
 
@@ -136,22 +137,63 @@ export function profileFromDelegatedHeaders(headers, config = createAuthProvider
   return { provider: 'delegated', subject: user, email, displayName: user, username: normalizeName(user), groups, teams: [], admin: groups.includes('krate:platform-engineers') || groups.includes('krate:repo-admins'), delegatedIdentitySource: headerUser ? 'proxy-header' : 'local-development' };
 }
 
-export async function registerLoginProfile({ controller, namespace = process.env.KRATE_NAMESPACE || 'default', profile }) {
-  const mapped = mapLoginProfileToKrateIdentity({ ...profile, namespace });
+export async function registerLoginProfile({ controller, namespace, profile }) {
+  const org = process.env.KRATE_ADMIN_ORG || process.env.KRATE_ORG || 'default';
+  const orgNamespace = namespace || `krate-org-${org}`;
+  const adminUsername = process.env.KRATE_ADMIN_USERNAME || '';
+  const isBootstrapAdmin = adminUsername && (profile.username === adminUsername || profile.email === adminUsername || normalizeName(profile.email || '') === adminUsername || normalizeName(profile.username || '') === adminUsername);
+  const mapped = mapLoginProfileToKrateIdentity({ ...profile, namespace: orgNamespace, organizationRef: org, admin: isBootstrapAdmin || profile.admin });
   const userResult = await controller.applyResource(mapped.user);
   const mappingResult = await controller.applyResource(mapped.mapping);
   return { ...mapped, userResult, mappingResult };
 }
 
-export function createSessionCookie(config, profile) {
-  const value = Buffer.from(JSON.stringify({ provider: profile.provider, subject: profile.subject, user: profile.username || profile.email })).toString('base64url');
+export function createSessionCookie(config, profile, options = {}) {
+  const secret = options.secret || process.env.KRATE_SESSION_SECRET || '';
+  const payload = Buffer.from(JSON.stringify({ provider: profile.provider, subject: profile.subject, user: profile.username || profile.email })).toString('base64url');
+  let value;
+  if (secret) {
+    const signature = createHmac('sha256', secret).update(payload).digest('base64url');
+    value = `${payload}.${signature}`;
+  } else {
+    value = payload;
+  }
   return `${config.session.cookieName}=${value}; Path=/; HttpOnly; SameSite=Lax`;
 }
 
-export function parseSessionCookie(config, cookieValue) {
+export function parseSessionCookie(config, cookieValue, options = {}) {
   if (!cookieValue || typeof cookieValue !== 'string') return null;
+  const secret = options.secret || process.env.KRATE_SESSION_SECRET || '';
   try {
-    const session = JSON.parse(Buffer.from(cookieValue, 'base64url').toString('utf8'));
+    const dotIndex = cookieValue.indexOf('.');
+    const isSigned = dotIndex !== -1;
+
+    if (isSigned && !secret) {
+      // Signed cookie but no secret to verify — reject
+      return null;
+    }
+
+    if (!isSigned && secret) {
+      // No signature present but secret is configured — reject (could be tampered or unsigned legacy)
+      return null;
+    }
+
+    let payload;
+    if (isSigned && secret) {
+      payload = cookieValue.slice(0, dotIndex);
+      const receivedSig = cookieValue.slice(dotIndex + 1);
+      const expectedSig = createHmac('sha256', secret).update(payload).digest('base64url');
+      // Constant-time comparison
+      const expected = Buffer.from(expectedSig, 'base64url');
+      const received = Buffer.from(receivedSig, 'base64url');
+      if (expected.length !== received.length || !timingSafeEqual(expected, received)) {
+        return null;
+      }
+    } else {
+      payload = cookieValue;
+    }
+
+    const session = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
     const user = typeof session.user === 'string' ? session.user.trim() : '';
     const subject = typeof session.subject === 'string' ? session.subject.trim() : '';
     const provider = typeof session.provider === 'string' ? session.provider.trim() : '';

package/src/controller-client.js

@@ -1,38 +1,112 @@
-import { createControllerUiModel } from './controller-ui.js';
-import { createKrateApiController } from './api-controller.js';
-import { createKubernetesResourceGateway } from './kubernetes-resource-gateway.js';
-
-export async function fetchControllerUiModel({ controllerUrl = process.env.KRATE_CONTROLLER_URL, fetchImpl = globalThis.fetch, controller = createKrateApiController({ resourceGateway: createKubernetesResourceGateway() }), organization = process.env.KRATE_ORG || null } = {}) {
-  if (controllerUrl) {
-    try {
-      const target = new URL('/api/controller', controllerUrl);
-      if (organization) target.searchParams.set('org', organization);
-      const response = await fetchImpl(target, { cache: 'no-store' });
-      if (!response.ok) throw new Error(`controller API ${response.status}`);
-      return response.json();
-    } catch (error) {
-      return fallbackControllerModel(controller, error, organization);
-    }
-  }
-  return fallbackControllerModel(controller, null, organization);
-}
-
-async function fallbackControllerModel(controller, connectionError = null, organization = null) {
-  try {
-    const model = createControllerUiModel(await controller.snapshot(), { organization });
-    if (connectionError) model.controller.connection.errors = [connectionError.message, ...(model.controller.connection.errors || [])];
-    return model;
-  } catch (error) {
-    return createControllerUiModel({
-      source: 'kubernetes',
-      namespace: process.env.KRATE_NAMESPACE || 'krate-system',
-      kubectl: { available: false, context: null, errors: [connectionError?.message, error.message].filter(Boolean) },
-      resources: {},
-      crds: [],
-      events: [],
-      permissions: [],
-      storage: {},
-      commands: []
-    }, { organization });
-  }
-}
+import { createControllerUiModel } from './controller-ui.js';
+import { clearSnapshotCache, staleWhileRevalidate } from './snapshot-cache.js';
+import { getControllerSnapshotAsync } from './kubernetes-controller-async.js';
+
+export { clearSnapshotCache };
+
+const CONTROLLER_REQUEST_TIMEOUT_MS = Number(process.env.KRATE_CONTROLLER_REQUEST_TIMEOUT_MS || 5_000);
+
+export async function fetchControllerUiModel({ controllerUrl = process.env.KRATE_CONTROLLER_URL, fetchImpl = globalThis.fetch, controller = null, organization = process.env.KRATE_ORG || null, localFallback = true, requestTimeoutMs = CONTROLLER_REQUEST_TIMEOUT_MS, useCache = true, swrOptions = {}, fallbackSnapshot = getControllerSnapshotAsync } = {}) {
+  const revalidateFn = async () => {
+    if (controllerUrl) {
+      try {
+        const target = new URL('/api/controller', controllerUrl);
+        if (organization) target.searchParams.set('org', organization);
+        const signal = requestTimeoutMs > 0 && globalThis.AbortSignal?.timeout ? AbortSignal.timeout(requestTimeoutMs) : undefined;
+        const response = await fetchImpl(target, { cache: 'no-store', ...(signal ? { signal } : {}) });
+        if (!response.ok) throw new Error(`controller API ${response.status}`);
+        const remoteModel = await response.json();
+        if (localFallback && shouldFallbackFromRemoteModel(remoteModel)) {
+          return fallbackControllerModel({ controller, connectionError: new Error(remoteControllerError(remoteModel) || 'controller returned degraded empty data'), organization, fallbackSnapshot });
+        }
+        if (localFallback && shouldProbeLocalModel(remoteModel)) {
+          const localModel = await fallbackControllerModel({ controller, organization, fallbackSnapshot });
+          if (modelResourceScore(localModel) > modelResourceScore(remoteModel)) return localModel;
+        }
+        return remoteModel;
+      } catch (error) {
+        if (localFallback) return fallbackControllerModel({ controller, connectionError: error, organization, fallbackSnapshot });
+        return unavailableControllerModel(error.message, organization);
+      }
+    }
+    if (!localFallback) return unavailableControllerModel('KRATE_CONTROLLER_URL is not configured', organization);
+    return fallbackControllerModel({ controller, organization, fallbackSnapshot });
+  };
+
+  if (!useCache) return revalidateFn();
+  return staleWhileRevalidate(organization, revalidateFn, swrOptions);
+}
+
+async function fallbackControllerModel({ controller = null, connectionError = null, organization = null, fallbackSnapshot = getControllerSnapshotAsync } = {}) {
+  try {
+    const snapshot = controller ? await controller.snapshot() : await fallbackSnapshot();
+    const model = createControllerUiModel(snapshot, { organization });
+    if (connectionError) model.controller.connection.errors = [connectionError.message, ...(model.controller.connection.errors || [])];
+    return model;
+  } catch (error) {
+    return createControllerUiModel({
+      source: 'kubernetes',
+      namespace: process.env.KRATE_NAMESPACE || 'krate-system',
+      kubectl: { available: false, context: null, errors: [connectionError?.message, error.message].filter(Boolean) },
+      resources: {},
+      crds: [],
+      events: [],
+      permissions: [],
+      storage: {},
+      commands: []
+    }, { organization });
+  }
+}
+
+
+function shouldProbeLocalModel(model) {
+  if (!model || model.status !== 'ready') return false;
+  const hasLiveConnection = Boolean(model.controller?.connection?.available || model.controller?.apiService);
+  if (!hasLiveConnection) return false;
+  const summaries = Array.isArray(model.resources) ? model.resources : [];
+  const crdKinds = new Set(['Repository', 'RunnerPool', 'Pipeline', 'Job']);
+  const crdItems = summaries
+    .filter((resource) => crdKinds.has(resource?.kind))
+    .reduce((count, resource) => count + Number(resource?.count || resource?.items?.length || 0), 0);
+  return crdItems === 0;
+}
+
+function modelResourceScore(model) {
+  if (!model) return 0;
+  const metricCount = Number(model.metrics?.resources || 0);
+  const summaryCount = Array.isArray(model.resources)
+    ? model.resources.reduce((count, resource) => count + Number(resource?.count || resource?.items?.length || 0), 0)
+    : 0;
+  const dashboardCount = Number(model.views?.dashboard?.repositories?.length || 0);
+  return metricCount + summaryCount + dashboardCount;
+}
+
+function shouldFallbackFromRemoteModel(model) {
+  if (!model || model.status !== 'degraded') return false;
+  const hasLiveConnection = Boolean(model.controller?.connection?.available || model.controller?.apiService);
+  if (hasLiveConnection) return false;
+  const resourceCount = Number(model.metrics?.resources || 0);
+  const hasResourceItems = Array.isArray(model.resources) && model.resources.some((resource) => Number(resource?.count || 0) > 0 || resource?.items?.length);
+  const hasDashboardItems = Number(model.views?.dashboard?.repositories?.length || 0) > 0;
+  const errors = model.controller?.connection?.errors || [];
+  return resourceCount === 0 && !hasResourceItems && !hasDashboardItems && errors.length > 0;
+}
+
+function remoteControllerError(model) {
+  return (model?.controller?.connection?.errors || []).filter(Boolean).join('; ');
+}
+
+function unavailableControllerModel(messages, organization = null) {
+  const errors = Array.isArray(messages) ? messages : [messages];
+  return createControllerUiModel({
+    source: 'kubernetes',
+    namespace: process.env.KRATE_NAMESPACE || 'krate-system',
+    kubectl: { available: false, context: null, errors: errors.filter(Boolean) },
+    resources: {},
+    crds: [],
+    events: [],
+    permissions: [],
+    storage: {},
+    commands: []
+  }, { organization });
+}