@p0security/cli 0.7.1 → 0.8.1

package/dist/drivers/api.js

@@ -32,12 +32,21 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.baseFetch = exports.fetchExerciseGrant = exports.fetchCommand = void 0;
+exports.baseFetch = exports.fetchCommand = void 0;
+/** Copyright © 2024-present P0 Security
+
+This file is part of @p0security/cli
+
+@p0security/cli is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
+
+@p0security/cli is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
+**/
 const env_1 = require("../drivers/env");
 const path = __importStar(require("node:path"));
 const tenantUrl = (tenant) => `${env_1.config.appUrl}/o/${tenant}`;
 const commandUrl = (tenant) => `${tenantUrl(tenant)}/command/`;
-const exerciseGrantUrl = (tenant) => `${tenantUrl(tenant)}/exercise-grant/`;
 const fetchCommand = (authn, args, argv) => __awaiter(void 0, void 0, void 0, function* () {
     return (0, exports.baseFetch)(authn, commandUrl(authn.identity.org.slug), "POST", JSON.stringify({
         argv,
@@ -45,10 +54,6 @@ const fetchCommand = (authn, args, argv) => __awaiter(void 0, void 0, void 0, fu
     }));
 });
 exports.fetchCommand = fetchCommand;
-const fetchExerciseGrant = (authn, args) => __awaiter(void 0, void 0, void 0, function* () {
-    return (0, exports.baseFetch)(authn, exerciseGrantUrl(authn.identity.org.slug), "POST", JSON.stringify(args));
-});
-exports.fetchExerciseGrant = fetchExerciseGrant;
 const baseFetch = (authn, url, method, body) => __awaiter(void 0, void 0, void 0, function* () {
     const token = yield authn.userCredential.user.getIdToken();
     const response = yield fetch(url, {

package/dist/index.d.ts

@@ -1,2 +1 @@
-export declare const TERMINATION_CONTROLLER: AbortController;
 export declare const main: () => void;

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.main = exports.TERMINATION_CONTROLLER = void 0;
+exports.main = void 0;
 /** Copyright © 2024-present P0 Security
 
 This file is part of @p0security/cli
@@ -13,17 +13,6 @@ You should have received a copy of the GNU General Public License along with @p0
 **/
 const commands_1 = require("./commands");
 const lodash_1 = require("lodash");
-const node_os_1 = require("node:os");
-// Subscribing to this global abort controller allows handling process termination signals anywhere in the application
-exports.TERMINATION_CONTROLLER = new AbortController();
-const terminationHandler = (code) => () => {
-    exports.TERMINATION_CONTROLLER.abort(code);
-    process.exit(128 + code); // by convention the exit code is the signal code + 128
-};
-process.on("SIGHUP", terminationHandler(node_os_1.constants.signals.SIGHUP));
-process.on("SIGINT", terminationHandler(node_os_1.constants.signals.SIGINT));
-process.on("SIGQUIT", terminationHandler(node_os_1.constants.signals.SIGQUIT));
-process.on("SIGTERM", terminationHandler(node_os_1.constants.signals.SIGTERM));
 const main = () => {
     // We can suppress output here, as .fail() already print1 errors
     void commands_1.cli.parse().catch(lodash_1.noop);

package/dist/plugins/aws/assumeRole.js

@@ -26,9 +26,10 @@ const api_1 = require("./api");
 const api_2 = require("./api");
 const roleArn = (args) => `${(0, api_1.arnPrefix)(args.account)}:role/${args.role}`;
 const stsAssume = (params) => __awaiter(void 0, void 0, void 0, function* () {
-    const url = `https://sts.amazonaws.com?${(0, fetch_1.urlEncode)(params)}`;
+    const url = `https://sts.amazonaws.com`;
     const response = yield fetch(url, {
-        method: "GET",
+        method: "POST",
+        body: new URLSearchParams(params),
     });
     yield (0, fetch_1.validateResponse)(response);
     const stsXml = yield response.text();

package/dist/plugins/aws/ssh.d.ts

@@ -0,0 +1,13 @@
+/** Copyright © 2024-present P0 Security
+
+This file is part of @p0security/cli
+
+@p0security/cli is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
+
+@p0security/cli is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
+**/
+import { SshRequest } from "../../commands/shared";
+import { AwsSsh } from "./types";
+export declare const awsRequestToSsh: (request: AwsSsh) => SshRequest;

package/dist/plugins/aws/ssh.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.awsRequestToSsh = void 0;
+const awsRequestToSsh = (request) => {
+    return {
+        id: request.permission.spec.instanceId,
+        accountId: request.permission.spec.accountId,
+        region: request.permission.spec.region,
+        role: request.generated.name,
+        linuxUserName: request.generated.ssh.linuxUserName,
+        type: "aws",
+    };
+};
+exports.awsRequestToSsh = awsRequestToSsh;

package/dist/plugins/aws/types.d.ts

@@ -8,6 +8,8 @@ This file is part of @p0security/cli
 
 You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
 **/
+import { CliPermissionSpec, PermissionSpec } from "../../types/request";
+import { CommonSshPermissionSpec } from "../ssh/types";
 export declare type AwsCredentials = {
     AWS_ACCESS_KEY_ID: string;
     AWS_SECRET_ACCESS_KEY: string;
@@ -50,19 +52,21 @@ export declare type AwsItem = {
 export declare type AwsConfig = {
     "iam-write": Record<string, AwsItemConfig>;
 };
-export declare type AwsSsh = {
-    permission: {
-        spec: {
-            awsResourcePermission: {
-                resource: {
-                    arn: string;
-                };
-            };
-        };
-        type: "session";
+export declare type AwsSshPermission = {
+    spec: CommonSshPermissionSpec & {
+        instanceId: string;
+        accountId: string;
+        region: string;
+        type: "aws";
     };
-    generated: {
-        documentName: string;
+    type: "session";
+};
+export declare type AwsSshGenerated = {
+    name: string;
+    ssh: {
+        linuxUserName: string;
     };
 };
+export declare type AwsPermissionSpec = PermissionSpec<"ssh", AwsSshPermission, AwsSshGenerated>;
+export declare type AwsSsh = CliPermissionSpec<AwsPermissionSpec>;
 export {};

package/dist/plugins/google/ssh-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Adds an ssh public key to the user object's sshPublicKeys array in Google Workspace.
+ * GCP OS Login uses these public keys to authenticate the user.
+ * Importing the same public key multiple times is idempotent.
+ *
+ * The user account and the access token is retrieved from the gcloud CLI.
+ *
+ * Returns the posix account to use for SSH access.
+ *
+ * See https://cloud.google.com/compute/docs/oslogin/rest/v1/users/importSshPublicKey
+ */
+export declare const importSshKey: (publicKey: string, options?: {
+    debug?: boolean;
+}) => Promise<string>;

package/dist/plugins/google/ssh-key.js

@@ -0,0 +1,80 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importSshKey = void 0;
+/** Copyright © 2024-present P0 Security
+
+This file is part of @p0security/cli
+
+@p0security/cli is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
+
+@p0security/cli is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
+**/
+const subprocess_1 = require("../../common/subprocess");
+const stdio_1 = require("../../drivers/stdio");
+/**
+ * Adds an ssh public key to the user object's sshPublicKeys array in Google Workspace.
+ * GCP OS Login uses these public keys to authenticate the user.
+ * Importing the same public key multiple times is idempotent.
+ *
+ * The user account and the access token is retrieved from the gcloud CLI.
+ *
+ * Returns the posix account to use for SSH access.
+ *
+ * See https://cloud.google.com/compute/docs/oslogin/rest/v1/users/importSshPublicKey
+ */
+const importSshKey = (publicKey, options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const debug = (_a = options === null || options === void 0 ? void 0 : options.debug) !== null && _a !== void 0 ? _a : false;
+    // Force debug=false otherwise it prints the access token
+    const accessToken = yield (0, subprocess_1.asyncSpawn)({ debug: false }, "gcloud", [
+        "auth",
+        "print-access-token",
+    ]);
+    const account = yield (0, subprocess_1.asyncSpawn)({ debug }, "gcloud", [
+        "config",
+        "get-value",
+        "account",
+    ]);
+    if (debug) {
+        (0, stdio_1.print2)(`Retrieved access token ${accessToken.slice(0, 10)}... for account ${account}`);
+    }
+    const url = `https://oslogin.googleapis.com/v1/users/${account}:importSshPublicKey`;
+    const response = yield fetch(url, {
+        method: "POST",
+        body: JSON.stringify({
+            key: publicKey,
+        }),
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+    });
+    const data = yield response.json();
+    if (debug) {
+        (0, stdio_1.print2)(`Login profile for user after importing public key: ${JSON.stringify(data)}`);
+    }
+    const { loginProfile } = data;
+    // Find the primary POSIX account for the user, or the first in the array
+    const linuxAccounts = loginProfile.posixAccounts.filter((account) => account.operatingSystemType === "LINUX");
+    const posixAccount = linuxAccounts.find((account) => account.primary) ||
+        loginProfile.posixAccounts[0];
+    if (debug) {
+        (0, stdio_1.print2)(`Picked linux user name: ${posixAccount === null || posixAccount === void 0 ? void 0 : posixAccount.username}`);
+    }
+    if (!posixAccount) {
+        throw "No POSIX accounts configured for the user. Ask your Google Workspace administrator to configure the user's POSIX account.";
+    }
+    return posixAccount.username;
+});
+exports.importSshKey = importSshKey;

package/dist/plugins/google/ssh.d.ts

@@ -0,0 +1,13 @@
+/** Copyright © 2024-present P0 Security
+
+This file is part of @p0security/cli
+
+@p0security/cli is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
+
+@p0security/cli is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
+**/
+import { SshRequest } from "../../commands/shared";
+import { GcpSsh } from "./types";
+export declare const gcpRequestToSsh: (request: GcpSsh) => SshRequest;

package/dist/plugins/google/ssh.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gcpRequestToSsh = void 0;
+const gcpRequestToSsh = (request) => {
+    return {
+        id: request.permission.spec.instanceName,
+        projectId: request.permission.spec.projectId,
+        zone: request.permission.spec.zone,
+        linuxUserName: request.cliLocalData.linuxUserName,
+        type: "gcloud",
+    };
+};
+exports.gcpRequestToSsh = gcpRequestToSsh;

package/dist/plugins/google/types.d.ts

@@ -0,0 +1,49 @@
+/** Copyright © 2024-present P0 Security
+
+This file is part of @p0security/cli
+
+@p0security/cli is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
+
+@p0security/cli is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
+**/
+import { CliPermissionSpec, PermissionSpec } from "../../types/request";
+import { CommonSshPermissionSpec } from "../ssh/types";
+export declare type GcpSshPermission = {
+    spec: CommonSshPermissionSpec & {
+        instanceName: string;
+        projectId: string;
+        zone: string;
+        type: "gcloud";
+    };
+    type: "session";
+};
+export declare type GcpPermissionSpec = PermissionSpec<"ssh", GcpSshPermission>;
+export declare type GcpSsh = CliPermissionSpec<GcpPermissionSpec, {
+    linuxUserName: string;
+}>;
+declare type PosixAccount = {
+    username: string;
+    uid: string;
+    gid: string;
+    operatingSystemType: "LINUX" | "OPERATING_SYSTEM_TYPE_UNSPECIFIED" | "WINDOWS";
+    homeDirectory?: string;
+    primary?: boolean;
+};
+declare type SshPublicKey = {
+    key: string;
+    fingerprint?: string;
+    expirationTimeUsec?: number;
+};
+declare type LoginProfile = {
+    name: string;
+    posixAccounts: PosixAccount[];
+    sshPublicKeys: {
+        [fingerprint: string]: SshPublicKey;
+    };
+};
+export declare type ImportSshPublicKeyResponse = {
+    loginProfile: LoginProfile;
+};
+export {};

package/dist/plugins/google/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/plugins/{aws/ssm → ssh}/index.d.ts

@@ -8,6 +8,6 @@ This file is part of @p0security/cli
 
 You should have received a copy of the GNU General Public License along with @p0security/cli. If not, see <https://www.gnu.org/licenses/>.
 **/
-import { ExerciseGrantResponse, ScpCommandArgs, SshCommandArgs } from "../../../commands/shared";
-import { Authn } from "../../../types/identity";
-export declare const sshOrScp: (authn: Authn, data: ExerciseGrantResponse, cmdArgs: ScpCommandArgs | SshCommandArgs, privateKey: string) => Promise<number | null>;
+import { ScpCommandArgs, SshCommandArgs, SshRequest } from "../../commands/shared";
+import { Authn } from "../../types/identity";
+export declare const sshOrScp: (authn: Authn, data: SshRequest, cmdArgs: ScpCommandArgs | SshCommandArgs, privateKey: string) => Promise<number | null>;

package/dist/plugins/ssh/index.js

@@ -0,0 +1,302 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sshOrScp = void 0;
+const keys_1 = require("../../common/keys");
+const stdio_1 = require("../../drivers/stdio");
+const util_1 = require("../../util");
+const install_1 = require("../aws/ssm/install");
+const aws_1 = require("../okta/aws");
+const ssh_agent_1 = require("../ssh-agent");
+const node_child_process_1 = require("node:child_process");
+/** Matches the error message that AWS SSM print1 when access is not propagated */
+// Note that the resource will randomly be either the SSM document or the EC2 instance
+const UNAUTHORIZED_START_SESSION_MESSAGE = /An error occurred \(AccessDeniedException\) when calling the StartSession operation: User: arn:aws:sts::.*:assumed-role\/P0GrantsRole.* is not authorized to perform: ssm:StartSession on resource: arn:aws:.*:.*:.* because no identity-based policy allows the ssm:StartSession action/;
+/**
+ * Matches the following error messages that AWS SSM print1 when ssh authorized
+ * key access hasn't propagated to the instance yet.
+ * - Connection closed by UNKNOWN port 65535
+ * - scp: Connection closed
+ * - kex_exchange_identification: Connection closed by remote host
+ */
+const CONNECTION_CLOSED_MESSAGE = /\bConnection closed\b.*\b(?:by UNKNOWN port \d+|by remote host)?/;
+const PUBLIC_KEY_DENIED_MESSAGE = /Permission denied \(publickey\)/;
+const UNAUTHORIZED_TUNNEL_USER_MESSAGE = /Error while connecting \[4033: 'not authorized'\]/;
+const UNAUTHORIZED_INSTANCES_GET_MESSAGE = /Required 'compute\.instances\.get' permission/;
+const DESTINATION_READ_ERROR = /Error while connecting \[4010: 'destination read failed'\]/;
+const GOOGLE_LOGIN_MESSAGE = /You do not currently have an active account selected/;
+/** Maximum amount of time after SSH subprocess starts to check for {@link UNPROVISIONED_ACCESS_MESSAGES}
+ *  in the process's stderr
+ */
+const DEFAULT_VALIDATION_WINDOW_MS = 5e3;
+/** Maximum number of attempts to start an SSH session
+ *
+ * Note that each attempt consumes ~ 1 s.
+ */
+const DEFAULT_MAX_SSH_RETRIES = 30;
+const GCP_MAX_SSH_RETRIES = 120; // GCP requires more time to propagate access
+/** The name of the SessionManager port forwarding document. This document is managed by AWS.  */
+const START_SSH_SESSION_DOCUMENT_NAME = "AWS-StartSSHSession";
+/**
+ * AWS
+ * There are 2 cases of unprovisioned access in AWS
+ * 1. SSM:StartSession action is missing either on the SSM document (AWS-StartSSHSession) or the EC2 instance
+ * 2. Temporary error when issuing an SCP command
+ *
+ * 1: results in UNAUTHORIZED_START_SESSION_MESSAGE
+ * 2: results in CONNECTION_CLOSED_MESSAGE
+ *
+ * Google Cloud
+ * There are 5 cases of unprovisioned access in Google Cloud.
+ * These are all potentially subject to propagation delays.
+ * 1. The linux user name is not present in the user's Google Workspace profile `posixAccounts` attribute
+ * 2. The public key is not present in the user's Google Workspace profile `sshPublicKeys` attribute
+ * 3. The user cannot act as the service account of the compute instance
+ * 4. The user cannot tunnel through the IAP tunnel to the instance
+ * 5. The user doesn't have osLogin or osAdminLogin role to the instance
+ * 5.a. compute.instances.get permission is missing
+ * 5.b. compute.instances.osLogin permission is missing
+ * 6: Rare occurrence, the exact conditions so far undetermined (together with CONNECTION_CLOSED_MESSAGE)
+ *
+ * 1, 2, 3 (yes!), 5b: result in PUBLIC_KEY_DENIED_MESSAGE
+ * 4: results in UNAUTHORIZED_TUNNEL_USER_MESSAGE and also CONNECTION_CLOSED_MESSAGE
+ * 5a: results in UNAUTHORIZED_INSTANCES_GET_MESSAGE
+ * 6: results in DESTINATION_READ_ERROR and also CONNECTION_CLOSED_MESSAGE
+ */
+const UNPROVISIONED_ACCESS_MESSAGES = [
+    { pattern: UNAUTHORIZED_START_SESSION_MESSAGE },
+    { pattern: CONNECTION_CLOSED_MESSAGE },
+    { pattern: PUBLIC_KEY_DENIED_MESSAGE },
+    { pattern: UNAUTHORIZED_TUNNEL_USER_MESSAGE },
+    { pattern: UNAUTHORIZED_INSTANCES_GET_MESSAGE, validationWindowMs: 30e3 },
+    { pattern: DESTINATION_READ_ERROR },
+];
+/** Checks if access has propagated through AWS to the SSM agent
+ *
+ * AWS takes about 8 minutes, GCP takes under 1 minute
+ * to fully resolve access after it is granted.
+ * During this time, calls to `aws ssm start-session` / `gcloud compute start-iap-tunnel`
+ * will fail randomly with an various error messages.
+ *
+ * This function checks the subprocess output to see if any of the error messages
+ * are printed to the error output within the first 5 seconds of startup.
+ * If they are, the returned `isAccessPropagated()` function will return false.
+ * When this occurs, the consumer of this function should retry the `aws` / `gcloud` command.
+ *
+ * Note that this function requires interception of the subprocess stderr stream.
+ * This works because AWS SSM wraps the session in a single-stream pty, so we
+ * do not capture stderr emitted from the wrapped shell session.
+ */
+const accessPropagationGuard = (child, debug) => {
+    let isEphemeralAccessDeniedException = false;
+    let isGoogleLoginException = false;
+    const beforeStart = Date.now();
+    child.stderr.on("data", (chunk) => {
+        const chunkString = chunk.toString("utf-8");
+        if (debug)
+            (0, stdio_1.print2)(chunkString);
+        const match = UNPROVISIONED_ACCESS_MESSAGES.find((message) => chunkString.match(message.pattern));
+        if (match &&
+            Date.now() <=
+                beforeStart + (match.validationWindowMs || DEFAULT_VALIDATION_WINDOW_MS)) {
+            isEphemeralAccessDeniedException = true;
+        }
+        const googleLoginMatch = chunkString.match(GOOGLE_LOGIN_MESSAGE);
+        isGoogleLoginException = isGoogleLoginException || !!googleLoginMatch; // once true, always true
+        if (isGoogleLoginException) {
+            isEphemeralAccessDeniedException = false; // always overwrite to false so we don't retry the access
+        }
+    });
+    return {
+        isAccessPropagated: () => !isEphemeralAccessDeniedException,
+        isGoogleLoginException: () => isGoogleLoginException,
+    };
+};
+const spawnChildProcess = (credential, command, args, stdio) => (0, node_child_process_1.spawn)(command, args, {
+    env: Object.assign(Object.assign({}, process.env), credential),
+    stdio,
+    shell: false,
+});
+const friendlyProvider = (provider) => provider === "aws"
+    ? "AWS"
+    : provider === "gcloud"
+        ? "Google Cloud"
+        : (0, util_1.throwAssertNever)(provider);
+/** Starts an SSM session in the terminal by spawning `aws ssm` as a subprocess
+ *
+ * Requires `aws ssm` to be installed on the client machine.
+ */
+function spawnSshNode(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve, reject) => {
+            const child = spawnChildProcess(options.credential, options.command, options.args, options.stdio);
+            // TODO ENG-2284 support login with Google Cloud: currently return a boolean to indicate if the exception was a Google login error.
+            const { isAccessPropagated, isGoogleLoginException } = accessPropagationGuard(child, options.debug);
+            const exitListener = child.on("exit", (code) => {
+                var _a;
+                exitListener.unref();
+                // In the case of ephemeral AccessDenied exceptions due to unpropagated
+                // permissions, continually retry access until success
+                if (!isAccessPropagated()) {
+                    const attemptsRemaining = options.attemptsRemaining;
+                    if (options.debug) {
+                        (0, stdio_1.print2)(`Waiting for access to propagate. Retrying SSH session... (remaining attempts: ${attemptsRemaining})`);
+                    }
+                    if (attemptsRemaining <= 0) {
+                        reject(`Access did not propagate through ${friendlyProvider(options.provider)} before max retry attempts were exceeded. Please contact support@p0.dev for assistance.`);
+                        return;
+                    }
+                    spawnSshNode(Object.assign(Object.assign({}, options), { attemptsRemaining: attemptsRemaining - 1 }))
+                        .then((code) => resolve(code))
+                        .catch(reject);
+                    return;
+                }
+                else if (isGoogleLoginException()) {
+                    reject(`Please login to Google Cloud CLI with 'gcloud auth login'`);
+                    return;
+                }
+                (_a = options.abortController) === null || _a === void 0 ? void 0 : _a.abort(code);
+                (0, stdio_1.print2)(`SSH session terminated`);
+                resolve(code);
+            });
+        });
+    });
+}
+const createProxyCommands = (data, args, debug) => {
+    let proxyCommand;
+    if (data.type === "aws") {
+        proxyCommand = [
+            "aws",
+            "ssm",
+            "start-session",
+            "--region",
+            data.region,
+            "--target",
+            "%h",
+            "--document-name",
+            START_SSH_SESSION_DOCUMENT_NAME,
+            "--parameters",
+            '"portNumber=%p"',
+        ];
+    }
+    else if (data.type === "gcloud") {
+        proxyCommand = [
+            "gcloud",
+            "compute",
+            "start-iap-tunnel",
+            data.id,
+            "%p",
+            // --listen-on-stdin flag is required for interactive SSH session.
+            // It is undocumented on page https://cloud.google.com/sdk/gcloud/reference/compute/start-iap-tunnel
+            // but mention on page https://cloud.google.com/iap/docs/tcp-by-host
+            // and also found in `gcloud ssh --dry-run` output
+            "--listen-on-stdin",
+            `--zone=${data.zone}`,
+            `--project=${data.projectId}`,
+        ];
+    }
+    else {
+        throw (0, util_1.assertNever)(data);
+    }
+    const commonArgs = [
+        ...(debug ? ["-v"] : []),
+        "-o",
+        `ProxyCommand=${proxyCommand.join(" ")}`,
+    ];
+    if ("source" in args) {
+        return {
+            command: "scp",
+            args: [
+                ...commonArgs,
+                // if a response is not received after three 5 minute attempts,
+                // the connection will be closed.
+                "-o",
+                "ServerAliveCountMax=3",
+                `-o`,
+                "ServerAliveInterval=300",
+                ...(args.recursive ? ["-r"] : []),
+                args.source,
+                args.destination,
+            ],
+        };
+    }
+    return {
+        command: "ssh",
+        args: [
+            ...commonArgs,
+            ...(args.A ? ["-A"] : []),
+            ...(args.L ? ["-L", args.L] : []),
+            ...(args.N ? ["-N"] : []),
+            `${data.linuxUserName}@${data.id}`,
+            ...(args.command ? [args.command] : []),
+            ...args.arguments.map((argument) => 
+            // escape all double quotes (") in commands such as `p0 ssh <instance>> echo 'hello; "world"'` because we
+            // need to encapsulate command arguments in double quotes as we pass them along to the remote shell
+            `"${String(argument).replace(/"/g, '\\"')}"`),
+        ],
+    };
+};
+/** Converts arguments for manual execution - arguments may have to be quoted or certain characters escaped when executing the commands from a shell */
+const transformForShell = (args) => {
+    return args.map((arg) => {
+        // The ProxyCommand option must be surrounded by single quotes
+        if (arg.startsWith("ProxyCommand=")) {
+            const [name, ...value] = arg.split("="); // contains the '=' character in the parameters option: ProxyCommand=aws ssm start-session ... --parameters "portNumber=%p"
+            return `${name}='${value.join("=")}'`;
+        }
+        return arg;
+    });
+};
+const awsLogin = (authn, data) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!(yield (0, install_1.ensureSsmInstall)())) {
+        throw "Please try again after installing the required AWS utilities";
+    }
+    return yield (0, aws_1.assumeRoleWithOktaSaml)(authn, {
+        account: data.accountId,
+        role: data.role,
+    });
+});
+const sshOrScp = (authn, data, cmdArgs, privateKey) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!privateKey) {
+        throw "Failed to load a private key for this request. Please contact support@p0.dev for assistance.";
+    }
+    // TODO ENG-2284 support login with Google Cloud
+    const credential = data.type === "aws" ? yield awsLogin(authn, data) : undefined;
+    return (0, ssh_agent_1.withSshAgent)(cmdArgs, () => __awaiter(void 0, void 0, void 0, function* () {
+        const { command, args } = createProxyCommands(data, cmdArgs, cmdArgs.debug);
+        if (cmdArgs.debug) {
+            const reproCommands = [
+                `eval $(ssh-agent)`,
+                `ssh-add "${keys_1.PRIVATE_KEY_PATH}"`,
+                // TODO ENG-2284 support login with Google Cloud
+                ...(data.type === "aws"
+                    ? [
+                        `eval $(p0 aws role assume ${data.role} --account ${data.accountId})`,
+                    ]
+                    : []),
+                `${command} ${transformForShell(args).join(" ")}`,
+            ];
+            (0, stdio_1.print2)(`Execute the following commands to create a similar SSH/SCP session:\n*** COMMANDS BEGIN ***\n${reproCommands.join("\n")}\n*** COMMANDS END ***"\n`);
+        }
+        const maxRetries = data.type === "gcloud" ? GCP_MAX_SSH_RETRIES : DEFAULT_MAX_SSH_RETRIES;
+        return spawnSshNode({
+            credential,
+            abortController: new AbortController(),
+            command,
+            args,
+            stdio: ["inherit", "inherit", "pipe"],
+            debug: cmdArgs.debug,
+            provider: data.type,
+            attemptsRemaining: maxRetries,
+        });
+    }));
+});
+exports.sshOrScp = sshOrScp;

package/dist/plugins/ssh/types.d.ts

@@ -15,4 +15,8 @@ declare type SshItemConfig = {
 export declare type SshConfig = {
     "iam-write": Record<string, SshItemConfig>;
 };
+export declare type CommonSshPermissionSpec = {
+    publicKey: string;
+    sudo?: boolean;
+};
 export {};