@graphprotocol/hypergraph 0.0.1

package/src/connect/identity-encryption.ts

@@ -0,0 +1,232 @@
+import { gcm } from '@noble/ciphers/aes';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+import type { Hex } from 'viem';
+import { verifyMessage } from 'viem';
+
+import { bytesToHex, canonicalize, hexToBytes } from '../utils/index.js';
+import type { IdentityKeys, PrivateAppIdentity, Signer } from './types.js';
+
+// Adapted from the XMTP approach to encrypt keys
+// See: https://github.com/xmtp/xmtp-js/blob/8d6e5a65813902926baac8150a648587acbaad92/sdks/js-sdk/src/keystore/providers/NetworkKeyManager.ts#L79-L116
+// (We reimplement their encrypt/decrypt functions using noble).
+
+const hkdfDeriveKey = (secret: Uint8Array, salt: Uint8Array): Uint8Array => {
+  return hkdf(sha256, secret, salt, '', 32);
+};
+
+// This implements the same encryption as  https://github.com/xmtp/xmtp-js/blob/336471de4ea95416ad0f4f9850d3f12bb0a13f1e/sdks/js-sdk/src/encryption/encryption.ts#L18
+// But using @noble/ciphers instead of the WebCrypto API.
+// The XMTP code was audited by Certik: https://skynet.certik.com/projects/xmtp
+//
+// Worth noting that GCM nonce collision would break the encryption,
+// and 12 bytes is not a lot. So this function should not be used to encrypt
+// a large number of messages with the same secret. In our case it should be okay
+// as each secret is only used to encrypt a single identity. If we need
+// something more secure for a larger number of messages we should use a
+// different encryption scheme, e.g. XAES-256-GCM, see https://words.filippo.io/dispatches/xaes-256-gcm/
+const encrypt = (msg: Uint8Array, secret: Uint8Array): string => {
+  const hkdfSalt = randomBytes(32);
+  const gcmNonce = randomBytes(12);
+  const derivedKey = hkdfDeriveKey(secret, hkdfSalt);
+
+  const aes = gcm(derivedKey, gcmNonce);
+
+  const ciphertext = aes.encrypt(msg);
+
+  // TODO: Use Effect Schema and better serialization?
+  const ciphertextJson = canonicalize({
+    aes256GcmHkdfSha256: {
+      payload: bytesToHex(ciphertext),
+      hkdfSalt: bytesToHex(hkdfSalt),
+      gcmNonce: bytesToHex(gcmNonce),
+    },
+  });
+  return bytesToHex(new TextEncoder().encode(ciphertextJson));
+};
+
+// This implements the same decryption as  https://github.com/xmtp/xmtp-js/blob/336471de4ea95416ad0f4f9850d3f12bb0a13f1e/sdks/js-sdk/src/encryption/encryption.ts#L41
+// But using @noble/ciphers instead of the WebCrypto API
+// The XMTP code was audited by Certik: https://skynet.certik.com/projects/xmtp
+const decrypt = (ciphertext: string, secret: Uint8Array): Uint8Array => {
+  const ciphertextJson = new TextDecoder().decode(hexToBytes(ciphertext));
+  const { aes256GcmHkdfSha256 } = JSON.parse(ciphertextJson);
+  const hkdfSalt = hexToBytes(aes256GcmHkdfSha256.hkdfSalt);
+  const gcmNonce = hexToBytes(aes256GcmHkdfSha256.gcmNonce);
+  const derivedKey = hkdfDeriveKey(secret, hkdfSalt);
+
+  const aes = gcm(derivedKey, gcmNonce);
+
+  return aes.decrypt(hexToBytes(aes256GcmHkdfSha256.payload));
+};
+
+const signatureMessage = (nonce: Uint8Array): string => {
+  return `The Graph: sign to encrypt/decrypt identity keys.\nNonce: ${bytesToHex(nonce)}\n`;
+};
+
+export const encryptIdentity = async (
+  signer: Signer,
+  accountAddress: string,
+  keys: IdentityKeys,
+): Promise<{ ciphertext: string; nonce: string }> => {
+  const nonce = randomBytes(32);
+  const message = signatureMessage(nonce);
+  const signature = (await signer.signMessage(message)) as Hex;
+
+  // Check that the signature is valid
+  const valid = await verifyMessage({
+    address: accountAddress as Hex,
+    message,
+    signature,
+  });
+  if (!valid) {
+    throw new Error('Invalid signature');
+  }
+  const secretKey = hexToBytes(signature);
+  // We use a simple plaintext encoding:
+  // Hex keys separated by newlines
+  const keysTxt = [
+    keys.encryptionPublicKey,
+    keys.encryptionPrivateKey,
+    keys.signaturePublicKey,
+    keys.signaturePrivateKey,
+  ].join('\n');
+  const keysMsg = new TextEncoder().encode(keysTxt);
+  const ciphertext = encrypt(keysMsg, secretKey);
+  return { ciphertext, nonce: bytesToHex(nonce) };
+};
+
+export const decryptIdentity = async (
+  signer: Signer,
+  accountAddress: string,
+  ciphertext: string,
+  nonce: string,
+): Promise<IdentityKeys> => {
+  const message = signatureMessage(hexToBytes(nonce));
+  const signature = (await signer.signMessage(message)) as Hex;
+
+  // Check that the signature is valid
+  const valid = await verifyMessage({
+    address: accountAddress as Hex,
+    message,
+    signature,
+  });
+  if (!valid) {
+    throw new Error('Invalid signature');
+  }
+  const secretKey = hexToBytes(signature);
+  let keysMsg: Uint8Array;
+  try {
+    keysMsg = await decrypt(ciphertext, secretKey);
+  } catch (e) {
+    // See https://github.com/xmtp/xmtp-js/blob/8d6e5a65813902926baac8150a648587acbaad92/sdks/js-sdk/src/keystore/providers/NetworkKeyManager.ts#L142-L146
+    if (secretKey.length !== 65) {
+      throw new Error('Expected 65 bytes before trying a different recovery byte');
+    }
+    // Try the other version of recovery byte, either +27 or -27
+    const lastByte = secretKey[secretKey.length - 1];
+    let newSecret = secretKey.slice(0, secretKey.length - 1);
+    if (lastByte < 27) {
+      newSecret = new Uint8Array([...newSecret, lastByte + 27]);
+    } else {
+      newSecret = new Uint8Array([...newSecret, lastByte - 27]);
+    }
+    keysMsg = await decrypt(ciphertext, newSecret);
+  }
+  const keysTxt = new TextDecoder().decode(keysMsg);
+  const [encryptionPublicKey, encryptionPrivateKey, signaturePublicKey, signaturePrivateKey] = keysTxt.split('\n');
+  return { encryptionPublicKey, encryptionPrivateKey, signaturePublicKey, signaturePrivateKey };
+};
+
+export const encryptAppIdentity = async (
+  signer: Signer,
+  accountAddress: string,
+  appIdentityAddress: string,
+  appIdentityAddressPrivateKey: string,
+  keys: IdentityKeys,
+): Promise<{ ciphertext: string; nonce: string }> => {
+  const nonce = randomBytes(32);
+  const message = signatureMessage(nonce);
+  const signature = (await signer.signMessage(message)) as Hex;
+
+  // Check that the signature is valid
+  const valid = await verifyMessage({
+    address: accountAddress as Hex,
+    message,
+    signature,
+  });
+  if (!valid) {
+    throw new Error('Invalid signature');
+  }
+  const secretKey = hexToBytes(signature);
+  // We use a simple plaintext encoding:
+  // Hex keys separated by newlines
+  const keysTxt = [
+    keys.encryptionPublicKey,
+    keys.encryptionPrivateKey,
+    keys.signaturePublicKey,
+    keys.signaturePrivateKey,
+    appIdentityAddress,
+    appIdentityAddressPrivateKey,
+  ].join('\n');
+  const keysMsg = new TextEncoder().encode(keysTxt);
+  const ciphertext = encrypt(keysMsg, secretKey);
+  return { ciphertext, nonce: bytesToHex(nonce) };
+};
+
+export const decryptAppIdentity = async (
+  signer: Signer,
+  accountAddress: string,
+  ciphertext: string,
+  nonce: string,
+): Promise<Omit<PrivateAppIdentity, 'sessionToken' | 'sessionTokenExpires'>> => {
+  const message = signatureMessage(hexToBytes(nonce));
+  const signature = (await signer.signMessage(message)) as Hex;
+
+  // Check that the signature is valid
+  const valid = await verifyMessage({
+    address: accountAddress as Hex,
+    message,
+    signature,
+  });
+  if (!valid) {
+    throw new Error('Invalid signature');
+  }
+  const secretKey = hexToBytes(signature);
+  let keysMsg: Uint8Array;
+  try {
+    keysMsg = await decrypt(ciphertext, secretKey);
+  } catch (e) {
+    // See https://github.com/xmtp/xmtp-js/blob/8d6e5a65813902926baac8150a648587acbaad92/sdks/js-sdk/src/keystore/providers/NetworkKeyManager.ts#L142-L146
+    if (secretKey.length !== 65) {
+      throw new Error('Expected 65 bytes before trying a different recovery byte');
+    }
+    // Try the other version of recovery byte, either +27 or -27
+    const lastByte = secretKey[secretKey.length - 1];
+    let newSecret = secretKey.slice(0, secretKey.length - 1);
+    if (lastByte < 27) {
+      newSecret = new Uint8Array([...newSecret, lastByte + 27]);
+    } else {
+      newSecret = new Uint8Array([...newSecret, lastByte - 27]);
+    }
+    keysMsg = await decrypt(ciphertext, newSecret);
+  }
+  const keysTxt = new TextDecoder().decode(keysMsg);
+  const [
+    encryptionPublicKey,
+    encryptionPrivateKey,
+    signaturePublicKey,
+    signaturePrivateKey,
+    appIdentityAddress,
+    appIdentityAddressPrivateKey,
+  ] = keysTxt.split('\n');
+  return {
+    encryptionPublicKey,
+    encryptionPrivateKey,
+    signaturePublicKey,
+    signaturePrivateKey,
+    address: appIdentityAddress,
+    addressPrivateKey: appIdentityAddressPrivateKey,
+  };
+};

package/src/connect/index.ts

@@ -0,0 +1,10 @@
+export * from './auth-storage.js';
+export * from './create-app-identity.js';
+export * from './create-auth-url.js';
+export * from './create-callback-params.js';
+export * from './identity-encryption.js';
+export * from './login.js';
+export * from './parse-auth-params.js';
+export * from './parse-callback-params.js';
+export * from './prove-ownership.js';
+export * from './types.js';

package/src/connect/login.ts

@@ -0,0 +1,114 @@
+import * as Schema from 'effect/Schema';
+import type { Address } from 'viem';
+import * as Messages from '../messages/index.js';
+import { store } from '../store-connect.js';
+import { storeAccountAddress, storeKeys } from './auth-storage.js';
+import { createIdentityKeys } from './create-identity-keys.js';
+import { decryptIdentity, encryptIdentity } from './identity-encryption.js';
+import { proveIdentityOwnership } from './prove-ownership.js';
+import type { IdentityKeys, Signer, Storage } from './types.js';
+
+export async function identityExists(accountAddress: string, syncServerUri: string) {
+  const res = await fetch(new URL(`/identity?accountAddress=${accountAddress}`, syncServerUri), {
+    method: 'GET',
+  });
+  return res.status === 200;
+}
+
+export async function signup(
+  signer: Signer,
+  accountAddress: Address,
+  syncServerUri: string,
+  storage: Storage,
+  identityToken: string,
+) {
+  const keys = createIdentityKeys();
+  const { ciphertext, nonce } = await encryptIdentity(signer, accountAddress, keys);
+  const { accountProof, keyProof } = await proveIdentityOwnership(signer, accountAddress, keys);
+
+  const req: Messages.RequestConnectCreateIdentity = {
+    keyBox: { accountAddress, ciphertext, nonce },
+    accountProof,
+    keyProof,
+    signaturePublicKey: keys.signaturePublicKey,
+    encryptionPublicKey: keys.encryptionPublicKey,
+  };
+  const res = await fetch(new URL('/connect/identity', syncServerUri), {
+    method: 'POST',
+    headers: {
+      'privy-id-token': identityToken,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(req),
+  });
+  if (res.status !== 200) {
+    // TODO: handle this better?
+    throw new Error(`Error creating identity: ${res.status}`);
+  }
+  const decoded = Schema.decodeUnknownSync(Messages.ResponseConnectCreateIdentity)(await res.json());
+  if (!decoded.success) {
+    throw new Error('Error creating identity');
+  }
+  storeAccountAddress(storage, accountAddress);
+  storeKeys(storage, accountAddress, keys);
+
+  return {
+    accountAddress,
+    keys,
+  };
+}
+
+export async function restoreKeys(
+  signer: Signer,
+  accountAddress: Address,
+  syncServerUri: string,
+  storage: Storage,
+  identityToken: string,
+) {
+  const res = await fetch(new URL('/connect/identity/encrypted', syncServerUri), {
+    method: 'POST',
+    headers: {
+      'privy-id-token': identityToken,
+      'Content-Type': 'application/json',
+    },
+  });
+
+  if (res.status === 200) {
+    const decoded = Schema.decodeUnknownSync(Messages.ResponseIdentityEncrypted)(await res.json());
+    const { keyBox } = decoded;
+    const { ciphertext, nonce } = keyBox;
+    const keys = await decryptIdentity(signer, accountAddress, ciphertext, nonce);
+    storeKeys(storage, accountAddress, keys);
+    return {
+      accountAddress,
+      keys,
+    };
+  }
+  throw new Error(`Error fetching identity ${res.status}`);
+}
+
+export async function login(
+  signer: Signer,
+  accountAddress: Address,
+  syncServerUri: string,
+  storage: Storage,
+  identityToken: string,
+) {
+  // const keys = loadKeys(storage, accountAddress);
+  let authData: {
+    accountAddress: Address;
+    keys: IdentityKeys;
+  };
+  const exists = await identityExists(accountAddress, syncServerUri);
+  if (!exists) {
+    authData = await signup(signer, accountAddress, syncServerUri, storage, identityToken);
+  } else {
+    authData = await restoreKeys(signer, accountAddress, syncServerUri, storage, identityToken);
+  }
+  store.send({ type: 'reset' });
+  store.send({
+    ...authData,
+    sessionToken: 'dummy', // not needed in the connect app
+    type: 'setAuth',
+  });
+}

package/src/connect/parse-auth-params.ts

@@ -0,0 +1,37 @@
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import * as Schema from 'effect/Schema';
+import { ConnectAuthPayload, FailedToParseConnectAuthUrl } from '../types.js';
+
+type ParseAuthUrlParams = {
+  data: unknown;
+  redirect: string;
+  nonce: string;
+};
+
+const decodePayload = Schema.decodeEither(ConnectAuthPayload);
+
+export const parseAuthParams = (
+  params: ParseAuthUrlParams,
+): Effect.Effect<{ payload: ConnectAuthPayload; redirect: string; nonce: string }, FailedToParseConnectAuthUrl> => {
+  const { data, redirect, nonce } = params;
+  if (!data || !redirect || !nonce) {
+    return Effect.fail(new FailedToParseConnectAuthUrl({ message: 'Missing data or redirect in callback URL' }));
+  }
+
+  if (nonce.length !== 64) {
+    return Effect.fail(new FailedToParseConnectAuthUrl({ message: 'Invalid nonce' }));
+  }
+
+  try {
+    const result = decodePayload(data as ConnectAuthPayload);
+
+    if (Either.isLeft(result)) {
+      return Effect.fail(new FailedToParseConnectAuthUrl({ message: 'Failed to parse connect auth payload' }));
+    }
+
+    return Effect.succeed({ payload: result.right, redirect, nonce });
+  } catch (error) {
+    return Effect.fail(new FailedToParseConnectAuthUrl({ message: 'Failed to parse connect auth payload' }));
+  }
+};

package/src/connect/parse-callback-params.ts

@@ -0,0 +1,67 @@
+import { bytesToUtf8, hexToBytes } from '@noble/hashes/utils';
+import { cryptoBoxSealOpen } from '@serenity-kit/noble-sodium';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import * as Schema from 'effect/Schema';
+import { ConnectCallbackDecryptedData, type ConnectCallbackResult, FailedToParseAuthCallbackUrl } from '../types.js';
+
+type ParseCallbackUrlParams = {
+  ciphertext: string;
+  nonce: string;
+  storedNonce: string;
+  storedExpiry: number;
+  storedSecretKey: string;
+  storedPublicKey: string;
+};
+
+const decodeDecryptedResult = Schema.decodeEither(ConnectCallbackDecryptedData);
+
+export const parseCallbackParams = ({
+  ciphertext,
+  nonce,
+  storedNonce,
+  storedExpiry,
+  storedSecretKey,
+  storedPublicKey,
+}: ParseCallbackUrlParams): Effect.Effect<ConnectCallbackResult, FailedToParseAuthCallbackUrl> => {
+  if (nonce !== storedNonce) {
+    return Effect.fail(new FailedToParseAuthCallbackUrl({ message: 'Invalid nonce' }));
+  }
+
+  try {
+    const publicKey = hexToBytes(storedPublicKey);
+    const decryptionResult = cryptoBoxSealOpen({
+      ciphertext: hexToBytes(ciphertext),
+      privateKey: hexToBytes(storedSecretKey),
+      publicKey,
+    });
+    const decoded = decodeDecryptedResult(JSON.parse(bytesToUtf8(decryptionResult)));
+    if (Either.isLeft(decoded)) {
+      return Effect.fail(
+        new FailedToParseAuthCallbackUrl({ message: 'Failed to parse connect auth callback payload' }),
+      );
+    }
+    const data = decoded.right;
+    if (data.expiry !== storedExpiry) {
+      return Effect.fail(new FailedToParseAuthCallbackUrl({ message: 'Incorrect expiry' }));
+    }
+    if (data.expiry < Date.now()) {
+      return Effect.fail(new FailedToParseAuthCallbackUrl({ message: 'Expired nonce' }));
+    }
+
+    return Effect.succeed({
+      appIdentityAddress: data.appIdentityAddress,
+      appIdentityAddressPrivateKey: data.appIdentityAddressPrivateKey,
+      signaturePublicKey: data.signaturePublicKey,
+      signaturePrivateKey: data.signaturePrivateKey,
+      encryptionPublicKey: data.encryptionPublicKey,
+      encryptionPrivateKey: data.encryptionPrivateKey,
+      sessionToken: data.sessionToken,
+      sessionTokenExpires: new Date(data.sessionTokenExpires),
+      spaces: data.spaces,
+    });
+  } catch (error) {
+    console.error(error);
+    return Effect.fail(new FailedToParseAuthCallbackUrl({ message: 'Failed to parse connect auth callback payload' }));
+  }
+};

package/src/connect/prove-ownership.ts

@@ -0,0 +1,58 @@
+import { type Hex, verifyMessage } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+import { publicKeyToAddress } from '../utils/index.js';
+import type { IdentityKeys, Signer } from './types.js';
+
+export const getAccountProofMessage = (accountAddress: string, publicKey: string): string => {
+  return `This message proves I am the owner of the account ${accountAddress} and the public key ${publicKey}`;
+};
+
+export const getKeyProofMessage = (accountAddress: string, publicKey: string): string => {
+  return `The public key ${publicKey} is owned by the account ${accountAddress}`;
+};
+
+export const proveIdentityOwnership = async (
+  signer: Signer,
+  accountAddress: string,
+  keys: IdentityKeys,
+): Promise<{ accountProof: string; keyProof: string }> => {
+  const publicKey = keys.signaturePublicKey;
+  const accountProofMessage = getAccountProofMessage(accountAddress, publicKey);
+  const keyProofMessage = getKeyProofMessage(accountAddress, publicKey);
+  const accountProof = await signer.signMessage(accountProofMessage);
+  const account = privateKeyToAccount(keys.signaturePrivateKey as Hex);
+  const keyProof = await account.signMessage({ message: keyProofMessage });
+  return { accountProof, keyProof };
+};
+
+export const verifyIdentityOwnership = async (
+  accountAddress: string,
+  publicKey: string,
+  accountProof: string,
+  keyProof: string,
+): Promise<boolean> => {
+  const accountProofMessage = getAccountProofMessage(accountAddress, publicKey);
+  const keyProofMessage = getKeyProofMessage(accountAddress, publicKey);
+  const validAccountProof = await verifyMessage({
+    address: accountAddress as Hex,
+    message: accountProofMessage,
+    signature: accountProof as Hex,
+  });
+  if (!validAccountProof) {
+    console.log('Invalid account proof');
+    return false;
+  }
+
+  const keyAddress = publicKeyToAddress(publicKey) as Hex;
+  const validKeyProof = await verifyMessage({
+    address: keyAddress,
+    message: keyProofMessage,
+    signature: keyProof as Hex,
+  });
+  if (!validKeyProof) {
+    console.log('Invalid key proof');
+    return false;
+  }
+  return true;
+};

package/src/connect/types.ts

@@ -0,0 +1,67 @@
+import { Schema } from 'effect';
+
+export type Storage = {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+};
+
+export type SignMessage = (message: string) => Promise<string> | string;
+export type GetAddress = () => Promise<string> | string;
+export type Signer = {
+  getAddress: GetAddress;
+  signMessage: SignMessage;
+};
+
+export type IdentityKeys = {
+  encryptionPublicKey: string;
+  encryptionPrivateKey: string;
+  signaturePublicKey: string;
+  signaturePrivateKey: string;
+};
+
+export const KeysSchema = Schema.Struct({
+  encryptionPublicKey: Schema.String,
+  encryptionPrivateKey: Schema.String,
+  signaturePublicKey: Schema.String,
+  signaturePrivateKey: Schema.String,
+});
+
+export type KeysSchema = Schema.Schema.Type<typeof KeysSchema>;
+
+export const AppIdentityResponse = Schema.Struct({
+  accountAddress: Schema.String,
+  signaturePublicKey: Schema.String,
+  encryptionPublicKey: Schema.String,
+  accountProof: Schema.String,
+  keyProof: Schema.String,
+  ciphertext: Schema.String,
+  nonce: Schema.String,
+  sessionToken: Schema.String,
+  address: Schema.String,
+  appId: Schema.String,
+  sessionTokenExpires: Schema.String,
+});
+
+export type AppIdentityResponse = Schema.Schema.Type<typeof AppIdentityResponse>;
+
+export type Identity = IdentityKeys & {
+  accountAddress: string;
+};
+
+export type PublicAppIdentity = {
+  address: string;
+  encryptionPublicKey: string;
+  signaturePublicKey: string;
+};
+
+export type PrivateAppIdentity = IdentityKeys & {
+  address: string;
+  addressPrivateKey: string;
+  sessionToken: string;
+  sessionTokenExpires: Date;
+};
+
+export class InvalidIdentityError {
+  readonly _tag = 'InvalidIdentityError';
+}

package/src/entity/create.ts

@@ -0,0 +1,58 @@
+import type { DocHandle } from '@automerge/automerge-repo';
+import * as Schema from 'effect/Schema';
+import { generateId } from '../utils/generateId.js';
+import { isRelationField } from '../utils/isRelationField.js';
+import { findOne } from './findOne.js';
+import type { AnyNoContext, DocumentContent, DocumentRelation, Entity, Insert } from './types.js';
+
+/**
+ * Creates an entity model of given type and stores it in the repo.
+ */
+export const create = <const S extends AnyNoContext>(handle: DocHandle<DocumentContent>, type: S) => {
+  // TODO: what's the right way to get the name of the type?
+  // @ts-expect-error name is defined
+  const typeName = type.name;
+  const encode = Schema.encodeSync(type.insert);
+
+  return (data: Readonly<Schema.Schema.Type<Insert<S>>>): Entity<S> => {
+    const entityId = generateId();
+    const encoded = encode(data);
+
+    const relations: Record<string, DocumentRelation> = {};
+
+    for (const [propertyName, field] of Object.entries(type.fields)) {
+      if (isRelationField(field) && encoded[propertyName]) {
+        for (const toEntityId of encoded[propertyName]) {
+          const relationId = generateId();
+          relations[relationId] = {
+            from: entityId,
+            to: toEntityId,
+            fromTypeName: typeName,
+            fromPropertyName: propertyName,
+            __deleted: false,
+          };
+        }
+        // we create the relation object in the repo, so we don't need it in the entity
+        delete encoded[propertyName];
+      }
+    }
+
+    // apply changes to the repo -> adds the entity to the repo entities document
+    handle.change((doc) => {
+      doc.entities ??= {};
+      doc.entities[entityId] = {
+        ...encoded,
+        '@@types@@': [typeName],
+        __deleted: false,
+        __version: '',
+      };
+      doc.relations ??= {};
+      // merge relations with existing relations
+      for (const [relationId, relation] of Object.entries(relations)) {
+        doc.relations[relationId] = relation;
+      }
+    });
+
+    return findOne(handle, type)(entityId) as Entity<S>;
+  };
+};

package/src/entity/decodedEntitiesCache.ts

@@ -0,0 +1,38 @@
+import type * as Schema from 'effect/Schema';
+import type { AnyNoContext, Entity } from './types.js';
+
+export type QueryEntry = {
+  data: Array<Entity<AnyNoContext>>; // holds the decoded entities of this query and must be a stable reference and use the same reference for the `entities` array
+  listeners: Array<() => void>; // listeners to this query
+  isInvalidated: boolean;
+  include: { [K in keyof Schema.Schema.Type<AnyNoContext>]?: Record<string, never> };
+};
+
+export type DecodedEntitiesCacheEntry = {
+  decoder: (data: unknown) => unknown;
+  type: AnyNoContext; // TODO should be the type of the entity
+  entities: Map<string, Entity<AnyNoContext>>; // holds all entities of this type
+  queries: Map<
+    string, // instead of serializedQueryKey as string we could also have the actual params
+    QueryEntry
+  >;
+  isInvalidated: boolean;
+};
+
+/*
+/*
+ * Note: Currently we only use one global cache for all entities.
+ * In the future we probably want a build function that creates a cache and returns the
+ * functions (create, update, findMany, …) that use this specific cache.
+ *
+ * How does it work?
+ *
+ * We store all decoded entities in a cache and for each query we reference the entities relevant to this query.
+ * Whenever a query is registered we add it to the cache and add a listener to the query. Whenever a query is unregistered we remove the listener from the query.
+ */
+type DecodedEntitiesCache = Map<
+  string, // type name
+  DecodedEntitiesCacheEntry
+>;
+
+export const decodedEntitiesCache: DecodedEntitiesCache = new Map();