@revealui/core 0.11.1 → 0.12.0

package/dist/license.d.ts

@@ -155,6 +155,33 @@ export declare function computeKeyId(publicKeyPem: string): Promise<string>;
  * options below. Signature is enforced via the public key.
  */
 export declare function validateLicenseKey(licenseKey: string, publicKey: string | readonly string[], expectedCustomerId?: string): Promise<LicensePayload | null>;
+/**
+ * How far past `exp` a license JWT is still accepted by the refresh endpoint
+ * (GAP-287 PR-1). Ratified by the owner 2026-07-18 at 30 days.
+ *
+ * Deliberately wider than the subscription validation grace
+ * (`LICENSE_GRACE_SUBSCRIPTION_DAYS`, default 3): the validation grace answers
+ * "may you still run", the refresh-accept window answers "may you still fetch
+ * your renewal". A customer returning from a month away should still be able to
+ * pull their current key rather than being bricked. Beyond this window the
+ * refresh path refuses and re-delivery goes through the authenticated admin
+ * account page.
+ */
+export declare const REFRESH_ACCEPT_DAYS = 30;
+/**
+ * Refresh-path validator (GAP-287 PR-1). Verifies a presented license JWT for
+ * `POST /api/license/refresh`, accepting a token whose `exp` is past by at most
+ * `refreshAcceptDays` (default {@link REFRESH_ACCEPT_DAYS}).
+ *
+ * It reuses the SAME ordered multi-key verification (GAP-259 rotation
+ * composition) and payload schema as {@link validateLicenseKey}, so a token
+ * minted under the outgoing private key during a dual-key rotation window still
+ * verifies. It performs NO `customerId` binding: the refresh endpoint trusts
+ * the token's `customerId` claim and then independently requires an ACTIVE
+ * license row for it. This function only proves possession of a recently-valid
+ * signed key. It never mints and never grants entitlement on its own.
+ */
+export declare function validateLicenseKeyForRefresh(licenseKey: string, publicKey: string | readonly string[], refreshAcceptDays?: number): Promise<LicensePayload | null>;
 /**
  * Outcome of a signing-keypair self-test. See {@link selfVerifyLicenseKeypair}.
  */
@@ -259,6 +286,82 @@ export declare function getMaxUsers(): number;
  * Track B metering: free=1K, pro=10K, max=50K, enterprise=unlimited.
  */
 export declare function getMaxAgentTasks(): number;
+/**
+ * Default subscription license JWT lifetime (seconds) — one year. Used as the
+ * fallback when a subscription's billing period is unavailable at mint time (an
+ * abnormal Stripe shape) so a period-bound token is never SHORTER than the
+ * pre-GAP-287 behavior, and as the default lifetime for {@link generateLicenseKey}
+ * when no explicit value is passed.
+ */
+export declare const DEFAULT_SUBSCRIPTION_TTL_SECONDS: number;
+/**
+ * Slack added to a hosted subscription's `current_period_end` when deriving the
+ * license JWT `exp` (GAP-287 PR-2). Ratified by the owner 2026-07-18 at 7 days.
+ *
+ * The token's lifetime equals what billing has actually granted plus this slack.
+ * The slack must cover the Stripe dunning/retry window so a card that recovers
+ * on retry never presents a lapsed key. Renewals advance the exp each billing
+ * cycle by re-minting on `invoice.payment_succeeded`.
+ */
+export declare const RENEWAL_SLACK_DAYS = 7;
+export declare const RENEWAL_SLACK_SECONDS: number;
+/**
+ * Default lifetime, in days, for a license JWT minted by the admin
+ * `POST /generate` manual-mint endpoint when the caller does not supply an
+ * explicit `expiresInDays` (GAP-287 PR-3). Ratified by the owner 2026-07-18 at
+ * 90, down from the prior flat 365-day default: this is an operator tool, and
+ * a short default nudges the right renewal habit for manually-issued keys. An
+ * explicit `expiresInDays` on the request is always honored unchanged.
+ */
+export declare const DEFAULT_MANUAL_MINT_DAYS = 90;
+/**
+ * Derives the relative `expiresInSeconds` argument for {@link generateLicenseKey}
+ * at the hosted subscription mint sites (GAP-287 PR-2): the token should expire
+ * at `periodEnd + RENEWAL_SLACK_SECONDS`. Because generateLicenseKey interprets a
+ * numeric lifetime relative to issue time, this returns that absolute bound minus
+ * now.
+ *
+ * Falls back to {@link DEFAULT_SUBSCRIPTION_TTL_SECONDS} when `periodEnd` is
+ * absent (a subscription with no billing period) so an unexpected Stripe shape
+ * never mints a shorter-than-before token. Never returns a non-positive lifetime:
+ * a period end already in the past floors at one second, leaving expiry to the
+ * validation grace + refresh window rather than minting an already-invalid token.
+ */
+export declare function subscriptionLicenseExpiresInSeconds(periodEnd: Date | null | undefined, nowMs?: number): number;
+/**
+ * Absolute epoch-second bound `periodEnd + RENEWAL_SLACK_SECONDS` a hosted
+ * subscription key should reach (GAP-287 PR-2). The renewal cadence re-mints IFF
+ * the stored key's `exp` is below this bound, so the comparison uses this
+ * absolute form while the mint uses the relative
+ * {@link subscriptionLicenseExpiresInSeconds}.
+ */
+export declare function subscriptionExpBound(periodEnd: Date): number;
+/**
+ * Idempotency tolerance for the renewal re-mint decision (fast-follow from the
+ * non-blocking finding on the #1978 guardrail-2 verdict). `subscriptionLicenseExpiresInSeconds`
+ * floors its relative TTL to whole seconds and the JWT signer floors `exp` to
+ * `iat + expiresInSeconds` at its own second granularity, so the `exp` actually
+ * persisted for a subscription key can land exactly 1s below
+ * {@link subscriptionExpBound}'s value even though the mint targeted that bound.
+ * Without this tolerance a duplicate/retried `invoice.payment_succeeded` lands on
+ * that 1s gap and re-enters the re-mint path instead of no-opping.
+ */
+export declare const RENEWAL_IDEMPOTENCY_TOLERANCE_SECONDS = 1;
+/**
+ * True when a stored license `exp` already covers the renewal bound, within the
+ * {@link RENEWAL_IDEMPOTENCY_TOLERANCE_SECONDS} idempotency tolerance  -  i.e. the
+ * renewal re-mint should be SKIPPED. `null` (perpetual token, or an undecodable
+ * key) never covers, so the caller falls through to re-mint.
+ */
+export declare function coversRenewalBound(storedExp: number | null, newBound: number): boolean;
+/**
+ * Reads the `exp` (epoch seconds) claim from a license JWT WITHOUT verifying its
+ * signature. Internal use only, for the GAP-287 PR-2 renewal cadence: the token
+ * comes from our OWN store and the caller needs only its expiry to decide whether
+ * to re-mint — never as an authentication or entitlement decision. Returns null
+ * for a perpetual token (no exp claim) or one that cannot be decoded.
+ */
+export declare function readLicenseExp(licenseKey: string): Promise<number | null>;
 /**
  * Generates a signed license key JWT.
  * Server-only in practice (requires the private key) but edge-compatible —

package/dist/license.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"license.d.ts","sourceRoot":"","sources":["../src/license.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"license.d.ts","sourceRoot":"","sources":["../src/license.ts"],"names":[],"mappings":"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"}

package/dist/license.js

@@ -204,6 +204,47 @@ export async function computeKeyId(publicKeyPem) {
  * options below. Signature is enforced via the public key.
  */
 export async function validateLicenseKey(licenseKey, publicKey, expectedCustomerId) {
+    // Accept tokens expired within the subscription grace window so the payload
+    // is available for grace-period calculations in isLicensed().
+    return verifyAndParseLicenseJwt(licenseKey, publicKey, graceConfig.subscriptionDays * 86_400, expectedCustomerId);
+}
+/**
+ * How far past `exp` a license JWT is still accepted by the refresh endpoint
+ * (GAP-287 PR-1). Ratified by the owner 2026-07-18 at 30 days.
+ *
+ * Deliberately wider than the subscription validation grace
+ * (`LICENSE_GRACE_SUBSCRIPTION_DAYS`, default 3): the validation grace answers
+ * "may you still run", the refresh-accept window answers "may you still fetch
+ * your renewal". A customer returning from a month away should still be able to
+ * pull their current key rather than being bricked. Beyond this window the
+ * refresh path refuses and re-delivery goes through the authenticated admin
+ * account page.
+ */
+export const REFRESH_ACCEPT_DAYS = 30;
+/**
+ * Refresh-path validator (GAP-287 PR-1). Verifies a presented license JWT for
+ * `POST /api/license/refresh`, accepting a token whose `exp` is past by at most
+ * `refreshAcceptDays` (default {@link REFRESH_ACCEPT_DAYS}).
+ *
+ * It reuses the SAME ordered multi-key verification (GAP-259 rotation
+ * composition) and payload schema as {@link validateLicenseKey}, so a token
+ * minted under the outgoing private key during a dual-key rotation window still
+ * verifies. It performs NO `customerId` binding: the refresh endpoint trusts
+ * the token's `customerId` claim and then independently requires an ACTIVE
+ * license row for it. This function only proves possession of a recently-valid
+ * signed key. It never mints and never grants entitlement on its own.
+ */
+export async function validateLicenseKeyForRefresh(licenseKey, publicKey, refreshAcceptDays = REFRESH_ACCEPT_DAYS) {
+    return verifyAndParseLicenseJwt(licenseKey, publicKey, refreshAcceptDays * 86_400);
+}
+/**
+ * Shared verify + parse path for {@link validateLicenseKey} and
+ * {@link validateLicenseKeyForRefresh}. The ONLY behavioral difference between
+ * the two callers is `clockToleranceSeconds` — how far past `exp` a token is
+ * still accepted — so the rotation-aware multi-key loop and the payload schema
+ * live in exactly one place.
+ */
+async function verifyAndParseLicenseJwt(licenseKey, publicKey, clockToleranceSeconds, expectedCustomerId) {
     const candidates = typeof publicKey === 'string' ? [publicKey] : [...publicKey];
     if (candidates.length === 0)
         return null;
@@ -218,11 +259,9 @@ export async function validateLicenseKey(licenseKey, publicKey, expectedCustomer
         for (const candidate of ordered) {
             try {
                 const key = await jose.importSPKI(candidate, 'EdDSA');
-                // Accept tokens expired within the subscription grace window so the
-                // payload is available for grace-period calculations in isLicensed().
                 const { payload } = await jose.jwtVerify(licenseKey, key, {
                     algorithms: ['EdDSA'],
-                    clockTolerance: graceConfig.subscriptionDays * 86_400,
+                    clockTolerance: clockToleranceSeconds,
                     issuer: LICENSE_ISSUER,
                     audience: LICENSE_AUDIENCE,
                 });
@@ -232,7 +271,7 @@ export async function validateLicenseKey(licenseKey, publicKey, expectedCustomer
             }
             catch {
                 // This candidate did not verify (wrong key, malformed PEM, bad
-                // iss/aud, or expired beyond grace) — try the next before giving up.
+                // iss/aud, or expired beyond tolerance) — try the next before giving up.
             }
         }
         if (!verified) {
@@ -617,6 +656,100 @@ export function getMaxAgentTasks() {
         return 10_000;
     return 1_000;
 }
+/**
+ * Default subscription license JWT lifetime (seconds) — one year. Used as the
+ * fallback when a subscription's billing period is unavailable at mint time (an
+ * abnormal Stripe shape) so a period-bound token is never SHORTER than the
+ * pre-GAP-287 behavior, and as the default lifetime for {@link generateLicenseKey}
+ * when no explicit value is passed.
+ */
+export const DEFAULT_SUBSCRIPTION_TTL_SECONDS = 365 * 24 * 60 * 60;
+/**
+ * Slack added to a hosted subscription's `current_period_end` when deriving the
+ * license JWT `exp` (GAP-287 PR-2). Ratified by the owner 2026-07-18 at 7 days.
+ *
+ * The token's lifetime equals what billing has actually granted plus this slack.
+ * The slack must cover the Stripe dunning/retry window so a card that recovers
+ * on retry never presents a lapsed key. Renewals advance the exp each billing
+ * cycle by re-minting on `invoice.payment_succeeded`.
+ */
+export const RENEWAL_SLACK_DAYS = 7;
+export const RENEWAL_SLACK_SECONDS = RENEWAL_SLACK_DAYS * 24 * 60 * 60;
+/**
+ * Default lifetime, in days, for a license JWT minted by the admin
+ * `POST /generate` manual-mint endpoint when the caller does not supply an
+ * explicit `expiresInDays` (GAP-287 PR-3). Ratified by the owner 2026-07-18 at
+ * 90, down from the prior flat 365-day default: this is an operator tool, and
+ * a short default nudges the right renewal habit for manually-issued keys. An
+ * explicit `expiresInDays` on the request is always honored unchanged.
+ */
+export const DEFAULT_MANUAL_MINT_DAYS = 90;
+/**
+ * Derives the relative `expiresInSeconds` argument for {@link generateLicenseKey}
+ * at the hosted subscription mint sites (GAP-287 PR-2): the token should expire
+ * at `periodEnd + RENEWAL_SLACK_SECONDS`. Because generateLicenseKey interprets a
+ * numeric lifetime relative to issue time, this returns that absolute bound minus
+ * now.
+ *
+ * Falls back to {@link DEFAULT_SUBSCRIPTION_TTL_SECONDS} when `periodEnd` is
+ * absent (a subscription with no billing period) so an unexpected Stripe shape
+ * never mints a shorter-than-before token. Never returns a non-positive lifetime:
+ * a period end already in the past floors at one second, leaving expiry to the
+ * validation grace + refresh window rather than minting an already-invalid token.
+ */
+export function subscriptionLicenseExpiresInSeconds(periodEnd, nowMs = Date.now()) {
+    if (!periodEnd)
+        return DEFAULT_SUBSCRIPTION_TTL_SECONDS;
+    const boundMs = periodEnd.getTime() + RENEWAL_SLACK_SECONDS * 1000;
+    return Math.max(1, Math.floor((boundMs - nowMs) / 1000));
+}
+/**
+ * Absolute epoch-second bound `periodEnd + RENEWAL_SLACK_SECONDS` a hosted
+ * subscription key should reach (GAP-287 PR-2). The renewal cadence re-mints IFF
+ * the stored key's `exp` is below this bound, so the comparison uses this
+ * absolute form while the mint uses the relative
+ * {@link subscriptionLicenseExpiresInSeconds}.
+ */
+export function subscriptionExpBound(periodEnd) {
+    return Math.floor(periodEnd.getTime() / 1000) + RENEWAL_SLACK_SECONDS;
+}
+/**
+ * Idempotency tolerance for the renewal re-mint decision (fast-follow from the
+ * non-blocking finding on the #1978 guardrail-2 verdict). `subscriptionLicenseExpiresInSeconds`
+ * floors its relative TTL to whole seconds and the JWT signer floors `exp` to
+ * `iat + expiresInSeconds` at its own second granularity, so the `exp` actually
+ * persisted for a subscription key can land exactly 1s below
+ * {@link subscriptionExpBound}'s value even though the mint targeted that bound.
+ * Without this tolerance a duplicate/retried `invoice.payment_succeeded` lands on
+ * that 1s gap and re-enters the re-mint path instead of no-opping.
+ */
+export const RENEWAL_IDEMPOTENCY_TOLERANCE_SECONDS = 1;
+/**
+ * True when a stored license `exp` already covers the renewal bound, within the
+ * {@link RENEWAL_IDEMPOTENCY_TOLERANCE_SECONDS} idempotency tolerance  -  i.e. the
+ * renewal re-mint should be SKIPPED. `null` (perpetual token, or an undecodable
+ * key) never covers, so the caller falls through to re-mint.
+ */
+export function coversRenewalBound(storedExp, newBound) {
+    return storedExp !== null && storedExp >= newBound - RENEWAL_IDEMPOTENCY_TOLERANCE_SECONDS;
+}
+/**
+ * Reads the `exp` (epoch seconds) claim from a license JWT WITHOUT verifying its
+ * signature. Internal use only, for the GAP-287 PR-2 renewal cadence: the token
+ * comes from our OWN store and the caller needs only its expiry to decide whether
+ * to re-mint — never as an authentication or entitlement decision. Returns null
+ * for a perpetual token (no exp claim) or one that cannot be decoded.
+ */
+export async function readLicenseExp(licenseKey) {
+    try {
+        const jose = await getJose();
+        const payload = jose.decodeJwt(licenseKey);
+        return typeof payload.exp === 'number' ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Generates a signed license key JWT.
  * Server-only in practice (requires the private key) but edge-compatible —
@@ -630,7 +763,7 @@ export function getMaxAgentTasks() {
  *   claim is added to the JWT header for forward-compatible key rotation.
  * @returns Signed JWT string
  */
-export async function generateLicenseKey(payload, privateKey, expiresInSeconds = 365 * 24 * 60 * 60, publicKey) {
+export async function generateLicenseKey(payload, privateKey, expiresInSeconds = DEFAULT_SUBSCRIPTION_TTL_SECONDS, publicKey) {
     const jose = await getJose();
     const key = await jose.importPKCS8(privateKey, 'EdDSA');
     const kid = publicKey ? await computeKeyId(publicKey) : undefined;

package/dist/revforge-license.d.ts

@@ -14,6 +14,15 @@ import { type LicensePayload } from './license.js';
 export declare const SLUG_PATTERN: RegExp;
 export declare const VALID_REVFORGE_TIERS: readonly ["pro", "max", "enterprise"];
 export type RevForgeTier = (typeof VALID_REVFORGE_TIERS)[number];
+/**
+ * Default lifetime, in days, for a RevForge kit license JWT when neither
+ * `expiresInDays` nor `perpetual` is supplied (GAP-287 PR-3). Ratified by the
+ * owner 2026-07-18: stays at 365 (no behavior change), matching the annual
+ * kit contract — the renewal path already exists via the GAP-316
+ * `stamp.sh --license-only` re-mint. This constant only names the value that
+ * was previously an inline literal.
+ */
+export declare const DEFAULT_KIT_MINT_DAYS = 365;
 export interface IssueRevForgeLicenseOptions {
     /** Customer slug; becomes the JWT customerId. Must match SLUG_PATTERN. */
     slug: string;

package/dist/revforge-license.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"revforge-license.d.ts","sourceRoot":"","sources":["../src/revforge-license.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,cAAc,EAAsB,MAAM,cAAc,CAAC;AAE3F,eAAO,MAAM,YAAY,QAAyB,CAAC;AAEnD,eAAO,MAAM,oBAAoB,uCAAwC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,MAAM,WAAW,2BAA2B;IAC1C,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oFAAoF;IACpF,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,2BAA2B,EACjC,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,0BAA0B,CAAC,CAuFrC"}
+{"version":3,"file":"revforge-license.d.ts","sourceRoot":"","sources":["../src/revforge-license.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,cAAc,EAAsB,MAAM,cAAc,CAAC;AAE3F,eAAO,MAAM,YAAY,QAAyB,CAAC;AAEnD,eAAO,MAAM,oBAAoB,uCAAwC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,MAAM,WAAW,2BAA2B;IAC1C,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oFAAoF;IACpF,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,2BAA2B,EACjC,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,0BAA0B,CAAC,CAwFrC"}

package/dist/revforge-license.js

@@ -13,6 +13,15 @@
 import { generateLicenseKey, validateLicenseKey } from './license.js';
 export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 export const VALID_REVFORGE_TIERS = ['pro', 'max', 'enterprise'];
+/**
+ * Default lifetime, in days, for a RevForge kit license JWT when neither
+ * `expiresInDays` nor `perpetual` is supplied (GAP-287 PR-3). Ratified by the
+ * owner 2026-07-18: stays at 365 (no behavior change), matching the annual
+ * kit contract — the renewal path already exists via the GAP-316
+ * `stamp.sh --license-only` re-mint. This constant only names the value that
+ * was previously an inline literal.
+ */
+export const DEFAULT_KIT_MINT_DAYS = 365;
 /**
  * Issue a signed RevForge license JWT for a paying customer.
  *
@@ -55,12 +64,13 @@ export async function issueRevForgeLicense(opts, keys) {
         ...(opts.domains && opts.domains.length > 0 ? { domains: opts.domains } : {}),
     };
     // Perpetual: pass null to omit exp claim. Otherwise translate days → seconds.
-    // Default (neither flag): 365-day subscription, matching generateLicenseKey's default.
+    // Default (neither flag): DEFAULT_KIT_MINT_DAYS (GAP-287 PR-3 named constant;
+    // value unchanged at 365).
     const expiresInSeconds = opts.perpetual
         ? null
         : opts.expiresInDays !== undefined
             ? opts.expiresInDays * 24 * 60 * 60
-            : 365 * 24 * 60 * 60;
+            : DEFAULT_KIT_MINT_DAYS * 24 * 60 * 60;
     const issuedAtMs = Date.now();
     const licenseKey = await generateLicenseKey(payload, keys.privateKey, expiresInSeconds, keys.publicKey);
     // Pair-match guard: prove the supplied public key can verify the JWT we just

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revealui/core",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "RevealUI's runtime engine — admin UI, REST API, auth, rich text, plugin system, and access control. The heart of the open-source platform.",
   "license": "MIT",
   "dependencies": {
@@ -23,10 +23,10 @@
     "pg": "^8.22.0",
     "yjs": "^13.6.31",
     "zod": "^4.4.3",
-    "@revealui/cache": "0.2.4",
-    "@revealui/contracts": "0.7.0",
+    "@revealui/cache": "0.2.5",
+    "@revealui/contracts": "0.8.0",
     "@revealui/resilience": "0.2.4",
-    "@revealui/security": "0.4.3",
+    "@revealui/security": "0.5.0",
     "@revealui/utils": "0.3.6"
   },
   "devDependencies": {