voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-server/skills/void-webhook-handler-pattern/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: void-webhook-handler-pattern
+description: Build a webhook handler with signature verification, idempotency, and dead-letter routing. Per-source patterns (Stripe, Resend, GitHub). Self-contained — no harness wrappers required.
+---
+
+# webhook-handler-pattern
+
+Use when adding any inbound webhook endpoint (Stripe, Resend, GitHub, custom). Webhooks are **untrusted POST endpoints** that fire from external systems — every wrong handler is either a security breach (forged events accepted), a duplicate-charge bug (no idempotency), or a silent failure (no dead-letter).
+
+## Location
+
+```
+apps/<app>/src/app/api/webhooks/<source>/route.ts
+```
+
+One folder per source. Path stable (external systems POST to a fixed URL — never rename without coordinating).
+
+## The 5 non-negotiable layers
+
+```
+1. Signature verification  — verify the event came from the source
+2. Idempotency             — same event delivered twice = one effect
+3. Zod validation          — parsed shape matches what handler expects
+4. Service call            — the business work (in apps/<app>/src/services/)
+5. Acknowledgment          — return 2xx on success; specific codes on failure
+```
+
+Skipping ANY of these is a Sev-2 waiting. The pattern below shows the 5 layers explicit — no wrapper assumed.
+
+## Canonical handler (explicit, self-contained)
+
+```ts
+// apps/web/src/app/api/webhooks/stripe/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import Stripe from 'stripe';
+import { z } from 'zod';
+import { db } from '@/adapters/db';
+import { env, logger } from '@repo/core';
+import * as Sentry from '@sentry/nextjs';
+import { handleStripeEvent } from '@/services/billing/stripe';
+
+const stripe = new Stripe(env.STRIPE_SECRET_KEY);
+
+// 3. Zod schema for the parsed Stripe event (defense in depth — Stripe's
+//    own parser is trusted, but we re-shape to our service contract).
+const EventSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  data: z.object({ object: z.unknown() }),
+  livemode: z.boolean(),
+});
+
+export async function POST(req: NextRequest) {
+  const sig = req.headers.get('stripe-signature');
+  const body = await req.text();
+  const idempotencyKey = `stripe:${req.headers.get('stripe-signature')?.slice(0, 16) ?? ''}`;
+
+  let stripeEvent: Stripe.Event;
+  try {
+    // 1. Signature verification (Stripe-specific)
+    if (!sig) {
+      return NextResponse.json({ error: 'missing signature' }, { status: 401 });
+    }
+    stripeEvent = stripe.webhooks.constructEvent(body, sig, env.STRIPE_WEBHOOK_SECRET);
+  } catch (err) {
+    logger.warn({ event: 'webhook.signature_invalid', source: 'stripe' });
+    return NextResponse.json({ error: 'invalid signature' }, { status: 401 });
+  }
+
+  // 2. Idempotency — Stripe's event.id is globally unique
+  const inboxKey = `stripe:${stripeEvent.id}`;
+  const inserted = await db
+    .insert(webhookInbox)
+    .values({ key: inboxKey, source: 'stripe', eventType: stripeEvent.type, payload: stripeEvent })
+    .onConflictDoNothing()
+    .returning();
+
+  if (inserted.length === 0) {
+    // Already seen — return 2xx to stop Stripe retrying
+    logger.info({ event: 'webhook.duplicate', source: 'stripe', eventId: stripeEvent.id });
+    return NextResponse.json({ ok: true, duplicate: true });
+  }
+
+  // 3. Re-validate with our schema
+  const event = EventSchema.parse(stripeEvent);
+
+  // 4. Service call — pure dispatch
+  logger.info({ event: 'webhook.received', source: 'stripe', type: event.type, eventId: event.id });
+  try {
+    await handleStripeEvent(event);
+    await db.update(webhookInbox).set({ committedAt: new Date() }).where(eq(webhookInbox.key, inboxKey));
+    // 5. Ack
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    Sentry.captureException(err, { tags: { webhook: 'stripe', eventType: event.type } });
+    // Retryable: return 5xx so Stripe retries with backoff
+    return NextResponse.json({ ok: false }, { status: 500 });
+  }
+}
+```
+
+The 5 layers are explicit. No wrapper is required. If your project ships its own `withWebhookSafety` helper that bundles these 5, that's a convenience — but the pattern is the substance, and it's the same.
+
+## Per-source notes
+
+### Stripe
+
+- Signature: `stripe-signature` header → `stripe.webhooks.constructEvent`
+- Idempotency: `event.id` is the canonical key
+- Retry: Stripe retries failed webhooks with exponential backoff for up to 3 days
+- Test mode: separate `STRIPE_WEBHOOK_SECRET_TEST` env var
+
+### Resend (via svix)
+
+- Signature: `svix-id`, `svix-timestamp`, `svix-signature` headers → `new Webhook(secret).verify(body, headers)` from `svix` package
+- Idempotency: `svix-id` header
+- Retry: Svix retries automatically; you only see the first failure if your endpoint returns 5xx
+
+### GitHub
+
+- Signature: `x-hub-signature-256` header (HMAC SHA-256 of the body with your secret)
+- Idempotency: `x-github-delivery` header (UUID)
+- Retry: GitHub does NOT auto-retry. If you return 5xx, the event is lost. Make sure dead-letter is robust.
+
+### Custom (internal services calling each other)
+
+- Signature: HMAC SHA-256 with a shared secret. Use Node's `crypto.timingSafeEqual` for the compare (constant-time, no early-exit on mismatch).
+- Idempotency: caller-generated UUID v7 in `x-idempotency-key`
+- Retry: caller's responsibility; receiver acknowledges with 2xx + the key it already saw
+
+## Inbox table
+
+The idempotency check needs persistent storage:
+
+```sql
+CREATE TABLE webhook_inbox (
+  key text PRIMARY KEY,                         -- e.g., "stripe:evt_xxx"
+  source text NOT NULL,
+  event_type text NOT NULL,
+  received_at timestamptz NOT NULL DEFAULT now(),
+  committed_at timestamptz,
+  payload jsonb NOT NULL
+);
+CREATE INDEX idx_webhook_inbox_received ON webhook_inbox (received_at);
+```
+
+Migration follows the safe-migration pattern (see `void-drizzle-migration-safe` skill).
+
+## Dead-letter routing
+
+When the handler decides the error is permanent (validation failure, downstream API said 4xx):
+
+```ts
+catch (err) {
+  if (isPermanentFailure(err)) {
+    await db.insert(webhookDeadLetter).values({
+      key: inboxKey,
+      source: 'stripe',
+      error: err.message,
+      payload: event,
+      receivedAt: new Date(),
+    });
+    return NextResponse.json({ ok: false, retry: false }, { status: 400 });
+    // 4xx tells Stripe "permanent — stop retrying"
+  }
+  throw err;   // retryable — let the 5xx propagate
+}
+```
+
+Dead letter = a queue/table the team reviews. UI: `Settings → Webhook DLQ`. Never silently drop.
+
+## Error response codes
+
+| Code | Means | Sender behavior |
+|---|---|---|
+| 200/202 | Accepted | Stops retrying |
+| 401 | Invalid signature | Stops retrying (Stripe, GitHub will flag the endpoint) |
+| 4xx (other) | Permanent failure (bad event shape) | Stops retrying — log this for investigation |
+| 5xx | Transient failure | Retries with backoff (Stripe/Svix); GitHub doesn't retry |
+
+NEVER return 200 to a malformed event (you'd accept invalid data). 4xx with a logged DLQ entry is the right pattern.
+
+## Anti-patterns
+
+- ✗ **No signature verification** — anyone with the URL can forge events
+- ✗ **Idempotency key = `Date.now()`** — re-delivery NOT detected; double-charges
+- ✗ **Calling services synchronously for slow work** — if the handler takes > 10s, the sender retries. Enqueue background jobs for slow work (see `void-background-job-pattern`).
+- ✗ **Returning 5xx to "make sender retry" without enqueueing** — sender's backoff is unpredictable; use your own queue
+- ✗ **One handler for all sources** (`/api/webhooks/route.ts` switching on `source`) — different signatures, different idempotency keys, different retry semantics. One folder per source.
+- ✗ **`==` for HMAC comparison** — use `crypto.timingSafeEqual`. Constant-time compare prevents timing attacks.
+
+## Testing
+
+- Unit-test the verifier with a real (sanitized) payload from the source's docs
+- Integration-test by running the handler against a captured event JSON
+- E2E: use Stripe CLI / Svix CLI / ngrok to deliver real webhooks to a dev endpoint
+
+## Composition (informational)
+
+- `void-async-safety` — generic retry, idempotency, dead-letter doctrine.
+- `void-server-action` — both cross trust boundaries; same Zod discipline.
+- `void-drizzle-migration-safe` — inbox table migration follows the safe pattern.
+- `void-env-validation` — webhook secrets validated in `@repo/core/env`.
+- `void-observability` — trace context per receive; Sentry breadcrumb.
+- `void-security-guidance` — Zod re-validation IS the trust boundary; HMAC compare with constant-time.

package/core-assets/packs/pack-server/skills/void-webhook-handler-pattern/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/policies/core.yaml

@@ -0,0 +1,95 @@
+schemaVersion: 1
+id: core:quality-floor
+version: 2
+layer: core
+rules:
+  - id: core:product
+    pass: product
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [product]
+  - id: core:architecture
+    pass: architecture
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [architecture]
+  - id: core:fortress-threat-model
+    pass: architecture
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [auth, pii, tenancy, destructive-migration, upload, code-execution, llm-tools, supply-chain]
+  - id: core:tdd
+    pass: tdd
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [tdd]
+  - id: core:qa
+    pass: qa
+    strength: required
+    baseline: true
+    appliesWhen:
+      any: [qa]
+  - id: core:fortress-critical-verification
+    pass: qa
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [auth, pii, tenancy, destructive-migration, upload, code-execution, llm-tools, supply-chain]
+  - id: core:security
+    pass: security
+    strength: blocking
+    baseline: true
+    appliesWhen:
+      any: [security]
+  - id: core:fortress-adversarial-security
+    pass: security
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [auth, pii, tenancy, destructive-migration, upload, code-execution, llm-tools, supply-chain]
+  - id: core:observability
+    pass: observability
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [observability]
+  - id: core:migration
+    pass: migration
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [migration]
+  - id: core:fortress-destructive-recovery
+    pass: migration
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [destructive-migration]
+  - id: core:performance
+    pass: performance
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [performance]
+  - id: core:stack-patterns
+    pass: stack-patterns
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [stack-patterns]
+  - id: core:pdf
+    pass: pdf
+    strength: required
+    baseline: false
+    appliesWhen:
+      any: [pdf]
+  - id: core:retrospective
+    pass: retrospective
+    strength: advisory
+    baseline: false
+    appliesWhen:
+      any: [retrospective]

package/core-assets/policies/ui.yaml

@@ -0,0 +1,23 @@
+schemaVersion: 1
+id: core:ui-quality
+version: 1
+layer: core
+rules:
+  - id: core:ui-tdd
+    pass: tdd
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [ux-ui, accessibility]
+  - id: core:ux-ui
+    pass: ux-ui
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [ux-ui]
+  - id: core:accessibility
+    pass: accessibility
+    strength: blocking
+    baseline: false
+    appliesWhen:
+      any: [ux-ui, accessibility]

package/core-assets/profiles/base.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+id: core:base
+version: 1
+name: base
+technologies: []
+detectors:
+  always: true
+  technologies: []
+  files:
+    extensions: []
+    names: []
+    pathSegments: []
+sources:
+  - title: void-machine repository
+    url: https://github.com/voidcorp-core/void-machine
+reviewedAt: 2026-07-27
+expiresAfterDays: 180
+invariants:
+  - Keep changes minimal, testable, reversible, and explicit at trust boundaries.
+  - Preserve project conventions unless the mission deliberately changes them.
+patterns:
+  - id: universal-change
+    appliesWhen:
+      technologies: []
+      files:
+        extensions: []
+        names: []
+        pathSegments: []
+    guidance: Apply the universal safety, verification, and maintainability doctrine.

package/core-assets/profiles/expo-config.yaml

@@ -0,0 +1,36 @@
+schemaVersion: 1
+id: core:expo-config
+version: 1
+name: expo-config
+technologies:
+  - id: expo
+    minimumVersion: 52.0.0
+    maximumVersionExclusive: 60.0.0
+  - id: react-native
+    minimumVersion: 0.75.0
+    maximumVersionExclusive: 1.0.0
+detectors:
+  always: false
+  technologies: [expo]
+  files:
+    extensions: []
+    names: [app.json, app.config.js, app.config.ts, eas.json]
+    pathSegments: []
+sources:
+  - title: Expo documentation
+    url: https://docs.expo.dev/
+  - title: React Native documentation
+    url: https://reactnative.dev/docs/getting-started
+reviewedAt: 2026-07-27
+expiresAfterDays: 90
+invariants:
+  - Validate version-specific configuration against the installed tool's official documentation.
+patterns:
+  - id: native-config
+    appliesWhen:
+      technologies: [expo]
+      files:
+        extensions: []
+        names: [app.json, app.config.js, app.config.ts, eas.json]
+        pathSegments: []
+    guidance: Validate configuration against the covered Expo documentation and rebuild native binaries when required.

package/core-assets/profiles/expo.yaml

@@ -0,0 +1,35 @@
+schemaVersion: 1
+id: core:expo
+version: 2
+name: expo
+technologies:
+  - id: expo
+    versionIndependent: true
+  - id: react-native
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [expo, react-native]
+  files:
+    extensions: [.ts, .tsx, .js, .jsx, .json]
+    names: [app.json, app.config.js, app.config.ts, eas.json]
+    pathSegments: [app, ios, android]
+sources:
+  - title: Expo documentation
+    url: https://docs.expo.dev/
+  - title: React Native documentation
+    url: https://reactnative.dev/docs/getting-started
+reviewedAt: 2026-07-27
+expiresAfterDays: 90
+invariants:
+  - Verify behavior on the supported native platforms and account for platform-specific capabilities.
+  - Treat native configuration changes as build changes, not over-the-air JavaScript updates.
+patterns:
+  - id: native-app
+    appliesWhen:
+      technologies: [expo, react-native]
+      files:
+        extensions: [.ts, .tsx, .js, .jsx]
+        names: []
+        pathSegments: [app, ios, android]
+    guidance: Verify navigation, permissions, accessibility, keyboard, and device lifecycle states.

package/core-assets/profiles/monorepo.yaml

@@ -0,0 +1,33 @@
+schemaVersion: 1
+id: core:monorepo
+version: 2
+name: monorepo
+technologies:
+  - id: monorepo
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [monorepo]
+  files:
+    extensions: [.json, .yaml, .yml, .ts]
+    names: [package.json, pnpm-workspace.yaml, turbo.json]
+    pathSegments: [apps, packages]
+sources:
+  - title: pnpm workspaces documentation
+    url: https://pnpm.io/workspaces
+  - title: npm workspaces documentation
+    url: https://docs.npmjs.com/cli/using-npm/workspaces
+reviewedAt: 2026-07-27
+expiresAfterDays: 180
+invariants:
+  - Preserve dependency direction and assign each shared concern a single owner.
+  - Test affected packages without hiding failures behind cache or task filtering.
+patterns:
+  - id: workspace-boundary
+    appliesWhen:
+      technologies: [monorepo]
+      files:
+        extensions: [.json, .yaml, .yml, .ts]
+        names: [package.json, pnpm-workspace.yaml, turbo.json]
+        pathSegments: [apps, packages]
+    guidance: Verify package ownership, dependency direction, and affected task coverage.

package/core-assets/profiles/nextjs-config.yaml

@@ -0,0 +1,31 @@
+schemaVersion: 1
+id: core:nextjs-config
+version: 1
+name: nextjs-config
+technologies:
+  - id: nextjs
+    minimumVersion: 15.0.0
+    maximumVersionExclusive: 18.0.0
+detectors:
+  always: false
+  technologies: [nextjs]
+  files:
+    extensions: []
+    names: [next.config.js, next.config.mjs, next.config.ts]
+    pathSegments: []
+sources:
+  - title: Next.js documentation
+    url: https://nextjs.org/docs
+reviewedAt: 2026-07-27
+expiresAfterDays: 120
+invariants:
+  - Validate version-specific configuration against the installed tool's official documentation.
+patterns:
+  - id: framework-config
+    appliesWhen:
+      technologies: [nextjs]
+      files:
+        extensions: []
+        names: [next.config.js, next.config.mjs, next.config.ts]
+        pathSegments: []
+    guidance: Validate configuration against the covered official Next.js documentation.

package/core-assets/profiles/nextjs.yaml

@@ -0,0 +1,31 @@
+schemaVersion: 1
+id: core:nextjs
+version: 2
+name: nextjs
+technologies:
+  - id: nextjs
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [nextjs]
+  files:
+    extensions: [.ts, .tsx, .js, .jsx, .css]
+    names: [next.config.js, next.config.mjs, next.config.ts]
+    pathSegments: [app, pages]
+sources:
+  - title: Next.js documentation
+    url: https://nextjs.org/docs
+reviewedAt: 2026-07-27
+expiresAfterDays: 120
+invariants:
+  - Make server and client boundaries explicit and minimize client-side JavaScript.
+  - Treat caching, revalidation, authorization, and request input as explicit contracts.
+patterns:
+  - id: app-router
+    appliesWhen:
+      technologies: [nextjs]
+      files:
+        extensions: [.ts, .tsx]
+        names: []
+        pathSegments: [app]
+    guidance: Keep routing and data-flow ownership explicit; verify framework-specific APIs against the installed version.

package/core-assets/profiles/node-server.yaml

@@ -0,0 +1,31 @@
+schemaVersion: 1
+id: core:node-server
+version: 2
+name: node-server
+technologies:
+  - id: node
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [node]
+  files:
+    extensions: [.ts, .mts, .cts, .js, .mjs, .cjs]
+    names: [server.ts, server.js]
+    pathSegments: [api, server, routes, webhooks]
+sources:
+  - title: Node.js documentation
+    url: https://nodejs.org/docs/latest/api/
+reviewedAt: 2026-07-27
+expiresAfterDays: 180
+invariants:
+  - Validate inputs before domain logic and authorize every protected operation server-side.
+  - Bound concurrency, timeouts, retries, request sizes, and resource lifetimes.
+patterns:
+  - id: request-boundary
+    appliesWhen:
+      technologies: [node]
+      files:
+        extensions: [.ts, .mts, .cts, .js, .mjs, .cjs]
+        names: [server.ts, server.js]
+        pathSegments: [api, server, routes, webhooks]
+    guidance: Keep transport parsing, authentication, authorization, domain logic, and response mapping separate.

package/core-assets/profiles/pwa.yaml

@@ -0,0 +1,33 @@
+schemaVersion: 1
+id: core:pwa
+version: 2
+name: pwa
+technologies:
+  - id: pwa
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [pwa]
+  files:
+    extensions: [.ts, .js, .json, .webmanifest]
+    names: [manifest.json, manifest.webmanifest, service-worker.js, service-worker.ts]
+    pathSegments: [public]
+sources:
+  - title: MDN Progressive web apps
+    url: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps
+  - title: web.dev Progressive Web Apps
+    url: https://web.dev/learn/pwa/
+reviewedAt: 2026-07-27
+expiresAfterDays: 120
+invariants:
+  - Make cache invalidation and offline fallback behavior explicit and testable.
+  - Never cache user-specific or security-sensitive responses without a proven policy.
+patterns:
+  - id: offline-surface
+    appliesWhen:
+      technologies: [pwa]
+      files:
+        extensions: [.ts, .js, .json, .webmanifest]
+        names: [manifest.json, manifest.webmanifest, service-worker.js, service-worker.ts]
+        pathSegments: [public]
+    guidance: Verify installability, update behavior, offline fallback, and cache boundaries.

package/core-assets/profiles/react.yaml

@@ -0,0 +1,39 @@
+schemaVersion: 1
+id: core:react
+version: 2
+name: react
+technologies:
+  - id: react
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [react]
+  files:
+    extensions: [.tsx, .jsx, .css]
+    names: []
+    pathSegments: []
+sources:
+  - title: React documentation
+    url: https://react.dev/
+reviewedAt: 2026-07-27
+expiresAfterDays: 120
+invariants:
+  - Keep rendering pure and derive state instead of synchronizing duplicates.
+  - Cover keyboard, focus, loading, empty, error, and success states where applicable.
+patterns:
+  - id: component-change
+    appliesWhen:
+      technologies: [react]
+      files:
+        extensions: [.tsx, .jsx]
+        names: []
+        pathSegments: []
+    guidance: Test behavior at the user boundary and preserve accessible semantics.
+  - id: visual-change
+    appliesWhen:
+      technologies: [react]
+      files:
+        extensions: [.css]
+        names: []
+        pathSegments: []
+    guidance: Verify responsive, focus, contrast, and interaction states in a browser.

package/core-assets/profiles/sql.yaml

@@ -0,0 +1,39 @@
+schemaVersion: 1
+id: core:sql
+version: 2
+name: sql
+technologies:
+  - id: drizzle
+    versionIndependent: true
+  - id: prisma
+    versionIndependent: true
+  - id: postgres
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [drizzle, prisma, postgres]
+  files:
+    extensions: [.sql]
+    names: [schema.ts, schema.prisma, drizzle.config.ts]
+    pathSegments: [migrations]
+sources:
+  - title: PostgreSQL documentation
+    url: https://www.postgresql.org/docs/current/
+  - title: Drizzle ORM documentation
+    url: https://orm.drizzle.team/docs/overview
+  - title: Prisma documentation
+    url: https://www.prisma.io/docs/
+reviewedAt: 2026-07-27
+expiresAfterDays: 120
+invariants:
+  - Make schema changes forward-compatible, observable, reversible, and safe under live traffic.
+  - Keep constraints and transactions aligned with domain invariants.
+patterns:
+  - id: schema-migration
+    appliesWhen:
+      technologies: [drizzle, prisma, postgres]
+      files:
+        extensions: [.sql]
+        names: [schema.ts, schema.prisma]
+        pathSegments: [migrations]
+    guidance: Plan expand-migrate-contract sequencing, rollback, backfill, locking, and production observability.