@aiacta-org/ai-citation-sdk 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+# @aiacta-org/ai-citation-sdk
+
+> Webhook receiver SDK for AIACTA citation events — verifies signatures, handles idempotency, and provides ready-to-use Express middleware (Proposal 2, §3.4).
+
+[![npm version](https://img.shields.io/npm/v/@aiacta-org/ai-citation-sdk.svg)](https://www.npmjs.com/package/@aiacta-org/ai-citation-sdk)
+[![PyPI version](https://img.shields.io/pypi/v/ai-citation-sdk.svg)](https://pypi.org/project/ai-citation-sdk/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+[![AIACTA Spec](https://img.shields.io/badge/spec-AIACTA%2F1.0-orange.svg)](../../docs/proposals/proposal-2-citation-webhooks.md)
+
+Available in **Node.js**, **Python**, and **Go**.
+
+---
+
+## What is this?
+
+When an AI provider (Anthropic, OpenAI, Google, etc.) cites your content in a response, they POST a signed event to your `Citation-Webhook` endpoint. This SDK handles the security and plumbing so you can focus on what to do with the data.
+
+It provides:
+- **Signature verification** — HMAC-SHA256 with constant-time comparison (prevents timing attacks)
+- **Replay attack prevention** — timestamps validated within a ±5-minute window
+- **Idempotency** — duplicate events are safely ignored
+- **Express middleware** — drop-in handler for Node.js servers
+- **Retry schedule** — implements the §3.5 six-attempt delivery retry
+
+---
+
+## Install
+
+**Node.js**
+```bash
+npm install @aiacta-org/ai-citation-sdk
+```
+
+**Python**
+```bash
+pip install ai-citation-sdk
+```
+
+**Go**
+```bash
+go get github.com/aiacta-org/aiacta/ai-citation-sdk
+```
+
+---
+
+## Quick Start
+
+### Node.js — Express middleware (recommended)
+
+```javascript
+const express = require('express');
+const { createExpressMiddleware } = require('@aiacta-org/ai-citation-sdk');
+
+const app = express();
+
+// IMPORTANT: express.raw() must come before the middleware.
+// Signature verification requires the raw bytes, not parsed JSON.
+app.post(
+  '/webhooks/ai-citations',
+  express.raw({ type: 'application/json' }),
+  createExpressMiddleware({
+    secret: process.env.WEBHOOK_SECRET,
+
+    // Idempotency store — prevents processing the same event twice.
+    // Replace with your database in production.
+    store: {
+      exists: async (key) => await db.citations.exists({ idempotency_key: key }),
+      set:    async (key) => await db.citations.markProcessed(key),
+    },
+
+    // Called once per unique, verified event
+    onEvent: async (event) => {
+      console.log('Citation received:', event.citation.url);
+      await db.citations.insert(event);
+    },
+  })
+);
+
+app.listen(3000);
+```
+
+### Node.js — manual verification
+
+```javascript
+const { verifyWebhookSignature } = require('@aiacta-org/ai-citation-sdk');
+
+app.post('/webhooks/ai-citations', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    const valid = verifyWebhookSignature(
+      req.body,                                    // raw Buffer
+      req.headers['x-ai-webhook-timestamp'],       // UNIX seconds string
+      req.headers['x-ai-webhook-sig'],             // 'sha256=<hex>'
+      process.env.WEBHOOK_SECRET
+    );
+    if (!valid) return res.status(401).json({ error: 'Invalid signature' });
+  } catch (err) {
+    // Timestamp outside ±5 min window — possible replay attack
+    return res.status(400).json({ error: err.message });
+  }
+
+  res.status(200).json({ status: 'accepted' });
+
+  const event = JSON.parse(req.body.toString());
+  console.log('Provider:', event.provider);
+  console.log('Cited URL:', event.citation.url);
+});
+```
+
+### Python
+
+```python
+from aiacta import verify_webhook_signature
+
+@app.route('/webhooks/ai-citations', methods=['POST'])
+def citation_webhook():
+    raw_body  = request.get_data()
+    timestamp = request.headers.get('X-AI-Webhook-Timestamp')
+    sig       = request.headers.get('X-AI-Webhook-Sig')
+    secret    = os.environ['WEBHOOK_SECRET']
+
+    try:
+        valid = verify_webhook_signature(raw_body, timestamp, sig, secret)
+    except ValueError as e:
+        return {'error': str(e)}, 400
+
+    if not valid:
+        return {'error': 'Invalid signature'}, 401
+
+    event = request.get_json(force=True)
+    print(f"Citation: {event['citation']['url']} via {event['provider']}")
+    return {'status': 'accepted'}, 200
+```
+
+### Go
+
+```go
+import "github.com/aiacta-org/aiacta/ai-citation-sdk"
+
+func webhookHandler(w http.ResponseWriter, r *http.Request) {
+    body, _ := io.ReadAll(r.Body)
+    timestamp := r.Header.Get("X-AI-Webhook-Timestamp")
+    sig       := r.Header.Get("X-AI-Webhook-Sig")
+    secret    := os.Getenv("WEBHOOK_SECRET")
+
+    ok, err := aiacta.VerifyWebhookSignature(body, timestamp, sig, secret)
+    if err != nil {
+        http.Error(w, err.Error(), http.StatusBadRequest)
+        return
+    }
+    if !ok {
+        http.Error(w, "Invalid signature", http.StatusUnauthorized)
+        return
+    }
+
+    w.WriteHeader(http.StatusOK)
+    // process event...
+}
+```
+
+---
+
+## Citation Event Schema
+
+```json
+{
+  "schema_version": "1.0",
+  "provider": "anthropic",
+  "event_type": "citation.generated",
+  "event_id": "evt_01J4KXQN2QP7HBW8FMYRC3T5VZ",
+  "idempotency_key": "idem_01J4KXQN_f3a9b2c1",
+  "timestamp": "2026-03-24T09:14:00Z",
+  "citation": {
+    "url": "https://yourdomain.com/articles/your-article",
+    "citation_type": "factual_source",
+    "context_summary": "Used to answer question about ...",
+    "query_category_l1": "technology",
+    "model": "claude-3-5-sonnet",
+    "user_country": "US"
+  },
+  "attribution": {
+    "display_type": "inline_link",
+    "user_interface": "chat"
+  }
+}
+```
+
+**Privacy note:** `user_country` is always country-level only. AI providers are prohibited from including user IDs or sub-country geodata (§3.3).
+
+---
+
+## Security Details
+
+The signature covers: `timestamp + "." + raw_json_body`
+
+```
+signature = HMAC-SHA256(shared_secret, signed_payload)
+header    = "sha256=" + hex(signature)
+```
+
+The SDK uses `crypto.timingSafeEqual()` (Node.js), `hmac.compare_digest()` (Python), and `hmac.Equal()` (Go) to prevent timing oracle attacks.
+
+---
+
+## API Reference
+
+### Node.js
+
+| Export | Description |
+|--------|-------------|
+| `verifyWebhookSignature(payload, timestamp, sigHeader, secret)` | Returns `boolean`. Throws `Error` if timestamp is outside ±300s. |
+| `processEvent(event, store, onEvent)` | Processes with idempotency check. |
+| `createExpressMiddleware({ secret, store, onEvent })` | Drop-in Express route handler. |
+
+### Python
+
+| Function | Description |
+|----------|-------------|
+| `verify_webhook_signature(payload, timestamp, sig_header, secret)` | Returns `True` if valid. Raises `ValueError` on timestamp violation. |
+
+### Go
+
+| Function | Description |
+|----------|-------------|
+| `VerifyWebhookSignature(rawBody, timestamp, sigHeader, secret)` | Returns `(bool, error)`. Error if timestamp outside window. |
+| `ProcessEvent(events, store, handler)` | Idempotent batch processing. |
+| `TruncateToMinute(t time.Time)` | Timestamp formatting per §3.2. |
+
+---
+
+## Related packages
+
+| Package | Purpose |
+|---------|---------|
+| [`@aiacta-org/ai-attribution-lint`](https://www.npmjs.com/package/@aiacta-org/ai-attribution-lint) | Validate your `ai-attribution.txt` |
+| [`@aiacta-org/crawl-manifest-client`](https://www.npmjs.com/package/@aiacta-org/crawl-manifest-client) | Query AI providers' crawl history |
+
+---
+
+## License & Copyright
+
+Copyright © 2026 Eric Michel, PhD. Licensed under the [Apache License 2.0](../../LICENSE).
+
+Part of the [AIACTA open standard](https://github.com/aiacta-org/aiacta).

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@aiacta-org/ai-citation-sdk",
+  "version": "1.0.0",
+  "description": "Webhook receiver SDK with signature verification, idempotency, and GDPR-compliant storage patterns (AIACTA Proposal 2 §3.4)",
+  "author": "Eric Michel",
+  "main": "./src/node/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "dependencies": {
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0",
+    "supertest": "^7.0.0"
+  }
+}

package/src/go/aiacta.go

@@ -0,0 +1,134 @@
+// Package aiacta provides the Go implementation of the AIACTA Citation SDK (§3.4).
+//
+// Implements:
+//   - VerifyWebhookSignature — HMAC-SHA256 request verification (§3.4A)
+//   - ProcessEvent           — Idempotent citation event processing (§3.2)
+//   - WithRetry              — Delivery retry schedule (§3.5)
+//   - TruncateToMinute       — Event timestamp minute precision (§3.2)
+package aiacta
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// TimestampToleranceSeconds is the maximum allowed clock skew for webhook
+// signature verification, preventing replay attacks (§3.4A).
+const TimestampToleranceSeconds = 300
+
+// RetryDelaysSeconds defines the delivery retry schedule (§3.5).
+// Attempt 1: immediate, Attempt 2: 30s, 3: 5m, 4: 30m, 5: 2h, 6: 12h.
+var RetryDelaysSeconds = []int{0, 30, 300, 1800, 7200, 43200}
+
+// CitationEvent represents a single AIACTA citation event payload (§3.2).
+type CitationEvent struct {
+	SchemaVersion  string     `json:"schema_version"`
+	Provider       string     `json:"provider"`
+	EventType      string     `json:"event_type"`
+	EventID        string     `json:"event_id"`
+	IdempotencyKey string     `json:"idempotency_key"`
+	Timestamp      string     `json:"timestamp"` // minute precision only (§3.2)
+	Citation       Citation   `json:"citation"`
+	Attribution    Attribution `json:"attribution"`
+}
+
+// Citation holds the per-event citation details.
+type Citation struct {
+	URL              string `json:"url"`
+	CitationType     string `json:"citation_type"`
+	ContextSummary   string `json:"context_summary,omitempty"`
+	QueryCategoryL1  string `json:"query_category_l1,omitempty"`
+	QueryCategoryL2  string `json:"query_category_l2,omitempty"`
+	Model            string `json:"model,omitempty"`
+	ResponseLocale   string `json:"response_locale,omitempty"`
+	UserCountry      string `json:"user_country,omitempty"` // country-level only (§3.3)
+}
+
+// Attribution describes how the citation was presented to the user.
+type Attribution struct {
+	DisplayType   string `json:"display_type"`
+	UserInterface string `json:"user_interface"`
+}
+
+// VerifyWebhookSignature validates an X-AI-Webhook-Sig header.
+//
+// The signature covers the string "${timestamp}.${rawBody}" using HMAC-SHA256
+// with the shared secret issued at enrollment (§3.4A).
+//
+// Returns an error if the timestamp is outside the tolerance window
+// (possible replay attack) or if the signature does not match.
+func VerifyWebhookSignature(rawBody []byte, timestamp, sigHeader, secret string) (bool, error) {
+	ts, err := strconv.ParseInt(timestamp, 10, 64)
+	if err != nil {
+		return false, fmt.Errorf("invalid timestamp value %q: %w", timestamp, err)
+	}
+	if math.Abs(float64(time.Now().Unix()-ts)) > TimestampToleranceSeconds {
+		return false, fmt.Errorf("timestamp outside %ds tolerance window — possible replay attack", TimestampToleranceSeconds)
+	}
+
+	// signed = timestamp + "." + rawBody
+	signed := append([]byte(timestamp+"."), rawBody...)
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(signed)
+	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
+	received := strings.TrimPrefix(sigHeader, "sha256=")
+
+	// Constant-time comparison to prevent timing attacks
+	return hmac.Equal([]byte(expected), []byte("sha256="+received)), nil
+}
+
+// TruncateToMinute truncates an ISO 8601 timestamp to minute precision
+// as required by §3.2 (prevents timing-attack re-identification of users).
+func TruncateToMinute(t time.Time) string {
+	truncated := time.Date(t.Year(), t.Month(), t.Day(), t.Hour(), t.Minute(), 0, 0, time.UTC)
+	return truncated.Format("2006-01-02T15:04:00Z")
+}
+
+// IdempotencyStore is the interface that callers must implement to track
+// processed event keys (§3.2: safe at-least-once reprocessing).
+type IdempotencyStore interface {
+	// Has returns true if the key has already been processed.
+	Has(key string) bool
+	// Set marks the key as processed.
+	Set(key string)
+}
+
+// EventHandler is called once per unique citation event.
+type EventHandler func(event CitationEvent) error
+
+// ProcessEvent processes a single CitationEvent or a batch, skipping
+// events whose idempotency_key has already been processed (§3.2).
+func ProcessEvent(events []CitationEvent, store IdempotencyStore, handler EventHandler) error {
+	for _, e := range events {
+		if store.Has(e.IdempotencyKey) {
+			continue
+		}
+		if err := handler(e); err != nil {
+			return fmt.Errorf("handler error for event %s: %w", e.EventID, err)
+		}
+		store.Set(e.IdempotencyKey)
+	}
+	return nil
+}
+
+// WithRetry executes fn up to len(RetryDelaysSeconds) times using the
+// AIACTA delivery retry schedule (§3.5). Returns an error if all attempts fail.
+func WithRetry(fn func() error) error {
+	for attempt, delay := range RetryDelaysSeconds {
+		if delay > 0 {
+			time.Sleep(time.Duration(delay) * time.Second)
+		}
+		if err := fn(); err == nil {
+			return nil
+		} else if attempt == len(RetryDelaysSeconds)-1 {
+			return fmt.Errorf("dead-lettered after %d attempts: %w", len(RetryDelaysSeconds), err)
+		}
+	}
+	return nil
+}

package/src/go/aiacta_test.go

@@ -0,0 +1,87 @@
+package aiacta_test
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/aiacta-org/aiacta/ai-citation-sdk"
+)
+
+func makeSignature(payload []byte, timestamp, secret string) string {
+	signed := append([]byte(timestamp+"."), payload...)
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(signed)
+	return "sha256=" + hex.EncodeToString(mac.Sum(nil))
+}
+
+func TestVerifyWebhookSignature_Valid(t *testing.T) {
+	ts      := fmt.Sprintf("%d", time.Now().Unix())
+	payload := []byte(`{"event_type":"citation.generated"}`)
+	sig     := makeSignature(payload, ts, "test-secret")
+
+	ok, err := aiacta.VerifyWebhookSignature(payload, ts, sig, "test-secret")
+	if err != nil { t.Fatalf("unexpected error: %v", err) }
+	if !ok        { t.Fatal("expected signature to be valid") }
+}
+
+func TestVerifyWebhookSignature_TamperedPayload(t *testing.T) {
+	ts      := fmt.Sprintf("%d", time.Now().Unix())
+	sig     := makeSignature([]byte("original"), ts, "secret")
+	ok, err := aiacta.VerifyWebhookSignature([]byte("tampered"), ts, sig, "secret")
+	if err != nil  { t.Fatalf("unexpected error: %v", err) }
+	if ok          { t.Fatal("expected tampered payload to fail verification") }
+}
+
+func TestVerifyWebhookSignature_StaleTimestamp(t *testing.T) {
+	oldTs := fmt.Sprintf("%d", time.Now().Unix()-400)
+	_, err := aiacta.VerifyWebhookSignature([]byte("{}"), oldTs, "sha256=abc", "secret")
+	if err == nil { t.Fatal("expected error for stale timestamp") }
+}
+
+func TestTruncateToMinute(t *testing.T) {
+	now       := time.Date(2026, 3, 24, 9, 14, 37, 500_000_000, time.UTC)
+	result    := aiacta.TruncateToMinute(now)
+	expected  := "2026-03-24T09:14:00Z"
+	if result != expected {
+		t.Fatalf("got %s, want %s", result, expected)
+	}
+}
+
+type inMemoryStore struct { keys map[string]bool }
+func (s *inMemoryStore) Has(k string) bool { return s.keys[k] }
+func (s *inMemoryStore) Set(k string)      { s.keys[k] = true }
+
+func TestProcessEvent_Idempotency(t *testing.T) {
+	store    := &inMemoryStore{keys: make(map[string]bool)}
+	called   := 0
+	events   := []aiacta.CitationEvent{
+		{IdempotencyKey: "idem_1", EventID: "evt_1"},
+	}
+	handler := func(e aiacta.CitationEvent) error { called++; return nil }
+
+	// Call 3 times — should only process once
+	for i := 0; i < 3; i++ {
+		if err := aiacta.ProcessEvent(events, store, handler); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+	}
+	if called != 1 {
+		t.Fatalf("expected handler called once, got %d", called)
+	}
+}
+
+func TestRetryDelaysSchedule(t *testing.T) {
+	if len(aiacta.RetryDelaysSeconds) != 6 {
+		t.Fatalf("expected 6 retry attempts, got %d", len(aiacta.RetryDelaysSeconds))
+	}
+	if aiacta.RetryDelaysSeconds[0] != 0 {
+		t.Fatal("first attempt must be immediate")
+	}
+	if aiacta.RetryDelaysSeconds[5] != 43200 {
+		t.Fatalf("last delay must be 43200s (12h), got %d", aiacta.RetryDelaysSeconds[5])
+	}
+}

package/src/go/go.mod

@@ -0,0 +1,5 @@
+module github.com/aiacta-org/aiacta/ai-citation-sdk
+
+go 1.21
+
+// No external dependencies — standard library only.

package/src/node/index.js

@@ -0,0 +1,10 @@
+/**
+ * ai-citation-sdk — Node.js
+ * Exports: verifyWebhookSignature, processEvent, createExpressMiddleware
+ */
+'use strict';
+const { verifyWebhookSignature } = require('./signature');
+const { processEvent }           = require('./processor');
+const { createExpressMiddleware }= require('./middleware');
+
+module.exports = { verifyWebhookSignature, processEvent, createExpressMiddleware };

package/src/node/middleware.js

@@ -0,0 +1,34 @@
+/**
+ * Express middleware factory.
+ * Attaches signature verification and idempotency handling to a route.
+ * Usage:
+ *   app.post('/webhooks/ai-citations', createExpressMiddleware({ secret, store, onEvent }));
+ */
+'use strict';
+const { verifyWebhookSignature } = require('./signature');
+const { processEvent }           = require('./processor');
+
+function createExpressMiddleware({ secret, store, onEvent }) {
+  return async (req, res) => {
+    const timestamp = req.headers['x-ai-webhook-timestamp'];
+    const sig       = req.headers['x-ai-webhook-sig'];
+    // Body must be raw Buffer — use express.raw() before this middleware
+    try {
+      const valid = verifyWebhookSignature(req.body, timestamp, sig, secret);
+      if (!valid) return res.status(401).json({ error: 'Invalid signature' });
+    } catch (e) {
+      return res.status(400).json({ error: e.message });
+    }
+
+    const payload = JSON.parse(req.body.toString('utf-8'));
+    // Respond quickly — process asynchronously (§3.5)
+    res.status(200).json({ status: 'accepted' });
+    await processEvent(payload, {
+      isProcessed:   (k) => store.exists(k),
+      markProcessed: (k) => store.set(k, true),
+      onEvent,
+    }).catch(err => console.error('[ai-citation-sdk] handler error:', err));
+  };
+}
+
+module.exports = { createExpressMiddleware };

package/src/node/processor.js

@@ -0,0 +1,28 @@
+/**
+ * Processes a parsed CitationEvent or CitationBatch.
+ * Handles idempotency check, normalization, and dispatches to user handler.
+ * GDPR: strips no fields beyond what the schema already omits (§3.3).
+ */
+'use strict';
+
+/**
+ * @param {object}   event        Parsed JSON body (single event or batch)
+ * @param {object}   opts
+ * @param {Function} opts.isProcessed   async (idempotency_key) => boolean
+ * @param {Function} opts.markProcessed async (idempotency_key) => void
+ * @param {Function} opts.onEvent       async (event) => void — your handler
+ */
+async function processEvent(event, { isProcessed, markProcessed, onEvent }) {
+  // Flatten batch into individual events
+  const events = event.events ? event.events : [event];
+
+  for (const e of events) {
+    if (await isProcessed(e.idempotency_key)) {
+      continue; // safe at-least-once reprocessing (§3.2)
+    }
+    await onEvent(e);
+    await markProcessed(e.idempotency_key);
+  }
+}
+
+module.exports = { processEvent };

package/src/node/retry.js

@@ -0,0 +1,29 @@
+/**
+ * Retry schedule constants and helper for outbound webhook delivery
+ * (relevant for AI provider implementations — §3.5).
+ */
+'use strict';
+
+/** Delays in seconds matching the spec's retry schedule. */
+const RETRY_DELAYS_SECONDS = [0, 30, 300, 1800, 7200, 43200];
+
+/**
+ * Executes fn with the AIACTA retry schedule.
+ * @param {Function} fn  Async function that throws on failure
+ */
+async function withRetry(fn) {
+  for (let attempt = 0; attempt < RETRY_DELAYS_SECONDS.length; attempt++) {
+    if (attempt > 0) {
+      await new Promise(r => setTimeout(r, RETRY_DELAYS_SECONDS[attempt] * 1000));
+    }
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt === RETRY_DELAYS_SECONDS.length - 1) {
+        throw new Error(`Dead-lettered after ${RETRY_DELAYS_SECONDS.length} attempts: ${err.message}`);
+      }
+    }
+  }
+}
+
+module.exports = { withRetry, RETRY_DELAYS_SECONDS };

package/src/node/signature.js

@@ -0,0 +1,30 @@
+/**
+ * Cryptographic webhook signature verification (§3.4 — HMAC-SHA256).
+ * Implements the exact algorithm specified in the whitepaper.
+ */
+'use strict';
+const crypto = require('crypto');
+
+const TIMESTAMP_TOLERANCE_SECONDS = 300; // 5 minutes (§3.4)
+
+/**
+ * @param {string|Buffer} payload  Raw request body
+ * @param {string} timestamp       Value of X-AI-Webhook-Timestamp header
+ * @param {string} sigHeader       Value of X-AI-Webhook-Sig header (sha256=<hex>)
+ * @param {string} secret          Shared HMAC secret issued at enrollment
+ * @returns {boolean}
+ * @throws {Error} if timestamp is outside tolerance window
+ */
+function verifyWebhookSignature(payload, timestamp, sigHeader, secret) {
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - parseInt(timestamp, 10)) > TIMESTAMP_TOLERANCE_SECONDS) {
+    throw new Error('Timestamp outside tolerance window — possible replay attack');
+  }
+  const signedPayload = `${timestamp}.${payload}`;
+  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+  const received  = sigHeader.replace('sha256=', '');
+  // Constant-time comparison to prevent timing attacks
+  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex'));
+}
+
+module.exports = { verifyWebhookSignature, TIMESTAMP_TOLERANCE_SECONDS };

package/src/node/timestamp.js

@@ -0,0 +1,35 @@
+/**
+ * Timestamp utilities for AIACTA webhook events.
+ *
+ * §3.2 specifies "minute precision only" for event timestamps to prevent
+ * timing attacks that could re-identify users.
+ *
+ * Implementation note: the X-AI-Webhook-Timestamp header used for HMAC
+ * signing (§3.4) remains at UNIX second precision — this is the
+ * cryptographic nonce that prevents replay attacks. The event.timestamp
+ * field inside the JSON payload is truncated to minute precision.
+ */
+'use strict';
+
+/**
+ * Returns the current time truncated to minute precision, as ISO 8601.
+ * e.g. "2026-03-24T09:14:00Z"  (seconds and sub-seconds always zero)
+ */
+function nowMinutePrecision() {
+  const d = new Date();
+  d.setSeconds(0, 0);
+  return d.toISOString().replace('.000Z', ':00Z').replace(/\.\d{3}Z$/, ':00Z');
+}
+
+/**
+ * Truncates any ISO 8601 string to minute precision.
+ * @param {string} isoString
+ * @returns {string}
+ */
+function truncateToMinute(isoString) {
+  const d = new Date(isoString);
+  d.setSeconds(0, 0);
+  return d.toISOString().slice(0, 16) + ':00Z';
+}
+
+module.exports = { nowMinutePrecision, truncateToMinute };

package/src/python/aiacta/__init__.py

@@ -0,0 +1,5 @@
+"""AIACTA Citation SDK for Python."""
+from .signature import verify_webhook_signature
+from .processor import process_event
+from .retry import with_retry, RETRY_DELAYS_SECONDS
+__all__ = ['verify_webhook_signature', 'process_event', 'with_retry', 'RETRY_DELAYS_SECONDS']

package/src/python/aiacta/processor.py

@@ -0,0 +1,8 @@
+"""Processes CitationEvent or CitationBatch with idempotency (§3.2)."""
+async def process_event(event: dict, *, is_processed, mark_processed, on_event):
+    events = event.get("events", [event])
+    for e in events:
+        if await is_processed(e["idempotency_key"]):
+            continue
+        await on_event(e)
+        await mark_processed(e["idempotency_key"])

package/src/python/aiacta/retry.py

@@ -0,0 +1,11 @@
+"""Retry schedule matching §3.5."""
+import asyncio
+RETRY_DELAYS_SECONDS = [0, 30, 300, 1800, 7200, 43200]
+async def with_retry(fn):
+    for attempt, delay in enumerate(RETRY_DELAYS_SECONDS):
+        if delay: await asyncio.sleep(delay)
+        try:
+            return await fn()
+        except Exception as e:
+            if attempt == len(RETRY_DELAYS_SECONDS) - 1:
+                raise RuntimeError(f"Dead-lettered after {len(RETRY_DELAYS_SECONDS)} attempts: {e}") from e

package/src/python/aiacta/signature.py

@@ -0,0 +1,13 @@
+"""Cryptographic webhook signature verification (§3.4)."""
+import hashlib, hmac, time
+
+TIMESTAMP_TOLERANCE_SECONDS = 300
+
+def verify_webhook_signature(payload: bytes, timestamp: str, sig_header: str, secret: str) -> bool:
+    now = int(time.time())
+    if abs(now - int(timestamp)) > TIMESTAMP_TOLERANCE_SECONDS:
+        raise ValueError("Timestamp outside tolerance window — possible replay attack")
+    signed = f"{timestamp}.".encode() + payload
+    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+    received = sig_header.removeprefix("sha256=")
+    return hmac.compare_digest(expected, received)

package/src/python/requirements.txt

@@ -0,0 +1,4 @@
+cryptography>=41.0
+requests>=2.31
+pytest>=7.0
+pytest-cov>=4.0

package/src/python/setup.py

@@ -0,0 +1,9 @@
+from setuptools import setup, find_packages
+setup(
+    name='ai-citation-sdk',
+    version='1.0.0',
+    description='AIACTA Citation Webhook SDK for Python (Proposal 2 §3.4)',
+    packages=find_packages(),
+    python_requires='>=3.9',
+    install_requires=['cryptography>=41.0', 'requests>=2.31'],
+)

package/tests/processor.test.js

@@ -0,0 +1,39 @@
+const { processEvent } = require('../src/node/processor');
+
+test('skips already-processed events', async () => {
+  const processed = new Set(['idem_duplicate']);
+  let called = 0;
+  await processEvent({ idempotency_key: 'idem_duplicate', event_type: 'citation.generated' }, {
+    isProcessed:   k => processed.has(k),
+    markProcessed: k => processed.add(k),
+    onEvent:       async () => { called++; },
+  });
+  expect(called).toBe(0);
+});
+
+test('processes new events and marks them', async () => {
+  const processed = new Set();
+  let called = 0;
+  await processEvent({ idempotency_key: 'idem_new', event_type: 'citation.generated' }, {
+    isProcessed:   k => processed.has(k),
+    markProcessed: k => processed.add(k),
+    onEvent:       async () => { called++; },
+  });
+  expect(called).toBe(1);
+  expect(processed.has('idem_new')).toBe(true);
+});
+
+test('processes batch events individually', async () => {
+  const processed = new Set();
+  const events = [
+    { idempotency_key: 'k1', event_type: 'citation.generated' },
+    { idempotency_key: 'k2', event_type: 'citation.generated' },
+  ];
+  let called = 0;
+  await processEvent({ events }, {
+    isProcessed:   k => processed.has(k),
+    markProcessed: k => processed.add(k),
+    onEvent:       async () => { called++; },
+  });
+  expect(called).toBe(2);
+});

package/tests/retry.test.js

@@ -0,0 +1,13 @@
+const { RETRY_DELAYS_SECONDS } = require('../src/node/retry');
+
+test('retry schedule has 6 attempts', () => {
+  expect(RETRY_DELAYS_SECONDS).toHaveLength(6);
+});
+
+test('first attempt is immediate', () => {
+  expect(RETRY_DELAYS_SECONDS[0]).toBe(0);
+});
+
+test('last delay is 12 hours', () => {
+  expect(RETRY_DELAYS_SECONDS[5]).toBe(43200);
+});

package/tests/signature.test.js

@@ -0,0 +1,26 @@
+const crypto = require('crypto');
+const { verifyWebhookSignature } = require('../src/node/signature');
+
+function makeHeader(payload, timestamp, secret) {
+  const signed = `${timestamp}.${payload}`;
+  const hex = crypto.createHmac('sha256', secret).update(signed).digest('hex');
+  return `sha256=${hex}`;
+}
+
+test('valid signature passes', () => {
+  const ts = String(Math.floor(Date.now() / 1000));
+  const payload = '{"event_type":"citation.generated"}';
+  const sig = makeHeader(payload, ts, 'mysecret');
+  expect(verifyWebhookSignature(payload, ts, sig, 'mysecret')).toBe(true);
+});
+
+test('tampered payload fails', () => {
+  const ts = String(Math.floor(Date.now() / 1000));
+  const sig = makeHeader('original', ts, 'mysecret');
+  expect(verifyWebhookSignature('tampered', ts, sig, 'mysecret')).toBe(false);
+});
+
+test('old timestamp throws', () => {
+  const oldTs = String(Math.floor(Date.now() / 1000) - 400);
+  expect(() => verifyWebhookSignature('{}', oldTs, 'sha256=abc', 'secret')).toThrow();
+});