@naughtbot/e2ee-payloads 0.9.0 → 0.10.0

package/src/index.test.ts

@@ -27,6 +27,12 @@ import type {
   MailboxGpgDecryptResponseSuccessV1,
   MailboxCaptchaRequestPayloadV1,
   MailboxCaptchaResponsePayloadV1,
+  MailboxKeyInventoryApprovalBindingV1,
+  MailboxKeyInventoryEntryV1,
+  MailboxKeyInventoryRequestPayloadV1,
+  MailboxKeyInventoryResponsePayloadV1,
+  MailboxKeyInventoryResponseRejectedV1,
+  MailboxKeyInventoryResponseSharedV1,
   MailboxLinkApprovalPayloadV1,
   MailboxLinkRejectionPayloadV1,
   MailboxLinkRequestPayloadV1,
@@ -37,6 +43,8 @@ import type {
   MailboxSshSignResponsePayloadV1,
   MailboxSshSignResponseSuccessV1,
   NaughtBotApprovalBindingV1,
+  PublicKeyAlgorithm,
+  PublicKeyFormat,
 } from "./index.ts";
 
 const captchaApprovalBindingProfile =
@@ -815,3 +823,263 @@ describe("KeyPurpose", () => {
     assert.ok(!(["ssh", "gpg", "age", "pkcs11"] as string[]).includes(bad));
   });
 });
+
+interface KeyInventoryVectorsFixture {
+  canonical_owner: string;
+  approval_binding_format: string;
+  empty_key_list_digest: string;
+  key_list_digest: string;
+  canonical_keys_json: string;
+  canonical_binding_json: string;
+  binding: MailboxKeyInventoryApprovalBindingV1;
+  keys: MailboxKeyInventoryEntryV1[];
+}
+
+function loadKeyInventoryVectors(): KeyInventoryVectorsFixture {
+  return JSON.parse(
+    readFileSync(
+      new URL("../../fixtures/key-inventory-v1-vectors.json", import.meta.url),
+      "utf8",
+    ),
+  ) as KeyInventoryVectorsFixture;
+}
+
+describe("MailboxKeyInventoryRequestPayloadV1", () => {
+  it("round-trips a purpose-filtered request including pkcs11", () => {
+    const request: MailboxKeyInventoryRequestPayloadV1 = {
+      purposes: ["ssh", "gpg", "age", "pkcs11"],
+      source_info: { hostname: "work-laptop" },
+    };
+    const json = JSON.stringify(request);
+    assert.ok(json.includes('"purposes":["ssh","gpg","age","pkcs11"]'));
+
+    const parsed = JSON.parse(json) as MailboxKeyInventoryRequestPayloadV1;
+    assert.equal(parsed.purposes.length, 4);
+    assert.equal(parsed.purposes[3], "pkcs11");
+  });
+});
+
+// Regression coverage for the closed canonical key-format enums. The
+// PublicKeyAlgorithm / PublicKeyFormat unions are closed sets; an unknown
+// member (e.g. "rsa" / "spki_der") must be a `tsc` error rather than a
+// silent accept. Casting through `unknown` documents the intentionally bad
+// runtime value.
+describe("canonical key-format enums", () => {
+  it("PublicKeyAlgorithm is a closed set", () => {
+    const known: PublicKeyAlgorithm[] = ["ecdsa_p256", "ed25519", "x25519"];
+    for (const algorithm of known) {
+      assert.ok(["ecdsa_p256", "ed25519", "x25519"].includes(algorithm));
+    }
+    const bad = "rsa" as unknown as PublicKeyAlgorithm;
+    assert.ok(!(known as string[]).includes(bad));
+  });
+
+  it("PublicKeyFormat is a closed set", () => {
+    const known: PublicKeyFormat[] = ["sec1_compressed", "raw_32"];
+    for (const format of known) {
+      assert.ok(["sec1_compressed", "raw_32"].includes(format));
+    }
+    const bad = "spki_der" as unknown as PublicKeyFormat;
+    assert.ok(!(known as string[]).includes(bad));
+  });
+
+  it("rejects public_key_hex inconsistent with algorithm + format", () => {
+    // The schema carries the relaxed `^(02|03)?[0-9a-f]{64}$` pattern;
+    // receivers MUST additionally enforce the per-algorithm layout. This
+    // mirrors the Go validateCanonicalKeyMaterial helper.
+    const ok: MailboxKeyInventoryEntryV1 = {
+      purpose: "ssh",
+      id: "ssh-key-0001",
+      device_key_id: "se-handle-ssh-0001",
+      algorithm: "ecdsa_p256",
+      public_key_format: "sec1_compressed",
+      public_key_hex:
+        "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
+    };
+    assert.ok(canonicalKeyMaterialValid(ok));
+
+    // ecdsa_p256 with a 64-hex (raw_32-length) value is inconsistent.
+    assert.ok(
+      !canonicalKeyMaterialValid({
+        ...ok,
+        public_key_hex:
+          "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
+      }),
+    );
+    // ed25519 with a 66-hex (sec1-length) value is inconsistent.
+    assert.ok(
+      !canonicalKeyMaterialValid({
+        ...ok,
+        algorithm: "ed25519",
+        public_key_format: "raw_32",
+      }),
+    );
+    // algorithm/format pairing mismatch.
+    assert.ok(
+      !canonicalKeyMaterialValid({ ...ok, public_key_format: "raw_32" }),
+    );
+  });
+});
+
+function canonicalKeyMaterialValid(entry: MailboxKeyInventoryEntryV1): boolean {
+  const hex = entry.public_key_hex;
+  switch (entry.algorithm) {
+    case "ecdsa_p256":
+      return (
+        entry.public_key_format === "sec1_compressed" &&
+        hex.length === 66 &&
+        (hex.startsWith("02") || hex.startsWith("03"))
+      );
+    case "ed25519":
+    case "x25519":
+      return entry.public_key_format === "raw_32" && hex.length === 64;
+    default:
+      return false;
+  }
+}
+
+describe("MailboxKeyInventoryResponsePayloadV1", () => {
+  it("discriminates shared vs rejected via status", () => {
+    const fixture = loadKeyInventoryVectors();
+
+    const shared: MailboxKeyInventoryResponseSharedV1 = {
+      status: "shared",
+      request_envelope_id: "11111111-2222-4333-8444-555555555555",
+      keys: fixture.keys,
+      approval_binding: fixture.binding,
+      approval_binding_bytes: Buffer.from(
+        fixture.canonical_binding_json,
+        "utf8",
+      ).toString("base64"),
+      approval_binding_format: "key-inventory-approval-binding/v1+json",
+      approval_signature: Buffer.from(
+        "key-inventory-approval-signature",
+        "utf8",
+      ).toString("base64"),
+      approval_signature_algorithm: "ES256",
+      approval_proof: approvalProofFixture(),
+    };
+    const sharedResp = JSON.parse(
+      JSON.stringify(shared),
+    ) as MailboxKeyInventoryResponsePayloadV1;
+    assert.equal(sharedResp.status, "shared");
+    if (sharedResp.status === "shared") {
+      assert.equal(sharedResp.keys.length, 4);
+      assert.equal(
+        Buffer.from(sharedResp.approval_binding_bytes, "base64").toString(
+          "utf8",
+        ),
+        fixture.canonical_binding_json,
+      );
+    }
+
+    const rejected: MailboxKeyInventoryResponseRejectedV1 = {
+      status: "rejected",
+      request_envelope_id: "11111111-2222-4333-8444-555555555555",
+      error_code: 1,
+      error_message: "User rejected the key inventory request",
+    };
+    const rejectedResp = JSON.parse(
+      JSON.stringify(rejected),
+    ) as MailboxKeyInventoryResponsePayloadV1;
+    assert.equal(rejectedResp.status, "rejected");
+    if (rejectedResp.status === "rejected") {
+      assert.equal(rejectedResp.error_code, 1);
+    }
+  });
+});
+
+describe("MailboxKeyInventoryEntryV1 protocol metadata", () => {
+  it("round-trips SSH / GPG / age / PKCS#11 export metadata", () => {
+    const fixture = loadKeyInventoryVectors();
+    const [ssh, gpg, age, pkcs11] = fixture.keys;
+
+    const sshParsed = JSON.parse(
+      JSON.stringify(ssh),
+    ) as MailboxKeyInventoryEntryV1;
+    assert.equal(sshParsed.purpose, "ssh");
+    assert.equal(
+      sshParsed.ssh?.ssh_key_type,
+      "sk-ecdsa-sha2-nistp256@openssh.com",
+    );
+    assert.ok(sshParsed.ssh?.ssh_fingerprint?.startsWith("SHA256:"));
+    assert.equal(sshParsed.ssh?.ssh_sk_flags, 5);
+
+    const gpgParsed = JSON.parse(
+      JSON.stringify(gpg),
+    ) as MailboxKeyInventoryEntryV1;
+    assert.equal(
+      gpgParsed.gpg?.fingerprint_hex,
+      "A1D597197F5C1DACB3E3BB7862BF2FC536D562FF",
+    );
+    assert.ok(gpgParsed.gpg?.armored_public_key?.includes("PGP PUBLIC KEY"));
+    assert.equal(
+      gpgParsed.gpg?.encryption_public_key_hex,
+      "03b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
+    );
+
+    const ageParsed = JSON.parse(
+      JSON.stringify(age),
+    ) as MailboxKeyInventoryEntryV1;
+    assert.ok(ageParsed.age?.age_recipient?.startsWith("age1nb1"));
+
+    const pkcs11Parsed = JSON.parse(
+      JSON.stringify(pkcs11),
+    ) as MailboxKeyInventoryEntryV1;
+    assert.equal(pkcs11Parsed.pkcs11?.cka_key_type, "CKK_EC");
+    assert.equal(pkcs11Parsed.pkcs11?.can_sign, true);
+    assert.equal(pkcs11Parsed.pkcs11?.can_derive, false);
+  });
+});
+
+describe("MailboxKeyInventoryApprovalBindingV1", () => {
+  it("agrees with Go and Swift on the canonical key-inventory vectors", () => {
+    const fixture = loadKeyInventoryVectors();
+    assert.equal(
+      fixture.canonical_owner,
+      "NaughtBot/e2ee-payloads fixtures/key-inventory-v1-vectors.json",
+    );
+    assert.equal(fixture.keys.length, 4);
+
+    // SHA-256 over the canonical keys JSON MUST equal key_list_digest.
+    const digest =
+      "sha256:" +
+      createHash("sha256")
+        .update(fixture.canonical_keys_json, "utf8")
+        .digest("hex");
+    assert.equal(digest, fixture.key_list_digest);
+    assert.equal(fixture.binding.key_list_digest, fixture.key_list_digest);
+
+    // The empty key list digest is SHA-256 of the JSON array "[]".
+    const emptyDigest =
+      "sha256:" + createHash("sha256").update("[]", "utf8").digest("hex");
+    assert.equal(emptyDigest, fixture.empty_key_list_digest);
+
+    // Every fixture entry's canonical key material is internally consistent.
+    for (const entry of fixture.keys) {
+      assert.ok(
+        canonicalKeyMaterialValid(entry),
+        `fixture key ${entry.purpose} failed canonical validation`,
+      );
+    }
+
+    // Re-stringifying the fixture binding object (whose properties are
+    // already in lexicographic order) reproduces the canonical signed bytes.
+    assert.equal(
+      JSON.stringify(fixture.binding),
+      fixture.canonical_binding_json,
+    );
+
+    const bindingParsed = JSON.parse(
+      JSON.stringify(fixture.binding),
+    ) as MailboxKeyInventoryApprovalBindingV1;
+    assert.equal(bindingParsed.version, "key-inventory-approval-binding/v1");
+    assert.equal(bindingParsed.request_envelope_type, "key_inventory_request");
+    assert.deepEqual(bindingParsed.requested_purposes, [
+      "ssh",
+      "gpg",
+      "age",
+      "pkcs11",
+    ]);
+  });
+});

package/src/index.ts

@@ -59,6 +59,11 @@ export type MailboxPkcs11DeriveResponsePayloadV1 = components["schemas"]["Mailbo
 export type MailboxPkcs11DeriveResponseSuccessV1 = components["schemas"]["MailboxPkcs11DeriveResponseSuccessV1"];
 export type MailboxPkcs11DeriveResponseFailureV1 = components["schemas"]["MailboxPkcs11DeriveResponseFailureV1"];
 export type KeyPurpose = components["schemas"]["KeyPurpose"];
+export type PublicKeyAlgorithm = components["schemas"]["PublicKeyAlgorithm"];
+export type PublicKeyFormat = components["schemas"]["PublicKeyFormat"];
+export type Sec1CompressedPublicKeyHex = components["schemas"]["Sec1CompressedPublicKeyHex"];
+export type Raw32PublicKeyHex = components["schemas"]["Raw32PublicKeyHex"];
+export type CanonicalPublicKeyHex = components["schemas"]["CanonicalPublicKeyHex"];
 export type MailboxEnrollRequestPayloadV1 = components["schemas"]["MailboxEnrollRequestPayloadV1"];
 export type MailboxEnrollResponsePayloadV1 = components["schemas"]["MailboxEnrollResponsePayloadV1"];
 export type MailboxEnrollResponseApprovedV1 = components["schemas"]["MailboxEnrollResponseApprovedV1"];
@@ -86,3 +91,14 @@ export type MailboxFirstPartyPrivilegedActionRequestV1 = components["schemas"]["
 export type MailboxFirstPartyRequestPayloadV1 = components["schemas"]["MailboxFirstPartyRequestPayloadV1"];
 export type MailboxFirstPartyPrivilegedActionDecisionBindingV1 = components["schemas"]["MailboxFirstPartyPrivilegedActionDecisionBindingV1"];
 export type MailboxFirstPartyResponsePayloadV1 = components["schemas"]["MailboxFirstPartyResponsePayloadV1"];
+export type MailboxKeyInventoryRequestPayloadV1 = components["schemas"]["MailboxKeyInventoryRequestPayloadV1"];
+export type MailboxKeyInventoryApprovalBindingFormat = components["schemas"]["MailboxKeyInventoryApprovalBindingFormat"];
+export type MailboxKeyInventoryEntryV1 = components["schemas"]["MailboxKeyInventoryEntryV1"];
+export type KeyInventorySshMetadataV1 = components["schemas"]["KeyInventorySshMetadataV1"];
+export type KeyInventoryGpgMetadataV1 = components["schemas"]["KeyInventoryGpgMetadataV1"];
+export type KeyInventoryAgeMetadataV1 = components["schemas"]["KeyInventoryAgeMetadataV1"];
+export type KeyInventoryPkcs11MetadataV1 = components["schemas"]["KeyInventoryPkcs11MetadataV1"];
+export type MailboxKeyInventoryResponseSharedV1 = components["schemas"]["MailboxKeyInventoryResponseSharedV1"];
+export type MailboxKeyInventoryResponseRejectedV1 = components["schemas"]["MailboxKeyInventoryResponseRejectedV1"];
+export type MailboxKeyInventoryResponsePayloadV1 = components["schemas"]["MailboxKeyInventoryResponsePayloadV1"];
+export type MailboxKeyInventoryApprovalBindingV1 = components["schemas"]["MailboxKeyInventoryApprovalBindingV1"];