@buildproven/license-core 1.0.0 → 1.0.2

package/README.md

@@ -1,71 +1,265 @@
-# @buildproven/license-core
+# `@buildproven/license-core`
 
-Shared license signing & verification primitives for BuildProven products.
+[![npm version](https://img.shields.io/npm/v/@buildproven/license-core.svg)](https://www.npmjs.com/package/@buildproven/license-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What this is
+Tiny, frozen-contract license signing & verification primitives. Deterministic JSON, RSA-SHA256, signed registry. Use it to issue and verify software licenses without running a license server on the hot path — clients fetch a signed JSON registry, verify it locally with a bundled public key, and decide.
 
-A tiny, frozen-contract package that does one thing: deterministic stringify + RSA-SHA256 sign/verify so that every BuildProven product (QA Architect, claude-kit-pro, future products) can validate licenses against the same byte-for-byte format.
+```
+npm install @buildproven/license-core
+```
 
-Used by:
+## Why this exists
 
-- `buildproven-fulfillment` (Vercel) — signs entries, builds signed registries
-- `qa-architect` (npm CLI) — verifies fetched registry against bundled public key
-- `claude-kit-pro` (Claude Code MCP plugin) — same
+If you're shipping a desktop app, CLI tool, or developer plugin and want to sell licenses, you need:
 
-## Why it exists
+1. A way to **sign** a license entry on your server (when a customer pays)
+2. A way for the **client** to verify that signature locally — without making a network call on every launch
 
-Before this package, the same crypto code lived in 3 places. Any drift broke signature verification across the product/server boundary. Now there's one source of truth.
+That's what this is. ~14 functions, no runtime dependencies. Sign on the server, distribute a signed registry as a static JSON file, verify on the client. Works offline, no license server to keep alive, no per-call latency.
 
-## API
+## Quick example
+
+### Server side (when a customer purchases)
 
 ```ts
 import {
-  // Crypto primitives
-  stableStringify,
+  buildLicensePayload,
+  buildSignedRegistry,
+  hashEmail,
   signPayload,
-  verifyPayload,
-  computeHash,
-  timingSafeStringEqual,
+  type Registry,
+} from '@buildproven/license-core';
 
-  // Payload construction
-  normalizeEmail,
-  hashEmail,
-  buildLicensePayload,
+const PRIVATE_KEY = process.env.LICENSE_PRIVATE_KEY!; // PEM, RSA 2048+
 
-  // Registry
-  buildSignedRegistry,
+const issued = new Date().toISOString();
+const payload = buildLicensePayload({
+  licenseKey: 'MYAPP-A1B2-C3D4-E5F6-7890',
+  tier: 'PRO',
+  isFounder: false,
+  issued,
+  emailHash: hashEmail('customer@example.com') ?? undefined,
+});
+
+const entry = {
+  tier: 'PRO' as const,
+  isFounder: false,
+  issued,
+  emailHash: hashEmail('customer@example.com'),
+  signature: signPayload(payload, PRIVATE_KEY),
+  customerId: 'cus_abc123',
+  keyId: 'default',
+};
+
+const registry: Registry = { 'MYAPP-A1B2-C3D4-E5F6-7890': entry };
+const signedRegistry = buildSignedRegistry(registry, PRIVATE_KEY);
+
+// Serve `signedRegistry` as JSON at e.g. https://yoursite.com/api/licenses.json
+```
 
-  // Validation helpers (pure — no I/O)
+### Client side (when the user starts your app)
+
+```ts
+import {
   validateRegistryEntry,
   verifyRegistryMetadata,
-
-  // Key format
-  licenseKeyPattern,
+  hashEmail,
   isValidLicenseKey,
-  normalizeLicenseKey,
 } from '@buildproven/license-core';
+
+const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+...
+-----END PUBLIC KEY-----`; // bundled with your app
+
+const userKey = process.env.MYAPP_LICENSE_KEY ?? '';
+const userEmail = '...'; // from your activation flow
+
+if (!isValidLicenseKey(userKey, 'MYAPP')) {
+  throw new Error('Bad key format');
+}
+
+const res = await fetch('https://yoursite.com/api/licenses.json');
+const signedRegistry = await res.json();
+
+const entries = verifyRegistryMetadata(signedRegistry, PUBLIC_KEY); // throws on tampering
+const entry = entries[userKey.toUpperCase()];
+if (!entry) throw new Error('License not found');
+
+const result = validateRegistryEntry({
+  licenseKey: userKey.toUpperCase(),
+  entry,
+  publicKeyPem: PUBLIC_KEY,
+  userEmailHash: hashEmail(userEmail) ?? undefined,
+});
+
+if (!result.valid) throw new Error(result.error);
+
+console.log(`Licensed: ${result.tier}, Founder: ${result.isFounder}`);
 ```
 
+## API reference
+
+### Crypto primitives
+
+- `stableStringify(value)` — deterministic JSON stringify (sorted keys, circular-ref detection)
+- `signPayload(payload, privateKeyPem)` — RSA-SHA256 sign, returns base64
+- `verifyPayload(payload, signature, publicKeyPem)` — RSA-SHA256 verify, returns boolean
+- `computeHash(data)` — SHA-256 hex
+- `timingSafeStringEqual(a, b)` — constant-time string comparison
+
+### Payload construction
+
+- `normalizeEmail(email)` — trim + lowercase + format-validate, or `null`
+- `hashEmail(email)` — SHA-256 hex of normalized email, or `null`
+- `buildLicensePayload({ licenseKey, tier, isFounder, issued, emailHash? })` — the **frozen** payload shape
+
+### Registry
+
+- `buildSignedRegistry(entries, privateKeyPem, keyId?)` — wraps entries with `_metadata` containing the registry signature and hash
+
+### Validation helpers (pure — no I/O)
+
+- `validateRegistryEntry({ licenseKey, entry, publicKeyPem, userEmailHash? })` — verifies one entry's signature and optional email match
+- `verifyRegistryMetadata(signedRegistry, publicKeyPem)` — verifies the registry-level signature and hash, returns extracted entries (throws on failure)
+
+### Key format
+
+- `licenseKeyPattern(prefix)` — RegExp for `PREFIX-XXXX-XXXX-XXXX-XXXX`
+- `isValidLicenseKey(key, prefix)` — boolean
+- `normalizeLicenseKey(key)` — trim + uppercase
+
+### Types
+
+`Tier`, `LicensePayload`, `RegistryEntry`, `Registry`, `RegistryMetadata`, `SignedRegistry`, `ValidatedEntry`, `ValidationFailure`, `ValidationResult`
+
 ## Frozen contract
 
-The shape of `LicensePayload` and `RegistryEntry` is **frozen** for the v1.x line. Adding fields is a breaking change because shipped customer CLIs reconstruct payloads from registry entries to verify signatures — any field set drift causes silent verification failure.
+The shape of `LicensePayload` and `RegistryEntry` is **frozen for the entire `1.x` line**. Shipped clients in the field rebuild these payloads from registry entries to verify signatures — adding a field would silently break verification for every existing customer.
 
-If you need a new field, bump the major and ship as a new package name (`@buildproven/license-core-v2`). The 1.x line continues to be the contract for QA Architect's deployed customers.
+To evolve the schema: bump major and ship as a new package name. The 1.x line is the contract for already-deployed clients.
 
-## Install
+## How keys work
+
+You generate one RSA-2048 keypair per product:
 
 ```bash
-npm install @buildproven/license-core
+openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
+openssl rsa -in private.pem -pubout -out public.pem
 ```
 
-## Develop
+- **Private key** lives in your fulfillment server's env vars. It signs license entries.
+- **Public key** is bundled with your client. It verifies signatures.
 
-```bash
-npm install
-npm test       # vitest, includes golden-vector test against QAA's deployed code
-npm run build  # tsup → dist/
+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
+[MIT](./LICENSE) © Vibe Build Lab LLC
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). The `1.x` line has a frozen contract; most contributions should be bug fixes, doc improvements, or test coverage.
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for the threat model and how to report vulnerabilities.

package/dist/index.cjs

@@ -126,7 +126,7 @@ function buildSignedRegistry(entries, privateKeyPem, keyId = "default") {
       version: "1.0",
       created: now,
       lastUpdate: now,
-      description: "BuildProven license registry \u2014 populated by fulfillment webhook",
+      description: "License registry \u2014 populated by fulfillment webhook",
       algorithm: "rsa-sha256",
       keyId,
       registrySignature,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/signing.ts","../src/payload.ts","../src/registry.ts","../src/validator.ts","../src/key-format.ts"],"sourcesContent":["// Crypto primitives\nexport {\n  stableStringify,\n  signPayload,\n  verifyPayload,\n  computeHash,\n  timingSafeStringEqual,\n} from './signing.js';\n\n// Payload construction\nexport { normalizeEmail, hashEmail, buildLicensePayload } from './payload.js';\n\n// Registry construction\nexport { buildSignedRegistry } from './registry.js';\n\n// Validation helpers (pure — no I/O)\nexport { validateRegistryEntry, verifyRegistryMetadata } from './validator.js';\nexport type { ValidatedEntry, ValidationFailure, ValidationResult } from './validator.js';\n\n// License key format\nexport { licenseKeyPattern, isValidLicenseKey, normalizeLicenseKey } from './key-format.js';\n\n// Types\nexport type {\n  Tier,\n  LicensePayload,\n  RegistryEntry,\n  Registry,\n  RegistryMetadata,\n  SignedRegistry,\n} from './types.js';\n","/**\n * Deterministic stringify + RSA-SHA256 sign/verify primitives.\n *\n * stableStringify must produce byte-identical output to QA Architect's\n * shipped lib/license-signing.js — the deployed CLI in customers' hands\n * uses that exact algorithm. Any divergence here breaks every QAA license\n * issued to date.\n */\n\nimport { sign as cryptoSign, verify as cryptoVerify, createHash } from 'crypto';\n\nexport function stableStringify(value: unknown, seen: WeakSet<object> = new WeakSet()): string {\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value);\n  }\n  if (seen.has(value as object)) {\n    throw new Error('Circular reference detected in payload - cannot serialize');\n  }\n  seen.add(value as object);\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, seen)).join(',')}]`;\n  }\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  const entries = keys.map(\n    (key) =>\n      `${JSON.stringify(key)}:${stableStringify((value as Record<string, unknown>)[key], seen)}`,\n  );\n  return `{${entries.join(',')}}`;\n}\n\nexport function signPayload(payload: unknown, privateKeyPem: string): string {\n  const data = Buffer.from(stableStringify(payload));\n  return cryptoSign(null, data, privateKeyPem).toString('base64');\n}\n\nexport function verifyPayload(payload: unknown, signature: string, publicKeyPem: string): boolean {\n  try {\n    const data = Buffer.from(stableStringify(payload));\n    return cryptoVerify(null, data, publicKeyPem, Buffer.from(signature, 'base64'));\n  } catch {\n    return false;\n  }\n}\n\nexport function computeHash(data: string): string {\n  return createHash('sha256').update(data).digest('hex');\n}\n\n/**\n * Constant-time string comparison. Same length precondition is checked\n * outside the comparison loop to avoid leaking length info.\n */\nexport function timingSafeStringEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) {\n    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n  return diff === 0;\n}\n","/**\n * Email normalization, hashing, and license payload construction.\n *\n * buildLicensePayload is the contract the fulfillment service signs against\n * and that every client must rebuild bit-for-bit before verification. Adding\n * fields here = breaking change.\n */\n\nimport { createHash } from 'crypto';\nimport type { LicensePayload, Tier } from './types.js';\n\nexport function normalizeEmail(email: string): string | null {\n  if (!email || typeof email !== 'string') return null;\n  const normalized = email.trim().toLowerCase();\n  if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(normalized)) return null;\n  return normalized.length > 0 ? normalized : null;\n}\n\nexport function hashEmail(email: string): string | null {\n  const normalized = normalizeEmail(email);\n  if (!normalized) return null;\n  return createHash('sha256').update(normalized).digest('hex');\n}\n\nexport function buildLicensePayload(opts: {\n  licenseKey: string;\n  tier: Tier;\n  isFounder: boolean;\n  issued: string;\n  emailHash?: string | null;\n}): LicensePayload {\n  if (!opts.licenseKey || typeof opts.licenseKey !== 'string') {\n    throw new Error('licenseKey is required and must be a string');\n  }\n  if (!opts.tier || typeof opts.tier !== 'string') {\n    throw new Error('tier is required and must be a string');\n  }\n  if (!opts.issued || typeof opts.issued !== 'string') {\n    throw new Error('issued is required and must be a string');\n  }\n\n  const payload: LicensePayload = {\n    licenseKey: opts.licenseKey,\n    tier: opts.tier,\n    isFounder: Boolean(opts.isFounder),\n    issued: opts.issued,\n  };\n  if (opts.emailHash) {\n    payload.emailHash = opts.emailHash;\n  }\n  return payload;\n}\n","/**\n * Build a complete signed registry from a flat entries map.\n *\n * The registry signature covers ONLY the entries — _metadata is excluded.\n * QAA's deployed validator destructures `_metadata` out before verifying,\n * so any change to what's signed will break compatibility.\n */\n\nimport { computeHash, signPayload, stableStringify } from './signing.js';\nimport type { Registry, SignedRegistry } from './types.js';\n\nexport function buildSignedRegistry(\n  entries: Registry,\n  privateKeyPem: string,\n  keyId = 'default',\n): SignedRegistry {\n  const now = new Date().toISOString();\n  const entriesStr = stableStringify(entries);\n  const registrySignature = signPayload(entries, privateKeyPem);\n  const hash = computeHash(entriesStr);\n\n  return {\n    _metadata: {\n      version: '1.0',\n      created: now,\n      lastUpdate: now,\n      description: 'BuildProven license registry — populated by fulfillment webhook',\n      algorithm: 'rsa-sha256',\n      keyId,\n      registrySignature,\n      hash,\n      totalLicenses: Object.keys(entries).length,\n    },\n    ...entries,\n  };\n}\n","/**\n * Pure validation helpers — no I/O, no caching, no env.\n *\n * Both QA Architect's CLI and claude-kit-pro's MCP server use these\n * to verify a registry response. Anything that touches disk, network,\n * or process.env stays in the consuming product. This is the seam\n * that prevents the two validators from drifting apart.\n */\n\nimport { buildLicensePayload } from './payload.js';\nimport { computeHash, stableStringify, timingSafeStringEqual, verifyPayload } from './signing.js';\nimport type { RegistryEntry, SignedRegistry } from './types.js';\n\nexport interface ValidatedEntry {\n  valid: true;\n  tier: RegistryEntry['tier'];\n  isFounder: boolean;\n  customerId: string;\n  keyId: string;\n}\n\nexport interface ValidationFailure {\n  valid: false;\n  error: string;\n}\n\nexport type ValidationResult = ValidatedEntry | ValidationFailure;\n\n/**\n * Verify a single registry entry against its embedded signature.\n * Optionally check the user's email hash against the entry's emailHash.\n *\n * Mirrors QAA's validateLicense() field-set exactly:\n *   payload = { licenseKey, tier, isFounder, issued, emailHash? }\n */\nexport function validateRegistryEntry(opts: {\n  licenseKey: string;\n  entry: RegistryEntry;\n  publicKeyPem: string;\n  /** If supplied, must match entry.emailHash (timing-safe). */\n  userEmailHash?: string;\n}): ValidationResult {\n  const { licenseKey, entry, publicKeyPem, userEmailHash } = opts;\n\n  if (entry.emailHash && userEmailHash && !timingSafeStringEqual(userEmailHash, entry.emailHash)) {\n    return { valid: false, error: 'Email address does not match license registration' };\n  }\n\n  const payload = buildLicensePayload({\n    licenseKey,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    issued: entry.issued,\n    emailHash: entry.emailHash,\n  });\n\n  if (!verifyPayload(payload, entry.signature, publicKeyPem)) {\n    return { valid: false, error: 'License entry signature verification failed' };\n  }\n\n  return {\n    valid: true,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    customerId: entry.customerId,\n    keyId: entry.keyId,\n  };\n}\n\n/**\n * Verify a complete signed registry: registry-level signature + hash check.\n * Returns the entries map (with _metadata stripped) on success, throws on failure.\n *\n * Throws (rather than returning a result) because a registry signature failure\n * should halt validation entirely — clients should not fall back to entries\n * from an unverified registry.\n */\nexport function verifyRegistryMetadata(\n  signedRegistry: SignedRegistry,\n  publicKeyPem: string,\n): Record<string, RegistryEntry> {\n  const { _metadata, ...entries } = signedRegistry;\n\n  if (!_metadata?.registrySignature) {\n    throw new Error('Registry missing _metadata.registrySignature');\n  }\n\n  if (!verifyPayload(entries, _metadata.registrySignature, publicKeyPem)) {\n    throw new Error('Registry signature verification failed');\n  }\n\n  if (_metadata.hash) {\n    const computed = computeHash(stableStringify(entries));\n    if (!timingSafeStringEqual(computed, _metadata.hash)) {\n      throw new Error('Registry hash mismatch');\n    }\n  }\n\n  return entries as Record<string, RegistryEntry>;\n}\n","/**\n * Per-product license key format.\n *\n * QAA-XXXX-XXXX-XXXX-XXXX, CKIT-XXXX-XXXX-XXXX-XXXX, etc.\n * One factory so every product validates the same way.\n */\n\nexport function licenseKeyPattern(prefix: string): RegExp {\n  if (!/^[A-Z0-9]+$/.test(prefix)) {\n    throw new Error(`Prefix must be uppercase alphanumeric: ${prefix}`);\n  }\n  return new RegExp(`^${prefix}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$`);\n}\n\nexport function isValidLicenseKey(key: string, prefix: string): boolean {\n  return licenseKeyPattern(prefix).test(key.trim().toUpperCase());\n}\n\nexport function normalizeLicenseKey(key: string): string {\n  return key.trim().toUpperCase();\n}\n"],"mappings":"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","names":["cryptoSign","cryptoVerify","import_crypto"]}
+{"version":3,"sources":["../src/index.ts","../src/signing.ts","../src/payload.ts","../src/registry.ts","../src/validator.ts","../src/key-format.ts"],"sourcesContent":["// Crypto primitives\nexport {\n  stableStringify,\n  signPayload,\n  verifyPayload,\n  computeHash,\n  timingSafeStringEqual,\n} from './signing.js';\n\n// Payload construction\nexport { normalizeEmail, hashEmail, buildLicensePayload } from './payload.js';\n\n// Registry construction\nexport { buildSignedRegistry } from './registry.js';\n\n// Validation helpers (pure — no I/O)\nexport { validateRegistryEntry, verifyRegistryMetadata } from './validator.js';\nexport type { ValidatedEntry, ValidationFailure, ValidationResult } from './validator.js';\n\n// License key format\nexport { licenseKeyPattern, isValidLicenseKey, normalizeLicenseKey } from './key-format.js';\n\n// Types\nexport type {\n  Tier,\n  LicensePayload,\n  RegistryEntry,\n  Registry,\n  RegistryMetadata,\n  SignedRegistry,\n} from './types.js';\n","/**\n * Deterministic stringify + RSA-SHA256 sign/verify primitives.\n *\n * stableStringify must produce byte-identical output to QA Architect's\n * shipped lib/license-signing.js — the deployed CLI in customers' hands\n * uses that exact algorithm. Any divergence here breaks every QAA license\n * issued to date.\n */\n\nimport { sign as cryptoSign, verify as cryptoVerify, createHash } from 'crypto';\n\nexport function stableStringify(value: unknown, seen: WeakSet<object> = new WeakSet()): string {\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value);\n  }\n  if (seen.has(value as object)) {\n    throw new Error('Circular reference detected in payload - cannot serialize');\n  }\n  seen.add(value as object);\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, seen)).join(',')}]`;\n  }\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  const entries = keys.map(\n    (key) =>\n      `${JSON.stringify(key)}:${stableStringify((value as Record<string, unknown>)[key], seen)}`,\n  );\n  return `{${entries.join(',')}}`;\n}\n\nexport function signPayload(payload: unknown, privateKeyPem: string): string {\n  const data = Buffer.from(stableStringify(payload));\n  return cryptoSign(null, data, privateKeyPem).toString('base64');\n}\n\nexport function verifyPayload(payload: unknown, signature: string, publicKeyPem: string): boolean {\n  try {\n    const data = Buffer.from(stableStringify(payload));\n    return cryptoVerify(null, data, publicKeyPem, Buffer.from(signature, 'base64'));\n  } catch {\n    return false;\n  }\n}\n\nexport function computeHash(data: string): string {\n  return createHash('sha256').update(data).digest('hex');\n}\n\n/**\n * Constant-time string comparison. Same length precondition is checked\n * outside the comparison loop to avoid leaking length info.\n */\nexport function timingSafeStringEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) {\n    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n  return diff === 0;\n}\n","/**\n * Email normalization, hashing, and license payload construction.\n *\n * buildLicensePayload is the contract the fulfillment service signs against\n * and that every client must rebuild bit-for-bit before verification. Adding\n * fields here = breaking change.\n */\n\nimport { createHash } from 'crypto';\nimport type { LicensePayload, Tier } from './types.js';\n\nexport function normalizeEmail(email: string): string | null {\n  if (!email || typeof email !== 'string') return null;\n  const normalized = email.trim().toLowerCase();\n  if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(normalized)) return null;\n  return normalized.length > 0 ? normalized : null;\n}\n\nexport function hashEmail(email: string): string | null {\n  const normalized = normalizeEmail(email);\n  if (!normalized) return null;\n  return createHash('sha256').update(normalized).digest('hex');\n}\n\nexport function buildLicensePayload(opts: {\n  licenseKey: string;\n  tier: Tier;\n  isFounder: boolean;\n  issued: string;\n  emailHash?: string | null;\n}): LicensePayload {\n  if (!opts.licenseKey || typeof opts.licenseKey !== 'string') {\n    throw new Error('licenseKey is required and must be a string');\n  }\n  if (!opts.tier || typeof opts.tier !== 'string') {\n    throw new Error('tier is required and must be a string');\n  }\n  if (!opts.issued || typeof opts.issued !== 'string') {\n    throw new Error('issued is required and must be a string');\n  }\n\n  const payload: LicensePayload = {\n    licenseKey: opts.licenseKey,\n    tier: opts.tier,\n    isFounder: Boolean(opts.isFounder),\n    issued: opts.issued,\n  };\n  if (opts.emailHash) {\n    payload.emailHash = opts.emailHash;\n  }\n  return payload;\n}\n","/**\n * Build a complete signed registry from a flat entries map.\n *\n * The registry signature covers ONLY the entries — _metadata is excluded.\n * QAA's deployed validator destructures `_metadata` out before verifying,\n * so any change to what's signed will break compatibility.\n */\n\nimport { computeHash, signPayload, stableStringify } from './signing.js';\nimport type { Registry, SignedRegistry } from './types.js';\n\nexport function buildSignedRegistry(\n  entries: Registry,\n  privateKeyPem: string,\n  keyId = 'default',\n): SignedRegistry {\n  const now = new Date().toISOString();\n  const entriesStr = stableStringify(entries);\n  const registrySignature = signPayload(entries, privateKeyPem);\n  const hash = computeHash(entriesStr);\n\n  return {\n    _metadata: {\n      version: '1.0',\n      created: now,\n      lastUpdate: now,\n      description: 'License registry — populated by fulfillment webhook',\n      algorithm: 'rsa-sha256',\n      keyId,\n      registrySignature,\n      hash,\n      totalLicenses: Object.keys(entries).length,\n    },\n    ...entries,\n  };\n}\n","/**\n * Pure validation helpers — no I/O, no caching, no env.\n *\n * Both QA Architect's CLI and claude-kit-pro's MCP server use these\n * to verify a registry response. Anything that touches disk, network,\n * or process.env stays in the consuming product. This is the seam\n * that prevents the two validators from drifting apart.\n */\n\nimport { buildLicensePayload } from './payload.js';\nimport { computeHash, stableStringify, timingSafeStringEqual, verifyPayload } from './signing.js';\nimport type { RegistryEntry, SignedRegistry } from './types.js';\n\nexport interface ValidatedEntry {\n  valid: true;\n  tier: RegistryEntry['tier'];\n  isFounder: boolean;\n  customerId: string;\n  keyId: string;\n}\n\nexport interface ValidationFailure {\n  valid: false;\n  error: string;\n}\n\nexport type ValidationResult = ValidatedEntry | ValidationFailure;\n\n/**\n * Verify a single registry entry against its embedded signature.\n * Optionally check the user's email hash against the entry's emailHash.\n *\n * Mirrors QAA's validateLicense() field-set exactly:\n *   payload = { licenseKey, tier, isFounder, issued, emailHash? }\n */\nexport function validateRegistryEntry(opts: {\n  licenseKey: string;\n  entry: RegistryEntry;\n  publicKeyPem: string;\n  /** If supplied, must match entry.emailHash (timing-safe). */\n  userEmailHash?: string;\n}): ValidationResult {\n  const { licenseKey, entry, publicKeyPem, userEmailHash } = opts;\n\n  if (entry.emailHash && userEmailHash && !timingSafeStringEqual(userEmailHash, entry.emailHash)) {\n    return { valid: false, error: 'Email address does not match license registration' };\n  }\n\n  const payload = buildLicensePayload({\n    licenseKey,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    issued: entry.issued,\n    emailHash: entry.emailHash,\n  });\n\n  if (!verifyPayload(payload, entry.signature, publicKeyPem)) {\n    return { valid: false, error: 'License entry signature verification failed' };\n  }\n\n  return {\n    valid: true,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    customerId: entry.customerId,\n    keyId: entry.keyId,\n  };\n}\n\n/**\n * Verify a complete signed registry: registry-level signature + hash check.\n * Returns the entries map (with _metadata stripped) on success, throws on failure.\n *\n * Throws (rather than returning a result) because a registry signature failure\n * should halt validation entirely — clients should not fall back to entries\n * from an unverified registry.\n */\nexport function verifyRegistryMetadata(\n  signedRegistry: SignedRegistry,\n  publicKeyPem: string,\n): Record<string, RegistryEntry> {\n  const { _metadata, ...entries } = signedRegistry;\n\n  if (!_metadata?.registrySignature) {\n    throw new Error('Registry missing _metadata.registrySignature');\n  }\n\n  if (!verifyPayload(entries, _metadata.registrySignature, publicKeyPem)) {\n    throw new Error('Registry signature verification failed');\n  }\n\n  if (_metadata.hash) {\n    const computed = computeHash(stableStringify(entries));\n    if (!timingSafeStringEqual(computed, _metadata.hash)) {\n      throw new Error('Registry hash mismatch');\n    }\n  }\n\n  return entries as Record<string, RegistryEntry>;\n}\n","/**\n * Per-product license key format.\n *\n * QAA-XXXX-XXXX-XXXX-XXXX, CKIT-XXXX-XXXX-XXXX-XXXX, etc.\n * One factory so every product validates the same way.\n */\n\nexport function licenseKeyPattern(prefix: string): RegExp {\n  if (!/^[A-Z0-9]+$/.test(prefix)) {\n    throw new Error(`Prefix must be uppercase alphanumeric: ${prefix}`);\n  }\n  return new RegExp(`^${prefix}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$`);\n}\n\nexport function isValidLicenseKey(key: string, prefix: string): boolean {\n  return licenseKeyPattern(prefix).test(key.trim().toUpperCase());\n}\n\nexport function normalizeLicenseKey(key: string): string {\n  return key.trim().toUpperCase();\n}\n"],"mappings":"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","names":["cryptoSign","cryptoVerify","import_crypto"]}

package/dist/index.d.cts

@@ -17,7 +17,7 @@ declare function computeHash(data: string): string;
 declare function timingSafeStringEqual(a: string, b: string): boolean;
 
 /**
- * Core types for BuildProven license payloads.
+ * Core types for license payloads.
  *
  * IMPORTANT: changing the shape of LicensePayload or RegistryEntry
  * breaks signature verification across every product in the field.

package/dist/index.d.ts

@@ -17,7 +17,7 @@ declare function computeHash(data: string): string;
 declare function timingSafeStringEqual(a: string, b: string): boolean;
 
 /**
- * Core types for BuildProven license payloads.
+ * Core types for license payloads.
  *
  * IMPORTANT: changing the shape of LicensePayload or RegistryEntry
  * breaks signature verification across every product in the field.

package/dist/index.js

@@ -87,7 +87,7 @@ function buildSignedRegistry(entries, privateKeyPem, keyId = "default") {
       version: "1.0",
       created: now,
       lastUpdate: now,
-      description: "BuildProven license registry \u2014 populated by fulfillment webhook",
+      description: "License registry \u2014 populated by fulfillment webhook",
       algorithm: "rsa-sha256",
       keyId,
       registrySignature,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/signing.ts","../src/payload.ts","../src/registry.ts","../src/validator.ts","../src/key-format.ts"],"sourcesContent":["/**\n * Deterministic stringify + RSA-SHA256 sign/verify primitives.\n *\n * stableStringify must produce byte-identical output to QA Architect's\n * shipped lib/license-signing.js — the deployed CLI in customers' hands\n * uses that exact algorithm. Any divergence here breaks every QAA license\n * issued to date.\n */\n\nimport { sign as cryptoSign, verify as cryptoVerify, createHash } from 'crypto';\n\nexport function stableStringify(value: unknown, seen: WeakSet<object> = new WeakSet()): string {\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value);\n  }\n  if (seen.has(value as object)) {\n    throw new Error('Circular reference detected in payload - cannot serialize');\n  }\n  seen.add(value as object);\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, seen)).join(',')}]`;\n  }\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  const entries = keys.map(\n    (key) =>\n      `${JSON.stringify(key)}:${stableStringify((value as Record<string, unknown>)[key], seen)}`,\n  );\n  return `{${entries.join(',')}}`;\n}\n\nexport function signPayload(payload: unknown, privateKeyPem: string): string {\n  const data = Buffer.from(stableStringify(payload));\n  return cryptoSign(null, data, privateKeyPem).toString('base64');\n}\n\nexport function verifyPayload(payload: unknown, signature: string, publicKeyPem: string): boolean {\n  try {\n    const data = Buffer.from(stableStringify(payload));\n    return cryptoVerify(null, data, publicKeyPem, Buffer.from(signature, 'base64'));\n  } catch {\n    return false;\n  }\n}\n\nexport function computeHash(data: string): string {\n  return createHash('sha256').update(data).digest('hex');\n}\n\n/**\n * Constant-time string comparison. Same length precondition is checked\n * outside the comparison loop to avoid leaking length info.\n */\nexport function timingSafeStringEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) {\n    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n  return diff === 0;\n}\n","/**\n * Email normalization, hashing, and license payload construction.\n *\n * buildLicensePayload is the contract the fulfillment service signs against\n * and that every client must rebuild bit-for-bit before verification. Adding\n * fields here = breaking change.\n */\n\nimport { createHash } from 'crypto';\nimport type { LicensePayload, Tier } from './types.js';\n\nexport function normalizeEmail(email: string): string | null {\n  if (!email || typeof email !== 'string') return null;\n  const normalized = email.trim().toLowerCase();\n  if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(normalized)) return null;\n  return normalized.length > 0 ? normalized : null;\n}\n\nexport function hashEmail(email: string): string | null {\n  const normalized = normalizeEmail(email);\n  if (!normalized) return null;\n  return createHash('sha256').update(normalized).digest('hex');\n}\n\nexport function buildLicensePayload(opts: {\n  licenseKey: string;\n  tier: Tier;\n  isFounder: boolean;\n  issued: string;\n  emailHash?: string | null;\n}): LicensePayload {\n  if (!opts.licenseKey || typeof opts.licenseKey !== 'string') {\n    throw new Error('licenseKey is required and must be a string');\n  }\n  if (!opts.tier || typeof opts.tier !== 'string') {\n    throw new Error('tier is required and must be a string');\n  }\n  if (!opts.issued || typeof opts.issued !== 'string') {\n    throw new Error('issued is required and must be a string');\n  }\n\n  const payload: LicensePayload = {\n    licenseKey: opts.licenseKey,\n    tier: opts.tier,\n    isFounder: Boolean(opts.isFounder),\n    issued: opts.issued,\n  };\n  if (opts.emailHash) {\n    payload.emailHash = opts.emailHash;\n  }\n  return payload;\n}\n","/**\n * Build a complete signed registry from a flat entries map.\n *\n * The registry signature covers ONLY the entries — _metadata is excluded.\n * QAA's deployed validator destructures `_metadata` out before verifying,\n * so any change to what's signed will break compatibility.\n */\n\nimport { computeHash, signPayload, stableStringify } from './signing.js';\nimport type { Registry, SignedRegistry } from './types.js';\n\nexport function buildSignedRegistry(\n  entries: Registry,\n  privateKeyPem: string,\n  keyId = 'default',\n): SignedRegistry {\n  const now = new Date().toISOString();\n  const entriesStr = stableStringify(entries);\n  const registrySignature = signPayload(entries, privateKeyPem);\n  const hash = computeHash(entriesStr);\n\n  return {\n    _metadata: {\n      version: '1.0',\n      created: now,\n      lastUpdate: now,\n      description: 'BuildProven license registry — populated by fulfillment webhook',\n      algorithm: 'rsa-sha256',\n      keyId,\n      registrySignature,\n      hash,\n      totalLicenses: Object.keys(entries).length,\n    },\n    ...entries,\n  };\n}\n","/**\n * Pure validation helpers — no I/O, no caching, no env.\n *\n * Both QA Architect's CLI and claude-kit-pro's MCP server use these\n * to verify a registry response. Anything that touches disk, network,\n * or process.env stays in the consuming product. This is the seam\n * that prevents the two validators from drifting apart.\n */\n\nimport { buildLicensePayload } from './payload.js';\nimport { computeHash, stableStringify, timingSafeStringEqual, verifyPayload } from './signing.js';\nimport type { RegistryEntry, SignedRegistry } from './types.js';\n\nexport interface ValidatedEntry {\n  valid: true;\n  tier: RegistryEntry['tier'];\n  isFounder: boolean;\n  customerId: string;\n  keyId: string;\n}\n\nexport interface ValidationFailure {\n  valid: false;\n  error: string;\n}\n\nexport type ValidationResult = ValidatedEntry | ValidationFailure;\n\n/**\n * Verify a single registry entry against its embedded signature.\n * Optionally check the user's email hash against the entry's emailHash.\n *\n * Mirrors QAA's validateLicense() field-set exactly:\n *   payload = { licenseKey, tier, isFounder, issued, emailHash? }\n */\nexport function validateRegistryEntry(opts: {\n  licenseKey: string;\n  entry: RegistryEntry;\n  publicKeyPem: string;\n  /** If supplied, must match entry.emailHash (timing-safe). */\n  userEmailHash?: string;\n}): ValidationResult {\n  const { licenseKey, entry, publicKeyPem, userEmailHash } = opts;\n\n  if (entry.emailHash && userEmailHash && !timingSafeStringEqual(userEmailHash, entry.emailHash)) {\n    return { valid: false, error: 'Email address does not match license registration' };\n  }\n\n  const payload = buildLicensePayload({\n    licenseKey,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    issued: entry.issued,\n    emailHash: entry.emailHash,\n  });\n\n  if (!verifyPayload(payload, entry.signature, publicKeyPem)) {\n    return { valid: false, error: 'License entry signature verification failed' };\n  }\n\n  return {\n    valid: true,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    customerId: entry.customerId,\n    keyId: entry.keyId,\n  };\n}\n\n/**\n * Verify a complete signed registry: registry-level signature + hash check.\n * Returns the entries map (with _metadata stripped) on success, throws on failure.\n *\n * Throws (rather than returning a result) because a registry signature failure\n * should halt validation entirely — clients should not fall back to entries\n * from an unverified registry.\n */\nexport function verifyRegistryMetadata(\n  signedRegistry: SignedRegistry,\n  publicKeyPem: string,\n): Record<string, RegistryEntry> {\n  const { _metadata, ...entries } = signedRegistry;\n\n  if (!_metadata?.registrySignature) {\n    throw new Error('Registry missing _metadata.registrySignature');\n  }\n\n  if (!verifyPayload(entries, _metadata.registrySignature, publicKeyPem)) {\n    throw new Error('Registry signature verification failed');\n  }\n\n  if (_metadata.hash) {\n    const computed = computeHash(stableStringify(entries));\n    if (!timingSafeStringEqual(computed, _metadata.hash)) {\n      throw new Error('Registry hash mismatch');\n    }\n  }\n\n  return entries as Record<string, RegistryEntry>;\n}\n","/**\n * Per-product license key format.\n *\n * QAA-XXXX-XXXX-XXXX-XXXX, CKIT-XXXX-XXXX-XXXX-XXXX, etc.\n * One factory so every product validates the same way.\n */\n\nexport function licenseKeyPattern(prefix: string): RegExp {\n  if (!/^[A-Z0-9]+$/.test(prefix)) {\n    throw new Error(`Prefix must be uppercase alphanumeric: ${prefix}`);\n  }\n  return new RegExp(`^${prefix}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$`);\n}\n\nexport function isValidLicenseKey(key: string, prefix: string): boolean {\n  return licenseKeyPattern(prefix).test(key.trim().toUpperCase());\n}\n\nexport function normalizeLicenseKey(key: string): string {\n  return key.trim().toUpperCase();\n}\n"],"mappings":";AASA,SAAS,QAAQ,YAAY,UAAU,cAAc,kBAAkB;AAEhE,SAAS,gBAAgB,OAAgB,OAAwB,oBAAI,QAAQ,GAAW;AAC7F,MAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;AAC/C,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B;AACA,MAAI,KAAK,IAAI,KAAe,GAAG;AAC7B,UAAM,IAAI,MAAM,2DAA2D;AAAA,EAC7E;AACA,OAAK,IAAI,KAAe;AAExB,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,IAAI,MAAM,IAAI,CAAC,SAAS,gBAAgB,MAAM,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC;AAAA,EACvE;AACA,QAAM,OAAO,OAAO,KAAK,KAAgC,EAAE,KAAK;AAChE,QAAM,UAAU,KAAK;AAAA,IACnB,CAAC,QACC,GAAG,KAAK,UAAU,GAAG,CAAC,IAAI,gBAAiB,MAAkC,GAAG,GAAG,IAAI,CAAC;AAAA,EAC5F;AACA,SAAO,IAAI,QAAQ,KAAK,GAAG,CAAC;AAC9B;AAEO,SAAS,YAAY,SAAkB,eAA+B;AAC3E,QAAM,OAAO,OAAO,KAAK,gBAAgB,OAAO,CAAC;AACjD,SAAO,WAAW,MAAM,MAAM,aAAa,EAAE,SAAS,QAAQ;AAChE;AAEO,SAAS,cAAc,SAAkB,WAAmB,cAA+B;AAChG,MAAI;AACF,UAAM,OAAO,OAAO,KAAK,gBAAgB,OAAO,CAAC;AACjD,WAAO,aAAa,MAAM,MAAM,cAAc,OAAO,KAAK,WAAW,QAAQ,CAAC;AAAA,EAChF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,YAAY,MAAsB;AAChD,SAAO,WAAW,QAAQ,EAAE,OAAO,IAAI,EAAE,OAAO,KAAK;AACvD;AAMO,SAAS,sBAAsB,GAAW,GAAoB;AACnE,MAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,MAAI,OAAO;AACX,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,YAAQ,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC;AAAA,EAC1C;AACA,SAAO,SAAS;AAClB;;;ACpDA,SAAS,cAAAA,mBAAkB;AAGpB,SAAS,eAAe,OAA8B;AAC3D,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;AAChD,QAAM,aAAa,MAAM,KAAK,EAAE,YAAY;AAC5C,MAAI,CAAC,6BAA6B,KAAK,UAAU,EAAG,QAAO;AAC3D,SAAO,WAAW,SAAS,IAAI,aAAa;AAC9C;AAEO,SAAS,UAAU,OAA8B;AACtD,QAAM,aAAa,eAAe,KAAK;AACvC,MAAI,CAAC,WAAY,QAAO;AACxB,SAAOA,YAAW,QAAQ,EAAE,OAAO,UAAU,EAAE,OAAO,KAAK;AAC7D;AAEO,SAAS,oBAAoB,MAMjB;AACjB,MAAI,CAAC,KAAK,cAAc,OAAO,KAAK,eAAe,UAAU;AAC3D,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,MAAI,CAAC,KAAK,QAAQ,OAAO,KAAK,SAAS,UAAU;AAC/C,UAAM,IAAI,MAAM,uCAAuC;AAAA,EACzD;AACA,MAAI,CAAC,KAAK,UAAU,OAAO,KAAK,WAAW,UAAU;AACnD,UAAM,IAAI,MAAM,yCAAyC;AAAA,EAC3D;AAEA,QAAM,UAA0B;AAAA,IAC9B,YAAY,KAAK;AAAA,IACjB,MAAM,KAAK;AAAA,IACX,WAAW,QAAQ,KAAK,SAAS;AAAA,IACjC,QAAQ,KAAK;AAAA,EACf;AACA,MAAI,KAAK,WAAW;AAClB,YAAQ,YAAY,KAAK;AAAA,EAC3B;AACA,SAAO;AACT;;;ACxCO,SAAS,oBACd,SACA,eACA,QAAQ,WACQ;AAChB,QAAM,OAAM,oBAAI,KAAK,GAAE,YAAY;AACnC,QAAM,aAAa,gBAAgB,OAAO;AAC1C,QAAM,oBAAoB,YAAY,SAAS,aAAa;AAC5D,QAAM,OAAO,YAAY,UAAU;AAEnC,SAAO;AAAA,IACL,WAAW;AAAA,MACT,SAAS;AAAA,MACT,SAAS;AAAA,MACT,YAAY;AAAA,MACZ,aAAa;AAAA,MACb,WAAW;AAAA,MACX;AAAA,MACA;AAAA,MACA;AAAA,MACA,eAAe,OAAO,KAAK,OAAO,EAAE;AAAA,IACtC;AAAA,IACA,GAAG;AAAA,EACL;AACF;;;ACAO,SAAS,sBAAsB,MAMjB;AACnB,QAAM,EAAE,YAAY,OAAO,cAAc,cAAc,IAAI;AAE3D,MAAI,MAAM,aAAa,iBAAiB,CAAC,sBAAsB,eAAe,MAAM,SAAS,GAAG;AAC9F,WAAO,EAAE,OAAO,OAAO,OAAO,oDAAoD;AAAA,EACpF;AAEA,QAAM,UAAU,oBAAoB;AAAA,IAClC;AAAA,IACA,MAAM,MAAM;AAAA,IACZ,WAAW,MAAM;AAAA,IACjB,QAAQ,MAAM;AAAA,IACd,WAAW,MAAM;AAAA,EACnB,CAAC;AAED,MAAI,CAAC,cAAc,SAAS,MAAM,WAAW,YAAY,GAAG;AAC1D,WAAO,EAAE,OAAO,OAAO,OAAO,8CAA8C;AAAA,EAC9E;AAEA,SAAO;AAAA,IACL,OAAO;AAAA,IACP,MAAM,MAAM;AAAA,IACZ,WAAW,MAAM;AAAA,IACjB,YAAY,MAAM;AAAA,IAClB,OAAO,MAAM;AAAA,EACf;AACF;AAUO,SAAS,uBACd,gBACA,cAC+B;AAC/B,QAAM,EAAE,WAAW,GAAG,QAAQ,IAAI;AAElC,MAAI,CAAC,WAAW,mBAAmB;AACjC,UAAM,IAAI,MAAM,8CAA8C;AAAA,EAChE;AAEA,MAAI,CAAC,cAAc,SAAS,UAAU,mBAAmB,YAAY,GAAG;AACtE,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC1D;AAEA,MAAI,UAAU,MAAM;AAClB,UAAM,WAAW,YAAY,gBAAgB,OAAO,CAAC;AACrD,QAAI,CAAC,sBAAsB,UAAU,UAAU,IAAI,GAAG;AACpD,YAAM,IAAI,MAAM,wBAAwB;AAAA,IAC1C;AAAA,EACF;AAEA,SAAO;AACT;;;AC5FO,SAAS,kBAAkB,QAAwB;AACxD,MAAI,CAAC,cAAc,KAAK,MAAM,GAAG;AAC/B,UAAM,IAAI,MAAM,0CAA0C,MAAM,EAAE;AAAA,EACpE;AACA,SAAO,IAAI,OAAO,IAAI,MAAM,mDAAmD;AACjF;AAEO,SAAS,kBAAkB,KAAa,QAAyB;AACtE,SAAO,kBAAkB,MAAM,EAAE,KAAK,IAAI,KAAK,EAAE,YAAY,CAAC;AAChE;AAEO,SAAS,oBAAoB,KAAqB;AACvD,SAAO,IAAI,KAAK,EAAE,YAAY;AAChC;","names":["createHash"]}
+{"version":3,"sources":["../src/signing.ts","../src/payload.ts","../src/registry.ts","../src/validator.ts","../src/key-format.ts"],"sourcesContent":["/**\n * Deterministic stringify + RSA-SHA256 sign/verify primitives.\n *\n * stableStringify must produce byte-identical output to QA Architect's\n * shipped lib/license-signing.js — the deployed CLI in customers' hands\n * uses that exact algorithm. Any divergence here breaks every QAA license\n * issued to date.\n */\n\nimport { sign as cryptoSign, verify as cryptoVerify, createHash } from 'crypto';\n\nexport function stableStringify(value: unknown, seen: WeakSet<object> = new WeakSet()): string {\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value);\n  }\n  if (seen.has(value as object)) {\n    throw new Error('Circular reference detected in payload - cannot serialize');\n  }\n  seen.add(value as object);\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, seen)).join(',')}]`;\n  }\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  const entries = keys.map(\n    (key) =>\n      `${JSON.stringify(key)}:${stableStringify((value as Record<string, unknown>)[key], seen)}`,\n  );\n  return `{${entries.join(',')}}`;\n}\n\nexport function signPayload(payload: unknown, privateKeyPem: string): string {\n  const data = Buffer.from(stableStringify(payload));\n  return cryptoSign(null, data, privateKeyPem).toString('base64');\n}\n\nexport function verifyPayload(payload: unknown, signature: string, publicKeyPem: string): boolean {\n  try {\n    const data = Buffer.from(stableStringify(payload));\n    return cryptoVerify(null, data, publicKeyPem, Buffer.from(signature, 'base64'));\n  } catch {\n    return false;\n  }\n}\n\nexport function computeHash(data: string): string {\n  return createHash('sha256').update(data).digest('hex');\n}\n\n/**\n * Constant-time string comparison. Same length precondition is checked\n * outside the comparison loop to avoid leaking length info.\n */\nexport function timingSafeStringEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) {\n    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n  return diff === 0;\n}\n","/**\n * Email normalization, hashing, and license payload construction.\n *\n * buildLicensePayload is the contract the fulfillment service signs against\n * and that every client must rebuild bit-for-bit before verification. Adding\n * fields here = breaking change.\n */\n\nimport { createHash } from 'crypto';\nimport type { LicensePayload, Tier } from './types.js';\n\nexport function normalizeEmail(email: string): string | null {\n  if (!email || typeof email !== 'string') return null;\n  const normalized = email.trim().toLowerCase();\n  if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(normalized)) return null;\n  return normalized.length > 0 ? normalized : null;\n}\n\nexport function hashEmail(email: string): string | null {\n  const normalized = normalizeEmail(email);\n  if (!normalized) return null;\n  return createHash('sha256').update(normalized).digest('hex');\n}\n\nexport function buildLicensePayload(opts: {\n  licenseKey: string;\n  tier: Tier;\n  isFounder: boolean;\n  issued: string;\n  emailHash?: string | null;\n}): LicensePayload {\n  if (!opts.licenseKey || typeof opts.licenseKey !== 'string') {\n    throw new Error('licenseKey is required and must be a string');\n  }\n  if (!opts.tier || typeof opts.tier !== 'string') {\n    throw new Error('tier is required and must be a string');\n  }\n  if (!opts.issued || typeof opts.issued !== 'string') {\n    throw new Error('issued is required and must be a string');\n  }\n\n  const payload: LicensePayload = {\n    licenseKey: opts.licenseKey,\n    tier: opts.tier,\n    isFounder: Boolean(opts.isFounder),\n    issued: opts.issued,\n  };\n  if (opts.emailHash) {\n    payload.emailHash = opts.emailHash;\n  }\n  return payload;\n}\n","/**\n * Build a complete signed registry from a flat entries map.\n *\n * The registry signature covers ONLY the entries — _metadata is excluded.\n * QAA's deployed validator destructures `_metadata` out before verifying,\n * so any change to what's signed will break compatibility.\n */\n\nimport { computeHash, signPayload, stableStringify } from './signing.js';\nimport type { Registry, SignedRegistry } from './types.js';\n\nexport function buildSignedRegistry(\n  entries: Registry,\n  privateKeyPem: string,\n  keyId = 'default',\n): SignedRegistry {\n  const now = new Date().toISOString();\n  const entriesStr = stableStringify(entries);\n  const registrySignature = signPayload(entries, privateKeyPem);\n  const hash = computeHash(entriesStr);\n\n  return {\n    _metadata: {\n      version: '1.0',\n      created: now,\n      lastUpdate: now,\n      description: 'License registry — populated by fulfillment webhook',\n      algorithm: 'rsa-sha256',\n      keyId,\n      registrySignature,\n      hash,\n      totalLicenses: Object.keys(entries).length,\n    },\n    ...entries,\n  };\n}\n","/**\n * Pure validation helpers — no I/O, no caching, no env.\n *\n * Both QA Architect's CLI and claude-kit-pro's MCP server use these\n * to verify a registry response. Anything that touches disk, network,\n * or process.env stays in the consuming product. This is the seam\n * that prevents the two validators from drifting apart.\n */\n\nimport { buildLicensePayload } from './payload.js';\nimport { computeHash, stableStringify, timingSafeStringEqual, verifyPayload } from './signing.js';\nimport type { RegistryEntry, SignedRegistry } from './types.js';\n\nexport interface ValidatedEntry {\n  valid: true;\n  tier: RegistryEntry['tier'];\n  isFounder: boolean;\n  customerId: string;\n  keyId: string;\n}\n\nexport interface ValidationFailure {\n  valid: false;\n  error: string;\n}\n\nexport type ValidationResult = ValidatedEntry | ValidationFailure;\n\n/**\n * Verify a single registry entry against its embedded signature.\n * Optionally check the user's email hash against the entry's emailHash.\n *\n * Mirrors QAA's validateLicense() field-set exactly:\n *   payload = { licenseKey, tier, isFounder, issued, emailHash? }\n */\nexport function validateRegistryEntry(opts: {\n  licenseKey: string;\n  entry: RegistryEntry;\n  publicKeyPem: string;\n  /** If supplied, must match entry.emailHash (timing-safe). */\n  userEmailHash?: string;\n}): ValidationResult {\n  const { licenseKey, entry, publicKeyPem, userEmailHash } = opts;\n\n  if (entry.emailHash && userEmailHash && !timingSafeStringEqual(userEmailHash, entry.emailHash)) {\n    return { valid: false, error: 'Email address does not match license registration' };\n  }\n\n  const payload = buildLicensePayload({\n    licenseKey,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    issued: entry.issued,\n    emailHash: entry.emailHash,\n  });\n\n  if (!verifyPayload(payload, entry.signature, publicKeyPem)) {\n    return { valid: false, error: 'License entry signature verification failed' };\n  }\n\n  return {\n    valid: true,\n    tier: entry.tier,\n    isFounder: entry.isFounder,\n    customerId: entry.customerId,\n    keyId: entry.keyId,\n  };\n}\n\n/**\n * Verify a complete signed registry: registry-level signature + hash check.\n * Returns the entries map (with _metadata stripped) on success, throws on failure.\n *\n * Throws (rather than returning a result) because a registry signature failure\n * should halt validation entirely — clients should not fall back to entries\n * from an unverified registry.\n */\nexport function verifyRegistryMetadata(\n  signedRegistry: SignedRegistry,\n  publicKeyPem: string,\n): Record<string, RegistryEntry> {\n  const { _metadata, ...entries } = signedRegistry;\n\n  if (!_metadata?.registrySignature) {\n    throw new Error('Registry missing _metadata.registrySignature');\n  }\n\n  if (!verifyPayload(entries, _metadata.registrySignature, publicKeyPem)) {\n    throw new Error('Registry signature verification failed');\n  }\n\n  if (_metadata.hash) {\n    const computed = computeHash(stableStringify(entries));\n    if (!timingSafeStringEqual(computed, _metadata.hash)) {\n      throw new Error('Registry hash mismatch');\n    }\n  }\n\n  return entries as Record<string, RegistryEntry>;\n}\n","/**\n * Per-product license key format.\n *\n * QAA-XXXX-XXXX-XXXX-XXXX, CKIT-XXXX-XXXX-XXXX-XXXX, etc.\n * One factory so every product validates the same way.\n */\n\nexport function licenseKeyPattern(prefix: string): RegExp {\n  if (!/^[A-Z0-9]+$/.test(prefix)) {\n    throw new Error(`Prefix must be uppercase alphanumeric: ${prefix}`);\n  }\n  return new RegExp(`^${prefix}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$`);\n}\n\nexport function isValidLicenseKey(key: string, prefix: string): boolean {\n  return licenseKeyPattern(prefix).test(key.trim().toUpperCase());\n}\n\nexport function normalizeLicenseKey(key: string): string {\n  return key.trim().toUpperCase();\n}\n"],"mappings":"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","names":["createHash"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildproven/license-core",
-  "version": "1.0.0",
+  "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",
@@ -42,7 +43,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/buildproven/buildproven-license-core.git"
+    "url": "https://github.com/buildproven/license-core.git"
   },
   "license": "MIT",
   "keywords": [