@serve.zone/cli 33.0.0 → 33.2.0

package/dist_ts_cliclient/classes.cliclient.d.ts

@@ -1,6 +1,13 @@
+import * as plugins from './plugins.js';
 import { CloudlyApiClient } from '@serve.zone/api';
 export declare class CliClient {
     cloudlyApiClient: CloudlyApiClient;
     constructor(cloudlyApiClientArg: CloudlyApiClient);
     getClusters(): Promise<void>;
+    /**
+     * Hands Cloudly the dcrouter admin token and prints the enrollment that results. The token is
+     * the caller's to wipe; the API client seals its own copy and never logs or keeps it.
+     */
+    bootstrapGateway(targetArg: plugins.servezoneApi.IExternalGatewayBootstrapTarget, bootstrapTokenArg: Uint8Array): Promise<void>;
+    getGatewayStatus(): Promise<void>;
 }

package/dist_ts_cliclient/classes.cliclient.js

@@ -8,5 +8,20 @@ export class CliClient {
         const clusters = await this.cloudlyApiClient.cluster.getClusters();
         console.log(clusters);
     }
+    /**
+     * Hands Cloudly the dcrouter admin token and prints the enrollment that results. The token is
+     * the caller's to wipe; the API client seals its own copy and never logs or keeps it.
+     */
+    async bootstrapGateway(targetArg, bootstrapTokenArg) {
+        const { state } = await this.cloudlyApiClient.settings.bootstrapExternalGatewayCredential({
+            target: targetArg,
+            bootstrapToken: bootstrapTokenArg,
+        });
+        console.log(JSON.stringify(state, null, 2));
+    }
+    async getGatewayStatus() {
+        const { state } = await this.cloudlyApiClient.settings.getExternalGatewayEnrollmentState();
+        console.log(JSON.stringify(state, null, 2));
+    }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5jbGljbGllbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19jbGljbGllbnQvY2xhc3Nlcy5jbGljbGllbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFbkQsTUFBTSxPQUFPLFNBQVM7SUFHcEIsWUFBWSxtQkFBcUM7UUFDL0MsSUFBSSxDQUFDLGdCQUFnQixHQUFHLG1CQUFtQixDQUFDO0lBQzlDLENBQUM7SUFFTSxLQUFLLENBQUMsV0FBVztRQUN0QixNQUFNLFFBQVEsR0FBRyxNQUFNLElBQUksQ0FBQyxnQkFBZ0IsQ0FBQyxPQUFPLENBQUMsV0FBVyxFQUFFLENBQUM7UUFDbkUsT0FBTyxDQUFDLEdBQUcsQ0FBQyxRQUFRLENBQUMsQ0FBQztJQUN4QixDQUFDO0NBQ0YifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5jbGljbGllbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19jbGljbGllbnQvY2xhc3Nlcy5jbGljbGllbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFbkQsTUFBTSxPQUFPLFNBQVM7SUFHcEIsWUFBWSxtQkFBcUM7UUFDL0MsSUFBSSxDQUFDLGdCQUFnQixHQUFHLG1CQUFtQixDQUFDO0lBQzlDLENBQUM7SUFFTSxLQUFLLENBQUMsV0FBVztRQUN0QixNQUFNLFFBQVEsR0FBRyxNQUFNLElBQUksQ0FBQyxnQkFBZ0IsQ0FBQyxPQUFPLENBQUMsV0FBVyxFQUFFLENBQUM7UUFDbkUsT0FBTyxDQUFDLEdBQUcsQ0FBQyxRQUFRLENBQUMsQ0FBQztJQUN4QixDQUFDO0lBRUQ7OztPQUdHO0lBQ0ksS0FBSyxDQUFDLGdCQUFnQixDQUMzQixTQUErRCxFQUMvRCxpQkFBNkI7UUFFN0IsTUFBTSxFQUFFLEtBQUssRUFBRSxHQUFHLE1BQU0sSUFBSSxDQUFDLGdCQUFnQixDQUFDLFFBQVEsQ0FBQyxrQ0FBa0MsQ0FBQztZQUN4RixNQUFNLEVBQUUsU0FBUztZQUNqQixjQUFjLEVBQUUsaUJBQWlCO1NBQ2xDLENBQUMsQ0FBQztRQUNILE9BQU8sQ0FBQyxHQUFHLENBQUMsSUFBSSxDQUFDLFNBQVMsQ0FBQyxLQUFLLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDOUMsQ0FBQztJQUVNLEtBQUssQ0FBQyxnQkFBZ0I7UUFDM0IsTUFBTSxFQUFFLEtBQUssRUFBRSxHQUFHLE1BQU0sSUFBSSxDQUFDLGdCQUFnQixDQUFDLFFBQVEsQ0FBQyxpQ0FBaUMsRUFBRSxDQUFDO1FBQzNGLE9BQU8sQ0FBQyxHQUFHLENBQUMsSUFBSSxDQUFDLFNBQVMsQ0FBQyxLQUFLLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDOUMsQ0FBQztDQUNGIn0=

package/dist_ts_cliclient/commands.d.ts

@@ -0,0 +1,22 @@
+import type * as plugins from './plugins.js';
+/** What one invocation of the CLI asks for, parsed before anything is read or connected. */
+export type TCliCommand = 
+/** No arguments: the default action, listing the clusters. */
+{
+    kind: 'clusters';
+} | {
+    kind: 'gateway-status';
+} | {
+    kind: 'gateway-bootstrap';
+    target: plugins.servezoneApi.IExternalGatewayBootstrapTarget;
+};
+export declare const cliUsage: string;
+/**
+ * An invocation the CLI does not run. It never quotes what it was given, because an argument may
+ * be a token pasted where it does not belong.
+ */
+export declare class CliUsageError extends Error {
+    constructor();
+}
+/** The command an argument vector names; any other vector is refused as usage. */
+export declare const parseCliCommand: (argsArg: readonly string[]) => TCliCommand;

package/dist_ts_cliclient/commands.js

@@ -0,0 +1,52 @@
+export const cliUsage = [
+    'Usage:',
+    '  servezone',
+    '  servezone gateway status',
+    '  servezone gateway bootstrap --gateway-url <https url> --client-id <id>',
+    '    The dcrouter admin token is read from stdin, never from arguments or the environment.',
+].join('\n');
+/**
+ * An invocation the CLI does not run. It never quotes what it was given, because an argument may
+ * be a token pasted where it does not belong.
+ */
+export class CliUsageError extends Error {
+    constructor() {
+        super(cliUsage);
+        this.name = 'CliUsageError';
+    }
+}
+function requireUsage(conditionArg) {
+    if (!conditionArg)
+        throw new CliUsageError();
+}
+/** Reads `--name value` pairs, each named option exactly once and nothing else. */
+const parseOptions = (argsArg, namesArg) => {
+    const options = new Map();
+    requireUsage(argsArg.length === namesArg.length * 2);
+    for (let index = 0; index < argsArg.length; index += 2) {
+        const name = argsArg[index];
+        const value = argsArg[index + 1];
+        requireUsage(namesArg.some((nameArg) => nameArg === name) && !options.has(name));
+        requireUsage(value.length > 0 && !value.startsWith('--'));
+        options.set(name, value);
+    }
+    return Object.fromEntries(options);
+};
+/** The command an argument vector names; any other vector is refused as usage. */
+export const parseCliCommand = (argsArg) => {
+    if (argsArg.length === 0)
+        return { kind: 'clusters' };
+    const [group, action, ...rest] = argsArg;
+    requireUsage(group === 'gateway');
+    if (action === 'status') {
+        requireUsage(rest.length === 0);
+        return { kind: 'gateway-status' };
+    }
+    requireUsage(action === 'bootstrap');
+    const options = parseOptions(rest, ['--gateway-url', '--client-id']);
+    return {
+        kind: 'gateway-bootstrap',
+        target: { gatewayUrl: options['--gateway-url'], gatewayClientId: options['--client-id'] },
+    };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29tbWFuZHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19jbGljbGllbnQvY29tbWFuZHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBU0EsTUFBTSxDQUFDLE1BQU0sUUFBUSxHQUFHO0lBQ3RCLFFBQVE7SUFDUixhQUFhO0lBQ2IsNEJBQTRCO0lBQzVCLDBFQUEwRTtJQUMxRSwyRkFBMkY7Q0FDNUYsQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUM7QUFFYjs7O0dBR0c7QUFDSCxNQUFNLE9BQU8sYUFBYyxTQUFRLEtBQUs7SUFDdEM7UUFDRSxLQUFLLENBQUMsUUFBUSxDQUFDLENBQUM7UUFDaEIsSUFBSSxDQUFDLElBQUksR0FBRyxlQUFlLENBQUM7SUFDOUIsQ0FBQztDQUNGO0FBRUQsU0FBUyxZQUFZLENBQUMsWUFBcUI7SUFDekMsSUFBSSxDQUFDLFlBQVk7UUFBRSxNQUFNLElBQUksYUFBYSxFQUFFLENBQUM7QUFDL0MsQ0FBQztBQUVELG1GQUFtRjtBQUNuRixNQUFNLFlBQVksR0FBRyxDQUNuQixPQUEwQixFQUMxQixRQUEwQixFQUNILEVBQUU7SUFDekIsTUFBTSxPQUFPLEdBQUcsSUFBSSxHQUFHLEVBQWtCLENBQUM7SUFDMUMsWUFBWSxDQUFDLE9BQU8sQ0FBQyxNQUFNLEtBQUssUUFBUSxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUMsQ0FBQztJQUNyRCxLQUFLLElBQUksS0FBSyxHQUFHLENBQUMsRUFBRSxLQUFLLEdBQUcsT0FBTyxDQUFDLE1BQU0sRUFBRSxLQUFLLElBQUksQ0FBQyxFQUFFLENBQUM7UUFDdkQsTUFBTSxJQUFJLEdBQUcsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQzVCLE1BQU0sS0FBSyxHQUFHLE9BQU8sQ0FBQyxLQUFLLEdBQUcsQ0FBQyxDQUFDLENBQUM7UUFDakMsWUFBWSxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDLE9BQU8sS0FBSyxJQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQztRQUNqRixZQUFZLENBQUMsS0FBSyxDQUFDLE1BQU0sR0FBRyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUM7UUFDMUQsT0FBTyxDQUFDLEdBQUcsQ0FBQyxJQUFJLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDM0IsQ0FBQztJQUNELE9BQU8sTUFBTSxDQUFDLFdBQVcsQ0FBQyxPQUFPLENBQTBCLENBQUM7QUFDOUQsQ0FBQyxDQUFDO0FBRUYsa0ZBQWtGO0FBQ2xGLE1BQU0sQ0FBQyxNQUFNLGVBQWUsR0FBRyxDQUFDLE9BQTBCLEVBQWUsRUFBRTtJQUN6RSxJQUFJLE9BQU8sQ0FBQyxNQUFNLEtBQUssQ0FBQztRQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsVUFBVSxFQUFFLENBQUM7SUFDdEQsTUFBTSxDQUFDLEtBQUssRUFBRSxNQUFNLEVBQUUsR0FBRyxJQUFJLENBQUMsR0FBRyxPQUFPLENBQUM7SUFDekMsWUFBWSxDQUFDLEtBQUssS0FBSyxTQUFTLENBQUMsQ0FBQztJQUNsQyxJQUFJLE1BQU0sS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUN4QixZQUFZLENBQUMsSUFBSSxDQUFDLE1BQU0sS0FBSyxDQUFDLENBQUMsQ0FBQztRQUNoQyxPQUFPLEVBQUUsSUFBSSxFQUFFLGdCQUFnQixFQUFFLENBQUM7SUFDcEMsQ0FBQztJQUNELFlBQVksQ0FBQyxNQUFNLEtBQUssV0FBVyxDQUFDLENBQUM7SUFDckMsTUFBTSxPQUFPLEdBQUcsWUFBWSxDQUFDLElBQUksRUFBRSxDQUFDLGVBQWUsRUFBRSxhQUFhLENBQUMsQ0FBQyxDQUFDO0lBQ3JFLE9BQU87UUFDTCxJQUFJLEVBQUUsbUJBQW1CO1FBQ3pCLE1BQU0sRUFBRSxFQUFFLFVBQVUsRUFBRSxPQUFPLENBQUMsZUFBZSxDQUFDLEVBQUUsZUFBZSxFQUFFLE9BQU8sQ0FBQyxhQUFhLENBQUMsRUFBRTtLQUMxRixDQUFDO0FBQ0osQ0FBQyxDQUFDIn0=

package/dist_ts_cliclient/index.d.ts

@@ -1 +1,3 @@
+export { CliUsageError, parseCliCommand, type TCliCommand } from './commands.js';
+export { BootstrapTokenInputError, readBootstrapTokenInput, type TBootstrapTokenInputRefusal, } from './tokeninput.js';
 export declare const runCli: () => Promise<void>;

package/dist_ts_cliclient/index.js

@@ -1,6 +1,56 @@
 import * as plugins from './plugins.js';
 import { CliClient } from './classes.cliclient.js';
+import { parseCliCommand } from './commands.js';
+import { readBootstrapTokenInput } from './tokeninput.js';
+export { CliUsageError, parseCliCommand } from './commands.js';
+export { BootstrapTokenInputError, readBootstrapTokenInput, } from './tokeninput.js';
 export const runCli = async () => {
+    // The command and the token are settled before anything connects, so a wrong invocation or a
+    // token that could never be one fails without reaching Cloudly.
+    let command;
+    try {
+        const parsed = parseCliCommand(process.argv.slice(2));
+        command = parsed.kind === 'gateway-bootstrap'
+            ? { ...parsed, bootstrapToken: await readBootstrapTokenInput(process.stdin) }
+            : parsed;
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const apiClient = await connect();
+        const cliClient = new CliClient(apiClient);
+        if (command.kind === 'clusters') {
+            // Default action example: list clusters when invoked without subcommands
+            await cliClient.getClusters();
+            return;
+        }
+        try {
+            if (command.kind === 'gateway-bootstrap') {
+                await cliClient.bootstrapGateway(command.target, command.bootstrapToken);
+            }
+            else {
+                await cliClient.getGatewayStatus();
+            }
+        }
+        catch (error) {
+            // Cloudly answers a refusal by name; it never carries the token.
+            console.error(error.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await apiClient.stop();
+        }
+    }
+    finally {
+        if (command.kind === 'gateway-bootstrap')
+            command.bootstrapToken.fill(0);
+    }
+};
+/** The API client, started and signed in the way every command of this CLI signs in. */
+const connect = async () => {
     // The directory the operator runs the CLI in is read for sources, exactly as before, but the
     // `required:` list it may find there is never enforced: that list is the Cloudly server's own
     // start-time contract, and none of a remote server's database, storage or keyring facts is this
@@ -15,17 +65,21 @@ export const runCli = async () => {
         cloudlyUrl,
     });
     await apiClient.start();
-    if (token) {
-        await apiClient.getIdentityByToken(token, { tagConnection: true, statefullIdentity: true });
-    }
-    else if (username && password) {
-        await apiClient.loginWithUsernameAndPassword(username, password);
+    try {
+        if (token) {
+            await apiClient.getIdentityByToken(token, { tagConnection: true, statefullIdentity: true });
+        }
+        else if (username && password) {
+            await apiClient.loginWithUsernameAndPassword(username, password);
+        }
+        else {
+            console.log('No credentials provided. Set CLOUDLY_TOKEN or CLOUDLY_USERNAME/CLOUDLY_PASSWORD.');
+        }
     }
-    else {
-        console.log('No credentials provided. Set CLOUDLY_TOKEN or CLOUDLY_USERNAME/CLOUDLY_PASSWORD.');
+    catch (error) {
+        await apiClient.stop();
+        throw error;
     }
-    const cliClient = new CliClient(apiClient);
-    // Default action example: list clusters when invoked without subcommands
-    await cliClient.getClusters();
+    return apiClient;
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19jbGljbGllbnQvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRW5ELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxLQUFLLElBQUksRUFBRTtJQUMvQiw2RkFBNkY7SUFDN0YsOEZBQThGO0lBQzlGLGdHQUFnRztJQUNoRywwRkFBMEY7SUFDMUYsTUFBTSxPQUFPLEdBQUcsSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxFQUFFLEVBQUUsU0FBUyxFQUFFLEtBQUssQ0FBQyxDQUFDO0lBQ3ZFLE1BQU0sVUFBVSxHQUFHLE1BQU0sT0FBTyxDQUFDLGlCQUFpQixDQUFDLGFBQWEsQ0FBQyxDQUFDO0lBQ2xFLE1BQU0sS0FBSyxHQUFHLE9BQU8sQ0FBQyxHQUFHLENBQUMsYUFBYSxDQUFDO0lBQ3hDLE1BQU0sUUFBUSxHQUFHLE9BQU8sQ0FBQyxHQUFHLENBQUMsZ0JBQWdCLENBQUM7SUFDOUMsTUFBTSxRQUFRLEdBQUcsT0FBTyxDQUFDLEdBQUcsQ0FBQyxnQkFBZ0IsQ0FBQztJQUU5QyxNQUFNLFNBQVMsR0FBRyxJQUFJLE9BQU8sQ0FBQyxZQUFZLENBQUMsZ0JBQWdCLENBQUM7UUFDMUQsVUFBVSxFQUFFLEtBQUs7UUFDakIsVUFBVTtLQUNYLENBQUMsQ0FBQztJQUNILE1BQU0sU0FBUyxDQUFDLEtBQUssRUFBRSxDQUFDO0lBRXhCLElBQUksS0FBSyxFQUFFLENBQUM7UUFDVixNQUFNLFNBQVMsQ0FBQyxrQkFBa0IsQ0FBQyxLQUFLLEVBQUUsRUFBRSxhQUFhLEVBQUUsSUFBSSxFQUFFLGlCQUFpQixFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7SUFDOUYsQ0FBQztTQUFNLElBQUksUUFBUSxJQUFJLFFBQVEsRUFBRSxDQUFDO1FBQ2hDLE1BQU0sU0FBUyxDQUFDLDRCQUE0QixDQUFDLFFBQVEsRUFBRSxRQUFRLENBQUMsQ0FBQztJQUNuRSxDQUFDO1NBQU0sQ0FBQztRQUNOLE9BQU8sQ0FBQyxHQUFHLENBQUMsa0ZBQWtGLENBQUMsQ0FBQztJQUNsRyxDQUFDO0lBRUQsTUFBTSxTQUFTLEdBQUcsSUFBSSxTQUFTLENBQUMsU0FBUyxDQUFDLENBQUM7SUFDM0MseUVBQXlFO0lBQ3pFLE1BQU0sU0FBUyxDQUFDLFdBQVcsRUFBRSxDQUFDO0FBQ2hDLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19jbGljbGllbnQvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQ25ELE9BQU8sRUFBRSxlQUFlLEVBQW9CLE1BQU0sZUFBZSxDQUFDO0FBQ2xFLE9BQU8sRUFBRSx1QkFBdUIsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBRTFELE9BQU8sRUFBRSxhQUFhLEVBQUUsZUFBZSxFQUFvQixNQUFNLGVBQWUsQ0FBQztBQUNqRixPQUFPLEVBQ0wsd0JBQXdCLEVBQ3hCLHVCQUF1QixHQUV4QixNQUFNLGlCQUFpQixDQUFDO0FBT3pCLE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxLQUFLLElBQUksRUFBRTtJQUMvQiw2RkFBNkY7SUFDN0YsZ0VBQWdFO0lBQ2hFLElBQUksT0FBdUIsQ0FBQztJQUM1QixJQUFJLENBQUM7UUFDSCxNQUFNLE1BQU0sR0FBRyxlQUFlLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztRQUN0RCxPQUFPLEdBQUcsTUFBTSxDQUFDLElBQUksS0FBSyxtQkFBbUI7WUFDM0MsQ0FBQyxDQUFDLEVBQUUsR0FBRyxNQUFNLEVBQUUsY0FBYyxFQUFFLE1BQU0sdUJBQXVCLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxFQUFFO1lBQzdFLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDYixDQUFDO0lBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztRQUNmLE9BQU8sQ0FBQyxLQUFLLENBQUUsS0FBZSxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBQ3hDLE9BQU8sQ0FBQyxRQUFRLEdBQUcsQ0FBQyxDQUFDO1FBQ3JCLE9BQU87SUFDVCxDQUFDO0lBRUQsSUFBSSxDQUFDO1FBQ0gsTUFBTSxT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

package/dist_ts_cliclient/tokeninput.d.ts

@@ -0,0 +1,25 @@
+/** Why the admin token piped in was not taken, named without quoting any of it. */
+export type TBootstrapTokenInputRefusal = 
+/** stdin is a terminal, which would echo a token typed into it; pipe the token in instead. */
+'token-input-terminal'
+/** stdin carried more bytes than a token and one line break. */
+ | 'token-input-oversized'
+/** What stdin carried is not a token: empty, or a byte outside visible ASCII, a space included. */
+ | 'token-input-invalid';
+export declare class BootstrapTokenInputError extends Error {
+    readonly refusal: TBootstrapTokenInputRefusal;
+    constructor(refusal: TBootstrapTokenInputRefusal);
+}
+/** What the token is read from: the command's stdin, or a stream a test hands in. */
+export type TBootstrapTokenInput = AsyncIterable<Uint8Array> & {
+    isTTY?: boolean;
+};
+/**
+ * The dcrouter admin token piped into `gateway bootstrap`, as bytes the caller wipes.
+ *
+ * stdin is the only source: an argument would sit in the process list and the shell history, and
+ * the environment leaks into child processes. One trailing line break, `\n` or `\r\n`, is what
+ * `echo` or a file adds and is not part of the token; everything else must pass the contract's
+ * token rule. Every byte read is wiped before this answers, whatever it answers.
+ */
+export declare const readBootstrapTokenInput: (inputArg: TBootstrapTokenInput) => Promise<Uint8Array>;

package/dist_ts_cliclient/tokeninput.js

@@ -0,0 +1,51 @@
+import * as plugins from './plugins.js';
+export class BootstrapTokenInputError extends Error {
+    constructor(refusal) {
+        super(`The dcrouter admin token on stdin was refused: ${refusal}.`);
+        this.refusal = refusal;
+        this.name = 'BootstrapTokenInputError';
+    }
+}
+function refuseUnless(conditionArg, refusalArg) {
+    if (!conditionArg)
+        throw new BootstrapTokenInputError(refusalArg);
+}
+/**
+ * The dcrouter admin token piped into `gateway bootstrap`, as bytes the caller wipes.
+ *
+ * stdin is the only source: an argument would sit in the process list and the shell history, and
+ * the environment leaks into child processes. One trailing line break, `\n` or `\r\n`, is what
+ * `echo` or a file adds and is not part of the token; everything else must pass the contract's
+ * token rule. Every byte read is wiped before this answers, whatever it answers.
+ */
+export const readBootstrapTokenInput = async (inputArg) => {
+    refuseUnless(inputArg.isTTY !== true, 'token-input-terminal');
+    const maximumBytes = plugins.servezoneInterfaces.data.externalGatewayBootstrapContract.maximumTokenBytes + 2;
+    const chunks = [];
+    let input;
+    try {
+        let byteLength = 0;
+        for await (const chunk of inputArg) {
+            chunks.push(chunk);
+            byteLength += chunk.byteLength;
+            refuseUnless(byteLength <= maximumBytes, 'token-input-oversized');
+        }
+        input = Buffer.concat(chunks, byteLength);
+        let end = input.byteLength;
+        if (end > 0 && input[end - 1] === 0x0a) {
+            end -= 1;
+            if (end > 0 && input[end - 1] === 0x0d)
+                end -= 1;
+        }
+        const token = input.subarray(0, end);
+        refuseUnless(plugins.servezoneInterfaces.data.isExternalGatewayBootstrapToken(token), 'token-input-invalid');
+        // A copy, because the input and every view of it are wiped below.
+        return new Uint8Array(token);
+    }
+    finally {
+        input?.fill(0);
+        for (const chunk of chunks)
+            chunk.fill(0);
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidG9rZW5pbnB1dC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2NsaWNsaWVudC90b2tlbmlucHV0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBV3hDLE1BQU0sT0FBTyx3QkFBeUIsU0FBUSxLQUFLO0lBQ2pELFlBQTRCLE9BQW9DO1FBQzlELEtBQUssQ0FBQyxrREFBa0QsT0FBTyxHQUFHLENBQUMsQ0FBQztRQUQxQyxZQUFPLEdBQVAsT0FBTyxDQUE2QjtRQUU5RCxJQUFJLENBQUMsSUFBSSxHQUFHLDBCQUEwQixDQUFDO0lBQ3pDLENBQUM7Q0FDRjtBQUVELFNBQVMsWUFBWSxDQUFDLFlBQXFCLEVBQUUsVUFBdUM7SUFDbEYsSUFBSSxDQUFDLFlBQVk7UUFBRSxNQUFNLElBQUksd0JBQXdCLENBQUMsVUFBVSxDQUFDLENBQUM7QUFDcEUsQ0FBQztBQUtEOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLENBQUMsTUFBTSx1QkFBdUIsR0FBRyxLQUFLLEVBQUUsUUFBOEIsRUFBdUIsRUFBRTtJQUNuRyxZQUFZLENBQUMsUUFBUSxDQUFDLEtBQUssS0FBSyxJQUFJLEVBQUUsc0JBQXNCLENBQUMsQ0FBQztJQUM5RCxNQUFNLFlBQVksR0FBRyxPQUFPLENBQUMsbUJBQW1CLENBQUMsSUFBSSxDQUFDLGdDQUFnQyxDQUFDLGlCQUFpQixHQUFHLENBQUMsQ0FBQztJQUM3RyxNQUFNLE1BQU0sR0FBaUIsRUFBRSxDQUFDO0lBQ2hDLElBQUksS0FBNkIsQ0FBQztJQUNsQyxJQUFJLENBQUM7UUFDSCxJQUFJLFVBQVUsR0FBRyxDQUFDLENBQUM7UUFDbkIsSUFBSSxLQUFLLEVBQUUsTUFBTSxLQUFLLElBQUksUUFBUSxFQUFFLENBQUM7WUFDbkMsTUFBTSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUNuQixVQUFVLElBQUksS0FBSyxDQUFDLFVBQVUsQ0FBQztZQUMvQixZQUFZLENBQUMsVUFBVSxJQUFJLFlBQVksRUFBRSx1QkFBdUIsQ0FBQyxDQUFDO1FBQ3BFLENBQUM7UUFDRCxLQUFLLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQyxNQUFNLEVBQUUsVUFBVSxDQUFDLENBQUM7UUFDMUMsSUFBSSxHQUFHLEdBQUcsS0FBSyxDQUFDLFVBQVUsQ0FBQztRQUMzQixJQUFJLEdBQUcsR0FBRyxDQUFDLElBQUksS0FBSyxDQUFDLEdBQUcsR0FBRyxDQUFDLENBQUMsS0FBSyxJQUFJLEVBQUUsQ0FBQztZQUN2QyxHQUFHLElBQUksQ0FBQyxDQUFDO1lBQ1QsSUFBSSxHQUFHLEdBQUcsQ0FBQyxJQUFJLEtBQUssQ0FBQyxHQUFHLEdBQUcsQ0FBQyxDQUFDLEtBQUssSUFBSTtnQkFBRSxHQUFHLElBQUksQ0FBQyxDQUFDO1FBQ25ELENBQUM7UUFDRCxNQUFNLEtBQUssR0FBRyxLQUFLLENBQUMsUUFBUSxDQUFDLENBQUMsRUFBRSxHQUFHLENBQUMsQ0FBQztRQUNyQyxZQUFZLENBQUMsT0FBTyxDQUFDLG1CQUFtQixDQUFDLElBQUksQ0FBQywrQkFBK0IsQ0FBQyxLQUFLLENBQUMsRUFBRSxxQkFBcUIsQ0FBQyxDQUFDO1FBQzdHLGtFQUFrRTtRQUNsRSxPQUFPLElBQUksVUFBVSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQy9CLENBQUM7WUFBUyxDQUFDO1FBQ1QsS0FBSyxFQUFFLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQztRQUNmLEtBQUssTUFBTSxLQUFLLElBQUksTUFBTTtZQUFFLEtBQUssQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDNUMsQ0FBQztBQUNILENBQUMsQ0FBQyJ9

package/package.json

@@ -38,7 +38,7 @@
     "security"
   ],
   "name": "@serve.zone/cli",
-  "version": "33.0.0",
+  "version": "33.2.0",
   "type": "module",
   "description": "A comprehensive tool for managing containerized applications across multiple cloud providers using Docker Swarmkit, featuring web, CLI, and API interfaces.",
   "main": "./dist_ts_cliclient/index.js",
@@ -50,8 +50,8 @@
     }
   },
   "dependencies": {
-    "@serve.zone/api": "32.0.0",
-    "@serve.zone/interfaces": "32.26.0",
+    "@serve.zone/api": "32.1.0",
+    "@serve.zone/interfaces": "32.29.0",
     "@push.rocks/projectinfo": "^5.1.0",
     "@push.rocks/qenv": "^8.1.0",
     "@push.rocks/smartcli": "^4.3.0"

package/readme.md

@@ -14,7 +14,8 @@ This submodule is intentionally small in the current codebase:
 - Authenticates with either `CLOUDLY_TOKEN` or `CLOUDLY_USERNAME` plus `CLOUDLY_PASSWORD`.
 - Starts a `CloudlyApiClient` registered as `cli`.
 - Creates a `CliClient` wrapper around the API client.
-- Calls `CliClient.getClusters()` and prints the result.
+- Without arguments, calls `CliClient.getClusters()` and prints the result.
+- Runs `servezone gateway bootstrap` and `servezone gateway status` for Cloudly's dcrouter gateway enrollment.
 
 It is not currently a full command tree for services, secrets, deployments, logs, profiles, or shell completion. Those flows should be implemented against `@serve.zone/api` before documenting them as CLI commands.
 
@@ -54,6 +55,24 @@ servezone
 
 When `CLOUDLY_TOKEN` is present, the CLI exchanges it for an identity and tags the WebSocket with a JWT-only credential. Cloudly verifies the JWT and reconstructs authoritative identity fields from persisted user data. Machine JWTs never outlive their source tokens, and cluster machine users must belong to exactly one persisted cluster. When username/password are present instead, the CLI uses Cloudly's admin login flow. If no credentials are provided, it prints a warning before attempting the default cluster-list operation.
 
+## Gateway Enrollment
+
+Cloudly enrolls itself at dcrouter as one gateway client, with a dcrouter admin token an administrator hands in once. Both commands sign in exactly as the default action does and need an administrator identity.
+
+```sh
+# Mint a short-lived admin token at dcrouter first, then pipe it in:
+CLOUDLY_URL=https://cloudly.example.com \
+CLOUDLY_USERNAME=admin CLOUDLY_PASSWORD=change-me \
+servezone gateway bootstrap --gateway-url https://gateway.example.com --client-id cloudly.example.com < admin-token.txt
+
+servezone gateway status
+```
+
+- `gateway bootstrap --gateway-url <https url> --client-id <id>` names Cloudly's `dcrouterGatewayUrl` and `dcrouterGatewayClientId` as its settings state them; Cloudly refuses any other target. The admin token is read from stdin and from nowhere else: an argument, `--token`, or any other extra argument is refused as usage without echoing it, and the environment is never read for it. stdin must not be a terminal. One trailing line break (`\n` or `\r\n`) is stripped; what remains must be 1 to 1024 bytes of visible ASCII. The token is checked before anything connects, sealed by `@serve.zone/api` for Cloudly, and wiped afterwards. The command prints the resulting enrollment state as JSON and exits 0; a refusal (`External gateway bootstrap refused: <refusal>.`) or a refused stdin is printed to stderr with exit code 1.
+- `gateway status` prints the current enrollment state as JSON.
+
+Revoke the admin token at dcrouter once `gateway status` reads `ready`.
+
 ## Programmatic Use
 
 The published submodule exports the `runCli()` entry point. For automation, most callers should use `@serve.zone/api` directly; the internal `CliClient` currently wraps `CloudlyApiClient` only to run the default cluster-list action:
@@ -79,7 +98,9 @@ await cli.getClusters();
 | Path | Purpose |
 | --- | --- |
 | `index.ts` | Runtime entry point for the published CLI. |
-| `classes.cliclient.ts` | Minimal client wrapper; currently exposes `getClusters()`. |
+| `classes.cliclient.ts` | Minimal client wrapper: `getClusters()`, `bootstrapGateway()` and `getGatewayStatus()`. |
+| `commands.ts` | Parses the argument vector into one command, refusing anything else as usage. |
+| `tokeninput.ts` | Reads the dcrouter admin token from stdin. |
 | `plugins.ts` | Centralized imports for the submodule. |
 | `tspublish.json` | Published package name, dependencies, `servezone` bin metadata, and `useBase`, which takes the registries from the release's npm target. |
 

package/ts_cliclient/classes.cliclient.ts

@@ -12,4 +12,24 @@ export class CliClient {
     const clusters = await this.cloudlyApiClient.cluster.getClusters();
     console.log(clusters);
   }
-}
+
+  /**
+   * Hands Cloudly the dcrouter admin token and prints the enrollment that results. The token is
+   * the caller's to wipe; the API client seals its own copy and never logs or keeps it.
+   */
+  public async bootstrapGateway(
+    targetArg: plugins.servezoneApi.IExternalGatewayBootstrapTarget,
+    bootstrapTokenArg: Uint8Array,
+  ) {
+    const { state } = await this.cloudlyApiClient.settings.bootstrapExternalGatewayCredential({
+      target: targetArg,
+      bootstrapToken: bootstrapTokenArg,
+    });
+    console.log(JSON.stringify(state, null, 2));
+  }
+
+  public async getGatewayStatus() {
+    const { state } = await this.cloudlyApiClient.settings.getExternalGatewayEnrollmentState();
+    console.log(JSON.stringify(state, null, 2));
+  }
+}

package/ts_cliclient/commands.ts

@@ -0,0 +1,65 @@
+import type * as plugins from './plugins.js';
+
+/** What one invocation of the CLI asks for, parsed before anything is read or connected. */
+export type TCliCommand =
+  /** No arguments: the default action, listing the clusters. */
+  | { kind: 'clusters' }
+  | { kind: 'gateway-status' }
+  | { kind: 'gateway-bootstrap'; target: plugins.servezoneApi.IExternalGatewayBootstrapTarget };
+
+export const cliUsage = [
+  'Usage:',
+  '  servezone',
+  '  servezone gateway status',
+  '  servezone gateway bootstrap --gateway-url <https url> --client-id <id>',
+  '    The dcrouter admin token is read from stdin, never from arguments or the environment.',
+].join('\n');
+
+/**
+ * An invocation the CLI does not run. It never quotes what it was given, because an argument may
+ * be a token pasted where it does not belong.
+ */
+export class CliUsageError extends Error {
+  constructor() {
+    super(cliUsage);
+    this.name = 'CliUsageError';
+  }
+}
+
+function requireUsage(conditionArg: unknown): asserts conditionArg {
+  if (!conditionArg) throw new CliUsageError();
+}
+
+/** Reads `--name value` pairs, each named option exactly once and nothing else. */
+const parseOptions = <TName extends string>(
+  argsArg: readonly string[],
+  namesArg: readonly TName[],
+): Record<TName, string> => {
+  const options = new Map<string, string>();
+  requireUsage(argsArg.length === namesArg.length * 2);
+  for (let index = 0; index < argsArg.length; index += 2) {
+    const name = argsArg[index];
+    const value = argsArg[index + 1];
+    requireUsage(namesArg.some((nameArg) => nameArg === name) && !options.has(name));
+    requireUsage(value.length > 0 && !value.startsWith('--'));
+    options.set(name, value);
+  }
+  return Object.fromEntries(options) as Record<TName, string>;
+};
+
+/** The command an argument vector names; any other vector is refused as usage. */
+export const parseCliCommand = (argsArg: readonly string[]): TCliCommand => {
+  if (argsArg.length === 0) return { kind: 'clusters' };
+  const [group, action, ...rest] = argsArg;
+  requireUsage(group === 'gateway');
+  if (action === 'status') {
+    requireUsage(rest.length === 0);
+    return { kind: 'gateway-status' };
+  }
+  requireUsage(action === 'bootstrap');
+  const options = parseOptions(rest, ['--gateway-url', '--client-id']);
+  return {
+    kind: 'gateway-bootstrap',
+    target: { gatewayUrl: options['--gateway-url'], gatewayClientId: options['--client-id'] },
+  };
+};

package/ts_cliclient/index.ts

@@ -1,7 +1,63 @@
 import * as plugins from './plugins.js';
 import { CliClient } from './classes.cliclient.js';
+import { parseCliCommand, type TCliCommand } from './commands.js';
+import { readBootstrapTokenInput } from './tokeninput.js';
+
+export { CliUsageError, parseCliCommand, type TCliCommand } from './commands.js';
+export {
+  BootstrapTokenInputError,
+  readBootstrapTokenInput,
+  type TBootstrapTokenInputRefusal,
+} from './tokeninput.js';
+
+/** A parsed command with everything it reads locally; a bootstrap carries the token from stdin. */
+type TCliInvocation =
+  | Exclude<TCliCommand, { kind: 'gateway-bootstrap' }>
+  | (Extract<TCliCommand, { kind: 'gateway-bootstrap' }> & { bootstrapToken: Uint8Array });
 
 export const runCli = async () => {
+  // The command and the token are settled before anything connects, so a wrong invocation or a
+  // token that could never be one fails without reaching Cloudly.
+  let command: TCliInvocation;
+  try {
+    const parsed = parseCliCommand(process.argv.slice(2));
+    command = parsed.kind === 'gateway-bootstrap'
+      ? { ...parsed, bootstrapToken: await readBootstrapTokenInput(process.stdin) }
+      : parsed;
+  } catch (error) {
+    console.error((error as Error).message);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const apiClient = await connect();
+    const cliClient = new CliClient(apiClient);
+    if (command.kind === 'clusters') {
+      // Default action example: list clusters when invoked without subcommands
+      await cliClient.getClusters();
+      return;
+    }
+    try {
+      if (command.kind === 'gateway-bootstrap') {
+        await cliClient.bootstrapGateway(command.target, command.bootstrapToken);
+      } else {
+        await cliClient.getGatewayStatus();
+      }
+    } catch (error) {
+      // Cloudly answers a refusal by name; it never carries the token.
+      console.error((error as Error).message);
+      process.exitCode = 1;
+    } finally {
+      await apiClient.stop();
+    }
+  } finally {
+    if (command.kind === 'gateway-bootstrap') command.bootstrapToken.fill(0);
+  }
+};
+
+/** The API client, started and signed in the way every command of this CLI signs in. */
+const connect = async (): Promise<plugins.servezoneApi.CloudlyApiClient> => {
   // The directory the operator runs the CLI in is read for sources, exactly as before, but the
   // `required:` list it may find there is never enforced: that list is the Cloudly server's own
   // start-time contract, and none of a remote server's database, storage or keyring facts is this
@@ -18,15 +74,17 @@ export const runCli = async () => {
   });
   await apiClient.start();
 
-  if (token) {
-    await apiClient.getIdentityByToken(token, { tagConnection: true, statefullIdentity: true });
-  } else if (username && password) {
-    await apiClient.loginWithUsernameAndPassword(username, password);
-  } else {
-    console.log('No credentials provided. Set CLOUDLY_TOKEN or CLOUDLY_USERNAME/CLOUDLY_PASSWORD.');
+  try {
+    if (token) {
+      await apiClient.getIdentityByToken(token, { tagConnection: true, statefullIdentity: true });
+    } else if (username && password) {
+      await apiClient.loginWithUsernameAndPassword(username, password);
+    } else {
+      console.log('No credentials provided. Set CLOUDLY_TOKEN or CLOUDLY_USERNAME/CLOUDLY_PASSWORD.');
+    }
+  } catch (error) {
+    await apiClient.stop();
+    throw error;
   }
-
-  const cliClient = new CliClient(apiClient);
-  // Default action example: list clusters when invoked without subcommands
-  await cliClient.getClusters();
+  return apiClient;
 };

package/ts_cliclient/readme.md

@@ -14,7 +14,8 @@ This submodule is intentionally small in the current codebase:
 - Authenticates with either `CLOUDLY_TOKEN` or `CLOUDLY_USERNAME` plus `CLOUDLY_PASSWORD`.
 - Starts a `CloudlyApiClient` registered as `cli`.
 - Creates a `CliClient` wrapper around the API client.
-- Calls `CliClient.getClusters()` and prints the result.
+- Without arguments, calls `CliClient.getClusters()` and prints the result.
+- Runs `servezone gateway bootstrap` and `servezone gateway status` for Cloudly's dcrouter gateway enrollment.
 
 It is not currently a full command tree for services, secrets, deployments, logs, profiles, or shell completion. Those flows should be implemented against `@serve.zone/api` before documenting them as CLI commands.
 
@@ -54,6 +55,24 @@ servezone
 
 When `CLOUDLY_TOKEN` is present, the CLI exchanges it for an identity and tags the WebSocket with a JWT-only credential. Cloudly verifies the JWT and reconstructs authoritative identity fields from persisted user data. Machine JWTs never outlive their source tokens, and cluster machine users must belong to exactly one persisted cluster. When username/password are present instead, the CLI uses Cloudly's admin login flow. If no credentials are provided, it prints a warning before attempting the default cluster-list operation.
 
+## Gateway Enrollment
+
+Cloudly enrolls itself at dcrouter as one gateway client, with a dcrouter admin token an administrator hands in once. Both commands sign in exactly as the default action does and need an administrator identity.
+
+```sh
+# Mint a short-lived admin token at dcrouter first, then pipe it in:
+CLOUDLY_URL=https://cloudly.example.com \
+CLOUDLY_USERNAME=admin CLOUDLY_PASSWORD=change-me \
+servezone gateway bootstrap --gateway-url https://gateway.example.com --client-id cloudly.example.com < admin-token.txt
+
+servezone gateway status
+```
+
+- `gateway bootstrap --gateway-url <https url> --client-id <id>` names Cloudly's `dcrouterGatewayUrl` and `dcrouterGatewayClientId` as its settings state them; Cloudly refuses any other target. The admin token is read from stdin and from nowhere else: an argument, `--token`, or any other extra argument is refused as usage without echoing it, and the environment is never read for it. stdin must not be a terminal. One trailing line break (`\n` or `\r\n`) is stripped; what remains must be 1 to 1024 bytes of visible ASCII. The token is checked before anything connects, sealed by `@serve.zone/api` for Cloudly, and wiped afterwards. The command prints the resulting enrollment state as JSON and exits 0; a refusal (`External gateway bootstrap refused: <refusal>.`) or a refused stdin is printed to stderr with exit code 1.
+- `gateway status` prints the current enrollment state as JSON.
+
+Revoke the admin token at dcrouter once `gateway status` reads `ready`.
+
 ## Programmatic Use
 
 The published submodule exports the `runCli()` entry point. For automation, most callers should use `@serve.zone/api` directly; the internal `CliClient` currently wraps `CloudlyApiClient` only to run the default cluster-list action:
@@ -79,7 +98,9 @@ await cli.getClusters();
 | Path | Purpose |
 | --- | --- |
 | `index.ts` | Runtime entry point for the published CLI. |
-| `classes.cliclient.ts` | Minimal client wrapper; currently exposes `getClusters()`. |
+| `classes.cliclient.ts` | Minimal client wrapper: `getClusters()`, `bootstrapGateway()` and `getGatewayStatus()`. |
+| `commands.ts` | Parses the argument vector into one command, refusing anything else as usage. |
+| `tokeninput.ts` | Reads the dcrouter admin token from stdin. |
 | `plugins.ts` | Centralized imports for the submodule. |
 | `tspublish.json` | Published package name, dependencies, `servezone` bin metadata, and `useBase`, which takes the registries from the release's npm target. |
 

package/ts_cliclient/tokeninput.ts

@@ -0,0 +1,60 @@
+import * as plugins from './plugins.js';
+
+/** Why the admin token piped in was not taken, named without quoting any of it. */
+export type TBootstrapTokenInputRefusal =
+  /** stdin is a terminal, which would echo a token typed into it; pipe the token in instead. */
+  | 'token-input-terminal'
+  /** stdin carried more bytes than a token and one line break. */
+  | 'token-input-oversized'
+  /** What stdin carried is not a token: empty, or a byte outside visible ASCII, a space included. */
+  | 'token-input-invalid';
+
+export class BootstrapTokenInputError extends Error {
+  constructor(public readonly refusal: TBootstrapTokenInputRefusal) {
+    super(`The dcrouter admin token on stdin was refused: ${refusal}.`);
+    this.name = 'BootstrapTokenInputError';
+  }
+}
+
+function refuseUnless(conditionArg: unknown, refusalArg: TBootstrapTokenInputRefusal): asserts conditionArg {
+  if (!conditionArg) throw new BootstrapTokenInputError(refusalArg);
+}
+
+/** What the token is read from: the command's stdin, or a stream a test hands in. */
+export type TBootstrapTokenInput = AsyncIterable<Uint8Array> & { isTTY?: boolean };
+
+/**
+ * The dcrouter admin token piped into `gateway bootstrap`, as bytes the caller wipes.
+ *
+ * stdin is the only source: an argument would sit in the process list and the shell history, and
+ * the environment leaks into child processes. One trailing line break, `\n` or `\r\n`, is what
+ * `echo` or a file adds and is not part of the token; everything else must pass the contract's
+ * token rule. Every byte read is wiped before this answers, whatever it answers.
+ */
+export const readBootstrapTokenInput = async (inputArg: TBootstrapTokenInput): Promise<Uint8Array> => {
+  refuseUnless(inputArg.isTTY !== true, 'token-input-terminal');
+  const maximumBytes = plugins.servezoneInterfaces.data.externalGatewayBootstrapContract.maximumTokenBytes + 2;
+  const chunks: Uint8Array[] = [];
+  let input: Uint8Array | undefined;
+  try {
+    let byteLength = 0;
+    for await (const chunk of inputArg) {
+      chunks.push(chunk);
+      byteLength += chunk.byteLength;
+      refuseUnless(byteLength <= maximumBytes, 'token-input-oversized');
+    }
+    input = Buffer.concat(chunks, byteLength);
+    let end = input.byteLength;
+    if (end > 0 && input[end - 1] === 0x0a) {
+      end -= 1;
+      if (end > 0 && input[end - 1] === 0x0d) end -= 1;
+    }
+    const token = input.subarray(0, end);
+    refuseUnless(plugins.servezoneInterfaces.data.isExternalGatewayBootstrapToken(token), 'token-input-invalid');
+    // A copy, because the input and every view of it are wiped below.
+    return new Uint8Array(token);
+  } finally {
+    input?.fill(0);
+    for (const chunk of chunks) chunk.fill(0);
+  }
+};