@reticlehq/server 3.8.1 → 3.9.0

package/dist/features/license/license.js

@@ -1,14 +1,9 @@
 /**
- * Enterprise license-key verification + the assertEnterprise gate. ENTERPRISE CODE (Reticle Enterprise
- * License — see./LICENSE), not the FSL that covers the rest of the server.
+ * License-key verification for `reticle license` and the telemetry `licenseStatus` field.
  *
- * Offline + no phone-home (preserves the no-telemetry brand): a key is a signed payload Reticle issues
- * with its private key; this verifies it against the issuer's PUBLIC key with Ed25519. Dev/eval is a
- * no-op (requireLicense:false) so the gate never gets in a contributor's way; only a production-mode
- * caller with requireLicense:true must present a valid, unexpired key. The clock is injected (rule 7).
- *
- * Rules for this directory: the free server must never import from ee/; ee/ depends only on protocol +
- * node + zod. This file imports neither server core nor any sibling outside ee/.
+ * Offline, with no phone-home: a key is a signed payload that Reticle issues with its private key.
+ * This file verifies it against the issuer's PUBLIC key with Ed25519. Nothing in this package is
+ * gated on a key. The clock is injected (rule 7).
  */
 import { createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
 import { z } from 'zod';
@@ -22,8 +17,8 @@ export const LicenseStatus = {
     EXPIRED: 'expired',
 };
 /**
- * The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features
- * unlock.
+ * The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes the features that
+ * the key covers.
  *
  * `lid` is the stable licence id and the only safe identity: `org` is a display name a human typed at
  * signing time, so two organisations with the same name collapse into one and a rename splits one into
@@ -48,8 +43,9 @@ export function signLicenseKey(payload, privateKey) {
 }
 /** Verify a key against the issuer public key. Never throws — returns a structured status. */
 export function verifyLicenseKey(key, publicKey, now) {
-    if (key === undefined || 0 === key.length)
+    if (key === undefined || 0 === key.length) {
         return { status: LicenseStatus.MISSING };
+    }
     const parts = key.split(KEY_SEP);
     if (parts.length !== 2 ||
         parts[0] === undefined ||
@@ -62,8 +58,9 @@ export function verifyLicenseKey(key, publicKey, now) {
     try {
         json = Buffer.from(parts[0], 'base64url').toString('utf8');
         const parsed = LicensePayloadSchema.safeParse(JSON.parse(json));
-        if (!parsed.success)
+        if (!parsed.success) {
             return { status: LicenseStatus.MALFORMED };
+        }
         payload = parsed.data;
     }
     catch {
@@ -76,98 +73,45 @@ export function verifyLicenseKey(key, publicKey, now) {
     catch {
         return { status: LicenseStatus.BAD_SIGNATURE };
     }
-    if (!signatureOk)
+    if (!signatureOk) {
         return { status: LicenseStatus.BAD_SIGNATURE };
-    if (payload.exp <= now)
+    }
+    if (payload.exp <= now) {
         return { status: LicenseStatus.EXPIRED, payload };
+    }
     return { status: LicenseStatus.VALID, payload };
 }
 /**
- * Where to get a key. A named constant because it appears in the gate's error AND in what
- * `reticle license` prints, and a contact address that drifts between the two is a support request
- * that reaches nobody.
+ * Where to get a key. A named constant because `reticle license` prints it on every branch, and a
+ * contact address that drifts is a support request that reaches nobody.
  */
 export const LICENSE_CONTACT = 'hey@reticle.sh';
-/**
- * The features a licence gates in THIS build. The single source: `assertEnterprise` callers name a
- * member rather than a string literal, and `reticle license` reports the list, so what the CLI claims
- * is gated is derived from what is actually gated rather than a second list somebody maintains.
- *
- * It is deliberately short. Reticle's roadmap for enterprise is longer (SSO, SCIM, RBAC, multi-org,
- * policy gates), and none of it is here yet — printing a roadmap as though it were shipped is how a
- * buyer discovers on day two that the thing they paid for does not exist. What is listed is what the
- * running build will actually refuse without a key.
- */
-export const EnterpriseFeature = {
-    /** Recording an audit event. */
-    AUDIT_LOG: 'audit-log',
-};
-/** Thrown when a production-mode enterprise feature is used without a valid license. */
-export class EnterpriseLicenseError extends Error {
-    feature;
-    reason;
-    constructor(feature, reason) {
-        super(`Reticle Enterprise feature "${feature}" requires a valid license (${reason}). Contact ${LICENSE_CONTACT}.`);
-        this.name = 'EnterpriseLicenseError';
-        this.feature = feature;
-        this.reason = reason;
-    }
-}
-/**
- * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
- * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
- */
-export function assertEnterprise(feature, ctx, env = process.env, baked) {
-    if (!ctx.requireLicense)
-        return;
-    // Resolved exactly as the env-entry point resolves it: BAKED first, env only as the dev/test
-    // hatch. Reading the environment alone denies every valid licence on a real release, where the key
-    // is baked and no env var is set. Two gates, one truth.
-    const publicKey = ctx.publicKey ?? loadPublicKey(resolveIssuerPublicKeyPem(env, baked));
-    if (publicKey === undefined)
-        throw new EnterpriseLicenseError(feature, 'no-issuer-key');
-    const check = verifyLicenseKey(ctx.key, publicKey, ctx.now());
-    if (check.status !== LicenseStatus.VALID)
-        throw new EnterpriseLicenseError(feature, check.status);
-    const { features } = check.payload;
-    if (features !== undefined && !features.includes(feature)) {
-        throw new EnterpriseLicenseError(feature, 'feature-not-licensed');
-    }
-}
 /** Env names that carry the activation: the operator's key, and the issuer public key baked at release. */
 export const LICENSE_KEY_ENV = 'RETICLE_LICENSE_KEY';
 export const LICENSE_PUBLIC_KEY_ENV = 'RETICLE_LICENSE_PUBLIC_KEY';
 /**
  * Issuer public key COMPILED INTO the build. Empty in the source tree; the release pipeline replaces
- * this literal with the real spki PEM. Baking it (rather than only reading env) is what makes the
- * enterprise gate fail closed: a self-hosted operator can no longer disable enforcement by simply
- * never setting RETICLE_LICENSE_PUBLIC_KEY, because the baked key takes precedence. The public key is
- * safe to ship openly — it can only verify licenses, never mint them (that needs the private key).
+ * this literal with the real spki PEM. The baked key takes precedence over RETICLE_LICENSE_PUBLIC_KEY,
+ * so an operator cannot swap in a key of their own. The public key is safe to ship openly: it can
+ * only verify licenses, never mint them (that needs the private key).
  */
 const BAKED_ISSUER_PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAcg+u61Fs5pwDHcYxFGhaxVaQoUbAdyl+RUdSViZyxDY=\n-----END PUBLIC KEY-----";
 /**
- * Resolve the issuer public-key PEM enforcement uses: the baked-in release key wins, so it can't be
- * turned off from the environment. Only when nothing is baked (dev/repo) does the env var apply — that
+ * Resolve the issuer public-key PEM: the baked-in release key wins, so the environment cannot
+ * replace it. Only when nothing is baked (dev/repo) does the env var apply — that
  * env path is the test/self-eval escape hatch, not the production switch.
  */
 function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
-    if (baked.length > 0)
+    if (baked.length > 0) {
         return baked;
+    }
     const envPem = env[LICENSE_PUBLIC_KEY_ENV];
     return envPem !== undefined && envPem.length > 0 ? envPem : undefined;
 }
-/**
- * The two fields every report carries, spread into each branch. One object rather than a field on each
- * return, because the value that must never go missing is the one on the branch nobody was thinking
- * about — and the branch an unlicensed reader lands on is exactly that branch.
- */
-const LICENSE_OFFER = {
-    gated: Object.values(EnterpriseFeature),
-    contact: LICENSE_CONTACT,
-};
 function loadPublicKey(pem) {
-    if (pem === undefined || 0 === pem.length)
+    if (pem === undefined || 0 === pem.length) {
         return undefined;
+    }
     try {
         return createPublicKey(pem);
     }
@@ -177,111 +121,74 @@ function loadPublicKey(pem) {
 }
 /**
  * Resolve activation entirely from the environment — the install mechanism: the release bakes the
- * issuer public key, the operator sets RETICLE_LICENSE_KEY. No public key configured ⇒ evaluation mode
- * (enterprise features run free, dev/test only). Offline, no phone-home.
+ * issuer public key, the operator sets RETICLE_LICENSE_KEY. No public key configured ⇒ evaluation mode.
+ * Offline, no phone-home.
  */
 export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
     const pem = resolveIssuerPublicKeyPem(env, baked);
     if (pem === undefined || 0 === pem.length) {
-        // In a production runtime this is NOT a benign eval session — it is a mis-built release whose gate
-        // is off, and assertEnterpriseFromEnv now denies rather than unlocking. Say so loudly here too.
+        // In a production runtime this is NOT a benign eval session: it is a mis-built release. Say so.
         return isProductionEnv(env)
             ? {
-                ...LICENSE_OFFER,
+                contact: LICENSE_CONTACT,
                 status: LicenseActivation.INVALID,
-                detail: 'MISCONFIGURED — running in production with no issuer key baked; enterprise features are DENIED (rebuild with BAKED_ISSUER_PUBLIC_KEY_PEM stamped in)',
+                detail: 'MISCONFIGURED — running in production with no issuer key baked (rebuild with BAKED_ISSUER_PUBLIC_KEY_PEM stamped in)',
             }
             : {
-                ...LICENSE_OFFER,
+                contact: LICENSE_CONTACT,
                 status: LicenseActivation.EVAL,
-                detail: 'evaluation mode: enterprise features run free (no issuer key configured)',
+                detail: 'evaluation mode (no issuer key configured)',
             };
     }
     const publicKey = loadPublicKey(pem);
-    if (publicKey === undefined)
+    if (publicKey === undefined) {
         return {
-            ...LICENSE_OFFER,
+            contact: LICENSE_CONTACT,
             status: LicenseActivation.INVALID,
             detail: `${LICENSE_PUBLIC_KEY_ENV} is not a valid public key`,
         };
+    }
     const check = verifyLicenseKey(env[LICENSE_KEY_ENV], publicKey, now);
     if (check.status === LicenseStatus.VALID) {
         const { lid, org, plan, exp, features } = check.payload;
-        // A key scoped to features this build does not gate is `active` and unlocks nothing. Both halves
-        // were already on screen (`features` against `gated`) and nothing joined them, so the one word a
-        // customer actually reads told them they were fine while every gated call refused them.
-        const coversNothingHere = features !== undefined && !features.some((f) => LICENSE_OFFER.gated.includes(f));
-        const detail = coversNothingHere
-            ? `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}. This key covers ${features?.join(', ')}, and nothing this build gates (${LICENSE_OFFER.gated.join(', ')}) is included. Contact ${LICENSE_CONTACT}`
-            : `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}`;
         return {
             contact: LICENSE_CONTACT,
-            // The one active case that still needs the list: a key covering nothing this build gates is
-            // reported here, and the sentence explaining it is unreadable without both sides named.
-            ...(coversNothingHere ? { gated: LICENSE_OFFER.gated } : {}),
             status: LicenseActivation.ACTIVE,
             licenseId: lid,
             org,
             plan,
             expiresAt: exp,
             ...(features !== undefined ? { features } : {}),
-            ...(coversNothingHere ? { coversNothingHere } : {}),
-            detail,
+            detail: `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}`,
         };
     }
     if (check.status === LicenseStatus.MISSING) {
         return {
-            ...LICENSE_OFFER,
+            contact: LICENSE_CONTACT,
             status: LicenseActivation.MISSING,
-            detail: `set ${LICENSE_KEY_ENV} to activate enterprise features in production. ` +
-                `Request a key from ${LICENSE_CONTACT}`,
+            detail: `set ${LICENSE_KEY_ENV} to activate a license. Request a key from ${LICENSE_CONTACT}`,
         };
     }
     if (check.status === LicenseStatus.EXPIRED) {
         // The id rides an expired key so the lapse can be identified; without it an expiry is
         // indistinguishable from any other.
         return {
-            ...LICENSE_OFFER,
+            contact: LICENSE_CONTACT,
             status: LicenseActivation.EXPIRED,
             licenseId: check.payload.lid,
             org: check.payload.org,
             expiresAt: check.payload.exp,
-            detail: `license expired. Renew with ${LICENSE_CONTACT} to keep using enterprise features`,
+            detail: `license expired. Renew with ${LICENSE_CONTACT}`,
         };
     }
     return {
-        ...LICENSE_OFFER,
+        contact: LICENSE_CONTACT,
         status: LicenseActivation.INVALID,
         detail: `license key rejected (${check.status}). ${LICENSE_CONTACT} can re-issue it`,
     };
 }
-/** True in a production runtime (NODE_ENV=production) — where a missing issuer key is a mis-built
- *  release, not an eval session, so the gate must fail CLOSED rather than run features free. */
+/** True in a production runtime (NODE_ENV=production), where a missing issuer key is a mis-built
+ *  release, not an eval session. */
 function isProductionEnv(env) {
     return 'production' === env['NODE_ENV'];
 }
-/**
- * Gate an enterprise feature using env-resolved activation. Enforcement is ON when the issuer public key
- * is configured (a real release). Without it, behaviour splits on runtime:
- *  - dev/eval (NODE_ENV ≠ production): features run FREE — never blocks a contributor or CI.
- *  - production (NODE_ENV = production): FAIL CLOSED — a release that reaches production with no
- *    resolvable issuer key was mis-built (the baked key wasn't stamped in, BAKED_ISSUER_PUBLIC_KEY_PEM
- *    is still ''), and silently unlocking every ee feature with no key and no warning is the worst
- *    outcome. Deny instead, with a distinct reason so the misconfiguration is obvious.
- */
-export function assertEnterpriseFromEnv(feature, now, env = process.env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
-    const publicKey = loadPublicKey(resolveIssuerPublicKeyPem(env, baked));
-    if (publicKey === undefined) {
-        if (isProductionEnv(env)) {
-            throw new EnterpriseLicenseError(feature, 'enterprise-gate-unconfigured');
-        }
-        return; // dev/eval — free
-    }
-    const key = env[LICENSE_KEY_ENV];
-    assertEnterprise(feature, {
-        requireLicense: true,
-        now: () => now,
-        ...(key !== undefined ? { key } : {}),
-        publicKey,
-    });
-}

package/dist/features/visual/desktop-capture.d.ts

@@ -0,0 +1,33 @@
+import { VisualReason } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/**
+ * Ask the desktop shell to photograph its own window.
+ *
+ * Returns undefined for a plain web page (no capture helper) and for a desktop app that did not
+ * install `@reticlehq/electron/main`. Deliberately NOT a screen-region capture: photographing
+ * the glass returns whatever window is on top, which would save a picture of the user's editor as a
+ * visual baseline — the exact false green Reticle exists to eliminate.
+ */
+export declare function desktopCapture(deps: ToolDeps, sessionId: string | undefined, fullPage: boolean): Promise<{
+    png?: Uint8Array;
+    reason?: VisualReason;
+    recommendation?: string;
+}>;
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export declare function isCapturePath(path: string): boolean;

package/dist/features/visual/desktop-capture.js

@@ -0,0 +1,94 @@
+/**
+ * The desktop shell's photograph of its own window, read from the file the shell wrote.
+ *
+ * Shared by `reticle_screenshot`, the drive frames and the step shots. The step shots use it only
+ * for a page SDK before 3.7, which has no `render` command and declares `capture` instead.
+ */
+import { readFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname } from 'node:path';
+import { asRecord, asString, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, RETICLE_TAURI_INERT_MARKER, TAURI_INERT_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
+import { trackCaptureDirectory } from './capture-cleanup.js';
+/**
+ * Ask the desktop shell to photograph its own window.
+ *
+ * Returns undefined for a plain web page (no capture helper) and for a desktop app that did not
+ * install `@reticlehq/electron/main`. Deliberately NOT a screen-region capture: photographing
+ * the glass returns whatever window is on top, which would save a picture of the user's editor as a
+ * visual baseline — the exact false green Reticle exists to eliminate.
+ */
+export async function desktopCapture(deps, sessionId, fullPage) {
+    const session = deps.sessions.resolve(sessionId);
+    // A session that cannot take commands (no live browser behind it) simply has no pixels to give.
+    if (typeof session.command !== 'function') {
+        return {};
+    }
+    const res = await session.command(ReticleCommand.CAPTURE, { fullPage });
+    if (!res.ok) {
+        return {};
+    }
+    const r = asRecord(res.result);
+    if (r['ok'] !== true) {
+        // The shell refused a full-page capture it cannot do. That is a different answer from "capture
+        // broke", and the caller has to hear it — otherwise they read `fullPage` as honoured.
+        if (r['reason'] === VisualReason.FULL_PAGE_UNSUPPORTED) {
+            return { reason: VisualReason.FULL_PAGE_UNSUPPORTED };
+        }
+        // A Tauri release build with the capture compiled out: say that, never the web answer.
+        return true === asString(r['reason'])?.includes(RETICLE_TAURI_INERT_MARKER)
+            ? { reason: VisualReason.NO_PROVIDER, recommendation: TAURI_INERT_RECOMMENDATION }
+            : {};
+    }
+    const path = asString(r['path']);
+    if (path === undefined || !isCapturePath(path)) {
+        return {};
+    }
+    try {
+        const bytes = await readFile(path);
+        await unlink(path).catch(() => undefined);
+        trackCaptureDirectory(path);
+        return isCompletePng(bytes) ? { png: new Uint8Array(bytes) } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export function isCapturePath(path) {
+    if (!basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX)) {
+        return false;
+    }
+    const parent = dirname(path);
+    if (parent === tmpdir()) {
+        return true;
+    }
+    return dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
+}
+/**
+ * A PNG is complete only if it ends with IEND. This check exists because a truncated image once
+ * sailed through as a saved baseline: the tool answered `saved: true` with a path, and the file was
+ * undecodable. A screenshot that cannot be read must fail loudly, never bank a corrupt baseline that
+ * a later visual_diff will compare against.
+ */
+function isCompletePng(bytes) {
+    if (bytes.byteLength < 12) {
+        return false;
+    }
+    return 'IEND' === bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii');
+}