@thejoseki/clawform 0.0.1 → 2.2.0

package/src/lib/constants.js

@@ -0,0 +1,85 @@
+export const ENVS = ['d', 'stg', 'p'];
+
+// The customer token is the widest variable slot in every generated name, and
+// the tightest consumer is the 32-char cap AWS puts on load-balancer and
+// target-group names. Eight characters is what that budget leaves once the
+// longest env, the fixed infix, and a usable project shortname are accounted
+// for — see the arithmetic in templates/alb.yaml. The archetypes'
+// AllowedPattern and the init wizard both have to agree with this number, or
+// the wizard writes a config that fails at deploy time.
+export const CUSTOMER_MAX_LEN = 8;
+export const CUSTOMER_RE = new RegExp(`^[a-z0-9]{1,${CUSTOMER_MAX_LEN}}$`);
+
+// Catalog + inventory are generated from the consumer's own AWS account, so
+// they belong in the consumer's project — not in the plugin checkout, where
+// they would be shared across every project, wiped by `npm update`, and out of
+// reach of the deploy-gate hook (which resolves them relative to the project).
+// Dotted and single-rooted so a buyer gitignores one entry.
+export const CATALOG_DIR_REL = '.clawform/catalog';
+
+export const VISIBILITY_PREFIXES = ['pri', 'pub'];
+
+// When adding: update rules/cfn-standards.md service-shortname table in the same change.
+// Consumers can extend this list via `service_shortnames_extra` in clawform.config.json
+// without forking the plugin.
+export const SERVICE_SHORTNAMES = [
+  'vpc', 'snet', 'sg', 'rt', 'vpce', 'igw', 'nat', 'eip',
+  'alb', 'nlb', 'tg', 'lstn',
+  'ecsc', 'ecss', 'ecr',
+  'rds', 'aur', 'ddb', 'ecache',
+  's3', 'lmbd',
+  'sns', 'sqs', 'glue',
+  'cf', 'r53', 'acm', 'cgnp', 'wafa',
+  'sm', 'cwlg', 'cwa', 'bgt',
+  'iamr', 'kms', 'ec2',
+  'ccmt', 'cbld', 'cpl', 'cdpl',
+];
+
+// The legacy-prefix list moved out of the plugin and into the consumer's
+// clawform.config.json (`legacy_prefixes`). See src/lib/project-config.js
+// and docs/config-schema.md. A fresh consumer with no config has no legacy
+// stacks, so the built-in default is an empty list — we don't impose Acme's
+// LEGACY/OLDAPP freeze on someone else's account.
+
+// Anchored to line-start to defeat prompt-injection via "FORCE LEGACY" inside narrative content.
+export const LEGACY_OVERRIDE_PHRASE = /^\s*#\s*FORCE\s+LEGACY\b/m;
+
+// Stateful CFN resource types per CLAUDE.md hard rule #4. Replace on any of these
+// requires the data-resource gate in src/commands/deploy.js (user must retype stack name).
+//
+// IMPORTANT: list only types that actually hold data. The RDS/EFS/ElastiCache namespaces
+// each contain config types (SubnetGroup, ParameterGroup, MountTarget, OptionGroup, ...)
+// that hold no data — including them via a bare-prefix match would over-fire the safety
+// gate on harmless config Replaces and train operators to ignore the warning. Add new
+// stateful types here explicitly; don't reintroduce DATA_RESOURCE_PREFIXES.
+export const DATA_RESOURCE_EXACT = [
+  // Cognito — a user pool holds every user account; a Replace repoints the
+  // export at a brand-new EMPTY pool. Treated as data per hard rule #4.
+  'AWS::Cognito::UserPool',
+  // S3 / DynamoDB / Logs / Secrets / KMS
+  'AWS::S3::Bucket',
+  'AWS::DynamoDB::Table',
+  'AWS::DynamoDB::GlobalTable',
+  'AWS::Logs::LogGroup',
+  'AWS::SecretsManager::Secret',
+  'AWS::KMS::Key',
+  // RDS — stateful only (DBInstance/Cluster + snapshots; NOT *Group, *Subscription, DBProxy)
+  'AWS::RDS::DBInstance',
+  'AWS::RDS::DBCluster',
+  'AWS::RDS::GlobalCluster',
+  'AWS::RDS::DBClusterSnapshot',
+  'AWS::RDS::DBSnapshot',
+  // EFS — stateful only (FileSystem; NOT MountTarget, AccessPoint, FileSystemPolicy)
+  'AWS::EFS::FileSystem',
+  // ElastiCache — "when persistent" per CLAUDE.md hard rule #4
+  // (NOT SubnetGroup, ParameterGroup, SecurityGroup, User, UserGroup)
+  'AWS::ElastiCache::CacheCluster',
+  'AWS::ElastiCache::ReplicationGroup',
+  'AWS::ElastiCache::GlobalReplicationGroup',
+  'AWS::ElastiCache::ServerlessCache',
+];
+
+export function isDataResource(resourceType) {
+  if (!resourceType) return false;
+  return DATA_RESOURCE_EXACT.includes(resourceType);
+}

package/src/lib/defaults.js

@@ -0,0 +1,16 @@
+// Built-in defaults for Clawform's consumer config. Merged FIRST (lowest precedence)
+// by src/lib/project-config.js. A fresh consumer (no clawform.config.json) sees these
+// values; the dogfood clawform.config.json in this repo overlays the Acme-specific bits.
+
+export const DEFAULT_ENVS = ['d', 'stg', 'p'];
+
+export const DEFAULT_CONFIG = {
+  customer: '',
+  envs: DEFAULT_ENVS,
+  region: '',
+  accounts: {},
+  // Empty by default — we never impose Acme's legacy list on someone else's account.
+  legacy_prefixes: [],
+  service_shortnames_extra: [],
+  tags_defaults: {},
+};

package/src/lib/fingerprint.js

@@ -0,0 +1,65 @@
+// Machine fingerprint for license device-binding. The hash is what Clawform
+// sends to Polar as an activation instance label, so one physical machine maps
+// to one activation slot (see docs — device limit is per human machine; CI uses
+// key-validate-only and never activates).
+//
+// The impure gathering (gatherMachineParts) is split from the pure hasher
+// (computeFingerprint) so the hash is unit-testable without touching the OS —
+// same pattern the rest of src/lib uses (pure core, injected I/O).
+
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import { readFileSync as fsRead } from 'node:fs';
+
+// Pure: given the raw identifying parts, return a stable short hex fingerprint.
+// Order-fixed and NUL-delimited so two machines that merely share one field
+// (e.g. platform) never collide, and so 'a'+'bc' can't alias 'ab'+'c'.
+export function computeFingerprint({ hostname = '', platform = '', arch = '', machineId = '' } = {}) {
+  // '\u0000' as an escape, not a literal NUL byte — a raw control character in
+  // the source makes grep/diff treat the whole file as binary.
+  const material = [hostname, platform, arch, machineId].join('\u0000');
+  return createHash('sha256').update(material).digest('hex').slice(0, 32);
+}
+
+// Impure: gather the parts from the OS. machineId is best-effort — a stable
+// per-install ID when the platform exposes one cheaply, else '' (the
+// hostname/platform/arch trio still yields a usable, if slightly weaker,
+// fingerprint). Never throws: any probe failure degrades to ''.
+export function gatherMachineParts({ readFileSync = fsRead, osImpl = os } = {}) {
+  return {
+    hostname: safe(() => osImpl.hostname()),
+    platform: safe(() => osImpl.platform()),
+    arch: safe(() => osImpl.arch()),
+    machineId: readMachineId(readFileSync, osImpl),
+  };
+}
+
+// Convenience: gather + hash in one call. This is what `activate` uses.
+export function machineFingerprint(deps = {}) {
+  return computeFingerprint(gatherMachineParts(deps));
+}
+
+function readMachineId(readFileSync, osImpl) {
+  const platform = safe(() => osImpl.platform());
+  // Linux exposes a stable per-install ID via systemd/dbus — cheap to read.
+  if (platform === 'linux') {
+    for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+      const v = safe(() => readFileSync(p, 'utf8').trim());
+      if (v) return v;
+    }
+  }
+  // macOS/Windows machine-id needs a subprocess (ioreg / registry query). To
+  // keep this layer dependency-free and side-effect-light, fall back to '' and
+  // lean on hostname+platform+arch — good enough for a device deterrent at this
+  // price point. Revisit with node-machine-id only if real collisions appear.
+  return '';
+}
+
+function safe(fn) {
+  try {
+    const v = fn();
+    return typeof v === 'string' ? v : String(v ?? '');
+  } catch {
+    return '';
+  }
+}

package/src/lib/install-workflow.js

@@ -0,0 +1,28 @@
+import { existsSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Claude Code has no "workflows" plugin component type — saved workflow
+// scripts are discovered only from a project's own .claude/workflows/ (or
+// ~/.claude/workflows/), never from a plugin's shipped files. This copies
+// the plugin-shipped workflows/audit-all-stacks.js into the CONSUMER
+// project's .claude/workflows/ so `/audit-all-stacks` (or `/workflows`)
+// actually finds it there. Idempotent: never overwrites an existing copy,
+// so a consumer's local customization survives repeated `clawform sync` runs.
+export function ensureWorkflowInstalled({
+  repoRoot,
+  projectDir,
+  exists = existsSync,
+  mkdir = mkdirSync,
+  copyFile = copyFileSync,
+} = {}) {
+  const src = join(repoRoot, 'workflows', 'audit-all-stacks.js');
+  if (!exists(src)) return { installed: false, reason: 'source-missing' };
+
+  const destDir = join(projectDir, '.claude', 'workflows');
+  const dest = join(destDir, 'audit-all-stacks.js');
+  if (exists(dest)) return { installed: false, reason: 'already-present', dest };
+
+  mkdir(destDir, { recursive: true });
+  copyFile(src, dest);
+  return { installed: true, dest };
+}

package/src/lib/kit-source.js

@@ -0,0 +1,81 @@
+// Where the plugin content kit comes from.
+//
+// It used to come from the npm tarball, alongside the key that opened it —
+// which meant `npm i` handed a non-buyer the entire library. The kit now lives
+// behind a licence check: the service verifies the key with the vendor and
+// streams the bundle over TLS, so no key ships in the CLI at all.
+//
+// Fetched once and cached. After that the plugin can be re-assembled or
+// repaired with no network, which matters because `init plugin` is not
+// something a buyer should have to be online to re-run.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { unpackFiles } from './payload.js';
+
+export const KIT_CACHE_FILENAME = 'kit.bin';
+
+// Said on every service failure. Someone hitting this may have a stack stuck
+// mid-update, and the first thing they need to know is that the emergency path
+// is not what just broke. Those two commands are never licence-gated, and they
+// do not touch this module.
+const STILL_WORKS = 'clawform deploy and clawform rollback are unaffected and keep working.';
+
+function outage(reason) {
+  return new Error(
+    `Could not reach the Clawform kit service (${reason}). This is our side, not your licence. `
+    + `Try again shortly — ${STILL_WORKS}`,
+  );
+}
+
+function refusal(reason) {
+  return new Error(
+    `The kit service would not serve this licence (${reason}). `
+    + 'Run `clawform license` to see what this machine holds, or contact support@thejoseki.com.',
+  );
+}
+
+async function detailOf(resp) {
+  try {
+    const body = await resp.json();
+    return String(body?.detail ?? `HTTP ${resp.status}`);
+  } catch {
+    return `HTTP ${resp.status}`;
+  }
+}
+
+/**
+ * Resolve the content kit, from cache or from the service.
+ * @returns {Promise<Array<{path: string, content: string}>>}
+ */
+export async function obtainKit({ licenseKey, serviceUrl, cacheDir, fetch: fetchImpl = fetch }) {
+  const cachePath = join(cacheDir, KIT_CACHE_FILENAME);
+  if (existsSync(cachePath)) return unpackFiles(readFileSync(cachePath));
+
+  let resp;
+  try {
+    resp = await fetchImpl(`${serviceUrl}/kit`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ license_key: licenseKey }),
+    });
+  } catch (err) {
+    throw outage(err?.message ?? 'network error');
+  }
+
+  // A throttle or a 5xx is the service failing, not the licence being judged —
+  // the same distinction the vendor client draws, and for the same reason.
+  if (resp.status === 429 || resp.status >= 500) throw outage(`HTTP ${resp.status}`);
+  if (!resp.ok) throw refusal(await detailOf(resp));
+
+  const bundle = Buffer.from(await resp.arrayBuffer());
+
+  // Unpack BEFORE caching. A truncated or mismatched bundle written to disk
+  // would be served as a real kit on every later run, turning one bad response
+  // into a permanently broken install with no obvious cause.
+  const entries = unpackFiles(bundle);
+
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(cachePath, bundle);
+  return entries;
+}

package/src/lib/license-client.js

@@ -0,0 +1,84 @@
+// Vendor-agnostic license client seam. Every consumer talks to this contract:
+//
+//   activate(key, fingerprint) → { status:'valid', instanceId, holder? }
+//                              | { status:'invalid', reason }   // limit_reached | expired | not_found
+//                              | { status:'error',   reason }   // vendor unreachable
+//   validate(key, activationId?) → { status:'valid'|'invalid'|'error', reason? }
+//   deactivate(key, activationId)→ { status:'valid'|'invalid'|'error', reason? }
+//
+// resolveClient() picks the implementation from the license mode:
+//   'off' (default)  → a dormant stub (configured:false) — assertLicensed
+//                      passes everything, so the repo's own dev/CI and every
+//                      buyer before launch is unaffected.
+//   'sandbox'/'live' → the real Polar adapter (configured:true) against the
+//                      matching base URL.
+//
+// Flipping the shipped default to a live mode is the single reviewed decision
+// that turns enforcement on (see license-config.js).
+
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readEnv } from './rename-compat.js';
+import { createPolarClient } from './providers/polar.js';
+import {
+  LICENSE_MODE_DEFAULT,
+  DEV_MARKER,
+  POLAR_ORGANIZATION_ID,
+  POLAR_BENEFIT_ID,
+  POLAR_TRIAL_BENEFIT_ID,
+  POLAR_BASE_URL,
+} from './license-config.js';
+
+const DORMANT = {
+  configured: false,
+  async activate() { return { status: 'error', reason: 'license enforcement is off in this build' }; },
+  async validate() { return { status: 'error', reason: 'license enforcement is off in this build' }; },
+  async deactivate() { return { status: 'error', reason: 'license enforcement is off in this build' }; },
+};
+
+// Resolved from THIS module's location, never from process.cwd(): with cwd, a
+// buyer running clawform inside any repo that happens to carry the dev marker
+// would be handed the dormant client — a bypass needing no edit at all.
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export function isSourceCheckout(packageRoot = PACKAGE_ROOT) {
+  return existsSync(join(packageRoot, DEV_MARKER));
+}
+
+// `env` stays POSITIONAL: callers pass an env object, and folding it into an
+// options bag would silently reinterpret every existing call as `{env:
+// undefined}` — falling back to process.env and passing for the wrong reason.
+export function resolveMode(env = process.env, { packageRoot = PACKAGE_ROOT } = {}) {
+  const fromEnv = readEnv('LICENSE_MODE', env);
+  // The environment may pick BETWEEN enforcing modes; it can never turn
+  // enforcement down. Anything else — 'off', a typo, an empty string — is
+  // ignored rather than treated as a request to disable.
+  if (fromEnv === 'sandbox' || fromEnv === 'live') return fromEnv;
+  if (isSourceCheckout(packageRoot)) return 'off';
+  return LICENSE_MODE_DEFAULT;
+}
+
+// Which benefits are trials, for the mode this install is running in. Resolved
+// here rather than in license-config because that is where mode resolution
+// already lives, and a second copy of it would be free to disagree.
+//
+// A dormant install has no trials: nothing to claim, nothing to refuse.
+export function resolveTrialBenefitIds({ env = process.env, packageRoot = PACKAGE_ROOT } = {}) {
+  const mode = resolveMode(env, { packageRoot });
+  return POLAR_TRIAL_BENEFIT_ID[mode] ?? [];
+}
+
+export function resolveClient({ env = process.env, packageRoot = PACKAGE_ROOT, fetch } = {}) {
+  const mode = resolveMode(env, { packageRoot });
+  if (mode !== 'sandbox' && mode !== 'live') return DORMANT;
+  // Both looked up by the same mode, so they cannot drift apart: a base URL
+  // for one environment with an organization from the other is the failure
+  // this shape exists to make impossible.
+  return createPolarClient({
+    baseUrl: POLAR_BASE_URL[mode],
+    organizationId: POLAR_ORGANIZATION_ID[mode],
+    benefitIds: POLAR_BENEFIT_ID[mode],
+    ...(fetch ? { fetch } : {}),
+  });
+}

package/src/lib/license-config.js

@@ -0,0 +1,162 @@
+// Licensing time policy. Vendor identifiers (org/product IDs) join this file
+// once the payout test settles which vendor we ship with — the time policy is
+// vendor-independent and the grace/revalidate logic only needs these two.
+
+// How long a cached "valid" verdict is trusted before the CLI re-checks with
+// the vendor in the background. Once per day keeps revocation reasonably fresh
+// without turning every command into a network call.
+export const REVALIDATE_HOURS = 24;
+
+// How long a buyer keeps working after the LAST successful validation when the
+// vendor cannot be reached (offline dev box, vendor outage). Two weeks: long
+// enough to survive a vacation offline, short enough that a revoked-but-
+// unreachable key does not run forever.
+export const GRACE_DAYS = 14;
+
+// --- Vendor: Polar -------------------------------------------------------
+// The organization id is not a secret — it is a public parameter of every
+// customer-portal call, and the API needs no server token besides the buyer's
+// own key. Safe to ship in the tarball.
+//
+// Keyed by mode, and it has to be. Polar's sandbox is a separate system rather
+// than a flag on the same one: you sign up for it separately, the organization
+// you create there does not exist in production, and its id is different. A
+// single id shared across both modes builds a client that talks to
+// api.polar.sh while naming a sandbox organization — every activation by a
+// real buyer fails, and it fails on the first day of selling rather than in
+// any amount of sandbox testing. Paired with POLAR_BASE_URL below so the two
+// can only be changed together.
+export const POLAR_ORGANIZATION_ID = {
+  live: '75b98aba-8768-4534-9b76-dd7f16cba3d3',
+  sandbox: 'c234fc61-20e4-4d6f-b919-0f5823f7984d',
+};
+export const POLAR_BASE_URL = {
+  live: 'https://api.polar.sh',
+  sandbox: 'https://sandbox-api.polar.sh',
+};
+
+// The License Keys benefit this product sells. The organization is not enough
+// to identify a key: every product under the same organization validates
+// against the same endpoint with the same organization id, so the moment a
+// second product sells from here, a key bought for THAT product activates this
+// one. A paying customer of one tool silently unlocking another is not a bug
+// anyone reports.
+//
+// Polar returns the benefit on both activate and validate, so the check costs
+// nothing and closes it. Keyed by mode for the same reason the organization is
+// — a sandbox benefit does not exist in production.
+//
+// A LIST per mode, one entry per paid tier. Polar carries limit_activations on
+// the benefit, not the product, so tiers with different device caps cannot share
+// one — the individual seat and the team seat are necessarily separate benefits.
+// A key is accepted when it matches ANY entry; the tier it belongs to is Polar's
+// business, not the CLI's.
+//
+// Nothing may appear in both lists: an id reachable from either environment
+// would let a sandbox key unlock a live install.
+export const POLAR_BENEFIT_ID = {
+  // [0] individual seat, [1] team seat. Order is not significance — a key is
+  // accepted on any match — but it is the order the walk tries, so the tier
+  // that sells most often belongs first.
+  live: [
+    'b85a9271-22ac-45b3-ab0a-b0c93df6b13c',
+    'be046860-7be4-43bd-ac8b-cf47d08f77d0',
+    'a3fc4e93-9e93-4317-bed5-5b44a5af9e19',
+  ],
+  sandbox: [
+    '69d1ccaa-65c4-48da-ad4a-64961772c17e',
+    'a540043d-da17-48ae-bee6-e9a900fbe1cc',
+    '9c5fe82d-09a7-490c-91e3-47d164603423',
+  ],
+};
+
+// Which of the benefits above are TRIALS. A trial key validates like any other
+// — it has to appear in POLAR_BENEFIT_ID as well — but it additionally claims
+// the machine, so one device cannot start a second trial under a new email.
+//
+// Listed separately rather than encoded in the entries above so phase 01's
+// shape and its tests stay untouched. A test pins that every id here also
+// appears in POLAR_BENEFIT_ID: an id in only one list is a trial key nobody can
+// activate, or a paid key that silently burns a device claim.
+//
+// The licence-key benefit on each trial product must be VISIBLE in Polar: the
+// buyer has to read the key out of the portal or the confirmation email to type
+// it into `clawform activate`. A hidden benefit is granted and unusable.
+export const POLAR_TRIAL_BENEFIT_ID = {
+  live: ['a3fc4e93-9e93-4317-bed5-5b44a5af9e19'],
+  sandbox: ['9c5fe82d-09a7-490c-91e3-47d164603423'],
+};
+
+// --- Content kit delivery -----------------------------------------------
+// The plugin content (skills/commands/agents/rules/templates) is NOT in the npm
+// tarball. It is fetched by `clawform init plugin` from this service, which
+// checks the licence with the vendor before serving anything.
+//
+// The previous model shipped the content as an encrypted blob with its key
+// beside it in the same tarball — which protected nothing: `npm i` handed a
+// non-buyer both halves. There is no key here now because the CLI never
+// decrypts; the bundle lives in a private bucket and travels over TLS.
+//
+// Not keyed by licence mode. There is one kit, and which licences may have it
+// is the service's judgement, not a build-time constant.
+export const KIT_SERVICE_URL = 'https://kit.thejoseki.com';
+
+// Written by scripts/pack-payload.js for upload, and cached under the vendor
+// home after a successful fetch. Never present in the published package.
+export const KIT_FILENAME = 'kit.bin';
+
+// Signs the local licence record. The gate trusts an 'active' record with a
+// fresh timestamp without calling the vendor, so an unsigned cache would make
+// `echo '{"status":"active",…}' > ~/.clawform/license.json` a complete bypass —
+// and a shareable one-liner at that. Signing raises it to "extract this secret
+// from the CLI first", the same bar as the dev marker.
+//
+// Same 1a honesty as PAYLOAD_KEY_HEX: the secret ships with the code, so a
+// determined attacker can still forge. The goal is killing the one-liner class.
+// Distinct from the payload key on purpose — keys with different jobs.
+//
+// Rotates alongside the payload key, and for the same reason: a release that
+// published this value hands every later release a forged 'active' record.
+// The cost is that records signed with the old secret read as unlicensed, so a
+// buyer re-activates — cheap now, and it only gets dearer with every seat sold.
+export const LICENSE_RECORD_SECRET_HEX = 'c4179ff7c3e2ebd223fdb2653ed1163f5b8cb89c7900af2a88f186fbb55818e5';
+
+// Tolerance for a machine clock running slightly ahead of the vendor's. Beyond
+// it, a future `lastValidatedAt` is treated as needing revalidation rather than
+// as an eternally fresh verdict.
+export const CLOCK_SKEW_HOURS = 1;
+
+// How a build tells whether it is a source checkout or an installed package.
+// This file is the payload build script — `package.json` `files` never ships
+// `scripts/`, so it is present in a clone and absent in `npm i -g @thejoseki/clawform`.
+//
+// Dormancy is granted by the install SHAPE, not by anything a buyer can set:
+// a `CLAWFORM_LICENSE_MODE=off` that disabled the gate would be a
+// copy-pasteable one-liner, the one bypass class that actually spreads.
+// Faking dormancy now means creating this file inside the installed package —
+// an edit, not a one-liner.
+//
+// ⚠️ Adding `scripts/` to `package.json` `files` would ship the marker and
+// silently disable enforcement for everyone. A packaging test asserts it stays
+// out of the tarball.
+export const DEV_MARKER = 'scripts/pack-payload.js';
+
+// The master switch, and the single decision that turns enforcement on.
+//
+// Held at 'off' through development, because enforcing before a key could be
+// bought would have locked out every user with no way back in. It moved to
+// 'live' only once all three preconditions were verified against the
+// production vendor rather than assumed:
+//
+//   - a Polar product exists with a License Keys benefit, activation limit 3
+//   - a real purchased key drives activate / validate / deactivate, the
+//     three-device cap refuses a fourth machine, and deactivate demonstrably
+//     frees a slot (proved by re-activating, not by the return code)
+//   - the sandbox and production environments reject each other's keys, which
+//     is what makes the per-mode organization and benefit ids load-bearing
+//
+// A source checkout stays dormant regardless: that exemption comes from the
+// dev marker's presence, not from this value, so contributors need no key.
+// Overridable per run via CLAWFORM_LICENSE_MODE, which can raise enforcement
+// but never lower it.
+export const LICENSE_MODE_DEFAULT = 'live';

package/src/lib/license-store.js

@@ -0,0 +1,107 @@
+// Local license cache — ~/.clawform/license.json. This is per-MACHINE / per-user
+// state (unlike the per-project .clawform-state.json in session-state.js), so it
+// lives in the home dir, not the project. It records what license enforcement
+// needs between runs: the key, its Polar activation instance, when it was last
+// validated, and who holds it. It never stores a Polar API secret — validation
+// uses the customer's key alone, there is no server-side credential in the CLI.
+//
+// All reads fail-open: a missing or corrupt file yields an 'unlicensed' state,
+// never an exception, so a bad cache can never crash a command (same discipline
+// as session-state.js). Writes create ~/.clawform/ on demand.
+//
+// Stored record shape (all optional except v/status):
+//   { v, status: 'active'|'unlicensed', key, instanceId, holder,
+//     fingerprint, lastValidatedAt (ISO string) }
+
+import {
+  readFileSync as fsRead,
+  writeFileSync as fsWrite,
+  mkdirSync as fsMkdir,
+  rmSync as fsRm,
+} from 'node:fs';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { homedir as osHomedir } from 'node:os';
+import { join } from 'node:path';
+import { LICENSE_RECORD_SECRET_HEX } from './license-config.js';
+
+export const LICENSE_DIR = '.clawform';
+export const LICENSE_FILENAME = 'license.json';
+export const LICENSE_VERSION = 1;
+
+function licenseDir(home) { return join(home, LICENSE_DIR); }
+function licensePath(home) { return join(licenseDir(home), LICENSE_FILENAME); }
+
+function unlicensed() { return { v: LICENSE_VERSION, status: 'unlicensed' }; }
+
+// Fields that a signature covers. Fixed order, so the digest depends on the
+// content and not on the order the caller happened to build the object in.
+//
+// `expiresAt` is here for the same reason `lastValidatedAt` is: a trial's end
+// date that a text editor can push out is not an end date. Adding a field
+// changes every existing signature, so records written before this read as
+// unlicensed and their owner re-activates once — cheap while the seat count is
+// small, and dearer with every seat sold.
+const SIGNED_FIELDS = ['v', 'status', 'key', 'instanceId', 'holder', 'fingerprint', 'lastValidatedAt', 'expiresAt'];
+
+function signatureOf(record) {
+  const canonical = JSON.stringify(SIGNED_FIELDS.map((f) => record[f] ?? null));
+  return createHmac('sha256', Buffer.from(LICENSE_RECORD_SECRET_HEX, 'hex'))
+    .update(canonical)
+    .digest('hex');
+}
+
+// Only an 'active' record makes a claim worth forging, so only that one has to
+// prove itself. Timing-safe compare keeps the check from leaking the expected
+// digest byte by byte.
+function signatureValid(record) {
+  const expected = Buffer.from(signatureOf(record), 'utf8');
+  const actual = Buffer.from(String(record.sig ?? ''), 'utf8');
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+
+// Read the cached license. Fail-open on every error path: missing file, bad
+// JSON, wrong version, or a shape that isn't an object → 'unlicensed'.
+export function readLicense({ homedir = osHomedir, readFileSync = fsRead } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(licensePath(homedir()), 'utf8');
+  } catch {
+    return unlicensed();
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return unlicensed();
+    if (parsed.v !== LICENSE_VERSION || typeof parsed.status !== 'string') return unlicensed();
+    // An unsigned or altered 'active' record is not a licence — it is exactly
+    // the forgery the signature exists to catch. 'unlicensed' claims nothing,
+    // so it needs no proof.
+    if (parsed.status === 'active' && !signatureValid(parsed)) return unlicensed();
+    return parsed;
+  } catch {
+    return unlicensed();
+  }
+}
+
+// Persist a license record, creating ~/.clawform/ if needed. The version is
+// always stamped by us, so callers pass only the payload fields.
+export function writeLicense(record, {
+  homedir = osHomedir,
+  writeFileSync = fsWrite,
+  mkdirSync = fsMkdir,
+} = {}) {
+  const home = homedir();
+  mkdirSync(licenseDir(home), { recursive: true });
+  const out = { ...record, v: LICENSE_VERSION };
+  out.sig = signatureOf(out);
+  writeFileSync(licensePath(home), JSON.stringify(out, null, 2));
+  return out;
+}
+
+// Remove the cache (used by `deactivate`). Fail-open: a missing file is success.
+export function clearLicense({ homedir = osHomedir, rmSync = fsRm } = {}) {
+  try {
+    rmSync(licensePath(homedir()), { force: true });
+  } catch {
+    // fail-open — nothing to clear, or an unwritable path we can't help here.
+  }
+}