@andypai/agent-kanban 0.7.0 → 0.8.0

package/src/tracker-config.ts

@@ -1,9 +1,60 @@
 import { ErrorCode, KanbanError } from './errors'
 import { providerNotConfigured } from './providers/errors'
 import { resolvePollingSyncIntervalMs } from './sync-config'
+import { parseDecimalDigits } from './transport-input'
 
 export type TrackerProvider = 'local' | 'linear' | 'jira'
 
+/**
+ * Single source of truth for which env var holds each provider's webhook signing
+ * secret (`null` = the provider has no webhook ingestion). Typed as
+ * `Record<TrackerProvider, …>`, so adding a new provider to the union is a
+ * compile error here until its secret env is declared — preventing a new
+ * webhook-capable provider from silently slipping past the tunnel-security gate
+ * (assertTunnelSecurity) with no secret enforced.
+ */
+export const WEBHOOK_SECRET_ENV: Record<TrackerProvider, string | null> = {
+  local: null,
+  linear: 'LINEAR_WEBHOOK_SECRET',
+  jira: 'JIRA_WEBHOOK_SECRET',
+}
+
+/**
+ * Normalize the raw `KANBAN_PROVIDER` env value to a known `TrackerProvider`,
+ * falling back to `'local'` for anything unset/unrecognized — matching how
+ * trackerConfigFromEnv resolves the provider. Centralized so the security gate
+ * and the config loader agree on a single derivation.
+ */
+export function trackerProviderFromEnv(
+  env: Record<string, string | undefined> = process.env,
+): TrackerProvider {
+  const raw = (env['KANBAN_PROVIDER'] ?? 'local').trim().toLowerCase()
+  // Recognize exactly the providers declared in WEBHOOK_SECRET_ENV — own keys
+  // only, so inherited names like "constructor"/"toString" don't match — and
+  // fall back to local otherwise. Deriving from the map keeps this normalizer in
+  // lockstep with it, so a newly-added provider is picked up here automatically.
+  return Object.prototype.hasOwnProperty.call(WEBHOOK_SECRET_ENV, raw)
+    ? (raw as TrackerProvider)
+    : 'local'
+}
+
+/**
+ * Resolve a provider's webhook signing secret from `env` via WEBHOOK_SECRET_ENV
+ * (the single source of truth), returning `undefined` when the provider declares
+ * no secret env or the env var is unset — the case where the webhook handler
+ * falls back to open dev mode. The runtime signature enforcement (the provider
+ * webhook handlers) and the assertTunnelSecurity tunnel gate both resolve the
+ * secret env name through this same map, so the gate cannot require one env name
+ * while enforcement reads another (a fail-open if they drifted).
+ */
+export function webhookSecretFromEnv(
+  provider: TrackerProvider,
+  env: Record<string, string | undefined> = process.env,
+): string | undefined {
+  const envName = WEBHOOK_SECRET_ENV[provider]
+  return envName ? env[envName] : undefined
+}
+
 export interface LocalTrackerConfig {
   provider: 'local'
   defaultColumns?: string[]
@@ -34,7 +85,7 @@ export type TrackerConfig = LocalTrackerConfig | LinearTrackerConfig | JiraTrack
 export function trackerConfigFromEnv(
   env: Record<string, string | undefined> = process.env,
 ): TrackerConfig {
-  const provider = (env['KANBAN_PROVIDER'] ?? 'local').trim().toLowerCase()
+  const provider = trackerProviderFromEnv(env)
 
   if (provider === 'linear') {
     const apiKey = env['LINEAR_API_KEY']
@@ -70,15 +121,14 @@ export function trackerConfigFromEnv(
         `${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} required when KANBAN_PROVIDER=jira`,
       )
     }
-    const boardIdRaw = env['JIRA_BOARD_ID']
-    const boardId = boardIdRaw ? Number.parseInt(boardIdRaw, 10) : undefined
+    const boardId = jiraBoardIdFromEnv(env['JIRA_BOARD_ID'])
     return {
       provider,
       baseUrl: baseUrl!,
       email: email!,
       apiToken: apiToken!,
       projectKey: projectKey!,
-      ...(Number.isFinite(boardId) ? { boardId } : {}),
+      ...(boardId !== undefined ? { boardId } : {}),
       defaultIssueType: env['JIRA_ISSUE_TYPE'] ?? 'Task',
       syncIntervalMs: resolvePollingSyncIntervalMs(env['KANBAN_SYNC_INTERVAL_MS']),
     }
@@ -94,6 +144,24 @@ export function trackerConfigFromEnv(
   }
 }
 
+/**
+ * Resolve the optional `JIRA_BOARD_ID` env var to a positive integer board id.
+ * Unset/blank → `undefined` (no board pinned). A set-but-invalid value throws
+ * `INVALID_CONFIG` rather than silently falling back: the previous
+ * `Number.parseInt` accepted trailing garbage and signs (`'12abc'→12`,
+ * `'-5'→-5`, `'1e3'→1`), quietly pinning a *wrong* board. This matches how
+ * resolvePollingSyncIntervalMs treats a malformed optional numeric env var.
+ */
+function jiraBoardIdFromEnv(raw: string | undefined): number | undefined {
+  const value = raw?.trim()
+  if (!value) return undefined
+  const parsed = parseDecimalDigits(value)
+  if (parsed === null || parsed < 1) {
+    throw new KanbanError(ErrorCode.INVALID_CONFIG, 'JIRA_BOARD_ID must be a positive integer')
+  }
+  return parsed
+}
+
 function defaultColumnsFromEnv(env: Record<string, string | undefined>): string[] | undefined {
   const raw = env['KANBAN_DEFAULT_COLUMNS']?.trim()
   if (!raw) return undefined

package/src/transport-input.ts

@@ -1,26 +1,58 @@
 import { ErrorCode, KanbanError } from './errors'
 
 /**
- * Parse an optional positive integer supplied through a transport boundary
- * (HTTP query string, CLI flag). Returns `undefined` when the value is absent,
- * and throws a `KanbanError(INVALID_ARGUMENT)` for anything that is not a
- * positive integer — `NaN`, negatives, zero, decimals, and trailing-garbage
- * strings like `"5abc"`. Centralizing this keeps invalid limits from leaking
- * into provider logic, where they would otherwise produce inconsistent
- * behavior across SQL `LIMIT`, `Array.prototype.slice`, and Postgres.
+ * Parse a plain decimal-digit string into an exact non-negative integer, or
+ * `null` if it is not one. Rejects signs, decimals, and exponent/hex forms like
+ * `"-1"` / `"3.5"` / `"1e100"` / `"0x10"` that `Number()` would otherwise coerce
+ * to an integer, and rejects an over-long digit string that `Number()` rounds
+ * past `MAX_SAFE_INTEGER` or overflows to `Infinity`, so the result is always
+ * exact. Surrounding whitespace is trimmed. This is the shared digits-only
+ * primitive the throwing boundary/config parsers (`parseBoundedInt`,
+ * `resolvePollingSyncIntervalMs`, the JIRA_BOARD_ID loader) build on — keeping a
+ * single definition of "what counts as an integer" so they can't drift.
+ */
+export function parseDecimalDigits(value: string): number | null {
+  const trimmed = value.trim()
+  if (!/^\d+$/.test(trimmed)) return null
+  const parsed = Number(trimmed)
+  return Number.isSafeInteger(parsed) ? parsed : null
+}
+
+/**
+ * Parse a required integer supplied through a transport boundary (HTTP query
+ * string, CLI flag) into the inclusive range `[min, max]` (max defaults to
+ * `MAX_SAFE_INTEGER`), via {@link parseDecimalDigits}. Throws
+ * `KanbanError(INVALID_ARGUMENT)` on any violation.
+ */
+export function parseBoundedInt(
+  value: string,
+  opts: { min: number; max?: number; field: string },
+): number {
+  const parsed = parseDecimalDigits(value)
+  const max = opts.max ?? Number.MAX_SAFE_INTEGER
+  if (parsed === null || parsed < opts.min || parsed > max) {
+    const range = opts.max === undefined ? `>= ${opts.min}` : `between ${opts.min} and ${opts.max}`
+    throw new KanbanError(ErrorCode.INVALID_ARGUMENT, `${opts.field} must be an integer ${range}`)
+  }
+  return parsed
+}
+
+/**
+ * Parse an optional positive integer supplied through a transport boundary.
+ * Returns `undefined` when the value is absent/blank, otherwise resolves via
+ * {@link parseDecimalDigits} (which trims and caps at `MAX_SAFE_INTEGER`) and
+ * enforces `>= 1`, throwing `KanbanError(INVALID_ARGUMENT)` framed as "positive
+ * integer" so invalid limits don't leak into provider logic (SQL `LIMIT`,
+ * `slice`, PG).
  */
 export function parsePositiveInt(
   value: string | null | undefined,
   field = 'limit',
 ): number | undefined {
   if (value === null || value === undefined) return undefined
-  const trimmed = value.trim()
-  if (trimmed === '') return undefined
-  // Plain decimal digits only — reject signs, decimals, and exponent forms like
-  // "1e100" that Number() would otherwise treat as integers and let escape into
-  // SQL `LIMIT`. Cap at MAX_SAFE_INTEGER so the parsed value stays exact.
-  const parsed = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN
-  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > Number.MAX_SAFE_INTEGER) {
+  if (value.trim() === '') return undefined
+  const parsed = parseDecimalDigits(value)
+  if (parsed === null || parsed < 1) {
     throw new KanbanError(
       ErrorCode.INVALID_ARGUMENT,
       `${field} must be a positive integer (received '${value}')`,

package/src/tunnel.ts

@@ -57,15 +57,32 @@ export function startCloudflareTunnel(port: number, opts: TunnelOptions = {}): T
   ): Promise<void> => {
     if (!stream) return
     const decoder = new TextDecoder()
+    // Accumulate across chunks: cloudflared may split the URL across read
+    // boundaries, so matching each chunk in isolation can miss it.
+    let buffer = ''
     for await (const chunk of stream) {
-      const text = decoder.decode(chunk as Uint8Array, { stream: true })
-      const match = text.match(TRYCLOUDFLARE_URL)
-      if (match) announce(match[0])
+      // Once announced, keep draining the pipe (so the child doesn't block on a
+      // full stdout buffer) but stop scanning.
+      if (announced) continue
+      buffer += decoder.decode(chunk as Uint8Array, { stream: true })
+      const match = buffer.match(TRYCLOUDFLARE_URL)
+      if (match) {
+        announce(match[0])
+      } else if (buffer.length > 4096) {
+        // Bound memory while keeping a tail long enough to span a split URL.
+        buffer = buffer.slice(-256)
+      }
     }
   }
 
-  void scanForUrl(child.stdout as ReadableStream<Uint8Array>)
-  void scanForUrl(child.stderr as ReadableStream<Uint8Array>)
+  // A stream error while draining stdout/stderr (e.g. the pipe tears down as the
+  // child is killed) must not surface as an unhandled rejection; the child.exited
+  // handler below still emits the no-URL warning when nothing was announced.
+  const drain = (stream: ReadableStream<Uint8Array> | null | undefined): void => {
+    void scanForUrl(stream).catch(() => {})
+  }
+  drain(child.stdout as ReadableStream<Uint8Array>)
+  drain(child.stderr as ReadableStream<Uint8Array>)
 
   void child.exited.then((code) => {
     if (!announced) {