@serve.zone/cli 33.9.0 → 33.11.0

package/ts_cliclient/relayauthorization.ts

@@ -0,0 +1,125 @@
+import * as plugins from './plugins.js';
+
+/** Why the relay bearer was not written, named without quoting the bearer. */
+export type TRelayAuthorizationOutputRefusal =
+  /** The output's directory does not exist, or a component of its path is not a directory. */
+  | 'output-directory-missing'
+  /**
+   * The output's directory is not a private directory of the caller: it is reached through a
+   * symbolic link, owned by another user, or writable by its group or by other users.
+   */
+  | 'output-directory-not-private'
+  /** Something already exists at the output path; it is left untouched. */
+  | 'output-exists';
+
+export class RelayAuthorizationOutputError extends Error {
+  constructor(public readonly refusal: TRelayAuthorizationOutputRefusal) {
+    super(`The relay bearer was not written: ${refusal}.`);
+    this.name = 'RelayAuthorizationOutputError';
+  }
+}
+
+/** What the CLI prints about the file it wrote: metadata only, never a byte of the bearer. */
+export interface IRelayAuthorizationOutput {
+  clusterId: string;
+  generation: number;
+  outputPath: string;
+  byteLength: number;
+  /** Hex SHA-256 of the file's bytes, as `sha256sum` prints it for the same file. */
+  sha256: string;
+  /** The audit receipt Cloudly recorded for this export. */
+  receiptId: string;
+}
+
+const errorCodeOf = (errorArg: unknown): string | undefined =>
+  errorArg instanceof Error && 'code' in errorArg && typeof errorArg.code === 'string'
+    ? errorArg.code : undefined;
+
+/** A directory that is not there, or not reachable as one, is the operator's to create. */
+const refuseMissingDirectory = (errorArg: unknown): never => {
+  const code = errorCodeOf(errorArg);
+  if (code === 'ENOENT' || code === 'ENOTDIR') {
+    throw new RelayAuthorizationOutputError('output-directory-missing');
+  }
+  throw errorArg;
+};
+
+/**
+ * Refuses an output whose directory is not a private directory of the caller, or that exists.
+ *
+ * Exclusive creation guards only the file's own name, so the directory is checked here: its path
+ * resolves to itself (no symbolic link anywhere on it), it is a directory owned by the caller,
+ * and neither its group nor other users can write it. Checked before Cloudly is asked, so a bad
+ * output fetches no bearer and writes no audit receipt.
+ */
+export const requirePrivateOutputDirectory = async (outputPathArg: string): Promise<void> => {
+  const directory = plugins.path.dirname(outputPathArg);
+  const stats = await plugins.fs.lstat(directory).catch(refuseMissingDirectory);
+  const resolved = await plugins.fs.realpath(directory).catch(refuseMissingDirectory);
+  // A symbolic link anywhere on the path is a directory someone else could redirect.
+  if (resolved !== directory) throw new RelayAuthorizationOutputError('output-directory-not-private');
+  if (!stats.isDirectory()) throw new RelayAuthorizationOutputError('output-directory-missing');
+  if (stats.uid !== process.getuid?.() || (stats.mode & 0o022) !== 0) {
+    throw new RelayAuthorizationOutputError('output-directory-not-private');
+  }
+  try {
+    await plugins.fs.lstat(outputPathArg);
+  } catch (error) {
+    if (errorCodeOf(error) === 'ENOENT') return;
+    throw error;
+  }
+  throw new RelayAuthorizationOutputError('output-exists');
+};
+
+/**
+ * Writes the bearer as a new file, mode 0600 whatever the umask, whole or not at all.
+ *
+ * The write is exclusive and atomic: an existing entry at the path is never replaced or
+ * followed, and the bytes go to a private temporary file that is linked into place.
+ */
+export const writeRelayAuthorization = async (
+  outputPathArg: string,
+  bearerArg: Uint8Array,
+): Promise<void> => {
+  await requirePrivateOutputDirectory(outputPathArg);
+  const smartFs = new plugins.smartfs.SmartFs(new plugins.smartfs.SmartFsProviderNode());
+  const bytes = Buffer.from(bearerArg);
+  try {
+    await smartFs.file(outputPathArg).mode(0o600).exclusive().atomic().write(bytes);
+  } catch (error) {
+    if (error instanceof plugins.smartfs.SmartFsExclusiveWriteError) {
+      throw new RelayAuthorizationOutputError(
+        error.code === 'EEXIST' ? 'output-exists' : 'output-directory-missing');
+    }
+    throw error;
+  } finally {
+    bytes.fill(0);
+  }
+};
+
+/**
+ * Fetches one cluster relay's bearer through the API client and writes it to the operator's
+ * file, answering only what describes the file.
+ */
+export const exportRelayAuthorizationToFile = async (
+  apiClientArg: plugins.servezoneApi.CloudlyApiClient,
+  requestArg: plugins.servezoneInterfaces.data.IClusterRelayAuthorizationExportRequest,
+  outputPathArg: string,
+): Promise<IRelayAuthorizationOutput> => {
+  await requirePrivateOutputDirectory(outputPathArg);
+  const exported = await apiClientArg.cluster.exportClusterRelayAuthorization(requestArg);
+  const bearer = new TextEncoder().encode(exported.authorization);
+  try {
+    await writeRelayAuthorization(outputPathArg, bearer);
+    return {
+      clusterId: exported.credential.clusterId,
+      generation: exported.credential.generation,
+      outputPath: outputPathArg,
+      byteLength: bearer.byteLength,
+      sha256: plugins.crypto.createHash('sha256').update(bearer).digest('hex'),
+      receiptId: exported.receipt.id,
+    };
+  } finally {
+    bearer.fill(0);
+  }
+};

package/ts_cliclient/tokeninput.ts

@@ -1,39 +1,64 @@
 import * as plugins from './plugins.js';
 
-/** Why the admin token piped in was not taken, named without quoting any of it. */
-export type TBootstrapTokenInputRefusal =
+/** Why a token piped in was not taken, named without quoting any of it. */
+export type TTokenInputRefusal =
   /** 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. */
+  /** What stdin carried is not a token by the token's own rule: empty, or a byte the rule refuses. */
   | 'token-input-invalid';
 
-export class BootstrapTokenInputError extends Error {
-  constructor(public readonly refusal: TBootstrapTokenInputRefusal) {
-    super(`The dcrouter admin token on stdin was refused: ${refusal}.`);
+/** Why the dcrouter admin token piped into `gateway bootstrap` was not taken. */
+export type TBootstrapTokenInputRefusal = TTokenInputRefusal;
+
+/** A refused token input: which token, and why, never a byte of what was read. */
+export class TokenInputError extends Error {
+  constructor(public readonly refusal: TTokenInputRefusal, subjectArg: string) {
+    super(`${subjectArg} on stdin was refused: ${refusal}.`);
+    this.name = 'TokenInputError';
+  }
+}
+
+export class BootstrapTokenInputError extends TokenInputError {
+  constructor(refusalArg: TTokenInputRefusal) {
+    super(refusalArg, 'The dcrouter admin token');
     this.name = 'BootstrapTokenInputError';
   }
 }
 
-function refuseUnless(conditionArg: unknown, refusalArg: TBootstrapTokenInputRefusal): asserts conditionArg {
-  if (!conditionArg) throw new BootstrapTokenInputError(refusalArg);
+export class CorestoreControlTokenInputError extends TokenInputError {
+  constructor(refusalArg: TTokenInputRefusal) {
+    super(refusalArg, 'The Corestore control token');
+    this.name = 'CorestoreControlTokenInputError';
+  }
 }
 
-/** What the token is read from: the command's stdin, or a stream a test hands in. */
-export type TBootstrapTokenInput = AsyncIterable<Uint8Array> & { isTTY?: boolean };
+/** What a token is read from: the command's stdin, or a stream a test hands in. */
+export type TTokenInput = AsyncIterable<Uint8Array> & { isTTY?: boolean };
+export type TBootstrapTokenInput = TTokenInput;
+
+/** One token's rule: its contract's bound and check, and the error its refusals are named with. */
+interface ITokenInputRule {
+  /** The most bytes the token itself may have; one line break more is read and stripped. */
+  maximumTokenBytes: number;
+  /** The contract's check of the token's bytes, line break stripped. */
+  isToken: (tokenArg: Uint8Array) => boolean;
+  refuse: (refusalArg: TTokenInputRefusal) => TokenInputError;
+}
 
 /**
- * The dcrouter admin token piped into `gateway bootstrap`, as bytes the caller wipes.
+ * A token piped into a command, 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.
+ * `echo` or a file adds and is not part of the token; everything else must pass the token's rule.
+ * Reading stops as soon as stdin carries more than the rule's bound and one line break. 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 readTokenInput = async (inputArg: TTokenInput, ruleArg: ITokenInputRule): Promise<Uint8Array> => {
+  if (inputArg.isTTY === true) throw ruleArg.refuse('token-input-terminal');
+  const maximumBytes = ruleArg.maximumTokenBytes + 2;
   const chunks: Uint8Array[] = [];
   let input: Uint8Array | undefined;
   try {
@@ -41,7 +66,7 @@ export const readBootstrapTokenInput = async (inputArg: TBootstrapTokenInput): P
     for await (const chunk of inputArg) {
       chunks.push(chunk);
       byteLength += chunk.byteLength;
-      refuseUnless(byteLength <= maximumBytes, 'token-input-oversized');
+      if (byteLength > maximumBytes) throw ruleArg.refuse('token-input-oversized');
     }
     input = Buffer.concat(chunks, byteLength);
     let end = input.byteLength;
@@ -50,7 +75,7 @@ export const readBootstrapTokenInput = async (inputArg: TBootstrapTokenInput): P
       if (end > 0 && input[end - 1] === 0x0d) end -= 1;
     }
     const token = input.subarray(0, end);
-    refuseUnless(plugins.servezoneInterfaces.data.isExternalGatewayBootstrapToken(token), 'token-input-invalid');
+    if (!ruleArg.isToken(token)) throw ruleArg.refuse('token-input-invalid');
     // A copy, because the input and every view of it are wiped below.
     return new Uint8Array(token);
   } finally {
@@ -58,3 +83,41 @@ export const readBootstrapTokenInput = async (inputArg: TBootstrapTokenInput): P
     for (const chunk of chunks) chunk.fill(0);
   }
 };
+
+/**
+ * The dcrouter admin token piped into `gateway bootstrap`: at most the bootstrap contract's
+ * `maximumTokenBytes` of visible ASCII.
+ */
+export const readBootstrapTokenInput = async (inputArg: TTokenInput): Promise<Uint8Array> =>
+  await readTokenInput(inputArg, {
+    maximumTokenBytes: plugins.servezoneInterfaces.data.externalGatewayBootstrapContract.maximumTokenBytes,
+    isToken: (tokenArg) => plugins.servezoneInterfaces.data.isExternalGatewayBootstrapToken(tokenArg),
+    refuse: (refusalArg) => new BootstrapTokenInputError(refusalArg),
+  });
+
+/**
+ * The token as text, exactly as its bytes say: invalid UTF-8 throws, and a leading byte order mark
+ * is kept, so the contract judges and Cloudly receives every character that was piped in.
+ */
+export const decodeCorestoreControlToken = (tokenArg: Uint8Array): string =>
+  new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(tokenArg);
+
+/**
+ * The Corestore control token piped into `corestore set-control-token`: what the contract's
+ * `isCorestoreControlToken` accepts, so at most `corestoreCredentialRuntimeLimits
+ * .maximumControlTokenBytes` of UTF-8 without whitespace.
+ */
+export const readCorestoreControlTokenInput = async (inputArg: TTokenInput): Promise<Uint8Array> =>
+  await readTokenInput(inputArg, {
+    maximumTokenBytes: plugins.servezoneInterfacesRuntime.corestoreCredentialRuntimeLimits.maximumControlTokenBytes,
+    isToken: (tokenArg) => {
+      let token: string;
+      try {
+        token = decodeCorestoreControlToken(tokenArg);
+      } catch {
+        return false;
+      }
+      return plugins.servezoneInterfacesRuntime.isCorestoreControlToken(token);
+    },
+    refuse: (refusalArg) => new CorestoreControlTokenInputError(refusalArg),
+  });