voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-server/skills/void-rate-limit-strategy/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: void-rate-limit-strategy
+description: Choose rate limit window, max, and key strategy per action class. Per-user for authed, per-IP for public, escalation for auth-adjacent. Default values + when to deviate.
+---
+
+# rate-limit-strategy
+
+Use when applying a rate limit to a Server Action, route handler, or webhook. Rate limits are mandatory at every trust boundary (per `void-security-guidance`); this skill says HOW to choose the right window/max/key per use case.
+
+If you're tempted to skip rate limit "because it's internal" — wrong. The trust boundary is the URL. Anything reachable from a browser is rate-limited.
+
+## The 3 parameters
+
+```ts
+{ window: '1 min', max: 10, key: 'user:${user.id}:contact-form' }
+```
+
+- `window` — time window (1 min, 1 hour, 24 hours)
+- `max` — number of requests allowed in the window
+- `key` — what gets counted (per user? per IP? per action?)
+
+## Default presets
+
+Per action class, here are the void-machine defaults. Deviate with explicit justification in a code comment.
+
+| Action class | Window / Max | Key | Why |
+|---|---|---|---|
+| Standard read (data fetch, list) | 1 min / 100 | `user:${id}` | Generous; reads are cheap |
+| Standard write (create, update) | 1 min / 30 | `user:${id}` | Conservative; writes are expensive |
+| Search / filter | 1 min / 60 | `user:${id}` OR `ip:${ip}` | Mid |
+| Auth: login | 5 min / 5 | `ip:${ip}` + `email:${email}` (BOTH) | Credential stuffing |
+| Auth: password reset | 1 hour / 3 | `ip:${ip}` + `email:${email}` | Account enumeration |
+| Auth: 2FA verify | 5 min / 5 | `user:${id}` | Brute force |
+| Auth: 2FA resend | 5 min / 1 | `user:${id}` | SMS cost |
+| LLM call | 1 hour / 50 | `user:${id}` | Cost control |
+| File upload | 1 hour / 20 | `user:${id}` | Bandwidth + disk |
+| Webhook receiver | 1 min / 1000 | `source:${source}` | Permissive; senders should self-throttle |
+| Public form (contact, signup) | 5 min / 3 | `ip:${ip}` | Anti-spam |
+
+These are **starting points**. If your traffic patterns show 1 min / 30 is too tight for a specific write that users do legitimately 50 times/min (e.g., batch import), document the deviation and raise.
+
+## Key strategy: `user:` vs `ip:`
+
+- **Per-user (`user:${id}`)** — for authenticated actions. User is the right scope; one user shouldn't tank another user's quota by sharing an IP (office NAT, mobile carrier CGN).
+- **Per-IP (`ip:${ip}`)** — for unauthenticated actions where user identity doesn't exist yet (login, public form, signup).
+- **Both (`user:${id}` AND `ip:${ip}`)** — for auth-adjacent flows (login, password reset, 2FA). One attacker can rotate emails on one IP; one IP can host one stolen credential. Block on either limit.
+
+When using BOTH, configure the rate limiter to use `Math.max` semantics: the more restrictive limit wins.
+
+## Sliding window vs token bucket vs fixed window
+
+Pick one strategy per app, stick with it. The differences in practice:
+
+- **Fixed window**: simple, off-by-one at boundary (user makes 30 in second 59, then 30 more in second 1 of next window = 60 in 2s). Use for non-security limits.
+- **Sliding window**: smoother, no boundary spike. Use for cost-sensitive limits (LLM, uploads).
+- **Token bucket**: allows burst then refill. Use when "burst is OK but sustained is not" (search-as-you-type, real-time API).
+
+The void-machine default is **sliding window** via Upstash Redis or Vercel KV (`@upstash/ratelimit`). Token bucket only when burst is the intended UX.
+
+## Implementation (Upstash example, no wrapper)
+
+```ts
+// apps/web/src/adapters/ratelimit.ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+import { env } from '@repo/core';
+
+const redis = Redis.fromEnv();
+
+export const ratelimit = {
+  perUser: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(30, '1 m'),
+    prefix: 'rl:user',
+  }),
+  perIp: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(5, '5 m'),
+    prefix: 'rl:ip',
+  }),
+  auth: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(5, '5 m'),
+    prefix: 'rl:auth',
+  }),
+};
+```
+
+Use in a Server Action:
+
+```ts
+// inside an action handler, after auth resolves session
+const { success } = await ratelimit.perUser.limit(`${session.userId}:note.create`);
+if (!success) return { ok: false as const, error: 'rate-limited' };
+```
+
+For per-IP or composite keys (login: both IP and email):
+
+```ts
+const ip = headers().get('x-forwarded-for')?.split(',')[0] ?? 'unknown';
+const { success: ipOk } = await ratelimit.auth.limit(`ip:${ip}:login`);
+const { success: emailOk } = await ratelimit.auth.limit(`email:${input.email}:login`);
+if (!ipOk || !emailOk) return { ok: false as const, error: 'rate-limited' };
+```
+
+Webhook handlers rate-limit per-source:
+
+```ts
+const { success } = await ratelimit.perUser.limit(`webhook:stripe`);
+if (!success) return NextResponse.json({ error: 'rate-limited' }, { status: 429 });
+```
+
+If you DRY this into a `defineAction` helper (recommended once the pattern repeats), the helper accepts a `rateLimit` option and applies the same primitive under the hood.
+
+## Escalation: progressive lockout
+
+For high-stakes auth flows, ramp the cost of repeated failures:
+
+```ts
+{
+  window: '5 min',
+  max: 5,
+  // After 5 failures, escalate: 1 hour cooldown
+  escalate: { afterFails: 5, lockoutMin: 60 },
+}
+```
+
+Not all limiters support this natively; if your stack doesn't, implement at the service layer: count failures in a separate counter, when threshold crossed, return 403 with a lockout response.
+
+## Anti-patterns
+
+- ✗ **No rate limit on Server Actions because "we'll add it later"** — every action ships with one or doesn't ship
+- ✗ **Same limit for reads and writes** — wastes capacity OR makes writes too easy to abuse
+- ✗ **IP-only limit on authed actions** — office NAT or carrier CGN punishes legit users; use user key
+- ✗ **No rate limit on webhook receivers** — a buggy sender can flood you
+- ✗ **Rate limit at the database query level** — too late; the request already consumed compute. Rate limit at the boundary.
+- ✗ **Identical message for "rate limited" and "denied"** — leaks "your credentials are valid, just slow down" (info disclosure). For auth flows, return a generic 429.
+
+## Monitoring
+
+Surface 429 responses in your dashboard. Sudden spikes = either an attack OR a UX bug (unintended retries from the client). Both need attention.
+
+## Composition (informational)
+
+- `void-security-guidance` — rate limit is a security control; Zod is the schema control; both at every boundary.
+- `void-async-safety` — webhook + background-job retry semantics interact with rate limits.
+- `void-server-action` — actions apply rate limit before service call (layer 3 of 5).
+- `void-webhook-handler-pattern` — webhook rate limits use a per-source key.
+- `void-llm-cost-discipline` — LLM call rate limits are cost-control, more conservative than CPU-control limits.

package/core-assets/packs/pack-server/skills/void-rate-limit-strategy/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/packs/pack-server/skills/void-server-action/.source

@@ -0,0 +1,7 @@
+Sources for `void-server-action` skill (see `docs/plans/skill-audits/void-server-action.md` for the full audit):
+
+- Next.js 16 docs — `'use server'` and defineAction semantics — distilled, not copied.
+- Vercel security guidance — trust-boundary obligations for Server Actions.
+- Solaar's webhook safety implementation — real-world source for withWebhookSafety / defineAction / defineFormAction patterns.
+
+Strategy: native. Distilled from the three sources above and adapted to the void-machine convention where services own domain logic and actions are pure trust-boundary wrappers.

package/core-assets/packs/pack-server/skills/void-server-action/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: void-server-action
+description: "Create a Next.js 16 Server Action with the void trust-boundary checklist: Zod ingress, auth, rate limit, observability, structured errors. Composes with security-guidance, async-safety."
+---
+
+# server-action
+
+Use when adding any `'use server'` function (in Next.js, Hono, or any Server Action-capable runtime) following the void-machine `pack-server` conventions. Server Actions cross a trust boundary — the input came from a browser. Treat them like HTTP handlers, not like internal function calls.
+
+If the function is **not** marked `'use server'` (it's a normal service function in `src/services/`), use `void-tdd` directly and skip this skill.
+
+## When this skill triggers
+
+- "Add a Server Action for X"
+- "Create the action that handles the contact form"
+- "Wire this button to a mutation"
+- Any new file or function exporting `'use server'`
+
+## Location (mandatory)
+
+```
+apps/<app>/src/
+├── actions/<feature>/<verb>.ts          # preferred: typed Server Actions
+└── app/<route>/_actions.ts              # only if tightly coupled to one route
+```
+
+Server Actions **never** live inside `packages/`. Packages own services (pure-by-default); apps own actions (the trust boundary).
+
+## The five non-negotiable layers (in order)
+
+Every Server Action goes through these layers, top to bottom, **always**:
+
+```
+1. Auth          — verify session; reject unauthenticated requests
+2. Zod ingress   — schema validates the input object (no untyped formData)
+3. Rate limit    — per-user or per-IP (see rate-limit-strategy)
+4. Observability — trace ID, Sentry user scope (anonymized via hash)
+5. Service call  — pure domain logic in src/services/<feature>/
+```
+
+Skipping any of these is a security or operability bug. There are no "internal" Server Actions — anything `'use server'` is reachable from the public internet via a forged request.
+
+## Canonical skeleton (vanilla — no wrapper assumed)
+
+```ts
+// apps/web/src/actions/billing/cancel-subscription.ts
+'use server';
+
+import { z } from 'zod';
+import { cookies } from 'next/headers';
+import { logger, env } from '@repo/core';
+import * as Sentry from '@sentry/nextjs';
+import { ratelimit } from '@/adapters/ratelimit';
+import { getSession } from '@/services/auth';
+import { cancelSubscription as cancelSubscriptionService } from '@/services/billing/cancel';
+
+const Input = z.object({
+  subscriptionId: z.string().uuid(),
+  reason: z.string().min(1).max(500).optional(),
+});
+
+export async function cancelSubscription(raw: unknown) {
+  // 1. Auth
+  const session = await getSession(cookies());
+  if (!session) return { ok: false as const, error: 'unauthenticated' };
+
+  // 2. Zod ingress
+  const parsed = Input.safeParse(raw);
+  if (!parsed.success) return { ok: false as const, error: 'invalid-input' };
+  const input = parsed.data;
+
+  // 3. Rate limit (per-user)
+  const rl = await ratelimit.check(`user:${session.userId}:billing.cancel`, { window: '1 min', max: 5 });
+  if (!rl.ok) return { ok: false as const, error: 'rate-limited' };
+
+  // 4. Observability — trace context + Sentry scope (hashed user)
+  Sentry.setUser({ id: hashUserId(session.userId) });
+  const traceId = crypto.randomUUID();
+  logger.info({ traceId, userId: session.userId, action: 'billing.cancelSubscription' }, 'start');
+
+  // 5. Service call — pure
+  const result = await cancelSubscriptionService({
+    subscriptionId: input.subscriptionId,
+    userId: session.userId,
+    reason: input.reason,
+  });
+
+  if (!result.ok) {
+    logger.warn({ traceId, error: result.error }, 'cancelSubscription failed');
+    return { ok: false as const, error: result.error.code };
+  }
+  return { ok: true as const, data: result.value };
+}
+```
+
+40 lines. The 5 layers are explicit and a reviewer can audit at a glance.
+
+## Optional: `defineAction` helper
+
+If your project repeats the 5 layers in every action (it will), DRY them into a `defineAction` helper. This is a project-side convention many void-machine monorepos add in `@repo/auth` or `@repo/server`:
+
+```ts
+// Equivalent action using a project-side defineAction helper
+export const cancelSubscription = defineAction({
+  name: 'billing.cancelSubscription',
+  auth: 'required',
+  input: Input,
+  rateLimit: { window: '1 min', max: 5 },
+  handler: async ({ input, user, traceId }) => {
+    /* just the service call + result mapping */
+  },
+});
+```
+
+The helper is convenience — the 5 layers below it are the substance. Build it once when the pattern repeats 3+ times; not before.
+
+## Return type discipline
+
+Server Actions return a **discriminated union**, never throw to the client:
+
+```ts
+type ActionResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: string };       // error is a stable, human-readable code
+```
+
+- ✗ Don't return raw domain objects — they leak schema. Pick a DTO.
+- ✗ Don't `throw new Error('...')` — Next swallows the message and the client sees a 500 with no actionable info. Use the Result type.
+- ✗ Don't return Date or BigInt — they don't serialize across the action boundary. Convert in the handler.
+
+## Forbidden
+
+- `db.query(...)` directly in the action — call a service. The service calls a repository.
+- `process.env.STRIPE_KEY` — use `@repo/core/env`.
+- Inline `fetch('https://external/...')` — go through an adapter behind a port.
+- `revalidatePath('/')` without scope — pass the specific path you mutated; broad revalidation kills cache hit rate.
+- `redirect('...')` from inside a `try/catch` — Next.js `redirect()` throws on purpose; catching it breaks navigation.
+
+## Forms vs. typed actions
+
+Two flavors, pick by use case:
+
+| Use | Action signature | Input source |
+|---|---|---|
+| Submit-on-click button / typed payload | `async function(input: T)` | Object (Zod object schema) |
+| HTML form with `<form action={action}>` | `async function(formData: FormData)` | FormData (Zod parses entries; `getAll` for repeated fields) |
+
+For the FormData variant, always parse via Zod — never reach into FormData manually with raw `.get()` casts. But `Object.fromEntries(formData)` is **not** a safe default: it keeps only the **last** value of a repeated field, so a multi-select, a checkbox group, or `<input multiple>` is silently truncated to one entry. Read any field that can repeat with `getAll` and validate it as an array:
+
+```ts
+const schema = z.object({
+  title: z.string().min(1),
+  tagIds: z.array(z.string()).default([]),   // repeated field
+});
+// Single-value fields via .get(); repeated fields via .getAll().
+const input = schema.parse({
+  title: formData.get('title'),
+  tagIds: formData.getAll('tagId'),
+});
+```
+
+`Object.fromEntries(formData)` is fine only when every field is known-single-valued — and that assumption breaks the day someone adds a multi-select. Prefer the explicit shape above for any form with a repeatable input.
+
+## Workflow
+
+1. **Define the service first**, in `src/services/<feature>/<verb>.ts`. Pure-by-default; deps injected; tested in strict TDD mode.
+2. **Write the Zod input schema** in the action file. Aim for the smallest possible surface; reject unknown keys.
+3. **Pick the action shape**: object input (typed payload) or FormData input (HTML form). Parse FormData via Zod; use `getAll` + `z.array` for any repeatable field (never `Object.fromEntries`, which drops all but the last value).
+4. **Decide auth posture**: logged-in required, optional, or public (`public` requires explicit justification in a comment).
+5. **Set the rate limit**. Default per-user 30/min for mutations, 100/min for reads. Stricter on auth-adjacent actions (see `void-rate-limit-strategy`).
+6. **Wire trace + Sentry scope** explicitly in the handler (until you extract a `defineAction` helper).
+7. **Write the action test** in `<verb>.test.ts` next to the action — assert auth, validation, rate limit, and happy path. Service tests already cover the domain.
+
+## Composition (informational)
+
+- `void-security-guidance` — Zod at every ingress; sensitive data redacted from logs; no PII in error messages returned to client.
+- `void-webhook-handler-pattern` — webhooks share the 5-layer pattern; same Zod discipline, different transport.
+- `void-rate-limit-strategy` — preset windows/max per action class.
+- `void-observability` — trace ID + Sentry user scope (hashed); same pattern across actions, webhooks, jobs.
+- `void-tdd` — souple mode on the action (boundary), strict on the underlying service.
+- `void-service-package` — when the service grows enough to deserve its own package, extract it (rare, but the path is there).

package/core-assets/packs/pack-server/skills/void-server-action/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/packs/pack-server/skills/void-testing-server-modules/.source

@@ -0,0 +1,7 @@
+Sources for `void-testing-server-modules` skill (see `docs/plans/skill-audits/void-testing-server-modules.md` for the full audit):
+
+- Next.js docs — `server-only` / `client-only` packages and their import-time throw semantics (poisoning the wrong bundle). Distilled, not copied.
+- Vitest docs — `test.alias` / `resolve.alias` resolution for replacing a module at test time. Version-matched to the installed Vitest.
+- Real-world friction from a consumer project (issue #17 cluster B / B3): a server-only import chain crashed the Vitest run before any assertion.
+
+Strategy: native. The "alias to an empty stub, keep the boundary real" framing is the void-machine adaptation — it deliberately refuses to let a test-time convenience erode the build-time server/client boundary.

package/core-assets/packs/pack-server/skills/void-testing-server-modules/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: void-testing-server-modules
+description: Unit-test modules guarded by server-only / client-only under Vitest by aliasing those packages to an empty stub. Test-time only; never a substitute for the real build-time boundary.
+---
+
+# testing-server-modules
+
+`server-only` and `client-only` are import-time tripwires: they exist to **throw** the moment a server module is pulled into a client bundle (or vice-versa). That is exactly what you want at build time — and exactly what breaks Vitest, which runs neither in an RSC server graph nor in a browser. Importing any module whose chain reaches `server-only` crashes the test run with a cryptic `"This module cannot be imported from a Client Component module"` before a single assertion runs.
+
+**Attribution**: see `.source`.
+
+---
+
+## The fix — alias the tripwire to an empty stub in the Vitest config
+
+The tripwire's only job is to throw outside its runtime. Tests are outside its runtime by design, so the correct test-time substitute is an **empty module** — not a mock, not a partial.
+
+```ts
+// vitest.base.ts (shared config in the monorepo — extend it per package)
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    alias: {
+      'server-only': new URL('./test/stubs/empty.ts', import.meta.url).pathname,
+      'client-only': new URL('./test/stubs/empty.ts', import.meta.url).pathname,
+    },
+  },
+});
+```
+
+```ts
+// test/stubs/empty.ts
+export {}; // server-only / client-only export nothing; their side effect is the throw.
+```
+
+A single shared stub serves both. In a monorepo, put the alias in the `vitest.base` config every package extends, so no package re-discovers the gotcha (composes with `void-turbo-pipeline-tuning` and the shared `@repo/config`).
+
+---
+
+## What the alias does and does NOT buy you
+
+- **Does**: lets you unit-test the *pure logic* inside a server module (the service, the mapper, the validation) without standing up an RSC runtime.
+- **Does NOT**: make the module safe to import from a Client Component. The real server/client boundary still holds at build time — the alias is **test-only**. If a client component genuinely imports a server module, that is a real boundary violation the build will (correctly) reject; do not "fix" it by widening the alias. Keep the pure, testable logic in a runtime-agnostic `services/` module and let the thin server wrapper carry the `server-only` import (composes with `void-env-validation`, which keeps server-only env access out of the edge/client chain).
+
+---
+
+## When this applies
+
+- A Vitest run fails on import with a `server-only` / `client-only` error before any test body executes.
+- You are setting up the shared test config for a Next.js / RSC monorepo and want every package to inherit the alias once.
+
+## When it does NOT
+
+- Pure modules with no `server-only` import need no alias — prefer keeping domain logic runtime-agnostic so the question never arises.
+- Integration/e2e runners that DO execute in the real runtime (Playwright, the Next.js test runtime) must NOT stub these — there the tripwire is meaningful.
+
+---
+
+## Anti-rules
+
+- MUST NOT mock `server-only` with anything but an empty module — it has no API to mock, only a side effect to neutralize.
+- MUST NOT use the alias to import a server module from client code in production — the alias is test-only; the boundary is real.
+- MUST NOT scatter the alias per-test-file — define it once in the shared Vitest config.
+
+---
+
+## Final rule
+
+```
+server-only/client-only break Vitest → alias to an empty stub in the shared config, test the pure logic.
+The build-time boundary stays real → never let the alias paper over a true client/server violation.
+```

package/core-assets/packs/pack-server/skills/void-testing-server-modules/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/packs/pack-server/skills/void-webhook-handler-pattern/.source

@@ -0,0 +1,7 @@
+Sources for `void-webhook-handler-pattern` skill (see `docs/plans/skill-audits/void-webhook-handler-pattern.md` for the full audit):
+
+- No external source audited — native distillation of canonical per-source webhook patterns.
+- Per-source patterns referenced (not vendored): Stripe, Resend, GitHub signature/idempotency/retry semantics.
+- Doctrine referenced: `void-async-safety` (stack-agnostic retry/idempotency/dead-letter).
+
+Strategy: distill. Per-source handler patterns distilled into the 5 non-negotiable layers; no upstream skill was copied.