@andypai/agent-kanban 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {

package/src/__tests__/webhooks.test.ts

@@ -6,6 +6,7 @@ import {
   headerLower,
   verifyHmacSha256,
   verifySha256HmacSignatureHeader,
+  webhookSignatureStatus,
 } from '../webhooks'
 import { JiraProvider, type JiraProviderConfig } from '../providers/jira'
 import { JiraClient } from '../providers/jira-client'
@@ -98,7 +99,12 @@ describe('authorizeWebhook (F32)', () => {
       signature: 'deadbeef',
       verify,
     })
-    expect(result).toEqual({ handled: false, unauthorized: true, message: 'Invalid signature' })
+    expect(result).toEqual({
+      handled: false,
+      unauthorized: true,
+      message: 'Invalid signature',
+      signatureStatus: 'invalid',
+    })
   })
 })
 
@@ -792,3 +798,46 @@ describe('webhook open dev mode when secret is unset', () => {
     }
   })
 })
+
+describe('webhookSignatureStatus', () => {
+  const verify = verifySha256HmacSignatureHeader
+  const body = '{"hello":"world"}'
+
+  test('no secret configured -> not_configured', () => {
+    expect(
+      webhookSignatureStatus({ secret: undefined, rawBody: body, signature: null, verify }),
+    ).toBe('not_configured')
+  })
+
+  test('secret configured, no signature header -> missing', () => {
+    expect(webhookSignatureStatus({ secret: 's3', rawBody: body, signature: null, verify })).toBe(
+      'missing',
+    )
+  })
+
+  test('bad signature -> invalid; good signature -> valid', () => {
+    expect(
+      webhookSignatureStatus({ secret: 's3', rawBody: body, signature: 'sha256=nope', verify }),
+    ).toBe('invalid')
+    expect(
+      webhookSignatureStatus({
+        secret: 's3',
+        rawBody: body,
+        signature: `sha256=${hmac('s3', body)}`,
+        verify,
+      }),
+    ).toBe('valid')
+  })
+
+  test('authorizeWebhook rejections carry the verdict', () => {
+    const rejected = authorizeWebhook({
+      secret: 's3',
+      rawBody: body,
+      signature: 'sha256=nope',
+      verify,
+    })
+    expect(rejected?.signatureStatus).toBe('invalid')
+    const noHeader = authorizeWebhook({ secret: 's3', rawBody: body, signature: null, verify })
+    expect(noHeader?.signatureStatus).toBe('missing')
+  })
+})

package/src/providers/jira-core.ts

@@ -13,6 +13,7 @@ import type {
 } from '../types'
 import {
   authorizeWebhook,
+  webhookSignatureStatus,
   headerLower,
   verifySha256HmacSignatureHeader,
   type WebhookRequest,
@@ -368,8 +369,8 @@ export class JiraProviderCore implements KanbanProvider {
         }
       }
 
-      // Fetch changelog per changed issue so the poll-based
-      // `moved` trigger in @garage/dispatch works. Server-side dedupe
+      // Fetch changelog per changed issue so a downstream consumer's
+      // poll-based `moved` trigger works. Server-side dedupe
       // keyed on (issue_id, history_id, item_field) keeps this cheap
       // even if the same issue is updated repeatedly.
       await forEachWithConcurrency(page.issues, 5, async (issue) => {
@@ -884,36 +885,47 @@ export class JiraProviderCore implements KanbanProvider {
         `[jira] ${WEBHOOK_SECRET_ENV['jira']} is not set — accepting webhook without signature verification (open dev mode)`,
       )
     }
+    const signature = headerLower(payload.headers, 'x-hub-signature')
+    const signatureStatus = webhookSignatureStatus({
+      secret,
+      rawBody: payload.rawBody,
+      signature,
+      verify: verifySha256HmacSignatureHeader,
+    })
     const auth = authorizeWebhook({
       secret,
       rawBody: payload.rawBody,
-      signature: headerLower(payload.headers, 'x-hub-signature'),
+      signature,
       verify: verifySha256HmacSignatureHeader,
     })
-    if (auth) return auth
+    if (auth) return { ...auth, signatureStatus }
+    const attachVerdict = (result: WebhookResult): WebhookResult => ({
+      ...result,
+      signatureStatus,
+    })
     let body: { webhookEvent?: string; issue?: JiraIssue } = {}
     try {
       body = JSON.parse(payload.rawBody) as typeof body
     } catch {
-      return { handled: false, message: 'Invalid JSON body' }
+      return attachVerdict({ handled: false, message: 'Invalid JSON body' })
     }
     const event = body.webhookEvent ?? ''
     const issue = body.issue
-    if (!issue) return { handled: false, message: `No issue in payload (${event})` }
+    if (!issue) return attachVerdict({ handled: false, message: `No issue in payload (${event})` })
 
     if (event === 'jira:issue_deleted') {
       await this.cache.deleteIssue(issue.id)
       await this.cache.saveSyncMeta({ lastWebhookAt: new Date().toISOString() })
-      return { handled: true }
+      return attachVerdict({ handled: true })
     }
 
     if (event === 'jira:issue_created' || event === 'jira:issue_updated') {
       const projectKey = issue.fields.project?.key
       if (projectKey !== this.config.projectKey) {
-        return {
+        return attachVerdict({
           handled: false,
           message: `Ignoring issue from project '${projectKey ?? 'unknown'}'`,
-        }
+        })
       }
       await this.cache.upsertIssues([
         toCacheIssue(issue, this.config.baseUrl, this.config.projectKey),
@@ -924,9 +936,9 @@ export class JiraProviderCore implements KanbanProvider {
         })
       }
       await this.cache.saveSyncMeta({ lastWebhookAt: new Date().toISOString() })
-      return { handled: true }
+      return attachVerdict({ handled: true })
     }
 
-    return { handled: false, message: `Unsupported event: ${event}` }
+    return attachVerdict({ handled: false, message: `Unsupported event: ${event}` })
   }
 }

package/src/webhook-events.ts

@@ -1,8 +1,9 @@
 /**
  * `webhook_events` — a small, generically-named receipts table that the Postgres
  * providers append to on every received webhook. It is *not* used by agent-kanban
- * itself; it exists so an external consumer (Garage Band's Studio "Webhooks"
- * panel) can show "did the sidecar receive/process a tracker webhook, and when".
+ * itself; it exists so an external consumer (for example a software factory's
+ * dashboard "Webhooks" panel) can show "did the sidecar receive/process a
+ * tracker webhook, and when".
  *
  * Ownership: agent-kanban owns and creates this table; consumers read it
  * read-only. Columns a consumer can rely on:
@@ -94,6 +95,9 @@ export async function withWebhookRecording(
     provider,
     ...meta,
     status: webhookEventStatus(result),
+    ...(result.signatureStatus === undefined
+      ? {}
+      : { detail: { signatureStatus: result.signatureStatus } }),
   })
   return result
 }

package/src/webhooks.ts

@@ -6,10 +6,14 @@ export interface WebhookRequest {
   rawBody: string
 }
 
+export type WebhookSignatureStatus = 'valid' | 'invalid' | 'missing' | 'not_configured'
+
 export interface WebhookResult {
   handled: boolean
   unauthorized?: boolean
   message?: string
+  /** Persisted signature verdict for this delivery (never a guess). */
+  signatureStatus?: WebhookSignatureStatus
 }
 
 /**
@@ -26,11 +30,33 @@ export function authorizeWebhook(opts: {
   const { secret, rawBody, signature, verify } = opts
   if (!secret) return null
   if (!verify(secret, rawBody, signature)) {
-    return { handled: false, unauthorized: true, message: 'Invalid signature' }
+    return {
+      handled: false,
+      unauthorized: true,
+      message: 'Invalid signature',
+      signatureStatus: signature ? 'invalid' : 'missing',
+    }
   }
   return null
 }
 
+/**
+ * Signature verdict for a delivery, computed the same way authorizeWebhook
+ * decides authorization. Providers attach this to every WebhookResult so the
+ * receipts table persists a true verdict instead of leaving consumers to guess.
+ */
+export function webhookSignatureStatus(opts: {
+  secret: string | undefined
+  rawBody: string
+  signature: string | undefined | null
+  verify: (secret: string, rawBody: string, signature: string | undefined | null) => boolean
+}): WebhookSignatureStatus {
+  const { secret, rawBody, signature, verify } = opts
+  if (!secret) return 'not_configured'
+  if (!signature) return 'missing'
+  return verify(secret, rawBody, signature) ? 'valid' : 'invalid'
+}
+
 export function verifyHmacSha256(
   secret: string,
   rawBody: string,