cojson 0.19.21 → 0.20.0

package/src/coValueCore/coValueCore.ts

@@ -1,10 +1,12 @@
 import { UpDownCounter, ValueType, metrics } from "@opentelemetry/api";
 import type { PeerState } from "../PeerState.js";
 import type { RawCoValue } from "../coValue.js";
-import type { ControlledAccountOrAgent } from "../coValues/account.js";
+import {
+  RawAccount,
+  type ControlledAccountOrAgent,
+} from "../coValues/account.js";
 import type { RawGroup } from "../coValues/group.js";
 import { CO_VALUE_LOADING_CONFIG } from "../config.js";
-import { validateTxSizeLimitInBytes } from "../coValueContentMessage.js";
 import { coreToCoValue } from "../coreToCoValue.js";
 import {
   CryptoProvider,
@@ -14,12 +16,18 @@ import {
   Signature,
   SignerID,
 } from "../crypto/crypto.js";
-import { AgentID, RawCoID, SessionID, TransactionID } from "../ids.js";
+import {
+  AgentID,
+  isDeleteSessionID,
+  RawCoID,
+  SessionID,
+  TransactionID,
+} from "../ids.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { LocalNode, ResolveAccountAgentError } from "../localNode.js";
 import { logger } from "../logger.js";
 import { determineValidTransactions } from "../permissions.js";
-import { NewContentMessage, PeerID } from "../sync.js";
+import { KnownStateMessage, NewContentMessage, PeerID } from "../sync.js";
 import { accountOrAgentIDfromSessionID } from "../typeUtils/accountOrAgentIDfromSessionID.js";
 import { expectGroup } from "../typeUtils/expectGroup.js";
 import {
@@ -27,7 +35,12 @@ import {
   getDependenciesFromGroupRawTransactions,
   getDependenciesFromHeader,
 } from "./utils.js";
-import { CoValueHeader, Transaction, VerifiedState } from "./verifiedState.js";
+import {
+  CoValueHeader,
+  Transaction,
+  Uniqueness,
+  VerifiedState,
+} from "./verifiedState.js";
 import { SessionMap } from "./SessionMap.js";
 import {
   MergeCommit,
@@ -51,6 +64,45 @@ import {
 } from "../knownState.js";
 import { safeParseJSON } from "../jsonStringify.js";
 
+export type ValidationValue =
+  | { isOk: true }
+  | {
+      isOk: false;
+      message: string;
+    };
+
+function validateUniqueness(uniqueness: Uniqueness): ValidationValue {
+  if (typeof uniqueness === "number" && !Number.isInteger(uniqueness)) {
+    return {
+      isOk: false,
+      message: "Uniqueness cannot be a non-integer number, got " + uniqueness,
+    };
+  }
+
+  if (Array.isArray(uniqueness)) {
+    return {
+      isOk: false,
+      message: "Uniqueness cannot be an array, got " + uniqueness,
+    };
+  }
+
+  if (typeof uniqueness === "object" && uniqueness !== null) {
+    for (let [key, value] of Object.entries(uniqueness)) {
+      if (typeof value !== "string") {
+        return {
+          isOk: false,
+          message:
+            "Uniqueness object values must be a string, got " +
+            value +
+            " for key " +
+            key,
+        };
+      }
+    }
+  }
+  return { isOk: true };
+}
+
 export function idforHeader(
   header: CoValueHeader,
   crypto: CryptoProvider,
@@ -197,6 +249,8 @@ export class CoValueCore {
   // context
   readonly node: LocalNode;
   private readonly crypto: CryptoProvider;
+  // Whether the coValue is deleted
+  public isDeleted: boolean = false;
 
   // state
   id: RawCoID;
@@ -373,16 +427,26 @@ export class CoValueCore {
     }
   }
 
-  unmount(garbageCollectGroups = false) {
-    if (
-      !garbageCollectGroups &&
-      this.verified?.header.ruleset.type === "group"
-    ) {
+  /**
+   * Removes the CoValue from memory.
+   *
+   * @returns true if the coValue was successfully unmounted, false otherwise
+   */
+  unmount(): boolean {
+    if (this.listeners.size > 0) {
+      // The coValue is still in use
       return false;
     }
 
-    if (this.listeners.size > 0) {
-      return false; // The coValue is still in use
+    for (const dependant of this.dependant) {
+      if (this.node.hasCoValue(dependant)) {
+        // Another in-memory coValue depends on this coValue
+        return false;
+      }
+    }
+
+    if (!this.node.syncManager.isSyncedToServerPeers(this.id)) {
+      return false;
     }
 
     this.counter.add(-1, { state: this.loadingState });
@@ -482,6 +546,15 @@ export class CoValueCore {
     skipVerify?: boolean,
   ) {
     if (!skipVerify) {
+      const validation = validateUniqueness(header.uniqueness);
+      if (!validation.isOk) {
+        logger.error("Invalid uniqueness", {
+          header,
+          errorMessage: validation.message,
+        });
+        return false;
+      }
+
       const expectedId = idforHeader(header, this.node.crypto);
 
       if (this.id !== expectedId) {
@@ -549,6 +622,33 @@ export class CoValueCore {
     return this.verified?.immutableKnownState() ?? emptyKnownState(this.id);
   }
 
+  /**
+   * Returns a known state message to signal to the peer that the coValue doesn't need to be synced anymore
+   *
+   * Implemented to be backward compatible with clients that don't support deleted coValues
+   */
+  stopSyncingKnownStateMessage(
+    peerKnownState: CoValueKnownState | undefined,
+  ): KnownStateMessage {
+    if (!peerKnownState) {
+      return {
+        action: "known",
+        ...this.knownState(),
+      };
+    }
+
+    const knownState = cloneKnownState(this.knownState());
+
+    // We combine everything for backward compatibility with clients that don't support deleted coValues
+    // This way they won't try to sync their own content that we have discarded because the coValue is deleted
+    combineKnownStateSessions(knownState.sessions, peerKnownState.sessions);
+
+    return {
+      action: "known",
+      ...knownState,
+    };
+  }
+
   get meta(): JsonValue {
     return this.verified?.header.meta ?? null;
   }
@@ -583,6 +683,107 @@ export class CoValueCore {
     }
   }
 
+  #isDeleteTransaction(
+    sessionID: SessionID,
+    newTransactions: Transaction[],
+    skipVerify: boolean,
+  ) {
+    if (!this.verified) {
+      return {
+        value: false,
+      };
+    }
+
+    // Detect + validate delete transactions during ingestion
+    // Delete transactions are:
+    // - in a delete session (sessionID ends with `$`)
+    // - trusting (unencrypted)
+    // - have meta `{ deleted: true }`
+    let deleteTransaction: Transaction | undefined = undefined;
+
+    if (isDeleteSessionID(sessionID)) {
+      const txCount =
+        this.verified.sessions.get(sessionID)?.transactions.length ?? 0;
+      if (txCount > 0 || newTransactions.length > 1) {
+        return {
+          value: true,
+          err: {
+            type: "DeleteTransactionRejected",
+            id: this.id,
+            sessionID,
+            reason: "InvalidDeleteTransaction",
+            error: new Error(
+              "Delete transaction must be the only transaction in the session",
+            ),
+          } as const,
+        };
+      }
+
+      const firstTransaction = newTransactions[0];
+      const deleteMarker =
+        firstTransaction && this.#getDeleteMarker(firstTransaction);
+
+      if (deleteMarker) {
+        deleteTransaction = firstTransaction;
+
+        if (deleteMarker.deleted !== this.id) {
+          return {
+            value: true,
+            err: {
+              type: "DeleteTransactionRejected",
+              id: this.id,
+              sessionID,
+              reason: "InvalidDeleteTransaction",
+              error: new Error(
+                `Delete transaction ID mismatch: expected ${this.id}, got ${deleteMarker.deleted}`,
+              ),
+            } as const,
+          };
+        }
+      }
+
+      if (this.isGroupOrAccount()) {
+        return {
+          value: true,
+          err: {
+            type: "DeleteTransactionRejected",
+            id: this.id,
+            sessionID,
+            reason: "CoValueNotDeletable",
+            error: new Error("Cannot delete Group or Account coValues"),
+          },
+        } as const;
+      }
+    }
+
+    if (!skipVerify && deleteTransaction) {
+      const author = accountOrAgentIDfromSessionID(sessionID);
+
+      const permission = this.#canAuthorDeleteCoValueAtTime(
+        author,
+        deleteTransaction.madeAt,
+      );
+
+      if (!permission.ok) {
+        return {
+          value: true,
+          err: {
+            type: "DeleteTransactionRejected",
+            id: this.id,
+            sessionID,
+            author,
+            reason: permission.reason,
+            error: new Error(permission.message),
+          },
+        } as const;
+      }
+    }
+
+    return {
+      value: Boolean(deleteTransaction),
+    };
+  }
+
   /**
    * Apply new transactions that were not generated by the current node to the CoValue
    */
@@ -592,8 +793,22 @@ export class CoValueCore {
     newSignature: Signature,
     skipVerify: boolean = false,
   ) {
+    if (newTransactions.length === 0) {
+      return;
+    }
+
     let signerID: SignerID | undefined;
 
+    // sync should never try to add transactions to a deleted coValue
+    // this can only happen if `tryAddTransactions` is called directly, without going through `handleNewContent`
+    if (this.isDeleted && !isDeleteSessionID(sessionID)) {
+      return {
+        type: "CoValueDeleted",
+        id: this.id,
+        error: new Error("Cannot add transactions to a deleted coValue"),
+      } as const;
+    }
+
     if (!skipVerify) {
       const result = this.node.resolveAccountAgent(
         accountOrAgentIDfromSessionID(sessionID),
@@ -619,6 +834,16 @@ export class CoValueCore {
       };
     }
 
+    const isDeleteTransaction = this.#isDeleteTransaction(
+      sessionID,
+      newTransactions,
+      skipVerify,
+    );
+
+    if (isDeleteTransaction.err) {
+      return isDeleteTransaction.err;
+    }
+
     try {
       this.verified.tryAddTransactions(
         sessionID,
@@ -628,6 +853,13 @@ export class CoValueCore {
         skipVerify,
       );
 
+      // Mark deleted state when a delete marker transaction is accepted.
+      // - In skipVerify mode (storage shards), we accept + mark without permission checks.
+      // - In verify mode, we only reach here if the delete permission check passed.
+      if (isDeleteTransaction.value) {
+        this.#markAsDeleted();
+      }
+
       this.processNewTransactions();
       this.scheduleNotifyUpdate();
       this.invalidateDependants();
@@ -636,6 +868,78 @@ export class CoValueCore {
     }
   }
 
+  #markAsDeleted() {
+    this.isDeleted = true;
+    this.verified?.markAsDeleted();
+  }
+
+  #getDeleteMarker(tx: Transaction): { deleted: RawCoID } | undefined {
+    if (tx.privacy !== "trusting") {
+      return;
+    }
+    if (!tx.meta) {
+      return;
+    }
+    const meta = safeParseJSON(tx.meta);
+
+    return meta && typeof meta.deleted === "string"
+      ? (meta as { deleted: RawCoID })
+      : undefined;
+  }
+
+  #canAuthorDeleteCoValueAtTime(
+    author: RawAccountID | AgentID,
+    madeAt: number,
+  ):
+    | { ok: true }
+    | {
+        ok: false;
+        reason: DeleteTransactionRejectedError["reason"];
+        message: string;
+      } {
+    if (!this.verified) {
+      return {
+        ok: false,
+        reason: "CannotVerifyPermissions",
+        message: "Cannot verify delete permissions without verified state",
+      };
+    }
+
+    if (this.isGroupOrAccount()) {
+      return {
+        ok: false,
+        reason: "CoValueNotDeletable",
+        message: "Cannot delete Group or Account coValues",
+      };
+    }
+
+    const group = this.safeGetGroup();
+
+    // Today, delete permission is defined in terms of group-admin on the owning group.
+    // If we cannot derive that (non-owned coValues), we reject the delete when verification is required.
+    if (!group) {
+      return {
+        ok: false,
+        reason: "CannotVerifyPermissions",
+        message:
+          "Cannot verify delete permissions for coValues not owned by a group",
+      };
+    }
+
+    const groupAtTime = group.atTime(madeAt);
+    const role = groupAtTime.roleOfInternal(author);
+
+    if (role !== "admin") {
+      return {
+        ok: false,
+        reason: "NotAdmin",
+        message: "Delete transaction rejected: author is not an admin",
+      };
+    }
+
+    return { ok: true };
+  }
+
   notifyDependants() {
     if (!this.isGroup()) {
       return;
@@ -733,6 +1037,70 @@ export class CoValueCore {
     };
   }
 
+  validateDeletePermissions() {
+    if (!this.verified) {
+      return {
+        ok: false,
+        reason: "CannotVerifyPermissions",
+        message: "Cannot verify delete permissions without verified state",
+      };
+    }
+
+    if (this.isGroupOrAccount()) {
+      return {
+        ok: false,
+        reason: "CoValueNotDeletable",
+        message: "Cannot delete Group or Account coValues",
+      };
+    }
+
+    const group = this.safeGetGroup();
+    if (!group) {
+      return {
+        ok: false,
+        reason: "CannotVerifyPermissions",
+        message:
+          "Cannot verify delete permissions for coValues not owned by a group",
+      };
+    }
+
+    const role = group.myRole();
+    if (role !== "admin") {
+      return {
+        ok: false,
+        reason: "NotAdmin",
+        message:
+          "The current account lacks admin permissions to delete this coValue",
+      };
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Creates a delete marker transaction for this CoValue and sets the coValue as deleted
+   *
+   * Constraints:
+   * - Account and Group CoValues cannot be deleted.
+   * - Only admins can delete a coValue.
+   */
+  deleteCoValue() {
+    if (this.isDeleted) {
+      return;
+    }
+
+    const result = this.validateDeletePermissions();
+    if (!result.ok) {
+      throw new Error(result.message);
+    }
+
+    this.makeTransaction(
+      [], // Empty changes array
+      "trusting", // Unencrypted
+      { deleted: this.id }, // Delete metadata
+    );
+  }
+
   /**
    * Creates a new transaction with local changes and syncs it to all peers
    */
@@ -747,11 +1115,17 @@ export class CoValueCore {
         "CoValueCore: makeTransaction called on coValue without verified state",
       );
     }
+    const isDeleteTransaction = Boolean(meta?.deleted);
 
-    validateTxSizeLimitInBytes(changes);
+    if (this.isDeleted && !isDeleteTransaction) {
+      logger.error("Cannot make transaction on a deleted coValue", {
+        id: this.id,
+      });
+      return false;
+    }
 
     // This is an ugly hack to get a unique but stable session ID for editing the current account
-    const sessionID =
+    let sessionID =
       this.verified.header.meta?.type === "account"
         ? (this.node.currentSessionID.replace(
             this.node.getCurrentAgent().id,
@@ -759,6 +1133,12 @@ export class CoValueCore {
           ) as SessionID)
         : this.node.currentSessionID;
 
+    if (isDeleteTransaction) {
+      sessionID = this.crypto.newDeleteSessionID(
+        this.node.getCurrentAccountOrAgentID(),
+      );
+    }
+
     const signerAgent = this.node.getCurrentAgent();
 
     let result: { signature: Signature; transaction: Transaction };
@@ -791,6 +1171,10 @@ export class CoValueCore {
       );
     }
 
+    if (isDeleteTransaction) {
+      this.#markAsDeleted();
+    }
+
     const { transaction } = result;
 
     // Assign pre-parsed meta and changes to skip the parse/decrypt operation when loading
@@ -1193,6 +1577,15 @@ export class CoValueCore {
     return matchingTransactions;
   }
 
+  /**
+   * The CoValues that this CoValue depends on.
+   * We currently track dependencies for:
+   * - Ownership (a CoValue depends on its account/group owner)
+   * - Group membership (a group depends on its direct account/group members)
+   * - Sessions (a CoValue depends on Accounts that made changes to it)
+   * - Branches (a branched CoValue depends on its branch source)
+   * See {@link dependant} for the CoValues that depend on this CoValue.
+   */
   dependencies: Set<RawCoID> = new Set();
   incompleteDependencies: Set<RawCoID> = new Set();
   private addDependency(dependency: RawCoID) {
@@ -1238,11 +1631,23 @@ export class CoValueCore {
     }
   }
 
+  /**
+   * The CoValues that depend on this CoValue.
+   * This is the inverse relationship of {@link dependencies}.
+   */
   dependant: Set<RawCoID> = new Set();
   private addDependant(dependant: RawCoID) {
     this.dependant.add(dependant);
   }
 
+  isGroupOrAccount() {
+    if (!this.verified) {
+      return false;
+    }
+
+    return this.verified.header.ruleset.type === "group";
+  }
+
   isGroup() {
     if (!this.verified) {
       return false;
@@ -1622,9 +2027,19 @@ export type TriedToAddTransactionsWithoutSignerIDError = {
   sessionID: SessionID;
 };
 
+export type DeleteTransactionRejectedError = {
+  type: "DeleteTransactionRejected";
+  id: RawCoID;
+  sessionID: SessionID;
+  author: RawAccountID | AgentID;
+  reason: "NotAdmin" | "CoValueNotDeletable" | "CannotVerifyPermissions";
+  error: Error;
+};
+
 export type TryAddTransactionsError =
   | TriedToAddTransactionsWithoutVerifiedStateErrpr
   | TriedToAddTransactionsWithoutSignerIDError
   | ResolveAccountAgentError
   | InvalidHashError
-  | InvalidSignatureError;
+  | InvalidSignatureError
+  | DeleteTransactionRejectedError;

package/src/coValueCore/verifiedState.ts

@@ -14,12 +14,16 @@ import {
   Signature,
   SignerID,
 } from "../crypto/crypto.js";
-import { RawCoID, SessionID, TransactionID } from "../ids.js";
+import {
+  isDeleteSessionID,
+  RawCoID,
+  SessionID,
+  TransactionID,
+} from "../ids.js";
 import { Stringified } from "../jsonStringify.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { PermissionsDef as RulesetDef } from "../permissions.js";
 import { NewContentMessage } from "../sync.js";
-import { TryAddTransactionsError } from "./coValueCore.js";
 import { SessionMap } from "./SessionMap.js";
 import { ControlledAccountOrAgent } from "../coValues/account.js";
 import {
@@ -35,10 +39,19 @@ export type CoValueHeader = {
 } & CoValueUniqueness;
 
 export type CoValueUniqueness = {
-  uniqueness: JsonValue;
+  uniqueness: Uniqueness;
   createdAt?: `2${string}` | null;
 };
 
+export type Uniqueness =
+  | string
+  | boolean
+  | null
+  | undefined
+  | {
+      [key: string]: string;
+    };
+
 export type PrivateTransaction = {
   privacy: "private";
   madeAt: number;
@@ -63,6 +76,7 @@ export class VerifiedState {
   public lastAccessed: number | undefined;
   public branchSourceId?: RawCoID;
   public branchName?: string;
+  private isDeleted: boolean = false;
 
   constructor(
     id: RawCoID,
@@ -87,6 +101,11 @@ export class VerifiedState {
     );
   }
 
+  markAsDeleted() {
+    this.isDeleted = true;
+    this.sessions.markAsDeleted();
+  }
+
   tryAddTransactions(
     sessionID: SessionID,
     signerID: SignerID | undefined,
@@ -199,6 +218,10 @@ export class VerifiedState {
     const sessionSent = knownState?.sessions;
 
     for (const [sessionID, log] of this.sessions.sessions) {
+      if (this.isDeleted && !isDeleteSessionID(sessionID)) {
+        continue;
+      }
+
       const startFrom = sessionSent?.[sessionID] ?? 0;
 
       let currentSessionSize = 0;

package/src/coValues/coList.ts

@@ -59,14 +59,14 @@ export class RawCoList<
   afterStart: OpID[] = [];
   beforeEnd: OpID[] = [];
   insertions: {
-    [sessionID: SessionID]: {
+    [sessionID: SessionIndex]: {
       [txIdx: number]: {
         [changeIdx: number]: InsertionEntry<Item>;
       };
     };
   } = {};
   deletionsByInsertion: {
-    [deletedSessionID: SessionID]: {
+    [deletedSessionID: SessionIndex]: {
       [deletedTxIdx: number]: {
         [deletedChangeIdx: number]: DeletionEntry[];
       };
@@ -700,7 +700,9 @@ export class RawCoList<
   }
 }
 
-function getSessionIndex(txID: TransactionID): SessionID {
+type SessionIndex = SessionID | `${SessionID}_branch_${RawCoID}`;
+
+function getSessionIndex(txID: TransactionID): SessionIndex {
   if (txID.branch) {
     return `${txID.sessionID}_branch_${txID.branch}`;
   }

package/src/coValues/group.ts

@@ -1203,12 +1203,11 @@ export class RawGroup<
 
     this.set(memberKey, "revoked", "trusting");
 
-    // TODO: removeMember fails silently. Uncomment this will be a breaking change
-    // if (this.get(memberKey) !== "revoked") {
-    //   throw new Error(
-    //     `Failed to revoke role to ${memberKey} (role of current account is ${this.myRole()})`,
-    //   );
-    // }
+    if (this.get(memberKey) !== "revoked") {
+      throw new Error(
+        `Failed to revoke role to ${memberKey} (role of current account is ${this.myRole()})`,
+      );
+    }
   }
 
   /**