cojson 0.19.22 → 0.20.1

package/src/coValueCore/SessionMap.ts

@@ -7,7 +7,7 @@ import type {
   Signature,
   SignerID,
 } from "../crypto/crypto.js";
-import { RawCoID, SessionID } from "../ids.js";
+import { isDeleteSessionID, RawCoID, SessionID } from "../ids.js";
 import { parseJSON, Stringified } from "../jsonStringify.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { TryAddTransactionsError } from "./coValueCore.js";
@@ -34,6 +34,7 @@ export type SessionLog = {
 };
 
 export class SessionMap {
+  private isDeleted: boolean = false;
   sessions: Map<SessionID, SessionLog> = new Map();
 
   // Known state related properies, mutated when adding transactions to the session map
@@ -60,7 +61,32 @@ export class SessionMap {
     }
   }
 
+  markAsDeleted() {
+    this.isDeleted = true;
+
+    // We reset the known state to report only the deleted session/transaction
+    this.knownState = { id: this.id, header: true, sessions: {} };
+
+    // We remove the streaming statuses, because once deleted we don't need
+    // to wait for any streaming to be completed
+    this.knownStateWithStreaming = undefined;
+    this.streamingKnownState = undefined;
+    this.invalidateKnownStateCache();
+
+    for (const [sessionID, sessionLog] of this.sessions.entries()) {
+      if (!isDeleteSessionID(sessionID)) {
+        continue;
+      }
+
+      this.knownState.sessions[sessionID] = sessionLog.transactions.length;
+    }
+  }
+
   setStreamingKnownState(streamingKnownState: KnownStateSessions) {
+    if (this.isDeleted) {
+      return;
+    }
+
     // if the streaming known state is a subset of the current known state, we can skip the update
     if (isKnownStateSubsetOf(streamingKnownState, this.knownState.sessions)) {
       return;
@@ -148,6 +174,10 @@ export class SessionMap {
     newSignature: Signature,
     skipVerify: boolean = false,
   ) {
+    if (this.isDeleted && !isDeleteSessionID(sessionID)) {
+      throw new Error("Cannot add transactions to a deleted coValue");
+    }
+
     const sessionLog = this.getOrCreateSessionLog(sessionID, signerID);
 
     sessionLog.impl.tryAdd(newTransactions, newSignature, skipVerify);
@@ -164,6 +194,12 @@ export class SessionMap {
     meta: JsonObject | undefined,
     madeAt: number,
   ): { signature: Signature; transaction: Transaction } {
+    if (this.isDeleted) {
+      throw new Error(
+        "Cannot make new private transaction on a deleted coValue",
+      );
+    }
+
     const sessionLog = this.getOrCreateSessionLog(
       sessionID,
       signerAgent.currentSignerID(),
@@ -194,6 +230,12 @@ export class SessionMap {
     meta: JsonObject | undefined,
     madeAt: number,
   ): { signature: Signature; transaction: Transaction } {
+    if (this.isDeleted) {
+      throw new Error(
+        "Cannot make new trusting transaction on a deleted coValue",
+      );
+    }
+
     const sessionLog = this.getOrCreateSessionLog(
       sessionID,
       signerAgent.currentSignerID(),

package/src/coValueCore/coValueCore.ts

@@ -1,10 +1,13 @@
 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 type { LoadMode } from "../queue/OutgoingLoadQueue.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 +17,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 +36,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 +65,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 +250,8 @@ export class CoValueCore {
   // context
   readonly node: LocalNode;
   private readonly crypto: CryptoProvider;
+  // Whether the coValue is deleted
+  public isDeleted: boolean = false;
 
   // state
   id: RawCoID;
@@ -492,6 +547,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) {
@@ -559,6 +623,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;
   }
@@ -593,6 +684,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
    */
@@ -602,8 +794,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),
@@ -629,6 +835,16 @@ export class CoValueCore {
       };
     }
 
+    const isDeleteTransaction = this.#isDeleteTransaction(
+      sessionID,
+      newTransactions,
+      skipVerify,
+    );
+
+    if (isDeleteTransaction.err) {
+      return isDeleteTransaction.err;
+    }
+
     try {
       this.verified.tryAddTransactions(
         sessionID,
@@ -638,6 +854,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();
@@ -646,6 +869,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;
@@ -743,6 +1038,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
    */
@@ -757,11 +1116,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,
@@ -769,6 +1134,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 };
@@ -801,6 +1172,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
@@ -1266,6 +1641,14 @@ export class CoValueCore {
     this.dependant.add(dependant);
   }
 
+  isGroupOrAccount() {
+    if (!this.verified) {
+      return false;
+    }
+
+    return this.verified.header.ruleset.type === "group";
+  }
+
   isGroup() {
     if (!this.verified) {
       return false;
@@ -1465,11 +1848,11 @@ export class CoValueCore {
     return this.node.syncManager.waitForSync(this.id, options?.timeout);
   }
 
-  load(peers: PeerState[]) {
+  load(peers: PeerState[], mode?: LoadMode) {
     this.loadFromStorage((found) => {
       // When found the load is triggered by handleNewContent
       if (!found) {
-        this.loadFromPeers(peers);
+        this.loadFromPeers(peers, mode);
       }
     });
   }
@@ -1555,7 +1938,7 @@ export class CoValueCore {
     this.node.storage.loadKnownState(this.id, done);
   }
 
-  loadFromPeers(peers: PeerState[]) {
+  loadFromPeers(peers: PeerState[], mode?: LoadMode) {
     if (peers.length === 0) {
       return;
     }
@@ -1565,29 +1948,17 @@ export class CoValueCore {
 
       if (currentState === "unknown" || currentState === "unavailable") {
         this.markPending(peer.id);
-        this.internalLoadFromPeer(peer);
+        this.internalLoadFromPeer(peer, mode);
       }
     }
   }
 
-  private internalLoadFromPeer(peer: PeerState) {
+  private internalLoadFromPeer(peer: PeerState, mode?: LoadMode) {
     if (peer.closed && !peer.persistent) {
       this.markNotFoundInPeer(peer.id);
       return;
     }
 
-    /**
-     * On reconnection persistent peers will automatically fire the load request
-     * as part of the reconnection process.
-     */
-    if (!peer.closed) {
-      peer.pushOutgoingMessage({
-        action: "load",
-        ...this.knownState(),
-      });
-      peer.trackLoadRequestSent(this.id);
-    }
-
     const markNotFound = () => {
       if (this.getLoadingStateForPeer(peer.id) === "pending") {
         logger.warn("Timeout waiting for peer to load coValue", {
@@ -1598,11 +1969,19 @@ export class CoValueCore {
       }
     };
 
-    const timeout = setTimeout(markNotFound, CO_VALUE_LOADING_CONFIG.TIMEOUT);
+    // Close listener for non-persistent peers
     const removeCloseListener = peer.persistent
       ? undefined
       : peer.addCloseListener(markNotFound);
 
+    /**
+     * On reconnection persistent peers will automatically fire the load request
+     * as part of the reconnection process.
+     */
+    if (!peer.closed) {
+      peer.sendLoadRequest(this, mode);
+    }
+
     this.subscribe((state, unsubscribe) => {
       const peerState = state.getLoadingStateForPeer(peer.id);
       if (
@@ -1613,7 +1992,6 @@ export class CoValueCore {
       ) {
         unsubscribe();
         removeCloseListener?.();
-        clearTimeout(timeout);
       }
     }, true);
   }
@@ -1645,9 +2023,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;