@graphprotocol/hypergraph 0.0.1

package/src/store.ts

@@ -0,0 +1,493 @@
+import type { AnyDocumentId, DocHandle, Repo } from '@automerge/automerge-repo';
+import { type Store, createStore } from '@xstate/store';
+import type { PrivateAppIdentity } from './connect/types.js';
+import { mergeMessages } from './inboxes/merge-messages.js';
+import type { InboxSenderAuthPolicy } from './inboxes/types.js';
+import type { Invitation, Updates } from './messages/index.js';
+import type { SpaceEvent, SpaceState } from './space-events/index.js';
+import { idToAutomergeId } from './utils/automergeId.js';
+
+export type InboxMessageStorageEntry = {
+  id: string;
+  plaintext: string;
+  ciphertext: string;
+  signature: {
+    hex: string;
+    recovery: number;
+  } | null;
+  createdAt: string;
+  authorAccountAddress: string | null;
+};
+
+export type SpaceInboxStorageEntry = {
+  inboxId: string;
+  isPublic: boolean;
+  authPolicy: InboxSenderAuthPolicy;
+  encryptionPublicKey: string;
+  secretKey: string;
+  lastMessageClock: string;
+  messages: InboxMessageStorageEntry[]; // Kept sorted by UUIDv7
+  seenMessageIds: Set<string>; // For deduplication
+};
+
+export type AccountInboxStorageEntry = {
+  inboxId: string;
+  isPublic: boolean;
+  authPolicy: InboxSenderAuthPolicy;
+  encryptionPublicKey: string;
+  lastMessageClock: string;
+  messages: InboxMessageStorageEntry[]; // Kept sorted by UUIDv7
+  seenMessageIds: Set<string>; // For deduplication
+};
+
+export type SpaceStorageEntry = {
+  id: string;
+  events: SpaceEvent[];
+  state: SpaceState | undefined;
+  keys: { id: string; key: string }[];
+  automergeDocHandle: DocHandle<unknown> | undefined;
+  inboxes: SpaceInboxStorageEntry[];
+};
+
+interface StoreContext {
+  spaces: SpaceStorageEntry[];
+  updatesInFlight: string[];
+  invitations: Invitation[];
+  repo: Repo | null;
+  identities: {
+    [accountAddress: string]: {
+      encryptionPublicKey: string;
+      signaturePublicKey: string;
+      accountProof: string;
+      keyProof: string;
+    };
+  };
+  authenticated: boolean;
+  identity: PrivateAppIdentity | null;
+  lastUpdateClock: { [spaceId: string]: number };
+  accountInboxes: AccountInboxStorageEntry[];
+}
+
+const initialStoreContext: StoreContext = {
+  spaces: [],
+  updatesInFlight: [],
+  invitations: [],
+  repo: null,
+  identities: {},
+  authenticated: false,
+  identity: null,
+  lastUpdateClock: {},
+  accountInboxes: [],
+};
+
+type StoreEvent =
+  | { type: 'setInvitations'; invitations: Invitation[] }
+  | { type: 'reset' }
+  | { type: 'addUpdateInFlight'; updateId: string }
+  | { type: 'removeUpdateInFlight'; updateId: string }
+  | { type: 'setSpaceFromList'; spaceId: string }
+  | { type: 'applyEvent'; spaceId: string; event: SpaceEvent; state: SpaceState }
+  | { type: 'updateConfirmed'; spaceId: string; clock: number }
+  | { type: 'applyUpdate'; spaceId: string; firstUpdateClock: number; lastUpdateClock: number }
+  | {
+      type: 'addVerifiedIdentity';
+      accountAddress: string;
+      encryptionPublicKey: string;
+      signaturePublicKey: string;
+      accountProof: string;
+      keyProof: string;
+    }
+  | {
+      type: 'setSpaceInbox';
+      spaceId: string;
+      inbox: SpaceInboxStorageEntry;
+    }
+  | {
+      type: 'setSpaceInboxMessages';
+      spaceId: string;
+      inboxId: string;
+      messages: InboxMessageStorageEntry[];
+      lastMessageClock: string;
+    }
+  | {
+      type: 'setAccountInbox';
+      inbox: AccountInboxStorageEntry;
+    }
+  | {
+      type: 'setAccountInboxMessages';
+      inboxId: string;
+      messages: InboxMessageStorageEntry[];
+      lastMessageClock: string;
+    }
+  | {
+      type: 'setSpace';
+      spaceId: string;
+      updates?: Updates;
+      events: SpaceEvent[];
+      inboxes?: SpaceInboxStorageEntry[];
+      spaceState: SpaceState;
+      keys: {
+        id: string;
+        key: string;
+      }[];
+    }
+  | {
+      type: 'setAuth';
+      identity: PrivateAppIdentity;
+    }
+  | {
+      type: 'resetAuth';
+    }
+  | {
+      type: 'setRepo';
+      repo: Repo;
+    };
+
+type GenericEventObject = { type: string };
+
+export const store: Store<StoreContext, StoreEvent, GenericEventObject> = createStore({
+  context: initialStoreContext,
+  on: {
+    setInvitations: (context, event: { invitations: Invitation[] }) => {
+      return {
+        ...context,
+        invitations: event.invitations,
+      };
+    },
+    reset: (context) => {
+      // once the repo is initialized, there is no need to reset it
+      return { ...initialStoreContext, repo: context.repo };
+    },
+    addUpdateInFlight: (context, event: { updateId: string }) => {
+      return {
+        ...context,
+        updatesInFlight: [...context.updatesInFlight, event.updateId],
+      };
+    },
+    removeUpdateInFlight: (context, event: { updateId: string }) => {
+      return {
+        ...context,
+        updatesInFlight: context.updatesInFlight.filter((id) => id !== event.updateId),
+      };
+    },
+    setSpaceFromList: (context, event: { spaceId: string }) => {
+      if (!context.repo) {
+        return context;
+      }
+      const existingSpace = context.spaces.find((s) => s.id === event.spaceId);
+      const lastUpdateClock = context.lastUpdateClock[event.spaceId] ?? -1;
+      const result = context.repo.findWithProgress(idToAutomergeId(event.spaceId) as AnyDocumentId);
+
+      // set it to ready to interact with the document
+      result.handle.doneLoading();
+
+      if (existingSpace) {
+        return {
+          ...context,
+          spaces: context.spaces.map((existingSpace) => {
+            if (existingSpace.id === event.spaceId) {
+              const newSpace: SpaceStorageEntry = {
+                id: existingSpace.id,
+                events: existingSpace.events ?? [],
+                state: existingSpace.state,
+                keys: existingSpace.keys ?? [],
+                automergeDocHandle: result.handle,
+                inboxes: existingSpace.inboxes ?? [],
+              };
+              return newSpace;
+            }
+            return existingSpace;
+          }),
+          lastUpdateClock: {
+            ...context.lastUpdateClock,
+            [event.spaceId]: lastUpdateClock,
+          },
+        };
+      }
+      return {
+        ...context,
+        spaces: [
+          ...context.spaces,
+          {
+            id: event.spaceId,
+            events: [],
+            state: undefined,
+            keys: [],
+            inboxes: [],
+            updates: [],
+            lastUpdateClock: -1,
+            automergeDocHandle: result.handle,
+          },
+        ],
+      };
+    },
+    applyEvent: (context, event: { spaceId: string; event: SpaceEvent; state: SpaceState }) => {
+      return {
+        ...context,
+        spaces: context.spaces.map((space) => {
+          if (space.id === event.spaceId) {
+            return { ...space, events: [...space.events, event.event], state: event.state };
+          }
+          return space;
+        }),
+      };
+    },
+    updateConfirmed: (context, event: { spaceId: string; clock: number }) => {
+      return {
+        ...context,
+        lastUpdateClock: {
+          ...context.lastUpdateClock,
+          [event.spaceId]: event.clock,
+        },
+      };
+    },
+    applyUpdate: (context, event: { spaceId: string; firstUpdateClock: number; lastUpdateClock: number }) => {
+      const lastUpdateClock = context.lastUpdateClock[event.spaceId] ?? -1;
+      if (event.firstUpdateClock === lastUpdateClock + 1) {
+        return {
+          ...context,
+          lastUpdateClock: {
+            ...context.lastUpdateClock,
+            [event.spaceId]: event.lastUpdateClock,
+          },
+        };
+      }
+
+      // TODO else case: request missing updates from server
+      return context;
+    },
+    addVerifiedIdentity: (
+      context,
+      event: {
+        accountAddress: string;
+        encryptionPublicKey: string;
+        signaturePublicKey: string;
+        accountProof: string;
+        keyProof: string;
+      },
+    ) => {
+      return {
+        ...context,
+        identities: {
+          ...context.identities,
+          [event.accountAddress]: {
+            encryptionPublicKey: event.encryptionPublicKey,
+            signaturePublicKey: event.signaturePublicKey,
+            accountProof: event.accountProof,
+            keyProof: event.keyProof,
+          },
+        },
+      };
+    },
+    setSpaceInbox: (context, event: { spaceId: string; inbox: SpaceInboxStorageEntry }) => {
+      return {
+        ...context,
+        spaces: context.spaces.map((space) => {
+          if (space.id === event.spaceId) {
+            const existingInbox = space.inboxes.find((inbox) => inbox.inboxId === event.inbox.inboxId);
+            if (existingInbox) {
+              return {
+                ...space,
+                inboxes: space.inboxes.map((inbox) => {
+                  if (inbox.inboxId === event.inbox.inboxId) {
+                    const { messages, seenMessageIds } = mergeMessages(
+                      existingInbox.messages,
+                      existingInbox.seenMessageIds,
+                      event.inbox.messages,
+                    );
+                    return {
+                      ...event.inbox,
+                      messages,
+                      seenMessageIds,
+                    };
+                  }
+                  return inbox;
+                }),
+              };
+            }
+            return { ...space, inboxes: [...space.inboxes, event.inbox] };
+          }
+          return space;
+        }),
+      };
+    },
+    setSpaceInboxMessages: (
+      context,
+      event: { spaceId: string; inboxId: string; messages: InboxMessageStorageEntry[]; lastMessageClock: string },
+    ) => {
+      return {
+        ...context,
+        spaces: context.spaces.map((space) => {
+          if (space.id === event.spaceId) {
+            return {
+              ...space,
+              inboxes: space.inboxes.map((inbox) => {
+                if (inbox.inboxId === event.inboxId) {
+                  const { messages, seenMessageIds } = mergeMessages(
+                    inbox.messages,
+                    inbox.seenMessageIds,
+                    event.messages,
+                  );
+                  return {
+                    ...inbox,
+                    messages,
+                    seenMessageIds,
+                    lastMessageClock: new Date(
+                      Math.max(new Date(inbox.lastMessageClock).getTime(), new Date(event.lastMessageClock).getTime()),
+                    ).toISOString(),
+                  };
+                }
+                return inbox;
+              }),
+            };
+          }
+          return space;
+        }),
+      };
+    },
+    setAccountInbox: (context, event: { inbox: AccountInboxStorageEntry }) => {
+      const existingInbox = context.accountInboxes.find((inbox) => inbox.inboxId === event.inbox.inboxId);
+      if (existingInbox) {
+        return {
+          ...context,
+          accountInboxes: context.accountInboxes.map((inbox) => {
+            if (inbox.inboxId === event.inbox.inboxId) {
+              const { messages, seenMessageIds } = mergeMessages(
+                existingInbox.messages,
+                existingInbox.seenMessageIds,
+                event.inbox.messages,
+              );
+              return {
+                ...event.inbox,
+                messages,
+                seenMessageIds,
+              };
+            }
+            return inbox;
+          }),
+        };
+      }
+      return {
+        ...context,
+        accountInboxes: [...context.accountInboxes, event.inbox],
+      };
+    },
+    setAccountInboxMessages: (
+      context,
+      event: { inboxId: string; messages: InboxMessageStorageEntry[]; lastMessageClock: string },
+    ) => {
+      return {
+        ...context,
+        accountInboxes: context.accountInboxes.map((inbox) => {
+          if (inbox.inboxId === event.inboxId) {
+            const { messages, seenMessageIds } = mergeMessages(inbox.messages, inbox.seenMessageIds, event.messages);
+            return {
+              ...inbox,
+              messages,
+              seenMessageIds,
+              lastMessageClock: new Date(
+                Math.max(new Date(inbox.lastMessageClock).getTime(), new Date(event.lastMessageClock).getTime()),
+              ).toISOString(),
+            };
+          }
+          return inbox;
+        }),
+      };
+    },
+    setSpace: (
+      context,
+      event: {
+        spaceId: string;
+        updates?: Updates;
+        inboxes?: SpaceInboxStorageEntry[];
+        events: SpaceEvent[];
+        spaceState: SpaceState;
+        keys: {
+          id: string;
+          key: string;
+        }[];
+      },
+    ) => {
+      const existingSpace = context.spaces.find((s) => s.id === event.spaceId);
+      if (!existingSpace && context.repo) {
+        const result = context.repo.findWithProgress(idToAutomergeId(event.spaceId) as AnyDocumentId);
+        // set it to ready to interact with the document
+        result.handle.doneLoading();
+
+        const newSpace: SpaceStorageEntry = {
+          id: event.spaceId,
+          events: event.events,
+          state: event.spaceState,
+          keys: event.keys,
+          automergeDocHandle: result.handle,
+          inboxes: event.inboxes ?? [],
+        };
+        return {
+          ...context,
+          spaces: [...context.spaces, newSpace],
+          lastUpdateClock: {
+            ...context.lastUpdateClock,
+            [event.spaceId]: -1,
+          },
+        };
+      }
+
+      let lastUpdateClock = context.lastUpdateClock[event.spaceId] ?? -1;
+      if (event.updates?.firstUpdateClock === lastUpdateClock + 1) {
+        lastUpdateClock = event.updates.lastUpdateClock;
+      } else {
+        // TODO request missing updates from server
+      }
+
+      return {
+        ...context,
+        spaces: context.spaces.map((space) => {
+          if (space.id === event.spaceId) {
+            // Merge inboxes: keep existing ones and add new ones
+            const mergedInboxes = [...space.inboxes];
+            for (const newInbox of event.inboxes ?? []) {
+              const existingInboxIndex = mergedInboxes.findIndex((inbox) => inbox.inboxId === newInbox.inboxId);
+              if (existingInboxIndex === -1) {
+                // Only add if it's a new inbox
+                mergedInboxes.push(newInbox);
+              }
+            }
+
+            return {
+              ...space,
+              events: event.events,
+              state: event.spaceState,
+              keys: event.keys,
+              inboxes: mergedInboxes,
+            };
+          }
+          return space;
+        }),
+        lastUpdateClock: {
+          ...context.lastUpdateClock,
+          [event.spaceId]: lastUpdateClock,
+        },
+      };
+    },
+    setAuth: (context, event: { identity: PrivateAppIdentity }) => {
+      return {
+        ...context,
+        authenticated: true,
+        identity: event.identity,
+      };
+    },
+    resetAuth: (context) => {
+      return {
+        ...context,
+        identity: null,
+        authenticated: false,
+      };
+    },
+    setRepo: (context, event: { repo: Repo }) => {
+      return {
+        ...context,
+        repo: event.repo,
+      };
+    },
+  },
+});

package/src/type/type.ts

@@ -0,0 +1,25 @@
+import * as Schema from 'effect/Schema';
+import { Field } from '../entity/entity.js';
+import type { AnyNoContext, EntityWithRelation } from '../entity/types.js';
+
+export const Text = Schema.String;
+// biome-ignore lint/suspicious/noShadowRestrictedNames: is part of a namespaces module and therefor ok
+export const Number = Schema.Number;
+export const Checkbox = Schema.Boolean;
+// biome-ignore lint/suspicious/noShadowRestrictedNames: is part of a namespaces module and therefor ok
+export const Date = Schema.Date;
+export const Url = Schema.URL;
+export const Point = Schema.transform(Schema.String, Schema.Array(Number), {
+  strict: true,
+  decode: (str: string) => {
+    return str.split(',').map((n: string) => globalThis.Number(n));
+  },
+  encode: (points: readonly number[]) => points.join(','),
+});
+
+export const Relation = <S extends AnyNoContext>(schema: S) =>
+  Field({
+    select: Schema.Array(schema) as unknown as Schema.Schema<ReadonlyArray<EntityWithRelation<S>>>,
+    insert: Schema.optional(Schema.Array(Schema.String)),
+    update: Schema.Undefined,
+  });

package/src/types.ts

@@ -0,0 +1,47 @@
+import * as Data from 'effect/Data';
+import * as Schema from 'effect/Schema';
+
+export const SignatureWithRecovery = Schema.Struct({
+  hex: Schema.String,
+  recovery: Schema.Number,
+});
+
+export type SignatureWithRecovery = Schema.Schema.Type<typeof SignatureWithRecovery>;
+
+export const ConnectAuthPayload = Schema.Struct({
+  expiry: Schema.Number,
+  encryptionPublicKey: Schema.String,
+  appId: Schema.String,
+});
+
+export type ConnectAuthPayload = Schema.Schema.Type<typeof ConnectAuthPayload>;
+
+export const ConnectCallbackResult = Schema.Struct({
+  appIdentityAddress: Schema.String,
+  appIdentityAddressPrivateKey: Schema.String,
+  signaturePublicKey: Schema.String,
+  signaturePrivateKey: Schema.String,
+  encryptionPublicKey: Schema.String,
+  encryptionPrivateKey: Schema.String,
+  sessionToken: Schema.String,
+  sessionTokenExpires: Schema.Date,
+  spaces: Schema.Array(Schema.Struct({ id: Schema.String })),
+});
+
+export type ConnectCallbackResult = Schema.Schema.Type<typeof ConnectCallbackResult>;
+
+export const ConnectCallbackDecryptedData = Schema.Struct({
+  ...ConnectCallbackResult.fields,
+  sessionTokenExpires: Schema.Number,
+  expiry: Schema.Number,
+});
+
+export type ConnectCallbackDecryptedData = Schema.Schema.Type<typeof ConnectCallbackDecryptedData>;
+
+export class FailedToParseConnectAuthUrl extends Data.TaggedError('FailedToParseConnectAuthUrl')<{
+  message: string;
+}> {}
+
+export class FailedToParseAuthCallbackUrl extends Data.TaggedError('FailedToParseAuthCallbackUrl')<{
+  message: string;
+}> {}

package/src/utils/assertExhaustive.ts

@@ -0,0 +1,3 @@
+export const assertExhaustive = (_value: never, message = 'Reached unexpected case in exhaustive switch'): never => {
+  throw new Error(message);
+};

package/src/utils/automergeId.ts

@@ -0,0 +1,18 @@
+import bs58check from 'bs58check';
+import { parse as parseUuid, stringify as stringifyUuid } from 'uuid';
+
+/**
+ * Converts a UUID into Base58Check
+ */
+export function idToAutomergeId(uuid: string, _versionByte = 0x00) {
+  const payload = parseUuid(uuid);
+  return bs58check.encode(payload);
+}
+
+/**
+ * Converts a Base58Check-encoded UUID back to UUID
+ */
+export function automergeIdToId(base58CheckUuid: string) {
+  const versionedPayload = bs58check.decode(base58CheckUuid);
+  return stringifyUuid(versionedPayload);
+}

package/src/utils/base58.ts

@@ -0,0 +1,74 @@
+import { BASE58_ALLOWED_CHARS } from './internal/base58Utils.js';
+
+export type Base58 = string;
+
+/**
+ * Base58 encodes the given string value.
+ *
+ * @example
+ * ```ts
+ * import { v4 as uuidv4 } from "uuid";
+ *
+ * const uuid = uuidv4(); // 92539817-7989-4083-ab80-e9c2b2b66669
+ * const dashesRemoved = uuid.replaceAll(/-/g, ""); // 9253981779894083ab80e9c2b2b66669
+ * const encoded = encodeBase58(dashesRemoved)
+ * console.log(encoded) // K51CbDqxW35osbjPo5ZF77
+ * ```
+ *
+ * @param val string to encode as base58
+ * @returns the base58 encoded string
+ */
+export function encodeBase58(val: string): Base58 {
+  const hex = BigInt(`0x${val}`);
+  let remainder = hex;
+  const result: string[] = []; // Use an array to store encoded characters
+
+  while (remainder > 0n) {
+    const mod = remainder % 58n;
+    const base58CharAtMod = BASE58_ALLOWED_CHARS[Number(mod)];
+    if (base58CharAtMod) {
+      result.push(base58CharAtMod);
+    }
+    remainder = remainder / 58n;
+  }
+
+  // Reverse and join the array to get the final Base58 encoded string
+  return result.reverse().join('');
+}
+
+export type UUID = string;
+
+/**
+ * Expand the base58 encoded UUID back to its original UUID format
+ *
+ * @example
+ * ```ts
+ * const uuid = 92539817-7989-4083-ab80-e9c2b2b66669;
+ * const encoded = encodeBase58(dashesRemoved); // K51CbDqxW35osbjPo5ZF77
+ * const decoded = decodeBase58ToUUID(encoded); // 92539817-7989-4083-ab80-e9c2b2b66669
+ *
+ * expect(decoded).toEqual(uuid);
+ * ```
+ *
+ * @param encoded base58 encoded UUID
+ * @returns the expanded UUID from the base58 encoded value
+ */
+export function decodeBase58ToUUID(encoded: string): UUID {
+  let decoded = 0n;
+
+  for (const char of encoded) {
+    const index = BASE58_ALLOWED_CHARS.indexOf(char);
+    if (index === -1) {
+      throw new Error('Invalid Base58 character');
+    }
+    decoded = decoded * 58n + BigInt(index);
+  }
+
+  // Convert the bigint to a hex string, padded to 32 characters
+  let hexStr = decoded.toString(16);
+  hexStr = hexStr.padStart(32, '0'); // Ensure it is 32 characters
+
+  return [hexStr.slice(0, 8), hexStr.slice(8, 12), hexStr.slice(12, 16), hexStr.slice(16, 20), hexStr.slice(20)].join(
+    '-',
+  );
+}

package/src/utils/generateId.ts

@@ -0,0 +1,18 @@
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Generate a v4 UUID.
+ *
+ * @example
+ * ```
+ * import { generateId } from '@graph-framework/utils'
+ *
+ * const id = generateId()
+ * console.log(id)
+ * ```
+ *
+ * @returns v4 UUID
+ */
+export function generateId() {
+  return uuidv4();
+}

package/src/utils/hexBytesAddressUtils.ts

@@ -0,0 +1,25 @@
+import { bytesToHex as nobleBytesToHex, hexToBytes as nobleHexToBytes } from '@noble/ciphers/utils';
+import { ProjectivePoint } from '@noble/secp256k1';
+import type { Hex } from 'viem';
+import { publicKeyToAddress as viemPublicKeyToAddress } from 'viem/accounts';
+
+export const bytesToHex = (bytes: Uint8Array): string => {
+  return `0x${nobleBytesToHex(bytes)}`;
+};
+
+export const hexToBytes = (hex: string): Uint8Array => {
+  return nobleHexToBytes(hex.slice(2));
+};
+
+function decompressPublicKey(compressedKey: string): string {
+  // Decompress the public key
+  const point = ProjectivePoint.fromHex(compressedKey.slice(2));
+
+  // Get the uncompressed public key
+  const uncompressedKey = point.toRawBytes(false); // `false` = uncompressed format
+  return bytesToHex(uncompressedKey);
+}
+export const publicKeyToAddress = (publicKey: string): string => {
+  const uncompressedKey = decompressPublicKey(publicKey);
+  return viemPublicKeyToAddress(uncompressedKey as Hex);
+};