@hs-x/cli 0.3.6 → 0.4.0

package/dist/commands/connect.js

@@ -7,7 +7,7 @@ import { controlPlaneAuthHeaders } from '../control-plane-fetch.js';
 import { loadCreateControlPlane } from '../control-plane-loader.js';
 import { executeCliHttp } from '../effect-http.js';
 import { emitHelp } from '../help.js';
-import { isInteractive, promptConfirm, promptSelect, promptText } from '../prompt.js';
+import { isInteractive, promptConfirm, promptPassword, promptSelect, promptText, } from '../prompt.js';
 import { createReporter } from '../reporter/index.js';
 import { connectHelpText } from './help-command.js';
 async function hostedHttp(input) {
@@ -22,6 +22,87 @@ async function hostedHttp(input) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
+/**
+ * A non-2xx from a hosted control-plane credential route, with the status and
+ * the CP's `{ error, message }` body preserved so callers can branch on
+ * authorization failures instead of collapsing everything into one retry
+ * message.
+ */
+class ControlPlaneRequestError extends Error {
+    name = 'ControlPlaneRequestError';
+    status;
+    errorCode;
+    constructor(status, errorCode, message) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+    }
+}
+async function toControlPlaneRequestError(response, fallback) {
+    const body = await response.json().catch(() => undefined);
+    const errorCode = isRecord(body) && typeof body.error === 'string' ? body.error : undefined;
+    const message = isRecord(body) && typeof body.message === 'string' ? body.message : fallback;
+    return new ControlPlaneRequestError(response.status, errorCode, message);
+}
+/**
+ * Credential routes (`/v1/accounts/:id/{hubspot,cloudflare}/…`) are admin-class
+ * under the control plane's PAT policy, while ordinary reads only need `read`.
+ * A deploy/read-scope token (the dashboard's create form defaults to deploy)
+ * therefore sails through every preliminary check and 403s only here — an
+ * unfixable-by-retry failure that must be reported as a scope problem, not a
+ * generic exchange error.
+ */
+function credentialAuthorizationDenied(input) {
+    if (input.error.status === 401) {
+        return inputValidationError({
+            argv: input.argv,
+            command: input.command,
+            json: input.json,
+            code: 'HSX_E_API_UNAUTHORIZED',
+            message: 'The control plane rejected the CLI credential.',
+            hint: 'Run `hs-x login` to refresh your CLI session, then retry.',
+            detail: input.error.message,
+        });
+    }
+    return inputValidationError({
+        argv: input.argv,
+        command: input.command,
+        json: input.json,
+        code: 'HSX_E_CREDENTIAL_SCOPE',
+        message: 'This CLI credential is not allowed to manage account credentials (admin scope required).',
+        hint: 'Run `hs-x login` — owners and admins get a full-access CLI session. If you logged in with a pasted API token, it needs admin scope (dashboard → API tokens); deploy and read tokens cannot connect credentials. Account members need an owner/admin to connect.',
+        detail: input.error.message,
+    });
+}
+function isCredentialAuthFailure(error) {
+    return (error instanceof ControlPlaneRequestError && (error.status === 401 || error.status === 403));
+}
+/**
+ * Probe whether the current CLI credential may manage credentials on
+ * `accountId` BEFORE any browser consent or credential prompting. Uses the
+ * credential-connection read (same admin PAT class as the connect/complete
+ * mutations); 404 just means nothing is connected yet, so only 401/403 count
+ * as a refusal. Network errors are swallowed — the real call will surface
+ * them with full context.
+ */
+async function probeCredentialAuthorization(input) {
+    let response;
+    try {
+        response = await hostedHttp({
+            url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/${input.surface}`, input.controlPlaneUrl),
+            headers: {
+                accept: 'application/json',
+                ...(await controlPlaneAuthHeaders(input.userId)),
+            },
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (response.status !== 401 && response.status !== 403)
+        return undefined;
+    return await toControlPlaneRequestError(response, `Credential authorization probe returned HTTP ${response.status}.`);
+}
 export async function connectCommand({ argv, cwd, json, }) {
     // Only a non-flag token is a subcommand — bare `connect --account-id x`
     // routes to the wizard with the flags passed through, not the help fallback.
@@ -133,6 +214,33 @@ async function connectHubspotCommand({ argv, cwd, json, }) {
             reporter.info(`Binding into HS-X account: ${active.displayName} (${active.id})`);
         }
     }
+    // Linked connects mutate an admin-class credential route. Fail here — before
+    // the PAK browser flow and prompts — when the CLI credential can't manage
+    // credentials at all (e.g. a deploy-scope API token), instead of letting the
+    // user generate and paste a PAK only to be refused at the connect call.
+    if (linked && !localControlPlane && !noControlPlane) {
+        const { activeSession } = await import('../account-store.js');
+        const store = await loadStore();
+        const probeAccountId = resolveFlag(argv, '--account-id') ??
+            activeSession(store)?.accountId?.trim() ??
+            store.defaultAccountId?.trim();
+        if (probeAccountId) {
+            const denied = await probeCredentialAuthorization({
+                controlPlaneUrl: resolveControlPlaneUrl(argv),
+                accountId: probeAccountId,
+                surface: 'hubspot',
+                userId: resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user',
+            });
+            if (denied) {
+                return credentialAuthorizationDenied({
+                    argv,
+                    command: 'connect hubspot',
+                    json,
+                    error: denied,
+                });
+            }
+        }
+    }
     let accountId = resolveFlag(argv, '--account-id');
     let developerAccountId = resolveFlag(argv, '--developer-account-id');
     let displayName = resolveFlag(argv, '--display-name');
@@ -235,7 +343,7 @@ async function connectHubspotCommand({ argv, cwd, json, }) {
                 personalAccessKey = discoveredDefault.pak;
             }
             else {
-                const answer = await promptText({
+                const answer = await promptPassword({
                     message: 'HubSpot personal access key',
                     validate: (v) => (v.length >= 10 ? undefined : 'PAK looks too short.'),
                 });
@@ -434,12 +542,21 @@ async function connectHubspotCommand({ argv, cwd, json, }) {
                 throw error;
             }
         }
-        const connection = await requestHostedControlPlaneHubSpotConnect({
-            accountId,
-            request,
-            controlPlaneUrl,
-            userId: resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user',
-        });
+        let connection;
+        try {
+            connection = await requestHostedControlPlaneHubSpotConnect({
+                accountId,
+                request,
+                controlPlaneUrl,
+                userId: resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user',
+            });
+        }
+        catch (error) {
+            if (isCredentialAuthFailure(error)) {
+                return credentialAuthorizationDenied({ argv, command: 'connect hubspot', json, error });
+            }
+            throw error;
+        }
         const result = {
             ok: true,
             command: 'connect hubspot',
@@ -758,12 +875,13 @@ async function runCloudflareOAuthFlowBody(input) {
                 controlPlaneUrl,
                 accountId: input.hsxAccountId,
                 userId: resolveFlag(input.argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user',
-                body: {
+                body: Schema.decodeUnknownSync(schemas.CloudflareOAuthCompleteRequest)({
                     code,
                     codeVerifier: pkce.verifier,
                     redirectUri: config.redirectUri,
+                    ...(input.cloudflareAccountId ? { cloudflareAccountId: input.cloudflareAccountId } : {}),
                     ...(input.displayName ? { displayName: input.displayName } : {}),
-                },
+                }),
             });
             reporter
                 .step('Cloudflare OAuth complete')
@@ -771,6 +889,20 @@ async function runCloudflareOAuthFlowBody(input) {
             return { kind: 'success-brokered', connection };
         }
         catch (error) {
+            // An authorization refusal (deploy/read-scope PAT, expired session) can
+            // never be fixed by re-running the OAuth flow — telling the user to
+            // retry sends them through browser consent in a loop.
+            if (isCredentialAuthFailure(error)) {
+                return {
+                    kind: 'error',
+                    result: credentialAuthorizationDenied({
+                        argv: input.argv,
+                        command: 'connect cloudflare',
+                        json: input.json,
+                        error,
+                    }),
+                };
+            }
             const detail = error instanceof Error ? error.message : String(error);
             return {
                 kind: 'error',
@@ -810,25 +942,48 @@ async function runCloudflareOAuthFlowBody(input) {
         }
         throw error;
     }
-    let discoveredAccountId;
+    let selectedAccountId;
     try {
-        // Resolve the account id via /accounts, NOT verifyCloudflareToken: OAuth
-        // access tokens 400 on the API-token verify endpoint, which left the id
-        // undefined and silently skipped persistence below (the credential is keyed
-        // by account id). /accounts works with the granted account-read scope.
-        const { resolveCloudflareAccountId } = await import('../cloudflare-auth.js');
-        discoveredAccountId = await resolveCloudflareAccountId(tokens.accessToken);
+        // OAuth access tokens 400 on the API-token verify endpoint. Discover the
+        // first visible account when no selector was supplied; when the user did
+        // supply one, require Cloudflare to confirm access to that exact account.
+        const { selectCloudflareAccountId } = await import('../cloudflare-auth.js');
+        const cloudflareApiBaseUrl = process.env.HSX_CLOUDFLARE_API_BASE_URL;
+        selectedAccountId = await selectCloudflareAccountId({
+            token: tokens.accessToken,
+            ...(input.cloudflareAccountId ? { requestedAccountId: input.cloudflareAccountId } : {}),
+            ...(cloudflareApiBaseUrl ? { baseUrl: cloudflareApiBaseUrl } : {}),
+        });
     }
-    catch {
-        // account discovery is best-effort
+    catch (error) {
+        const { CloudflareAccountSelectionError } = await import('../cloudflare-auth.js');
+        if (error instanceof CloudflareAccountSelectionError) {
+            return {
+                kind: 'error',
+                result: inputValidationError({
+                    argv: input.argv,
+                    command: 'connect cloudflare',
+                    json: input.json,
+                    code: error.code,
+                    message: error.message,
+                    hint: error.reason === 'verification-failed'
+                        ? 'Check the Cloudflare API connection and retry. The requested account was not selected or stored.'
+                        : 'Choose a Cloudflare account this OAuth token can access, or omit --cloudflare-account-id to use the first visible account.',
+                    detail: error.detail,
+                }),
+            };
+        }
+        if (input.cloudflareAccountId)
+            throw error;
+        // Discovery without an explicit selector remains best-effort.
     }
     // Persist the credential so a later `hs-x deploy` can reuse this connection
     // without re-authorizing. Cloudflare OAuth returns no refresh token, so the
     // access token IS what we store (with its expiry); deploy uses it directly
     // while valid and prompts a reconnect once it lapses.
-    if (discoveredAccountId && (tokens.refreshToken || tokens.accessToken)) {
+    if (selectedAccountId && (tokens.refreshToken || tokens.accessToken)) {
         try {
-            await saveCloudflareOAuthCredential(discoveredAccountId, {
+            await saveCloudflareOAuthCredential(selectedAccountId, {
                 ...(tokens.refreshToken ? { refreshToken: tokens.refreshToken } : {}),
                 ...(tokens.accessToken
                     ? { accessToken: tokens.accessToken, accessTokenExpiresAt: tokens.expiresAt }
@@ -842,11 +997,11 @@ async function runCloudflareOAuthFlowBody(input) {
     }
     reporter
         .step('Cloudflare OAuth complete')
-        .ok(discoveredAccountId ? `account ${discoveredAccountId} (dev)` : 'token acquired (dev)');
+        .ok(selectedAccountId ? `account ${selectedAccountId} (dev)` : 'token acquired (dev)');
     return {
         kind: 'success-local',
         accessToken: tokens.accessToken,
-        ...(discoveredAccountId ? { cloudflareAccountId: discoveredAccountId } : {}),
+        ...(selectedAccountId ? { cloudflareAccountId: selectedAccountId } : {}),
     };
 }
 async function postCloudflareOAuthComplete(input) {
@@ -861,8 +1016,7 @@ async function postCloudflareOAuthComplete(input) {
         body: input.body,
     });
     if (!response.ok) {
-        const text = await response.text().catch(() => '');
-        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
+        throw await toControlPlaneRequestError(response, `Cloudflare OAuth completion failed with HTTP ${response.status}.`);
     }
     const raw = (await response.json());
     return Schema.decodeUnknownSync(schemas.CloudflareConnection)(raw);
@@ -881,7 +1035,7 @@ async function promptHubspotBrowserFlow(argv) {
     await openInBrowser(HUBSPOT_PAK_GENERATION_URL);
     reporter.info('On the HubSpot page: generate a PAK and copy it.');
     for (;;) {
-        const pak = await promptText({
+        const pak = await promptPassword({
             message: 'Paste your HubSpot personal access key',
             validate: (v) => (v.length >= 20 ? undefined : 'PAK looks too short.'),
         });
@@ -966,6 +1120,78 @@ async function connectCloudflareCommand({ argv, json, }) {
     const interactive = !json && isInteractive();
     let cloudflareAccountId = resolveFlag(argv, '--cloudflare-account-id');
     let displayName = resolveFlag(argv, '--display-name');
+    // Linked OAuth mutates the named HS-X account after the user grants consent.
+    // Fail before opening the browser when that account is only a stale local
+    // record or the current user is not a member. Otherwise the user completes
+    // Cloudflare consent only to receive a late 404 from the broker callback.
+    if (linked && !localControlPlane) {
+        const controlPlaneUrl = resolveControlPlaneUrl(argv);
+        const userId = resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user';
+        let response;
+        try {
+            response = await hostedHttp({
+                url: new URL('/v1/accounts/me', controlPlaneUrl),
+                headers: {
+                    accept: 'application/json',
+                    'x-hsx-account-id': accountId,
+                    ...(await controlPlaneAuthHeaders(userId)),
+                },
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return inputValidationError({
+                argv,
+                command: 'connect cloudflare',
+                json,
+                code: 'HSX_E_API_NETWORK',
+                message: 'Could not verify the target HS-X account before Cloudflare authorization.',
+                hint: 'Check the control-plane URL and network connection, then retry.',
+                detail,
+            });
+        }
+        if (!response.ok) {
+            const status = response.status;
+            const code = status === 404
+                ? 'HSX_E_API_NOT_FOUND'
+                : status === 401 || status === 403
+                    ? 'HSX_E_API_UNAUTHORIZED'
+                    : status >= 500
+                        ? 'HSX_E_API_SERVER'
+                        : 'HSX_E_API_BAD_REQUEST';
+            return inputValidationError({
+                argv,
+                command: 'connect cloudflare',
+                json,
+                code,
+                message: status === 404
+                    ? `HS-X account ${accountId} does not exist on this control plane or is not available to the current user.`
+                    : `Could not verify HS-X account ${accountId} before Cloudflare authorization.`,
+                hint: status === 404
+                    ? 'Run `hs-x api /v1/users/me/accounts` and choose an account returned by the control plane.'
+                    : 'Refresh your HS-X login and retry.',
+                detail: `Account preflight returned HTTP ${status}.`,
+            });
+        }
+        // Membership verified — now verify this credential may MANAGE credentials.
+        // The account read above is read-class under PAT policy; the OAuth
+        // completion is admin-class. Without this probe a deploy-scope token
+        // passes preflight, burns a full browser consent, and only then 403s.
+        const denied = await probeCredentialAuthorization({
+            controlPlaneUrl,
+            accountId,
+            surface: 'cloudflare',
+            userId,
+        });
+        if (denied) {
+            return credentialAuthorizationDenied({
+                argv,
+                command: 'connect cloudflare',
+                json,
+                error: denied,
+            });
+        }
+    }
     // OAuth (authorization code + PKCE) is the ONLY connection method — owner
     // decision 2026-06-11. No API-token paste path in the CLI or the dashboard:
     // the consent screen grants exactly the scopes HS-X needs, and the
@@ -996,6 +1222,7 @@ async function connectCloudflareCommand({ argv, json, }) {
         json,
         hsxAccountId: accountId,
         brokered: linked,
+        ...(cloudflareAccountId ? { cloudflareAccountId } : {}),
         ...(displayName ? { displayName } : {}),
     });
     if (oauthOutcome.kind === 'cancelled') {
@@ -1102,16 +1329,25 @@ async function connectCloudflareCommand({ argv, json, }) {
     };
     const controlPlaneUrl = resolveFlag(argv, '--control-plane-url') ?? process.env.HSX_CONTROL_PLANE_URL;
     const userId = resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user';
-    const connection = controlPlaneUrl
-        ? await requestHostedControlPlaneCloudflareConnect({
-            accountId,
-            request,
-            controlPlaneUrl,
-            userId,
-        })
-        : argv.includes('--local-control-plane')
-            ? await requestLocalControlPlaneCloudflareConnect({ accountId, request, userId })
-            : undefined;
+    let connection;
+    try {
+        connection = controlPlaneUrl
+            ? await requestHostedControlPlaneCloudflareConnect({
+                accountId,
+                request,
+                controlPlaneUrl,
+                userId,
+            })
+            : argv.includes('--local-control-plane')
+                ? await requestLocalControlPlaneCloudflareConnect({ accountId, request, userId })
+                : undefined;
+    }
+    catch (error) {
+        if (isCredentialAuthFailure(error)) {
+            return credentialAuthorizationDenied({ argv, command: 'connect cloudflare', json, error });
+        }
+        throw error;
+    }
     if (!connection) {
         const result = {
             ok: true,
@@ -1198,7 +1434,7 @@ async function requestHostedControlPlaneHubSpotConnect({ accountId, request, con
     });
     const body = await response.json();
     if (!response.ok) {
-        throw new Error(isRecord(body) && typeof body.message === 'string'
+        throw new ControlPlaneRequestError(response.status, isRecord(body) && typeof body.error === 'string' ? body.error : undefined, isRecord(body) && typeof body.message === 'string'
             ? body.message
             : `Control-plane HubSpot connect failed with status ${response.status}`);
     }
@@ -1234,7 +1470,7 @@ async function requestHostedControlPlaneCloudflareConnect({ accountId, request,
     });
     const body = await response.json();
     if (!response.ok) {
-        throw new Error(isRecord(body) && typeof body.message === 'string'
+        throw new ControlPlaneRequestError(response.status, isRecord(body) && typeof body.error === 'string' ? body.error : undefined, isRecord(body) && typeof body.message === 'string'
             ? body.message
             : `Control-plane Cloudflare connect failed with status ${response.status}`);
     }