feat: license verification library + minting service

.gitignore

@@ -43,3 +43,6 @@ __pycache__/
 
 # Local LangGraph deployment deps
 deployments/*/deps/
+
+# Generated license public key (produced by libs/licensing/scripts/generate-public-key.mjs)
+libs/licensing/src/lib/license-public-key.generated.ts

apps/cockpit/project.json

@@ -41,7 +41,7 @@
       }
     },
     "test": {
-      "executor": "@nx/vite:test",
+      "executor": "@nx/vitest:test",
       "options": {
         "configFile": "apps/cockpit/vite.config.mts"
       }

apps/minting-service/.env.example

@@ -0,0 +1,16 @@
+# Stripe
+STRIPE_SECRET_KEY=sk_test_replace_me
+STRIPE_WEBHOOK_SECRET=whsec_replace_me
+
+# Postgres (Vercel Postgres connection string)
+DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=require
+
+# Resend
+RESEND_API_KEY=re_replace_me
+EMAIL_FROM=licenses@example.com
+
+# License signing (64 hex chars, 32 bytes Ed25519 private key)
+LICENSE_SIGNING_PRIVATE_KEY_HEX=0000000000000000000000000000000000000000000000000000000000000000
+
+# Optional: fallback TTL when a subscription has no current_period_end
+LICENSE_DEFAULT_TTL_DAYS=365

apps/minting-service/README.md

@@ -0,0 +1,152 @@
+# @cacheplane/minting-service
+
+License minting service for Cacheplane. Receives Stripe webhooks, signs
+Ed25519 license tokens via `@cacheplane/licensing`, persists them to
+Postgres via `@cacheplane/db`, and emails them to customers via Resend.
+
+**Design spec:** `docs/superpowers/specs/2026-04-20-minting-service-design.md`
+
+## What this service does
+
+- Handles Stripe events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`.
+- Mints a signed license token per active subscription.
+- Emails the token to the customer.
+- Stores license state keyed on `stripe_subscription_id`.
+
+## What this service does NOT do
+
+- No customer portal / self-service resend (run the CLI — see below).
+- No pricing/checkout UI (handled on the website — Plan 3).
+- No automated key rotation (requires library republish).
+
+## Local development
+
+1. Install Docker (for local Postgres) and the Stripe CLI.
+2. From the repo root:
+   ```bash
+   docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16
+   cp apps/minting-service/.env.example apps/minting-service/.env
+   # Edit .env with local values; for LICENSE_SIGNING_PRIVATE_KEY_HEX
+   # generate a keypair (see "Generating a signing key" below).
+   DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres npx nx run db:db:migrate
+   cd apps/minting-service && vercel dev
+   ```
+3. In another terminal:
+   ```bash
+   stripe listen --forward-to localhost:3000/api/stripe-webhook
+   # Copy the printed whsec_... into apps/minting-service/.env as STRIPE_WEBHOOK_SECRET
+   ```
+4. Trigger events:
+   ```bash
+   stripe trigger checkout.session.completed
+   ```
+
+## Generating a signing key
+
+```bash
+node -e "import('@noble/ed25519').then(async (e) => {
+  const sk = e.utils.randomPrivateKey();
+  const pk = await e.getPublicKeyAsync(sk);
+  console.log('priv (LICENSE_SIGNING_PRIVATE_KEY_HEX):', Buffer.from(sk).toString('hex'));
+  console.log('pub  (LICENSE_PUBLIC_KEY in @cacheplane/licensing):', Buffer.from(pk).toString('hex'));
+});"
+```
+
+Store the private key in the Vercel env as `LICENSE_SIGNING_PRIVATE_KEY_HEX`
+marked "Sensitive". Back up to a password manager. The **public** key must be
+baked into `libs/licensing/src/lib/license-public-key.generated.ts` and the
+lib republished.
+
+## Environment variables
+
+All listed in `.env.example`. Validated at process start by `src/lib/env.ts`.
+Missing/malformed vars throw with a descriptive message.
+
+## Deployment
+
+1. Ensure schema is up to date:
+   ```bash
+   DATABASE_URL=<prod-url> npx nx run db:db:migrate
+   ```
+2. Push. Vercel deploys from `main` automatically for production and per PR
+   for previews.
+3. Smoke test preview:
+   ```bash
+   curl https://<preview>.vercel.app/api/health   # {"ok":true}
+   stripe trigger checkout.session.completed      # (against preview webhook endpoint)
+   ```
+
+## Operator runbook
+
+### Re-mint a license
+
+```bash
+nx run minting-service:remint --sub=sub_1234 [--dry-run] [--to=new@email.com] [--new-token]
+```
+
+- `--sub=<stripe_subscription_id>` (required): which license to resend.
+- `--dry-run`: print what would be sent; don't call Resend.
+- `--to=<email>`: override destination (use after an email bounce).
+- `--new-token`: re-sign a fresh token (updates `last_token` + `issued_at`).
+  Default is to re-send the existing `last_token`.
+
+Revoked licenses are refused.
+
+### Look up a customer's license
+
+```bash
+psql $DATABASE_URL -c "SELECT * FROM licenses WHERE customer_email = 'x@y.z'"
+```
+
+### Manually revoke
+
+```sql
+UPDATE licenses SET revoked_at = now() WHERE stripe_subscription_id = 'sub_xxx';
+```
+
+Prefer canceling the Stripe subscription — this bypasses the normal webhook
+flow and won't un-revoke on a new subscription.
+
+### Un-revoke after accidental revoke
+
+```sql
+UPDATE licenses SET revoked_at = NULL WHERE stripe_subscription_id = 'sub_xxx';
+```
+
+Then `nx run minting-service:remint --sub=sub_xxx --new-token` to issue a
+fresh token.
+
+### Retry a failed webhook
+
+1. In the Stripe dashboard → Developers → Webhooks, find the failed event `evt_xxx`.
+2. Check if we recorded it:
+   ```sql
+   SELECT * FROM processed_events WHERE stripe_event_id = 'evt_xxx';
+   ```
+3. If present: `DELETE FROM processed_events WHERE stripe_event_id = 'evt_xxx';`
+4. Click "Resend" on the event in Stripe.
+
+### Rotate the signing key (manual, v1)
+
+Current design requires a library republish (no multi-key verification).
+Steps:
+
+1. Generate new keypair (see "Generating a signing key").
+2. Update `libs/licensing/src/lib/license-public-key.generated.ts` with the new public key.
+3. Republish `@cacheplane/licensing` (minor version bump).
+4. Update `LICENSE_SIGNING_PRIVATE_KEY_HEX` in Vercel env.
+5. Deploy minting service.
+6. Batch-remint all active licenses:
+   ```bash
+   # Example: loop over all non-revoked subs and re-mint with fresh tokens
+   psql $DATABASE_URL -t -c "SELECT stripe_subscription_id FROM licenses WHERE revoked_at IS NULL" | \
+     xargs -I{} nx run minting-service:remint --sub={} --new-token
+   ```
+
+All existing tokens become unverifiable once customers upgrade the library.
+
+## Why this repo is public
+
+The private signing key lives only in Vercel env. Everything else — schema,
+webhook logic, re-mint flow — is plumbing. Possession of the key is the only
+thing that matters. Documenting the process openly is a transparency plus.

apps/minting-service/api/health.ts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+
+export default function handler(_req: VercelRequest, res: VercelResponse): void {
+  res.status(200).json({ ok: true });
+}

apps/minting-service/api/stripe-webhook.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import type { IncomingMessage } from 'node:http';
+import {
+  createDb,
+  markEventProcessed,
+  deleteProcessedEvent,
+  upsertLicense,
+  getLicense,
+  revokeLicense,
+} from '@cacheplane/db';
+import { loadEnv } from '../src/lib/env.js';
+import { getStripe } from '../src/lib/stripe.js';
+import { mintToken } from '../src/lib/sign.js';
+import { sendLicenseEmail } from '../src/lib/email.js';
+import { handleEvent, type HandlerDeps } from '../src/lib/handlers.js';
+
+export const config = { api: { bodyParser: false } };
+
+async function readRawBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+export default async function handler(req: VercelRequest, res: VercelResponse): Promise<void> {
+  if (req.method !== 'POST') {
+    res.status(405).end();
+    return;
+  }
+
+  const env = loadEnv();
+  const stripe = getStripe(env.STRIPE_SECRET_KEY);
+
+  const rawBody = await readRawBody(req);
+  const sig = req.headers['stripe-signature'];
+  if (typeof sig !== 'string') {
+    res.status(400).send('missing signature');
+    return;
+  }
+
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(rawBody, sig, env.STRIPE_WEBHOOK_SECRET);
+  } catch (err) {
+    console.error('stripe signature verification failed', err);
+    res.status(400).send('invalid signature');
+    return;
+  }
+
+  const db = createDb(env.DATABASE_URL);
+  const deps: HandlerDeps = {
+    db,
+    stripe,
+    markEventProcessed,
+    deleteProcessedEvent,
+    upsertLicense,
+    getLicense,
+    revokeLicense,
+    mintToken,
+    sendLicenseEmail,
+    privateKeyHex: env.LICENSE_SIGNING_PRIVATE_KEY_HEX,
+    resendApiKey: env.RESEND_API_KEY,
+    emailFrom: env.EMAIL_FROM,
+    defaultTtlDays: env.LICENSE_DEFAULT_TTL_DAYS,
+  };
+
+  try {
+    await handleEvent(event, deps);
+    res.status(200).json({ received: true });
+  } catch (err) {
+    console.error('webhook handler error', { eventId: event.id, type: event.type, err });
+    res.status(500).send('internal error');
+  } finally {
+    await db.close();
+  }
+}

apps/minting-service/eslint.config.mjs

@@ -0,0 +1,3 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [...baseConfig];

apps/minting-service/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cacheplane/minting-service",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "postgres": "^3.4.9",
+    "resend": "^6.10.0",
+    "stripe": "^22.0.2"
+  }
+}

apps/minting-service/project.json

@@ -0,0 +1,21 @@
+{
+  "name": "minting-service",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/minting-service/src",
+  "projectType": "application",
+  "tags": ["scope:service", "type:app"],
+  "targets": {
+    "lint": { "executor": "@nx/eslint:lint" },
+    "test": {
+      "executor": "@nx/vitest:test",
+      "options": { "configFile": "apps/minting-service/vite.config.mts" }
+    },
+    "remint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsx scripts/remint.ts",
+        "cwd": "apps/minting-service"
+      }
+    }
+  }
+}