Read Setup URI generator values from LIVESYNC_ variables

hostname, username, and the other unprefixed names collide with shell
and system variables (fish makes hostname read-only, Windows already
defines USERNAME). The generator now reads LIVESYNC_HOST, LIVESYNC_USER,
LIVESYNC_PASS, LIVESYNC_DB, and LIVESYNC_PASSPHRASE first and falls back
to the old names, so existing instructions keep working.

Co-authored-by: rwbru <59871009+rwbru@users.noreply.github.com>

utils/readme.md

@@ -31,21 +31,23 @@ Authentication and other non-retryable HTTP failures stop immediately. Network a
 
 The existing `flyio/generate_setupuri.ts` path remains a CouchDB-only compatibility wrapper for the Fly.io deployment script.
 
+The connection and Vault encryption values use a `LIVESYNC_` prefix so that they do not collide with shell or system variables such as `hostname` and `USERNAME`. The unprefixed names `hostname`, `username`, `password`, `database`, and `passphrase` are still read when the prefixed ones are not set.
+
 The generator creates a fresh random ID key by default and includes it in the encrypted Setup URI. It prints a tagged `sls-id-v1:` recovery code. Set `id_recovery_code` to that code when generating another URI for the same Vault; a new run without it creates a different key. This restores only the ID key: reuse the original connection details too. For P2P, provide the original `p2p_room_id` and `p2p_passphrase` because omitted values are generated afresh. Set `id_mode=legacy` to generate a URI with the previous ID behaviour. `id_mode=legacy` and `id_recovery_code` cannot be combined. Keep the recovery code private and retain it if every device might be lost.
 
 ### CouchDB
 
 ```sh
-export hostname=https://couch.example.com
-export username=couchdb-admin-username
-export password=couchdb-admin-password
-export database=obsidiannotes
-export passphrase=a-strong-vault-encryption-passphrase
+export LIVESYNC_HOST=https://couch.example.com
+export LIVESYNC_USER=couchdb-admin-username
+export LIVESYNC_PASS=couchdb-admin-password
+export LIVESYNC_DB=obsidiannotes
+export LIVESYNC_PASSPHRASE=a-strong-vault-encryption-passphrase
 export uri_passphrase=a-separate-setup-uri-passphrase # Optional
 deno run --minimum-dependency-age=0 --config=./flyio/deno.jsonc --frozen --lock=./flyio/deno.lock --allow-env ./setup/generate_setup_uri.ts
 ```
 
-If `uri_passphrase` is omitted, the tool generates and prints a cryptographically random one. Store the Setup URI and its passphrase separately. The `passphrase` value protects synchronised Vault data and must also be stored safely.
+If `uri_passphrase` is omitted, the tool generates and prints a cryptographically random one. Store the Setup URI and its passphrase separately. The `LIVESYNC_PASSPHRASE` value protects synchronised Vault data and must also be stored safely.
 
 The generator defaults to `uri_mode=ephemeral`. The URI opens only during the current fixed seven-day UTC window, and the tool prints its exact end time. It may have less than seven days remaining when generated. For an indefinitely reusable URI, set `uri_mode=persistent` before running the command. Persistent uses the existing encrypted format, which older clients that already support that format can read. The time condition controls opening the URI; it does not revoke settings or credentials after import.
 
@@ -59,7 +61,7 @@ export secret_key=<SECRET KEY>
 export bucket=vault-data
 export region=auto
 export bucket_prefix=team-a # Optional
-export passphrase=<A STRONG VAULT ENCRYPTION PASSPHRASE>
+export LIVESYNC_PASSPHRASE=<A STRONG VAULT ENCRYPTION PASSPHRASE>
 deno run --minimum-dependency-age=0 --config=./flyio/deno.jsonc --frozen --lock=./flyio/deno.lock --allow-env ./setup/generate_setup_uri.ts
 ```
 
@@ -69,7 +71,7 @@ Optional Object Storage variables are `use_custom_request_handler`, `force_path_
 
 ```sh
 export remote_type=p2p
-export passphrase=<A STRONG VAULT ENCRYPTION PASSPHRASE>
+export LIVESYNC_PASSPHRASE=<A STRONG VAULT ENCRYPTION PASSPHRASE>
 deno run --minimum-dependency-age=0 --config=./flyio/deno.jsonc --frozen --lock=./flyio/deno.lock --allow-env ./setup/generate_setup_uri.ts
 ```
 

utils/setup/generate_setup_uri.test.ts

@@ -8,6 +8,76 @@ function assert(condition: unknown, message: string): asserts condition {
   if (!condition) throw new Error(message);
 }
 
+Deno.test("reads LIVESYNC_ variables before the unprefixed names", async () => {
+  const generated = await generateSetupURI({
+    LIVESYNC_HOST: "https://couch.example.test",
+    LIVESYNC_USER: "alice",
+    LIVESYNC_PASS: "couch-secret",
+    LIVESYNC_DB: "notes",
+    LIVESYNC_PASSPHRASE: "vault-secret",
+    hostname: "https://shell.example.test",
+    username: "shell-user",
+    password: "shell-secret",
+    database: "shell-db",
+    passphrase: "shell-passphrase",
+    uri_passphrase: "setup-secret",
+  });
+  const decoded = await decodeSettingsFromSetupURI(
+    generated.setupURI,
+    generated.setupPassphrase,
+  );
+  assert(decoded, "Commonlib could not decode the CouchDB Setup URI");
+  const effective = { ...DEFAULT_SETTINGS, ...decoded };
+  assert(
+    effective.couchDB_URI === "https://couch.example.test" &&
+      effective.couchDB_USER === "alice" &&
+      effective.couchDB_PASSWORD === "couch-secret" &&
+      effective.couchDB_DBNAME === "notes",
+    "the CouchDB connection did not come from the LIVESYNC_ variables",
+  );
+  assert(
+    effective.passphrase === "vault-secret",
+    "the Vault passphrase did not come from LIVESYNC_PASSPHRASE",
+  );
+});
+
+Deno.test("falls back to the unprefixed names when LIVESYNC_ variables are blank", async () => {
+  const generated = await generateSetupURI({
+    LIVESYNC_HOST: " ",
+    hostname: "https://couch.example.test",
+    username: "alice",
+    password: "couch-secret",
+    database: "notes",
+    passphrase: "vault-secret",
+    uri_passphrase: "setup-secret",
+  });
+  const decoded = await decodeSettingsFromSetupURI(
+    generated.setupURI,
+    generated.setupPassphrase,
+  );
+  assert(decoded, "Commonlib could not decode the CouchDB Setup URI");
+  const effective = { ...DEFAULT_SETTINGS, ...decoded };
+  assert(
+    effective.couchDB_URI === "https://couch.example.test" &&
+      effective.couchDB_USER === "alice" &&
+      effective.couchDB_PASSWORD === "couch-secret" &&
+      effective.couchDB_DBNAME === "notes" &&
+      effective.passphrase === "vault-secret",
+    "the generator did not fall back to the unprefixed names",
+  );
+});
+
+Deno.test("names both variables when a CouchDB value is missing", async () => {
+  let rejected = false;
+  try {
+    await generateSetupURI({ uri_passphrase: "setup-secret" });
+  } catch (error) {
+    rejected = error instanceof Error &&
+      error.message === "LIVESYNC_HOST (or hostname) is required";
+  }
+  assert(rejected, "the generator did not name both host variables");
+});
+
 Deno.test("generates an Object Storage Setup URI with a selected S3 profile", async () => {
   const generated = await generateSetupURI({
     remote_type: "s3",

utils/setup/generate_setup_uri.ts

@@ -64,9 +64,17 @@ function configureIdDerivation(
 function requireValue(
   environment: SetupGeneratorEnvironment,
   name: string,
+  legacyName?: string,
 ): string {
-  const value = environment[name]?.trim();
-  if (!value) throw new Error(`${name} is required`);
+  const value = environment[name]?.trim() ||
+    (legacyName && environment[legacyName]?.trim());
+  if (!value) {
+    throw new Error(
+      legacyName
+        ? `${name} (or ${legacyName}) is required`
+        : `${name} is required`,
+    );
+  }
   return value;
 }
 
@@ -97,7 +105,7 @@ function applyEncryptedVaultSettings(
   Object.assign(settings, {
     isConfigured: true,
     encrypt: true,
-    passphrase: requireValue(environment, "passphrase"),
+    passphrase: requireValue(environment, "LIVESYNC_PASSPHRASE", "passphrase"),
     usePathObfuscation: true,
   });
 }
@@ -107,10 +115,10 @@ function createCouchDBSettings(
 ): ObsidianLiveSyncSettings {
   const settings = createNewVaultSettings();
   Object.assign(settings, PREFERRED_SETTING_SELF_HOSTED, {
-    couchDB_URI: requireValue(environment, "hostname"),
-    couchDB_USER: requireValue(environment, "username"),
-    couchDB_PASSWORD: requireValue(environment, "password"),
-    couchDB_DBNAME: requireValue(environment, "database"),
+    couchDB_URI: requireValue(environment, "LIVESYNC_HOST", "hostname"),
+    couchDB_USER: requireValue(environment, "LIVESYNC_USER", "username"),
+    couchDB_PASSWORD: requireValue(environment, "LIVESYNC_PASS", "password"),
+    couchDB_DBNAME: requireValue(environment, "LIVESYNC_DB", "database"),
     batchSave: true,
     periodicReplication: true,
     syncOnStart: true,