@graffiti-garden/implementation-decentralized 0.0.1

package/src/1-services/utilities.ts

@@ -0,0 +1,65 @@
+import {
+  GraffitiErrorCursorExpired,
+  GraffitiErrorForbidden,
+  GraffitiErrorNotFound,
+  GraffitiErrorTooLarge,
+} from "@graffiti-garden/api";
+
+const SERVICE_ENDPOINT_PREFIX_HTTPS = "https://";
+export function verifyHTTPSEndpoint(endpoint: string): void {
+  if (!endpoint.startsWith(SERVICE_ENDPOINT_PREFIX_HTTPS)) {
+    throw new Error("Unrecognized storage bucket endpoint type");
+  }
+}
+
+export async function getAuthorizationEndpoint(
+  serviceEndpoint: string,
+): Promise<string> {
+  verifyHTTPSEndpoint(serviceEndpoint);
+  const authUrl = `${serviceEndpoint}/auth`;
+
+  const response = await fetch(authUrl);
+  if (!response.ok) {
+    throw new Error("Failed to get storage bucket authorization endpoint");
+  }
+  return await response.text();
+}
+
+export class GraffitiErrorUnauthorized extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorUnauthorized";
+    Object.setPrototypeOf(this, GraffitiErrorUnauthorized.prototype);
+  }
+}
+
+export async function fetchWithErrorHandling(
+  ...args: Parameters<typeof fetch>
+) {
+  const response = await fetch(...args);
+
+  if (!response.ok) {
+    let errorText: string;
+    try {
+      errorText = await response.text();
+    } catch {
+      errorText = response.statusText;
+    }
+
+    if (response.status === 401) {
+      throw new GraffitiErrorUnauthorized(errorText);
+    } else if (response.status === 403) {
+      throw new GraffitiErrorForbidden(errorText);
+    } else if (response.status === 404) {
+      throw new GraffitiErrorNotFound(errorText);
+    } else if (response.status === 410) {
+      throw new GraffitiErrorCursorExpired(errorText);
+    } else if (response.status === 413) {
+      throw new GraffitiErrorTooLarge(errorText);
+    } else {
+      throw new Error(errorText);
+    }
+  }
+
+  return response;
+}

package/src/2-primitives/1-string-encoding-tests.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import {
+  STRING_ENCODER_METHOD_BASE64URL,
+  StringEncoder,
+} from "./1-string-encoding";
+import { randomBytes } from "@noble/hashes/utils.js";
+
+export function stringEncodingTests() {
+  describe("String encoding tests", () => {
+    const stringEncodingMethods = [STRING_ENCODER_METHOD_BASE64URL];
+    const stringEncoder = new StringEncoder();
+
+    test("Invalid string decoding method", async () => {
+      const bytes = randomBytes();
+      await expect(() =>
+        stringEncoder.encode("invalid-method", bytes),
+      ).rejects.toThrow();
+    });
+
+    for (const method of stringEncodingMethods) {
+      describe(`String Encoding Method: ${method}`, () => {
+        test("encodes and decodes strings correctly", async () => {
+          const bytes = randomBytes();
+          const encoded = await stringEncoder.encode(method, bytes);
+          const decoded = await stringEncoder.decode(encoded);
+
+          expect(decoded).toEqual(bytes);
+          expect(decoded).not.toEqual(randomBytes());
+        });
+      });
+    }
+  });
+}

package/src/2-primitives/1-string-encoding.ts

@@ -0,0 +1,33 @@
+// https://github.com/multiformats/multibase/blob/master/multibase.csv
+export const STRING_ENCODER_METHOD_BASE64URL = "base64url";
+const STRING_ENCODER_PREFIX_BASE64URL = "u";
+
+export class StringEncoder {
+  async encode(method: string, bytes: Uint8Array): Promise<string> {
+    if (method !== STRING_ENCODER_METHOD_BASE64URL) {
+      throw new Error(`Unsupported string encoding method: ${method}`);
+    }
+    // Convert it to base64
+    const base64 = btoa(String.fromCodePoint(...bytes));
+    // Make sure it is url safe
+    const encoded = base64
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/\=+$/, "");
+    // Append method prefix
+    return STRING_ENCODER_PREFIX_BASE64URL + encoded;
+  }
+
+  async decode(base64Url: string): Promise<Uint8Array> {
+    if (!base64Url.startsWith(STRING_ENCODER_PREFIX_BASE64URL)) {
+      throw new Error(`Unsupported string encoding prefix: ${base64Url[0]}`);
+    }
+    base64Url = base64Url.slice(1);
+    // Undo url-safe base64
+    let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+    // Add padding if necessary
+    while (base64.length % 4 !== 0) base64 += "=";
+    // Decode
+    return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+  }
+}

package/src/2-primitives/2-content-addresses-tests.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import {
+  CONTENT_ADDRESS_METHOD_SHA256,
+  ContentAddresses,
+} from "./2-content-addresses";
+import { randomBytes } from "@noble/hashes/utils.js";
+
+export function contentAddressesTests() {
+  describe("Content Address Tests", () => {
+    const contentAddressMethods = [CONTENT_ADDRESS_METHOD_SHA256];
+    const contentAddresses = new ContentAddresses();
+
+    test("Invalid content address method", async () => {
+      const bytes = randomBytes();
+      await expect(() =>
+        contentAddresses.register("invalid-method", bytes),
+      ).rejects.toThrow();
+    });
+
+    for (const method of contentAddressMethods) {
+      describe(`Content Address Method: ${method}`, () => {
+        test("idempotent addresses", async () => {
+          const bytes = randomBytes();
+          const address1 = await contentAddresses.register(method, bytes);
+          const address2 = await contentAddresses.register(method, bytes);
+          expect(address1).toEqual(address2);
+        });
+
+        test("unique adddresses", async () => {
+          const bytes1 = randomBytes();
+          const bytes2 = randomBytes();
+          const address1 = await contentAddresses.register(method, bytes1);
+          const address2 = await contentAddresses.register(method, bytes2);
+          expect(address1).not.toEqual(address2);
+        });
+
+        test("get method", async () => {
+          const bytes = randomBytes();
+          const address = await contentAddresses.register(method, bytes);
+          const retrievedMethod = await contentAddresses.getMethod(address);
+          expect(retrievedMethod).toEqual(method);
+        });
+      });
+    }
+  });
+}

package/src/2-primitives/2-content-addresses.ts

@@ -0,0 +1,42 @@
+import { sha256 } from "@noble/hashes/webcrypto.js";
+
+export const CONTENT_ADDRESS_METHOD_SHA256 = "sha2-256";
+
+// Multihash code and length for SHA2-256
+// https://multiformats.io/multihash/#sha2-256---256-bits-aka-sha256
+export const MULTIHASH_CODE_SHA256 = 0x12;
+export const MULTIHASH_LENGTH_SHA256 = 32;
+
+export class ContentAddresses {
+  async register(
+    contentAddressMethod: string,
+    data: Uint8Array,
+  ): Promise<Uint8Array> {
+    if (contentAddressMethod !== CONTENT_ADDRESS_METHOD_SHA256) {
+      throw new Error(
+        `Unsupported content address method: ${contentAddressMethod}`,
+      );
+    }
+
+    const hash = await sha256(data);
+
+    const prefixedHash = new Uint8Array(2 + hash.length);
+    prefixedHash[0] = MULTIHASH_CODE_SHA256;
+    prefixedHash[1] = MULTIHASH_LENGTH_SHA256;
+    prefixedHash.set(hash, 2);
+
+    return prefixedHash;
+  }
+
+  async getMethod(contentAddress: Uint8Array): Promise<string> {
+    if (
+      contentAddress[0] === MULTIHASH_CODE_SHA256 &&
+      contentAddress[1] === MULTIHASH_LENGTH_SHA256 &&
+      contentAddress.length === 2 + MULTIHASH_LENGTH_SHA256
+    ) {
+      return CONTENT_ADDRESS_METHOD_SHA256;
+    } else {
+      throw new Error(`Unrecognized content address format.`);
+    }
+  }
+}

package/src/2-primitives/3-channel-attestations-tests.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "vitest";
+import {
+  CHANNEL_ATTESTATION_METHOD_SHA256_ED25519,
+  ChannelAttestations,
+} from "./3-channel-attestations";
+import { randomBytes } from "@noble/hashes/utils.js";
+import {
+  StringEncoder,
+  STRING_ENCODER_METHOD_BASE64URL,
+} from "./1-string-encoding";
+
+export function channelAttestationTests() {
+  describe("Channel Attestation Tests", () => {
+    const allowedAttestationMethods = [
+      CHANNEL_ATTESTATION_METHOD_SHA256_ED25519,
+    ];
+    const channelAttestations = new ChannelAttestations();
+
+    async function randomActor() {
+      const bytes = randomBytes();
+      const str = await new StringEncoder().encode(
+        STRING_ENCODER_METHOD_BASE64URL,
+        bytes,
+      );
+      return `did:web:${str}.com`;
+    }
+    async function randomChannel() {
+      const bytes = randomBytes();
+      return await new StringEncoder().encode(
+        STRING_ENCODER_METHOD_BASE64URL,
+        bytes,
+      );
+    }
+
+    test("Invalid attestation method", async () => {
+      const actor = await randomActor();
+      await expect(() =>
+        channelAttestations.register("invalid-method", actor),
+      ).rejects.toThrow();
+    });
+
+    for (const method of allowedAttestationMethods) {
+      describe(`Attestation Method: ${method}`, () => {
+        test("get method", async () => {
+          const channel = await randomChannel();
+          const publicId = await channelAttestations.register(method, channel);
+          const methodReturned = await channelAttestations.getMethod(publicId);
+          expect(methodReturned).toEqual(method);
+        });
+
+        test("Idempotent public Ids", async () => {
+          const channel = await randomChannel();
+          const publicId1 = await channelAttestations.register(method, channel);
+          const publicId2 = await channelAttestations.register(method, channel);
+          expect(publicId1).toEqual(publicId2);
+        });
+
+        test("Unique public ids", async () => {
+          const channel1 = await randomChannel();
+          const channel2 = await randomChannel();
+          const publicId1 = await channelAttestations.register(
+            method,
+            channel1,
+          );
+          const publicId2 = await channelAttestations.register(
+            method,
+            channel2,
+          );
+          expect(publicId1).not.toEqual(publicId2);
+        });
+
+        test("Valid attestation", async () => {
+          const actor = await randomActor();
+          const channel = await randomChannel();
+          const { attestation, channelPublicId } =
+            await channelAttestations.attest(method, actor, channel);
+          const isValid = await channelAttestations.validate(
+            attestation,
+            actor,
+            channelPublicId,
+          );
+          expect(isValid).toBe(true);
+
+          const channelPublicIdSeperate = await channelAttestations.register(
+            method,
+            channel,
+          );
+          expect(channelPublicId).toEqual(channelPublicIdSeperate);
+        });
+
+        test("Invalid attestation with wrong actor", async () => {
+          const actor = await randomActor();
+          const wrongActor = await randomActor();
+          const channel = await randomChannel();
+          const { attestation, channelPublicId } =
+            await channelAttestations.attest(method, actor, channel);
+          const isValid = await channelAttestations.validate(
+            attestation,
+            wrongActor,
+            channelPublicId,
+          );
+          expect(isValid).toBe(false);
+        });
+
+        test("Invalid attestation with wrong channel", async () => {
+          const actor = await randomActor();
+          const channel = await randomChannel();
+          const wrongChannel = await randomChannel();
+          const { attestation, channelPublicId } =
+            await channelAttestations.attest(method, actor, channel);
+          const wrongChannelPublicId = await channelAttestations.register(
+            method,
+            wrongChannel,
+          );
+          const isValid = await channelAttestations.validate(
+            attestation,
+            actor,
+            wrongChannelPublicId,
+          );
+          expect(isValid).toBe(false);
+        });
+      });
+    }
+  });
+}

package/src/2-primitives/3-channel-attestations.ts

@@ -0,0 +1,95 @@
+import {
+  getPublicKeyAsync,
+  signAsync,
+  verifyAsync,
+  hashes,
+} from "@noble/ed25519";
+import { sha256, sha512 } from "@noble/hashes/webcrypto.js";
+hashes.sha512Async = sha512;
+
+export const CHANNEL_ATTESTATION_METHOD_SHA256_ED25519 = "pk:sha2-256+ed25519";
+const CHANNEL_ATTESTATION_METHOD_PREFIX_SHA256_ED25519 = 0;
+
+export class ChannelAttestations {
+  async register(
+    channelAttestationMethod: string,
+    channel: string,
+  ): Promise<Uint8Array> {
+    if (
+      channelAttestationMethod !== CHANNEL_ATTESTATION_METHOD_SHA256_ED25519
+    ) {
+      throw new Error(
+        `Unsupported channel attestation method: ${channelAttestationMethod}`,
+      );
+    }
+    const privateKey = await this.channelToPrivateKey(channel);
+    return await this.channelPublicIdFromPrivateKey(privateKey);
+  }
+
+  async getMethod(channelPublicId: Uint8Array): Promise<string> {
+    if (
+      channelPublicId[0] === CHANNEL_ATTESTATION_METHOD_PREFIX_SHA256_ED25519
+    ) {
+      return CHANNEL_ATTESTATION_METHOD_SHA256_ED25519;
+    } else {
+      throw new Error(`Unrecognized channel attestation method.`);
+    }
+  }
+
+  protected async channelToPrivateKey(channel: string): Promise<Uint8Array> {
+    const channelBytes = new TextEncoder().encode(channel);
+    return await sha256(channelBytes);
+  }
+  protected async channelPublicIdFromPrivateKey(
+    privateKey: Uint8Array,
+  ): Promise<Uint8Array> {
+    const channelPublicIdRaw = await getPublicKeyAsync(privateKey);
+    const channelPublicId = new Uint8Array(channelPublicIdRaw.length + 1);
+    channelPublicId[0] = CHANNEL_ATTESTATION_METHOD_PREFIX_SHA256_ED25519;
+    channelPublicId.set(channelPublicIdRaw, 1);
+    return channelPublicId;
+  }
+
+  async attest(
+    channelAttestationMethod: string,
+    actor: string,
+    channel: string,
+  ): Promise<{
+    attestation: Uint8Array;
+    channelPublicId: Uint8Array;
+  }> {
+    if (
+      channelAttestationMethod !== CHANNEL_ATTESTATION_METHOD_SHA256_ED25519
+    ) {
+      throw new Error(
+        `Unsupported channel attestation method: ${channelAttestationMethod}`,
+      );
+    }
+    const privateKey = await this.channelToPrivateKey(channel);
+    const channelPublicId =
+      await this.channelPublicIdFromPrivateKey(privateKey);
+
+    const actorBytes = new TextEncoder().encode(actor);
+    const attestation = await signAsync(actorBytes, privateKey);
+    return { attestation, channelPublicId };
+  }
+
+  async validate(
+    attestation: Uint8Array,
+    actor: string,
+    channelPublicId: Uint8Array,
+  ): Promise<boolean> {
+    const prefix = channelPublicId[0];
+    if (prefix !== CHANNEL_ATTESTATION_METHOD_PREFIX_SHA256_ED25519) {
+      throw new Error(
+        `Unrecognized channel attestation method prefix: ${prefix}`,
+      );
+    }
+
+    return await verifyAsync(
+      attestation,
+      new TextEncoder().encode(actor),
+      channelPublicId.slice(1),
+    );
+  }
+}

package/src/2-primitives/4-allowed-attestations-tests.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "vitest";
+import {
+  ALLOWED_ATTESTATION_METHOD_HMAC_SHA256,
+  AllowedAttestations,
+} from "./4-allowed-attestations";
+import { randomBytes } from "@noble/hashes/utils.js";
+import {
+  StringEncoder,
+  STRING_ENCODER_METHOD_BASE64URL,
+} from "./1-string-encoding";
+
+export function allowedAttestationTests() {
+  describe("Allowed Attestation Tests", () => {
+    const allowedAttestationMethods = [ALLOWED_ATTESTATION_METHOD_HMAC_SHA256];
+    const allowedAttestations = new AllowedAttestations();
+
+    async function randomActor() {
+      const bytes = randomBytes();
+      const str = await new StringEncoder().encode(
+        STRING_ENCODER_METHOD_BASE64URL,
+        bytes,
+      );
+      return `did:web:${str}.com`;
+    }
+
+    test("Invalid attestation method", async () => {
+      const actor = await randomActor();
+      await expect(() =>
+        allowedAttestations.attest("invalid-method", actor),
+      ).rejects.toThrow();
+    });
+
+    for (const method of allowedAttestationMethods) {
+      describe(`Attestation Method: ${method}`, () => {
+        test("Valid attestation", async () => {
+          const actor = await randomActor();
+          const { attestation, ticket } = await allowedAttestations.attest(
+            method,
+            actor,
+          );
+          const isValid = await allowedAttestations.validate(
+            attestation,
+            actor,
+            ticket,
+          );
+          expect(isValid).toBe(true);
+        });
+
+        test("Wrong actor", async () => {
+          const actor = await randomActor();
+          const { attestation, ticket } = await allowedAttestations.attest(
+            method,
+            actor,
+          );
+          const otherActor = await randomActor();
+          const isValid = await allowedAttestations.validate(
+            attestation,
+            otherActor,
+            ticket,
+          );
+          expect(isValid).toBe(false);
+        });
+
+        test("Wrong ticket", async () => {
+          const actor = await randomActor();
+          const { attestation: attestation1, ticket: ticket1 } =
+            await allowedAttestations.attest(method, actor);
+          const { attestation: attestation2, ticket: ticket2 } =
+            await allowedAttestations.attest(method, actor);
+          const isValid1 = await allowedAttestations.validate(
+            attestation1,
+            actor,
+            ticket2,
+          );
+          const isValid2 = await allowedAttestations.validate(
+            attestation2,
+            actor,
+            ticket1,
+          );
+          expect(isValid1).toBe(false);
+          expect(isValid2).toBe(false);
+        });
+      });
+    }
+  });
+}

package/src/2-primitives/4-allowed-attestations.ts

@@ -0,0 +1,69 @@
+import { sha256, hmac } from "@noble/hashes/webcrypto.js";
+import { randomBytes } from "@noble/hashes/utils.js";
+import {
+  MULTIHASH_CODE_SHA256,
+  MULTIHASH_LENGTH_SHA256,
+} from "./2-content-addresses";
+
+export const ALLOWED_ATTESTATION_METHOD_HMAC_SHA256 = "hmac:sha2-256";
+const ALLOWED_ATTESTATION_METHOD_PREFIX_HMAC = 0;
+
+export class AllowedAttestations {
+  async attest(
+    allowedAttestationMethod: string,
+    actor: string,
+  ): Promise<{
+    attestation: Uint8Array;
+    ticket: Uint8Array;
+  }> {
+    if (allowedAttestationMethod !== ALLOWED_ATTESTATION_METHOD_HMAC_SHA256) {
+      throw new Error(
+        `Unsupported allowed attestation method: ${allowedAttestationMethod}`,
+      );
+    }
+
+    const ticket = randomBytes();
+    const attestation = await hmac(
+      sha256,
+      ticket,
+      new TextEncoder().encode(actor),
+    );
+
+    const prefixedTicket = new Uint8Array(ticket.length + 3);
+    prefixedTicket[0] = ALLOWED_ATTESTATION_METHOD_PREFIX_HMAC;
+    prefixedTicket[1] = MULTIHASH_CODE_SHA256;
+    prefixedTicket[2] = MULTIHASH_LENGTH_SHA256;
+    prefixedTicket.set(ticket, 3);
+
+    return { attestation, ticket: prefixedTicket };
+  }
+
+  async validate(
+    attestation: Uint8Array,
+    actor: string,
+    ticket: Uint8Array,
+  ): Promise<boolean> {
+    const typePrefix = ticket[0];
+    const hashPrefix = ticket[1];
+    const lengthPrefix = ticket[2];
+    if (
+      typePrefix !== ALLOWED_ATTESTATION_METHOD_PREFIX_HMAC ||
+      hashPrefix !== MULTIHASH_CODE_SHA256 ||
+      lengthPrefix !== MULTIHASH_LENGTH_SHA256
+    ) {
+      throw new Error(`Unrecognized allowed ticket format`);
+    }
+
+    const expected = await hmac(
+      sha256,
+      ticket.slice(3),
+      new TextEncoder().encode(actor),
+    );
+
+    // Make sure the bytes are exactly equal
+    if (attestation.length !== expected.length) {
+      return false;
+    }
+    return expected.every((b, i) => attestation[i] === b);
+  }
+}