xcoder-dna 0.0.0-stage → 1.3.0

package/dist/license/gate.js

@@ -0,0 +1,188 @@
+// xcoder:version 4 | xcoder:task task-689517 | xcoder:updated 2026-11-01T09:16:05.783Z | xcoder:subtask code-st-828150
+// The single choke point for licensed features.
+//
+// Rules this module guarantees:
+//   * Fail closed. `requireLicense()` never throws and never does network I/O;
+//     a missing file, an EACCES, corrupt JSON or a broken trust anchor all
+//     resolve to `{ allowed: false }`.
+//   * One predicate. `isLicensedFeature()` is the only definition of what is
+//     gated, so a new command cannot acquire a licence check by accident.
+//   * Offline by default. Refresh is opportunistic and runs only AFTER the
+//     gate has passed, so an unreachable server never blocks a paid user.
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { verifyReceipt } from "./receipt.js";
+import { createLicenseStore, resolveCandidateFiles } from "./store.js";
+import { primaryStatePath } from "./state-paths.js";
+import { decodeStateFile, recordFromClaims, writeStateFile } from "./state-codec.js";
+import { createLicenseApi } from "./http-client.js";
+import { createLicenseManager } from "./manager.js";
+import { LICENSE_API_BASE_URL, LICENSE_ISSUER, LICENSE_PRODUCT_ID, TRUST_ANCHOR } from "./trust-anchor.js";
+import { DENIAL_DETAIL } from "./types.js";
+/** Exit code for "this command needs an active license". */
+export const LICENSE_REQUIRED_EXIT_CODE = 4;
+/**
+ * The licensed surface: entering the SDLC orchestrator run loop.
+ * Everything else (index, status, backlog, sprint status/retro/abort,
+ * browse, observe, bench, test, swarm, task, release, license) stays ungated.
+ */
+const LICENSED_FEATURES = new Set(["run", "resume", "sprint-start"]);
+export function isLicensedFeature(commandPath) {
+    return LICENSED_FEATURES.has(commandPath.trim().toLowerCase());
+}
+/** True when an activation file is present but the store could not parse it. */
+function activationFileExists(file) {
+    try {
+        return fs.existsSync(file);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Upgrade a verified pre-unification record into the shared store.
+ *
+ * This is the adopt-on-read half of the shared-state fix: a user who activated
+ * with v3 (or an older v1) keeps their seat, and the very next command in any
+ * binary finds the activation at the shared path. Best-effort by contract — a
+ * failed write must never block a paid user.
+ */
+function adoptLegacy(claims, receipt, installationId) {
+    try {
+        // Keep the machine identity the legacy record already carried: a fresh id
+        // would make this machine look like a second installation to the server.
+        const id = installationId ?? createLicenseStore().readInstallation()?.installationId ?? randomUUID();
+        // The verified receipt MUST survive the upgrade: without it the rewritten
+        // file decodes as incomplete and the next command asks for a key again —
+        // the very bug this adoption exists to fix.
+        writeStateFile(primaryStatePath(), recordFromClaims(claims, { installationId: id, receipt }));
+    }
+    catch {
+        // Never fatal: the gate already has verified claims to return.
+    }
+}
+/**
+ * The hint a denial prints. Per-tree, so a v1 user is told v1's own binary
+ * name rather than another tree's command.
+ */
+export const ACTIVATE_COMMAND = "xcoder license activate";
+function denialMessage(reason) {
+    return `licensed feature unavailable (${reason}: ${DENIAL_DETAIL[reason]}) — run \`${ACTIVATE_COMMAND}\``;
+}
+function isDenialReason(value) {
+    return typeof value === "string" && value in DENIAL_DETAIL;
+}
+/**
+ * Decide whether a licensed feature may run.
+ *
+ * Never throws, never touches the network. Returns the verified claims on
+ * success so the caller does not have to re-read the store.
+ */
+export function requireLicense(opts) {
+    let reason = null;
+    let claims = null;
+    try {
+        const store = opts?.store ?? createLicenseStore();
+        const anchor = opts?.anchor ?? TRUST_ANCHOR;
+        const now = opts?.now ?? (() => Date.now());
+        // An injected store is a fixture: read exactly the file it owns. The
+        // production path walks the shared discovery list so ONE activation made by
+        // any xcoder binary satisfies every other one on the machine.
+        const files = opts?.store ? [path.join(store.dir, "activation.json")] : resolveCandidateFiles();
+        let sawDecodableReceipt = false;
+        let sawUnreadableStore = false;
+        for (const file of files) {
+            const decoded = decodeStateFile(file);
+            // A pre-unification record carries a receipt but none of the activation
+            // fields. It is a candidate all the same: verify the receipt and, if it
+            // holds, adopt it into the shared store on first use.
+            const legacy = !decoded.ok && decoded.reason === "host-legacy" ? decoded.partial : null;
+            const receipt = decoded.ok ? decoded.record.receipt : legacy ? legacy.receipt : null;
+            if (receipt) {
+                sawDecodableReceipt = true;
+                const result = verifyReceipt(receipt, {
+                    publicKeyPem: anchor.publicKeyPem,
+                    pinnedPublicKeyPem: anchor.publicKeyPem,
+                    issuer: LICENSE_ISSUER,
+                    audience: LICENSE_PRODUCT_ID,
+                    now: now(),
+                });
+                if (result.ok) {
+                    claims = result.claims;
+                    if (legacy && !opts?.store)
+                        adoptLegacy(result.claims, receipt, legacy.installationId);
+                    break;
+                }
+                // Keep the most specific verdict seen so far; candidates are ordered by
+                // priority, so a later, lower-priority file never overwrites it.
+                if (!reason)
+                    reason = isDenialReason(result.reason) ? result.reason : "corrupt-store";
+                continue;
+            }
+            // The store never deletes anything, so the gate is the layer that tells
+            // "unreadable" apart from "not activated yet" (and from a record that is
+            // merely awaiting the schema upgrade).
+            if (!decoded.ok && decoded.reason !== "absent" && decoded.reason !== "incomplete") {
+                sawUnreadableStore = true;
+            }
+            else if (activationFileExists(file)) {
+                sawUnreadableStore = true;
+            }
+        }
+        if (!claims) {
+            if (sawUnreadableStore)
+                reason = "corrupt-store";
+            else if (!sawDecodableReceipt)
+                reason = "no-activation";
+        }
+    }
+    catch {
+        // Any unexpected fault (EACCES, unreadable dir, bad anchor) fails closed
+        // and is reported as a corrupt store rather than leaking internals.
+        reason = "corrupt-store";
+        claims = null;
+    }
+    if (claims)
+        return { allowed: true, claims };
+    const denied = reason ?? "corrupt-store";
+    return { allowed: false, reason: denied, message: denialMessage(denied) };
+}
+/** Hard ceiling on an opportunistic refresh; never blocks for longer. */
+const REFRESH_TIMEOUT_MS = 5_000;
+/**
+ * Opportunity-refresh after a successful gate. Best-effort by contract: any
+ * failure is swallowed so an offline machine still runs the command.
+ */
+export async function maybeRefreshLicense(mgr, now) {
+    try {
+        const status = mgr.status(now ? now() : undefined);
+        if (!status.activation || !status.needsRefresh)
+            return;
+        await withTimeout(mgr.refresh(), REFRESH_TIMEOUT_MS);
+    }
+    catch {
+        // Deliberately ignored — the caller logs at dim level at most.
+    }
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("license refresh timed out")), ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/** Build a manager with production wiring (used by licensed call sites). */
+export function createDefaultLicenseManager(api, store) {
+    return createLicenseManager({
+        store: store ?? createLicenseStore(),
+        api: api ?? createLicenseApi({ baseUrl: LICENSE_API_BASE_URL, retries: 1 }),
+        anchor: TRUST_ANCHOR,
+    });
+}

package/dist/license/http-client.d.ts

@@ -0,0 +1,43 @@
+import type { LicenseClaims } from "./types.js";
+export interface ActivationRequest {
+    serialKey: string;
+    productId: "xcoder-sdlc-cli";
+    installationId: string;
+    label?: string;
+}
+export interface RefreshRequest {
+    activationId: string;
+    installationId: string;
+}
+export interface ReleaseRequest {
+    activationId: string;
+    installationId: string;
+}
+export interface ActivationResponse {
+    receipt: string;
+    activationId: string;
+    claims: LicenseClaims;
+    /** INFORMATIONAL. Never a trust anchor. Never read. */
+    publicKey?: string;
+}
+export type LicenseApiErrorKind = "invalid-input" | "license-invalid" | "seat-limit" | "network" | "timeout" | "server" | "bad-response";
+export declare class LicenseApiError extends Error {
+    readonly kind: LicenseApiErrorKind;
+    readonly status?: number;
+    constructor(kind: LicenseApiErrorKind, message: string, status?: number);
+}
+export interface LicenseApi {
+    activate(req: ActivationRequest, signal?: AbortSignal): Promise<ActivationResponse>;
+    refresh(req: RefreshRequest, signal?: AbortSignal): Promise<ActivationResponse>;
+    release(req: ReleaseRequest, signal?: AbortSignal): Promise<void>;
+}
+export interface HttpClientOptions {
+    baseUrl: string;
+    /** Default 5_000 ms; clamped to a 10_000 ms hard ceiling. */
+    timeoutMs?: number;
+    /** Injection point for tests; defaults to the platform fetch. */
+    fetchImpl?: typeof fetch;
+    /** Retries for transient failures. Defaults to 0. */
+    retries?: number;
+}
+export declare function createLicenseApi(opts: HttpClientOptions): LicenseApi;

package/dist/license/http-client.js

@@ -0,0 +1,195 @@
+// xcoder:version 3 | xcoder:task task-689517 | xcoder:updated 2026-11-01T08:22:46.853Z | xcoder:subtask code-st-828150
+// Typed HTTP access to the Key System activation API.
+//
+// Every response body is treated as hostile input and zod-validated before
+// use — this includes the `publicKey` field, which is *discarded*: a
+// server-supplied key must never become a trust anchor. Trust in the receipt
+// is decided in exactly one place (receipt.ts) against the build-pinned key.
+import { z } from "zod";
+export class LicenseApiError extends Error {
+    kind;
+    status;
+    constructor(kind, message, status) {
+        super(message);
+        this.name = "LicenseApiError";
+        this.kind = kind;
+        this.status = status;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 10_000;
+/**
+ * Hard ceiling on a response body. A receipt is a few hundred bytes; anything
+ * near this is a misrouted or hostile endpoint, and buffering it unbounded is
+ * a cheap denial-of-service against the caller.
+ */
+const MAX_RESPONSE_BYTES = 64 * 1024;
+/**
+ * Refuse an oversized body, then read it.
+ *
+ * `content-length` is advisory (a hostile server can understate or omit it), so
+ * the declared size is a fast reject and the actual length is re-checked after
+ * the read. Neither path silently truncates: a truncated receipt would fail
+ * signature verification anyway, and the honest verdict is `bad-response`.
+ */
+async function readBounded(response) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+        throw new LicenseApiError("bad-response", USER_MESSAGE["bad-response"], response.status);
+    }
+    const text = await response.text();
+    if (text.length > MAX_RESPONSE_BYTES) {
+        throw new LicenseApiError("bad-response", USER_MESSAGE["bad-response"], response.status);
+    }
+    return text;
+}
+const ClaimsSchema = z.strictObject({
+    iss: z.string().min(1),
+    aud: z.string().min(1),
+    licenseId: z.string().min(1),
+    activationId: z.string().min(1),
+    plan: z.string().min(1),
+    issuedAt: z.string().min(1),
+    expiresAt: z.string().min(1),
+    refreshBy: z.string().min(1),
+});
+const ActivationResponseSchema = z.object({
+    receipt: z.string().min(1).max(8 * 1024),
+    activationId: z.string().min(1).max(256),
+    claims: ClaimsSchema,
+    publicKey: z.string().optional(), // parsed, then intentionally ignored
+});
+const ErrorBodySchema = z.object({ error: z.object({ code: z.string().min(1) }) });
+const USER_MESSAGE = {
+    "invalid-input": "the serial key was rejected as malformed",
+    "license-invalid": "the serial key is not valid",
+    "seat-limit": "this serial key has no free seats left",
+    network: "could not reach the license server",
+    timeout: "the license server did not respond in time",
+    server: "the license server reported an error",
+    "bad-response": "the license server returned an unexpected response",
+};
+function statusToKind(status) {
+    if (status === 400)
+        return "invalid-input";
+    if (status === 403)
+        return "license-invalid";
+    if (status === 409)
+        return "seat-limit";
+    if (status >= 500)
+        return "server";
+    if (status >= 200 && status < 300)
+        return null;
+    // Any other 4xx (e.g. 404/429) is a deployment/surface problem, not a
+    // user-actionable license state — surface it as a bad response.
+    return "bad-response";
+}
+function isRetryable(kind) {
+    return kind === "network" || kind === "timeout" || kind === "server";
+}
+function readErrorCode(text) {
+    try {
+        const parsed = ErrorBodySchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data.error.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createLicenseApi(opts) {
+    const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = Math.min(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const retries = Math.max(0, opts.retries ?? 0);
+    async function once(url, body, outerSignal) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const onOuterAbort = () => controller.abort();
+        outerSignal?.addEventListener("abort", onOuterAbort, { once: true });
+        try {
+            return await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json", accept: "application/json" },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+                // A license endpoint never legitimately redirects. Following one would
+                // hand the serial key to whatever host the redirect names, so a 3xx is
+                // a hard transport failure rather than a transparent hop.
+                redirect: "error",
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            outerSignal?.removeEventListener("abort", onOuterAbort);
+        }
+    }
+    async function post(path, body, outerSignal) {
+        for (let attempt = 0; attempt <= retries; attempt += 1) {
+            const lastAttempt = attempt === retries;
+            let response;
+            try {
+                response = await once(`${baseUrl}${path}`, body, outerSignal);
+            }
+            catch (err) {
+                // An abort surfaces as AbortError (web fetch) or a DOMException-ish
+                // error whose name is "AbortError"; anything else is a transport fault.
+                const kind = err?.name === "AbortError" ? "timeout" : "network";
+                if (!lastAttempt && isRetryable(kind))
+                    continue;
+                throw new LicenseApiError(kind, USER_MESSAGE[kind]);
+            }
+            let text;
+            try {
+                text = await readBounded(response);
+            }
+            catch (err) {
+                if (err instanceof LicenseApiError)
+                    throw err;
+                if (!lastAttempt)
+                    continue;
+                throw new LicenseApiError("network", USER_MESSAGE.network);
+            }
+            const kind = statusToKind(response.status);
+            if (kind === null)
+                return text;
+            const code = readErrorCode(text);
+            if (!lastAttempt && isRetryable(kind))
+                continue;
+            const message = code ? `${USER_MESSAGE[kind]} (${code})` : USER_MESSAGE[kind];
+            throw new LicenseApiError(kind, message, response.status);
+        }
+        // Unreachable: the loop either returns or throws.
+        throw new LicenseApiError("network", USER_MESSAGE.network);
+    }
+    function parseActivation(text) {
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            throw new LicenseApiError("bad-response", USER_MESSAGE["bad-response"]);
+        }
+        const parsed = ActivationResponseSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new LicenseApiError("bad-response", USER_MESSAGE["bad-response"]);
+        }
+        // `publicKey` is dropped here on purpose: it is parsed only so the schema
+        // stays honest about the wire shape, never used as a trust anchor.
+        return {
+            receipt: parsed.data.receipt,
+            activationId: parsed.data.activationId,
+            claims: parsed.data.claims,
+        };
+    }
+    return {
+        async activate(req, signal) {
+            return parseActivation(await post("/activations", req, signal));
+        },
+        async refresh(req, signal) {
+            return parseActivation(await post("/activations/refresh", req, signal));
+        },
+        async release(req, signal) {
+            await post("/activations/release", req, signal);
+        },
+    };
+}

package/dist/license/manager.d.ts

@@ -0,0 +1,39 @@
+import type { LicenseApi } from "./http-client.js";
+import type { LicenseStore, ActivationRecord } from "./store.js";
+import type { VerifyResult } from "./types.js";
+import { type TrustAnchor } from "./trust-anchor.js";
+/** Opportunistic refresh starts this far before `refreshBy`. */
+export declare const REFRESH_WINDOW_MS: number;
+export interface LicenseStatus {
+    activation: ActivationRecord | null;
+    /** The verification verdict at `now`; never throws. */
+    verification: VerifyResult | {
+        ok: false;
+        reason: "no-activation";
+    };
+    /** True when now >= refreshBy - REFRESH_WINDOW_MS. */
+    needsRefresh: boolean;
+}
+export interface LicenseManager {
+    activate(input: {
+        serialKey: string;
+        label?: string;
+    }): Promise<ActivationRecord>;
+    refresh(): Promise<ActivationRecord>;
+    release(): Promise<void>;
+    status(now?: number): LicenseStatus;
+}
+export interface LicenseManagerDeps {
+    store: LicenseStore;
+    api: LicenseApi;
+    anchor: TrustAnchor;
+    now?: () => number;
+}
+/**
+ * Normalise and sanity-check a serial key locally, before any network call.
+ * Throws a typed `invalid-input` so the CLI has one error shape to print.
+ */
+export declare function normalizeSerialKey(raw: string): string;
+/** Short, non-reversible stand-in used for logging/debugging only. */
+export declare function fingerprintSerialKey(serialKey: string): string;
+export declare function createLicenseManager(deps: LicenseManagerDeps): LicenseManager;

package/dist/license/manager.js

@@ -0,0 +1,175 @@
+// xcoder:version 4 | xcoder:task task-689517 | xcoder:updated 2026-11-01T08:22:08.457Z | xcoder:subtask code-st-828150
+// License use-cases: activate / refresh / release / status.
+//
+// Composes the store, the HTTP client and the pure verifier. No CLI
+// formatting and no process exit here — those belong to the command layer,
+// so every rule below is unit-testable without spawning a process.
+//
+// The two rules the acceptance criteria hang on:
+//   * a receipt is verified BEFORE it is persisted, so a bad or malicious
+//     server response can never be written to disk;
+//   * a refresh can never extend validity — the new receipt is persisted
+//     only when its offline window is at least as long as the old one.
+import { createHash } from "node:crypto";
+import { verifyReceipt, validUntilMs } from "./receipt.js";
+import { LicenseApiError } from "./http-client.js";
+import { recordFromClaims } from "./state-codec.js";
+import { LICENSE_ISSUER, LICENSE_PRODUCT_ID, RECEIPT_TTL_MS } from "./trust-anchor.js";
+/** Opportunistic refresh starts this far before `refreshBy`. */
+export const REFRESH_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Local, pre-network sanity limits on a serial key. */
+const SERIAL_KEY_MAX_LENGTH = 200;
+const SERIAL_KEY_PATTERN = /^[A-Z0-9-]+$/;
+/**
+ * Normalise and sanity-check a serial key locally, before any network call.
+ * Throws a typed `invalid-input` so the CLI has one error shape to print.
+ */
+export function normalizeSerialKey(raw) {
+    const trimmed = typeof raw === "string" ? raw.trim().toUpperCase() : "";
+    // Reject control characters outright; never echo the value back.
+    if (!trimmed || trimmed.length > SERIAL_KEY_MAX_LENGTH || /[\u0000-\u001f\u007f]/.test(trimmed)) {
+        throw new LicenseApiError("invalid-input", "the serial key was rejected as malformed");
+    }
+    if (!SERIAL_KEY_PATTERN.test(trimmed)) {
+        throw new LicenseApiError("invalid-input", "the serial key contains unsupported characters");
+    }
+    return trimmed;
+}
+/** Short, non-reversible stand-in used for logging/debugging only. */
+export function fingerprintSerialKey(serialKey) {
+    return createHash("sha256").update(serialKey).digest("hex").slice(0, 12);
+}
+function denialToApiError(reason) {
+    return new LicenseApiError("bad-response", `the license server returned a receipt this build does not trust (${reason})`);
+}
+export function createLicenseManager(deps) {
+    const { store, api, anchor } = deps;
+    const now = deps.now ?? (() => Date.now());
+    function verify(rawReceipt, at) {
+        return verifyReceipt(rawReceipt, {
+            publicKeyPem: anchor.publicKeyPem,
+            pinnedPublicKeyPem: anchor.publicKeyPem,
+            issuer: LICENSE_ISSUER,
+            audience: LICENSE_PRODUCT_ID,
+            now: at,
+        });
+    }
+    /**
+     * Persistable record, projected from VERIFIED claims.
+     *
+     * The activation id comes from the claims too: the wire `activationId` is
+     * only an echo of the request, while the claims are what the pinned key
+     * actually signed. `recordFromClaims` (state-codec) keeps this in step with
+     * the shared on-disk schema the other two binaries read.
+     */
+    function toRecord(response, claims, installationId) {
+        const projected = recordFromClaims(claims, {
+            installationId,
+            receipt: response.receipt,
+            savedAt: new Date(now()).toISOString(),
+        });
+        return {
+            activationId: projected.activationId,
+            licenseId: projected.licenseId,
+            plan: projected.plan,
+            receipt: projected.receipt,
+            expiresAt: projected.expiresAt,
+            refreshBy: projected.refreshBy,
+            savedAt: projected.savedAt,
+        };
+    }
+    return {
+        async activate(input) {
+            const serialKey = normalizeSerialKey(input.serialKey);
+            const installation = store.ensureInstallation();
+            const response = await api.activate({
+                serialKey,
+                productId: LICENSE_PRODUCT_ID,
+                installationId: installation.installationId,
+                ...(input.label ? { label: input.label.slice(0, 120) } : {}),
+            });
+            // Verify BEFORE persisting: an untrusted receipt is never written.
+            const verdict = verify(response.receipt, now());
+            if (!verdict.ok)
+                throw denialToApiError(verdict.reason);
+            const record = toRecord(response, verdict.claims, installation.installationId);
+            store.writeActivation(record); // replace, never append (AC3)
+            return record;
+        },
+        async refresh() {
+            const existing = store.readActivation();
+            if (!existing) {
+                throw new LicenseApiError("license-invalid", "there is no activation to refresh — run `xcoder license activate`");
+            }
+            const installation = store.readInstallation();
+            if (!installation) {
+                throw new LicenseApiError("license-invalid", "this machine has no installation id — run `xcoder license activate`");
+            }
+            // A refresh failing throws; the stored record is left untouched, so a
+            // failed refresh can never extend validity.
+            const response = await api.refresh({
+                activationId: existing.activationId,
+                installationId: installation.installationId,
+            });
+            const verdict = verify(response.receipt, now());
+            if (!verdict.ok)
+                throw denialToApiError(verdict.reason);
+            // Never shorten. Also re-assert the TTL bound against the old window so
+            // a compromised server cannot push the deadline arbitrarily far out.
+            // The stored record carries the verified claims' expiresAt/refreshBy,
+            // so this is exactly validUntilMs() of the previous receipt.
+            const previousUntil = Math.min(Date.parse(existing.expiresAt), Date.parse(existing.refreshBy));
+            const nextUntil = validUntilMs(verdict.claims);
+            const issuedAt = Date.parse(verdict.claims.issuedAt);
+            const ttlBound = Math.min(Date.parse(verdict.claims.expiresAt), issuedAt + RECEIPT_TTL_MS);
+            if (Date.parse(verdict.claims.refreshBy) > ttlBound)
+                throw denialToApiError("malformed-receipt");
+            if (Number.isNaN(nextUntil) || nextUntil < previousUntil)
+                throw denialToApiError("malformed-receipt");
+            const record = toRecord(response, verdict.claims, installation.installationId);
+            store.writeActivation(record);
+            return record;
+        },
+        async release() {
+            const existing = store.readActivation();
+            if (!existing)
+                return; // nothing activated locally — nothing to free
+            const installation = store.readInstallation();
+            if (!installation) {
+                store.clearActivation();
+                return;
+            }
+            try {
+                await api.release({
+                    activationId: existing.activationId,
+                    installationId: installation.installationId,
+                });
+                store.clearActivation();
+            }
+            catch (err) {
+                const kind = err instanceof LicenseApiError ? err.kind : undefined;
+                // The seat is already gone server-side if the activation is unknown
+                // or revoked — clear locally so the user is not stuck.
+                if (kind === "license-invalid") {
+                    store.clearActivation();
+                    return;
+                }
+                // network / timeout / server: keep local state so the user can retry.
+                throw err instanceof LicenseApiError
+                    ? err
+                    : new LicenseApiError("network", "could not reach the license server");
+            }
+        },
+        status(at) {
+            const moment = at ?? now();
+            const activation = store.readActivation();
+            if (!activation) {
+                return { activation: null, verification: { ok: false, reason: "no-activation" }, needsRefresh: false };
+            }
+            const verification = verify(activation.receipt, moment);
+            const refreshBy = Date.parse(activation.refreshBy);
+            const needsRefresh = !Number.isNaN(refreshBy) && moment >= refreshBy - REFRESH_WINDOW_MS;
+            return { activation, verification, needsRefresh };
+        },
+    };
+}

package/dist/license/receipt.d.ts

@@ -0,0 +1,27 @@
+import type { LicenseClaims, VerifyResult } from "./types.js";
+export interface VerifyContext {
+    publicKeyPem: string;
+    issuer: string;
+    audience: string;
+    /** Epoch ms — injected, never read from the ambient clock. */
+    now: number;
+    /** Tolerance for `not-yet-valid`. Defaults to 60 s. */
+    clockSkewMs?: number;
+    /**
+     * The single key this build trusts. When supplied, a `publicKeyPem` that
+     * differs from it is rejected as `untrusted-key` *before* any signature is
+     * checked — a receipt is never validated against a key that is not pinned.
+     */
+    pinnedPublicKeyPem?: string;
+}
+/**
+ * Single source of truth for the offline window: a receipt is usable until
+ * whichever comes first, its subscription expiry or its refresh deadline.
+ */
+export declare function validUntilMs(claims: LicenseClaims): number;
+/**
+ * Verify a signed receipt against a pinned key.
+ *
+ * Pure and total: returns a typed result for every input, including garbage.
+ */
+export declare function verifyReceipt(rawReceipt: string, ctx: VerifyContext): VerifyResult;