agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/README.md

@@ -1,4 +1,41 @@
 # agmsg-cloud
 
-This package name is reserved for the agmsg cloud companion CLI.
-Nothing to see here yet.
+The companion CLI for the agmsg cloud service. It signs a machine in, puts a
+team you already run onto the service, and joins that team from a second
+machine — with the key handoff confirmed by a code the two people compare out
+loud.
+
+This is a prerelease. It is published under the `next` tag, so it is not what
+`npm install agmsg-cloud` gives you:
+
+```
+npm install -g agmsg-cloud@next
+agmsg-cloud            # prints what it can do
+agmsg-cloud version    # which build this is
+```
+
+Node 22 or newer.
+
+## What it does
+
+```
+agmsg-cloud login                  sign this machine in
+agmsg-cloud connect <team>         put a team this machine runs onto the service
+agmsg-cloud sync <team>            (on a new machine) ask to join, and wait
+agmsg-cloud approve <team>         (on a machine that has the keys) answer that request
+agmsg-cloud recovery setup         create the account's recovery key and back up every
+                                   active team this machine's store reports
+
+```
+
+`sync` and `approve` are two halves of one ceremony: each screen shows eight
+digits, the two people read them to each other, and the keys move only if they
+match. Nothing is carried between the machines by hand.
+
+## Where it lives
+
+Home: <https://agmsg.ai>. The open-source project it builds on is
+[agmsg](https://agmsg.cc).
+
+Issues and source: <https://github.com/JugemuAI/agmsg-cloud> — the repository is
+private during the prerelease.

package/dist/src/api.js

@@ -0,0 +1,517 @@
+import { isCanonicalAgeRecipient } from '@agmsg-cloud/sas-core';
+// Wire validation.
+//
+// Every response is checked here, at the boundary, rather than cast and trusted.
+// The reason is one specific failure repeated three times in this arc: a body
+// that is not what it claims arrives as `undefined` somewhere downstream, and
+// downstream cannot tell "malformed" from "absent". In the reconciliation path
+// that difference decides whether a live enrollment is abandoned and its nonce
+// deleted, so a body this client cannot vouch for has to be an error, not an
+// empty answer.
+//
+// Validated as a CLASS, not where the bug was found. Checking only the endpoint
+// that happened to be reported leaves the same hole in every sibling.
+const HEX64 = /^[0-9a-f]{64}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const STATUSES = [
+    'requester_committed',
+    'both_committed',
+    'requester_opened',
+    'opened',
+    'consumed',
+    'expired',
+    'failed',
+    'refused',
+];
+// Ranges, not types.
+//
+// `typeof x === 'string'` is a statement about JavaScript; what each of these
+// fields has to be is narrower, and a value that is the right TYPE with the
+// wrong MEANING passes straight through a type check into whatever reads it.
+// The revision that prompted this is the clearest case — a number, but 3.5 —
+// and the same gap was sitting in every neighbouring field.
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function isTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    return Number.isFinite(Date.parse(value));
+}
+// Exported for the one caller that has to check an id the wire never carried:
+// `pull --team-id` is handed straight to the OSS side without passing this
+// module's response validation at all.
+export function isUuid(value) {
+    return typeof value === 'string' && UUID.test(value);
+}
+function isRecipient(value) {
+    return typeof value === 'string' && isCanonicalAgeRecipient(value);
+}
+function isBase64(value) {
+    return typeof value === 'string' && value.length % 4 === 0 && BASE64.test(value);
+}
+// Non-empty and bounded. An unbounded label is a display surface fed by the
+// server; a zero-length one is not a label.
+function isLabel(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 256;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function optionalHex(value) {
+    return value === null || (typeof value === 'string' && HEX64.test(value));
+}
+function isTranscript(value) {
+    if (!isObject(value))
+        return false;
+    if (!isUuid(value['id']))
+        return false;
+    if (!STATUSES.includes(value['status']))
+        return false;
+    if (!isLabel(value['label']))
+        return false;
+    if (typeof value['commitment'] !== 'string' || !HEX64.test(value['commitment']))
+        return false;
+    if (!optionalHex(value['approver_commitment']))
+        return false;
+    if (!optionalHex(value['opening_nonce']))
+        return false;
+    if (!optionalHex(value['approver_nonce']))
+        return false;
+    if (!optionalHex(value['request_nonce']))
+        return false;
+    if (!optionalHex(value['handoff_digest']))
+        return false;
+    // The device key is the value the whole ceremony is about. Accepting any
+    // string here would let a non-recipient reach the commitment check and fail
+    // there instead — a permanent failure for what is really a malformed reply.
+    if (value['device_pubkey'] !== null && !isRecipient(value['device_pubkey'])) {
+        return false;
+    }
+    if (!isTimestamp(value['created_at']) || !isTimestamp(value['expires_at']))
+        return false;
+    return true;
+}
+// The Argon2id parameters the recovery key is derived with. Numbers that arrive
+// as strings, or a missing cost, would otherwise reach the derivation and change
+// what key comes out.
+// A revision the append path can add one to and still be exact.
+//
+// Checked as a safe INTEGER, not merely as a number. The current revision is
+// read here and sealed into the AAD as `existing.revision + 1`; a wire value of
+// 3.5 becomes 4.5 in the AAD, the server stores the integer 4, and the mismatch
+// is only noticed after a version nobody can open has been written. The safe
+// bound is what makes the `+ 1` exact rather than approximate.
+function isRevision(value) {
+    // The SUCCESSOR has to be safe, not just the value. MAX_SAFE_INTEGER passes
+    // Number.isSafeInteger and then `+ 1` lands on 2^53, where distinct integers
+    // stop being distinct — so a later mismatch check could compare two different
+    // revisions and find them equal. The comment above used to claim this
+    // property while the predicate did not enforce it.
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && Number.isSafeInteger(value + 1);
+}
+// A wrap slot off the wire. Every field is stored by this client into an AEAD's
+// additional data or fed to the KDF, so each is checked for its kind rather than
+// for being present: a cost that arrives as a string changes what key comes out,
+// and a slot_type this version does not know is a slot it must not try to open.
+//
+// 'recovery-key' is the only type. The device slot is not one of these: it lives
+// in this machine's secure store, never on the server (:528-530). A response
+// carrying one is either a server that stored what it must not, or a response
+// this client should not be following — both are malformed here.
+function isVdkWrap(value) {
+    if (!isObject(value))
+        return false;
+    if (!isUuid(value['slot_id']))
+        return false;
+    if (value['slot_type'] !== 'recovery-key')
+        return false;
+    if (typeof value['wrap_profile'] !== 'string' || value['wrap_profile'].length === 0)
+        return false;
+    if (typeof value['kdf_profile'] !== 'string' || value['kdf_profile'].length === 0)
+        return false;
+    if (typeof value['salt'] !== 'string' || value['salt'].length === 0)
+        return false;
+    if (!isBase64(value['wrapped_vdk']))
+        return false;
+    const params = value['kdf_params'];
+    if (!isObject(params))
+        return false;
+    for (const cost of ['m', 't', 'p']) {
+        const n = params[cost];
+        if (typeof n !== 'number' || !Number.isInteger(n) || n <= 0)
+            return false;
+    }
+    return true;
+}
+function isKdfMeta(value) {
+    if (!isObject(value))
+        return false;
+    if (typeof value['kdf'] !== 'string' || typeof value['salt'] !== 'string')
+        return false;
+    for (const cost of ['m', 't', 'p']) {
+        const n = value[cost];
+        if (typeof n !== 'number' || !Number.isInteger(n) || n <= 0)
+            return false;
+    }
+    return true;
+}
+function requireTranscript(value) {
+    if (!isTranscript(value))
+        throw new CourierError(200, 'malformed_enrollment');
+    return value;
+}
+export class CourierError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`courier request failed: ${status} ${code}`);
+        this.status = status;
+        this.code = code;
+        this.name = 'CourierError';
+    }
+}
+export class CourierClient {
+    baseUrl;
+    secret;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.secret = opts.secret;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async call(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.secret}`,
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (res.status === 204)
+            return undefined;
+        if (!res.ok) {
+            let code = 'unknown';
+            try {
+                const parsed = (await res.json());
+                if (typeof parsed.error === 'string')
+                    code = parsed.error;
+            }
+            catch {
+                // no/'' JSON body — keep the generic code, never echo the raw response
+            }
+            throw new CourierError(res.status, code);
+        }
+        return res.status === 200 || res.status === 201 ? res.json() : undefined;
+    }
+    // B: ask to be added, carrying ONLY the commitment digest and a label. The
+    // device key and the opening nonce are deliberately absent — a request that
+    // held them before A has committed is what would let A choose its own
+    // contribution to match.
+    async createEnrollment(input) {
+        const out = await this.call('POST', '/v1/enrollments', input);
+        if (!isObject(out) ||
+            !isUuid(out['request_id']) ||
+            !isTimestamp(out['expires_at'])) {
+            throw new CourierError(200, 'malformed_create_response');
+        }
+        return { request_id: out['request_id'], expires_at: out['expires_at'] };
+    }
+    // The live ceremonies this caller may drive: the org's, for a key holder;
+    // its own, for anyone else.
+    //
+    // The shape is checked rather than asserted. A cast turns a body that is not
+    // what it claims into `undefined` and then into a TypeError several frames
+    // away, where a caller trying to decide "did my request reach the server?"
+    // cannot tell a malformed answer from any other kind of failure — and that
+    // difference decides whether a live enrollment is abandoned.
+    async listEnrollments() {
+        const out = await this.call('GET', '/v1/enrollments');
+        if (!isObject(out) || !Array.isArray(out['enrollments'])) {
+            throw new CourierError(200, 'malformed_enrollments_response');
+        }
+        // ONE malformed row fails the whole list. A caller asking "is my request
+        // still live?" reads a short list as an answer, and silently dropping the
+        // rows we could not parse would make that answer wrong in the one direction
+        // that costs a live enrollment.
+        return out['enrollments'].map(requireTranscript);
+    }
+    // Either side: read one ceremony. B polls this to learn A's commitment, which
+    // it MUST have before opening its own.
+    async getEnrollment(requestId) {
+        return requireTranscript(await this.call('GET', `/v1/enrollments/${encodeURIComponent(requestId)}`));
+    }
+    // A: fix a commitment to its nonce, without revealing it.
+    /**
+     * Ask the server to settle which request this approver is answering, when it
+     * was given no id.
+     *
+     * Called BEFORE an attempt is consumed and before any commitment is built.
+     * §4.1 charges the send rather than the reply, so a "there are two" discovered
+     * at commitment time is discovered too late: it could only be given back by
+     * the local ledger believing the server's account of what it did, and the
+     * server is inside the threat model.
+     */
+    async claimSoleLiveRequest() {
+        const body = (await this.call('POST', '/v1/enrollments/claim', {}));
+        // The same check the create response gets. Not a security boundary — the
+        // claim is enforced server-side — but it is the same wire surface, and one
+        // field validated more weakly than its neighbours is how a second, looser
+        // spelling of a timestamp gets in (raised in review).
+        if (typeof body.request_id !== 'string' || !isTimestamp(body.claim_expires_at)) {
+            throw new Error('courier returned a claim without a request id');
+        }
+        return { requestId: body.request_id, claimExpiresAt: body.claim_expires_at };
+    }
+    async submitApproverCommitment(requestId, approverCommitment, 
+    // True when this approver named no request id and had the server settle
+    // which one this is, before these bytes were built. It asks the server to
+    // check that claim is still ours and still live.
+    requireSoleLiveRequest = false) {
+        return requireTranscript(await this.call('POST', `/v1/enrollments/${encodeURIComponent(requestId)}/approver-commitment`, {
+            approver_commitment: approverCommitment,
+            ...(requireSoleLiveRequest ? { require_sole_live_request: true } : {}),
+        }));
+    }
+    // B: reveal the device key and the nonce it committed to.
+    async submitOpening(requestId, input) {
+        return requireTranscript(await this.call('POST', `/v1/enrollments/${encodeURIComponent(requestId)}/opening`, input));
+    }
+    // A: reveal its nonce, after verifying B's opening.
+    async submitApproverOpening(requestId, approverNonce, 
+    // Sent WITH the nonce, because the commitment is over both. The server
+    // cannot verify the opening without it, and B cannot derive the SAS
+    // without it (spec 3.3).
+    handoffDigest) {
+        return requireTranscript(await this.call('POST', `/v1/enrollments/${encodeURIComponent(requestId)}/approver-opening`, {
+            approver_nonce: approverNonce,
+            handoff_digest: handoffDigest,
+        }));
+    }
+    // Either side: report that the ceremony failed — a code mismatch, a
+    // cancellation, a timeout noticed locally. The attempt still counts; that is
+    // the point of reporting it rather than walking away.
+    async abortEnrollment(requestId) {
+        await this.call('DELETE', `/v1/enrollments/${encodeURIComponent(requestId)}`);
+    }
+    // A: approve by uploading the sealed bundle. operation_id is the idempotency key.
+    async uploadBundle(requestId, input) {
+        const out = await this.call('POST', `/v1/enrollments/${encodeURIComponent(requestId)}/bundle`, input);
+        if (!isObject(out) || !isUuid(out['device_id'])) {
+            throw new CourierError(200, 'malformed_bundle_response');
+        }
+        return { device_id: out['device_id'] };
+    }
+    // A: the rotate recipient set (every registered device's public key).
+    // Register THIS machine as the team's first device. Only the capability that
+    // claimed the team may do it.
+    //
+    // Success covers the re-run: the server answers 201 both when it creates the
+    // row and when this capability was already registered under this same key,
+    // because in both cases what the caller asked for is true. It distinguishes
+    // the two failures that used to share one code — this capability holding a
+    // different key, and this key belonging to another capability — which no
+    // client can tell apart from the outside.
+    async bootstrapDevice(input) {
+        const out = (await this.call('POST', '/v1/devices', input));
+        return { deviceId: out.device_id };
+    }
+    // Which team is called X, asked of the CONTROL plane.
+    //
+    // The core has a name lookup and the gateway keeps it closed on purpose: it
+    // answers across every team on the server, so forwarding it would tell one
+    // org that another org's team exists. The control plane knows whose team is
+    // whose, so it can answer inside the caller's org — which is why the second
+    // machine resolves the name here and pulls by id, rather than handing a
+    // name to the data plane.
+    async resolveTeamByName(name) {
+        const out = await this.call('GET', `/v1/edge/teams?name=${encodeURIComponent(name)}`);
+        // A response this cannot read is not an answer about which teams exist,
+        // and it must not be turned into one. `teams` must be PRESENT and an
+        // array, with an empty array the only way to say "none" — the same rule
+        // the vault boundary above follows, for the same reason: absence here is
+        // a normal state that the caller acts on, and an unreadable 200 collapsed
+        // into it becomes the assertion "this organization has no team by that
+        // name".
+        if (!isObject(out) || !Array.isArray(out['teams'])) {
+            throw new CourierError(200, 'malformed_teams_response');
+        }
+        // Every member, or none. Dropping a malformed row would be worse than
+        // dropping the whole response: `pull` refuses when a name matches more
+        // than one team, so a single unreadable row beside a valid one would
+        // reduce the ambiguous set to one and pull whichever row survived —
+        // exactly the case the refusal exists to prevent, reached with wire data
+        // nobody could parse.
+        for (const t of out['teams']) {
+            if (!isObject(t) ||
+                !isUuid(t['team_id']) ||
+                !(typeof t['team_name'] === 'string' || t['team_name'] === null)) {
+                throw new CourierError(200, 'malformed_teams_response');
+            }
+        }
+        return out['teams'].map((t) => ({
+            teamId: t.team_id,
+            teamName: t.team_name,
+        }));
+    }
+    async listDevices() {
+        const out = await this.call('GET', '/v1/devices');
+        if (!isObject(out) || !Array.isArray(out['devices'])) {
+            throw new CourierError(200, 'malformed_devices_response');
+        }
+        for (const d of out['devices']) {
+            // `devicePubkey`, not `device_pubkey`: the server maps its columns before
+            // responding. The validator and the interface both named the column, so
+            // every real response was rejected as malformed — which nothing noticed,
+            // because nothing had ever called this against a live server.
+            if (!isObject(d) || !isRecipient(d['devicePubkey']) || !isUuid(d['id'])) {
+                throw new CourierError(200, 'malformed_devices_response');
+            }
+            // `thisMachine` DECIDES A REFUSAL, so it is checked like one.
+            //
+            // Absent or boolean, nothing else. `"true"`, `null` and `0` are all
+            // truthy-or-falsy in some reading, and any of them would make the
+            // pre-flight below treat a row as "not this machine" while ALSO treating
+            // the response as coming from a server that answers the question — so an
+            // ordinary rejoin would be refused locally, without a single request
+            // reaching the server that could have corrected it.
+            //
+            // Refused here rather than coerced: this value gates a decision no other
+            // check re-derives, and the pre-flight's own catch turns a malformed
+            // response into "go ahead and run the ceremony", which is the safe
+            // direction (raised in review).
+            if (d['thisMachine'] !== undefined && typeof d['thisMachine'] !== 'boolean') {
+                throw new CourierError(200, 'malformed_devices_response');
+            }
+        }
+        return out['devices'];
+    }
+    // B: fetch the blobs sealed to this device.
+    async fetchBlobs() {
+        const out = await this.call('GET', '/v1/courier');
+        if (!isObject(out) || !Array.isArray(out['blobs'])) {
+            throw new CourierError(200, 'malformed_courier_response');
+        }
+        for (const b of out['blobs']) {
+            if (!isObject(b) ||
+                !isUuid(b['id']) ||
+                !isUuid(b['operation_id']) ||
+                // Decoded and sealed to this device's key; a non-base64 body would be
+                // decoded to something shorter and handed to age.
+                !isBase64(b['ciphertext'])) {
+                throw new CourierError(200, 'malformed_courier_response');
+            }
+        }
+        return out['blobs'];
+    }
+    // B: ack a stored blob (deletes it server-side).
+    async ackBlob(blobId) {
+        await this.call('DELETE', `/v1/courier/${encodeURIComponent(blobId)}`);
+    }
+    // The account's vault, plus the two identifiers the client cannot derive.
+    //
+    // `vault` is null when the account has none yet — a normal first run, not an
+    // error: the identity fields are exactly what a create needs, so answering
+    // 404 would leave the client with nothing to seal against.
+    //
+    // Checked rather than cast, like getVault below and for the same reason:
+    // every field here is attacker-controlled if the server is, and account_id
+    // and vault_service_id go straight into the AEAD's additional data.
+    async getAccountVault() {
+        const out = await this.call('GET', '/v1/vault');
+        // Both identifiers are UUIDs and both go straight into the AEAD's
+        // additional data, so "a non-empty string" is not the check. A response
+        // that got this far with something else in these fields is malformed, and
+        // sealing under it would produce a vault that opens only for whatever sent
+        // it.
+        if (!isObject(out) || !isUuid(out['account_id']) || !isUuid(out['vault_service_id'])) {
+            throw new CourierError(200, 'malformed_vault_response');
+        }
+        const identity = {
+            accountId: out['account_id'],
+            vaultServiceId: out['vault_service_id'],
+        };
+        // `vault` must be PRESENT, with null the only way to say "none". Accepting
+        // a missing field as "no vault yet" turns a malformed 200 into a first run:
+        // the client would create a vault, under an identity it was handed by a
+        // response it could not parse, over whatever is actually stored.
+        if (!('vault' in out))
+            throw new CourierError(200, 'malformed_vault_response');
+        const vault = out['vault'];
+        if (vault === null)
+            return { ...identity, version: null };
+        if (!isObject(vault) ||
+            !isUuid(vault['vault_id']) ||
+            !isRevision(vault['revision']) ||
+            typeof vault['wrap_profile'] !== 'string' ||
+            typeof vault['etag'] !== 'string' ||
+            !isBase64(vault['ciphertext']) ||
+            !isKdfMeta(vault['kdf_meta']) ||
+            // Checked with the same predicate as `revision`, and for a related
+            // reason: the generation is compared and carried, and a value that is not
+            // a safe integer stops behaving like the number it is printed as. There
+            // is no fallback for an absent one — the server's column is NOT NULL, so
+            // a response without it is malformed, and treating it as generation 1
+            // would let a server that omits the field address this machine's slots.
+            !isRevision(vault['recovery_generation']) ||
+            // The list may be empty on a vault created before the wrap list existed.
+            // That is a real state of the stored data, and refusing it here would
+            // report "the server is malformed" for a vault the server stored
+            // correctly. What cannot be opened is decided where the opening happens.
+            !Array.isArray(vault['vdk_wraps']) ||
+            !vault['vdk_wraps'].every(isVdkWrap)) {
+            throw new CourierError(200, 'malformed_vault_response');
+        }
+        return { ...identity, version: vault };
+    }
+    // Store a wrapped version of the ACCOUNT's vault. Same contract as putVault
+    // below, minus the team: there is one vault per account now.
+    async putAccountVault(input) {
+        const out = await this.call('PUT', '/v1/vault', input);
+        if (!isObject(out) ||
+            !isRevision(out['revision']) ||
+            typeof out['etag'] !== 'string' ||
+            // Required, with no default. The caller compares this against the
+            // generation it bound into the slot it just uploaded, and a missing value
+            // filled in as 1 would make that comparison pass by construction — it
+            // would check the client's own assumption rather than what was recorded.
+            !isRevision(out['recovery_generation'])) {
+            throw new CourierError(200, 'malformed_vault_response');
+        }
+        return {
+            revision: out['revision'],
+            etag: out['etag'],
+            recovery_generation: out['recovery_generation'],
+        };
+    }
+    // Store a wrapped recovery version. Omit if_match to create the vault; pass the
+    // etag of the version you read to append. operation_id is the idempotency key —
+    // reusing it with a different payload is a 409, never a silent overwrite.
+    async putVault(teamId, input) {
+        const out = await this.call('PUT', `/v1/vault/${encodeURIComponent(teamId)}`, input);
+        if (!isObject(out) || !isRevision(out['revision']) || typeof out['etag'] !== 'string') {
+            throw new CourierError(200, 'malformed_vault_response');
+        }
+        return { revision: out['revision'], etag: out['etag'] };
+    }
+    // The current wrapped version. Device-approved only; the ciphertext is opaque
+    // to the server and every field here is attacker-controlled if the server is.
+    //
+    // Which is why it is checked rather than cast. The comment above already says
+    // the fields are attacker-controlled — a cast makes that sentence advisory. A
+    // missing revision or etag would flow into the append path as undefined and be
+    // compared as one, and a kdf_meta that is not an object would reach the key
+    // derivation as whatever it happens to be.
+    async getVault(teamId) {
+        const out = await this.call('GET', `/v1/vault/${encodeURIComponent(teamId)}`);
+        if (!isObject(out) ||
+            typeof out['vault_id'] !== 'string' ||
+            !isRevision(out['revision']) ||
+            typeof out['wrap_profile'] !== 'string' ||
+            typeof out['etag'] !== 'string' ||
+            !isBase64(out['ciphertext']) ||
+            !isKdfMeta(out['kdf_meta'])) {
+            throw new CourierError(200, 'malformed_vault_response');
+        }
+        return out;
+    }
+}