@xopcai/xopc 0.0.27 → 0.0.29

package/dist/src/gateway/security/operator-scopes.js

@@ -0,0 +1,137 @@
+//#region src/gateway/security/operator-scopes.ts
+/**
+* Operator scope system for fine-grained gateway API authorization.
+*
+* Each gateway API method maps to one or more required scopes.
+* Clients declare their scopes at connection time; the gateway enforces
+* that the declared scopes cover the method being invoked.
+*/
+const ADMIN_SCOPE = "operator.admin";
+const READ_SCOPE = "operator.read";
+const WRITE_SCOPE = "operator.write";
+const KNOWN_OPERATOR_SCOPES = new Set([
+	ADMIN_SCOPE,
+	READ_SCOPE,
+	WRITE_SCOPE
+]);
+function isOperatorScope(value) {
+	return typeof value === "string" && KNOWN_OPERATOR_SCOPES.has(value);
+}
+/** Default scopes granted to authenticated CLI / direct connections. */
+const DEFAULT_OPERATOR_SCOPES = [
+	ADMIN_SCOPE,
+	READ_SCOPE,
+	WRITE_SCOPE
+];
+/**
+* Route-level scope requirements.
+* Maps HTTP route path prefixes to required minimum scope.
+*/
+const ROUTE_SCOPE_REQUIREMENTS = [
+	{
+		prefix: "/api/config",
+		scope: ADMIN_SCOPE
+	},
+	{
+		prefix: "/api/update",
+		scope: ADMIN_SCOPE
+	},
+	{
+		prefix: "/api/extensions/registry",
+		scope: ADMIN_SCOPE
+	},
+	{
+		prefix: "/api/agent",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/sessions",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/cron",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/channels",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/agents",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/workspace",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/skills",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/commands",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/host-fs",
+		scope: WRITE_SCOPE
+	},
+	{
+		prefix: "/api/status",
+		scope: READ_SCOPE
+	},
+	{
+		prefix: "/api/models",
+		scope: READ_SCOPE
+	},
+	{
+		prefix: "/api/logs",
+		scope: READ_SCOPE
+	},
+	{
+		prefix: "/api/doctor",
+		scope: READ_SCOPE
+	},
+	{
+		prefix: "/api/events",
+		scope: READ_SCOPE
+	}
+];
+/** Scope hierarchy: admin > write > read. */
+const SCOPE_HIERARCHY = {
+	[ADMIN_SCOPE]: 3,
+	[WRITE_SCOPE]: 2,
+	[READ_SCOPE]: 1
+};
+function scopeSatisfies(granted, required) {
+	return SCOPE_HIERARCHY[granted] >= SCOPE_HIERARCHY[required];
+}
+/**
+* Check whether a set of granted scopes satisfies the required scope for a route.
+*/
+function authorizeRouteScope(routePath, grantedScopes) {
+	const routeRequirement = ROUTE_SCOPE_REQUIREMENTS.find((entry) => routePath.startsWith(entry.prefix));
+	if (!routeRequirement) return authorizeScope(READ_SCOPE, grantedScopes);
+	return authorizeScope(routeRequirement.scope, grantedScopes);
+}
+/**
+* Check whether any of the granted scopes satisfies the required scope.
+*/
+function authorizeScope(requiredScope, grantedScopes) {
+	if (grantedScopes.some((granted) => scopeSatisfies(granted, requiredScope))) return { allowed: true };
+	return {
+		allowed: false,
+		requiredScope
+	};
+}
+/**
+* Parse scopes from a comma-separated header value.
+*/
+function parseScopesHeader(headerValue) {
+	if (!headerValue?.trim()) return [...DEFAULT_OPERATOR_SCOPES];
+	return headerValue.split(",").map((scope) => scope.trim()).filter(isOperatorScope);
+}
+//#endregion
+export { ADMIN_SCOPE, DEFAULT_OPERATOR_SCOPES, KNOWN_OPERATOR_SCOPES, READ_SCOPE, WRITE_SCOPE, authorizeRouteScope, authorizeScope, isOperatorScope, parseScopesHeader };
+
+//# sourceMappingURL=operator-scopes.js.map

package/dist/src/gateway/security/operator-scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-scopes.js","names":[],"sources":["../../../../src/gateway/security/operator-scopes.ts"],"sourcesContent":["/**\n * Operator scope system for fine-grained gateway API authorization.\n *\n * Each gateway API method maps to one or more required scopes.\n * Clients declare their scopes at connection time; the gateway enforces\n * that the declared scopes cover the method being invoked.\n */\n\nexport const ADMIN_SCOPE = 'operator.admin' as const;\nexport const READ_SCOPE = 'operator.read' as const;\nexport const WRITE_SCOPE = 'operator.write' as const;\n\nexport type OperatorScope =\n  | typeof ADMIN_SCOPE\n  | typeof READ_SCOPE\n  | typeof WRITE_SCOPE;\n\nconst KNOWN_OPERATOR_SCOPE_VALUES: readonly OperatorScope[] = [\n  ADMIN_SCOPE,\n  READ_SCOPE,\n  WRITE_SCOPE,\n];\n\nexport const KNOWN_OPERATOR_SCOPES: ReadonlySet<OperatorScope> = new Set(\n  KNOWN_OPERATOR_SCOPE_VALUES,\n);\n\nexport function isOperatorScope(value: unknown): value is OperatorScope {\n  return typeof value === 'string' && KNOWN_OPERATOR_SCOPES.has(value as OperatorScope);\n}\n\n/** Default scopes granted to authenticated CLI / direct connections. */\nexport const DEFAULT_OPERATOR_SCOPES: OperatorScope[] = [\n  ADMIN_SCOPE,\n  READ_SCOPE,\n  WRITE_SCOPE,\n];\n\n/**\n * Route-level scope requirements.\n * Maps HTTP route path prefixes to required minimum scope.\n */\nconst ROUTE_SCOPE_REQUIREMENTS: ReadonlyArray<{ prefix: string; scope: OperatorScope }> = [\n  // Admin routes\n  { prefix: '/api/config', scope: ADMIN_SCOPE },\n  { prefix: '/api/update', scope: ADMIN_SCOPE },\n  { prefix: '/api/extensions/registry', scope: ADMIN_SCOPE },\n\n  // Write routes\n  { prefix: '/api/agent', scope: WRITE_SCOPE },\n  { prefix: '/api/sessions', scope: WRITE_SCOPE },\n  { prefix: '/api/cron', scope: WRITE_SCOPE },\n  { prefix: '/api/channels', scope: WRITE_SCOPE },\n  { prefix: '/api/agents', scope: WRITE_SCOPE },\n  { prefix: '/api/workspace', scope: WRITE_SCOPE },\n  { prefix: '/api/skills', scope: WRITE_SCOPE },\n  { prefix: '/api/commands', scope: WRITE_SCOPE },\n  { prefix: '/api/host-fs', scope: WRITE_SCOPE },\n\n  // Read routes\n  { prefix: '/api/status', scope: READ_SCOPE },\n  { prefix: '/api/models', scope: READ_SCOPE },\n  { prefix: '/api/logs', scope: READ_SCOPE },\n  { prefix: '/api/doctor', scope: READ_SCOPE },\n  { prefix: '/api/events', scope: READ_SCOPE },\n];\n\n/** Scope hierarchy: admin > write > read. */\nconst SCOPE_HIERARCHY: Record<OperatorScope, number> = {\n  [ADMIN_SCOPE]: 3,\n  [WRITE_SCOPE]: 2,\n  [READ_SCOPE]: 1,\n};\n\nfunction scopeSatisfies(granted: OperatorScope, required: OperatorScope): boolean {\n  return SCOPE_HIERARCHY[granted] >= SCOPE_HIERARCHY[required];\n}\n\n/**\n * Check whether a set of granted scopes satisfies the required scope for a route.\n */\nexport function authorizeRouteScope(\n  routePath: string,\n  grantedScopes: readonly OperatorScope[],\n): { allowed: true } | { allowed: false; requiredScope: OperatorScope } {\n  const routeRequirement = ROUTE_SCOPE_REQUIREMENTS.find(\n    (entry) => routePath.startsWith(entry.prefix),\n  );\n\n  if (!routeRequirement) {\n    // Routes without explicit scope requirements default to read\n    return authorizeScope(READ_SCOPE, grantedScopes);\n  }\n\n  return authorizeScope(routeRequirement.scope, grantedScopes);\n}\n\n/**\n * Check whether any of the granted scopes satisfies the required scope.\n */\nexport function authorizeScope(\n  requiredScope: OperatorScope,\n  grantedScopes: readonly OperatorScope[],\n): { allowed: true } | { allowed: false; requiredScope: OperatorScope } {\n  const hasSufficientScope = grantedScopes.some(\n    (granted) => scopeSatisfies(granted, requiredScope),\n  );\n\n  if (hasSufficientScope) {\n    return { allowed: true };\n  }\n  return { allowed: false, requiredScope };\n}\n\n/**\n * Parse scopes from a comma-separated header value.\n */\nexport function parseScopesHeader(headerValue: string | undefined): OperatorScope[] {\n  if (!headerValue?.trim()) {\n    return [...DEFAULT_OPERATOR_SCOPES];\n  }\n  return headerValue\n    .split(',')\n    .map((scope) => scope.trim())\n    .filter(isOperatorScope);\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,cAAc;AAC3B,MAAa,aAAa;AAC1B,MAAa,cAAc;AAa3B,MAAa,wBAAoD,IAAI,IACnE;CANA;CACA;CACA;CAIA,CACD;AAED,SAAgB,gBAAgB,OAAwC;AACtE,QAAO,OAAO,UAAU,YAAY,sBAAsB,IAAI,MAAuB;;;AAIvF,MAAa,0BAA2C;CACtD;CACA;CACA;CACD;;;;;AAMD,MAAM,2BAAoF;CAExF;EAAE,QAAQ;EAAe,OAAO;EAAa;CAC7C;EAAE,QAAQ;EAAe,OAAO;EAAa;CAC7C;EAAE,QAAQ;EAA4B,OAAO;EAAa;CAG1D;EAAE,QAAQ;EAAc,OAAO;EAAa;CAC5C;EAAE,QAAQ;EAAiB,OAAO;EAAa;CAC/C;EAAE,QAAQ;EAAa,OAAO;EAAa;CAC3C;EAAE,QAAQ;EAAiB,OAAO;EAAa;CAC/C;EAAE,QAAQ;EAAe,OAAO;EAAa;CAC7C;EAAE,QAAQ;EAAkB,OAAO;EAAa;CAChD;EAAE,QAAQ;EAAe,OAAO;EAAa;CAC7C;EAAE,QAAQ;EAAiB,OAAO;EAAa;CAC/C;EAAE,QAAQ;EAAgB,OAAO;EAAa;CAG9C;EAAE,QAAQ;EAAe,OAAO;EAAY;CAC5C;EAAE,QAAQ;EAAe,OAAO;EAAY;CAC5C;EAAE,QAAQ;EAAa,OAAO;EAAY;CAC1C;EAAE,QAAQ;EAAe,OAAO;EAAY;CAC5C;EAAE,QAAQ;EAAe,OAAO;EAAY;CAC7C;;AAGD,MAAM,kBAAiD;EACpD,cAAc;EACd,cAAc;EACd,aAAa;CACf;AAED,SAAS,eAAe,SAAwB,UAAkC;AAChF,QAAO,gBAAgB,YAAY,gBAAgB;;;;;AAMrD,SAAgB,oBACd,WACA,eACsE;CACtE,MAAM,mBAAmB,yBAAyB,MAC/C,UAAU,UAAU,WAAW,MAAM,OAAO,CAC9C;AAED,KAAI,CAAC,iBAEH,QAAO,eAAe,YAAY,cAAc;AAGlD,QAAO,eAAe,iBAAiB,OAAO,cAAc;;;;;AAM9D,SAAgB,eACd,eACA,eACsE;AAKtE,KAJ2B,cAAc,MACtC,YAAY,eAAe,SAAS,cAAc,CAG/B,CACpB,QAAO,EAAE,SAAS,MAAM;AAE1B,QAAO;EAAE,SAAS;EAAO;EAAe;;;;;AAM1C,SAAgB,kBAAkB,aAAkD;AAClF,KAAI,CAAC,aAAa,MAAM,CACtB,QAAO,CAAC,GAAG,wBAAwB;AAErC,QAAO,YACJ,MAAM,IAAI,CACV,KAAK,UAAU,MAAM,MAAM,CAAC,CAC5B,OAAO,gBAAgB"}

package/dist/src/gateway/security/origin-check.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Browser Origin checking for CSRF protection on HTTP and WebSocket requests.
+ *
+ * Validates that browser-initiated requests come from an allowed origin.
+ * Non-browser requests (no Origin header) are handled by other auth layers.
+ */
+type OriginCheckResult = {
+    ok: true;
+    matchedBy: 'allowlist' | 'host-header-fallback' | 'local-loopback';
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkBrowserOrigin(params: {
+    requestHost?: string;
+    origin?: string;
+    allowedOrigins?: string[];
+    allowHostHeaderOriginFallback?: boolean;
+    isLocalClient?: boolean;
+}): OriginCheckResult;
+export {};

package/dist/src/gateway/security/origin-check.js

@@ -0,0 +1,56 @@
+//#region src/gateway/security/origin-check.ts
+const LOOPBACK_HOSTNAMES = new Set([
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]"
+]);
+function isLoopbackHost(hostname) {
+	return LOOPBACK_HOSTNAMES.has(hostname.toLowerCase());
+}
+function parseOriginHost(originRaw) {
+	const trimmed = (originRaw ?? "").trim();
+	if (!trimmed || trimmed === "null") return null;
+	try {
+		const url = new URL(trimmed);
+		return {
+			origin: url.origin.toLowerCase(),
+			host: url.host.toLowerCase(),
+			hostname: url.hostname.toLowerCase()
+		};
+	} catch {
+		return null;
+	}
+}
+function normalizeHostHeader(hostRaw) {
+	return (hostRaw ?? "").trim().toLowerCase();
+}
+function checkBrowserOrigin(params) {
+	const parsedOrigin = parseOriginHost(params.origin);
+	if (!parsedOrigin) return {
+		ok: false,
+		reason: "origin missing or invalid"
+	};
+	const allowlist = new Set((params.allowedOrigins ?? []).map((value) => value.trim().toLowerCase()).filter(Boolean));
+	if (allowlist.has("*") || allowlist.has(parsedOrigin.origin)) return {
+		ok: true,
+		matchedBy: "allowlist"
+	};
+	const requestHost = normalizeHostHeader(params.requestHost);
+	if (params.allowHostHeaderOriginFallback === true && requestHost && parsedOrigin.host === requestHost) return {
+		ok: true,
+		matchedBy: "host-header-fallback"
+	};
+	if (params.isLocalClient && isLoopbackHost(parsedOrigin.hostname)) return {
+		ok: true,
+		matchedBy: "local-loopback"
+	};
+	return {
+		ok: false,
+		reason: "origin not allowed"
+	};
+}
+//#endregion
+export { checkBrowserOrigin };
+
+//# sourceMappingURL=origin-check.js.map

package/dist/src/gateway/security/origin-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin-check.js","names":[],"sources":["../../../../src/gateway/security/origin-check.ts"],"sourcesContent":["/**\n * Browser Origin checking for CSRF protection on HTTP and WebSocket requests.\n *\n * Validates that browser-initiated requests come from an allowed origin.\n * Non-browser requests (no Origin header) are handled by other auth layers.\n */\n\ntype OriginCheckResult =\n  | { ok: true; matchedBy: 'allowlist' | 'host-header-fallback' | 'local-loopback' }\n  | { ok: false; reason: string };\n\nconst LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);\n\nfunction isLoopbackHost(hostname: string): boolean {\n  return LOOPBACK_HOSTNAMES.has(hostname.toLowerCase());\n}\n\nfunction parseOriginHost(originRaw?: string): { origin: string; host: string; hostname: string } | null {\n  const trimmed = (originRaw ?? '').trim();\n  if (!trimmed || trimmed === 'null') {\n    return null;\n  }\n  try {\n    const url = new URL(trimmed);\n    return {\n      origin: url.origin.toLowerCase(),\n      host: url.host.toLowerCase(),\n      hostname: url.hostname.toLowerCase(),\n    };\n  } catch {\n    return null;\n  }\n}\n\nfunction normalizeHostHeader(hostRaw?: string): string {\n  const trimmed = (hostRaw ?? '').trim().toLowerCase();\n  // Strip port if present for comparison\n  return trimmed;\n}\n\nexport function checkBrowserOrigin(params: {\n  requestHost?: string;\n  origin?: string;\n  allowedOrigins?: string[];\n  allowHostHeaderOriginFallback?: boolean;\n  isLocalClient?: boolean;\n}): OriginCheckResult {\n  const parsedOrigin = parseOriginHost(params.origin);\n  if (!parsedOrigin) {\n    return { ok: false, reason: 'origin missing or invalid' };\n  }\n\n  const allowlist = new Set(\n    (params.allowedOrigins ?? [])\n      .map((value) => value.trim().toLowerCase())\n      .filter(Boolean),\n  );\n  if (allowlist.has('*') || allowlist.has(parsedOrigin.origin)) {\n    return { ok: true, matchedBy: 'allowlist' };\n  }\n\n  const requestHost = normalizeHostHeader(params.requestHost);\n  if (\n    params.allowHostHeaderOriginFallback === true &&\n    requestHost &&\n    parsedOrigin.host === requestHost\n  ) {\n    return { ok: true, matchedBy: 'host-header-fallback' };\n  }\n\n  // Dev fallback only for genuinely local socket clients, not Host-header claims.\n  if (params.isLocalClient && isLoopbackHost(parsedOrigin.hostname)) {\n    return { ok: true, matchedBy: 'local-loopback' };\n  }\n\n  return { ok: false, reason: 'origin not allowed' };\n}\n"],"mappings":";AAWA,MAAM,qBAAqB,IAAI,IAAI;CAAC;CAAa;CAAa;CAAO;CAAQ,CAAC;AAE9E,SAAS,eAAe,UAA2B;AACjD,QAAO,mBAAmB,IAAI,SAAS,aAAa,CAAC;;AAGvD,SAAS,gBAAgB,WAA+E;CACtG,MAAM,WAAW,aAAa,IAAI,MAAM;AACxC,KAAI,CAAC,WAAW,YAAY,OAC1B,QAAO;AAET,KAAI;EACF,MAAM,MAAM,IAAI,IAAI,QAAQ;AAC5B,SAAO;GACL,QAAQ,IAAI,OAAO,aAAa;GAChC,MAAM,IAAI,KAAK,aAAa;GAC5B,UAAU,IAAI,SAAS,aAAa;GACrC;SACK;AACN,SAAO;;;AAIX,SAAS,oBAAoB,SAA0B;AAGrD,SAFiB,WAAW,IAAI,MAAM,CAAC,aAEzB;;AAGhB,SAAgB,mBAAmB,QAMb;CACpB,MAAM,eAAe,gBAAgB,OAAO,OAAO;AACnD,KAAI,CAAC,aACH,QAAO;EAAE,IAAI;EAAO,QAAQ;EAA6B;CAG3D,MAAM,YAAY,IAAI,KACnB,OAAO,kBAAkB,EAAE,EACzB,KAAK,UAAU,MAAM,MAAM,CAAC,aAAa,CAAC,CAC1C,OAAO,QAAQ,CACnB;AACD,KAAI,UAAU,IAAI,IAAI,IAAI,UAAU,IAAI,aAAa,OAAO,CAC1D,QAAO;EAAE,IAAI;EAAM,WAAW;EAAa;CAG7C,MAAM,cAAc,oBAAoB,OAAO,YAAY;AAC3D,KACE,OAAO,kCAAkC,QACzC,eACA,aAAa,SAAS,YAEtB,QAAO;EAAE,IAAI;EAAM,WAAW;EAAwB;AAIxD,KAAI,OAAO,iBAAiB,eAAe,aAAa,SAAS,CAC/D,QAAO;EAAE,IAAI;EAAM,WAAW;EAAkB;AAGlD,QAAO;EAAE,IAAI;EAAO,QAAQ;EAAsB"}

package/dist/src/gateway/security/preauth-connection-budget.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pre-authentication connection budget per IP address.
+ *
+ * Limits the number of concurrent unauthenticated connections from a single
+ * IP to prevent connection-flood DoS attacks. Once a connection authenticates
+ * successfully, its slot is released.
+ */
+export declare function getMaxPreauthConnectionsPerIp(env?: NodeJS.ProcessEnv): number;
+export type PreauthConnectionBudget = {
+    /** Try to acquire a slot for the given client IP. Returns false if the budget is exhausted. */
+    acquire(clientIp: string | undefined): boolean;
+    /** Release a slot when the connection authenticates or closes. */
+    release(clientIp: string | undefined): void;
+    /** Current number of tracked IPs. */
+    size(): number;
+};
+export declare function createPreauthConnectionBudget(limit?: number): PreauthConnectionBudget;

package/dist/src/gateway/security/preauth-connection-budget.js

@@ -0,0 +1,49 @@
+//#region src/gateway/security/preauth-connection-budget.ts
+/**
+* Pre-authentication connection budget per IP address.
+*
+* Limits the number of concurrent unauthenticated connections from a single
+* IP to prevent connection-flood DoS attacks. Once a connection authenticates
+* successfully, its slot is released.
+*/
+const DEFAULT_MAX_PREAUTH_CONNECTIONS_PER_IP = 32;
+const UNKNOWN_CLIENT_IP_BUDGET_KEY = "__xopc_unknown_client_ip__";
+function getMaxPreauthConnectionsPerIp(env = process.env) {
+	const configured = env.XOPC_MAX_PREAUTH_CONNECTIONS_PER_IP;
+	if (!configured) return DEFAULT_MAX_PREAUTH_CONNECTIONS_PER_IP;
+	const parsed = Number(configured);
+	if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_MAX_PREAUTH_CONNECTIONS_PER_IP;
+	return Math.max(1, Math.floor(parsed));
+}
+function createPreauthConnectionBudget(limit = getMaxPreauthConnectionsPerIp()) {
+	const counts = /* @__PURE__ */ new Map();
+	function normalizeBudgetKey(clientIp) {
+		return clientIp?.trim() || UNKNOWN_CLIENT_IP_BUDGET_KEY;
+	}
+	return {
+		acquire(clientIp) {
+			const ip = normalizeBudgetKey(clientIp);
+			const next = (counts.get(ip) ?? 0) + 1;
+			if (next > limit) return false;
+			counts.set(ip, next);
+			return true;
+		},
+		release(clientIp) {
+			const ip = normalizeBudgetKey(clientIp);
+			const current = counts.get(ip);
+			if (current === void 0) return;
+			if (current <= 1) {
+				counts.delete(ip);
+				return;
+			}
+			counts.set(ip, current - 1);
+		},
+		size() {
+			return counts.size;
+		}
+	};
+}
+//#endregion
+export { createPreauthConnectionBudget, getMaxPreauthConnectionsPerIp };
+
+//# sourceMappingURL=preauth-connection-budget.js.map

package/dist/src/gateway/security/preauth-connection-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preauth-connection-budget.js","names":[],"sources":["../../../../src/gateway/security/preauth-connection-budget.ts"],"sourcesContent":["/**\n * Pre-authentication connection budget per IP address.\n *\n * Limits the number of concurrent unauthenticated connections from a single\n * IP to prevent connection-flood DoS attacks. Once a connection authenticates\n * successfully, its slot is released.\n */\n\nconst DEFAULT_MAX_PREAUTH_CONNECTIONS_PER_IP = 32;\nconst UNKNOWN_CLIENT_IP_BUDGET_KEY = '__xopc_unknown_client_ip__';\n\nexport function getMaxPreauthConnectionsPerIp(env: NodeJS.ProcessEnv = process.env): number {\n  const configured = env.XOPC_MAX_PREAUTH_CONNECTIONS_PER_IP;\n  if (!configured) {\n    return DEFAULT_MAX_PREAUTH_CONNECTIONS_PER_IP;\n  }\n  const parsed = Number(configured);\n  if (!Number.isFinite(parsed) || parsed < 1) {\n    return DEFAULT_MAX_PREAUTH_CONNECTIONS_PER_IP;\n  }\n  return Math.max(1, Math.floor(parsed));\n}\n\nexport type PreauthConnectionBudget = {\n  /** Try to acquire a slot for the given client IP. Returns false if the budget is exhausted. */\n  acquire(clientIp: string | undefined): boolean;\n  /** Release a slot when the connection authenticates or closes. */\n  release(clientIp: string | undefined): void;\n  /** Current number of tracked IPs. */\n  size(): number;\n};\n\nexport function createPreauthConnectionBudget(\n  limit = getMaxPreauthConnectionsPerIp(),\n): PreauthConnectionBudget {\n  const counts = new Map<string, number>();\n\n  function normalizeBudgetKey(clientIp: string | undefined): string {\n    const ip = clientIp?.trim();\n    // Keep unresolved IPs capped under a shared fallback bucket\n    // instead of failing open.\n    return ip || UNKNOWN_CLIENT_IP_BUDGET_KEY;\n  }\n\n  return {\n    acquire(clientIp) {\n      const ip = normalizeBudgetKey(clientIp);\n      const next = (counts.get(ip) ?? 0) + 1;\n      if (next > limit) {\n        return false;\n      }\n      counts.set(ip, next);\n      return true;\n    },\n\n    release(clientIp) {\n      const ip = normalizeBudgetKey(clientIp);\n      const current = counts.get(ip);\n      if (current === undefined) {\n        return;\n      }\n      if (current <= 1) {\n        counts.delete(ip);\n        return;\n      }\n      counts.set(ip, current - 1);\n    },\n\n    size() {\n      return counts.size;\n    },\n  };\n}\n"],"mappings":";;;;;;;;AAQA,MAAM,yCAAyC;AAC/C,MAAM,+BAA+B;AAErC,SAAgB,8BAA8B,MAAyB,QAAQ,KAAa;CAC1F,MAAM,aAAa,IAAI;AACvB,KAAI,CAAC,WACH,QAAO;CAET,MAAM,SAAS,OAAO,WAAW;AACjC,KAAI,CAAC,OAAO,SAAS,OAAO,IAAI,SAAS,EACvC,QAAO;AAET,QAAO,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,CAAC;;AAYxC,SAAgB,8BACd,QAAQ,+BAA+B,EACd;CACzB,MAAM,yBAAS,IAAI,KAAqB;CAExC,SAAS,mBAAmB,UAAsC;AAIhE,SAHW,UAAU,MAAM,IAGd;;AAGf,QAAO;EACL,QAAQ,UAAU;GAChB,MAAM,KAAK,mBAAmB,SAAS;GACvC,MAAM,QAAQ,OAAO,IAAI,GAAG,IAAI,KAAK;AACrC,OAAI,OAAO,MACT,QAAO;AAET,UAAO,IAAI,IAAI,KAAK;AACpB,UAAO;;EAGT,QAAQ,UAAU;GAChB,MAAM,KAAK,mBAAmB,SAAS;GACvC,MAAM,UAAU,OAAO,IAAI,GAAG;AAC9B,OAAI,YAAY,KAAA,EACd;AAEF,OAAI,WAAW,GAAG;AAChB,WAAO,OAAO,GAAG;AACjB;;AAEF,UAAO,IAAI,IAAI,UAAU,EAAE;;EAG7B,OAAO;AACL,UAAO,OAAO;;EAEjB"}

package/dist/src/gateway/security/secret-equal.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ *
+ * Uses `crypto.timingSafeEqual` with padding so both buffers always have
+ * the same byte length. The actual length is checked separately to reject
+ * mismatches without leaking position information.
+ */
+export declare function safeEqualSecret(provided: string | undefined | null, expected: string | undefined | null): boolean;

package/dist/src/gateway/security/secret-equal.js

@@ -0,0 +1,30 @@
+import { timingSafeEqual } from "node:crypto";
+//#region src/gateway/security/secret-equal.ts
+/**
+* Pad a Buffer to the target length by allocating a zeroed buffer and copying.
+*/
+function padSecretBytes(bytes, length) {
+	if (bytes.length === length) return bytes;
+	const padded = Buffer.alloc(length);
+	bytes.copy(padded);
+	return padded;
+}
+/**
+* Constant-time string comparison to prevent timing attacks.
+*
+* Uses `crypto.timingSafeEqual` with padding so both buffers always have
+* the same byte length. The actual length is checked separately to reject
+* mismatches without leaking position information.
+*/
+function safeEqualSecret(provided, expected) {
+	if (typeof provided !== "string" || typeof expected !== "string") return false;
+	const providedBytes = Buffer.from(provided, "utf8");
+	const expectedBytes = Buffer.from(expected, "utf8");
+	const byteLength = Math.max(providedBytes.length, expectedBytes.length);
+	if (byteLength === 0) return true;
+	return timingSafeEqual(padSecretBytes(providedBytes, byteLength), padSecretBytes(expectedBytes, byteLength)) && providedBytes.length === expectedBytes.length;
+}
+//#endregion
+export { safeEqualSecret };
+
+//# sourceMappingURL=secret-equal.js.map

package/dist/src/gateway/security/secret-equal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-equal.js","names":[],"sources":["../../../../src/gateway/security/secret-equal.ts"],"sourcesContent":["import { timingSafeEqual } from 'node:crypto';\n\n/**\n * Pad a Buffer to the target length by allocating a zeroed buffer and copying.\n */\nfunction padSecretBytes(bytes: Buffer, length: number): Buffer {\n  if (bytes.length === length) {\n    return bytes;\n  }\n  const padded = Buffer.alloc(length);\n  bytes.copy(padded);\n  return padded;\n}\n\n/**\n * Constant-time string comparison to prevent timing attacks.\n *\n * Uses `crypto.timingSafeEqual` with padding so both buffers always have\n * the same byte length. The actual length is checked separately to reject\n * mismatches without leaking position information.\n */\nexport function safeEqualSecret(\n  provided: string | undefined | null,\n  expected: string | undefined | null,\n): boolean {\n  if (typeof provided !== 'string' || typeof expected !== 'string') {\n    return false;\n  }\n  const providedBytes = Buffer.from(provided, 'utf8');\n  const expectedBytes = Buffer.from(expected, 'utf8');\n  const byteLength = Math.max(providedBytes.length, expectedBytes.length);\n  if (byteLength === 0) {\n    return true;\n  }\n  return (\n    timingSafeEqual(\n      padSecretBytes(providedBytes, byteLength),\n      padSecretBytes(expectedBytes, byteLength),\n    ) && providedBytes.length === expectedBytes.length\n  );\n}\n"],"mappings":";;;;;AAKA,SAAS,eAAe,OAAe,QAAwB;AAC7D,KAAI,MAAM,WAAW,OACnB,QAAO;CAET,MAAM,SAAS,OAAO,MAAM,OAAO;AACnC,OAAM,KAAK,OAAO;AAClB,QAAO;;;;;;;;;AAUT,SAAgB,gBACd,UACA,UACS;AACT,KAAI,OAAO,aAAa,YAAY,OAAO,aAAa,SACtD,QAAO;CAET,MAAM,gBAAgB,OAAO,KAAK,UAAU,OAAO;CACnD,MAAM,gBAAgB,OAAO,KAAK,UAAU,OAAO;CACnD,MAAM,aAAa,KAAK,IAAI,cAAc,QAAQ,cAAc,OAAO;AACvE,KAAI,eAAe,EACjB,QAAO;AAET,QACE,gBACE,eAAe,eAAe,WAAW,EACzC,eAAe,eAAe,WAAW,CAC1C,IAAI,cAAc,WAAW,cAAc"}

package/dist/src/gateway/service.d.ts

@@ -170,6 +170,8 @@ export declare class GatewayService {
     }, unknown>;
     /** Abort an in-flight webchat agent run (matches `runId` from SSE `status`). */
     abortAgentRun(runId: string): boolean;
+    /** Background drain for extension-initiated webchat turns (`scheduleWebchatContinuation`). */
+    private drainScheduledWebchatContinuation;
     /**
      * Queue steering text for an active webchat run (`Agent.steer` / tool-boundary injection).
      * `chatId` is the same as `POST /api/agent` body (`sessionKey` or legacy peer id).
@@ -429,7 +431,7 @@ export declare class GatewayService {
     /**
      * Get current auth mode.
      */
-    getAuthMode(): 'none' | 'token';
+    getAuthMode(): 'none' | 'token' | 'password';
     /**
      * Get current auth token (for CLI server integration).
      * Returns undefined if mode is 'none'.

package/dist/src/gateway/service.js

@@ -35,6 +35,8 @@ import { computeBundledExtensionExtensionsPatch } from "../extensions/bundled-ex
 import { HeartbeatService, heartbeatRunnerConfigFromConfig } from "./heartbeat/service.js";
 import "./heartbeat/index.js";
 import { assertGatewayAuthConfigured, extractToken, resolveGatewayAuth, validateToken } from "./auth.js";
+import { assertGatewayAuthNotKnownWeak } from "./security/known-weak-secrets.js";
+import { auditGatewayConfig } from "./security/audit.js";
 import { AgentRunRelay } from "./agent-run-relay.js";
 import { ClarifyBridge } from "./clarify-bridge.js";
 import { downloadSkillZipBuffer, fetchMarketplacePackageDetail, listSkillPackages, resolveSkillZipDownloadUrl, resolveSkillsStoreBaseUrl, skillIdForMarketplaceInstall } from "../agent/skills/skills-store-client.js";
@@ -86,6 +88,12 @@ var GatewayService = class {
 		this.config = loadConfig(this.configPath);
 		this.auth = resolveGatewayAuth({ authConfig: this.config.gateway?.auth });
 		assertGatewayAuthConfigured(this.auth);
+		assertGatewayAuthNotKnownWeak(this.auth);
+		auditGatewayConfig({
+			auth: this.auth,
+			host: this.config.gateway?.host,
+			corsOrigins: this.config.gateway?.corsOrigins
+		});
 		if (this.auth.mode === "token") {
 			const tokenPreview = this.auth.token ? `${this.auth.token.slice(0, 4)}***` : "none";
 			log.info({
@@ -199,7 +207,12 @@ var GatewayService = class {
 		this.channelManager.enableOutboundPersistence(resolveAgentDir(this.config, getDefaultAgentId(this.config)));
 		if (this.extensionLoader) this.extensionLoader.setRuntimeContext({
 			bus: this.bus,
-			sessionManager: this.sessionManager
+			sessionManager: this.sessionManager,
+			scheduleWebchatContinuation: (sessionKey, continuationMessage) => {
+				queueMicrotask(() => {
+					this.drainScheduledWebchatContinuation(sessionKey, continuationMessage);
+				});
+			}
 		});
 		await this.loadExtensionsAndRegisterChannels();
 		await this.channelManager.initialize();
@@ -609,7 +622,8 @@ var GatewayService = class {
 					peerKind: "direct",
 					peerId: chatId
 				});
-				const stampedMessage = prependEnvelopeTimestamp(message, this.agentService.resolveUserTimezoneForSession(sessionKey));
+				const timezone = this.agentService.resolveUserTimezoneForSession(sessionKey);
+				const stampedMessage = message.trimStart().startsWith("/") ? message : prependEnvelopeTimestamp(message, timezone);
 				const prepared = await this.agentService.prepareInboundAttachments(sessionKey, cappedAttachments);
 				try {
 					await this._saveUserMessage(sessionKey, message, prepared);
@@ -623,6 +637,7 @@ var GatewayService = class {
 				if (!runAbort) throw new Error("run abort controller missing for webchat");
 				const mergedSignal = runOptions?.signal ? AbortSignal.any([runOptions.signal, runAbort.signal]) : runAbort.signal;
 				this.activeWebchatRunBySession.set(sessionKey, runId);
+				let streamError;
 				try {
 					this.emit("agent.stream", {
 						sessionKey,
@@ -651,9 +666,10 @@ var GatewayService = class {
 					};
 				} catch (error) {
 					log.error({ error }, "Agent processing failed");
+					streamError = error instanceof Error ? error.message : "Unknown error";
 					const errorEvent = {
 						type: "error",
-						content: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+						content: `Error: ${streamError}`
 					};
 					this.runRelay.publish(runId, errorEvent);
 					this.emit("agent.stream", {
@@ -664,11 +680,19 @@ var GatewayService = class {
 					yield errorEvent;
 					return {
 						status: "error",
-						summary: error instanceof Error ? error.message : "Unknown error"
+						summary: streamError
 					};
 				} finally {
 					this.activeWebchatRunBySession.delete(sessionKey);
 					this.runAbortControllers.delete(runId);
+					const assistantPlainText = this.agentService.getLastAssistantPlainText(sessionKey);
+					await this.agentService.emitWebchatTurnComplete({
+						sessionKey,
+						inboundUserText: message,
+						assistantPlainText,
+						aborted: mergedSignal.aborted,
+						...streamError !== void 0 ? { streamError } : {}
+					});
 				}
 			}
 			const correlationMeta = inboundCorrelationMetadataFromAsyncLogContext();
@@ -706,6 +730,18 @@ var GatewayService = class {
 		c.abort();
 		return true;
 	}
+	/** Background drain for extension-initiated webchat turns (`scheduleWebchatContinuation`). */
+	async drainScheduledWebchatContinuation(sessionKey, message) {
+		try {
+			const gen = this.runAgent(message, "webchat", sessionKey, void 0, void 0, void 0);
+			for await (const _ of gen);
+		} catch (err) {
+			log.warn({
+				err,
+				sessionKey
+			}, "Scheduled webchat continuation failed");
+		}
+	}
 	/**
 	* Queue steering text for an active webchat run (`Agent.steer` / tool-boundary injection).
 	* `chatId` is the same as `POST /api/agent` body (`sessionKey` or legacy peer id).