@buildproven/license-core 1.0.1 → 1.0.2

package/README.md

@@ -153,6 +153,105 @@ openssl rsa -in private.pem -pubout -out public.pem
 
 The package never handles key generation, storage, or rotation — that's your call. Use whatever secret manager you already have.
 
+### Rotating a signing key
+
+Every entry in the registry has a `keyId` field, and `_metadata.keyId` records which key signed the registry as a whole. To rotate without breaking already-shipped clients:
+
+1. Generate a new keypair. Add the new private key to your fulfillment env vars (e.g. `LICENSE_PRIVATE_KEY_V2`).
+2. Update fulfillment to sign new entries with the new key, passing `keyId: 'v2'`:
+
+   ```ts
+   buildSignedRegistry(entries, NEW_PRIVATE_KEY, 'v2');
+   ```
+
+3. **Bundle BOTH public keys with your client.** When verifying, look up the right key based on `entry.keyId`:
+
+   ```ts
+   const publicKeys = { default: OLD_PUBLIC_KEY, v2: NEW_PUBLIC_KEY };
+   const result = validateRegistryEntry({
+     licenseKey,
+     entry,
+     publicKeyPem: publicKeys[entry.keyId] ?? publicKeys.default,
+   });
+   ```
+
+4. Existing entries (signed with `keyId: 'default'`) continue to verify under the old public key. New entries verify under the new key.
+5. Once all old entries have expired or been re-issued, you can ship a client release that drops the old public key.
+
+The package leaves `keyId` as a free-form string, so use whatever convention you like (`v1`/`v2`, dates, fingerprints).
+
+## Recurring billing & subscriptions
+
+The frozen-contract v1.x API doesn't include `expiresAt` on payloads, so subscriptions need a layer above the package. Two patterns work:
+
+### Pattern A — short-lived registries (re-sign on a schedule)
+
+Your fulfillment service holds the source-of-truth subscription state (Stripe, paddle, whatever). On a cron/interval (e.g. once an hour), it walks active customers, builds a fresh `Registry`, calls `buildSignedRegistry`, and serves the result. Cancelled customers simply stop appearing in the next signed registry.
+
+The client refreshes the registry once per launch + once per N hours/days, and falls back to the locally-cached signed JSON if offline. A 7-day grace period (registry valid 7 days offline) is typical — long enough that flaky internet doesn't lock paying customers out, short enough that cancellations propagate within a week.
+
+```ts
+// Client side
+async function getRegistry() {
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(5000) });
+    const signed = await res.json();
+    const entries = verifyRegistryMetadata(signed, PUBLIC_KEY);
+    await fs.writeFile(CACHE_PATH, JSON.stringify(signed));   // cache for offline
+    return entries;
+  } catch {
+    const cached = JSON.parse(await fs.readFile(CACHE_PATH, 'utf8'));
+    return verifyRegistryMetadata(cached, PUBLIC_KEY);        // offline path
+  }
+}
+```
+
+### Pattern B — long-lived entries + revocation list
+
+Entries are signed once and stay valid forever. A separate signed `revoked.json` lists keys that should no longer verify. The client fetches both and rejects any license that appears in the revocations file.
+
+This is faster on the fulfillment side (you don't re-sign the whole registry every hour) but requires more client logic. Tracked in the v2.x roadmap because v1.x doesn't ship a revocation helper yet.
+
+### Which pattern when?
+
+- **Few customers, frequent cancellations:** Pattern A — re-signing daily is cheap.
+- **Many customers, rare cancellations:** Pattern B — appending to a small revocations list is cheaper than re-signing thousands of entries.
+- **Lifetime licenses only:** neither — sign once on purchase, never re-sign.
+
+## Publishing your own fork (Trusted Publishing setup)
+
+If you fork this and want to publish under your own scope via npm Trusted Publishing (no `NPM_TOKEN`), there's one gotcha worth documenting because it cost an hour during the initial release here:
+
+**Don't pass `registry-url` to `actions/setup-node`.** It auto-generates an `.npmrc` with a placeholder `${NODE_AUTH_TOKEN}` value, which makes `npm publish` authenticate via that fake token instead of falling through to OIDC. Result: a `404 Not Found` from the registry that looks like a misconfigured trusted publisher.
+
+The minimal working workflow:
+
+```yaml
+name: Publish to npm
+on:
+  push:
+    tags: ['v*.*.*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # required for OIDC
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          # NO registry-url here — it would inject a fake NODE_AUTH_TOKEN
+      - run: npm install -g npm@latest    # need >=11.5.1 for Trusted Publishing
+      - run: npm ci
+      - run: npm test
+      - run: npm publish --access public --provenance
+```
+
+On the npm side, configure the trusted publisher under your package's settings page after the package exists (chicken-and-egg: do the *first* publish via a granular access token, then switch to OIDC for everything after).
+
 ## License
 
 [MIT](./LICENSE) © Vibe Build Lab LLC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildproven/license-core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Shared license signing & verification primitives for BuildProven products (RSA-SHA256, signed registry).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "fast-check": "^4.7.0",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",