operation.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
//
// Copyright (c) 2024-2026 TripleACS Pty Ltd t/a 2pi Software

//! CRDT-style operation types for the Krillnotes operation log.

use crate::core::hlc::HlcTimestamp;
use crate::FieldValue;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// A single document mutation recorded in the workspace operation log.
///
/// Operations capture the full intent of each change so they can be
/// replayed, merged, or synced across devices in a future sync phase.
/// Every variant carries a stable `operation_id`, an HLC `timestamp`,
/// and the `device_id` of the originating machine.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum Operation {
    /// A new note was inserted into the workspace hierarchy.
    CreateNote {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID assigned to the new note.
        note_id: String,
        /// Parent note ID, or `None` for a root note.
        parent_id: Option<String>,
        /// Fractional position among siblings.
        position: f64,
        /// Schema type of the new note.
        schema: String,
        /// Initial title of the new note.
        title: String,
        /// Initial field values of the new note.
        fields: BTreeMap<String, FieldValue>,
        /// Public key (base64) of the identity that created this note.
        created_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// The title of an existing note was updated.
    UpdateNote {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the note whose title was updated.
        note_id: String,
        /// New title for the note.
        title: String,
        /// Public key (base64) of the identity that modified this note.
        modified_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A single schema field on an existing note was updated.
    UpdateField {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the note whose field was updated.
        note_id: String,
        /// Name of the field that changed.
        field: String,
        /// New value for the field.
        value: FieldValue,
        /// Public key (base64) of the identity that modified this note.
        modified_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A note (and all its descendants) was deleted.
    DeleteNote {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the deleted note.
        note_id: String,
        /// Public key (base64) of the identity that deleted this note.
        deleted_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A note was relocated to a new parent or position.
    MoveNote {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the note that was moved.
        note_id: String,
        /// New parent note ID, or `None` to move to root level.
        new_parent_id: Option<String>,
        /// New fractional position among siblings.
        new_position: f64,
        /// Public key (base64) of the identity that moved this note.
        moved_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// The tags on an existing note were replaced.
    SetTags {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the note whose tags were updated.
        note_id: String,
        /// Full replacement tag list (normalised).
        tags: Vec<String>,
        /// Public key (base64) of the identity that modified this note.
        modified_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A new user script was created.
    CreateUserScript {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID assigned to the new script.
        script_id: String,
        /// Script name (from front matter).
        name: String,
        /// Script description (from front matter).
        description: String,
        /// Full Rhai source code.
        source_code: String,
        /// Position in load order.
        load_order: i32,
        /// Whether the script is active.
        enabled: bool,
        /// Public key (base64) of the identity that created this script.
        created_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// An existing user script was modified (source, enabled state, or load order).
    UpdateUserScript {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the script that was modified.
        script_id: String,
        /// Updated script name.
        name: String,
        /// Updated script description.
        description: String,
        /// Updated full source code.
        source_code: String,
        /// Updated load order.
        load_order: i32,
        /// Updated enabled state.
        enabled: bool,
        /// Public key (base64) of the identity that modified this script.
        modified_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A user script was deleted.
    DeleteUserScript {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the deleted script.
        script_id: String,
        /// Public key (base64) of the identity that deleted this script.
        deleted_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A schema was updated and notes were migrated to the new version.
    UpdateSchema {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the migration ran.
        timestamp: HlcTimestamp,
        /// ID of the device that performed the migration.
        device_id: String,
        /// The schema that was updated.
        schema_name: String,
        /// The minimum note version before migration.
        from_version: u32,
        /// The schema version notes were migrated to.
        to_version: u32,
        /// Number of notes that were migrated.
        notes_migrated: u32,
        /// Public key (base64) of the identity that ran the migration.
        updated_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// Reverses one or more previously logged operations (undo).
    ///
    /// `retracted_ids` lists all operation IDs this retract covers.
    /// A note save emits title + N field ops; one retract covers all of them.
    RetractOperation {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// Operation IDs that this retract reverses.
        retracted_ids: Vec<String>,
        /// The inverse data needed to restore the previous state.
        inverse: crate::RetractInverse,
        /// `false` for textarea (CRDT) field retracts — excluded from `.swarm` diffs.
        propagate: bool,
    },
    /// A permission was granted on a note subtree.
    ///
    /// `note_id = None` means the grant covers the entire workspace.
    SetPermission {
        operation_id: String,
        timestamp: HlcTimestamp,
        device_id: String,
        /// Target note (subtree root), or None for workspace-level grant.
        note_id: Option<String>,
        /// Public key (base64) of the identity receiving the permission.
        user_id: String,
        /// Role being granted: "owner" | "writer" | "reader" | "none".
        role: String,
        /// Public key (base64) of the identity issuing this grant.
        granted_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A previously granted permission was revoked.
    RevokePermission {
        operation_id: String,
        timestamp: HlcTimestamp,
        device_id: String,
        /// Target note (subtree root), or None for workspace-level revocation.
        note_id: Option<String>,
        /// Public key (base64) of the identity whose permission is revoked.
        user_id: String,
        /// Public key (base64) of the identity performing the revocation.
        revoked_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A peer has joined the workspace via the invitation handshake.
    JoinWorkspace {
        operation_id: String,
        timestamp: HlcTimestamp,
        device_id: String,
        /// Ed25519 public key (base64) of the joining identity.
        identity_public_key: String,
        /// Display name the joining peer has chosen.
        declared_name: String,
        /// Reference to the pairing token from the corresponding invite.swarm.
        pairing_token: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// Remove a peer from the workspace entirely.
    /// Root Owner only. Revokes all grants and cuts off sync.
    RemovePeer {
        operation_id: String,
        timestamp: HlcTimestamp,
        device_id: String,
        /// Public key of the peer being removed.
        user_id: String,
        /// Public key of the Root Owner performing the removal.
        removed_by: String,
        signature: String,
    },
    /// Transfer root ownership to another peer.
    /// Root Owner only. Recipient must be an existing peer.
    TransferRootOwnership {
        operation_id: String,
        timestamp: HlcTimestamp,
        device_id: String,
        /// Public key of the new Root Owner.
        new_owner: String,
        /// Public key of the current (outgoing) Root Owner.
        transferred_by: String,
        signature: String,
    },
    /// A file attachment was added to a note.
    AddAttachment {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// Stable UUID for the attachment itself.
        attachment_id: String,
        /// ID of the note this attachment belongs to.
        note_id: String,
        /// Original filename of the attachment.
        filename: String,
        /// MIME type of the attachment, if known.
        mime_type: Option<String>,
        /// Size of the attachment in bytes.
        size_bytes: i64,
        /// SHA-256 hex digest of the attachment content.
        hash_sha256: String,
        /// Public key (base64) of the identity that added this attachment.
        added_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A file attachment was removed from a note.
    RemoveAttachment {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// UUID of the attachment being removed.
        attachment_id: String,
        /// ID of the note this attachment belongs to.
        note_id: String,
        /// Public key (base64) of the identity that removed this attachment.
        removed_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// A device registered itself in this workspace for the first time.
    /// Emitted once per (workspace, device) pair on first open.
    RegisterDevice {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// The composite device UUID portion (part after ':' in device_id).
        device_uuid: String,
        /// Human-readable name for this device (from hostname).
        device_name: String,
        /// Base64-encoded Ed25519 public key of the registering identity.
        identity_public_key: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// The checked state of a note was toggled.
    SetChecked {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// ID of the note whose checked state changed.
        note_id: String,
        /// New checked state.
        checked: bool,
        /// Public key (base64) of the identity that modified this note.
        modified_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
    /// Workspace-level metadata (author, license, description, etc.) was updated.
    /// Owner-only. Carries the full serialized WorkspaceMetadata JSON blob.
    UpdateWorkspaceMetadata {
        /// Stable UUID for this operation.
        operation_id: String,
        /// HLC timestamp when the operation was created.
        timestamp: HlcTimestamp,
        /// ID of the device that performed this operation.
        device_id: String,
        /// JSON-serialized WorkspaceMetadata.
        metadata_json: String,
        /// Public key (base64) of the identity that updated the metadata.
        modified_by: String,
        /// Ed25519 signature over the canonical JSON payload (base64).
        signature: String,
    },
}

impl Operation {
    /// Returns the stable identifier for this operation.
    #[must_use]
    pub fn operation_id(&self) -> &str {
        match self {
            Self::CreateNote { operation_id, .. }
            | Self::UpdateNote { operation_id, .. }
            | Self::UpdateField { operation_id, .. }
            | Self::DeleteNote { operation_id, .. }
            | Self::MoveNote { operation_id, .. }
            | Self::SetTags { operation_id, .. }
            | Self::CreateUserScript { operation_id, .. }
            | Self::UpdateUserScript { operation_id, .. }
            | Self::DeleteUserScript { operation_id, .. }
            | Self::UpdateSchema { operation_id, .. }
            | Self::RetractOperation { operation_id, .. }
            | Self::SetPermission { operation_id, .. }
            | Self::RevokePermission { operation_id, .. }
            | Self::JoinWorkspace { operation_id, .. }
            | Self::RemovePeer { operation_id, .. }
            | Self::TransferRootOwnership { operation_id, .. }
            | Self::AddAttachment { operation_id, .. }
            | Self::RemoveAttachment { operation_id, .. }
            | Self::RegisterDevice { operation_id, .. }
            | Self::SetChecked { operation_id, .. }
            | Self::UpdateWorkspaceMetadata { operation_id, .. } => operation_id,
        }
    }

    /// Returns the HLC timestamp when this operation was created.
    #[must_use]
    pub fn timestamp(&self) -> HlcTimestamp {
        match self {
            Self::CreateNote { timestamp, .. }
            | Self::UpdateNote { timestamp, .. }
            | Self::UpdateField { timestamp, .. }
            | Self::DeleteNote { timestamp, .. }
            | Self::MoveNote { timestamp, .. }
            | Self::SetTags { timestamp, .. }
            | Self::CreateUserScript { timestamp, .. }
            | Self::UpdateUserScript { timestamp, .. }
            | Self::DeleteUserScript { timestamp, .. }
            | Self::UpdateSchema { timestamp, .. }
            | Self::RetractOperation { timestamp, .. }
            | Self::SetPermission { timestamp, .. }
            | Self::RevokePermission { timestamp, .. }
            | Self::JoinWorkspace { timestamp, .. }
            | Self::RemovePeer { timestamp, .. }
            | Self::TransferRootOwnership { timestamp, .. }
            | Self::AddAttachment { timestamp, .. }
            | Self::RemoveAttachment { timestamp, .. }
            | Self::RegisterDevice { timestamp, .. }
            | Self::SetChecked { timestamp, .. }
            | Self::UpdateWorkspaceMetadata { timestamp, .. } => *timestamp,
        }
    }

    /// Returns the device identifier of the machine that created this operation.
    #[must_use]
    pub fn device_id(&self) -> &str {
        match self {
            Self::CreateNote { device_id, .. }
            | Self::UpdateNote { device_id, .. }
            | Self::UpdateField { device_id, .. }
            | Self::DeleteNote { device_id, .. }
            | Self::MoveNote { device_id, .. }
            | Self::SetTags { device_id, .. }
            | Self::CreateUserScript { device_id, .. }
            | Self::UpdateUserScript { device_id, .. }
            | Self::DeleteUserScript { device_id, .. }
            | Self::UpdateSchema { device_id, .. }
            | Self::RetractOperation { device_id, .. }
            | Self::SetPermission { device_id, .. }
            | Self::RevokePermission { device_id, .. }
            | Self::JoinWorkspace { device_id, .. }
            | Self::RemovePeer { device_id, .. }
            | Self::TransferRootOwnership { device_id, .. }
            | Self::AddAttachment { device_id, .. }
            | Self::RemoveAttachment { device_id, .. }
            | Self::RegisterDevice { device_id, .. }
            | Self::SetChecked { device_id, .. }
            | Self::UpdateWorkspaceMetadata { device_id, .. } => device_id,
        }
    }

    /// Returns the base64-encoded public key of the author of this operation.
    ///
    /// Returns an empty string for `RetractOperation`, which is a local-only undo marker.
    #[must_use]
    pub fn author_key(&self) -> &str {
        match self {
            Self::CreateNote { created_by, .. } => created_by,
            Self::UpdateNote { modified_by, .. } => modified_by,
            Self::UpdateField { modified_by, .. } => modified_by,
            Self::DeleteNote { deleted_by, .. } => deleted_by,
            Self::MoveNote { moved_by, .. } => moved_by,
            Self::SetTags { modified_by, .. } => modified_by,
            Self::CreateUserScript { created_by, .. } => created_by,
            Self::UpdateUserScript { modified_by, .. } => modified_by,
            Self::DeleteUserScript { deleted_by, .. } => deleted_by,
            Self::UpdateSchema { updated_by, .. } => updated_by,
            Self::RetractOperation { .. } => "",
            Self::SetPermission { granted_by, .. } => granted_by,
            Self::RevokePermission { revoked_by, .. } => revoked_by,
            Self::JoinWorkspace {
                identity_public_key,
                ..
            } => identity_public_key,
            Self::RemovePeer { removed_by, .. } => removed_by,
            Self::TransferRootOwnership { transferred_by, .. } => transferred_by,
            Self::AddAttachment { added_by, .. } => added_by,
            Self::RemoveAttachment { removed_by, .. } => removed_by,
            Self::RegisterDevice {
                identity_public_key,
                ..
            } => identity_public_key,
            Self::SetChecked { modified_by, .. } => modified_by,
            Self::UpdateWorkspaceMetadata { modified_by, .. } => modified_by,
        }
    }

    // ── Private helpers for sign/verify ────────────────────────────────────

    fn set_author_key(&mut self, key: String) {
        match self {
            Self::CreateNote { created_by, .. } => *created_by = key,
            Self::UpdateNote { modified_by, .. } => *modified_by = key,
            Self::UpdateField { modified_by, .. } => *modified_by = key,
            Self::DeleteNote { deleted_by, .. } => *deleted_by = key,
            Self::MoveNote { moved_by, .. } => *moved_by = key,
            Self::SetTags { modified_by, .. } => *modified_by = key,
            Self::CreateUserScript { created_by, .. } => *created_by = key,
            Self::UpdateUserScript { modified_by, .. } => *modified_by = key,
            Self::DeleteUserScript { deleted_by, .. } => *deleted_by = key,
            Self::UpdateSchema { updated_by, .. } => *updated_by = key,
            Self::RetractOperation { .. } => {}
            Self::SetPermission { granted_by, .. } => *granted_by = key,
            Self::RevokePermission { revoked_by, .. } => *revoked_by = key,
            Self::JoinWorkspace {
                identity_public_key,
                ..
            } => *identity_public_key = key,
            Self::RemovePeer { removed_by, .. } => *removed_by = key,
            Self::TransferRootOwnership { transferred_by, .. } => *transferred_by = key,
            Self::AddAttachment { added_by, .. } => *added_by = key,
            Self::RemoveAttachment { removed_by, .. } => *removed_by = key,
            Self::RegisterDevice {
                identity_public_key,
                ..
            } => *identity_public_key = key,
            Self::SetChecked { modified_by, .. } => *modified_by = key,
            Self::UpdateWorkspaceMetadata { modified_by, .. } => *modified_by = key,
        }
    }

    fn set_signature(&mut self, sig: String) {
        match self {
            Self::CreateNote { signature, .. }
            | Self::UpdateNote { signature, .. }
            | Self::UpdateField { signature, .. }
            | Self::DeleteNote { signature, .. }
            | Self::MoveNote { signature, .. }
            | Self::SetTags { signature, .. }
            | Self::CreateUserScript { signature, .. }
            | Self::UpdateUserScript { signature, .. }
            | Self::DeleteUserScript { signature, .. }
            | Self::UpdateSchema { signature, .. }
            | Self::SetPermission { signature, .. }
            | Self::RevokePermission { signature, .. }
            | Self::JoinWorkspace { signature, .. }
            | Self::RemovePeer { signature, .. }
            | Self::TransferRootOwnership { signature, .. }
            | Self::AddAttachment { signature, .. }
            | Self::RemoveAttachment { signature, .. }
            | Self::RegisterDevice { signature, .. }
            | Self::SetChecked { signature, .. }
            | Self::UpdateWorkspaceMetadata { signature, .. } => *signature = sig,
            Self::RetractOperation { .. } => {}
        }
    }

    fn get_signature(&self) -> &str {
        match self {
            Self::CreateNote { signature, .. }
            | Self::UpdateNote { signature, .. }
            | Self::UpdateField { signature, .. }
            | Self::DeleteNote { signature, .. }
            | Self::MoveNote { signature, .. }
            | Self::SetTags { signature, .. }
            | Self::CreateUserScript { signature, .. }
            | Self::UpdateUserScript { signature, .. }
            | Self::DeleteUserScript { signature, .. }
            | Self::UpdateSchema { signature, .. }
            | Self::SetPermission { signature, .. }
            | Self::RevokePermission { signature, .. }
            | Self::JoinWorkspace { signature, .. }
            | Self::RemovePeer { signature, .. }
            | Self::TransferRootOwnership { signature, .. }
            | Self::AddAttachment { signature, .. }
            | Self::RemoveAttachment { signature, .. }
            | Self::RegisterDevice { signature, .. }
            | Self::SetChecked { signature, .. }
            | Self::UpdateWorkspaceMetadata { signature, .. } => signature,
            Self::RetractOperation { .. } => "",
        }
    }

    // ── Cryptographic signing ───────────────────────────────────────────────

    /// Sign this operation in place. Sets the author key and signature.
    ///
    /// The canonical payload is the operation serialised to JSON with
    /// `signature = ""` so that the signature field itself is not part of
    /// what is signed.
    pub fn sign(&mut self, key: &ed25519_dalek::SigningKey) {
        use base64::{engine::general_purpose::STANDARD, Engine as _};
        use ed25519_dalek::Signer;

        // 1. Set the author key to the verifying key (base64).
        let pubkey_bytes = key.verifying_key().to_bytes();
        let pubkey_b64 = STANDARD.encode(pubkey_bytes);
        self.set_author_key(pubkey_b64);

        // 2. Set signature to "" for canonical payload.
        self.set_signature(String::new());

        // 3. Serialise and sign.
        let payload = serde_jcs::to_string(self).expect("Operation must be serializable");
        let sig = key.sign(payload.as_bytes());

        // 4. Store the signature.
        self.set_signature(STANDARD.encode(sig.to_bytes()));
    }

    /// Verify the Ed25519 signature on this operation against the provided public key.
    ///
    /// Returns `false` if the signature is missing, malformed, or invalid.
    pub fn verify(&self, pubkey: &ed25519_dalek::VerifyingKey) -> bool {
        use base64::{engine::general_purpose::STANDARD, Engine as _};
        use ed25519_dalek::Verifier;

        let sig_b64 = self.get_signature();
        let Ok(sig_bytes) = STANDARD.decode(sig_b64) else {
            return false;
        };
        let Ok(sig_bytes_arr) = <[u8; 64]>::try_from(sig_bytes) else {
            return false;
        };
        let sig = ed25519_dalek::Signature::from_bytes(&sig_bytes_arr);

        // Build canonical payload with signature = "".
        let mut clone = self.clone();
        clone.set_signature(String::new());
        let payload = serde_jcs::to_string(&clone).expect("Operation must be serializable");

        pubkey.verify(payload.as_bytes(), &sig).is_ok()
    }
}

#[cfg(test)]
#[path = "operation_tests.rs"]
mod tests;