xcoder-dna 0.0.0-stage → 1.3.0

package/dist/license/receipt.js

@@ -0,0 +1,108 @@
+// xcoder:version 1 | xcoder:task task-1d9460 | xcoder:updated 2026-10-25T17:01:39.466Z | xcoder:subtask code-st-4b0403
+// Pure offline receipt verification.
+//
+// No network, no filesystem, no `process`, no hidden Date.now(): the clock is
+// injected so the gate, the manager and the tests all agree on "now".
+//
+// Receipt format: `<base64url(claims JSON)>.<base64url(ed25519 signature)>`
+// where the signature is over the ASCII bytes of segment 0, exactly as
+// transmitted. Verification order is deliberate: the signature is checked
+// before any claim is interpreted, so attacker-chosen claims are never
+// treated as authority.
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { z } from "zod";
+import { RECEIPT_TTL_MS } from "./trust-anchor.js";
+/** Receipts larger than this are rejected before any decoding work. */
+const MAX_RECEIPT_BYTES = 8 * 1024;
+/** Default tolerance for clock drift when checking `issuedAt`. */
+const DEFAULT_CLOCK_SKEW_MS = 60_000;
+const LicenseClaimsSchema = z.strictObject({
+    iss: z.string().min(1).max(512),
+    aud: z.string().min(1).max(256),
+    licenseId: z.string().min(1).max(256),
+    activationId: z.string().min(1).max(256),
+    plan: z.string().min(1).max(64),
+    issuedAt: z.string().min(1).max(64),
+    expiresAt: z.string().min(1).max(64),
+    refreshBy: z.string().min(1).max(64),
+});
+/**
+ * Single source of truth for the offline window: a receipt is usable until
+ * whichever comes first, its subscription expiry or its refresh deadline.
+ */
+export function validUntilMs(claims) {
+    return Math.min(Date.parse(claims.expiresAt), Date.parse(claims.refreshBy));
+}
+function normalizePem(pem) {
+    return pem.replace(/\r\n/g, "\n").trim();
+}
+/**
+ * Verify a signed receipt against a pinned key.
+ *
+ * Pure and total: returns a typed result for every input, including garbage.
+ */
+export function verifyReceipt(rawReceipt, ctx) {
+    // 0. The caller may only ever verify with the pinned key.
+    if (ctx.pinnedPublicKeyPem !== undefined && normalizePem(ctx.publicKeyPem) !== normalizePem(ctx.pinnedPublicKeyPem)) {
+        return { ok: false, reason: "untrusted-key", detail: "verification key is not the pinned key" };
+    }
+    // 1. Shape: exactly two segments, bounded size.
+    if (typeof rawReceipt !== "string")
+        return { ok: false, reason: "malformed-receipt" };
+    if (Buffer.byteLength(rawReceipt, "utf8") > MAX_RECEIPT_BYTES) {
+        return { ok: false, reason: "malformed-receipt", detail: "receipt exceeds 8 KiB" };
+    }
+    const segments = rawReceipt.split(".");
+    if (segments.length !== 2 || segments[0].length === 0 || segments[1].length === 0) {
+        return { ok: false, reason: "malformed-receipt", detail: "expected two segments" };
+    }
+    const [payloadSegment, signatureSegment] = segments;
+    // 2. Decode + schema-validate the claims (still untrusted at this point).
+    let claims;
+    try {
+        const json = Buffer.from(payloadSegment, "base64url").toString("utf8");
+        claims = LicenseClaimsSchema.parse(JSON.parse(json));
+    }
+    catch {
+        return { ok: false, reason: "malformed-receipt" };
+    }
+    // 3. Signature over the transmitted segment bytes.
+    try {
+        const key = createPublicKey(ctx.publicKeyPem);
+        const signature = Buffer.from(signatureSegment, "base64url");
+        const signed = Buffer.from(payloadSegment, "utf8");
+        if (!cryptoVerify(null, signed, key, signature)) {
+            return { ok: false, reason: "bad-signature" };
+        }
+    }
+    catch {
+        return { ok: false, reason: "bad-signature" };
+    }
+    // ── Everything below runs only on a receipt whose signature verified. ──
+    // 4. Timestamps must be parseable before they are compared.
+    const issuedAt = Date.parse(claims.issuedAt);
+    const expiresAt = Date.parse(claims.expiresAt);
+    const refreshBy = Date.parse(claims.refreshBy);
+    if (Number.isNaN(issuedAt) || Number.isNaN(expiresAt) || Number.isNaN(refreshBy)) {
+        return { ok: false, reason: "malformed-receipt", detail: "unparseable timestamp" };
+    }
+    // 5. Defence in depth against a compromised or misconfigured issuer: a
+    //    receipt can never claim a longer offline window than the TTL allows.
+    if (refreshBy > Math.min(expiresAt, issuedAt + RECEIPT_TTL_MS)) {
+        return { ok: false, reason: "malformed-receipt", detail: "refreshBy exceeds the maximum window" };
+    }
+    // 6. Issuer / audience pinning.
+    if (claims.iss !== ctx.issuer)
+        return { ok: false, reason: "wrong-issuer" };
+    if (claims.aud !== ctx.audience)
+        return { ok: false, reason: "wrong-audience" };
+    // 7. Validity window, in order of user-actionability.
+    const skew = ctx.clockSkewMs ?? DEFAULT_CLOCK_SKEW_MS;
+    if (ctx.now + skew < issuedAt)
+        return { ok: false, reason: "not-yet-valid" };
+    if (ctx.now >= expiresAt)
+        return { ok: false, reason: "expired" };
+    if (ctx.now >= refreshBy)
+        return { ok: false, reason: "refresh-overdue" };
+    return { ok: true, claims };
+}

package/dist/license/state-codec.d.ts

@@ -0,0 +1,72 @@
+export type StateCandidateKind = 'override' | 'canonical' | 'legacy-host';
+export interface SharedActivationRecord {
+    version: 1;
+    installationId: string;
+    activationId: string;
+    licenseId: string;
+    plan: string;
+    receipt: string;
+    expiresAt: string;
+    refreshBy: string;
+    savedAt: string;
+    lastSeenAt?: string;
+    lastRefreshAttemptAt?: string;
+}
+/** The parts of a store that exist before a receipt does. */
+export interface IncompleteState {
+    version: 1;
+    installationId: string;
+    lastSeenAt?: string;
+    lastRefreshAttemptAt?: string;
+}
+/** A pre-unification record: identity plus a receipt, no activation fields. */
+export interface HostLegacyState extends IncompleteState {
+    receipt: string;
+}
+export type DecodeFailure = 'absent' | 'incomplete' | 'host-legacy' | 'corrupt' | 'unsafe-file' | 'schema';
+export type DecodeResult = {
+    ok: true;
+    record: SharedActivationRecord;
+} | {
+    ok: false;
+    reason: 'incomplete';
+    partial: IncompleteState;
+} | {
+    ok: false;
+    reason: 'host-legacy';
+    partial: HostLegacyState;
+} | {
+    ok: false;
+    reason: Exclude<DecodeFailure, 'incomplete' | 'host-legacy'>;
+};
+/** The verified claims a record is projected from. */
+export interface VerifiedClaimsShape {
+    licenseId: string;
+    activationId: string;
+    plan: string;
+    expiresAt: string;
+    refreshBy: string;
+}
+/** What can legitimately sit at the shared path. */
+export type PersistedState = SharedActivationRecord | IncompleteState;
+/**
+ * Read + validate one state file. Never throws.
+ *
+ * Symlinks and non-regular files are refused BEFORE reading: the receipt store
+ * is the local trust boundary, so following a link out of it is not supported.
+ */
+export declare function decodeStateFile(file: string): DecodeResult;
+/**
+ * Project VERIFIED claims into the shared record.
+ *
+ * The only trusted source of expiresAt/refreshBy/plan/ids is the receipt that
+ * just verified; prior contributes bookkeeping and is deliberately unable to
+ * override validity fields.
+ */
+export declare function recordFromClaims(claims: VerifiedClaimsShape, prior?: Partial<SharedActivationRecord>): SharedActivationRecord;
+/**
+ * Atomic replace: write a temp file in the target directory, then rename.
+ * Mode 0600 inside a 0700 directory; on Windows the ACLs govern access and the
+ * chmod calls are best-effort.
+ */
+export declare function writeStateFile(file: string, record: PersistedState): void;

package/dist/license/state-codec.js

@@ -0,0 +1,218 @@
+// xcoder:version 1 | xcoder:task task-689517 | xcoder:updated 2026-11-01T08:20:37.423Z | xcoder:subtask code-st-828150
+// C2 — StateCodec (v1 tree).
+//
+// One JSON object, readable by ALL THREE xcoder readers with no change to any
+// of them: v3 host, ronin, and v1. SharedActivationRecord is the union
+// (superset) of every reader required subset, and every reader tolerates
+// unknown keys, so one file satisfies all of them.
+//
+// Invariants:
+//   1. DECODE NEVER THROWS. Every failure is a typed reason, so the gate keeps
+//      its fail-closed contract instead of surfacing fs errors as crashes.
+//   2. VALIDITY COMES FROM THE RECEIPT. expiresAt/refreshBy/plan/ids are
+//      projected from VERIFIED claims (recordFromClaims), never trusted from
+//      the file, so hand-editing a record cannot widen its own window.
+//
+// Contains no secrets: the serial key is never written, only the signed public
+// receipt.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Files above this are refused unread: a state file is a few KiB. */
+const MAX_STATE_BYTES = 64 * 1024;
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function isUuid(value) {
+    return (typeof value === 'string' &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value));
+}
+/** Optional ISO field: absent is fine, present-but-garbage is dropped. */
+function optionalIso(value) {
+    const text = asString(value);
+    if (!text)
+        return undefined;
+    return Number.isFinite(Date.parse(text)) ? text : undefined;
+}
+/**
+ * Machine id for a record written before the shared schema existed. v1 and
+ * ronin kept installationId in installation.json next to the activation file;
+ * reading it (never writing it) lets those machines keep their seat.
+ */
+function legacyInstallationId(activationFile) {
+    try {
+        const sibling = path.join(path.dirname(activationFile), 'installation.json');
+        const stat = fs.lstatSync(sibling);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_STATE_BYTES)
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(sibling, 'utf8'));
+        return isRecord(parsed) && isUuid(parsed.installationId) ? parsed.installationId : null;
+    }
+    catch {
+        return null;
+    }
+}
+function bookkeeping(parsed, into) {
+    const seen = optionalIso(parsed.lastSeenAt);
+    if (seen)
+        into.lastSeenAt = seen;
+    const attempted = optionalIso(parsed.lastRefreshAttemptAt);
+    if (attempted)
+        into.lastRefreshAttemptAt = attempted;
+    return into;
+}
+/**
+ * Read + validate one state file. Never throws.
+ *
+ * Symlinks and non-regular files are refused BEFORE reading: the receipt store
+ * is the local trust boundary, so following a link out of it is not supported.
+ */
+export function decodeStateFile(file) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch {
+        return { ok: false, reason: 'absent' };
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return { ok: false, reason: 'unsafe-file' };
+    if (stat.size > MAX_STATE_BYTES)
+        return { ok: false, reason: 'corrupt' };
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { ok: false, reason: 'corrupt' };
+    }
+    if (!isRecord(parsed))
+        return { ok: false, reason: 'corrupt' };
+    // Machine identity first: it decides whether a receipt-less file is
+    // not-activated-yet (a valid bootstrap) or an unsupported shape.
+    const hasHostIdentity = parsed.version === 1 && isUuid(parsed.installationId);
+    let installationId;
+    if (hasHostIdentity) {
+        installationId = parsed.installationId;
+    }
+    else if (parsed.version === undefined) {
+        const legacy = legacyInstallationId(file);
+        if (!legacy)
+            return { ok: false, reason: 'schema' };
+        installationId = legacy;
+    }
+    else {
+        return { ok: false, reason: 'schema' };
+    }
+    const receipt = asString(parsed.receipt);
+    if (receipt === null) {
+        if (!hasHostIdentity)
+            return { ok: false, reason: 'schema' };
+        return { ok: false, reason: 'incomplete', partial: bookkeeping(parsed, { version: 1, installationId }) };
+    }
+    const activationId = asString(parsed.activationId);
+    const licenseId = asString(parsed.licenseId);
+    const plan = asString(parsed.plan);
+    const expiresAt = asString(parsed.expiresAt);
+    const refreshBy = asString(parsed.refreshBy);
+    const savedAt = asString(parsed.savedAt);
+    if (!activationId || !licenseId || !plan || !expiresAt || !refreshBy || !savedAt) {
+        // Not corrupt: the pre-unification record, which never carried these
+        // fields. Its validity is projected from the receipt by the reader.
+        if (hasHostIdentity) {
+            return {
+                ok: false,
+                reason: 'host-legacy',
+                partial: bookkeeping(parsed, { version: 1, installationId, receipt }),
+            };
+        }
+        return { ok: false, reason: 'schema' };
+    }
+    if (!Number.isFinite(Date.parse(expiresAt)) || !Number.isFinite(Date.parse(refreshBy))) {
+        return { ok: false, reason: 'schema' };
+    }
+    return {
+        ok: true,
+        record: bookkeeping(parsed, {
+            version: 1,
+            installationId,
+            activationId,
+            licenseId,
+            plan,
+            receipt,
+            expiresAt,
+            refreshBy,
+            savedAt,
+        }),
+    };
+}
+/**
+ * Project VERIFIED claims into the shared record.
+ *
+ * The only trusted source of expiresAt/refreshBy/plan/ids is the receipt that
+ * just verified; prior contributes bookkeeping and is deliberately unable to
+ * override validity fields.
+ */
+export function recordFromClaims(claims, prior) {
+    const record = {
+        version: 1,
+        installationId: isUuid(prior?.installationId) ? prior.installationId : randomUUID(),
+        activationId: claims.activationId,
+        licenseId: claims.licenseId,
+        plan: claims.plan,
+        receipt: prior?.receipt ?? '',
+        expiresAt: claims.expiresAt,
+        refreshBy: claims.refreshBy,
+        // Bookkeeping only — never a validity input.
+        savedAt: optionalIso(prior?.savedAt) ?? new Date().toISOString(),
+    };
+    if (prior?.lastSeenAt)
+        record.lastSeenAt = prior.lastSeenAt;
+    if (prior?.lastRefreshAttemptAt)
+        record.lastRefreshAttemptAt = prior.lastRefreshAttemptAt;
+    return record;
+}
+/**
+ * Atomic replace: write a temp file in the target directory, then rename.
+ * Mode 0600 inside a 0700 directory; on Windows the ACLs govern access and the
+ * chmod calls are best-effort.
+ */
+export function writeStateFile(file, record) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: FILE_MODE,
+        });
+        try {
+            fs.chmodSync(temp, FILE_MODE);
+        }
+        catch {
+            /* Windows ACLs govern file access. */
+        }
+        fs.renameSync(temp, file);
+        try {
+            fs.chmodSync(file, FILE_MODE);
+        }
+        catch {
+            /* Windows ACLs govern file access. */
+        }
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temp, { force: true });
+        }
+        catch {
+            /* keep the original error */
+        }
+        throw error;
+    }
+}

package/dist/license/state-paths.d.ts

@@ -0,0 +1,17 @@
+export type StateCandidateKind = 'override' | 'canonical' | 'legacy-host';
+export interface StateCandidate {
+    path: string;
+    kind: StateCandidateKind;
+}
+/** The one shared store every xcoder binary writes. */
+export declare function canonicalStatePath(): string;
+/**
+ * Discovery order for activation state. The env map is injectable so tests
+ * (and the parity harness) never have to mutate process.env.
+ */
+export declare function resolveStateCandidates(env?: NodeJS.ProcessEnv): StateCandidate[];
+/**
+ * The file this tree writes. Override when set (so an explicit target stays
+ * explicit), otherwise the canonical shared store.
+ */
+export declare function primaryStatePath(env?: NodeJS.ProcessEnv): string;

package/dist/license/state-paths.js

@@ -0,0 +1,64 @@
+// xcoder:version 1 | xcoder:task task-689517 | xcoder:updated 2026-11-01T08:20:11.715Z | xcoder:subtask code-st-828150
+// C1 — SharedStateResolver (v1 tree).
+//
+// Owns WHERE an activation may be found. Pure path algebra: no I/O, no fs, no
+// mkdir. The host and ronin trees carry byte-identical copies of this module;
+// the three are duplicated (not shared) because the layering guard forbids
+// cross-tree imports, and scripts/license-state-parity.test.mjs turns any drift
+// into a red test.
+//
+// Why v1 must use the same list: v1 shipped with its OWN activation.json plus
+// its own (wrong) API base URL, so a key activated by v3 was invisible here and
+// a key activated here was invisible to v3. Sharing the discovery order is what
+// makes ONE activation cover every binary on the machine.
+//
+// Order:
+//   1. $XCODER_LICENSE_FILE                                  -> override
+//   2. <homedir>/.xcoder/license/activation.json             -> canonical
+//   3. <dirname($XCODER_CONFIG_FILE or ~/.xcoder/config.json)>/license.json
+//                                                            -> legacy-host
+//
+// The override SHORT-CIRCUITS the list on purpose. It is the documented
+// point-this-binary-somewhere-else switch, so it must not fall back to the real
+// user store: an explicit override that silently read the ambient activation
+// would make every fixture-based test depend on the developer home directory,
+// and would make setting the override a lie.
+import os from 'node:os';
+import path from 'node:path';
+/** The one shared store every xcoder binary writes. */
+export function canonicalStatePath() {
+    return path.join(os.homedir(), '.xcoder', 'license', 'activation.json');
+}
+/**
+ * Discovery order for activation state. The env map is injectable so tests
+ * (and the parity harness) never have to mutate process.env.
+ */
+export function resolveStateCandidates(env = process.env) {
+    const override = (env.XCODER_LICENSE_FILE ?? '').trim();
+    if (override)
+        return [{ path: path.resolve(override), kind: 'override' }];
+    // Mirrors userConfigPath() without importing it, so candidate discovery
+    // stays env-pure and identical in every tree.
+    const configPath = (env.XCODER_CONFIG_FILE ?? '').trim() || path.join(os.homedir(), '.xcoder', 'config.json');
+    const legacyHost = path.join(path.dirname(configPath), 'license.json');
+    const ordered = [
+        { path: canonicalStatePath(), kind: 'canonical' },
+        { path: legacyHost, kind: 'legacy-host' },
+    ];
+    // The default config path makes candidate 3 collide with candidate 2.
+    const seen = new Set();
+    return ordered.filter((candidate) => {
+        const key = path.resolve(candidate.path).toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * The file this tree writes. Override when set (so an explicit target stays
+ * explicit), otherwise the canonical shared store.
+ */
+export function primaryStatePath(env = process.env) {
+    return resolveStateCandidates(env)[0].path;
+}

package/dist/license/store.d.ts

@@ -0,0 +1,44 @@
+export interface InstallationRecord {
+    installationId: string;
+    createdAt: string;
+}
+export interface ActivationRecord {
+    activationId: string;
+    licenseId: string;
+    plan: string;
+    /** The signed receipt; contains no serial key. */
+    receipt: string;
+    expiresAt: string;
+    refreshBy: string;
+    savedAt: string;
+}
+export interface LicenseStore {
+    readonly dir: string;
+    readInstallation(): InstallationRecord | null;
+    /** Creates the UUID exactly once, atomically; concurrent callers agree. */
+    ensureInstallation(): InstallationRecord;
+    readActivation(): ActivationRecord | null;
+    writeActivation(rec: ActivationRecord): void;
+    clearActivation(): void;
+}
+export declare function defaultLicenseDir(): string;
+/**
+ * Every FILE an activation may be stored in, highest priority first.
+ *
+ * Candidates are files, not directories: $XCODER_LICENSE_FILE names an
+ * arbitrary file and the legacy host store is license.json. Collapsing them to
+ * their parent directory and re-appending a hard-coded activation.json silently
+ * ignored both, which is exactly the v1-asks-for-a-key bug that this sharing
+ * work exists to fix. Reads, writes and clears all use this one list.
+ */
+export declare function resolveCandidateFiles(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Directories of the candidate files, highest priority first.
+ *
+ * Kept for callers that reason about the installation sidecar next to the
+ * activation; activation I/O must use resolveCandidateFiles().
+ */
+export declare function resolveCandidateDirs(env?: NodeJS.ProcessEnv): string[];
+export declare function createLicenseStore(opts?: {
+    dir?: string;
+}): LicenseStore;