@buildproven/license-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibe Build Lab LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @buildproven/license-core
+
+Shared license signing & verification primitives for BuildProven products.
+
+## What this is
+
+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.
+
+Used by:
+
+- `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
+
+## Why it exists
+
+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.
+
+## API
+
+```ts
+import {
+  // Crypto primitives
+  stableStringify,
+  signPayload,
+  verifyPayload,
+  computeHash,
+  timingSafeStringEqual,
+
+  // Payload construction
+  normalizeEmail,
+  hashEmail,
+  buildLicensePayload,
+
+  // Registry
+  buildSignedRegistry,
+
+  // Validation helpers (pure — no I/O)
+  validateRegistryEntry,
+  verifyRegistryMetadata,
+
+  // Key format
+  licenseKeyPattern,
+  isValidLicenseKey,
+  normalizeLicenseKey,
+} from '@buildproven/license-core';
+```
+
+## 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.
+
+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.
+
+## Install
+
+```bash
+npm install @buildproven/license-core
+```
+
+## Develop
+
+```bash
+npm install
+npm test       # vitest, includes golden-vector test against QAA's deployed code
+npm run build  # tsup → dist/
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildLicensePayload: () => buildLicensePayload,
+  buildSignedRegistry: () => buildSignedRegistry,
+  computeHash: () => computeHash,
+  hashEmail: () => hashEmail,
+  isValidLicenseKey: () => isValidLicenseKey,
+  licenseKeyPattern: () => licenseKeyPattern,
+  normalizeEmail: () => normalizeEmail,
+  normalizeLicenseKey: () => normalizeLicenseKey,
+  signPayload: () => signPayload,
+  stableStringify: () => stableStringify,
+  timingSafeStringEqual: () => timingSafeStringEqual,
+  validateRegistryEntry: () => validateRegistryEntry,
+  verifyPayload: () => verifyPayload,
+  verifyRegistryMetadata: () => verifyRegistryMetadata
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/signing.ts
+var import_crypto = require("crypto");
+function stableStringify(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (seen.has(value)) {
+    throw new Error("Circular reference detected in payload - cannot serialize");
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const entries = keys.map(
+    (key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen)}`
+  );
+  return `{${entries.join(",")}}`;
+}
+function signPayload(payload, privateKeyPem) {
+  const data = Buffer.from(stableStringify(payload));
+  return (0, import_crypto.sign)(null, data, privateKeyPem).toString("base64");
+}
+function verifyPayload(payload, signature, publicKeyPem) {
+  try {
+    const data = Buffer.from(stableStringify(payload));
+    return (0, import_crypto.verify)(null, data, publicKeyPem, Buffer.from(signature, "base64"));
+  } catch {
+    return false;
+  }
+}
+function computeHash(data) {
+  return (0, import_crypto.createHash)("sha256").update(data).digest("hex");
+}
+function timingSafeStringEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// src/payload.ts
+var import_crypto2 = require("crypto");
+function normalizeEmail(email) {
+  if (!email || typeof email !== "string") return null;
+  const normalized = email.trim().toLowerCase();
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)) return null;
+  return normalized.length > 0 ? normalized : null;
+}
+function hashEmail(email) {
+  const normalized = normalizeEmail(email);
+  if (!normalized) return null;
+  return (0, import_crypto2.createHash)("sha256").update(normalized).digest("hex");
+}
+function buildLicensePayload(opts) {
+  if (!opts.licenseKey || typeof opts.licenseKey !== "string") {
+    throw new Error("licenseKey is required and must be a string");
+  }
+  if (!opts.tier || typeof opts.tier !== "string") {
+    throw new Error("tier is required and must be a string");
+  }
+  if (!opts.issued || typeof opts.issued !== "string") {
+    throw new Error("issued is required and must be a string");
+  }
+  const payload = {
+    licenseKey: opts.licenseKey,
+    tier: opts.tier,
+    isFounder: Boolean(opts.isFounder),
+    issued: opts.issued
+  };
+  if (opts.emailHash) {
+    payload.emailHash = opts.emailHash;
+  }
+  return payload;
+}
+
+// src/registry.ts
+function buildSignedRegistry(entries, privateKeyPem, keyId = "default") {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const entriesStr = stableStringify(entries);
+  const registrySignature = signPayload(entries, privateKeyPem);
+  const hash = computeHash(entriesStr);
+  return {
+    _metadata: {
+      version: "1.0",
+      created: now,
+      lastUpdate: now,
+      description: "BuildProven license registry \u2014 populated by fulfillment webhook",
+      algorithm: "rsa-sha256",
+      keyId,
+      registrySignature,
+      hash,
+      totalLicenses: Object.keys(entries).length
+    },
+    ...entries
+  };
+}
+
+// src/validator.ts
+function validateRegistryEntry(opts) {
+  const { licenseKey, entry, publicKeyPem, userEmailHash } = opts;
+  if (entry.emailHash && userEmailHash && !timingSafeStringEqual(userEmailHash, entry.emailHash)) {
+    return { valid: false, error: "Email address does not match license registration" };
+  }
+  const payload = buildLicensePayload({
+    licenseKey,
+    tier: entry.tier,
+    isFounder: entry.isFounder,
+    issued: entry.issued,
+    emailHash: entry.emailHash
+  });
+  if (!verifyPayload(payload, entry.signature, publicKeyPem)) {
+    return { valid: false, error: "License entry signature verification failed" };
+  }
+  return {
+    valid: true,
+    tier: entry.tier,
+    isFounder: entry.isFounder,
+    customerId: entry.customerId,
+    keyId: entry.keyId
+  };
+}
+function verifyRegistryMetadata(signedRegistry, publicKeyPem) {
+  const { _metadata, ...entries } = signedRegistry;
+  if (!_metadata?.registrySignature) {
+    throw new Error("Registry missing _metadata.registrySignature");
+  }
+  if (!verifyPayload(entries, _metadata.registrySignature, publicKeyPem)) {
+    throw new Error("Registry signature verification failed");
+  }
+  if (_metadata.hash) {
+    const computed = computeHash(stableStringify(entries));
+    if (!timingSafeStringEqual(computed, _metadata.hash)) {
+      throw new Error("Registry hash mismatch");
+    }
+  }
+  return entries;
+}
+
+// src/key-format.ts
+function licenseKeyPattern(prefix) {
+  if (!/^[A-Z0-9]+$/.test(prefix)) {
+    throw new Error(`Prefix must be uppercase alphanumeric: ${prefix}`);
+  }
+  return new RegExp(`^${prefix}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$`);
+}
+function isValidLicenseKey(key, prefix) {
+  return licenseKeyPattern(prefix).test(key.trim().toUpperCase());
+}
+function normalizeLicenseKey(key) {
+  return key.trim().toUpperCase();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildLicensePayload,
+  buildSignedRegistry,
+  computeHash,
+  hashEmail,
+  isValidLicenseKey,
+  licenseKeyPattern,
+  normalizeEmail,
+  normalizeLicenseKey,
+  signPayload,
+  stableStringify,
+  timingSafeStringEqual,
+  validateRegistryEntry,
+  verifyPayload,
+  verifyRegistryMetadata
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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"]}

package/dist/index.d.cts

@@ -0,0 +1,157 @@
+/**
+ * Deterministic stringify + RSA-SHA256 sign/verify primitives.
+ *
+ * stableStringify must produce byte-identical output to QA Architect's
+ * shipped lib/license-signing.js — the deployed CLI in customers' hands
+ * uses that exact algorithm. Any divergence here breaks every QAA license
+ * issued to date.
+ */
+declare function stableStringify(value: unknown, seen?: WeakSet<object>): string;
+declare function signPayload(payload: unknown, privateKeyPem: string): string;
+declare function verifyPayload(payload: unknown, signature: string, publicKeyPem: string): boolean;
+declare function computeHash(data: string): string;
+/**
+ * Constant-time string comparison. Same length precondition is checked
+ * outside the comparison loop to avoid leaking length info.
+ */
+declare function timingSafeStringEqual(a: string, b: string): boolean;
+
+/**
+ * Core types for BuildProven license payloads.
+ *
+ * IMPORTANT: changing the shape of LicensePayload or RegistryEntry
+ * breaks signature verification across every product in the field.
+ * Treat these as a frozen contract — bump schemaVersion + ship a new
+ * major instead of mutating.
+ */
+type Tier = 'FREE' | 'PRO';
+/**
+ * The payload that is RSA-signed for each license entry.
+ * Field set is FROZEN — see comment above.
+ */
+interface LicensePayload {
+    licenseKey: string;
+    tier: Tier;
+    isFounder: boolean;
+    issued: string;
+    /** Optional — only included when emailHash is non-null on the entry. */
+    emailHash?: string;
+}
+/**
+ * One row in the signed registry.
+ * Stored in Vercel KV by the fulfillment service, fetched + verified by clients.
+ */
+interface RegistryEntry {
+    tier: Tier;
+    isFounder: boolean;
+    issued: string;
+    emailHash: string | null;
+    /** RSA-SHA256 base64 signature of the LicensePayload above. */
+    signature: string;
+    customerId: string;
+    /** Identifies which keypair signed this entry — for rotation. */
+    keyId: string;
+}
+type Registry = Record<string, RegistryEntry>;
+interface RegistryMetadata {
+    version: string;
+    created: string;
+    lastUpdate: string;
+    description: string;
+    algorithm: string;
+    keyId: string;
+    /** RSA-SHA256 base64 signature over the entries (metadata excluded). */
+    registrySignature: string;
+    /** SHA-256 hex of stableStringify(entries). */
+    hash: string;
+    totalLicenses: number;
+}
+interface SignedRegistry {
+    _metadata: RegistryMetadata;
+    [licenseKey: string]: RegistryEntry | RegistryMetadata;
+}
+
+/**
+ * Email normalization, hashing, and license payload construction.
+ *
+ * buildLicensePayload is the contract the fulfillment service signs against
+ * and that every client must rebuild bit-for-bit before verification. Adding
+ * fields here = breaking change.
+ */
+
+declare function normalizeEmail(email: string): string | null;
+declare function hashEmail(email: string): string | null;
+declare function buildLicensePayload(opts: {
+    licenseKey: string;
+    tier: Tier;
+    isFounder: boolean;
+    issued: string;
+    emailHash?: string | null;
+}): LicensePayload;
+
+/**
+ * Build a complete signed registry from a flat entries map.
+ *
+ * The registry signature covers ONLY the entries — _metadata is excluded.
+ * QAA's deployed validator destructures `_metadata` out before verifying,
+ * so any change to what's signed will break compatibility.
+ */
+
+declare function buildSignedRegistry(entries: Registry, privateKeyPem: string, keyId?: string): SignedRegistry;
+
+/**
+ * Pure validation helpers — no I/O, no caching, no env.
+ *
+ * Both QA Architect's CLI and claude-kit-pro's MCP server use these
+ * to verify a registry response. Anything that touches disk, network,
+ * or process.env stays in the consuming product. This is the seam
+ * that prevents the two validators from drifting apart.
+ */
+
+interface ValidatedEntry {
+    valid: true;
+    tier: RegistryEntry['tier'];
+    isFounder: boolean;
+    customerId: string;
+    keyId: string;
+}
+interface ValidationFailure {
+    valid: false;
+    error: string;
+}
+type ValidationResult = ValidatedEntry | ValidationFailure;
+/**
+ * Verify a single registry entry against its embedded signature.
+ * Optionally check the user's email hash against the entry's emailHash.
+ *
+ * Mirrors QAA's validateLicense() field-set exactly:
+ *   payload = { licenseKey, tier, isFounder, issued, emailHash? }
+ */
+declare function validateRegistryEntry(opts: {
+    licenseKey: string;
+    entry: RegistryEntry;
+    publicKeyPem: string;
+    /** If supplied, must match entry.emailHash (timing-safe). */
+    userEmailHash?: string;
+}): ValidationResult;
+/**
+ * Verify a complete signed registry: registry-level signature + hash check.
+ * Returns the entries map (with _metadata stripped) on success, throws on failure.
+ *
+ * Throws (rather than returning a result) because a registry signature failure
+ * should halt validation entirely — clients should not fall back to entries
+ * from an unverified registry.
+ */
+declare function verifyRegistryMetadata(signedRegistry: SignedRegistry, publicKeyPem: string): Record<string, RegistryEntry>;
+
+/**
+ * Per-product license key format.
+ *
+ * QAA-XXXX-XXXX-XXXX-XXXX, CKIT-XXXX-XXXX-XXXX-XXXX, etc.
+ * One factory so every product validates the same way.
+ */
+declare function licenseKeyPattern(prefix: string): RegExp;
+declare function isValidLicenseKey(key: string, prefix: string): boolean;
+declare function normalizeLicenseKey(key: string): string;
+
+export { type LicensePayload, type Registry, type RegistryEntry, type RegistryMetadata, type SignedRegistry, type Tier, type ValidatedEntry, type ValidationFailure, type ValidationResult, buildLicensePayload, buildSignedRegistry, computeHash, hashEmail, isValidLicenseKey, licenseKeyPattern, normalizeEmail, normalizeLicenseKey, signPayload, stableStringify, timingSafeStringEqual, validateRegistryEntry, verifyPayload, verifyRegistryMetadata };

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Deterministic stringify + RSA-SHA256 sign/verify primitives.
+ *
+ * stableStringify must produce byte-identical output to QA Architect's
+ * shipped lib/license-signing.js — the deployed CLI in customers' hands
+ * uses that exact algorithm. Any divergence here breaks every QAA license
+ * issued to date.
+ */
+declare function stableStringify(value: unknown, seen?: WeakSet<object>): string;
+declare function signPayload(payload: unknown, privateKeyPem: string): string;
+declare function verifyPayload(payload: unknown, signature: string, publicKeyPem: string): boolean;
+declare function computeHash(data: string): string;
+/**
+ * Constant-time string comparison. Same length precondition is checked
+ * outside the comparison loop to avoid leaking length info.
+ */
+declare function timingSafeStringEqual(a: string, b: string): boolean;
+
+/**
+ * Core types for BuildProven license payloads.
+ *
+ * IMPORTANT: changing the shape of LicensePayload or RegistryEntry
+ * breaks signature verification across every product in the field.
+ * Treat these as a frozen contract — bump schemaVersion + ship a new
+ * major instead of mutating.
+ */
+type Tier = 'FREE' | 'PRO';
+/**
+ * The payload that is RSA-signed for each license entry.
+ * Field set is FROZEN — see comment above.
+ */
+interface LicensePayload {
+    licenseKey: string;
+    tier: Tier;
+    isFounder: boolean;
+    issued: string;
+    /** Optional — only included when emailHash is non-null on the entry. */
+    emailHash?: string;
+}
+/**
+ * One row in the signed registry.
+ * Stored in Vercel KV by the fulfillment service, fetched + verified by clients.
+ */
+interface RegistryEntry {
+    tier: Tier;
+    isFounder: boolean;
+    issued: string;
+    emailHash: string | null;
+    /** RSA-SHA256 base64 signature of the LicensePayload above. */
+    signature: string;
+    customerId: string;
+    /** Identifies which keypair signed this entry — for rotation. */
+    keyId: string;
+}
+type Registry = Record<string, RegistryEntry>;
+interface RegistryMetadata {
+    version: string;
+    created: string;
+    lastUpdate: string;
+    description: string;
+    algorithm: string;
+    keyId: string;
+    /** RSA-SHA256 base64 signature over the entries (metadata excluded). */
+    registrySignature: string;
+    /** SHA-256 hex of stableStringify(entries). */
+    hash: string;
+    totalLicenses: number;
+}
+interface SignedRegistry {
+    _metadata: RegistryMetadata;
+    [licenseKey: string]: RegistryEntry | RegistryMetadata;
+}
+
+/**
+ * Email normalization, hashing, and license payload construction.
+ *
+ * buildLicensePayload is the contract the fulfillment service signs against
+ * and that every client must rebuild bit-for-bit before verification. Adding
+ * fields here = breaking change.
+ */
+
+declare function normalizeEmail(email: string): string | null;
+declare function hashEmail(email: string): string | null;
+declare function buildLicensePayload(opts: {
+    licenseKey: string;
+    tier: Tier;
+    isFounder: boolean;
+    issued: string;
+    emailHash?: string | null;
+}): LicensePayload;
+
+/**
+ * Build a complete signed registry from a flat entries map.
+ *
+ * The registry signature covers ONLY the entries — _metadata is excluded.
+ * QAA's deployed validator destructures `_metadata` out before verifying,
+ * so any change to what's signed will break compatibility.
+ */
+
+declare function buildSignedRegistry(entries: Registry, privateKeyPem: string, keyId?: string): SignedRegistry;
+
+/**
+ * Pure validation helpers — no I/O, no caching, no env.
+ *
+ * Both QA Architect's CLI and claude-kit-pro's MCP server use these
+ * to verify a registry response. Anything that touches disk, network,
+ * or process.env stays in the consuming product. This is the seam
+ * that prevents the two validators from drifting apart.
+ */
+
+interface ValidatedEntry {
+    valid: true;
+    tier: RegistryEntry['tier'];
+    isFounder: boolean;
+    customerId: string;
+    keyId: string;
+}
+interface ValidationFailure {
+    valid: false;
+    error: string;
+}
+type ValidationResult = ValidatedEntry | ValidationFailure;
+/**
+ * Verify a single registry entry against its embedded signature.
+ * Optionally check the user's email hash against the entry's emailHash.
+ *
+ * Mirrors QAA's validateLicense() field-set exactly:
+ *   payload = { licenseKey, tier, isFounder, issued, emailHash? }
+ */
+declare function validateRegistryEntry(opts: {
+    licenseKey: string;
+    entry: RegistryEntry;
+    publicKeyPem: string;
+    /** If supplied, must match entry.emailHash (timing-safe). */
+    userEmailHash?: string;
+}): ValidationResult;
+/**
+ * Verify a complete signed registry: registry-level signature + hash check.
+ * Returns the entries map (with _metadata stripped) on success, throws on failure.
+ *
+ * Throws (rather than returning a result) because a registry signature failure
+ * should halt validation entirely — clients should not fall back to entries
+ * from an unverified registry.
+ */
+declare function verifyRegistryMetadata(signedRegistry: SignedRegistry, publicKeyPem: string): Record<string, RegistryEntry>;
+
+/**
+ * Per-product license key format.
+ *
+ * QAA-XXXX-XXXX-XXXX-XXXX, CKIT-XXXX-XXXX-XXXX-XXXX, etc.
+ * One factory so every product validates the same way.
+ */
+declare function licenseKeyPattern(prefix: string): RegExp;
+declare function isValidLicenseKey(key: string, prefix: string): boolean;
+declare function normalizeLicenseKey(key: string): string;
+
+export { type LicensePayload, type Registry, type RegistryEntry, type RegistryMetadata, type SignedRegistry, type Tier, type ValidatedEntry, type ValidationFailure, type ValidationResult, buildLicensePayload, buildSignedRegistry, computeHash, hashEmail, isValidLicenseKey, licenseKeyPattern, normalizeEmail, normalizeLicenseKey, signPayload, stableStringify, timingSafeStringEqual, validateRegistryEntry, verifyPayload, verifyRegistryMetadata };

package/dist/index.js

@@ -0,0 +1,171 @@
+// src/signing.ts
+import { sign as cryptoSign, verify as cryptoVerify, createHash } from "crypto";
+function stableStringify(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (seen.has(value)) {
+    throw new Error("Circular reference detected in payload - cannot serialize");
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const entries = keys.map(
+    (key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen)}`
+  );
+  return `{${entries.join(",")}}`;
+}
+function signPayload(payload, privateKeyPem) {
+  const data = Buffer.from(stableStringify(payload));
+  return cryptoSign(null, data, privateKeyPem).toString("base64");
+}
+function verifyPayload(payload, signature, publicKeyPem) {
+  try {
+    const data = Buffer.from(stableStringify(payload));
+    return cryptoVerify(null, data, publicKeyPem, Buffer.from(signature, "base64"));
+  } catch {
+    return false;
+  }
+}
+function computeHash(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+function timingSafeStringEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// src/payload.ts
+import { createHash as createHash2 } from "crypto";
+function normalizeEmail(email) {
+  if (!email || typeof email !== "string") return null;
+  const normalized = email.trim().toLowerCase();
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)) return null;
+  return normalized.length > 0 ? normalized : null;
+}
+function hashEmail(email) {
+  const normalized = normalizeEmail(email);
+  if (!normalized) return null;
+  return createHash2("sha256").update(normalized).digest("hex");
+}
+function buildLicensePayload(opts) {
+  if (!opts.licenseKey || typeof opts.licenseKey !== "string") {
+    throw new Error("licenseKey is required and must be a string");
+  }
+  if (!opts.tier || typeof opts.tier !== "string") {
+    throw new Error("tier is required and must be a string");
+  }
+  if (!opts.issued || typeof opts.issued !== "string") {
+    throw new Error("issued is required and must be a string");
+  }
+  const payload = {
+    licenseKey: opts.licenseKey,
+    tier: opts.tier,
+    isFounder: Boolean(opts.isFounder),
+    issued: opts.issued
+  };
+  if (opts.emailHash) {
+    payload.emailHash = opts.emailHash;
+  }
+  return payload;
+}
+
+// src/registry.ts
+function buildSignedRegistry(entries, privateKeyPem, keyId = "default") {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const entriesStr = stableStringify(entries);
+  const registrySignature = signPayload(entries, privateKeyPem);
+  const hash = computeHash(entriesStr);
+  return {
+    _metadata: {
+      version: "1.0",
+      created: now,
+      lastUpdate: now,
+      description: "BuildProven license registry \u2014 populated by fulfillment webhook",
+      algorithm: "rsa-sha256",
+      keyId,
+      registrySignature,
+      hash,
+      totalLicenses: Object.keys(entries).length
+    },
+    ...entries
+  };
+}
+
+// src/validator.ts
+function validateRegistryEntry(opts) {
+  const { licenseKey, entry, publicKeyPem, userEmailHash } = opts;
+  if (entry.emailHash && userEmailHash && !timingSafeStringEqual(userEmailHash, entry.emailHash)) {
+    return { valid: false, error: "Email address does not match license registration" };
+  }
+  const payload = buildLicensePayload({
+    licenseKey,
+    tier: entry.tier,
+    isFounder: entry.isFounder,
+    issued: entry.issued,
+    emailHash: entry.emailHash
+  });
+  if (!verifyPayload(payload, entry.signature, publicKeyPem)) {
+    return { valid: false, error: "License entry signature verification failed" };
+  }
+  return {
+    valid: true,
+    tier: entry.tier,
+    isFounder: entry.isFounder,
+    customerId: entry.customerId,
+    keyId: entry.keyId
+  };
+}
+function verifyRegistryMetadata(signedRegistry, publicKeyPem) {
+  const { _metadata, ...entries } = signedRegistry;
+  if (!_metadata?.registrySignature) {
+    throw new Error("Registry missing _metadata.registrySignature");
+  }
+  if (!verifyPayload(entries, _metadata.registrySignature, publicKeyPem)) {
+    throw new Error("Registry signature verification failed");
+  }
+  if (_metadata.hash) {
+    const computed = computeHash(stableStringify(entries));
+    if (!timingSafeStringEqual(computed, _metadata.hash)) {
+      throw new Error("Registry hash mismatch");
+    }
+  }
+  return entries;
+}
+
+// src/key-format.ts
+function licenseKeyPattern(prefix) {
+  if (!/^[A-Z0-9]+$/.test(prefix)) {
+    throw new Error(`Prefix must be uppercase alphanumeric: ${prefix}`);
+  }
+  return new RegExp(`^${prefix}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$`);
+}
+function isValidLicenseKey(key, prefix) {
+  return licenseKeyPattern(prefix).test(key.trim().toUpperCase());
+}
+function normalizeLicenseKey(key) {
+  return key.trim().toUpperCase();
+}
+export {
+  buildLicensePayload,
+  buildSignedRegistry,
+  computeHash,
+  hashEmail,
+  isValidLicenseKey,
+  licenseKeyPattern,
+  normalizeEmail,
+  normalizeLicenseKey,
+  signPayload,
+  stableStringify,
+  timingSafeStringEqual,
+  validateRegistryEntry,
+  verifyPayload,
+  verifyRegistryMetadata
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":"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","names":["createHash"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@buildproven/license-core",
+  "version": "1.0.0",
+  "description": "Shared license signing & verification primitives for BuildProven products (RSA-SHA256, signed registry).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildproven/buildproven-license-core.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "license",
+    "licensing",
+    "rsa",
+    "rsa-sha256",
+    "signature",
+    "registry",
+    "stripe",
+    "saas"
+  ],
+  "private": false
+}