@graffiti-garden/implementation-decentralized 0.0.1

package/src/3-protocol/3-object-encoding-tests.ts

@@ -0,0 +1,269 @@
+import { assert, describe, expect, test } from "vitest";
+
+import {
+  encodeObjectUrl,
+  decodeObjectUrl,
+  ObjectEncoding,
+} from "./3-object-encoding.js";
+import { randomBytes } from "@noble/hashes/utils.js";
+import {
+  STRING_ENCODER_METHOD_BASE64URL,
+  StringEncoder,
+} from "../2-primitives/1-string-encoding.js";
+import { ContentAddresses } from "../2-primitives/2-content-addresses.js";
+import { ChannelAttestations } from "../2-primitives/3-channel-attestations.js";
+import {
+  ALLOWED_ATTESTATION_METHOD_HMAC_SHA256,
+  AllowedAttestations,
+} from "../2-primitives/4-allowed-attestations.js";
+import {
+  encode as dagCborEncode,
+  decode as dagCborDecode,
+} from "@ipld/dag-cbor";
+import {
+  maskGraffitiObject,
+  type GraffitiObjectBase,
+} from "@graffiti-garden/api";
+
+export function objectEncodingTests() {
+  describe("object Urls", () => {
+    for (const actor of [
+      "did:plc:alsdkjfkdjf",
+      "did:web:example.com/someone",
+      "did:example:123456789abcdefghi👻",
+    ]) {
+      test(`encodeObjectUrl encodes and decodes correctly with actor: ${actor}`, async () => {
+        const contentAddressBytes = randomBytes();
+        const contentAddress = await new StringEncoder().encode(
+          STRING_ENCODER_METHOD_BASE64URL,
+          contentAddressBytes,
+        );
+
+        const url = encodeObjectUrl(actor, contentAddress);
+        const decoded = decodeObjectUrl(url);
+        expect(decoded.actor).toBe(actor);
+        expect(decoded.contentAddress).toBe(contentAddress);
+      });
+    }
+
+    for (const invalidUrl of [
+      "http://example.com/not-an-object-url",
+      "graffiti:",
+      "graffiti:",
+      "graffiti:no-content-address",
+      "graffiti:too:many:parts",
+    ]) {
+      test(`Invalid Graffiti URL: ${invalidUrl}`, () => {
+        expect(() => decodeObjectUrl(invalidUrl)).toThrow();
+      });
+    }
+  });
+
+  describe("object encoding and validation", async () => {
+    const objectEncoding = new ObjectEncoding({
+      stringEncoder: new StringEncoder(),
+      allowedAttestations: new AllowedAttestations(),
+      channelAttestations: new ChannelAttestations(),
+      contentAddresses: new ContentAddresses(),
+    });
+
+    const value = {
+      message: "Hello world!",
+      nested: {
+        foo: {
+          bar: 42,
+        },
+      },
+      array: [1, "something 👻", { key: "value" }],
+    };
+    const channels = ["channel1👻", "channel2"];
+    const allowed = ["did:web:noone.example.com", "did:web:someone.else.com"];
+    const actor = "did:web:someone.example.com";
+
+    const { allowedTickets, tags, objectBytes, object } =
+      await objectEncoding.encode<{}>(
+        {
+          value,
+          channels,
+          allowed,
+        },
+        actor,
+      );
+    assert(Array.isArray(allowedTickets));
+
+    test("validate private", async () => {
+      await objectEncoding.validate(object, tags, objectBytes, {
+        allowedTickets,
+      });
+
+      for (const [index, recipient] of allowed.entries()) {
+        const copy = JSON.parse(JSON.stringify(object)) as GraffitiObjectBase;
+        const masked = maskGraffitiObject(copy, [], recipient);
+        await objectEncoding.validate(masked, tags, objectBytes, {
+          recipient: recipient,
+          allowedTicket: allowedTickets[index],
+          allowedIndex: index,
+        });
+      }
+    });
+
+    test("incorrect value", async () => {
+      await expect(
+        objectEncoding.validate(
+          {
+            ...object,
+            value: {
+              ...object.value,
+              extra: "field",
+            },
+          },
+          tags,
+          objectBytes,
+          {
+            allowedTickets,
+          },
+        ),
+      ).rejects.toThrow();
+    });
+
+    test("incorrect content address", async () => {
+      const url = encodeObjectUrl(
+        actor,
+        await new StringEncoder().encode(
+          STRING_ENCODER_METHOD_BASE64URL,
+          randomBytes(),
+        ),
+      );
+
+      await expect(
+        objectEncoding.validate(
+          {
+            ...object,
+            url,
+          },
+          [new TextEncoder().encode(url), ...tags.slice(1)],
+          objectBytes,
+          {
+            allowedTickets,
+          },
+        ),
+      ).rejects.toThrow();
+    });
+
+    test("incorrect bytes", async () => {
+      const wrongObjectBytes = randomBytes();
+      const correctContentAddress = decodeObjectUrl(object.url).contentAddress;
+      const correctContentAddressBytes = await new StringEncoder().decode(
+        correctContentAddress,
+      );
+      const contentAddresses = new ContentAddresses();
+      const contentAddressMethod = await contentAddresses.getMethod(
+        correctContentAddressBytes,
+      );
+      const wrongContentAddressBytes = await contentAddresses.register(
+        contentAddressMethod,
+        wrongObjectBytes,
+      );
+      const wrongContentAddress = await new StringEncoder().encode(
+        STRING_ENCODER_METHOD_BASE64URL,
+        wrongContentAddressBytes,
+      );
+      const wrongObjectUrl = encodeObjectUrl(actor, wrongContentAddress);
+
+      await expect(
+        objectEncoding.validate(
+          {
+            ...object,
+            url: wrongObjectUrl,
+          },
+          [new TextEncoder().encode(wrongObjectUrl), ...tags.slice(1)],
+          wrongObjectBytes,
+          {
+            allowedTickets,
+          },
+        ),
+      ).rejects.toThrow();
+    });
+
+    test("incorrect format", async () => {
+      const wrongData = {
+        not: "the expected format",
+      };
+      const wrongObjectBytes = dagCborEncode(wrongData);
+      const correctContentAddress = decodeObjectUrl(object.url).contentAddress;
+      const correctContentAddressBytes = await new StringEncoder().decode(
+        correctContentAddress,
+      );
+      const contentAddresses = new ContentAddresses();
+      const contentAddressMethod = await contentAddresses.getMethod(
+        correctContentAddressBytes,
+      );
+      const wrongContentAddressBytes = await contentAddresses.register(
+        contentAddressMethod,
+        wrongObjectBytes,
+      );
+      const wrongContentAddress = await new StringEncoder().encode(
+        STRING_ENCODER_METHOD_BASE64URL,
+        wrongContentAddressBytes,
+      );
+      const wrongObjectUrl = encodeObjectUrl(actor, wrongContentAddress);
+      await expect(
+        objectEncoding.validate(
+          {
+            ...object,
+            url: wrongObjectUrl,
+          },
+          [new TextEncoder().encode(wrongObjectUrl), ...tags.slice(1)],
+          wrongObjectBytes,
+          {
+            allowedTickets,
+          },
+        ),
+      ).rejects.toThrow();
+    });
+
+    test("missing allowed tickets", async () => {
+      await expect(
+        objectEncoding.validate(object, tags, objectBytes),
+      ).rejects.toThrow();
+    });
+
+    test("wrong allowed tickets", async () => {
+      const wrongAllowedTickets = await Promise.all(
+        allowedTickets.map(
+          async (ticket) =>
+            (
+              await new AllowedAttestations().attest(
+                ALLOWED_ATTESTATION_METHOD_HMAC_SHA256,
+                "did:web:not-the-right.actor",
+              )
+            ).ticket,
+        ),
+      );
+
+      await expect(
+        objectEncoding.validate(object, tags, objectBytes, {
+          allowedTickets: wrongAllowedTickets,
+        }),
+      ).rejects.toThrow();
+    });
+
+    test("wrong recipients", async () => {
+      const wrongRecipients = allowed.map((recipient) => recipient + "-wrong");
+
+      await expect(
+        objectEncoding.validate(
+          {
+            ...object,
+            allowed: wrongRecipients,
+          },
+          tags,
+          objectBytes,
+          {
+            allowedTickets,
+          },
+        ),
+      ).rejects.toThrow();
+    });
+  });
+}

package/src/3-protocol/3-object-encoding.ts

@@ -0,0 +1,396 @@
+import type { JSONSchema } from "json-schema-to-ts";
+import type {
+  GraffitiObject,
+  GraffitiObjectBase,
+  GraffitiPostObject,
+} from "@graffiti-garden/api";
+import type { ChannelAttestations } from "../2-primitives/3-channel-attestations";
+import type { AllowedAttestations } from "../2-primitives/4-allowed-attestations";
+import {
+  CONTENT_ADDRESS_METHOD_SHA256,
+  type ContentAddresses,
+} from "../2-primitives/2-content-addresses";
+import { randomBytes } from "@noble/hashes/utils.js";
+import {
+  encode as dagCborEncode,
+  decode as dagCborDecode,
+} from "@ipld/dag-cbor";
+import {
+  type infer as infer_,
+  array,
+  custom,
+  looseObject,
+  optional,
+  strictObject,
+} from "zod/mini";
+import { CHANNEL_ATTESTATION_METHOD_SHA256_ED25519 } from "../2-primitives/3-channel-attestations";
+import { ALLOWED_ATTESTATION_METHOD_HMAC_SHA256 } from "../2-primitives/4-allowed-attestations";
+import {
+  STRING_ENCODER_METHOD_BASE64URL,
+  type StringEncoder,
+} from "../2-primitives/1-string-encoding";
+
+// Objects have a max size of 32kb
+// If each channel and allowed actor takes 32 bytes
+// of space (i.e. they are hashed with 256 bit security)
+// then this means that the combined number of channels
+// and recipients of object has cannot exceed one thousand.
+// This seems like a reasonable limit and on par with
+// signal's group chat limit of 1000
+export const MAX_OBJECT_SIZE_BYTES = 32 * 1024;
+
+export class ObjectEncoding {
+  constructor(
+    protected readonly primitives: {
+      readonly stringEncoder: StringEncoder;
+      readonly channelAttestations: ChannelAttestations;
+      readonly allowedAttestations: AllowedAttestations;
+      readonly contentAddresses: ContentAddresses;
+    },
+  ) {}
+
+  async encode<Schema extends JSONSchema>(
+    partialObject: GraffitiPostObject<Schema>,
+    actor: string,
+  ): Promise<{
+    object: GraffitiObject<Schema>;
+    tags: Uint8Array[];
+    objectBytes: Uint8Array;
+    allowedTickets: Uint8Array[] | undefined;
+  }> {
+    // Clean out any undefineds
+    partialObject = cleanUndefined(partialObject);
+
+    // Create a verifiable attestation that the actor
+    // knows the included channels without
+    // directly revealing any channel to anyone who doesn't
+    // know the channel already
+    const channelAttestationAndPublicIds = await Promise.all(
+      partialObject.channels.map((channel) =>
+        this.primitives.channelAttestations.attest(
+          // TODO: get this from the DID document of the actor
+          CHANNEL_ATTESTATION_METHOD_SHA256_ED25519,
+          actor,
+          channel,
+        ),
+      ),
+    );
+    const channelAttestations = channelAttestationAndPublicIds.map(
+      (c) => c.attestation,
+    );
+    const channelPublicIds = channelAttestationAndPublicIds.map(
+      (c) => c.channelPublicId,
+    );
+
+    const objectData: infer_<typeof ObjectDataSchema> = {
+      [VALUE_PROPERTY]: partialObject.value,
+      [CHANNEL_ATTESTATIONS_PROPERTY]: channelAttestations,
+      [NONCE_PROPERTY]: randomBytes(32),
+    };
+
+    let allowedTickets: Uint8Array[] | undefined = undefined;
+
+    // If the object is private...
+    if (Array.isArray(partialObject.allowed)) {
+      // Create an attestation that the object's allowed list
+      // includes the given actors, without revealing the
+      // presence of an actor on the list to anyone except
+      // that actor themselves. Each actor will receive a
+      // "ticket" that they can use to verify their own membership
+      // on the allowed list.
+      const allowedAttestations = await Promise.all(
+        partialObject.allowed.map(async (allowedActor) =>
+          this.primitives.allowedAttestations.attest(
+            // TODO: get this from the DID document of the actor
+            ALLOWED_ATTESTATION_METHOD_HMAC_SHA256,
+            allowedActor,
+          ),
+        ),
+      );
+      objectData[ALLOWED_ATTESTATIONS_PROPERTY] = allowedAttestations.map(
+        (a) => a.attestation,
+      );
+      allowedTickets = allowedAttestations.map((a) => a.ticket);
+    }
+
+    // Encode the mixed JSON/binary data using CBOR
+    const objectBytes = dagCborEncode(objectData);
+    if (objectBytes.byteLength > MAX_OBJECT_SIZE_BYTES) {
+      throw new Error("The object is too large");
+    }
+
+    // Compute a public identifier (hash) of the object data
+    const objectContentAddressBytes =
+      await this.primitives.contentAddresses.register(
+        // TODO: get this from the DID document of the actor
+        CONTENT_ADDRESS_METHOD_SHA256,
+        objectBytes,
+      );
+    const objectContentAddress = await this.primitives.stringEncoder.encode(
+      STRING_ENCODER_METHOD_BASE64URL,
+      objectContentAddressBytes,
+    );
+    // Use it to compute the object's URL
+    const objectUrl = encodeObjectUrl(actor, objectContentAddress);
+
+    const tags = [new TextEncoder().encode(objectUrl), ...channelPublicIds];
+
+    const object: GraffitiObject<Schema> = {
+      value: partialObject.value,
+      channels: partialObject.channels,
+      url: objectUrl,
+      actor,
+      ...(partialObject.allowed
+        ? {
+            allowed: partialObject.allowed,
+          }
+        : {}),
+    } as GraffitiObject<Schema>;
+
+    // Return object URL and allowed secrets
+    return {
+      object,
+      tags,
+      objectBytes,
+      allowedTickets,
+    };
+  }
+
+  async validate(
+    object: GraffitiObjectBase,
+    tags: Uint8Array[],
+    objectBytes: Uint8Array,
+    privateObjectInfo?:
+      | {
+          recipient: string;
+          allowedTicket: Uint8Array;
+          allowedIndex: number;
+        }
+      | {
+          allowedTickets: Uint8Array[];
+        },
+  ): Promise<void> {
+    if (objectBytes.byteLength > MAX_OBJECT_SIZE_BYTES) {
+      throw new Error("Object is too big");
+    }
+    const { actor, contentAddress } = decodeObjectUrl(object.url);
+    if (actor !== object.actor) {
+      throw new Error("Object actor does not match URL actor");
+    }
+
+    const objectUrlTag = tags.at(0);
+    if (!objectUrlTag) {
+      throw new Error("No object URL tag");
+    }
+    if (new TextDecoder().decode(objectUrlTag) !== object.url) {
+      throw new Error("Object URL tag does not match object URL");
+    }
+    const channelPublicIds = tags.slice(1);
+
+    // Make sure the object content address matches the object content
+    const contentAddressBytes =
+      await this.primitives.stringEncoder.decode(contentAddress);
+    const contentAddressMethod =
+      await this.primitives.contentAddresses.getMethod(contentAddressBytes);
+    const expectedContentAddress =
+      await this.primitives.contentAddresses.register(
+        contentAddressMethod,
+        objectBytes,
+      );
+    if (
+      expectedContentAddress.length !== contentAddressBytes.length ||
+      !expectedContentAddress.every((b, i) => b === contentAddressBytes[i])
+    ) {
+      throw new Error("Content address is invalid");
+    }
+
+    // Convert the raw object data from CBOR
+    // back to a javascript object
+    const objectDataUnknown = dagCborDecode(objectBytes);
+    const objectData = ObjectDataSchema.parse(objectDataUnknown);
+
+    // And extract the values
+    const value = objectData[VALUE_PROPERTY];
+    const channelAttestations = objectData[CHANNEL_ATTESTATIONS_PROPERTY];
+    const allowedAttestations = objectData[ALLOWED_ATTESTATIONS_PROPERTY];
+
+    // Validate that the object's value matches
+    const valueBytes = dagCborEncode(value);
+    const expectedValueBytes = dagCborEncode(object.value);
+    if (
+      valueBytes.length !== expectedValueBytes.length ||
+      !valueBytes.every((b, i) => b === expectedValueBytes[i])
+    ) {
+      throw new Error("Object value does not match storage value");
+    }
+
+    // Validate the object's channels
+    if (channelAttestations.length !== channelPublicIds.length) {
+      throw new Error("Not as many channel attestations and public ids");
+    }
+    for (const [index, attestation] of channelAttestations.entries()) {
+      const channelPublicId = channelPublicIds[index];
+      const isValid = await this.primitives.channelAttestations.validate(
+        attestation,
+        actor,
+        channelPublicId,
+      );
+      if (!isValid) {
+        throw new Error("Invalid channel attestation");
+      }
+    }
+    if (object.channels.length) {
+      // If any channels are included, they all must be included
+      if (object.channels.length !== channelPublicIds.length) {
+        throw new Error(
+          "Number of claimed channels does not match attestations/public IDs",
+        );
+      }
+      const channelAttestationMethod =
+        await this.primitives.channelAttestations.getMethod(
+          channelPublicIds[0],
+        );
+      const expectedChannelPublicIds = await Promise.all(
+        object.channels.map((channel) =>
+          this.primitives.channelAttestations.register(
+            channelAttestationMethod,
+            channel,
+          ),
+        ),
+      );
+      for (const [
+        index,
+        expectedPublicId,
+      ] of expectedChannelPublicIds.entries()) {
+        const actualPublicId = channelPublicIds[index];
+        if (
+          expectedPublicId.length !== actualPublicId.length ||
+          !expectedPublicId.every((b, i) => b === actualPublicId[i])
+        ) {
+          throw new Error("Channel public id does not match expected");
+        }
+      }
+    }
+
+    // Validate the recipient
+    if (privateObjectInfo) {
+      if (!allowedAttestations) {
+        throw new Error("Object is public but thought to be private");
+      }
+
+      let recipients: string[];
+      let allowedTickets: Uint8Array[];
+      let attestations: Uint8Array[];
+      if ("recipient" in privateObjectInfo) {
+        recipients = [privateObjectInfo.recipient];
+        allowedTickets = [privateObjectInfo.allowedTicket];
+        attestations = allowedAttestations.filter(
+          (_, i) => i === privateObjectInfo.allowedIndex,
+        );
+      } else {
+        recipients = [...(object.allowed ?? [])];
+        allowedTickets = privateObjectInfo.allowedTickets;
+        attestations = allowedAttestations;
+      }
+
+      // All recipients must be in the allowed list
+      if (recipients.length !== object.allowed?.length) {
+        throw new Error("Recipient count does not match object allowed list");
+      }
+      if (!recipients.every((r) => object.allowed?.includes(r))) {
+        throw new Error("Recipient not in object allowed list");
+      }
+
+      for (const [index, recipient] of recipients.entries()) {
+        const allowedTicket = allowedTickets.at(index);
+        const allowedAttestation = attestations.at(index);
+        if (!allowedTicket) {
+          throw new Error("Missing allowed ticket for recipient");
+        }
+        if (!allowedAttestation) {
+          throw new Error("Missing allowed attestation for recipient");
+        }
+        const isValid = await this.primitives.allowedAttestations.validate(
+          allowedAttestation,
+          recipient,
+          allowedTicket,
+        );
+
+        if (!isValid) {
+          throw new Error("Invalid allowed attestation for recipient");
+        }
+      }
+    } else if (allowedAttestations) {
+      throw new Error("Object is private but no recipient info provided");
+    }
+  }
+}
+
+// A compact data representation of the object data
+const VALUE_PROPERTY = "v";
+const CHANNEL_ATTESTATIONS_PROPERTY = "c";
+const ALLOWED_ATTESTATIONS_PROPERTY = "a";
+const NONCE_PROPERTY = "n";
+
+const Uint8ArraySchema = custom<Uint8Array>(
+  (v): v is Uint8Array => v instanceof Uint8Array,
+);
+
+const ObjectDataSchema = strictObject({
+  [VALUE_PROPERTY]: looseObject({}),
+  [CHANNEL_ATTESTATIONS_PROPERTY]: array(Uint8ArraySchema),
+  [ALLOWED_ATTESTATIONS_PROPERTY]: optional(array(Uint8ArraySchema)),
+  [NONCE_PROPERTY]: Uint8ArraySchema,
+});
+
+export const GRAFFITI_OBJECT_URL_PREFIX = "graffiti:";
+
+// Methods to encode and decode object URLs
+export function encodeObjectUrlComponent(value: string) {
+  const replaced = value.replace(/:/g, "!").replace(/\//g, "~");
+  return encodeURIComponent(replaced);
+}
+export function decodeObjectUrlComponent(value: string) {
+  const decoded = decodeURIComponent(value);
+  return decoded.replace(/!/g, ":").replace(/~/g, "/");
+}
+export function encodeObjectUrl(actor: string, contentAddress: string) {
+  return `${GRAFFITI_OBJECT_URL_PREFIX}${encodeObjectUrlComponent(actor)}:${encodeObjectUrlComponent(contentAddress)}`;
+}
+export function decodeObjectUrl(objectUrl: string) {
+  if (!objectUrl.startsWith(GRAFFITI_OBJECT_URL_PREFIX)) {
+    throw new Error("Invalid object URL");
+  }
+
+  const rest = objectUrl.slice(GRAFFITI_OBJECT_URL_PREFIX.length);
+  const parts = rest.split(":");
+
+  if (parts.length !== 2) {
+    throw new Error("Invalid object URL format");
+  }
+
+  const [actor, contentAddress] = parts;
+
+  return {
+    actor: decodeObjectUrlComponent(actor),
+    contentAddress: decodeObjectUrlComponent(contentAddress),
+  };
+}
+
+function cleanUndefined(value: any): any {
+  if (value === undefined) return null;
+
+  if (Array.isArray(value)) {
+    return value.map(cleanUndefined);
+  }
+
+  if (typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => [k, cleanUndefined(v)]),
+    );
+  }
+
+  return value;
+}