HF-329: re-port the license key reader to the entitlement key format (7/8)

[marcin-kordas-hoc]

7/8 of the HF-307 stack (#1728 → #1729 → #1730 → #1731 → #1736 → #1737 → this). Implements HF-329 ("Import license key validator shared code to HF"). Pairs with hyperformula-tests#41 — merge the tests PR first (CI clones it by branch name).

Why now

Upstream handsontable/license-key 4.0.0 (18.08, DEV-2512) deleted src/typed-key/ — the exact directory our vendored reader was ported from — and replaced the tagged key format with the entitlement key format:

<prose>\n\n[<base64url-payload><sha512-checksum>]

my.handsontable.com already pins 4.0.0 and mints entitlement keys for trials, so the vendored reader was reading a format that no longer exists anywhere. The byte-level rules are specified in the key spec's "Technical implementation" addendum (T1–T14).

What changed

Only the envelope. The entitlement layer — token resolution, the capability table, gate A/B, ensureCapability — is untouched by design.

• Re-vendored from src/entitlement-key/ at tag 4.0.0: detectFormat.ts and extractKeyData.ts are new ports; sha512.ts/utils.ts are byte-identical upstream (same hashes) and carry over. PROVENANCE.md records the new tag, commit, and sha256 table.
• The reader is schema-free by upstream design (strict on shape, lenient on vocabulary — T7), so defaultSchema.ts is no longer vendored; the only name the engine reads is its own hyperformula product entry.
• resolveLicense routes on the vendored detectLicenseKeyFormat (normative T12 order: literals → bracketed block → legacy shape). Literal keys and legacy 25-character keys reach checkLicenseKeyValidity completely unchanged.
• The invariant stands: only a VALID entitlement key may restrict the entitlement; MISSING/INVALID/EXPIRED resolve to unrestrictedEntitlement() (mutation-tested in the suite).

Decisions to confirm in review

1. The tagged format is removed outright, not kept alongside. It was never issued to anyone (its 3.5.0 carrier is unreleased, and my.handsontable.com's own PR says "the typed keys never reached production"), upstream deleted it, and PROVENANCE mirrors upstream. With it goes TIER_TO_CAPABILITY_TOKEN — the entitlement format has no tier field.
2. Deliberate behaviour deltas, each spec-mandated and pinned in the paired tests:
   • a prose edit keeps a key VALID (T8, stated by the addendum as a reversal of the typed-key behaviour);
   • a key granting another product only never expires for HyperFormula (each entry carries its own terms; the licensed-product rule is gone);
   • both-dates, numeric-date, and null-entry payloads are INVALID (T7 strict shape; the old adapter tolerated each).
3. Dates are carried as the payload's own YYYY-MM-DD strings, never routed through Date formatting (fixture J11).

Testing

Fixtures re-minted with upstream's real generator at 4.0.0 and round-tripped through upstream's extractor; the addendum's T14 conformance vectors pinned 1:1, baselined on its T13 worked example verbatim. Full private suite: 516 suites / 6430 passed, 3 pre-existing skips; tsc --noEmit and ESLint clean.

Found while working on this, NOT fixed here

CHANGELOG.md's [Unreleased] has no Removed entry for the static function metadata API removed by HF-349 (#1724) — a breaking change currently shipping into 3.5.0 unannounced. Raised separately.

🤖 Generated with Claude Code

https://claude.ai/code/session_019pxNP45obT2LZfjitaCv9o

---

Note

Medium Risk
Rewrites proprietary license parsing and routing, which is business-critical, but legacy/gpl paths and the “bad key → unrestricted entitlement” invariant are preserved; risk is mainly wrong verdicts or grants for new entitlement keys and hostile payloads.

Overview
Replaces the internal tagged (“typed”) proprietary key reader with the upstream entitlement key format — human-readable text plus a trailing [base64url-payload + sha512] block — vendored from handsontable/license-key 4.0.0. The old tagged format and defaultSchema.ts / tier-to-package mapping are removed; classic 25-character keys and gpl-v3 still route through the unchanged legacy validator.

resolveLicense now uses detectLicenseKeyFormat (literals → bracketed block → legacy shape) and extractEntitlementKeyData. Terms come only from the payload’s hyperformula product entry (per-entry dates, notice, grace, flags); keys for other products or with no HyperFormula entry are valid but grant nothing for this library.

Behavior fixes on the entitlement path: capability tokens are appended one-by-one so huge payloads cannot crash construction via push(...array); the “grant all five feat:* areas” fallback runs only when the key names a recognized feat:* token, so unknown feat:* tokens stay inert per D3. Console notice identity uses the checksum plus closing bracket (129 trailing chars).

Docs and CHANGELOG describe both key formats, validation axes (usage_until vs release_until), and the valid-key expiry notice.

^{Reviewed by Cursor Bugbot for commit a425d37. Bugbot is set up for automated code reviews on this repo. Configure here.}

Spec-to-ship review (2026-08-20): 3 findings fixed here

A six-dimension adversarial review ran over this PR, #1741 and #1743 (spec conformance, decision
conformance, port fidelity, hostile payloads, dialect table, API surface). What it found against
this commit, all fixed above and each one verified by running it:

1. A hostile key could crash engine construction. capabilityTokens.push(...grant.capabilities)
   spread an attacker-sized array into a call: measured, a checksum-valid key carrying 125 000
   tokens threw RangeError: Maximum call stack size exceeded out of buildFromArray instead of
   resolving to a verdict — the one thing this module's own doc comment promises never happens. Now
   appended element by element; 200 000 tokens (a 3 MB key) resolves in 141 ms. Pinned by a test.
2. The T14 payload-tamper vector was vacuous. rejects one character changed in the payload segment [catches: the checksum doing nothing] passed with the checksum comparison deleted
   outright, because the flipped character corrupted the payload's products key and the T7 shape
   check rejected it first. Mutation-verified in both directions: with the comparison removed only
   the checksum-segment vector failed. Replaced with a well-formed payload (the T13 record with
   notice: 61) carrying T13's original checksum, plus a positive control asserting the same
   payload with its own checksum is accepted — so the rejection can only come from the checksum.
3. Two inaccuracies in what this PR wrote. PROVENANCE.md's divergence DATE type is not supported by arithmetic and comparison operators #3 claimed the typed
   entry's "fields carry their verified types", but the date field is verified only by matching
   String(value) against YYYY-MM-DD, so an array holding one date string passes and the declared
   string is wider than the value (faithful to upstream — the manifest was the thing overstating).
   And isNonNegativeInteger had drifted to the global isFinite where upstream uses
   Number.isFinite: behaviour-identical behind the typeof guard, but an undocumented edit inside
   a hash-pinned mirror. Both corrected.

Also corrected in the guide: the classic-key example showed 20 characters next to the sentence
"25 characters", and the entitlement-key paragraph said the text "may be re-wrapped or re-formatted
… without affecting the key" — true of the prose, false of the block, which has to arrive character
for character.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	a425d37	Commit Preview URL Branch Preview URL	Aug 26 2026, 03:39 AM

[qunabu]

Task linked: HF-307 Implement feature packages and add-ons in HF
Task linked: HF-329 Import license key validator shared code to HF
Task linked: HF-349 Static methods cannot read functions granted by license key

[github-actions]

Performance comparison of head (a425d37) vs base (3dbcbe6)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |  475.85 |  479.91 | +0.85%
                                      Sheet B |  152.38 |  154.08 | +1.12%
                                      Sheet T |  133.77 |  134.52 | +0.56%
                                Column ranges |   512.2 |  510.08 | -0.41%
                                Sorted lookup | 15332.6 | 15112.7 | -1.43%
Sheet A:  change value, add/remove row/column |   15.11 |   16.11 | +6.62%
 Sheet B: change value, add/remove row/column |  133.66 |   128.6 | -3.79%
                   Column ranges - add column |   153.1 |  155.44 | +1.53%
                Column ranges - without batch |  475.88 |   490.3 | +3.03%
                        Column ranges - batch |  120.74 |  121.92 | +0.98%

[Tobiadefami]

Reviewed at 523316e together with the paired tests at 81f180ce. I checked format routing, checksum-before-parse ordering, the strict-shape/lenient-vocabulary contract, per-product expiry, the invalid-key invariant, hostile-payload handling, provenance, docs and changelog, current automated findings, and later stacked branches. The 15 focused license suites pass (256 tests), and all current engine checks are green. I found one material shape-validation issue: a single-element array is accepted where an entitlement date must be a YYYY-MM-DD string, as noted inline.

[Tobiadefami]

value as string is only a compile-time assertion, while parseIsoDate stringifies at runtime. A checksum-valid payload with usage_until: ["2099-12-31"] therefore passes extraction unchanged and resolveLicense reports it VALID; I reproduced both on this head. That contradicts T7/J6's strict YYYY-MM-DD string shape and makes the declared usage_until?: string type untrue, so malformed input can activate a restricted entitlement instead of taking the invalid-key path. It would help to require typeof value === 'string' before parsing, fix the mirror upstream first, and pin the array case.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.38%. Comparing base (3dbcbe6) to head (a425d37).

Additional details and impacted files

@@                     Coverage Diff                      @@
##           spike/hf307-addon-grants    #1740      +/-   ##
============================================================
- Coverage                     97.38%   97.38%   -0.01%     
============================================================
  Files                           204      204              
  Lines                         16236    16233       -3     
  Branches                       3493     3482      -11     
============================================================
- Hits                          15812    15809       -3     
  Misses                          424      424              

Files with missing lines	Coverage Δ
src/Config.ts	94.69% <ø> (ø)
src/helpers/licenseKeyValidator.ts	95.83% <100.00%> (+0.08%)	⬆️
src/license/LicenseEntitlement.ts	100.00% <ø> (ø)
src/license/capabilities.ts	100.00% <ø> (ø)
src/license/licenseResolution.ts	98.63% <100.00%> (+1.19%)	⬆️
src/license/vendor/constants.ts	100.00% <100.00%> (ø)
src/license/vendor/detectFormat.ts	100.00% <100.00%> (ø)
src/license/vendor/extractKeyData.ts	97.56% <100.00%> (-2.44%)	⬇️
src/license/vendor/sha512.ts	100.00% <ø> (ø)
src/license/vendor/utils.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.