@hypequery/cli 1.10.4 → 1.11.0

package/README.md

@@ -182,11 +182,64 @@ are still accepted for metadata-only validation.
 npx hypequery deployment:validate analytics/hypequery-deployment
 ```
 
+### `hypequery login`
+
+Authorizes the local CLI through your existing Hypequery Cloud browser
+session. The command uses an S256 PKCE loopback flow, then stores the
+target-scoped deployment token in the operating-system credential vault.
+Tokens expire after 12 hours.
+
+```bash
+npx hypequery login
+```
+
+Use `--cloud-url <origin>` or `HYPEQUERY_CLOUD_URL` for a self-hosted or local
+Cloud instance. HTTPS is required except for loopback development origins.
+
+Once logged in, `hypequery deploy` automatically uses the stored endpoint and
+token. The deployment endpoint is returned by Cloud during the token exchange;
+it is the authenticated upload API, not the browser login endpoint. For
+non-interactive CI usage, set both `HYPEQUERY_API_TOKEN` and
+`HYPEQUERY_DEPLOYMENT_ENDPOINT` (or pass `--endpoint`).
+
+Because the CLI also loads a project `.env`, a `HYPEQUERY_API_TOKEN` left there
+takes precedence over the login flow and is rejected unless it is paired with an
+endpoint. Unset it to use `hypequery login`.
+
+Token storage requires an operating-system credential vault (Keychain,
+Credential Manager, or a Secret Service implementation such as
+gnome-keyring/KWallet). Headless environments without one should use
+`HYPEQUERY_API_TOKEN` instead of `hypequery login`.
+
+### `hypequery logout`
+
+Revokes the current Cloud token and removes it from the operating-system
+credential vault:
+
+```bash
+npx hypequery logout
+```
+
+If the stored profile is unreadable, `logout` still removes the local state and
+reports that the token was not revoked; it expires on its own.
+
 ### `hypequery deployment:release`
 
 Prepares a deterministic release request from a verified deployment bundle and
-an explicit project/environment target. This command does not upload, authorize,
-or execute the release.
+a project/environment target. This command does not upload, authorize, or
+execute the release.
+
+After `hypequery login` the target is read from the stored Cloud profile, and
+the resolved target is printed alongside the release identity:
+
+```bash
+npx hypequery deployment:release analytics/hypequery-deployment
+```
+
+To target something other than the logged-in project and environment, pass both
+flags. A half-specified override is rejected rather than completed from the
+stored profile, so an unset shell variable fails loudly instead of silently
+retargeting the release:
 
 ```bash
 npx hypequery deployment:release analytics/hypequery-deployment \
@@ -200,8 +253,10 @@ invalidate bundle verification.
 
 Options:
 
-- `--project <project>`: required target project identifier
-- `--environment <environment>`: required target environment identifier
+- `--project <project>`: target project identifier; defaults to the logged-in
+  target and must be paired with `--environment`
+- `--environment <environment>`: target environment identifier; defaults to the
+  logged-in target and must be paired with `--project`
 - `--output <path>`: release JSON path, default beside the bundle
 
 ### `hypequery deploy`
@@ -211,17 +266,21 @@ release. The command verifies both inputs again, requires their bundle
 identities to match, and streams only the files declared by the bundle.
 
 ```bash
-HYPEQUERY_API_TOKEN=<token> \
 npx hypequery deploy analytics/hypequery-deployment \
-  --release analytics/hypequery-deployment.release.json \
-  --endpoint https://deploy.example.com/v1/releases
+  --release analytics/hypequery-deployment.release.json
 ```
 
-The token is accepted only through `HYPEQUERY_API_TOKEN`, keeping it out of
-shell history. The submission endpoint must use HTTPS, may also be supplied by
-`HYPEQUERY_DEPLOYMENT_ENDPOINT`, and must not contain credentials or a URL
-fragment. The release identity is sent as the idempotency key, so an unchanged
-release can be submitted safely again.
+For local development, run `hypequery login` first; the CLI reads the endpoint
+and token from its secure Cloud profile. For CI and manual credentials, set
+`HYPEQUERY_API_TOKEN` together with either `--endpoint` or
+`HYPEQUERY_DEPLOYMENT_ENDPOINT`. The CLI never combines one explicit value with
+the other value from the stored profile. Tokens are never accepted as
+command-line arguments, keeping them out of shell history. The submission
+endpoint must not contain credentials or a URL fragment, and must use HTTPS
+except for `127.0.0.1`/`localhost`, which is permitted for local Cloud
+development and warns that the token is sent in cleartext. The release identity
+is sent as the idempotency key, so an unchanged release can be submitted safely
+again.
 
 This command submits immutable deployment inputs. Activation, status changes,
 promotion, and rollback remain control-plane operations.
@@ -229,7 +288,7 @@ promotion, and rollback remain control-plane operations.
 Options:
 
 - `--release <path>`: required target-bound release JSON
-- `--endpoint <url>`: HTTPS submission endpoint; defaults to `HYPEQUERY_DEPLOYMENT_ENDPOINT`
+- `--endpoint <url>`: HTTPS submission endpoint; requires `HYPEQUERY_API_TOKEN`
 
 ## Non-interactive Setup
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAgLD,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAoMD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -8,6 +8,7 @@ import { generateDatasetsCommand } from './commands/generate-datasets.js';
 import { generateManifestCommand } from './commands/generate-manifest.js';
 import { buildDeploymentCommand, prepareDeploymentReleaseCommand, validateDeploymentCommand, } from './commands/deployment.js';
 import { deployCommand, } from './commands/deploy.js';
+import { loginCommand, logoutCommand, } from './commands/login.js';
 const program = new Command();
 function getCliVersion() {
     try {
@@ -28,6 +29,19 @@ program
     .name('hypequery')
     .description('Type-safe analytics layer for ClickHouse')
     .version(getCliVersion());
+program
+    .command('login')
+    .description('Authorize this machine with Hypequery Cloud')
+    .option('--cloud-url <url>', 'Cloud origin (or HYPEQUERY_CLOUD_URL)')
+    .action(runCommand(async (options) => {
+    await loginCommand(options);
+}));
+program
+    .command('logout')
+    .description('Revoke and remove the local Hypequery Cloud credential')
+    .action(runCommand(async () => {
+    await logoutCommand();
+}));
 function runCommand(action) {
     return async (...args) => {
         try {
@@ -133,8 +147,8 @@ program
 program
     .command('deployment:release <bundle>')
     .description('Prepare a target-bound release from a verified deployment bundle')
-    .requiredOption('--project <project>', 'Target project identifier')
-    .requiredOption('--environment <environment>', 'Target environment identifier')
+    .option('--project <project>', 'Target project identifier (advanced override)')
+    .option('--environment <environment>', 'Target environment identifier (advanced override)')
     .option('-o, --output <path>', 'Release JSON path (default: beside the bundle)')
     .action(runCommand(async (bundle, options) => {
     await prepareDeploymentReleaseCommand(bundle, options);
@@ -143,7 +157,7 @@ program
     .command('deploy <bundle>')
     .description('Submit a verified deployment bundle and release')
     .requiredOption('--release <path>', 'Target-bound release JSON path')
-    .option('--endpoint <url>', 'HTTPS submission endpoint (or HYPEQUERY_DEPLOYMENT_ENDPOINT)')
+    .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
     .action(runCommand(async (bundle, options) => {
     await deployCommand(bundle, options);
 }));
@@ -170,6 +184,8 @@ program
 program.on('--help', () => {
     console.log('');
     console.log('Examples:');
+    console.log('  hypequery login');
+    console.log('  hypequery logout');
     console.log('  hypequery init');
     console.log('  hypequery dev');
     console.log('  hypequery dev --port 3000');

package/dist/commands/deploy.d.ts

@@ -1,4 +1,5 @@
 import { createHttpDeploymentUploadTransport, type DeploymentSubmissionResponse } from '../utils/deployment-upload.js';
+import { type StoredCloudCredential } from '../utils/cloud-credential-store.js';
 export interface DeployOptions {
     release?: string;
     endpoint?: string;
@@ -6,6 +7,7 @@ export interface DeployOptions {
 export interface DeployDependencies {
     readonly env?: Readonly<Record<string, string | undefined>>;
     readonly createTransport?: typeof createHttpDeploymentUploadTransport;
+    readonly loadCredential?: () => Promise<StoredCloudCredential | null>;
 }
 export declare function deployCommand(bundlePath: string | undefined, options?: DeployOptions, dependencies?: DeployDependencies): Promise<DeploymentSubmissionResponse>;
 //# sourceMappingURL=deploy.d.ts.map

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAMvC,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,mCAAmC,CAAC;CACvE;AA4DD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CA0DvC"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAK5C,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,mCAAmC,CAAC;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CACvE;AA4DD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAoFvC"}

package/dist/commands/deploy.js

@@ -3,6 +3,7 @@ import { prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
 import { verifyDeploymentBundle } from '../utils/deployment-bundle.js';
 import { createHttpDeploymentUploadTransport, DeploymentUploadError, } from '../utils/deployment-upload.js';
 import { logger } from '../utils/logger.js';
+import { loadCloudCredential, } from '../utils/cloud-credential-store.js';
 const MAX_RELEASE_FILE_BYTES = 16 * 1024;
 const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
 async function readReleaseFile(releasePath) {
@@ -68,8 +69,29 @@ export async function deployCommand(bundlePath, options = {}, dependencies = {})
     }
     const releasePath = requiredConfiguration(options.release, 'Missing required --release <path>.');
     const env = dependencies.env ?? process.env;
-    const endpoint = requiredConfiguration(options.endpoint ?? env.HYPEQUERY_DEPLOYMENT_ENDPOINT, 'Missing deployment endpoint. Pass --endpoint or set HYPEQUERY_DEPLOYMENT_ENDPOINT.');
-    const token = requiredConfiguration(env.HYPEQUERY_API_TOKEN, 'Missing HYPEQUERY_API_TOKEN.');
+    let deploymentEndpoint = options.endpoint ?? env.HYPEQUERY_DEPLOYMENT_ENDPOINT;
+    let token = env.HYPEQUERY_API_TOKEN;
+    const hasExplicitEndpoint = Boolean(deploymentEndpoint);
+    const hasExplicitToken = Boolean(token);
+    if (hasExplicitEndpoint !== hasExplicitToken) {
+        throw new Error(hasExplicitEndpoint
+            ? 'An explicit deployment endpoint requires HYPEQUERY_API_TOKEN.'
+            : 'HYPEQUERY_API_TOKEN requires --endpoint or HYPEQUERY_DEPLOYMENT_ENDPOINT.\n\n'
+                + 'If you meant to use `hypequery login`, unset HYPEQUERY_API_TOKEN — '
+                + 'the CLI also reads it from a project .env file.');
+    }
+    if (!hasExplicitEndpoint) {
+        const credential = await (dependencies.loadCredential ?? loadCloudCredential)();
+        if (credential) {
+            if (Date.parse(credential.expiresAt) <= Date.now()) {
+                throw new Error('The stored Cloud credential has expired. Run `hypequery login` again.');
+            }
+            deploymentEndpoint = credential.deploymentEndpoint;
+            token = credential.token;
+        }
+    }
+    deploymentEndpoint = requiredConfiguration(deploymentEndpoint, 'Missing deployment endpoint. Run `hypequery login`, pass --endpoint, or set HYPEQUERY_DEPLOYMENT_ENDPOINT.');
+    token = requiredConfiguration(token, 'Missing deployment credential. Run `hypequery login` or set HYPEQUERY_API_TOKEN.');
     let bundle;
     try {
         bundle = await verifyDeploymentBundle(bundlePath);
@@ -91,7 +113,10 @@ export async function deployCommand(bundlePath, options = {}, dependencies = {})
         throw new DeploymentUploadError('HQ_UPLOAD_IDENTITY_MISMATCH', 'Release bundle identity does not match the verified deployment bundle.');
     }
     const createTransport = dependencies.createTransport ?? createHttpDeploymentUploadTransport;
-    const transportOptions = { endpoint, token };
+    const transportOptions = {
+        endpoint: deploymentEndpoint,
+        token,
+    };
     const result = await createTransport(transportOptions).submit(bundle, release);
     logger.success(result.status === 'accepted'
         ? 'Deployment release accepted'

package/dist/commands/deployment.d.ts

@@ -1,4 +1,5 @@
 import { type ProtocolDeploymentContract, type ProtocolDeploymentReleaseEnvelope } from '@hypequery/protocol';
+import { type StoredCloudCredential } from '../utils/cloud-credential-store.js';
 export interface BuildDeploymentOptions {
     bundleOutput?: string;
     output?: string;
@@ -14,7 +15,10 @@ export interface PrepareDeploymentReleaseOptions {
     environment?: string;
     output?: string;
 }
+export interface PrepareDeploymentReleaseDependencies {
+    loadCredential?: () => Promise<StoredCloudCredential | null>;
+}
 export declare function buildDeploymentCommand(apiPath: string | undefined, options?: BuildDeploymentOptions): Promise<ProtocolDeploymentContract>;
 export declare function validateDeploymentCommand(artifactPath: string | undefined): Promise<ProtocolDeploymentContract>;
-export declare function prepareDeploymentReleaseCommand(bundlePath: string | undefined, options?: PrepareDeploymentReleaseOptions): Promise<ProtocolDeploymentReleaseEnvelope>;
+export declare function prepareDeploymentReleaseCommand(bundlePath: string | undefined, options?: PrepareDeploymentReleaseOptions, dependencies?: PrepareDeploymentReleaseDependencies): Promise<ProtocolDeploymentReleaseEnvelope>;
 //# sourceMappingURL=deployment.d.ts.map

package/dist/commands/deployment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACvC,MAAM,qBAAqB,CAAC;AAiB7B,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAwIrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC;AA0DD,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,iCAAiC,CAAC,CA8C5C"}
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACvC,MAAM,qBAAqB,CAAC;AAc7B,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAI5C,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oCAAoC;IACnD,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAC9D;AAoDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAwIrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC;AA0DD,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,+BAAoC,EAC7C,YAAY,GAAE,oCAAyC,GACtD,OAAO,CAAC,iCAAiC,CAAC,CAgE5C"}

package/dist/commands/deployment.js

@@ -6,6 +6,7 @@ import { writeDeploymentBundle, verifyDeploymentBundle, readDeploymentRuntimeFil
 import { buildNodeRuntimeArtifact, getDeploymentRuntimeEntrypoints, } from '../utils/deployment-runtime-artifact.js';
 import { loadApiModule } from '../utils/load-api.js';
 import { logger } from '../utils/logger.js';
+import { loadCloudCredential, } from '../utils/cloud-credential-store.js';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const DEFAULT_BUNDLE_OUTPUT = 'analytics/hypequery-deployment';
 function runtimeName(options) {
@@ -274,17 +275,33 @@ async function assertOutputIsNotSymbolicLink(outputPath) {
         }
     }
 }
-export async function prepareDeploymentReleaseCommand(bundlePath, options = {}) {
+export async function prepareDeploymentReleaseCommand(bundlePath, options = {}, dependencies = {}) {
     if (!bundlePath) {
         throw new Error('Missing deployment bundle path.\n\n'
-            + 'Usage: hypequery deployment:release analytics/hypequery-deployment '
-            + '--project <project> --environment <environment>');
-    }
-    if (options.project === undefined) {
-        throw new Error('Missing required --project <project>.');
-    }
-    if (options.environment === undefined) {
-        throw new Error('Missing required --environment <environment>.');
+            + 'Usage: hypequery deployment:release analytics/hypequery-deployment');
+    }
+    // Passing either flag opts out of the logged-in target entirely. Completing
+    // a half-specified override from the stored profile would silently retarget
+    // the release — `--project "$P" --environment "$E"` with an unset variable
+    // must fail loudly, not bind to whatever the last login used.
+    let project;
+    let environment;
+    if (options.project !== undefined || options.environment !== undefined) {
+        if (!options.project)
+            throw new Error('Missing required --project <project>.');
+        if (!options.environment)
+            throw new Error('Missing required --environment <environment>.');
+        project = options.project;
+        environment = options.environment;
+    }
+    else {
+        const credential = await (dependencies.loadCredential ?? loadCloudCredential)();
+        project = credential?.target?.project;
+        environment = credential?.target?.environment;
+        if (!project || !environment) {
+            throw new Error('Missing deployment target. Run `hypequery login` or pass both '
+                + '--project <project> and --environment <environment>.');
+        }
     }
     const outputPath = options.output ?? `${bundlePath.replace(/[\\/]+$/, '')}.release.json`;
     assertOutputOutsideBundle(bundlePath, outputPath);
@@ -302,14 +319,15 @@ export async function prepareDeploymentReleaseCommand(bundlePath, options = {})
         version: 1,
         bundleIdentity: bundle.identity,
         target: {
-            project: options.project,
-            environment: options.environment,
+            project,
+            environment,
         },
     });
     await mkdir(path.dirname(outputPath), { recursive: true });
     await assertOutputIsNotSymbolicLink(outputPath);
     await writeFile(outputPath, `${prepared.canonical}\n`, 'utf8');
     logger.success(`Deployment release written to ${outputPath}`);
+    logger.info(`Target: ${project}/${environment}`);
     logger.info(`Release identity: ${prepared.identity}`);
     logger.info(`Bundle identity: ${bundle.identity}`);
     return prepared.release;

package/dist/commands/login.d.ts

@@ -0,0 +1,21 @@
+import { deleteCloudCredential, loadCloudCredential, saveCloudCredential } from '../utils/cloud-credential-store.js';
+export interface LoginOptions {
+    readonly cloudUrl?: string;
+}
+export interface LoginDependencies {
+    readonly fetch?: typeof fetch;
+    readonly openBrowser?: (url: string) => Promise<unknown>;
+    readonly now?: () => number;
+    readonly requestTimeoutMs?: number;
+    readonly saveCredential?: typeof saveCloudCredential;
+    readonly timeoutMs?: number;
+}
+export interface LogoutDependencies {
+    readonly fetch?: typeof fetch;
+    readonly loadCredential?: typeof loadCloudCredential;
+    readonly deleteCredential?: typeof deleteCloudCredential;
+    readonly requestTimeoutMs?: number;
+}
+export declare function loginCommand(options?: LoginOptions, dependencies?: LoginDependencies): Promise<void>;
+export declare function logoutCommand(dependencies?: LogoutDependencies): Promise<void>;
+//# sourceMappingURL=login.d.ts.map

package/dist/commands/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/commands/login.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,qBAAqB,EACrB,mBAAmB,EAGnB,mBAAmB,EAEpB,MAAM,oCAAoC,CAAC;AAgB5C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,mBAAmB,CAAC;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,mBAAmB,CAAC;IACrD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,qBAAqB,CAAC;IACzD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAsJD,wBAAsB,YAAY,CAChC,OAAO,GAAE,YAAiB,EAC1B,YAAY,GAAE,iBAAsB,iBAoDrC;AAED,wBAAsB,aAAa,CAAC,YAAY,GAAE,kBAAuB,iBAoCxE"}

package/dist/commands/login.js

@@ -0,0 +1,241 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import open from 'open';
+import { validateProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+import { CLOUD_DEPLOYMENT_SCOPE, deleteCloudCredential, loadCloudCredential, normalizeCloudDeploymentEndpoint, normalizeCloudOrigin, saveCloudCredential, } from '../utils/cloud-credential-store.js';
+import { logger } from '../utils/logger.js';
+const DEFAULT_CLOUD_URL = 'https://cloud.hypequery.com';
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+// Cloud issues 12-hour credentials; allow limited client/server clock skew.
+const MAX_TOKEN_LIFETIME_MS = 13 * 60 * 60_000;
+// Cloud owns the token format. Validate only what protects this client — an
+// opaque, header-safe bearer credential of a sane length — rather than pinning
+// a version prefix or exact length that would break every already-published
+// CLI the day Cloud rotates its token format.
+const TOKEN_PATTERN = /^hqdp_[A-Za-z0-9_-]{16,512}$/;
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+function callbackHtml(success) {
+    const title = success ? 'CLI authorized' : 'Authorization failed';
+    const message = success
+        ? 'You can close this window and return to your terminal.'
+        : 'Return to your terminal and run the login command again.';
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${title}</title></head><body><main><h1>${title}</h1><p>${message}</p></main></body></html>`;
+}
+async function callbackServer(state, timeoutMs) {
+    let settle;
+    let reject;
+    const code = new Promise((resolve, rejectPromise) => {
+        settle = resolve;
+        reject = rejectPromise;
+    });
+    // The caller only awaits `code` after the browser has been opened, which
+    // takes long enough for a rejection to be seen as unhandled and terminate
+    // the process. This keeps a handler attached from the very first tick.
+    code.catch(() => undefined);
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        if (request.method !== 'GET' || url.pathname !== '/callback') {
+            response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            response.end('Not found');
+            return;
+        }
+        const returnedState = url.searchParams.get('state');
+        const authorizationCode = url.searchParams.get('code');
+        const authorizationError = url.searchParams.get('error');
+        const stateMatches = returnedState === state;
+        const valid = stateMatches
+            && typeof authorizationCode === 'string'
+            && authorizationCode.length >= 1
+            && authorizationCode.length <= 4096;
+        response.writeHead(valid ? 200 : 400, {
+            'Cache-Control': 'no-store',
+            'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'",
+            'Content-Type': 'text/html; charset=utf-8',
+            'Referrer-Policy': 'no-referrer',
+            'X-Content-Type-Options': 'nosniff',
+        });
+        response.end(callbackHtml(valid));
+        // Only a matching callback completes the login. Any web page the user has
+        // open can issue a no-CORS request to this port, so a mismatch is ignored
+        // rather than settled: aborting here would let a background tab cancel a
+        // legitimate login. A matching Cloud error still ends the transaction.
+        if (valid)
+            settle?.(authorizationCode);
+        else if (stateMatches && authorizationError) {
+            reject?.(new Error('Cloud authorization was not completed.'));
+        }
+    });
+    server.listen(0, '127.0.0.1');
+    await new Promise((resolve, rejectListen) => {
+        server.once('listening', resolve);
+        server.once('error', rejectListen);
+    });
+    const address = server.address();
+    const timer = setTimeout(() => {
+        reject?.(new Error('CLI authorization timed out. Run `hypequery login` again.'));
+    }, timeoutMs);
+    timer.unref();
+    return {
+        code,
+        redirectUri: `http://127.0.0.1:${address.port}/callback`,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+        },
+    };
+}
+async function boundedJsonResponse(response) {
+    if (!response.body)
+        return null;
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_TOKEN_RESPONSE_BYTES) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error('Cloud returned an oversized CLI token response.');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(utf8Decoder.decode(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+function tokenResponse(input, origin, now) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error('Cloud returned an invalid CLI token response.');
+    }
+    const value = input;
+    if (typeof value.access_token !== 'string'
+        || !TOKEN_PATTERN.test(value.access_token)
+        || value.token_type !== 'Bearer'
+        || typeof value.expires_at !== 'string'
+        || !Number.isFinite(Date.parse(value.expires_at))
+        || value.scope !== CLOUD_DEPLOYMENT_SCOPE
+        || typeof value.deployment_endpoint !== 'string'
+        || value.deployment_target === undefined) {
+        throw new Error('Cloud returned an invalid CLI token response.');
+    }
+    const expiresAt = Date.parse(value.expires_at);
+    if (expiresAt <= now || expiresAt > now + MAX_TOKEN_LIFETIME_MS) {
+        throw new Error('Cloud returned an invalid CLI token expiration.');
+    }
+    const deploymentEndpoint = normalizeCloudDeploymentEndpoint(value.deployment_endpoint, origin);
+    let target;
+    try {
+        target = validateProtocolDeploymentReleaseTarget(value.deployment_target);
+    }
+    catch {
+        throw new Error('Cloud returned an invalid CLI deployment target.');
+    }
+    return {
+        cloudUrl: origin,
+        deploymentEndpoint,
+        expiresAt: value.expires_at,
+        scope: value.scope,
+        target,
+        token: value.access_token,
+    };
+}
+export async function loginCommand(options = {}, dependencies = {}) {
+    const origin = normalizeCloudOrigin(options.cloudUrl ?? process.env.HYPEQUERY_CLOUD_URL ?? DEFAULT_CLOUD_URL);
+    const state = randomBytes(24).toString('base64url');
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    const callback = await callbackServer(state, dependencies.timeoutMs ?? LOGIN_TIMEOUT_MS);
+    const authorizeUrl = new URL('/cli/authorize', origin);
+    authorizeUrl.searchParams.set('redirect_uri', callback.redirectUri);
+    authorizeUrl.searchParams.set('code_challenge', challenge);
+    authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+    authorizeUrl.searchParams.set('state', state);
+    try {
+        logger.info('Opening your browser to authorize Hypequery CLI…');
+        await (dependencies.openBrowser ?? open)(authorizeUrl.toString());
+        logger.info(`If the browser did not open, visit:\n${authorizeUrl}`);
+        const code = await callback.code;
+        callback.close();
+        const request = dependencies.fetch ?? fetch;
+        const response = await request(new URL('/api/cli/token', origin), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                grant_type: 'authorization_code',
+                code,
+                code_verifier: verifier,
+                redirect_uri: callback.redirectUri,
+            }),
+            redirect: 'error',
+            signal: AbortSignal.timeout(dependencies.requestTimeoutMs ?? REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error('Cloud rejected the CLI authorization code. Run `hypequery login` again.');
+        }
+        const body = await boundedJsonResponse(response);
+        const credential = tokenResponse(body, origin, (dependencies.now ?? Date.now)());
+        await (dependencies.saveCredential ?? saveCloudCredential)(credential);
+        logger.success('Logged in to Hypequery Cloud');
+        logger.info(`Credential expires ${new Date(credential.expiresAt).toLocaleString()}`);
+    }
+    finally {
+        callback.close();
+    }
+}
+export async function logoutCommand(dependencies = {}) {
+    const load = dependencies.loadCredential ?? loadCloudCredential;
+    const remove = dependencies.deleteCredential ?? deleteCloudCredential;
+    let credential = null;
+    let unreadable = false;
+    try {
+        credential = await load();
+    }
+    catch {
+        // Logout is the command users reach for when local state is broken, so a
+        // corrupt profile or an unreachable vault must not block the cleanup below.
+        unreadable = true;
+        logger.warn('The stored Cloud credential could not be read; removing local state without revoking. The token will expire automatically.');
+    }
+    if (!credential && !unreadable) {
+        logger.info('You are not logged in to Hypequery Cloud.');
+        return;
+    }
+    if (credential) {
+        try {
+            const request = dependencies.fetch ?? fetch;
+            const response = await request(new URL('/api/cli/token', credential.cloudUrl), {
+                method: 'DELETE',
+                headers: { Authorization: `Bearer ${credential.token}` },
+                redirect: 'error',
+                signal: AbortSignal.timeout(dependencies.requestTimeoutMs ?? REQUEST_TIMEOUT_MS),
+            });
+            await response.body?.cancel().catch(() => undefined);
+            if (!response.ok)
+                throw new Error(`Cloud returned HTTP ${response.status}.`);
+        }
+        catch {
+            logger.warn('Cloud could not be reached; the local credential was removed and the token will expire automatically.');
+        }
+    }
+    await remove();
+    logger.success('Logged out of Hypequery Cloud');
+}

package/dist/utils/cloud-credential-store.d.ts

@@ -0,0 +1,28 @@
+import { type ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+export declare const CLOUD_DEPLOYMENT_SCOPE = "deploy:submit";
+export interface StoredCloudCredential {
+    readonly cloudUrl: string;
+    readonly deploymentEndpoint: string;
+    readonly expiresAt: string;
+    readonly scope: string;
+    readonly target?: ProtocolDeploymentReleaseTarget;
+    readonly token: string;
+}
+interface KeyringEntry {
+    setPassword(password: string): void | Promise<void>;
+    getPassword(): string | null | Promise<string | null>;
+    deletePassword(): unknown;
+}
+export interface CloudCredentialStoreDependencies {
+    readonly configDirectory?: string;
+    readonly createKeyringEntry?: (service: string, account: string) => Promise<KeyringEntry> | KeyringEntry;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly platform?: NodeJS.Platform;
+}
+export declare function normalizeCloudOrigin(input: string): string;
+export declare function normalizeCloudDeploymentEndpoint(input: string, cloudOrigin: string): string;
+export declare function saveCloudCredential(credential: StoredCloudCredential, dependencies?: CloudCredentialStoreDependencies): Promise<void>;
+export declare function loadCloudCredential(dependencies?: CloudCredentialStoreDependencies): Promise<StoredCloudCredential | null>;
+export declare function deleteCloudCredential(dependencies?: CloudCredentialStoreDependencies): Promise<void>;
+export {};
+//# sourceMappingURL=cloud-credential-store.d.ts.map

package/dist/utils/cloud-credential-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-credential-store.d.ts","sourceRoot":"","sources":["../../src/utils/cloud-credential-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,qBAAqB,CAAC;AAI7B,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAGtD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,+BAA+B,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAYD,UAAU,YAAY;IACpB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,cAAc,IAAI,OAAO,CAAC;CAC3B;AAQD,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAyCD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAmBR;AAmFD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,qBAAqB,EACjC,YAAY,GAAE,gCAAqC,iBAiEpD;AAED,wBAAsB,mBAAmB,CACvC,YAAY,GAAE,gCAAqC,GAClD,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAsBvC;AA0BD,wBAAsB,qBAAqB,CACzC,YAAY,GAAE,gCAAqC,iBA0BpD"}

package/dist/utils/cloud-credential-store.js

@@ -0,0 +1,293 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { validateProtocolDeploymentReleaseTarget, } from '@hypequery/protocol';
+const KEYCHAIN_SERVICE = 'dev.hypequery.cli';
+const PROFILE_FILE = 'cloud-profile.json';
+export const CLOUD_DEPLOYMENT_SCOPE = 'deploy:submit';
+const MAX_KEYCHAIN_ACCOUNT_LENGTH = 2048;
+function defaultConfigDirectory(env, platform) {
+    if (env.HYPEQUERY_CONFIG_DIR)
+        return env.HYPEQUERY_CONFIG_DIR;
+    if (platform === 'win32') {
+        return path.join(env.APPDATA ?? env.LOCALAPPDATA ?? homedir(), 'hypequery');
+    }
+    if (platform === 'darwin') {
+        return path.join(homedir(), 'Library', 'Application Support', 'hypequery');
+    }
+    return path.join(env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config'), 'hypequery');
+}
+function vaultUnavailable(error) {
+    return new Error('The operating-system credential vault is unavailable. '
+        + 'Install its keyring service or use HYPEQUERY_API_TOKEN for manual authentication.', { cause: error });
+}
+async function defaultKeyringEntry(service, account) {
+    try {
+        const { Entry } = await import('@napi-rs/keyring');
+        return new Entry(service, account);
+    }
+    catch (error) {
+        throw vaultUnavailable(error);
+    }
+}
+function paths(dependencies) {
+    const env = dependencies.env ?? process.env;
+    const platform = dependencies.platform ?? process.platform;
+    const directory = dependencies.configDirectory
+        ?? defaultConfigDirectory(env, platform);
+    return { directory, profile: path.join(directory, PROFILE_FILE) };
+}
+export function normalizeCloudOrigin(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error('Cloud URL must be an absolute HTTPS URL.');
+    }
+    const loopback = url.protocol === 'http:'
+        && (url.hostname === '127.0.0.1' || url.hostname === 'localhost');
+    if ((url.protocol !== 'https:' && !loopback) || url.username || url.password
+        || url.pathname !== '/' || url.search || url.hash) {
+        throw new Error('Cloud URL must be an HTTPS origin without a path, query, or credentials.');
+    }
+    return url.origin;
+}
+export function normalizeCloudDeploymentEndpoint(input, cloudOrigin) {
+    let endpoint;
+    try {
+        endpoint = new URL(input);
+    }
+    catch {
+        throw new Error('Cloud returned an invalid deployment endpoint.');
+    }
+    // Origin equality is what binds the token to the Cloud that issued it, and it
+    // is the only check that has to hold for a tampered profile to be harmless.
+    // Cloud owns its own path layout: pinning an exact submission path here would
+    // break every already-published CLI the day that path is versioned or moved.
+    if (endpoint.origin !== cloudOrigin
+        || endpoint.username
+        || endpoint.password
+        || endpoint.search
+        || endpoint.hash) {
+        throw new Error('Cloud returned an invalid deployment endpoint.');
+    }
+    return endpoint.toString();
+}
+function parseProfile(input) {
+    const parsed = JSON.parse(input);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('The stored Hypequery Cloud profile is invalid. Run `hypequery login` again.');
+    }
+    const value = parsed;
+    if (value.version !== 1
+        || typeof value.cloudUrl !== 'string'
+        || typeof value.deploymentEndpoint !== 'string'
+        || typeof value.expiresAt !== 'string'
+        || typeof value.scope !== 'string'
+        || typeof value.keychainAccount !== 'string') {
+        throw new Error('The stored Hypequery Cloud profile is invalid. Run `hypequery login` again.');
+    }
+    let cloudUrl;
+    let deploymentEndpoint;
+    let target;
+    try {
+        cloudUrl = normalizeCloudOrigin(value.cloudUrl);
+        deploymentEndpoint = normalizeCloudDeploymentEndpoint(value.deploymentEndpoint, cloudUrl);
+        if (value.keychainAccount !== cloudUrl
+            || !Number.isFinite(Date.parse(value.expiresAt))
+            || value.scope !== CLOUD_DEPLOYMENT_SCOPE) {
+            throw new Error('profile invariant mismatch');
+        }
+        target = value.target === undefined
+            ? undefined
+            : validateProtocolDeploymentReleaseTarget(value.target);
+    }
+    catch {
+        throw new Error('The stored Hypequery Cloud profile is invalid. Run `hypequery login` again.');
+    }
+    return {
+        version: 1,
+        cloudUrl,
+        deploymentEndpoint,
+        expiresAt: value.expiresAt,
+        scope: value.scope,
+        ...(target ? { target } : {}),
+        keychainAccount: value.keychainAccount,
+    };
+}
+async function entry(account, dependencies) {
+    const create = dependencies.createKeyringEntry ?? defaultKeyringEntry;
+    const created = await create(KEYCHAIN_SERVICE, account);
+    // Constructing an entry is lazy — the vault is only contacted on get/set/
+    // delete — so a locked keyring or a missing Secret Service surfaces here, not
+    // at construction. Translate those failures into the same actionable error.
+    return {
+        async setPassword(password) {
+            try {
+                await created.setPassword(password);
+            }
+            catch (error) {
+                throw vaultUnavailable(error);
+            }
+        },
+        async getPassword() {
+            try {
+                return await created.getPassword();
+            }
+            catch (error) {
+                throw vaultUnavailable(error);
+            }
+        },
+        async deletePassword() {
+            try {
+                return await created.deletePassword();
+            }
+            catch (error) {
+                throw vaultUnavailable(error);
+            }
+        },
+    };
+}
+export async function saveCloudCredential(credential, dependencies = {}) {
+    const location = paths(dependencies);
+    let previousProfile = null;
+    try {
+        previousProfile = parseProfile(await readFile(location.profile, 'utf8'));
+    }
+    catch {
+        // A new login must be able to replace a missing or malformed profile; the
+        // only thing lost is the chance to purge a superseded vault entry.
+        previousProfile = null;
+    }
+    const cloudUrl = normalizeCloudOrigin(credential.cloudUrl);
+    const deploymentEndpoint = normalizeCloudDeploymentEndpoint(credential.deploymentEndpoint, cloudUrl);
+    if (!Number.isFinite(Date.parse(credential.expiresAt))
+        || credential.scope !== CLOUD_DEPLOYMENT_SCOPE) {
+        throw new Error('Cannot store an invalid Hypequery Cloud credential.');
+    }
+    const keychainAccount = cloudUrl;
+    const keyring = await entry(keychainAccount, dependencies);
+    const previousPassword = await keyring.getPassword();
+    await keyring.setPassword(credential.token);
+    const profile = {
+        version: 1,
+        cloudUrl,
+        deploymentEndpoint,
+        expiresAt: credential.expiresAt,
+        scope: credential.scope,
+        ...(credential.target ? { target: credential.target } : {}),
+        keychainAccount,
+    };
+    const temporary = `${location.profile}.${randomUUID()}.tmp`;
+    try {
+        await mkdir(location.directory, { recursive: true, mode: 0o700 });
+        await chmod(location.directory, 0o700);
+        await writeFile(temporary, `${JSON.stringify(profile, null, 2)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: 0o600,
+        });
+        await chmod(temporary, 0o600);
+        await rename(temporary, location.profile);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        if (previousPassword === null) {
+            await keyring.deletePassword().catch(() => undefined);
+        }
+        else {
+            await keyring.setPassword(previousPassword).catch(() => undefined);
+        }
+        throw error;
+    }
+    if (previousProfile && previousProfile.keychainAccount !== keychainAccount) {
+        try {
+            const previousKeyring = await entry(previousProfile.keychainAccount, dependencies);
+            await previousKeyring.deletePassword();
+        }
+        catch {
+            // The new profile is already committed; the previous token will expire.
+        }
+    }
+}
+export async function loadCloudCredential(dependencies = {}) {
+    const location = paths(dependencies);
+    let profile;
+    try {
+        profile = parseProfile(await readFile(location.profile, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const keyring = await entry(profile.keychainAccount, dependencies);
+    const token = await keyring.getPassword();
+    if (!token) {
+        throw new Error('The Hypequery Cloud token is missing from your credential vault. Run `hypequery login` again.');
+    }
+    return {
+        cloudUrl: profile.cloudUrl,
+        deploymentEndpoint: profile.deploymentEndpoint,
+        expiresAt: profile.expiresAt,
+        scope: profile.scope,
+        ...(profile.target ? { target: profile.target } : {}),
+        token,
+    };
+}
+/**
+ * Recovers just the vault account from a profile that failed validation, so a
+ * corrupted profile can still be cleaned up. Only the account is salvaged, and
+ * only under our own keychain service, so the worst a tampered value can do is
+ * delete another Hypequery entry that `hypequery login` recreates.
+ */
+function salvageKeychainAccount(input) {
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const account = parsed.keychainAccount;
+    return typeof account === 'string'
+        && account.length > 0
+        && account.length <= MAX_KEYCHAIN_ACCOUNT_LENGTH
+        ? account
+        : null;
+}
+export async function deleteCloudCredential(dependencies = {}) {
+    const location = paths(dependencies);
+    let contents = null;
+    try {
+        contents = await readFile(location.profile, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (contents !== null) {
+        let account;
+        try {
+            account = parseProfile(contents).keychainAccount;
+        }
+        catch {
+            // `logout` is what users reach for when their profile is broken, so a
+            // malformed profile has to stay removable instead of throwing here.
+            account = salvageKeychainAccount(contents);
+        }
+        if (account !== null) {
+            const keyring = await entry(account, dependencies).catch(() => null);
+            await keyring?.deletePassword().catch(() => undefined);
+        }
+    }
+    await unlink(location.profile).catch(error => {
+        if (error.code !== 'ENOENT')
+            throw error;
+    });
+}

package/dist/utils/deployment-upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment-upload.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-upload.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAIL,KAAK,yCAAyC,EAC/C,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,YAAY,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAQ1E,MAAM,MAAM,yBAAyB,GACjC,yBAAyB,GACzB,6BAA6B,GAC7B,0BAA0B,GAC1B,mBAAmB,GACnB,oBAAoB,GACpB,4BAA4B,CAAC;AAEjC,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAM9E;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CACJ,MAAM,EAAE,wBAAwB,EAChC,OAAO,EAAE,yCAAyC,GACjD,OAAO,CAAC,4BAA4B,CAAC,CAAC;CAC1C;AAmVD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,yBAAyB,CAsF3B"}
+{"version":3,"file":"deployment-upload.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-upload.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAIL,KAAK,yCAAyC,EAC/C,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,YAAY,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAQ1E,MAAM,MAAM,yBAAyB,GACjC,yBAAyB,GACzB,6BAA6B,GAC7B,0BAA0B,GAC1B,mBAAmB,GACnB,oBAAoB,GACpB,4BAA4B,CAAC;AAEjC,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAM9E;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CACJ,MAAM,EAAE,wBAAwB,EAChC,OAAO,EAAE,yCAAyC,GACjD,OAAO,CAAC,4BAA4B,CAAC,CAAC;CAC1C;AA+VD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,yBAAyB,CAsF3B"}

package/dist/utils/deployment-upload.js

@@ -3,6 +3,7 @@ import { constants, open } from 'node:fs/promises';
 import path from 'node:path';
 import { prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
 import { DEPLOYMENT_BUNDLE_MANIFEST, } from './deployment-bundle.js';
+import { logger } from './logger.js';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const MAX_RESPONSE_BYTES = 64 * 1024;
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -30,8 +31,18 @@ function endpointUrl(input) {
     catch {
         configurationError('Deployment endpoint must be an absolute HTTPS URL.');
     }
-    if (url.protocol !== 'https:') {
-        configurationError('Deployment endpoint must use HTTPS.');
+    // Loopback HTTP exists so a local Cloud instance can be developed against.
+    // It still puts the bearer token on the wire in cleartext, where any local
+    // process listening on that port can read it, so say so rather than let a
+    // production token be pointed at localhost silently.
+    const loopbackHttp = url.protocol === 'http:'
+        && (url.hostname === '127.0.0.1' || url.hostname === 'localhost');
+    if (url.protocol !== 'https:' && !loopbackHttp) {
+        configurationError('Deployment endpoint must use HTTPS (HTTP is allowed only for loopback development).');
+    }
+    if (loopbackHttp) {
+        logger.warn(`Submitting to ${url.origin} over plaintext HTTP; the deployment token is `
+            + 'sent unencrypted. Use this only for local Cloud development.');
     }
     if (url.username || url.password) {
         configurationError('Deployment endpoint must not contain credentials.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.10.4",
+  "version": "1.11.0",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,9 @@
     "@hypequery/deployment": "0.6.0",
     "@hypequery/protocol": "0.9.0"
   },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "1.3.0"
+  },
   "peerDependencies": {
     "@hypequery/clickhouse": "*",
     "@hypequery/serve": "*"