agmsg-cloud 0.1.0-rc.7 → 0.1.0

package/dist/src/credentials.js

@@ -3,15 +3,51 @@ import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readF
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 /**
- * A server-minted org address: `org_` followed by a canonical uuid.
+ * A server-minted org address, in either of the two forms the server mints.
  *
  * Exported because the shape is a contract between the two places that care —
  * the caller that receives one over the wire and the key that is built from it.
  * Stating it in a comment next to the key was not enough: the comment justified
  * a delimiter by a property nothing enforced.
+ *
+ *   org_<canonical uuid>   what every server has answered with so far
+ *   agor_<26 base32>       the convention (#210), stored in `orgs.public_id`
+ *
+ * BOTH, AND THIS HALF SHIPS FIRST. Until this build is what `npm install`
+ * fetches, the server cannot start answering with the second form: the previous
+ * published build — measured on the tarball the registry serves, not on a
+ * branch, `agmsg-cloud@0.1.0-rc.8`, `dist/src/credentials.js` line 14 — matches
+ * `org_<uuid>` alone, and `keyFor` below THROWS on anything else. So an
+ * installed copy stops being able to store a credential the moment the server
+ * changes, and shipping a newer CLI does not repair an installation nobody has
+ * updated.
+ *
+ * Which is also why this accepts both rather than switching: for the whole
+ * period between this publish and the server's cutover, this build is talking
+ * to a server that still answers with `org_<uuid>`. A build that took only the
+ * new form would break exactly the window it exists to bridge.
+ *
+ * The `agor_` shape is not chosen here. It is the one the database enforces —
+ * `orgs.public_id`'s CHECK is `^agor_[a-z2-7]{26}$` (app/migrations/0036).
+ *
+ * A hand-written fourth copy of a mapping is the defect #216 is about, so what
+ * makes this one safe is a test rather than this paragraph:
+ * `test/org-address-matches-server.test.ts` parses the prefix, the body length
+ * and the alphabet out of `app/src/public-id.ts` and drives THIS function with
+ * values built from them. It is hand-written because the two packages share no
+ * module — `@agmsg-cloud/sas-core` is one protocol's derivations, not a place
+ * for whatever two packages both need.
+ *
+ * That covers one direction: this build accepting what that server mints. The
+ * other — the server refusing to emit anything this build would reject —
+ * belongs to the cutover change, and until it lands the contract holding the
+ * two together is the merge order itself: the cutover does not land until
+ * `npm view agmsg-cloud version` resolves to a build whose `isOrgAddress`
+ * accepts the new form.
  */
 export function isOrgAddress(value) {
-    return /^org_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value);
+    return (/^org_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value) ||
+        /^agor_[a-z2-7]{26}$/.test(value));
 }
 /**
  * The storage key: one slot per (host, org).
@@ -19,9 +55,29 @@ export function isOrgAddress(value) {
  * Both halves are derived rather than taken as typed — `https://x.test/` and
  * `https://x.test` are one host and must not become two slots holding two
  * secrets. The separator is a space because neither half can contain one: an
- * origin has no spaces by construction, and an org address is `org_<uuid>`.
+ * origin has no spaces by construction, and neither org address form admits one
+ * — `isOrgAddress` is anchored at both ends over alphabets that exclude it, and
+ * that is now true of two shapes rather than one.
  *
- * That second half is now checked here rather than assumed. A malformed org —
+ * THE KEY IS THE ADDRESS AS RECEIVED, and the two forms of one org are two
+ * keys. That is correct while the server emits one form at a time: a machine
+ * enrolled before the cutover holds `org_<uuid>` and keeps using it, because
+ * nothing rewrites credentials.json and nothing here can turn one form into the
+ * other — `agor_` is not derived from the uuid, it is a separate stored value
+ * only the server can map. A machine that enrolls again after the cutover gets
+ * a second slot for the same org: no collision and no silent overwrite, since
+ * distinct keys is exactly what stops the second login clobbering the first.
+ *
+ * The cost is one reachable message, and it is worth naming rather than calling
+ * it harmless. `readCredential(origin)` throws when an origin has more than one
+ * slot and none is active — after logging out of the active one, that error now
+ * reads "credentials for more than one org (agor_…, org_…)" about what is ONE
+ * org wearing both of its addresses. The instruction it gives is still the
+ * right one and still works. Cleaning this up means mapping one form to the
+ * other, which only the server can do; it belongs to the cutover change, not
+ * here, and is recorded on #210.
+ *
+ * The org half is checked here rather than assumed. A malformed org —
  * `x`, or anything carrying a space or a newline — would not be caught by a
  * non-empty test upstream, and it does not fail loudly either: it writes a slot
  * under a key nothing will ever look up again, which is worse than the
@@ -84,14 +140,29 @@ function readFile(path) {
  * two secrets that both fit: don't.
  *
  * - one credential for the host — return it
- * - several, and `active` is one of them — return that, the last login
- * - several, and `active` is elsewhere — THROW, naming the orgs
+ * - none — return null
+ * - several — THROW, naming the orgs
+ *
+ * SEVERAL IS NOW ONLY REACHABLE FROM A FILE WRITTEN BEFORE #399, and the branch
+ * stays for exactly that reason. `writeCredential` cannot produce it any more,
+ * so on this version's own files the throw is unreachable — but the file
+ * outlives the binary that wrote it, and a machine upgrading from rc.8 can be
+ * holding two orgs for one host right now. Deleting the branch would not make
+ * that machine consistent; it would make it pick one silently, which is the
+ * failure the org half of the key was added to stop.
  *
- * The last case is the one worth being careful about. Returning `null` there
- * would say "no credential for this host", which is false and sends the caller
- * down the sign-in path — the same collapse of "ambiguous" into "absent" that
- * hid the original defect. It throws instead, and the message names the orgs so
- * the person can say which one they meant.
+ * The `active` tie-break went with the accumulation. It used to answer "several,
+ * and one of them is the last login — use that", and preferring the last login
+ * is precisely the behaviour that was ruled out: a machine holds one credential
+ * per host, so an origin with two is a machine in a state no version can act in
+ * rather than one with a default. `active` itself stays, for the `origin === null`
+ * path below — a machine may still hold one credential for each of several
+ * hosts.
+ *
+ * Returning `null` for the several case would say "no credential for this host",
+ * which is false and sends the caller down the sign-in path — the same collapse
+ * of "ambiguous" into "absent" that hid the original defect. It throws instead,
+ * and the message names the orgs and the one command that resolves it.
  */
 export function readCredential(origin, env = process.env) {
     const file = readFile(credentialsPath(env));
@@ -103,15 +174,14 @@ export function readCredential(origin, env = process.env) {
         return null;
     if (matches.length === 1)
         return matches[0][1];
-    if (file.active && file.credentials[file.active] && file.active.startsWith(`${origin} `)) {
-        return file.credentials[file.active];
-    }
     const orgs = matches
         .map(([, c]) => c.org)
         .sort()
         .join(', ');
-    throw new Error(`${origin} has credentials for more than one org (${orgs}) and none of them is the active one. ` +
-        `Run agmsg-cloud login again for the org you want, which makes it active.`);
+    throw new Error(`${origin} has credentials for more than one org (${orgs}), which this version does not store. ` +
+        `That file was written by an older agmsg-cloud. Run agmsg-cloud logout --endpoint ${origin} ` +
+        `to remove both, then agmsg-cloud login for the org you want — a login now keeps one ` +
+        `credential per service.`);
 }
 // An atomic rename prevents a half-written FILE. It does not serialize an
 // update: two logins to different origins both read the same old JSON, both
@@ -272,6 +342,34 @@ function acquireLock(path) {
         spin(LOCK_RETRY_MS);
     }
 }
+/**
+ * Every credential stored for one host, in no particular order, never throwing.
+ *
+ * `readCredential(origin)` fails closed when a host holds more than one, and
+ * that contract is right for the commands that ASK it something — `connect` and
+ * `pull` want one secret to present, and there is no honest way to pick between
+ * two. It is exactly wrong for `login`.
+ *
+ * Because `login` is the command that RESOLVES the ambiguity. It calls
+ * `readCredential(origin)` before anything else, so on a file written by rc.8 —
+ * two orgs on one host, which is the state this whole change exists to end — it
+ * threw before reaching the grant, the warning, or the replacing write. The
+ * error told the person to run `logout` first, which means "login replaces what
+ * is stored" held only for single slots that the NEW writer had produced, and
+ * not for the machines already in the state. The fail-closed guard was closed
+ * against its own remedy.
+ *
+ * So this is the reader for the one caller that is allowed to see the whole
+ * pile: it returns all of them and lets `login` say how many are going. Nothing
+ * else should use it — a command that acts on an ambiguous host is the defect,
+ * and only the one that is about to collapse the ambiguity is exempt.
+ */
+export function credentialsForOrigin(origin, env = process.env) {
+    const file = readFile(credentialsPath(env));
+    return Object.entries(file.credentials)
+        .filter(([key]) => key.startsWith(`${origin} `))
+        .map(([, credential]) => credential);
+}
 export function writeCredential(credential, env = process.env) {
     const path = credentialsPath(env);
     const dir = dirname(path);
@@ -287,15 +385,49 @@ export function writeCredential(credential, env = process.env) {
         release();
     }
 }
+/**
+ * ONE CREDENTIAL PER ORIGIN, enforced here (#399).
+ *
+ * This used to merge: `{ ...file.credentials, [key]: credential }`, so a login
+ * under a second org added a slot beside the first and nothing ever removed it.
+ * The pile-up was not a feature — the key gained its org half to stop a second
+ * login silently CLOBBERING the first, and accumulation was the side effect. The
+ * resolver has always conceded as much by throwing when an origin holds several
+ * and none is active: what could be stored and what could be used disagreed, and
+ * the gap is what someone walked into when `logout` reported signing out of two
+ * orgs, one of which no longer existed on the server.
+ *
+ * PER ORIGIN, NOT PER MACHINE, and the difference is deliberate. The origin half
+ * of the key separates deployments — staging from production — which is a
+ * distinction someone chose. The org half is the one that accumulated. So a
+ * login to one host leaves another host's credential alone, and signing into
+ * staging cannot delete a production secret.
+ *
+ * The replacement happens INSIDE the lock and in ONE commit, rather than as a
+ * remove followed by a write. Two durable writes have a window between them
+ * where the file holds nothing, and this file is the only copy of a secret: an
+ * interrupt in that window would sign a machine out of a service it was never
+ * asked to leave. `commit` is temp -> fsync -> rename -> fsync dir, so the file
+ * on disk is either entirely the old credential or entirely the new one.
+ *
+ * Entries for OTHER origins are carried across untouched.
+ */
 function writeLocked(path, dir, credential) {
     const key = keyFor(credential.endpoint, credential.org);
+    const origin = originOf(credential.endpoint);
     // Read INSIDE the lock: a copy read before acquiring it is exactly the stale
     // base that loses another entry.
     const file = readFile(path);
+    const otherOrigins = Object.entries(file.credentials).filter(([existing]) => !existing.startsWith(`${origin} `));
     const next = {
         version: 1,
+        // Still a pointer, and still needed: `readCredential(null)` answers "what
+        // does this machine have" for callers that were given no endpoint, and a
+        // machine may legitimately hold one credential per origin. What died is
+        // choosing between two credentials for the SAME origin, which cannot happen
+        // any more.
         active: key,
-        credentials: { ...file.credentials, [key]: credential },
+        credentials: { ...Object.fromEntries(otherOrigins), [key]: credential },
     };
     commit(path, dir, next);
 }

package/dist/src/data-plane.js

@@ -0,0 +1,67 @@
+/**
+ * The one thing this CLI asks the data plane directly: which server is it.
+ *
+ * Everything else that touches the sync gateway goes through the OSS scripts.
+ * This does not, and the reason is an ordering problem they cannot solve for
+ * us: `remote.sh` only reports a server instance for a team it has already
+ * PULLED, and a pull is exactly what must not happen until the instance is
+ * known.
+ *
+ * A vault entry is keyed on `(server_instance_id, team_id)`. Placing one means
+ * pulling it, and a pull creates a local team under a person's name and gives
+ * it history — which, measured on the OSS side, is what makes the NEXT pull
+ * refuse. So a pull performed to discover that the entry belonged to another
+ * server leaves a team that cannot be replaced by the right one, and this
+ * product has no way to free a local name (#446). Nothing may be created until
+ * the pair is confirmed.
+ *
+ * ## Why `/v1/health`, and not `/v1/capabilities`
+ *
+ * The first version of this asked `/v1/capabilities` with the vault entry's
+ * team id, and that request is **not a read on the hosted path** (review).
+ * `gateway/src/server.ts` gives that route `scope: 'header'`, and a scoped
+ * request whose team id comes back `unclaimed` runs `claimOrVerifyTeamCapped`
+ * — for a GET. Probing an entry belonging to another server would therefore
+ * CLAIM that id for this org and spend a unit of the teams cap, and could stop
+ * the org that actually owns it from claiming it later. A check against
+ * creating a local obstacle would have created a server-side one.
+ *
+ * `/v1/health` is `scope: 'none'` in the same table, and **this sends no team
+ * header at all**. With no header the gateway's `healthTeamId` returns before
+ * `verifyTeam` (`if (requested)`), so no claim path is reachable — not
+ * "unlikely", unreachable. The response carries `server_instance_id`, which is
+ * the field the gateway itself caches from it.
+ *
+ * The absence of that header is load-bearing, so it is what the test asserts.
+ */
+/** The OSS client uses 10s connect / 15s total for its own reads; matched. */
+const HEALTH_TIMEOUT_MS = 15_000;
+/**
+ * Ask an endpoint which server instance it is, without asking about any team.
+ *
+ * MEASURED against the OSS server: `GET /v1/health` with no headers answers
+ * 200 with `server_instance_id`, `status`, `database`, and an empty `team_id`.
+ * The instance is a property of the server, so naming no team costs nothing
+ * here — and naming one is what would have cost something.
+ */
+export async function dataPlaneIdentity(capabilityUrl, fetchImpl = fetch) {
+    const url = `${capabilityUrl.replace(/\/+$/, '')}/v1/health`;
+    const response = await fetchImpl(url, {
+        method: 'GET',
+        // No `Agmsg-Team-ID`. See above: the header is what reaches the claim path.
+        headers: { 'Agmsg-Protocol-Version': '1' },
+        signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`the sync server did not answer which instance it is (HTTP ${response.status})`);
+    }
+    const body = await response.json();
+    const instance = body.server_instance_id;
+    // Shape-checked rather than trusted. This value decides whether a backup is
+    // placed, so a wrong one is the accident the check exists to prevent, wearing
+    // the check's clothes.
+    if (typeof instance !== 'string' || instance === '') {
+        throw new Error('the sync server answered without naming which instance it is');
+    }
+    return { serverInstanceId: instance };
+}

package/dist/src/index.js

@@ -11,7 +11,7 @@ import { cmdPull } from './commands/pull.js';
 import { cmdRequest } from './commands/request.js';
 import { cmdVaultPut, cmdVaultRestore } from './commands/vault.js';
 import { cmdWatch } from './commands/watch.js';
-import { packageVersion } from './version.js';
+import { packageInstall } from './version.js';
 const USAGE = `agmsg-cloud — hosted agmsg from this machine
 
   login                        sign this machine in; approve it in your own browser
@@ -33,14 +33,15 @@ const USAGE = `agmsg-cloud — hosted agmsg from this machine
                                it is matched against the snapshot your code authenticated
   approve <team> [request-id]   (on a key-holding machine) approve the waiting request after the codes match
   watch [--interval-ms <n>]    (on a key-holding machine) print pending requests as they arrive
-  recovery setup [team]        create this account's recovery key and back up every active
-                               team this machine's store reports; name one to back up
-                               only that team
-  recovery restore <team>      (on any approved machine) open the backup and unlock <team>
+  recovery setup               create this account's recovery key and back up every active
+                               team this machine's store reports
+  recovery restore [team]      (on any approved machine) open the backup; name a team to
+                               unlock that one, or none to unlock what the vault holds
   whoami                       which of this account's machines this one is —
                                its name, its organization, and the prefix the
                                console shows beside it
-  version                      the version of this CLI (also --version, -v)
+  version                      the version of this CLI, and the directory it is
+                               running out of (also --version, -v)
                                the OSS scripts it drives are reported by
                                \`connect --preflight\`, which is a separate answer
 
@@ -104,7 +105,21 @@ async function main(argv) {
             // one it must assume someone will paste. Written without naming a
             // version: an example that has to be bumped is a second place to bump,
             // which is the reason this command reads the manifest at all.
-            process.stdout.write(`agmsg-cloud/${packageVersion()}\n`);
+            //
+            // The directory follows on its own line because the version alone does
+            // not answer the question people ask this command. `npm i -g agmsg-cloud`
+            // can succeed while a copy another package manager put earlier on PATH is
+            // what runs, and nothing about that is an error: both installs are valid
+            // and the shell picks one. That happened here, and the two defects being
+            // chased were already fixed in the copy that was NOT running. Choosing
+            // for the user would mean deciding their PATH; saying which one answered
+            // costs one line and leaves the choice where it was.
+            //
+            // A path, not a command: this line must not read as something to paste,
+            // which is why it is not shaped like an invocation.
+            const install = packageInstall();
+            process.stdout.write(`agmsg-cloud/${install.version}\n`);
+            process.stdout.write(`running from ${install.directory}\n`);
             return;
         }
         // Beside `version` for the same reason it sits there: both answer a
@@ -229,36 +244,57 @@ async function main(argv) {
         // the one thing that opens the backup, shown once and stored nowhere.
         // A name that hides that is a name someone runs without reading.
         case 'recovery': {
-            const [sub, team] = rest;
+            const [sub, team, ...extra] = rest;
             if (sub !== 'setup' && sub !== 'restore') {
                 // The two take different arguments, so one line covering both said the
                 // wrong thing about each: `setup` does not need a team and `restore`
                 // does. A usage message is read as the contract (raised in review).
-                throw new Error('usage: agmsg-cloud recovery setup [team]\n' +
-                    '       agmsg-cloud recovery restore <team>');
+                throw new Error('usage: agmsg-cloud recovery setup\n' +
+                    '       agmsg-cloud recovery restore [team]');
             }
-            // `setup` takes no team in its ordinary form: the vault is the ACCOUNT's,
-            // so setting it up covers every connected team, and naming one made it a
-            // thing to repeat each time a team was added. A team may still be given,
-            // to add that one on its own. `restore` still requires one — it unlocks a
-            // specific team on this machine.
+            // `setup` takes no team: the vault is the ACCOUNT's, so setting it up
+            // covers every connected team this machine reports. The optional form
+            // was kept only while agmsg#650 could silently return a short enumeration;
+            // that producer now distinguishes unreadable teams, so retaining the
+            // argument would keep teaching an expired per-team recovery model (#182).
+            //
+            // `restore`'s arity is NOT this change's subject. #342a made its team
+            // optional -- the disaster case supplies none -- which is why the line
+            // above reads `[team]`. This branch predates #342a and its side of this
+            // hunk still said `<team>`; taking the hunk wholesale would have
+            // re-imposed the requirement and reverted #342a, with no conflict
+            // marker to show it.
+            //
+            // `restore` NO LONGER REQUIRES ONE (#342), and the reason is the disaster
+            // it is for. It resolved the name through this machine's LOCAL binding
+            // before touching the vault, so the machine the command exists to rescue
+            // — the one that lost everything — never got as far as opening it:
+            // `remote.sh status <team>` answered `team '<x>' has never been
+            // connected` and it stopped there. Measured against a stub endpoint that
+            // logs every request: the server received nothing. Knowing the name did
+            // not help; the name was never the missing thing.
             //
-            // `restore`, written out. It is the only value `sub` can hold here — the
-            // branch tests for it — so the interpolation was indirection that printed
-            // a constant, and it carried a `printed-commands:` exemption to say so.
+            // The restore argument is kept rather than removed. Naming a team is still
+            // what someone does when this machine HAS the team and wants that one
+            // unlocked, and that path works today -- deleting it to fix the broken one
+            // would trade a defect for a regression (#342a).
             //
-            // That exemption was the last one in this file, and #201 is about what it
-            // rested on. Measured: nothing. The guard never reached this line, because
-            // a command introduced by `usage: ` opened no command extent, so the
-            // comment sat over a slot no rule was applied to. Both the comment and the
-            // slot are gone, and the line is now inside the guard's scope.
-            if (sub === 'restore' && !team) {
-                throw new Error('usage: agmsg-cloud recovery restore <team>');
+            // The exemption that used to sit here is gone with #201: measured, the
+            // guard never reached this line, because a command introduced by `usage: `
+            // opened no command extent, so the comment sat over a slot no rule was
+            // applied to. The line is inside the guard's scope now.
+            if (sub === 'setup' && (team !== undefined || extra.length > 0)) {
+                throw new Error('usage: agmsg-cloud recovery setup');
             }
+            // NO `restore` guard. This branch had one, re-asserting that restore
+            // requires a team; #342a removed that requirement and the disaster case
+            // supplies no team. Its call below therefore has to keep main's optional
+            // form -- the two travel together, and taking this hunk wholesale would
+            // have restored both halves silently.
             const config = loadConfig();
             return sub === 'setup'
-                ? cmdVaultPut(config, team === undefined ? {} : { team })
-                : cmdVaultRestore(config, { team: team });
+                ? cmdVaultPut(config)
+                : cmdVaultRestore(config, team === undefined ? {} : { team });
         }
         default:
             throw new Error(`unknown command: ${cmd}\n\n${USAGE}`);

package/dist/src/oss.js

@@ -29,7 +29,7 @@ function run(cmd, args, input) {
     });
 }
 /** A finished run, whatever its exit code. For callers where non-zero is an ANSWER. */
-function runAllowingFailure(cmd, args) {
+export function runAllowingFailure(cmd, args) {
     return new Promise((resolve, reject) => {
         const child = spawnOssPiped(cmd, args);
         const out = [];
@@ -211,10 +211,39 @@ export async function connectedTeams(scriptsDir) {
             teamId: status.remote_team_id,
             serverInstanceId: status.server_instance_id,
             state: status.state,
+            // NOT refused when absent, unlike the ids above. A binding without the
+            // ids cannot be filed into a vault entry, which is why those refuse; a
+            // binding whose address this version cannot read is still a team, and the
+            // only caller that wants the address can say "could not tell" for it. An
+            // empty string is that, and `teamsBoundTo` treats it as not matching any
+            // host rather than as matching the one being asked about.
+            endpoint: typeof status.endpoint === 'string' ? status.endpoint : '',
         });
     }
     return teams;
 }
+export async function teamsBoundTo(scriptsDir, origin) {
+    const teams = await connectedTeams(scriptsDir);
+    const matched = [];
+    const unreadable = [];
+    for (const t of teams) {
+        if (t.endpoint === '') {
+            unreadable.push(t.team);
+            continue;
+        }
+        let bound;
+        try {
+            bound = new URL(t.endpoint).origin;
+        }
+        catch {
+            unreadable.push(t.team);
+            continue;
+        }
+        if (bound === origin)
+            matched.push(t.team);
+    }
+    return { matched: matched.sort(), unreadable: unreadable.sort() };
+}
 export async function remoteTeamId(scriptsDir, team) {
     const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
     const text = out.toString().trim();