agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/version.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// This package's own name, as its manifest declares it. Not a duplicate of the
+// version — an identity, and the only thing that tells one package.json from
+// another while walking up a tree that may contain several.
+const PACKAGE_NAME = 'agmsg-cloud';
+// The version this build was published as.
+//
+// Read from the package's own `package.json` at runtime rather than baked into
+// a constant, because a constant is a second place to update and the one that
+// gets forgotten: a build that says the wrong version is worse than one that
+// says none, since the answer looks authoritative either way. npm always
+// includes package.json in a tarball, so it is there for a published install.
+//
+// Found by walking UP from this module rather than by a fixed relative path,
+// because the depth differs between the two places this file runs from:
+// `src/version.ts` sits one level under the package root, `dist/src/version.js`
+// sits two. A path correct in one is wrong in the other, and the one that would
+// be wrong is the published one.
+//
+// The walk answers only from a manifest that NAMES this package. Without that
+// check the first non-empty version above the module wins, and the installs
+// most likely to hit it are the broken ones — a package.json missing or
+// stripped of its version is exactly when a monorepo root, an npx cache entry,
+// or a parent workspace supplies its own. Reporting a stranger's version is the
+// failure this command exists to prevent, wearing the shape of a success.
+export function packageVersion(moduleUrl = import.meta.url) {
+    let dir = dirname(fileURLToPath(moduleUrl));
+    const { root } = parse(dir);
+    for (;;) {
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        }
+        catch {
+            // No manifest here, or one that is not JSON. Either way it does not
+            // identify itself, so it cannot be this package's answer.
+            manifest = undefined;
+        }
+        if (manifest?.name === PACKAGE_NAME) {
+            const version = manifest.version;
+            if (typeof version === 'string' && version !== '')
+                return version;
+            // Fail closed. This IS the package and it cannot say what it is; climbing
+            // past would hand the question to whatever sits above, which is how a
+            // broken install comes to announce a stranger's version.
+            throw new Error(`the installed ${PACKAGE_NAME} package.json carries no version — this install cannot say which build it is`);
+        }
+        if (dir === root)
+            break;
+        dir = dirname(dir);
+    }
+    // Reached when the package was installed without its manifest. Said, not
+    // guessed — see the note above.
+    throw new Error(`cannot determine the installed version: no ${PACKAGE_NAME} package.json above this module`);
+}

package/node_modules/@agmsg-cloud/sas-core/dist/src/bech32.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Decode a canonical lowercase bech32 string, or return null.
+ *
+ * Mixed case is rejected rather than folded: BIP-173 allows an all-uppercase
+ * form, but folding it here would mean two spellings of one recipient, and the
+ * commitment binds the STRING. Anything a caller has to normalize first is
+ * something the two sides could normalize differently.
+ */
+export declare function decodeBech32(input: string): {
+    hrp: string;
+    data: number[];
+} | null;
+/**
+ * Whether a string is a canonical age recipient: bech32 with the `age` human-
+ * readable part, a valid checksum, and exactly a 32-byte X25519 payload.
+ */
+export declare function isCanonicalAgeRecipient(input: string): boolean;

package/node_modules/@agmsg-cloud/sas-core/dist/src/bech32.js

@@ -0,0 +1,103 @@
+// Bech32 (BIP-173) decoding, enough to decide whether a string is a canonical
+// age recipient.
+//
+// This exists because a shape check is not a canonicality check. `age1` followed
+// by 58 lowercase alphanumerics matches strings that are not recipients at all:
+// `b`, `i`, `o` and `1` are excluded from the bech32 data alphabet precisely
+// because they are easy to confuse with `6`, `1`, `0` and `l`, and the six
+// trailing characters are a checksum that a length check never looks at.
+//
+// Spec §2 says reject rather than normalize. A validator that accepts a
+// checksum-broken recipient does not merely admit junk: it lets two
+// implementations disagree about whether a transcript is valid, and the whole
+// point of the ceremony is that both sides commit to the SAME device key.
+const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+// An X25519 public key. age recipients carry exactly this much payload, so a
+// well-formed bech32 string of the wrong length is still not a recipient.
+const AGE_PAYLOAD_BYTES = 32;
+const AGE_HRP = 'age';
+function polymod(values) {
+    let chk = 1;
+    for (const value of values) {
+        const top = chk >> 25;
+        chk = ((chk & 0x1ffffff) << 5) ^ value;
+        for (let i = 0; i < 5; i++) {
+            if ((top >> i) & 1)
+                chk ^= GENERATOR[i];
+        }
+    }
+    return chk;
+}
+function hrpExpand(hrp) {
+    const out = [];
+    for (let i = 0; i < hrp.length; i++)
+        out.push(hrp.charCodeAt(i) >> 5);
+    out.push(0);
+    for (let i = 0; i < hrp.length; i++)
+        out.push(hrp.charCodeAt(i) & 31);
+    return out;
+}
+// 5-bit groups back to 8-bit bytes. The two trailing checks are the part a
+// naive implementation drops: leftover bits must be fewer than a full byte and
+// must be zero, or several distinct encodings would decode to the same key.
+function convert5to8(data) {
+    let acc = 0;
+    let bits = 0;
+    const out = [];
+    for (const value of data) {
+        acc = (acc << 5) | value;
+        bits += 5;
+        while (bits >= 8) {
+            bits -= 8;
+            out.push((acc >> bits) & 0xff);
+        }
+    }
+    if (bits >= 5)
+        return null; // more padding than a partial group can justify
+    if ((acc << (8 - bits)) & 0xff)
+        return null; // padding bits must be zero
+    return Uint8Array.from(out);
+}
+/**
+ * Decode a canonical lowercase bech32 string, or return null.
+ *
+ * Mixed case is rejected rather than folded: BIP-173 allows an all-uppercase
+ * form, but folding it here would mean two spellings of one recipient, and the
+ * commitment binds the STRING. Anything a caller has to normalize first is
+ * something the two sides could normalize differently.
+ */
+export function decodeBech32(input) {
+    if (input !== input.toLowerCase())
+        return null;
+    const separator = input.lastIndexOf('1');
+    if (separator < 1 || separator + 7 > input.length)
+        return null;
+    const hrp = input.slice(0, separator);
+    for (let i = 0; i < hrp.length; i++) {
+        const code = hrp.charCodeAt(i);
+        if (code < 33 || code > 126)
+            return null;
+    }
+    const data = [];
+    for (const char of input.slice(separator + 1)) {
+        const index = CHARSET.indexOf(char);
+        if (index === -1)
+            return null;
+        data.push(index);
+    }
+    if (polymod([...hrpExpand(hrp), ...data]) !== 1)
+        return null;
+    return { hrp, data: data.slice(0, data.length - 6) };
+}
+/**
+ * Whether a string is a canonical age recipient: bech32 with the `age` human-
+ * readable part, a valid checksum, and exactly a 32-byte X25519 payload.
+ */
+export function isCanonicalAgeRecipient(input) {
+    const decoded = decodeBech32(input);
+    if (!decoded || decoded.hrp !== AGE_HRP)
+        return false;
+    const payload = convert5to8(decoded.data);
+    return payload !== null && payload.length === AGE_PAYLOAD_BYTES;
+}

package/node_modules/@agmsg-cloud/sas-core/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+export { decodeBech32, isCanonicalAgeRecipient } from './bech32.js';
+export type Bytes32 = Uint8Array;
+export interface SasCommitment {
+    commitmentHex: string;
+    openingNonce: Bytes32;
+}
+export declare function deriveSasCommitment(devicePubkey: string, openingNonce: Bytes32): string;
+export declare function deriveApproverCommitment(approverNonce: Bytes32, handoffDigestHex: string): string;
+export declare function deriveRequestNonce(approverNonce: Bytes32, openingNonce: Bytes32): Bytes32;
+export declare function deriveSas(devicePubkey: string, requestNonce: Bytes32, handoffDigestHex: string): string;
+export declare function verifySasCommitment(commitmentHex: string, devicePubkey: string, openingNonce: Bytes32): boolean;
+export declare function verifyApproverCommitment(commitmentHex: string, approverNonce: Bytes32, handoffDigestHex: string): boolean;
+export declare function createSasCommitment(devicePubkey: string, randomBytes?: (length: 32) => Bytes32): SasCommitment;
+export declare function createApproverCommitment(handoffDigestHex: string, randomBytes?: (length: 32) => Bytes32): {
+    commitmentHex: string;
+    approverNonce: Bytes32;
+};

package/node_modules/@agmsg-cloud/sas-core/dist/src/index.js

@@ -0,0 +1,147 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { isCanonicalAgeRecipient } from './bech32.js';
+// Re-exported so the routes validate with the SAME function the derivations
+// use. A route that kept its own check is how the two drift apart.
+export { decodeBech32, isCanonicalAgeRecipient } from './bech32.js';
+const NONCE_BYTES = 32;
+const DIGEST_HEX = /^[0-9a-f]{64}$/;
+// §3.5: the largest multiple of 100,000,000 below 2^32. Candidates at or above
+// it are rejected so every eight-digit value stays equally likely.
+const REJECT_AT = 4_200_000_000;
+const SAS_MODULUS = 100_000_000;
+function ascii(s) {
+    return Buffer.from(s, 'ascii');
+}
+function u32be(n) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32BE(n >>> 0);
+    return b;
+}
+// LP(x) = U32BE(byte_length(x)) || x  (§2). The length prefix is what stops a
+// longer pubkey from being confused with a shorter one plus the bytes after it.
+function lengthPrefixed(x) {
+    return Buffer.concat([u32be(x.length), x]);
+}
+function sha256(...parts) {
+    return createHash('sha256').update(Buffer.concat(parts)).digest();
+}
+// §2: reject rather than normalize. Trimming or lowercasing here would make two
+// callers that disagree about the input agree about the digest, which is the
+// substitution this protocol is built to detect.
+function requireDevicePubkey(devicePubkey) {
+    // Checked as an ENCODING, not as a shape. `age1` plus 58 lowercase
+    // alphanumerics matches strings that are not recipients: the bech32 alphabet
+    // excludes b, i, o and 1, and the last six characters are a checksum a length
+    // test never reads. A validator that accepts those lets two implementations
+    // disagree about whether a transcript is valid, which is exactly the
+    // disagreement the ceremony exists to make impossible.
+    if (!isCanonicalAgeRecipient(devicePubkey)) {
+        throw new Error('device_pubkey is not a canonical age recipient');
+    }
+    return ascii(devicePubkey);
+}
+function requireNonce(nonce, label) {
+    if (!(nonce instanceof Uint8Array) || nonce.length !== NONCE_BYTES) {
+        throw new Error(`${label} must be exactly ${NONCE_BYTES} bytes`);
+    }
+    return Buffer.from(nonce);
+}
+function requireDigestHex(hex, label) {
+    if (!DIGEST_HEX.test(hex)) {
+        throw new Error(`${label} must be 64 lowercase hexadecimal characters`);
+    }
+    return Buffer.from(hex, 'hex');
+}
+function csprng(length) {
+    return new Uint8Array(randomBytes(length));
+}
+// §3.1 — B's commitment to (device_pubkey, b).
+export function deriveSasCommitment(devicePubkey, openingNonce) {
+    return sha256(ascii('agmsg-sas-commit-v1\0'), lengthPrefixed(requireDevicePubkey(devicePubkey)), requireNonce(openingNonce, 'opening nonce')).toString('hex');
+}
+// §3.2 — A's commitment to `a` AND to the SNAPSHOT it will hand over.
+//
+// The digest is bound HERE, before either side opens, and that ordering is the
+// whole point. The previous version fixed the eight digits first and produced
+// the handed-over state afterwards, so the side that produced it last was free
+// to vary it: an attacker could search offline for a state whose digest still
+// produced the same eight digits, and the brute force that two-party
+// commitment removes walked back in through the handover.
+//
+// What this closes, stated as knowledge rather than as ignorance: A commits
+// before B opens its committed `device_pubkey` and `b`. A is NOT blind here —
+// it has fetched B's request and holds the commitment and the label — but
+// neither of those lets it aim at the resulting digits, because B's commitment
+// hides those two values behind a fresh random nonce and both are SAS inputs.
+// Within the attempt, A can no longer change what it will hand over; starting
+// a fresh attempt is a different act, bounded by §4.1 (raised in review).
+//
+// It is still A's own nonce that hides the digest until the opening: the
+// commitment is over `a || handoff_digest`, and `a` is 32 random bytes, so the
+// commitment discloses nothing about which snapshot is being handed over.
+export function deriveApproverCommitment(approverNonce, handoffDigestHex) {
+    return sha256(
+    // The tag stays v1, and the INPUT is what changed. Nothing has ever been
+    // shipped under the old input, so there is no deployed derivation for this
+    // one to collide with — and cutting a v2 would mean a second protocol
+    // identity, wire negotiation, and a rejection boundary for values that do
+    // not exist. The tag names the spec; the spec is being corrected in place
+    // (raised in review).
+    ascii('agmsg-sas-approver-commit-v1\0'), requireNonce(approverNonce, 'approver nonce'), requireDigestHex(handoffDigestHex, 'handoff digest')).toString('hex');
+}
+// §3.4 — the nonce the SAS is derived from. Neither side alone chooses it.
+export function deriveRequestNonce(approverNonce, openingNonce) {
+    return new Uint8Array(sha256(ascii('agmsg-sas-request-nonce-v1\0'), requireNonce(approverNonce, 'approver nonce'), requireNonce(openingNonce, 'opening nonce')));
+}
+// §3.5 — eight decimal digits as dddd-dddd, rejection-sampled so no value is
+// more likely than another. Leading zeroes are significant.
+export function deriveSas(devicePubkey, requestNonce, handoffDigestHex) {
+    const seed = sha256(ascii('agmsg-sas-v1\0'), lengthPrefixed(requireDevicePubkey(devicePubkey)), requireNonce(requestNonce, 'request nonce'), 
+    // The digits attest the BUNDLE as well as the device. Without this the
+    // human comparison says "the machine I am talking to holds this key" and
+    // says nothing about what is being handed to it, which is the half the
+    // committed digest exists to cover — and a code that covers one of two
+    // things reads to the person comparing it as covering the ceremony.
+    requireDigestHex(handoffDigestHex, 'handoff digest'));
+    for (let counter = 0;; counter += 1) {
+        const block = sha256(ascii('agmsg-sas-code-v1\0'), seed, u32be(counter));
+        const candidate = block.readUInt32BE(0);
+        if (candidate < REJECT_AT) {
+            const digits = String(candidate % SAS_MODULUS).padStart(8, '0');
+            return `${digits.slice(0, 4)}-${digits.slice(4)}`;
+        }
+    }
+}
+// Both verifiers compare decoded digest BYTES in constant time, after strict
+// encoding checks (§7). A string compare would leak how much of a guessed
+// commitment was right through timing, and would also accept an uppercase or
+// padded form that the derivation never produces.
+export function verifySasCommitment(commitmentHex, devicePubkey, openingNonce) {
+    const offered = requireDigestHex(commitmentHex, 'commitment');
+    const computed = Buffer.from(deriveSasCommitment(devicePubkey, openingNonce), 'hex');
+    return timingSafeEqual(offered, computed);
+}
+export function verifyApproverCommitment(commitmentHex, approverNonce, handoffDigestHex) {
+    const offered = requireDigestHex(commitmentHex, 'approver commitment');
+    const computed = Buffer.from(deriveApproverCommitment(approverNonce, handoffDigestHex), 'hex');
+    return timingSafeEqual(offered, computed);
+}
+// Randomness is injectable for tests only (§7); production callers take the
+// default, which is the platform CSPRNG.
+export function createSasCommitment(devicePubkey, randomBytes = csprng) {
+    const openingNonce = randomBytes(NONCE_BYTES);
+    return { commitmentHex: deriveSasCommitment(devicePubkey, openingNonce), openingNonce };
+}
+// The digest is a parameter, not something this can produce: A must have
+// exported the snapshot locally before it can commit. That order is the change
+// — a caller that has no digest yet cannot get a commitment out of this, which
+// is the compile-time shape of "nothing is committed to before the state being
+// handed over is fixed". The bundle carrying identity material is generated
+// after the user answers, and §4 checks it against this digest.
+export function createApproverCommitment(handoffDigestHex, randomBytes = csprng) {
+    const approverNonce = randomBytes(NONCE_BYTES);
+    return {
+        commitmentHex: deriveApproverCommitment(approverNonce, handoffDigestHex),
+        approverNonce,
+    };
+}

package/node_modules/@agmsg-cloud/sas-core/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@agmsg-cloud/sas-core",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "files": [
+    "dist/src"
+  ]
+}

package/package.json

@@ -1,10 +1,53 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.0.1",
-  "description": "Reserved: companion CLI for the agmsg cloud service.",
-  "bin": { "agmsg-cloud": "bin/agmsg-cloud.js" },
-  "files": ["bin/", "README.md"],
-  "repository": { "type": "git", "url": "git+https://github.com/JugemuAI/agmsg-cloud.git" },
-  "author": "Jugemu Labs, Inc.",
-  "license": "UNLICENSED"
+  "version": "0.1.0-rc.4",
+  "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "agmsg-cloud": "dist/src/index.js"
+  },
+  "files": [
+    "dist/src",
+    "!dist/src/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JugemuAI/agmsg-cloud.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://agmsg.ai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:deps": "pnpm --filter @agmsg-cloud/sas-core build",
+    "prebuild": "pnpm run build:deps",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node dist/src/index.js",
+    "pretest": "pnpm run build:deps",
+    "test": "vitest run",
+    "pretypecheck": "pnpm run build:deps",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsx scripts/check-printed-commands.ts && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
+    "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts"
+  },
+  "dependencies": {
+    "@agmsg-cloud/sas-core": "workspace:*",
+    "hash-wasm": "4.12.0",
+    "uuid": "14.0.1"
+  },
+  "bundleDependencies": [
+    "@agmsg-cloud/sas-core"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsx": "4.23.1",
+    "typescript": "7.0.2",
+    "typescript5": "npm:typescript@5.9.3",
+    "vitest": "4.1.10"
+  }
 }

package/bin/agmsg-cloud.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-// Placeholder. This package name is reserved for the agmsg cloud
-// companion CLI. Nothing to run yet.
-console.log('agmsg-cloud: coming soon.');