@stacksjs/ts-cloud 0.7.105 → 0.7.109

package/dist/chunk-xrtwv3v2.js

@@ -0,0 +1,420 @@
+import {
+  isValidCidr
+} from "./chunk-aa2dkn7b.js";
+// src/protection/ratelimit.ts
+var RATE_LIMIT_KEY_SEPARATOR = "\x00";
+var GLOB_PLACEHOLDER = "\x01";
+function globMatches(pattern, value) {
+  if (pattern === "*" || pattern === "**")
+    return true;
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, GLOB_PLACEHOLDER).replace(/\*/g, "[^/]*").replace(/\u0001/g, ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
+function hostMatches(pattern, host) {
+  if (pattern.startsWith("*.")) {
+    const suffix = pattern.slice(1);
+    return host.endsWith(suffix) && host.length > suffix.length;
+  }
+  return pattern === host;
+}
+function ruleMatches(rule, request) {
+  if (rule.enabled === false)
+    return false;
+  if (rule.methods?.length && !rule.methods.some((method) => method.toUpperCase() === request.method.toUpperCase()))
+    return false;
+  if (rule.path && !globMatches(rule.path, request.path))
+    return false;
+  if (rule.host && !hostMatches(rule.host, request.host ?? ""))
+    return false;
+  return true;
+}
+function rateLimitKey(rule, request) {
+  const spec = rule.key ?? { source: "ip" };
+  const fallback = spec.fallbackToIp !== false;
+  let identity;
+  if (spec.source === "ip")
+    identity = request.ip;
+  else if (spec.source === "global")
+    identity = "global";
+  else if (spec.source === "host")
+    identity = request.host ?? "";
+  else if (spec.source === "path")
+    identity = request.path;
+  else if (spec.source === "header")
+    identity = spec.name ? request.headers?.[spec.name.toLowerCase()] : undefined;
+  else if (spec.source === "cookie")
+    identity = spec.name ? request.cookies?.[spec.name] : undefined;
+  if (!identity && spec.source !== "global")
+    identity = fallback ? request.ip : "__missing__";
+  return `${rule.id}${RATE_LIMIT_KEY_SEPARATOR}${identity}`;
+}
+
+class RateLimiter {
+  clock;
+  maxTrackedKeys;
+  buckets = new Map;
+  windows = new Map;
+  rules;
+  constructor(rules, clock = () => Date.now(), maxTrackedKeys = 1e5) {
+    this.clock = clock;
+    this.maxTrackedKeys = maxTrackedKeys;
+    this.rules = [...rules].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+  }
+  check(request) {
+    const now = this.clock();
+    const matching = this.rules.filter((rule) => ruleMatches(rule, request));
+    let blocked;
+    for (const rule of matching) {
+      const test = this.test(rule, request, now);
+      if (test.allowed)
+        continue;
+      if (!blocked || severity(test.action) > severity(blocked.action))
+        blocked = test;
+    }
+    if (blocked)
+      return blocked;
+    let tightest = { action: "allow", allowed: true };
+    for (const rule of matching) {
+      const decision = this.consume(rule, request, now);
+      if (decision.remaining != null && (tightest.remaining ?? Infinity) > decision.remaining)
+        tightest = decision;
+    }
+    return tightest;
+  }
+  test(rule, request, now) {
+    const key = rateLimitKey(rule, request);
+    if ((rule.algorithm ?? "token_bucket") === "token_bucket") {
+      const capacity = rule.burst ?? rule.limit;
+      const state = this.buckets.get(key);
+      const tokens = state ? Math.min(capacity, state.tokens + this.refill(rule, now - state.updatedAt)) : capacity;
+      if (tokens >= 1)
+        return { action: "allow", allowed: true };
+      return this.blocked(rule, key, 0, this.msPerToken(rule) * (1 - tokens), now);
+    }
+    const hits = (this.windows.get(key)?.hits ?? []).filter((at) => at > now - rule.windowMs);
+    if (hits.length < rule.limit)
+      return { action: "allow", allowed: true };
+    return this.blocked(rule, key, 0, hits[0] + rule.windowMs - now, now);
+  }
+  peek(request) {
+    const now = this.clock();
+    for (const rule of this.rules) {
+      if (!ruleMatches(rule, request))
+        continue;
+      const decision = this.test(rule, request, now);
+      if (!decision.allowed)
+        return decision;
+    }
+    return { action: "allow", allowed: true };
+  }
+  msPerToken(rule) {
+    return rule.windowMs / Math.max(1, rule.limit);
+  }
+  refill(rule, elapsedMs) {
+    return Math.max(0, elapsedMs) / this.msPerToken(rule);
+  }
+  blocked(rule, key, remaining, retryAfterMs, now) {
+    const action = rule.action ?? "deny";
+    return {
+      action,
+      allowed: action === "allow" || action === "log",
+      ruleId: rule.id,
+      limit: rule.limit,
+      remaining,
+      retryAfterMs: Math.max(0, Math.ceil(retryAfterMs)),
+      resetAt: now + Math.max(0, retryAfterMs),
+      key
+    };
+  }
+  consume(rule, request, now) {
+    const key = rateLimitKey(rule, request);
+    const algorithm = rule.algorithm ?? "token_bucket";
+    if (algorithm === "token_bucket") {
+      const capacity = rule.burst ?? rule.limit;
+      const state2 = this.buckets.get(key) ?? { tokens: capacity, updatedAt: now };
+      const tokens = Math.min(capacity, state2.tokens + this.refill(rule, now - state2.updatedAt));
+      if (tokens < 1) {
+        this.buckets.set(key, { tokens, updatedAt: now });
+        return this.blocked(rule, key, 0, this.msPerToken(rule) * (1 - tokens), now);
+      }
+      this.evictIfNeeded(this.buckets);
+      this.buckets.set(key, { tokens: tokens - 1, updatedAt: now });
+      return {
+        action: "allow",
+        allowed: true,
+        ruleId: rule.id,
+        limit: capacity,
+        remaining: Math.floor(tokens - 1),
+        resetAt: now + this.msPerToken(rule) * (capacity - (tokens - 1)),
+        key
+      };
+    }
+    const state = this.windows.get(key) ?? { hits: [] };
+    const cutoff = now - rule.windowMs;
+    const hits = state.hits.filter((at) => at > cutoff);
+    if (hits.length >= rule.limit) {
+      this.windows.set(key, { hits });
+      return this.blocked(rule, key, 0, hits[0] + rule.windowMs - now, now);
+    }
+    hits.push(now);
+    this.evictIfNeeded(this.windows);
+    this.windows.set(key, { hits });
+    return {
+      action: "allow",
+      allowed: true,
+      ruleId: rule.id,
+      limit: rule.limit,
+      remaining: rule.limit - hits.length,
+      resetAt: hits[0] + rule.windowMs,
+      key
+    };
+  }
+  evictIfNeeded(map) {
+    if (map.size < this.maxTrackedKeys)
+      return;
+    const excess = map.size - this.maxTrackedKeys + 1;
+    let removed = 0;
+    for (const key of map.keys()) {
+      map.delete(key);
+      if (++removed >= excess)
+        break;
+    }
+  }
+  sweep() {
+    const now = this.clock();
+    let removed = 0;
+    for (const [key, state] of this.windows) {
+      const ruleId = key.split(RATE_LIMIT_KEY_SEPARATOR)[0];
+      const rule = this.rules.find((candidate) => candidate.id === ruleId);
+      if (!rule) {
+        this.windows.delete(key);
+        removed++;
+        continue;
+      }
+      if (state.hits.every((at) => at <= now - rule.windowMs)) {
+        this.windows.delete(key);
+        removed++;
+      }
+    }
+    for (const [key, state] of this.buckets) {
+      const ruleId = key.split(RATE_LIMIT_KEY_SEPARATOR)[0];
+      const rule = this.rules.find((candidate) => candidate.id === ruleId);
+      if (!rule || now - state.updatedAt > rule.windowMs * 2) {
+        this.buckets.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+  get trackedKeys() {
+    return this.buckets.size + this.windows.size;
+  }
+}
+function severity(action) {
+  return { allow: 0, log: 1, throttle: 2, challenge: 3, deny: 4 }[action];
+}
+function rateLimitHeaders(decision) {
+  const headers = {};
+  if (decision.limit != null)
+    headers["ratelimit-limit"] = String(decision.limit);
+  if (decision.remaining != null)
+    headers["ratelimit-remaining"] = String(decision.remaining);
+  if (decision.resetAt != null)
+    headers["ratelimit-reset"] = String(Math.max(0, Math.ceil((decision.resetAt - Date.now()) / 1000)));
+  if (!decision.allowed && decision.retryAfterMs != null)
+    headers["retry-after"] = String(Math.max(1, Math.ceil(decision.retryAfterMs / 1000)));
+  return headers;
+}
+function defaultRateLimitRules() {
+  return [
+    { id: "global-ip", limit: 600, windowMs: 60000, burst: 100, key: { source: "ip" }, action: "deny", priority: 100 },
+    {
+      id: "api-ip",
+      limit: 120,
+      windowMs: 60000,
+      burst: 30,
+      path: "/api/**",
+      key: { source: "ip" },
+      action: "deny",
+      priority: 50
+    },
+    {
+      id: "auth-ip",
+      limit: 10,
+      windowMs: 60000,
+      algorithm: "sliding_window",
+      path: "/auth/**",
+      methods: ["POST"],
+      key: { source: "ip" },
+      action: "challenge",
+      priority: 10
+    }
+  ];
+}
+// src/protection/controls.ts
+var PROTECTION_SETTING = "protection.controls";
+var MAX_CONTROL_HOURS = 24;
+var DEFAULT_ATTACK_MODE_HOURS = 4;
+var EMPTY = { ipRules: { allow: [], block: [] } };
+function activeControl(control, now) {
+  if (!control?.enabled)
+    return;
+  return new Date(control.expiresAt).getTime() > now.getTime() ? control : undefined;
+}
+function clampHours(hours, fallback) {
+  const value = Number.isFinite(hours) ? Number(hours) : fallback;
+  return Math.min(MAX_CONTROL_HOURS, Math.max(0.25, value));
+}
+var MAX_IP_RULES = 500;
+
+class ProtectionControlStore {
+  controlPlane;
+  options;
+  constructor(controlPlane, options = {}) {
+    this.controlPlane = controlPlane;
+    this.options = options;
+  }
+  now() {
+    return this.options.now?.() ?? new Date;
+  }
+  read() {
+    const raw = this.controlPlane.getSetting(PROTECTION_SETTING);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+      return { ...EMPTY, ipRules: { allow: [], block: [] } };
+    const record = raw;
+    return {
+      attackMode: record.attackMode,
+      mitigationPause: record.mitigationPause,
+      ipRules: {
+        allow: Array.isArray(record.ipRules?.allow) ? record.ipRules.allow : [],
+        block: Array.isArray(record.ipRules?.block) ? record.ipRules.block : []
+      },
+      updatedAt: record.updatedAt
+    };
+  }
+  write(next) {
+    const stored = { ...next, updatedAt: this.now().toISOString() };
+    this.controlPlane.setSetting(PROTECTION_SETTING, stored);
+    return stored;
+  }
+  raw() {
+    return this.read();
+  }
+  current() {
+    const now = this.now();
+    const stored = this.read();
+    return {
+      attackMode: activeControl(stored.attackMode, now),
+      mitigationPause: activeControl(stored.mitigationPause, now),
+      ipRules: stored.ipRules
+    };
+  }
+  enableAttackMode(input) {
+    const now = this.now();
+    const control = {
+      enabled: true,
+      startedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + clampHours(input.hours, DEFAULT_ATTACK_MODE_HOURS) * 3600000).toISOString(),
+      reason: input.reason.trim() || "Attack mode enabled by an operator.",
+      actorId: input.actorId
+    };
+    this.write({ ...this.read(), attackMode: control });
+    return control;
+  }
+  disableAttackMode() {
+    const stored = this.read();
+    if (!stored.attackMode?.enabled)
+      return false;
+    this.write({ ...stored, attackMode: { ...stored.attackMode, enabled: false } });
+    return true;
+  }
+  pauseMitigations(input) {
+    const reason = input.reason.trim();
+    if (!reason)
+      throw new Error("Pausing mitigations requires a reason: you are liable for the traffic it admits.");
+    const now = this.now();
+    const control = {
+      enabled: true,
+      startedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + clampHours(input.hours, MAX_CONTROL_HOURS) * 3600000).toISOString(),
+      reason,
+      actorId: input.actorId
+    };
+    this.write({ ...this.read(), mitigationPause: control });
+    return control;
+  }
+  resumeMitigations() {
+    const stored = this.read();
+    if (!stored.mitigationPause?.enabled)
+      return false;
+    this.write({ ...stored, mitigationPause: { ...stored.mitigationPause, enabled: false } });
+    return true;
+  }
+  addIpRule(list, cidr) {
+    const value = cidr.trim();
+    if (!isValidCidr(value))
+      throw new Error(`Not a valid IP or CIDR: ${cidr}`);
+    const stored = this.read();
+    const next = { ...stored.ipRules, [list]: [...new Set([...stored.ipRules[list], value])] };
+    if (next[list].length > MAX_IP_RULES)
+      throw new Error(`At most ${MAX_IP_RULES} ${list} rules are supported.`);
+    const other = list === "allow" ? "block" : "allow";
+    next[other] = next[other].filter((entry) => entry !== value);
+    this.write({ ...stored, ipRules: next });
+    return next;
+  }
+  removeIpRule(list, cidr) {
+    const stored = this.read();
+    const next = { ...stored.ipRules, [list]: stored.ipRules[list].filter((entry) => entry !== cidr.trim()) };
+    this.write({ ...stored, ipRules: next });
+    return next;
+  }
+}
+function describePosture(controls) {
+  if (controls.mitigationPause)
+    return {
+      attackMode: !!controls.attackMode,
+      mitigationPaused: true,
+      summary: `Automatic mitigation is paused until ${controls.mitigationPause.expiresAt}. All traffic is being served and billed.`,
+      expiresAt: controls.mitigationPause.expiresAt
+    };
+  if (controls.attackMode)
+    return {
+      attackMode: true,
+      mitigationPaused: false,
+      summary: `Attack mode is on until ${controls.attackMode.expiresAt}. Every visitor is being challenged.`,
+      expiresAt: controls.attackMode.expiresAt
+    };
+  return { attackMode: false, mitigationPaused: false, summary: "Protection is in its normal posture." };
+}
+function applyControlsToRateLimits(rules, controls) {
+  if (controls.mitigationPause)
+    return rules.map((rule) => ({ ...rule, enabled: false }));
+  if (!controls.attackMode)
+    return [...rules];
+  return rules.map((rule) => ({
+    ...rule,
+    action: rule.action === "deny" ? "deny" : "challenge",
+    burst: Math.max(1, Math.min(rule.burst ?? rule.limit, 5))
+  }));
+}
+function applyControlsToDdos(config, controls) {
+  const allowlist = [...new Set([...config.allowlist ?? [], ...controls.ipRules.allow])];
+  const blocklist = [...new Set([...config.blocklist ?? [], ...controls.ipRules.block])];
+  if (controls.mitigationPause)
+    return { ...config, allowlist, blocklist, monitorOnly: true };
+  if (!controls.attackMode)
+    return { ...config, allowlist, blocklist };
+  const thresholds = config.thresholds ?? {};
+  return {
+    ...config,
+    allowlist,
+    blocklist,
+    thresholds: {
+      ...thresholds,
+      newConnectionsPerSecond: Math.max(1, Math.floor((thresholds.newConnectionsPerSecond ?? 50) / 5)),
+      concurrentPerSource: Math.max(1, Math.floor((thresholds.concurrentPerSource ?? 100) / 5))
+    }
+  };
+}
+export { RATE_LIMIT_KEY_SEPARATOR, globMatches, ruleMatches, rateLimitKey, RateLimiter, rateLimitHeaders, defaultRateLimitRules, PROTECTION_SETTING, MAX_CONTROL_HOURS, DEFAULT_ATTACK_MODE_HOURS, ProtectionControlStore, describePosture, applyControlsToRateLimits, applyControlsToDdos };

package/dist/control-plane/types.d.ts

@@ -9,7 +9,7 @@ export type OrganizationRoleTemplate = 'owner' | 'admin' | 'deployer' | 'operato
 export type AuthorizationScopeType = 'organization' | 'project' | 'environment' | 'resource';
 export type AuthorizationEffect = 'allow' | 'deny';
 export type AuthorizationRecordSource = 'manual' | 'legacy' | 'invitation';
-export type AuthorizationCapability = 'project:read' | 'config:read' | 'config:write' | 'deployments:read' | 'deployments:create' | 'deployments:cancel' | 'deployments:rollback' | 'runtime:read' | 'runtime:restart' | 'runtime:logs' | 'runtime:terminal' | 'data:read' | 'data:write' | 'data:admin' | 'backups:read' | 'backups:create' | 'backups:restore' | 'secrets:read' | 'secrets:write' | 'fleet:read' | 'fleet:manage' | 'users:read' | 'users:manage' | 'users:transfer-ownership' | 'audit:read' | 'security:read' | 'security:manage' | 'security:waive' | 'sources:read' | 'sources:manage' | 'applications:read' | 'applications:manage' | 'automation:read' | 'automation:manage' | 'tags:manage';
+export type AuthorizationCapability = 'project:read' | 'config:read' | 'config:write' | 'deployments:read' | 'deployments:create' | 'deployments:cancel' | 'deployments:rollback' | 'runtime:read' | 'runtime:restart' | 'runtime:logs' | 'runtime:terminal' | 'data:read' | 'data:write' | 'data:admin' | 'backups:read' | 'backups:create' | 'backups:restore' | 'secrets:read' | 'secrets:write' | 'fleet:read' | 'fleet:manage' | 'users:read' | 'users:manage' | 'users:transfer-ownership' | 'audit:read' | 'billing:read' | 'billing:manage' | 'security:read' | 'security:manage' | 'security:waive' | 'sources:read' | 'sources:manage' | 'applications:read' | 'applications:manage' | 'automation:read' | 'automation:manage' | 'tags:manage';
 export interface AuthorizationScope {
     type: AuthorizationScopeType;
     id?: ControlPlaneId;

package/dist/deploy/dashboard-bundle-encoding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deploy/dashboard-payload.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Serialize the dashboard payload for the trip through an environment variable.
+ *
+ * The UI is rebuilt by spawning stx with the resolved data in
+ * `TSCLOUD_DASHBOARD_DATA`. Environment variables are bytes, and the child
+ * decodes them using its locale — so on a box whose locale is `POSIX`/`C`
+ * (the default on most minimal server images) every non-ASCII character in the
+ * payload comes back mis-decoded and is then re-encoded as UTF-8, arriving in
+ * the built page as mojibake: `—` renders as `â€"`, `·` as `·`.
+ *
+ * That is not hypothetical or cosmetic. It corrupts any project name, domain,
+ * or status text carrying an accent or a dash, on exactly the hosts operators
+ * are most likely to provision.
+ *
+ * Escaping every non-ASCII code point makes the transport pure ASCII, which no
+ * locale can misread. `JSON.parse` on the other side turns the escapes back
+ * into the original characters, so the payload is unchanged — only its wire
+ * form is narrowed.
+ */
+export declare function encodeDashboardPayload(data: unknown): string;

package/dist/deploy/dashboard-payload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deploy/dashboard-protection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deploy/dashboard-spend.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deploy/dashboard-topology.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Derive the infrastructure topology the dashboard draws as a diagram.
+ *
+ * Deliberately built from the *resolved dashboard data* rather than straight
+ * from the cloud config: the diagram then shows what the rest of the cockpit
+ * shows — the same sites, services, functions and queues, with the same
+ * statuses — instead of a second, subtly different reading of the world.
+ *
+ * Nothing here invents a resource. A slice that could not be read simply
+ * contributes no node, and the reason lands in `notes` so the page can say so
+ * out loud. See `packages/ui/pages/infrastructure/topology.stx`.
+ */
+export type TopologyStatus = 'ok' | 'warn' | 'bad' | 'idle' | 'unknown';
+export type TopologyKind = 'internet' | 'dns' | 'waf' | 'firewall' | 'cdn' | 'gateway' | 'proxy' | 'site' | 'function' | 'worker' | 'scheduler' | 'queue' | 'cache' | 'database' | 'storage' | 'filesystem' | 'backup';
+/** How traffic or state moves along an edge — drives the edge styling. */
+export type TopologyFlow = 'request' | 'async' | 'data' | 'backup';
+export interface TopologyFact {
+    label: string;
+    value: string;
+}
+export interface TopologyNode {
+    id: string;
+    label: string;
+    kind: TopologyKind;
+    /** Row in the diagram: 0 is the internet, higher is deeper in the stack. */
+    layer: number;
+    status: TopologyStatus;
+    /** One-line subtitle: runtime, engine, instance class… */
+    sub?: string;
+    facts: TopologyFact[];
+    /** Dashboard page this resource is managed from. */
+    href?: string;
+    /** Boundary this node sits inside (a box, a VPC, a managed account). */
+    group?: string;
+    /** Outside the deployment — drawn as an open shape. */
+    external?: boolean;
+}
+export interface TopologyLink {
+    source: string;
+    target: string;
+    flow: TopologyFlow;
+    label?: string;
+    status?: TopologyStatus;
+}
+export interface TopologyGroup {
+    id: string;
+    label: string;
+    sub?: string;
+}
+export interface TopologyLayer {
+    index: number;
+    id: string;
+    label: string;
+}
+/** Identity the data bag doesn't carry on its own. */
+export interface TopologyContext {
+    project?: string;
+    environment?: string;
+}
+export interface TopologyModel {
+    mode: 'server' | 'serverless';
+    project: string;
+    environment: string;
+    provider: string;
+    region: string;
+    generatedAt: string;
+    layers: TopologyLayer[];
+    groups: TopologyGroup[];
+    nodes: TopologyNode[];
+    links: TopologyLink[];
+    /** What the diagram could not show, and why. Never left implicit. */
+    notes: string[];
+}
+/**
+ * Server-mode topology: clients → DNS → host firewall → reverse proxy → sites,
+ * with the box's workers, scheduler, data services and backups hanging off it.
+ */
+export declare function buildServerTopology(data: Record<string, any>, context?: TopologyContext): TopologyModel;
+/**
+ * Serverless-mode topology: clients → DNS → WAF/CDN → the HTTP entry point →
+ * functions, with queues, database, cache and object storage behind them.
+ */
+export declare function buildServerlessTopology(data: Record<string, any>, context?: TopologyContext): TopologyModel;
+/** Build the topology matching the dashboard mode the data was resolved for. */
+export declare function buildTopology(mode: 'server' | 'serverless', data: Record<string, any>, context?: TopologyContext): TopologyModel;

package/dist/deploy/dashboard-topology.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deploy/egress-collection.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Object-storage egress collection.
+ *
+ * Host network counters answer a different question than the one an
+ * object-storage invoice asks. When an application redirects downloads to a
+ * bucket (or to a CDN in front of one), those bytes never traverse the host's
+ * NIC — the box can sit idle while the bucket serves terabytes. The only
+ * component that knows a transfer happened, and how large it was, is the
+ * application that authorized it, so this polls it instead of guessing.
+ *
+ * The reports carry a per-day history rather than a single counter, and that is
+ * deliberately exploited here: each day becomes one metric point stamped with
+ * that day's own timestamp. Because record ids are a deterministic hash of
+ * (source, name, timestamp) and the store inserts with OR IGNORE, replaying a
+ * history is idempotent. A collector that was down for six hours — or six days
+ * — backfills what it missed on its next run instead of leaving a hole, and
+ * re-reading the same day never double-counts it.
+ */
+import type { EgressEndpointConfig, EgressReport } from '@ts-cloud/core';
+export interface EgressMetric {
+    name: string;
+    value: number;
+    unit: string;
+    /** ISO timestamp this point belongs to. */
+    timestamp: string;
+    attributes: Record<string, string>;
+}
+export interface EgressCollectionResult {
+    metrics: EgressMetric[];
+    errors: Array<{
+        source: string;
+        message: string;
+    }>;
+}
+/**
+ * Turn one report into metric points.
+ *
+ * Pure: no clock, no network. `now` is the timestamp for the point-in-time
+ * series (month-to-date, projection, allowance), which describe the moment of
+ * collection rather than a calendar day.
+ */
+export declare function egressReportMetrics(report: EgressReport | null | undefined, options: {
+    name: string;
+    now: string;
+    maxReplayDays?: number;
+}): EgressMetric[];
+/**
+ * Fetch one endpoint's report.
+ *
+ * Returns null on any failure. An egress endpoint is supplementary — it must
+ * never be able to fail a telemetry collection that is also carrying host
+ * metrics, so problems surface as an error entry rather than a throw.
+ */
+export declare function fetchEgressReport(endpoint: EgressEndpointConfig, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Promise<EgressReport | null>;
+/** Poll every configured endpoint and flatten the results. */
+export declare function collectEgressMetrics(endpoints: EgressEndpointConfig[] | undefined, options: {
+    now: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+}): Promise<EgressCollectionResult>;

package/dist/deploy/index.d.ts

@@ -15,5 +15,7 @@ export * from './container-image';
 export { buildFunctionEnv, type CodeSource, deployServerlessApp, type DeployServerlessOptions, infraEnvFromOutputs, redeployServerlessApp, type ResolvedContext, rollbackServerlessApp, runRemoteCommand, setMaintenance, } from './serverless-app';
 export { buildAndPushServerlessImage, type BuildImageOptions, type BuiltImage } from './serverless-image';
 export { type DashboardData, resolveDashboardData } from './dashboard-data';
+export { buildServerlessTopology, buildServerTopology, buildTopology, type TopologyContext, type TopologyFact, type TopologyFlow, type TopologyGroup, type TopologyKind, type TopologyLayer, type TopologyLink, type TopologyModel, type TopologyNode, type TopologyStatus, } from './dashboard-topology';
+export { collectEgressMetrics, type EgressCollectionResult, egressReportMetrics, type EgressMetric, fetchEgressReport, } from './egress-collection';
 export { dashboardActions, resolveDashboardAction, sanitizeCloudConfig, startLocalDashboardServer, type DashboardAction, type LocalDashboardServer, type LocalDashboardServerOptions, } from './local-dashboard-server';
 export { buildManagementDashboardArtifact, dashboardCredentialsFile, ensureManagementDashboard, type EnsureDashboardLogger, MANAGEMENT_DASHBOARD_SITE, resolveDashboardAuth, type ResolvedDashboardAuth, resolveUiSource, } from './management-dashboard';