@takodotid/circuit 0.34.3 → 0.36.0

package/src/core/schema-docs.ts

@@ -1,166 +1,174 @@
 // The schema's own comments, read as data: each type, what it is, and each field with its type and description. The schema reference page and Studio both show them.
 
-/** The schema files in reading order, with the title each gets. */
-export const SCHEMA_FILES = [
-    ["device.ts", "Device"],
-    ["interfaces.ts", "Ports and interfaces"],
-    ["routing.ts", "Routing"],
-    ["policy.ts", "Route policies"],
-    ["firewall.ts", "Firewall and ACLs"],
-    ["system.ts", "System and management"],
-    ["common.ts", "Common values"],
-] as const;
-
 export type Field = { path: string; type: string; description: string };
 export type TypeDoc = { name: string; description: string; definition?: string; includes?: string[]; fields: Field[] };
 
-/** The text of a JSDoc comment, without its markers, as one paragraph. */
-function commentText(lines: string[]): string {
-    return lines
-        .map((line) => line.replace(/^\s*\/\*\*\s?|\s*\*\/\s*$|^\s*\*\s?/g, "").trim())
-        .filter(Boolean)
-        .join(" ");
-}
-
-/** What a type parameter stands for, where it is not one of the device's names. */
-const PARAMETER_MEANING: Record<string, string> = { Pl: "platform", M: "model" };
-
-/** A type as a reader needs it: "name" for each of the device's names, and no parameter list on the schema's own types. */
-function withoutGenerics(type: string, generics: Set<string>): string {
-    let result = type;
-    while (/NoInfer<([^<>]*)>/.test(result)) {
-        result = result.replace(/NoInfer<([^<>]*)>/g, (_, inner: string) => (inner.includes("|") ? `(${inner})` : inner));
+export class SchemaDocs {
+    /** The schema files in reading order, with the title each gets. */
+    static readonly FILES = [
+        ["device.ts", "Device"],
+        ["interfaces.ts", "Ports and interfaces"],
+        ["routing.ts", "Routing"],
+        ["policy.ts", "Route policies"],
+        ["firewall.ts", "Firewall and ACLs"],
+        ["system.ts", "System and management"],
+        ["common.ts", "Common values"],
+    ] as const;
+
+    /** The text of a JSDoc comment, without its markers, as one paragraph. */
+    private static commentText(lines: string[]): string {
+        return lines
+            .map((line) => line.replace(/^\s*\/\*\*\s?|\s*\*\/\s*$|^\s*\*\s?/g, "").trim())
+            .filter(Boolean)
+            .join(" ");
     }
 
-    for (const name of generics) {
-        result = result.replace(new RegExp(`\\b${name}<[^<>]*(?:<[^<>]*>[^<>]*)*>`, "g"), name);
-    }
+    /** What a type parameter stands for, where it is not one of the device's names. */
+    private static readonly PARAMETER_MEANING: Record<string, string> = { Pl: "platform", M: "model" };
 
-    return result
-        .replace(/\b(Pl|M|N|V|I|P|S|G|A|AS|U|F|C|L|K)\b/g, (parameter) => PARAMETER_MEANING[parameter] ?? "name")
-        .replace(/\bname(?: \| name)+\b/g, "name")
-        .replace(/\(name\)/g, "name");
-}
+    /** A type as a reader needs it: "name" for each of the device's names, and no parameter list on the schema's own types. */
+    private static withoutGenerics(type: string, generics: Set<string>): string {
+        let result = type;
+        while (/NoInfer<([^<>]*)>/.test(result)) {
+            result = result.replace(/NoInfer<([^<>]*)>/g, (_, inner: string) => (inner.includes("|") ? `(${inner})` : inner));
+        }
 
-function parse(source: string, generics: Set<string>): TypeDoc[] {
-    const lines = source.split("\n");
-    const types: TypeDoc[] = [];
-
-    let comment: string[] = [];
-    let inComment = false;
-    let current: TypeDoc | undefined;
-    let depth = 0;
-    const parents: string[] = [];
-    let header: string | undefined;
-
-    /** Reads a whole declaration: a type it aliases, the types whose fields it also has, and whether a body opens. */
-    function finishHeader(): void {
-        const text = header!;
-        header = undefined;
-
-        // The part after `=`, with the generic parameter list before it left out.
-        const body = text.slice(text.indexOf("> =") >= 0 ? text.indexOf("> =") + 3 : text.indexOf("=") + 1).trim();
-
-        if (!body.includes("{")) {
-            current!.definition = body.replace(/;$/, "").replace(/^\|\s*/, "");
-        } else {
-            const before = body.slice(0, body.indexOf("{"));
-            const included = before
-                .split("&")
-                .map((part) => part.trim())
-                .filter((part) => /^\w/.test(part));
-            if (included.length) current!.includes = included;
+        for (const name of generics) {
+            result = result.replace(new RegExp(`\\b${name}<[^<>]*(?:<[^<>]*>[^<>]*)*>`, "g"), name);
         }
 
-        depth = (text.match(/{/g) ?? []).length - (text.match(/}/g) ?? []).length;
+        return (
+            result
+                // A quoted value, such as the "M" of a rate, is left as it is.
+                .replace(/"[^"]*"|\b(Pl|M|N|V|I|P|S|G|A|AS|U|F|C|L|K)\b/g, (found, parameter?: string) =>
+                    parameter ? (SchemaDocs.PARAMETER_MEANING[parameter] ?? "name") : found
+                )
+                .replace(/\bname(?: \| name)+\b/g, "name")
+                .replace(/\(name\)/g, "name")
+        );
     }
 
-    for (const line of lines) {
-        const trimmed = line.trim();
+    private static parse(source: string, generics: Set<string>): TypeDoc[] {
+        const lines = source.split("\n");
+        const types: TypeDoc[] = [];
+
+        let comment: string[] = [];
+        let inComment = false;
+        let current: TypeDoc | undefined;
+        let depth = 0;
+        const parents: string[] = [];
+        let header: string | undefined;
+
+        /** Reads a whole declaration: a type it aliases, the types whose fields it also has, and whether a body opens. */
+        function finishHeader(): void {
+            const text = header!;
+            header = undefined;
+
+            // The part after `=`, with the generic parameter list before it left out.
+            const body = text.slice(text.indexOf("> =") >= 0 ? text.indexOf("> =") + 3 : text.indexOf("=") + 1).trim();
+
+            // A template literal type, such as `${number}:${number}`, holds braces but opens no body.
+            if (!body.includes("{") || body.startsWith("`")) {
+                current!.definition = body.replace(/;$/, "").replace(/^\|\s*/, "");
+            } else {
+                const before = body.slice(0, body.indexOf("{"));
+                const included = before
+                    .split("&")
+                    .map((part) => part.trim())
+                    .filter((part) => /^\w/.test(part));
+                if (included.length) current!.includes = included;
+            }
 
-        if (trimmed.startsWith("/**")) {
-            comment = [trimmed];
-            inComment = !trimmed.endsWith("*/");
-            continue;
+            depth = (text.match(/{/g) ?? []).length - (text.match(/}/g) ?? []).length;
         }
 
-        if (inComment) {
-            comment.push(trimmed);
-            if (trimmed.endsWith("*/")) inComment = false;
-            continue;
-        }
+        for (const line of lines) {
+            const trimmed = line.trim();
 
-        // A declaration can span lines before its body opens or it ends.
-        if (header !== undefined) {
-            header += ` ${trimmed}`;
-            if (trimmed.endsWith("{") || trimmed.endsWith(";")) finishHeader();
-            continue;
-        }
+            if (trimmed.startsWith("/**")) {
+                comment = [trimmed];
+                inComment = !trimmed.endsWith("*/");
+                continue;
+            }
 
-        // A type the schema does not export is documented too, since exported types take its fields.
-        const declaration = /^(?:export )?type (\w+)(<)?/.exec(trimmed);
-        if (declaration && depth === 0) {
-            if (declaration[2]) generics.add(declaration[1]!);
+            if (inComment) {
+                comment.push(trimmed);
+                if (trimmed.endsWith("*/")) inComment = false;
+                continue;
+            }
 
-            current = { name: declaration[1]!, description: commentText(comment), fields: [] };
-            types.push(current);
-            comment = [];
+            // A declaration can span lines before its body opens or it ends.
+            if (header !== undefined) {
+                header += ` ${trimmed}`;
+                if (trimmed.endsWith("{") || trimmed.endsWith(";")) finishHeader();
+                continue;
+            }
 
-            header = trimmed;
-            if (trimmed.endsWith("{") || trimmed.endsWith(";")) finishHeader();
-            continue;
-        }
+            // A type the schema does not export is documented too, since exported types take its fields.
+            const declaration = /^(?:export )?type (\w+)(<)?/.exec(trimmed);
+            if (declaration && depth === 0) {
+                if (declaration[2]) generics.add(declaration[1]!);
 
-        if (!current) continue;
+                current = { name: declaration[1]!, description: SchemaDocs.commentText(comment), fields: [] };
+                types.push(current);
+                comment = [];
 
-        const field = /^(?:readonly\s+)?("?[\w-]+"?)(\?)?:\s*(.*)$/.exec(trimmed);
-        if (field && depth >= 1) {
-            const [, name, optional, rest] = field;
-            const path = [...parents, name!.replace(/"/g, "")].join(".");
-            const opensObject = rest!.trim().endsWith("{");
-            const type = opensObject ? "object" : rest!.replace(/;$/, "").trim();
+                header = trimmed;
+                if (trimmed.endsWith("{") || trimmed.endsWith(";")) finishHeader();
+                continue;
+            }
 
-            current.fields.push({ path: `${path}${optional ? "?" : ""}`, type, description: commentText(comment) });
-            comment = [];
+            if (!current) continue;
+
+            const field = /^(?:readonly\s+)?("?[\w-]+"?)(\?)?:\s*(.*)$/.exec(trimmed);
+            if (field && depth >= 1) {
+                const [, name, optional, rest] = field;
+                const path = [...parents, name!.replace(/"/g, "")].join(".");
+                const opensObject = rest!.trim().endsWith("{");
+                const type = opensObject ? "object" : rest!.replace(/;$/, "").trim();
+
+                current.fields.push({ path: `${path}${optional ? "?" : ""}`, type, description: SchemaDocs.commentText(comment) });
+                comment = [];
 
-            if (opensObject) {
-                parents.push(name!.replace(/"/g, ""));
-                depth++;
+                if (opensObject) {
+                    parents.push(name!.replace(/"/g, ""));
+                    depth++;
+                }
+                continue;
             }
-            continue;
-        }
 
-        const opens = (trimmed.match(/{/g) ?? []).length;
-        const closes = (trimmed.match(/}/g) ?? []).length;
+            const opens = (trimmed.match(/{/g) ?? []).length;
+            const closes = (trimmed.match(/}/g) ?? []).length;
 
-        for (let index = 0; index < closes - opens; index++) {
-            if (parents.length >= depth - 1 && parents.length > 0) parents.pop();
-        }
+            for (let index = 0; index < closes - opens; index++) {
+                if (parents.length >= depth - 1 && parents.length > 0) parents.pop();
+            }
 
-        depth += opens - closes;
-        if (depth <= 0) {
-            depth = 0;
-            parents.length = 0;
+            depth += opens - closes;
+            if (depth <= 0) {
+                depth = 0;
+                parents.length = 0;
+            }
+
+            comment = [];
         }
 
-        comment = [];
+        return types;
     }
 
-    return types;
-}
-
-/** Every type in each schema file, in the order given. Every file is read first, so a type is known to take parameters wherever it is used. */
-export function schemaTypes(sources: readonly string[]): TypeDoc[][] {
-    const generics = new Set<string>();
-    const parsed = sources.map((source) => parse(source, generics));
+    /** Every type in each schema file, in the order given. Every file is read first, so a type is known to take parameters wherever it is used. */
+    static read(sources: readonly string[]): TypeDoc[][] {
+        const generics = new Set<string>();
+        const parsed = sources.map((source) => SchemaDocs.parse(source, generics));
 
-    for (const types of parsed) {
-        for (const type of types) {
-            if (type.definition) type.definition = withoutGenerics(type.definition, generics);
-            if (type.includes) type.includes = type.includes.map((name) => withoutGenerics(name, generics));
-            for (const field of type.fields) field.type = withoutGenerics(field.type, generics);
+        for (const types of parsed) {
+            for (const type of types) {
+                if (type.definition) type.definition = SchemaDocs.withoutGenerics(type.definition, generics);
+                if (type.includes) type.includes = type.includes.map((name) => SchemaDocs.withoutGenerics(name, generics));
+                for (const field of type.fields) field.type = SchemaDocs.withoutGenerics(field.type, generics);
+            }
         }
-    }
 
-    return parsed;
+        return parsed;
+    }
 }

package/src/core/secrets.ts

@@ -3,111 +3,205 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { Secret } from "../schema";
+import { parseEnv } from "node:util";
+import type { Network } from "./define";
+import type { Console, Device, IP, Secret } from "../schema";
+
+/** How a device is logged in to: its management address and SSH port, its connection user and that user's password, and its console. */
+export type DeviceLogin = {
+    /** Absent for a device reached only through its console. */
+    host?: IP;
+    port: number;
+    user: string;
+    /** The value, not a reference. Never print it. */
+    password: string;
+    console?: Console;
+};
+
+export class Secrets {
+    /** The directory of the config file. `.env` and secret files are found from here. */
+    private static root = process.cwd();
+
+    private static envFile: Record<string, string> | undefined;
+    private static readonly fromOnePassword = new Map<string, string>();
+    /** Every value read in this run, so `scrub` can hide it. */
+    private static readonly revealed = new Set<string>();
+
+    /** What `scrub` puts where a secret was. */
+    static readonly REDACTED = "<redacted>";
+
+    /** A value in `.env` shorter than this is not hidden: `.env` can hold settings that are not secrets, and hiding a short one would garble the text. */
+    private static readonly SHORTEST_DOTENV_VALUE = 6;
+
+    /** A marker anywhere in a command. Its group is the reference. */
+    static readonly MARKER = /<secret:([A-Za-z0-9_./:-]+)>/g;
+
+    /** Find `.env` and secret files from this directory, the config file's, instead of the working directory. */
+    static useRoot(directory: string): void {
+        Secrets.root = directory;
+        Secrets.envFile = undefined;
+    }
 
-/** The directory of the config file. `.env` and secret files are found from here. */
-let root = process.cwd();
+    /** `.env` beside the config, read once. Node and Bun read it the same way they load `.env` themselves: a `#` starts a comment unless the value is quoted. */
+    private static dotenv(): Record<string, string> {
+        if (Secrets.envFile) return Secrets.envFile;
 
-let envFile: Record<string, string> | undefined;
-const fromOnePassword = new Map<string, string>();
+        const path = join(Secrets.root, ".env");
+        const text = existsSync(path) ? readFileSync(path, "utf8") : "";
 
-/** Find `.env` and secret files from this directory, the config file's, instead of the working directory. */
-export function useRoot(directory: string): void {
-    root = directory;
-    envFile = undefined;
-}
+        Secrets.refuseCutValues(text);
+        Secrets.envFile = parseEnv(text) as Record<string, string>;
+        return Secrets.envFile;
+    }
+
+    /** An unquoted value is cut at a `#`. A `#` after a space is a comment, but one inside the value, as in `abc#def`, would cut a password short and send that to a device, so it stops the run and asks for quotes. */
+    private static refuseCutValues(text: string): void {
+        for (const line of text.split(/\r?\n/)) {
+            const [, name, value] = /^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*)$/.exec(line) ?? [];
+            if (!name || !value || /^['"`]/.test(value) || !/\S#/.test(value)) continue;
+
+            throw new Error(`.env: the value of ${name} has a # in it, which starts a comment there; put the value in quotes`);
+        }
+    }
+
+    /** Read a 1Password reference with the 1Password CLI, `op`, once per run. */
+    private static readOnePassword(name: string, reference: string): string {
+        const cached = Secrets.fromOnePassword.get(reference);
+        if (cached !== undefined) return cached;
 
-/** `.env` beside the config, read once. */
-function dotenv(): Record<string, string> {
-    if (envFile) return envFile;
+        const result = spawnSync("op", ["read", "--no-newline", reference], { encoding: "utf8" });
 
-    envFile = {};
-    const path = join(root, ".env");
-    if (!existsSync(path)) return envFile;
+        if (result.error) throw new Error(`secret ${name} is a 1Password reference, and the 1Password CLI, op, is not installed`);
 
-    for (const line of readFileSync(path, "utf8").split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#")) continue;
+        if (result.status !== 0) {
+            const reason = result.stderr.trim() || `op exited with ${result.status}`;
+            throw new Error(`secret ${name}: 1Password could not read ${reference}: ${reason}`);
+        }
 
-        const separator = trimmed.indexOf("=");
-        if (separator <= 0) continue;
+        const value = result.stdout;
+        Secrets.fromOnePassword.set(reference, value);
+        return value;
+    }
 
-        const value = trimmed.slice(separator + 1).trim();
-        const unquoted = /^(["']).*\1$/.test(value) ? value.slice(1, -1) : value;
-        envFile[trimmed.slice(0, separator).trim()] = unquoted;
+    static isSecret(value: unknown): value is Secret {
+        return typeof value === "object" && value !== null && ("secret" in value || "secret_file" in value);
     }
 
-    return envFile;
-}
+    /** How a reference is written inside a marker: a variable's name, or `file:` and a path. */
+    static referenceOf(secret: Secret): string {
+        return "secret" in secret ? secret.secret : `file:${secret.secret_file}`;
+    }
 
-/** Read a 1Password reference with the 1Password CLI, `op`, once per run. */
-function readOnePassword(name: string, reference: string): string {
-    const cached = fromOnePassword.get(reference);
-    if (cached !== undefined) return cached;
+    /** Where a reference's value comes from, such as `.env` or `1Password, through .env`, without reading it. Undefined when it is set nowhere. */
+    static sourceOf(reference: string): string | undefined {
+        if (reference.startsWith("file:")) return existsSync(join(Secrets.root, reference.slice("file:".length))) ? "a file" : undefined;
 
-    const result = spawnSync("op", ["read", "--no-newline", reference], { encoding: "utf8" });
+        const fromFile = Secrets.dotenv()[reference];
+        const value = process.env[reference] || fromFile;
+        if (!value) return undefined;
 
-    if (result.error) throw new Error(`secret ${name} is a 1Password reference, and the 1Password CLI, op, is not installed`);
+        // Bun loads `.env` into the environment when it starts in the same directory, so the same value in both came from `.env`.
+        const where = process.env[reference] && process.env[reference] !== fromFile ? "the environment" : ".env";
 
-    if (result.status !== 0) {
-        const reason = result.stderr.trim() || `op exited with ${result.status}`;
-        throw new Error(`secret ${name}: 1Password could not read ${reference}: ${reason}`);
+        return value.startsWith("op://") ? `1Password, through ${where}` : where;
     }
 
-    const value = result.stdout;
-    fromOnePassword.set(reference, value);
-    return value;
-}
+    /** The value behind a reference, as `referenceOf` writes it: one marker's reference, for a platform that takes a secret interactively. */
+    static valueOf(reference: string): string {
+        if (reference.startsWith("file:")) {
+            const path = reference.slice("file:".length);
+            const fullPath = join(Secrets.root, path);
+            if (!existsSync(fullPath)) throw new Error(`secret file ${path} does not exist`);
 
-export const isSecret = (value: unknown): value is Secret =>
-    typeof value === "object" && value !== null && ("secret" in value || "secret_file" in value);
+            const value = readFileSync(fullPath, "utf8").trimEnd();
+            if (!value) throw new Error(`secret file ${path} is empty`);
 
-/** How a reference is written inside a marker: a variable's name, or `file:` and a path. */
-export const referenceOf = (secret: Secret) => ("secret" in secret ? secret.secret : `file:${secret.secret_file}`);
+            Secrets.revealed.add(value);
+            return value;
+        }
 
-/** Where a reference's value comes from, such as `.env` or `1Password, through .env`, without reading it. Undefined when it is set nowhere. */
-export function sourceOf(reference: string): string | undefined {
-    if (reference.startsWith("file:")) return existsSync(join(root, reference.slice("file:".length))) ? "a file" : undefined;
+        // `.env` is read first even when the environment has the value, so a value cut at a `#` is caught under Bun too, which loads `.env` itself.
+        const fromFile = Secrets.dotenv()[reference];
+        const value = process.env[reference] || fromFile;
+        if (!value) throw new Error(`secret ${reference} is not set in the environment or in .env`);
 
-    const value = process.env[reference] || dotenv()[reference];
-    if (!value) return undefined;
+        const revealed = value.startsWith("op://") ? Secrets.readOnePassword(reference, value) : value;
+        Secrets.revealed.add(revealed);
+        return revealed;
+    }
 
-    // Bun loads `.env` into the environment when it starts in the same directory, so the same value in both came from `.env`.
-    const where = process.env[reference] && process.env[reference] !== dotenv()[reference] ? "the environment" : ".env";
+    /** The value of a secret, or of a variable named directly: from the environment, `.env`, 1Password or a file. */
+    static reveal(secret: Secret | string): string {
+        return Secrets.valueOf(typeof secret === "string" ? secret : Secrets.referenceOf(secret));
+    }
 
-    return value.startsWith("op://") ? `1Password, through ${where}` : where;
-}
+    /** Every secret reference in a value, however deep, such as a network or one device, as `referenceOf` writes it. */
+    static referencesIn(value: unknown, found = new Set<string>()): Set<string> {
+        if (Secrets.isSecret(value)) found.add(Secrets.referenceOf(value));
+        else if (Array.isArray(value)) for (const item of value) Secrets.referencesIn(item, found);
+        else if (typeof value === "object" && value !== null) for (const item of Object.values(value)) Secrets.referencesIn(item, found);
 
-/** The value behind a reference, as `referenceOf` writes it. */
-function valueOf(reference: string): string {
-    if (reference.startsWith("file:")) {
-        const path = reference.slice("file:".length);
-        const fullPath = join(root, path);
-        if (!existsSync(fullPath)) throw new Error(`secret file ${path} does not exist`);
+        return found;
+    }
 
-        const value = readFileSync(fullPath, "utf8").trimEnd();
-        if (!value) throw new Error(`secret file ${path} is empty`);
+    /**
+     * Text with every secret value Circuit knows replaced by `<redacted>`, before it is printed. Devices echo what they are sent, passwords too.
+     *
+     * Hidden are: each value in `.env` of at least six characters, each value read in this run (1Password reads and secret files among them), each secret of `network` that the environment, `.env` or a file holds, and `extra`. A 1Password reference not read in this run is not read for this.
+     */
+    static scrub(text: string, options: { network?: Network; extra?: readonly string[] } = {}): string {
+        const values = new Set<string>(options.extra ?? []);
 
-        return value;
-    }
+        for (const value of Object.values(Secrets.dotenv())) {
+            if (value.length >= Secrets.SHORTEST_DOTENV_VALUE && !value.startsWith("op://")) values.add(value);
+        }
 
-    const value = process.env[reference] || dotenv()[reference];
-    if (!value) throw new Error(`secret ${reference} is not set in the environment or in .env`);
+        for (const value of Secrets.revealed) values.add(value);
 
-    return value.startsWith("op://") ? readOnePassword(reference, value) : value;
-}
+        for (const reference of Secrets.referencesIn(options.network)) {
+            const value = Secrets.storedValueOf(reference);
+            if (value) values.add(value);
+        }
 
-/** The value of a secret, or of a variable named directly. */
-export const resolve = (secret: Secret | string): string => valueOf(typeof secret === "string" ? secret : referenceOf(secret));
+        // Longest first, so a value that holds another is hidden whole.
+        const ordered = [...values].filter(Boolean).sort((a, b) => b.length - a.length);
+        return ordered.reduce((out, value) => out.split(value).join(Secrets.REDACTED), text);
+    }
 
-/** How a secret appears in rendered config. Replaced with its value only when sent to a device. */
-export const marker = (secret: Secret) => `<secret:${referenceOf(secret)}>`;
+    /** The value behind a reference when it can be had without asking anyone: a 1Password reference only once read in this run. Undefined otherwise. */
+    private static storedValueOf(reference: string): string | undefined {
+        if (reference.startsWith("file:")) {
+            const path = join(Secrets.root, reference.slice("file:".length));
+            return existsSync(path) ? readFileSync(path, "utf8").trimEnd() : undefined;
+        }
 
-/** A marker anywhere in a command. Its group is the reference. */
-export const MARKER = /<secret:([A-Za-z0-9_./:-]+)>/g;
+        const value = process.env[reference] || Secrets.dotenv()[reference];
+        if (!value?.startsWith("op://")) return value;
 
-/** Replace every marker in a command with its value. */
-export const substitute = (text: string) => text.replace(MARKER, (_, reference: string) => valueOf(reference));
+        return Secrets.fromOnePassword.get(value);
+    }
 
-/** The value behind one marker's reference, for a platform that takes a secret interactively. */
-export const valueOfReference = valueOf;
+    /** How Circuit logs in to a device: its address, port, connection user, that user's password revealed, and its console. */
+    static loginOf(device: Device): DeviceLogin {
+        const user = device.users?.[device.connection.user];
+        if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
+
+        return {
+            ...(device.connection.host ? { host: device.connection.host } : {}),
+            port: device.connection.port ?? 22,
+            user: device.connection.user,
+            password: Secrets.reveal(user.password),
+            ...(device.connection.console ? { console: device.connection.console } : {}),
+        };
+    }
+
+    /** How a secret appears in rendered config. Replaced with its value only when sent to a device. */
+    static marker(secret: Secret): string {
+        return `<secret:${Secrets.referenceOf(secret)}>`;
+    }
+
+    /** Replace every marker in a command with its value. */
+    static substitute(text: string): string {
+        return text.replace(Secrets.MARKER, (_, reference: string) => Secrets.valueOf(reference));
+    }
+}