@devicecloud.dev/dcd 5.6.0 → 5.7.0-beta.1

package/dist/services/telemetry.service.d.ts

@@ -1,9 +1,18 @@
 import type { AuthContext } from '../types/domain/auth.types.js';
+import type { EncryptionSource } from '../utils/envelope.js';
 export type TelemetryLevel = 'log' | 'info' | 'warn' | 'error';
+/** What a run encrypted, and what decided it (dcd#1138). */
+export interface EncryptionTelemetry {
+    binary: boolean;
+    env: boolean;
+    flow: boolean;
+    source: EncryptionSource;
+}
 declare class Telemetry {
     private buffer;
     private config;
     private command;
+    private encryption;
     private sessionId;
     private startedAt;
     private readonly disabled;
@@ -27,13 +36,22 @@ declare class Telemetry {
     setCommand(command: string): void;
     recordCommandStart(): void;
     recordMcpToolStart(tool: string): void;
-    recordMcpToolSuccess(tool: string, durationMs: number): void;
-    recordMcpToolFailure(tool: string, error: unknown, durationMs: number): void;
+    recordMcpToolSuccess(tool: string, durationMs: number, extra?: Record<string, unknown>): void;
+    recordMcpToolFailure(tool: string, error: unknown, durationMs: number, extra?: Record<string, unknown>): void;
+    /**
+     * Record what this command encrypts (dcd#1138), sent as `encrypt` on its
+     * `command completed` / `command failed` event. Merged into what is already
+     * recorded, so a command can fill each part in as it happens. On the event
+     * rather than in `meta`, because the API's `/cli/logs` proxy forwards only
+     * the meta fields it knows, but forwards every event's `extra`.
+     */
+    recordEncryption(update: Partial<EncryptionTelemetry>): void;
     recordCommandSuccess(): void;
     recordCommandFailure(opts: {
         error: Error | string;
         exitCode: number;
     }): void;
+    private encryptionExtra;
     private enqueue;
     flush(): Promise<void>;
     /**

package/dist/services/telemetry.service.js

@@ -23,6 +23,7 @@ class Telemetry {
     buffer = [];
     config = null;
     command = inferCommandFromArgv();
+    encryption = null;
     sessionId = randomUUID();
     startedAt = Date.now();
     disabled = !!process.env.DCD_TELEMETRY_DISABLED;
@@ -60,24 +61,44 @@ class Telemetry {
     recordMcpToolStart(tool) {
         this.enqueue('info', 'cli.mcp', 'mcp tool invoked', { tool });
     }
-    recordMcpToolSuccess(tool, durationMs) {
+    recordMcpToolSuccess(tool, durationMs, extra = {}) {
         this.enqueue('info', 'cli.mcp', 'mcp tool completed', {
             tool,
             duration_ms: durationMs,
+            ...extra,
         });
     }
-    recordMcpToolFailure(tool, error, durationMs) {
+    recordMcpToolFailure(tool, error, durationMs, extra = {}) {
         this.enqueue('error', 'cli.mcp', 'mcp tool failed', {
             tool,
             duration_ms: durationMs,
             error_message: error instanceof Error ? error.message : String(error),
             error_name: error instanceof Error ? error.name : 'Error',
+            ...extra,
         });
     }
+    /**
+     * Record what this command encrypts (dcd#1138), sent as `encrypt` on its
+     * `command completed` / `command failed` event. Merged into what is already
+     * recorded, so a command can fill each part in as it happens. On the event
+     * rather than in `meta`, because the API's `/cli/logs` proxy forwards only
+     * the meta fields it knows, but forwards every event's `extra`.
+     */
+    recordEncryption(update) {
+        this.encryption = {
+            binary: false,
+            env: false,
+            flow: false,
+            source: 'off',
+            ...this.encryption,
+            ...update,
+        };
+    }
     recordCommandSuccess() {
         this.enqueue('info', 'cli.lifecycle', 'command completed', {
             duration_ms: Date.now() - this.startedAt,
             exit_code: 0,
+            ...this.encryptionExtra(),
         });
     }
     recordCommandFailure(opts) {
@@ -88,8 +109,12 @@ class Telemetry {
             error_message: message,
             error_name: opts.error instanceof Error ? opts.error.name : 'CliError',
             error_stack: opts.error instanceof Error ? opts.error.stack : undefined,
+            ...this.encryptionExtra(),
         });
     }
+    encryptionExtra() {
+        return this.encryption ? { encrypt: this.encryption } : {};
+    }
     enqueue(level, context, message, extra) {
         if (this.disabled)
             return;

package/dist/services/test-submission.service.d.ts

@@ -34,9 +34,10 @@ export interface TestSubmissionConfig {
     /**
      * Encrypt the flow zip and env vars before upload (#1151/#1152), each with its
      * own per-upload DEK wrapped under the environment KEK. Requires `apiUrl` to
-     * resolve the pinned KEK public key.
+     * resolve the pinned KEK public key. Required, like `uploadBinary`'s: callers
+     * pass the decision from `resolveEncryption`.
      */
-    encrypt?: boolean;
+    encrypt: boolean;
     env?: string[];
     executionPlan: IExecutionPlan;
     flowFile: string;

package/dist/services/test-submission.service.js

@@ -20,7 +20,7 @@ export class TestSubmissionService {
      * @returns The flow zip buffer, its SHA-256, and the string-encoded fields
      */
     async buildTestPayload(config) {
-        const { apiUrl, appBinaryId, appPlatform, encrypt = false, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], cancelPrevious = false, googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, retry, continueOnFailure = true, renderEngine, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
+        const { apiUrl, appBinaryId, appPlatform, encrypt, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], cancelPrevious = false, googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, retry, continueOnFailure = true, renderEngine, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
         const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, includedFiles = [], referencedFiles, sequence, workspaceConfig, } = executionPlan;
         const { flows: sequentialFlows = [] } = sequence ?? {};
         const envObject = this.parseKeyValuePairs(env);
@@ -80,8 +80,8 @@ export class TestSubmissionService {
             }
             const kek = resolveKekPublicKey(apiUrl);
             if (!kek) {
-                throw new Error('Encryption was requested but no KEK public key is configured for this environment. ' +
-                    'Set DCD_BINARY_KEK_PUBLIC=<version>:<base64> or pin one in src/config/environments.ts.');
+                throw new Error('Encryption is on (from --encrypt, DCD_ENCRYPT or the organization default) but no KEK public key is configured for this API. ' +
+                    'Set DCD_BINARY_KEK_PUBLIC=<version>:<base64>, or pass --no-encrypt to upload without encryption.');
             }
             const flow = encryptFlowBuffer(plaintextZip, kek);
             buffer = flow.ciphertext;

package/dist/types/generated/schema.types.d.ts

@@ -1004,6 +1004,38 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/frontend/uploads/{uploadId}/download": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["FrontendController_downloadUpload"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/frontend/results/{resultId}/env": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["FrontendController_getResultEnv"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/frontend/artifact-download-url": {
         parameters: {
             query?: never;
@@ -1662,7 +1694,7 @@ export interface components {
             workspaceConfig?: string;
             flowMetadata?: string;
             testFileOverrides?: string;
-            /** @description JSON array of explicit device configs forming the upload device matrix. Every flow that does not name its own device runs once per entry. Each entry names exactly one validated cell and must match the binary platform — there is no cross-product expansion. iOS: {"iOSDevice":"iphone-16","iOSVersion":"18"}. Android: {"androidDevice":"pixel-7","androidApiLevel":"34","googlePlay":true}. Omit for single-device (legacy) behaviour. */
+            /** @description JSON array of explicit device configs forming the upload device matrix. Every flow that does not name its own device runs once per entry. Each entry names exactly one validated cell and must match the binary platform — there is no cross-product expansion. iOS: {"iOSDevice":"iphone-16","iOSVersion":"18"}. Android: {"androidDevice":"pixel-8","androidApiLevel":"34","googlePlay":true}. Omit for single-device (legacy) behaviour. */
             deviceMatrix?: string;
             /** @description SHA-256 hash of the flow ZIP file */
             sha?: string;
@@ -1704,7 +1736,7 @@ export interface components {
             workspaceConfig?: string;
             flowMetadata?: string;
             testFileOverrides?: string;
-            /** @description JSON array of explicit device configs forming the upload device matrix. Every flow that does not name its own device runs once per entry. Each entry names exactly one validated cell and must match the binary platform — there is no cross-product expansion. iOS: {"iOSDevice":"iphone-16","iOSVersion":"18"}. Android: {"androidDevice":"pixel-7","androidApiLevel":"34","googlePlay":true}. Omit for single-device (legacy) behaviour. */
+            /** @description JSON array of explicit device configs forming the upload device matrix. Every flow that does not name its own device runs once per entry. Each entry names exactly one validated cell and must match the binary platform — there is no cross-product expansion. iOS: {"iOSDevice":"iphone-16","iOSVersion":"18"}. Android: {"androidDevice":"pixel-8","androidApiLevel":"34","googlePlay":true}. Omit for single-device (legacy) behaviour. */
             deviceMatrix?: string;
             /** @description SHA-256 hash of the flow ZIP file */
             sha?: string;
@@ -1757,7 +1789,7 @@ export interface components {
             workspaceConfig?: string;
             flowMetadata?: string;
             testFileOverrides?: string;
-            /** @description JSON array of explicit device configs forming the upload device matrix. Every flow that does not name its own device runs once per entry. Each entry names exactly one validated cell and must match the binary platform — there is no cross-product expansion. iOS: {"iOSDevice":"iphone-16","iOSVersion":"18"}. Android: {"androidDevice":"pixel-7","androidApiLevel":"34","googlePlay":true}. Omit for single-device (legacy) behaviour. */
+            /** @description JSON array of explicit device configs forming the upload device matrix. Every flow that does not name its own device runs once per entry. Each entry names exactly one validated cell and must match the binary platform — there is no cross-product expansion. iOS: {"iOSDevice":"iphone-16","iOSVersion":"18"}. Android: {"androidDevice":"pixel-8","androidApiLevel":"34","googlePlay":true}. Omit for single-device (legacy) behaviour. */
             deviceMatrix?: string;
             /** @description SHA-256 hash of the flow ZIP file */
             sha?: string;
@@ -2235,7 +2267,15 @@ export interface operations {
                      *       ]
                      *     }
                      */
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /**
+                         * Format: uuid
+                         * @description Present only when a newer run from the same CI context (`dcd cloud --cancel-previous`) superseded this one by cancelling its queued tests: the id of that newer upload. `status` still rolls up to FAILED for such a run (its queued tests were cancelled), so check this field before failing a CI job on `status`.
+                         */
+                        supersededBy?: string;
+                    } & {
+                        [key: string]: unknown;
+                    };
                 };
             };
         };
@@ -2590,6 +2630,7 @@ export interface operations {
             content: {
                 "application/json": {
                     orgId: string;
+                    /** @description Overage allowed on top of the plan’s included credits, rounded down to a whole number. 0 allows no overage: usage is capped at the included credits. Negative values are rejected. */
                     overageLimit: number;
                 };
             };
@@ -3076,6 +3117,13 @@ export interface operations {
                      *         "androidPlay": {
                      *           "pixel-7": [
                      *             "34"
+                     *           ],
+                     *           "pixel-8": [
+                     *             "34"
+                     *           ],
+                     *           "pixel-10": [
+                     *             "36",
+                     *             "37"
                      *           ]
                      *         },
                      *         "maestro": {
@@ -3095,6 +3143,9 @@ export interface operations {
                      *           ],
                      *           "defaultVersion": "2.2.0",
                      *           "latestVersion": "2.10.0"
+                     *         },
+                     *         "encryption": {
+                     *           "defaultOn": false
                      *         }
                      *       }
                      *     }
@@ -3110,6 +3161,11 @@ export interface operations {
                                 defaultVersion?: string;
                                 latestVersion?: string;
                             };
+                            /** @description The org's client-side encryption default (#1138). An API that predates it omits the field, which a client must read as `defaultOn: false`. */
+                            encryption?: {
+                                /** @description Encrypt uploads unless the caller opts out (`--no-encrypt` / `DCD_ENCRYPT=0`). True only for orgs in the `client_encryption` beta, and forced false by `CLIENT_ENCRYPTION_DEFAULT=off` on the API. */
+                                defaultOn: boolean;
+                            };
                         };
                     };
                 };
@@ -3790,16 +3846,16 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Signed download URL for the binary; `dek` (base64) is present when the binary is encrypted */
+            /** @description Signed download URL for the stored binary. `encrypted` is present (true) when that object is ciphertext; download it through GET /frontend/binaries/{binaryId}/download instead. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        url?: string;
-                        encrypted?: boolean;
-                        dek?: string;
+                        url: string;
+                        /** @enum {boolean} */
+                        encrypted?: true;
                     };
                 };
             };
@@ -3807,9 +3863,7 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": Record<string, never>;
-                };
+                content?: never;
             };
             /** @description Binary not found or not accessible */
             400: {
@@ -3829,8 +3883,13 @@ export interface operations {
             query: {
                 orgId: number;
             };
-            header: {
-                authorization: string;
+            header?: {
+                /** @description The @devicecloud.dev staff member a back-office request acts for; recorded as the key-release actor. */
+                "x-staff-email"?: string;
+                /** @description Back-office service key (BACKOFFICE_API_KEY), in place of a JWT. Requires x-staff-email. */
+                "x-backoffice-key"?: string;
+                /** @description Bearer <Supabase JWT>. Omit when sending x-backoffice-key. */
+                authorization?: string;
             };
             path: {
                 binaryId: string;
@@ -3839,13 +3898,20 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Binary bytes (decrypted if encrypted) */
+            /** @description Encrypted binary: the stream-decrypted plaintext bytes */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
+            /** @description Plaintext binary: redirect to a signed storage URL */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             /** @description Binary not found or not accessible */
             400: {
                 headers: {
@@ -3853,6 +3919,118 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description No valid JWT or back-office key, or not an org member */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    FrontendController_downloadUpload: {
+        parameters: {
+            query: {
+                orgId: number;
+            };
+            header?: {
+                /** @description The @devicecloud.dev staff member a back-office request acts for; recorded as the key-release actor. */
+                "x-staff-email"?: string;
+                /** @description Back-office service key (BACKOFFICE_API_KEY), in place of a JWT. Requires x-staff-email. */
+                "x-backoffice-key"?: string;
+                /** @description Bearer <Supabase JWT>. Omit when sending x-backoffice-key. */
+                authorization?: string;
+            };
+            path: {
+                uploadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Encrypted flow upload: the stream-decrypted zip */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Plaintext flow upload: redirect to a signed storage URL */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Upload not found or not accessible */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No valid JWT or back-office key, or not an org member */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    FrontendController_getResultEnv: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description The @devicecloud.dev staff member a back-office request acts for; recorded as the key-release actor. */
+                "x-staff-email"?: string;
+                /** @description Back-office service key (BACKOFFICE_API_KEY), in place of a JWT. Requires x-staff-email. */
+                "x-backoffice-key"?: string;
+                /** @description Bearer <Supabase JWT>. Omit when sending x-backoffice-key. */
+                authorization?: string;
+            };
+            path: {
+                resultId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The result's env. `encrypted` says whether it was stored encrypted; `env` is the (decrypted) KEY -> VALUE map, or null when the result has none. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        encrypted: boolean;
+                        env: {
+                            [key: string]: string;
+                        } | null;
+                    };
+                };
+            };
+            /** @description No valid JWT or back-office key */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The JWT is not a staff account */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Result not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     FrontendController_getArtifactDownloadUrl: {

package/dist/types.d.ts

@@ -8,4 +8,9 @@ export type TAppMetadata = {
      * release the DEK and decrypt. Absent = legacy plaintext upload.
      */
     enc?: BinaryEnvelope;
+    /**
+     * Whether an encrypted APK ships the Flutter engine (dcd#1138). The API
+     * detects this itself for plaintext binaries, so it is only sent with `enc`.
+     */
+    usesFlutterEngine?: boolean;
 };

package/dist/utils/compatibility.d.ts

@@ -11,6 +11,14 @@ export interface CompatibilityData {
     };
     /** Active CLI notices, piggybacked onto the compatibility response by the API. */
     notices?: Notice[];
+    /**
+     * The org's client-side encryption default (dcd#1138): on for orgs in the
+     * `client_encryption` beta unless the API's kill switch is set. An older API
+     * omits it, which means off.
+     */
+    encryption?: {
+        defaultOn: boolean;
+    };
 }
 /** Identity the CLI forwards so the API can target notices by version / CI. */
 export interface ClientContext {

package/dist/utils/envelope.d.ts

@@ -14,14 +14,39 @@ export interface EnvEnvelope extends BinaryEnvelope {
     /** base64 of a single-segment DCDE container of `JSON.stringify(env)`. */
     ciphertext: string;
 }
+/** What decided whether a run encrypts (dcd#1138); recorded in telemetry. */
+export type EncryptionSource = 'env' | 'flag' | 'off' | 'server';
+export interface EncryptionDecision {
+    enabled: boolean;
+    /** Kept when encryption is skipped, so telemetry shows what asked for it. */
+    source: EncryptionSource;
+    /** One line for the user when encryption was wanted but is skipped. */
+    notice?: string;
+}
 /**
- * Whether client-side envelope encryption is on. Explicit `flag` (the
- * `--encrypt` CLI flag) wins; otherwise `DCD_ENCRYPT=1` enables it for binary,
- * flow, and env, and the legacy `DCD_ENCRYPT_BINARIES=1` is kept as an alias.
+ * Whether client-side envelope encryption is on, and what decided it. The
+ * first of these that is set wins:
+ *   1. `flag`: `--encrypt` / `--no-encrypt`, or the MCP tool's `encrypt` input.
+ *   2. `DCD_ENCRYPT`, then its legacy alias `DCD_ENCRYPT_BINARIES`.
+ *   3. `serverDefault`: `encryption.defaultOn` from the compatibility data,
+ *      which the API turns on for orgs in the `client_encryption` beta.
+ *   4. Off. An API too old to send `encryption` ends up here.
  * When on, the binary, the flow zip, and the env map are each encrypted with
  * their **own** per-upload DEK (all wrapped under the same per-env KEK).
  */
-export declare function isEncryptionEnabled(flag?: boolean): boolean;
+export declare function resolveEncryption(opts: {
+    env?: NodeJS.ProcessEnv;
+    flag?: boolean;
+    serverDefault?: boolean;
+}): EncryptionDecision;
+/**
+ * Check that `apiUrl` has a KEK before a run encrypts against it: either
+ * `DCD_BINARY_KEK_PUBLIC` is set or the URL is a known devicecloud.dev API
+ * (see kekEnvForApiUrl). Without one, an explicit `--encrypt` is an error,
+ * while encryption from DCD_ENCRYPT or the org default is skipped with a
+ * notice, so a run against another API URL uploads in plaintext as before.
+ */
+export declare function checkKekForEncryption(decision: EncryptionDecision, apiUrl: string): EncryptionDecision;
 /** Pinned KEK public key (base64 raw 32-byte X25519) + version, per env. */
 interface KekPublicKey {
     version: number;
@@ -30,8 +55,9 @@ interface KekPublicKey {
 /**
  * Resolve the KEK public key for the environment behind `apiUrl`. Order:
  *   1. `DCD_BINARY_KEK_PUBLIC` env override (`<version>:<base64>`, e.g. `1:AAAA…`)
- *      — lets the feature be exercised before keys are pinned in the release.
- *   2. the pinned `ENVIRONMENTS[env].kekPublicKey`.
+ *      — lets the feature be exercised before keys are pinned in the release,
+ *      or against an API URL that isn't a known one.
+ *   2. the pinned `ENVIRONMENTS[env].kekPublicKey`, only for a known API URL.
  * Returns null when no key is available (encryption cannot proceed).
  */
 export declare function resolveKekPublicKey(apiUrl: string): KekPublicKey | null;

package/dist/utils/envelope.js

@@ -1,7 +1,6 @@
 import { createCipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from 'node:crypto';
 import { open, stat } from 'node:fs/promises';
-import { inferEnvFromApiUrl } from '../config/environments.js';
-import { ENVIRONMENTS } from '../config/environments.js';
+import { ENVIRONMENTS, kekEnvForApiUrl } from '../config/environments.js';
 /**
  * Client-side envelope encryption of app binaries before upload (dcd#1138).
  *
@@ -24,17 +23,63 @@ export const CHUNK_SIZE = 1024 * 1024; // 1 MiB plaintext segments
 const HKDF_INFO = Buffer.from('dcd-binary-dek-wrap-v1', 'ascii');
 // DER prefix that turns a raw 32-byte X25519 public key into an importable SPKI.
 const SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+/** `1`/`true` is on and `0`/`false` is off, in any case; anything else is unset. */
+function parseEncryptEnv(value) {
+    switch (value?.trim().toLowerCase()) {
+        case '1':
+        case 'true': {
+            return true;
+        }
+        case '0':
+        case 'false': {
+            return false;
+        }
+        default: {
+            return undefined;
+        }
+    }
+}
 /**
- * Whether client-side envelope encryption is on. Explicit `flag` (the
- * `--encrypt` CLI flag) wins; otherwise `DCD_ENCRYPT=1` enables it for binary,
- * flow, and env, and the legacy `DCD_ENCRYPT_BINARIES=1` is kept as an alias.
+ * Whether client-side envelope encryption is on, and what decided it. The
+ * first of these that is set wins:
+ *   1. `flag`: `--encrypt` / `--no-encrypt`, or the MCP tool's `encrypt` input.
+ *   2. `DCD_ENCRYPT`, then its legacy alias `DCD_ENCRYPT_BINARIES`.
+ *   3. `serverDefault`: `encryption.defaultOn` from the compatibility data,
+ *      which the API turns on for orgs in the `client_encryption` beta.
+ *   4. Off. An API too old to send `encryption` ends up here.
  * When on, the binary, the flow zip, and the env map are each encrypted with
  * their **own** per-upload DEK (all wrapped under the same per-env KEK).
  */
-export function isEncryptionEnabled(flag) {
+export function resolveEncryption(opts) {
+    const { env = process.env, flag, serverDefault } = opts;
     if (flag !== undefined)
-        return flag;
-    return (process.env.DCD_ENCRYPT === '1' || process.env.DCD_ENCRYPT_BINARIES === '1');
+        return { enabled: flag, source: 'flag' };
+    const fromEnv = parseEncryptEnv(env.DCD_ENCRYPT) ?? parseEncryptEnv(env.DCD_ENCRYPT_BINARIES);
+    if (fromEnv !== undefined)
+        return { enabled: fromEnv, source: 'env' };
+    if (serverDefault === true)
+        return { enabled: true, source: 'server' };
+    return { enabled: false, source: 'off' };
+}
+/**
+ * Check that `apiUrl` has a KEK before a run encrypts against it: either
+ * `DCD_BINARY_KEK_PUBLIC` is set or the URL is a known devicecloud.dev API
+ * (see kekEnvForApiUrl). Without one, an explicit `--encrypt` is an error,
+ * while encryption from DCD_ENCRYPT or the org default is skipped with a
+ * notice, so a run against another API URL uploads in plaintext as before.
+ */
+export function checkKekForEncryption(decision, apiUrl) {
+    if (!decision.enabled || resolveKekPublicKey(apiUrl))
+        return decision;
+    if (decision.source === 'flag') {
+        throw new Error(`--encrypt needs the KEK public key of the API it uploads to, and ${apiUrl} is not a devicecloud.dev API this CLI has one for. ` +
+            'Set DCD_BINARY_KEK_PUBLIC=<version>:<base64> to encrypt against it, or drop --encrypt.');
+    }
+    return {
+        enabled: false,
+        notice: `Not encrypting uploads: ${apiUrl} is not a devicecloud.dev API this CLI has a key for. Set DCD_BINARY_KEK_PUBLIC to encrypt against it.`,
+        source: decision.source,
+    };
 }
 function x25519PublicFromRaw(raw) {
     return createPublicKey({
@@ -46,8 +91,9 @@ function x25519PublicFromRaw(raw) {
 /**
  * Resolve the KEK public key for the environment behind `apiUrl`. Order:
  *   1. `DCD_BINARY_KEK_PUBLIC` env override (`<version>:<base64>`, e.g. `1:AAAA…`)
- *      — lets the feature be exercised before keys are pinned in the release.
- *   2. the pinned `ENVIRONMENTS[env].kekPublicKey`.
+ *      — lets the feature be exercised before keys are pinned in the release,
+ *      or against an API URL that isn't a known one.
+ *   2. the pinned `ENVIRONMENTS[env].kekPublicKey`, only for a known API URL.
  * Returns null when no key is available (encryption cannot proceed).
  */
 export function resolveKekPublicKey(apiUrl) {
@@ -62,7 +108,9 @@ export function resolveKekPublicKey(apiUrl) {
         }
         throw new Error('DCD_BINARY_KEK_PUBLIC must be "<version>:<base64 32-byte X25519 public key>"');
     }
-    const env = inferEnvFromApiUrl(apiUrl);
+    const env = kekEnvForApiUrl(apiUrl);
+    if (!env)
+        return null;
     const pinned = ENVIRONMENTS[env].kekPublicKey;
     if (!pinned)
         return null;

package/dist/utils/help.d.ts

@@ -0,0 +1,12 @@
+import type { ArgDef, ArgsDef, CommandDef } from 'citty';
+/**
+ * A citty arg definition plus a local `hidden` marker. citty (0.2) can hide a
+ * command from help (`meta.hidden`) but not an arg, so {@link withoutHiddenArgs}
+ * drops hidden args before usage is rendered. They still parse as normal.
+ */
+export type CliArgDef = ArgDef & {
+    hidden?: boolean;
+};
+export type CliArgsDef = Record<string, CliArgDef>;
+/** `cmd` with its hidden args left out, for rendering `--help` only. */
+export declare function withoutHiddenArgs<T extends ArgsDef>(cmd: CommandDef<T>): Promise<CommandDef<T>>;