syncweb_core/indexing/

links.rs

//! Stable content links, signed mutable names, capabilities, and mirrors.
//!
//! Links are deliberately independent of the document and blob stores.  A
//! caller can persist the records in either store, or use [`LinkResolver`] as
//! a small in-memory resolver for local indexing and tests.  Immutable links
//! identify a hash directly; mutable links identify a signed, monotonically
//! advancing pointer.

use std::{
    collections::{BTreeMap, HashMap, HashSet},
    fmt,
    future::Future,
    path::{Path, PathBuf},
    pin::Pin,
    str::{FromStr, Split},
    sync::{Arc, Mutex},
};

use ed25519_dalek::SigningKey;
use iroh::{PublicKey, SecretKey};
use iroh_blobs::{Hash, ticket::BlobTicket};
use iroh_docs::NamespaceId;
use serde::{Deserialize, Serialize};

use super::IndexingDatabase;
use crate::{
    constants::{LINK_SCHEME, LINK_SIGNATURE_CONTEXT},
    error::{Result, SyncwebError},
    folder::FolderManager,
    node::{identity::IdentityManager, iroh_node::IrohNode},
};

const DEFAULT_PRIVATE_LINK_TTL: u64 = 30 * 24 * 60 * 60;

/// An immutable content-addressed link.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub struct ContentLink {
    /// The content or manifest hash identified by this link.
    pub hash: Hash,
}

impl ContentLink {
    /// Create an immutable content link.
    #[must_use]
    pub const fn new(hash: Hash) -> Self {
        Self { hash }
    }

    /// Return the content hash.
    #[must_use]
    pub const fn hash(self) -> Hash {
        self.hash
    }

    /// Parse an immutable content URI.
    ///
    /// # Errors
    ///
    /// Returns an error if the URI or hash is malformed.
    pub fn parse(value: &str) -> Result<Self> {
        value.parse()
    }

    /// Return the canonical URI.
    #[must_use]
    pub fn uri(self) -> String {
        self.to_string()
    }

    /// Validate this link.
    ///
    /// # Errors
    ///
    /// This currently cannot fail, but is provided so all link kinds have a
    /// common validation API.
    pub const fn validate(self) -> Result<()> {
        Ok(())
    }
}

impl fmt::Display for ContentLink {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{LINK_SCHEME}content/{}", self.hash)
    }
}

impl FromStr for ContentLink {
    type Err = SyncwebError;

    fn from_str(value: &str) -> Result<Self> {
        let hash_text = value
            .strip_prefix("syncweb://content/")
            .ok_or_else(|| SyncwebError::InvalidConfig("content link must use syncweb://content/".to_owned()))?;
        if hash_text.is_empty() || hash_text.contains('/') || hash_text.contains('?') || hash_text.contains('#') {
            return Err(SyncwebError::InvalidConfig(
                "content link has an invalid hash".to_owned(),
            ));
        }
        let hash = hash_text
            .parse::<Hash>()
            .map_err(|error| SyncwebError::InvalidConfig(format!("invalid content link hash: {error}")))?;
        Ok(Self::new(hash))
    }
}

/// Alias used by callers that prefer the term immutable link.
pub type ImmutableLink = ContentLink;

/// A stable publisher/alias portion of a mutable link.
#[derive(Clone, Debug, Eq, PartialEq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub struct NameLink {
    /// The publisher whose signed pointer is followed.
    pub publisher: PublicKey,
    /// The publisher-controlled alias.
    pub alias: String,
}

impl NameLink {
    /// Create a mutable name link.
    ///
    /// # Errors
    ///
    /// Returns an error for an empty publisher alias or an alias that could
    /// change URI path semantics.
    pub fn new(publisher: PublicKey, alias: impl Into<String>) -> Result<Self> {
        let link = Self {
            publisher,
            alias: alias.into(),
        };
        link.validate()?;
        Ok(link)
    }

    /// Parse a mutable name URI.
    ///
    /// # Errors
    ///
    /// Returns an error if the URI or publisher is malformed.
    pub fn parse(value: &str) -> Result<Self> {
        value.parse()
    }

    /// Return the canonical URI.
    #[must_use]
    pub fn uri(&self) -> String {
        self.to_string()
    }

    /// Validate the publisher alias.
    ///
    /// # Errors
    ///
    /// Returns an error if the alias is empty or contains URI delimiters.
    pub fn validate(&self) -> Result<()> {
        validate_path_segment(&self.alias, "mutable link alias")
    }
}

impl fmt::Display for NameLink {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{LINK_SCHEME}name/{}/{}", self.publisher, self.alias)
    }
}

impl FromStr for NameLink {
    type Err = SyncwebError;

    fn from_str(value: &str) -> Result<Self> {
        let remainder = value
            .strip_prefix("syncweb://name/")
            .ok_or_else(|| SyncwebError::InvalidConfig("name link must use syncweb://name/".to_owned()))?;
        let mut parts = remainder.split('/');
        let publisher_text = next_part(&mut parts, "name link publisher")?;
        let alias = next_part(&mut parts, "name link alias")?;
        if parts.next().is_some() {
            return Err(SyncwebError::InvalidConfig(
                "name link has too many path segments".to_owned(),
            ));
        }
        let publisher = publisher_text
            .parse::<PublicKey>()
            .map_err(|error| SyncwebError::InvalidIdentity(format!("invalid name link publisher: {error}")))?;
        Self::new(publisher, alias)
    }
}

/// Alias used by callers that prefer the term mutable link.
pub type MutableLink = NameLink;

/// A signed mutable pointer to an immutable manifest.
///
/// Every accepted pointer has a publisher, alias, sequence, and manifest
/// bound by an Ed25519 signature.  A resolver accepts only a sequence greater
/// than the currently accepted sequence for that publisher and alias.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct MutablePointer {
    /// Publisher identity; this must match the signing key.
    pub publisher: PublicKey,
    /// Publisher-controlled alias.
    pub alias: String,
    /// Monotonically increasing update number.
    pub sequence: u64,
    /// Immutable manifest identified by this pointer.
    pub manifest: Hash,
    /// Optional semantic version used for version pinning.
    #[serde(default)]
    pub version: Option<String>,
    /// Hex-encoded Ed25519 signature over the pointer without this field.
    #[serde(default)]
    pub signature: Option<String>,
}

impl MutablePointer {
    /// Create an unsigned pointer.
    ///
    /// Call [`Self::sign`] before registering it with a resolver.
    ///
    /// # Errors
    ///
    /// Returns an error if the alias or sequence is invalid.
    pub fn new(publisher: PublicKey, alias: impl Into<String>, manifest: Hash, sequence: u64) -> Result<Self> {
        let pointer = Self {
            publisher,
            alias: alias.into(),
            sequence,
            manifest,
            version: None,
            signature: None,
        };
        pointer.validate()?;
        Ok(pointer)
    }

    /// Create and sign a pointer with a Dalek signing key.
    ///
    /// # Errors
    ///
    /// Returns an error if the pointer is invalid or the signer does not
    /// match the publisher.
    pub fn signed(
        publisher: PublicKey,
        alias: impl Into<String>,
        manifest: Hash,
        sequence: u64,
        signing_key: &SigningKey,
    ) -> Result<Self> {
        let mut pointer = Self::new(publisher, alias, manifest, sequence)?;
        pointer.sign(signing_key)?;
        Ok(pointer)
    }

    /// Create and sign a pointer with an iroh secret key.
    ///
    /// # Errors
    ///
    /// Returns an error if the pointer is invalid or the signer does not
    /// match the publisher.
    pub fn signed_with_secret_key(
        publisher: PublicKey,
        alias: impl Into<String>,
        manifest: Hash,
        sequence: u64,
        secret_key: &SecretKey,
    ) -> Result<Self> {
        let signing_key = SigningKey::from_bytes(&secret_key.to_bytes());
        Self::signed(publisher, alias, manifest, sequence, &signing_key)
    }

    /// Set a semantic version on this pointer.
    #[must_use]
    pub fn with_version(mut self, version: impl Into<String>) -> Self {
        self.version = Some(version.into());
        self.signature = None;
        self
    }

    /// Return the corresponding stable name link.
    ///
    /// # Errors
    ///
    /// Returns an error if the alias is invalid.
    pub fn link(&self) -> Result<NameLink> {
        NameLink::new(self.publisher, self.alias.clone())
    }

    /// Return the immutable manifest hash targeted by this pointer.
    #[must_use]
    pub const fn manifest_hash(&self) -> Hash {
        self.manifest
    }

    /// Serialize the pointer without its signature.
    ///
    /// # Errors
    ///
    /// Returns an error if the pointer is invalid or cannot be serialized.
    pub fn unsigned_bytes(&self) -> Result<Vec<u8>> {
        let mut unsigned = self.clone();
        unsigned.signature = None;
        unsigned.validate()?;
        let mut bytes = LINK_SIGNATURE_CONTEXT.to_vec();
        let encoded = serde_json::to_vec(&unsigned)
            .map_err(|error| SyncwebError::operation("failed to serialize mutable link pointer", error))?;
        bytes.extend_from_slice(&encoded);
        Ok(bytes)
    }

    /// Sign this pointer with an Ed25519 key.
    ///
    /// # Errors
    ///
    /// Returns an error if the signer does not match the publisher or the
    /// pointer cannot be serialized.
    pub fn sign(&mut self, signing_key: &SigningKey) -> Result<()> {
        if signing_key.verifying_key().to_bytes() != *self.publisher.as_bytes() {
            return Err(SyncwebError::InvalidIdentity(
                "mutable link signer does not match publisher".to_owned(),
            ));
        }
        self.validate()?;
        self.signature = Some(crate::signature::sign_hex(signing_key, &self.unsigned_bytes()?));
        Ok(())
    }

    /// Verify the pointer's signature and all provider leases.
    ///
    /// # Errors
    ///
    /// Returns an error if the signature, pointer, or provider lease is
    /// invalid.
    pub fn verify_signature(&self) -> Result<()> {
        self.validate()?;
        let signature_text = self
            .signature
            .as_deref()
            .ok_or_else(|| SyncwebError::InvalidConfig("mutable link pointer must be signed".to_owned()))?;
        crate::signature::verify_hex(
            &hex::encode(self.publisher.as_bytes()),
            &self.unsigned_bytes()?,
            signature_text,
        )
    }

    /// Validate non-cryptographic pointer fields.
    ///
    /// # Errors
    ///
    /// Returns an error if a pointer field or provider lease is invalid.
    pub fn validate(&self) -> Result<()> {
        validate_path_segment(&self.alias, "mutable link alias")?;
        if self.sequence == 0 {
            return Err(SyncwebError::InvalidConfig(
                "mutable link sequence must be greater than zero".to_owned(),
            ));
        }
        if let Some(version) = &self.version
            && version.trim().is_empty()
        {
            return Err(SyncwebError::InvalidConfig(
                "mutable link version cannot be empty".to_owned(),
            ));
        }
        Ok(())
    }

    /// Encode the signed pointer as JSON.
    ///
    /// # Errors
    ///
    /// Returns an error if the pointer is unsigned, invalid, or cannot be
    /// serialized.
    pub fn to_bytes(&self) -> Result<Vec<u8>> {
        self.verify_signature()?;
        serde_json::to_vec(self)
            .map_err(|error| SyncwebError::operation("failed to serialize mutable link pointer", error))
    }

    /// Decode and validate a signed pointer.
    ///
    /// # Errors
    ///
    /// Returns an error if the bytes do not contain a valid signed pointer.
    pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Result<Self> {
        let pointer: Self = serde_json::from_slice(bytes.as_ref())
            .map_err(|error| SyncwebError::operation("failed to deserialize mutable link pointer", error))?;
        pointer.verify_signature()?;
        Ok(pointer)
    }
}

/// Alias for the signed mutable pointer terminology used by the protocol.
pub type SignedMutablePointer = MutablePointer;

/// A bearer capability link to a private manifest.
#[derive(Clone, Debug, Eq, PartialEq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub struct PrivateLink {
    /// Immutable manifest granted by this capability.
    pub manifest: Hash,
    /// Secret read capability.  It is intentionally included in the URI.
    pub capability: [u8; 32],
    /// Unix timestamp after which the capability is no longer accepted.
    pub expires_at: u64,
}

impl PrivateLink {
    /// Generate a private capability link with a cryptographically random
    /// bearer token.
    ///
    /// # Errors
    ///
    /// Returns an error if the expiration is invalid.
    pub fn generate(manifest: Hash, expires_at: u64) -> Result<Self> {
        let capability = rand::random::<[u8; 32]>();
        Self::new(manifest, capability, expires_at)
    }

    /// Parse a private capability URI.
    ///
    /// # Errors
    ///
    /// Returns an error if the URI, hash, capability, or expiration is
    /// malformed.
    pub fn parse(value: &str) -> Result<Self> {
        value.parse()
    }

    /// Create a private capability link.
    ///
    /// # Errors
    ///
    /// Returns an error if the capability or expiration is invalid.
    pub fn new(manifest: Hash, capability: [u8; 32], expires_at: u64) -> Result<Self> {
        let link = Self {
            manifest,
            capability,
            expires_at,
        };
        link.validate()?;
        Ok(link)
    }

    /// Return the canonical capability URI.
    #[must_use]
    pub fn uri(&self) -> String {
        self.to_string()
    }

    /// Validate the capability and expiry.
    ///
    /// # Errors
    ///
    /// Returns an error if the expiration is zero.
    pub fn validate(&self) -> Result<()> {
        if self.expires_at == 0 {
            return Err(SyncwebError::InvalidConfig(
                "private link expiration must be greater than zero".to_owned(),
            ));
        }
        Ok(())
    }

    /// Return whether this link is expired at `now`.
    #[must_use]
    pub const fn is_expired_at(&self, now: u64) -> bool {
        self.expires_at <= now
    }

    /// Return a stable key used by revocation lists.
    #[must_use]
    pub fn revocation_key(&self) -> (Hash, Vec<u8>) {
        (self.manifest, self.capability.to_vec())
    }
}

impl fmt::Display for PrivateLink {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            formatter,
            "{LINK_SCHEME}private/{}/{}?expires={}",
            self.manifest,
            hex::encode(self.capability),
            self.expires_at
        )
    }
}

impl FromStr for PrivateLink {
    type Err = SyncwebError;

    fn from_str(value: &str) -> Result<Self> {
        let (path, query) = value
            .strip_prefix("syncweb://private/")
            .ok_or_else(|| SyncwebError::InvalidConfig("private link must use syncweb://private/".to_owned()))?
            .split_once('?')
            .ok_or_else(|| SyncwebError::InvalidConfig("private link must contain an expiration".to_owned()))?;
        let mut parts = path.split('/');
        let manifest = next_part(&mut parts, "private link manifest")?;
        let capability_hex = next_part(&mut parts, "private link capability")?;
        if parts.next().is_some() {
            return Err(SyncwebError::InvalidConfig(
                "private link has too many path segments".to_owned(),
            ));
        }
        let manifest_hash = manifest
            .parse::<Hash>()
            .map_err(|error| SyncwebError::InvalidConfig(format!("invalid private link manifest: {error}")))?;
        let capability_bytes = hex::decode(capability_hex)
            .map_err(|error| SyncwebError::InvalidConfig(format!("invalid private link capability: {error}")))?;
        let capability: [u8; 32] = capability_bytes.try_into().map_err(|bytes: Vec<u8>| {
            SyncwebError::InvalidConfig(format!("private link capability must be 32 bytes, got {}", bytes.len()))
        })?;
        let expires_text = query
            .strip_prefix("expires=")
            .ok_or_else(|| SyncwebError::InvalidConfig("private link query must contain expires".to_owned()))?;
        let expires_at = expires_text
            .parse::<u64>()
            .map_err(|error| SyncwebError::InvalidConfig(format!("invalid private link expiration: {error}")))?;
        Self::new(manifest_hash, capability, expires_at)
    }
}

/// Alias for capability links.
pub type CapabilityLink = PrivateLink;

/// A direct provider ticket registered as a mirror.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct Mirror {
    /// Hash served by this mirror.
    pub hash: Hash,
    /// Blob ticket for the mirror.
    pub ticket: BlobTicket,
}

impl Mirror {
    /// Construct a mirror from a blob ticket.
    ///
    /// # Errors
    ///
    /// Returns an error if the ticket does not match its hash.
    pub fn new(ticket: BlobTicket) -> Result<Self> {
        let mirror = Self {
            hash: ticket.hash(),
            ticket,
        };
        mirror.validate()?;
        Ok(mirror)
    }

    /// Validate that the ticket is consistent with the mirror hash.
    ///
    /// # Errors
    ///
    /// Returns an error if the ticket does not match its hash.
    pub fn validate(&self) -> Result<()> {
        if self.ticket.hash() != self.hash {
            return Err(SyncwebError::InvalidTicket(
                "mirror ticket does not match its content hash".to_owned(),
            ));
        }
        Ok(())
    }
}

/// Result of resolving any public or private link.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct LinkResolution {
    /// Manifest or content hash identified by the link.
    pub manifest: Hash,
    /// Semantic version selected by a mutable link, if available.
    pub version: Option<String>,
    /// Mutable pointer sequence, if the link is mutable.
    pub sequence: Option<u64>,
    /// Direct blob tickets in mirror fallback order.
    pub tickets: Vec<BlobTicket>,
}

impl LinkResolution {
    /// Create a new resolution containing just a manifest hash.
    #[must_use]
    pub const fn new(manifest: Hash) -> Self {
        Self {
            manifest,
            version: None,
            sequence: None,
            tickets: Vec::new(),
        }
    }

    /// Return the resolved hash.
    #[must_use]
    pub const fn hash(&self) -> Hash {
        self.manifest
    }

    /// Return provider and mirror tickets in fallback order.
    #[must_use]
    pub fn provider_tickets(&self) -> &[BlobTicket] {
        &self.tickets
    }

    /// Fetch using the first provider that succeeds.
    ///
    /// # Errors
    ///
    /// Returns an error when no provider exists or every provider fails.
    pub fn fetch_with<T, Fetch>(&self, mut fetch: Fetch) -> Result<T>
    where
        Fetch: FnMut(&BlobTicket) -> Result<T>,
    {
        fetch_from_mirrors(&self.tickets, &mut fetch)
    }
}

/// Alias used by callers that prefer the shorter resolution name.
pub type ResolvedLink = LinkResolution;

/// A parsed syncweb stable link.
#[derive(Clone, Debug, Eq, PartialEq, Hash)]
#[non_exhaustive]
pub enum Link {
    /// Immutable content link.
    Content(ContentLink),
    /// Mutable publisher name.
    Name(NameLink),
    /// Private bearer capability.
    Private(PrivateLink),
}

impl Link {
    /// Parse a stable link.
    ///
    /// # Errors
    ///
    /// Returns an error if the URI is not a supported syncweb link.
    pub fn parse(value: &str) -> Result<Self> {
        value.parse()
    }

    /// Return the link URI.
    #[must_use]
    pub fn uri(&self) -> String {
        self.to_string()
    }
}

impl fmt::Display for Link {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Content(link) => link.fmt(formatter),
            Self::Name(link) => link.fmt(formatter),
            Self::Private(link) => link.fmt(formatter),
        }
    }
}

impl FromStr for Link {
    type Err = SyncwebError;

    fn from_str(value: &str) -> Result<Self> {
        if value.starts_with("syncweb://content/") {
            return Ok(Self::Content(value.parse()?));
        }
        if value.starts_with("syncweb://name/") {
            return Ok(Self::Name(value.parse()?));
        }
        if value.starts_with("syncweb://private/") {
            return Ok(Self::Private(value.parse()?));
        }
        Err(SyncwebError::InvalidConfig(
            "unsupported syncweb link; expected content, name, or private".to_owned(),
        ))
    }
}

/// Options for a link resolution operation.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[non_exhaustive]
pub struct ResolveOptions {
    /// Select an exact semantic version from a mutable pointer history.
    pub version: Option<String>,
    /// Evaluate expiry and provider leases at this timestamp.
    pub now: Option<u64>,
}

impl ResolveOptions {
    /// Select an exact version.
    #[must_use]
    pub fn version(version: impl Into<String>) -> Self {
        Self {
            version: Some(version.into()),
            now: None,
        }
    }

    /// Evaluate the link at an explicit time.
    #[must_use]
    pub const fn at(now: u64) -> Self {
        Self {
            version: None,
            now: Some(now),
        }
    }

    /// Set an exact version while retaining the other options.
    #[must_use]
    pub fn with_version(mut self, version: impl Into<String>) -> Self {
        self.version = Some(version.into());
        self
    }
}

#[derive(Clone, Debug, Default)]
struct ResolverState {
    mirrors: HashMap<Hash, Vec<Mirror>>,
    pointers: HashMap<(PublicKey, String), PointerHistory>,
    revoked: HashSet<(Hash, Vec<u8>)>,
}

#[derive(Clone, Debug, Default)]
struct PointerHistory {
    current: Option<MutablePointer>,
    versions: BTreeMap<String, MutablePointer>,
}

/// Provider fetch hook for network-aware resolution.
pub type ProviderFetch =
    Arc<dyn Fn(NameLink) -> Pin<Box<dyn Future<Output = Result<LinkResolution>> + Send>> + Send + Sync>;

/// In-memory resolver and mirror registry.
#[derive(Clone)]
pub struct LinkResolver {
    state: Arc<Mutex<ResolverState>>,
    database: Option<IndexingDatabase>,
    provider_fetch: Option<ProviderFetch>,
}

impl fmt::Debug for LinkResolver {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("LinkResolver")
            .field("state", &self.state)
            .field("database", &self.database)
            .finish_non_exhaustive()
    }
}

impl Default for LinkResolver {
    fn default() -> Self {
        Self {
            state: Arc::new(Mutex::new(ResolverState::default())),
            database: None,
            provider_fetch: None,
        }
    }
}

impl LinkResolver {
    /// Create an empty resolver.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a resolver with a provider fetch hook for network resolution.
    ///
    /// The fetch function is called when a name link cannot be resolved
    /// locally, allowing the caller to query remote peers via iroh-docs.
    #[must_use]
    pub fn with_provider_fetch(fetch: ProviderFetch) -> Self {
        Self {
            state: Arc::new(Mutex::new(ResolverState::default())),
            database: None,
            provider_fetch: Some(fetch),
        }
    }

    /// Attempt to resolve a name link by querying remote peers.
    ///
    /// Returns `None` if no provider fetch hook is registered or the link
    /// is not a name link. The caller is responsible for falling back to
    /// local resolution.
    ///
    /// # Errors
    ///
    /// Returns an error if the remote fetch fails.
    pub async fn resolve_remote(&self, link: &Link) -> Result<Option<LinkResolution>> {
        match link {
            Link::Name(name) => {
                if let Some(ref fetch) = self.provider_fetch {
                    fetch(name.clone()).await.map(Some)
                } else {
                    Ok(None)
                }
            }
            Link::Content(_) | Link::Private(_) => Ok(None),
        }
    }

    /// Create a resolver backed by an indexing database.
    ///
    /// Pointers and mirrors are hydrated from the database on construction.
    /// Mutations are persisted through the database.
    ///
    /// # Errors
    ///
    /// Returns an error if the database cannot be read.
    pub fn with_database(database: IndexingDatabase) -> Result<Self> {
        let result = database.load_links()?;
        let mut state = ResolverState::default();
        for pointer in result.0 {
            let key = (pointer.publisher, pointer.alias.clone());
            let history = state.pointers.entry(key).or_default();
            if let Some(current) = &history.current
                && pointer.sequence <= current.sequence
            {
                continue;
            }
            if let Some(version) = &pointer.version {
                history.versions.insert(version.clone(), pointer.clone());
            }
            history.current = Some(pointer);
        }
        for ticket_str in result.1 {
            if let Ok(ticket) = ticket_str.parse::<iroh_blobs::ticket::BlobTicket>()
                && let Ok(mirror) = Mirror::new(ticket)
            {
                let mirrors = state.mirrors.entry(mirror.hash).or_default();
                if !mirrors.iter().any(|existing| existing.ticket == mirror.ticket) {
                    mirrors.push(mirror);
                }
            }
        }
        for link in result.2 {
            state.revoked.insert(link.revocation_key());
        }
        Ok(Self {
            state: Arc::new(Mutex::new(state)),
            database: Some(database),
            provider_fetch: None,
        })
    }

    /// Register a direct mirror ticket for a hash.
    ///
    /// # Errors
    ///
    /// Returns an error if the ticket is malformed.
    pub fn register_mirror(&self, ticket: BlobTicket) -> Result<()> {
        let mirror = Mirror::new(ticket)?;
        let mut state = self.lock_state()?;
        let mirrors = state.mirrors.entry(mirror.hash).or_default();
        if !mirrors.iter().any(|existing| existing.ticket == mirror.ticket) {
            mirrors.push(mirror.clone());
            if let Some(ref database) = self.database {
                let _ = database.upsert_link_mirror(&mirror.ticket.to_string());
            }
        }
        drop(state);
        Ok(())
    }

    /// Return registered direct mirror tickets in registration order.
    ///
    /// # Errors
    ///
    /// Returns an error if the resolver state lock is poisoned.
    pub fn mirrors(&self, hash: Hash) -> Result<Vec<BlobTicket>> {
        let state = self.lock_state()?;
        Ok(state
            .mirrors
            .get(&hash)
            .map(|mirrors| mirrors.iter().map(|mirror| mirror.ticket.clone()).collect())
            .unwrap_or_default())
    }

    /// Accept a signed mutable pointer, enforcing monotonic sequence.
    ///
    /// # Errors
    ///
    /// Returns an error if the pointer is unsigned, invalid, or older than
    /// the current pointer.
    pub fn publish(&self, pointer: &MutablePointer) -> Result<()> {
        pointer.verify_signature()?;
        let key = (pointer.publisher, pointer.alias.clone());
        let mut state = self.lock_state()?;
        let history = state.pointers.entry(key).or_default();
        if let Some(current) = &history.current
            && pointer.sequence <= current.sequence
        {
            return Err(SyncwebError::InvalidConfig(format!(
                "mutable link sequence {} must be greater than {}",
                pointer.sequence, current.sequence
            )));
        }
        if let Some(version) = &pointer.version {
            if history.versions.contains_key(version) {
                return Err(SyncwebError::InvalidConfig(format!(
                    "mutable link version {version:?} is already published"
                )));
            }
            history.versions.insert(version.clone(), pointer.clone());
        }
        history.current = Some(pointer.clone());
        if let Some(ref database) = self.database {
            let _ = database.upsert_link_pointer(pointer);
        }
        drop(state);
        Ok(())
    }

    /// Return the current pointer for a mutable name.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid or the resolver state lock is
    /// poisoned.
    pub fn current_pointer(&self, link: &NameLink) -> Result<Option<MutablePointer>> {
        link.validate()?;
        let state = self.lock_state()?;
        Ok(state
            .pointers
            .get(&(link.publisher, link.alias.clone()))
            .and_then(|history| history.current.clone()))
    }

    /// Revoke a private capability.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid or the resolver state lock is
    /// poisoned.
    pub fn revoke(&self, link: &PrivateLink) -> Result<()> {
        link.validate()?;
        self.lock_state()?.revoked.insert(link.revocation_key());
        Ok(())
    }

    /// Return whether a private capability has been revoked.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid or the resolver state lock is
    /// poisoned.
    pub fn is_revoked(&self, link: &PrivateLink) -> Result<bool> {
        link.validate()?;
        Ok(self.lock_state()?.revoked.contains(&link.revocation_key()))
    }

    /// Resolve a link using the current time.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid, unavailable, expired, revoked,
    /// or has an invalid provider.
    pub fn resolve(&self, link: &Link) -> Result<LinkResolution> {
        self.resolve_with_options(link, &ResolveOptions::default())
    }

    /// Resolve a link at an explicit timestamp.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid, unavailable, expired, revoked,
    /// or has an invalid provider.
    pub fn resolve_at(&self, link: &Link, now: u64) -> Result<LinkResolution> {
        self.resolve_with_options(link, &ResolveOptions::at(now))
    }

    /// Resolve a mutable link to an exact semantic version.
    ///
    /// # Errors
    ///
    /// Returns an error if the link or requested version is unavailable.
    pub fn resolve_version(&self, link: &NameLink, version: &str) -> Result<LinkResolution> {
        self.resolve_with_options(&Link::Name(link.clone()), &ResolveOptions::version(version))
    }

    /// Resolve a link using explicit version and expiry options.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid, unavailable, expired, revoked,
    /// or has an invalid provider.
    pub fn resolve_with_options(&self, link: &Link, options: &ResolveOptions) -> Result<LinkResolution> {
        let now = options.now.unwrap_or_else(crate::parsing::current_unix_secs);
        let state = self.lock_state()?;
        let resolution = match link {
            Link::Content(content) => {
                content.validate()?;
                resolution_for_hash(content.hash, None, None, &state)
            }
            Link::Private(private) => {
                private.validate()?;
                if private.is_expired_at(now) {
                    return Err(SyncwebError::InvalidConfig("private link has expired".to_owned()));
                }
                if state.revoked.contains(&private.revocation_key()) {
                    return Err(SyncwebError::InvalidConfig("private link has been revoked".to_owned()));
                }
                resolution_for_hash(private.manifest, None, None, &state)
            }
            Link::Name(name) => {
                name.validate()?;
                let history = state
                    .pointers
                    .get(&(name.publisher, name.alias.clone()))
                    .ok_or_else(|| SyncwebError::InvalidConfig("mutable link has no published pointer".to_owned()))?;
                let pointer = if let Some(version) = &options.version {
                    history.versions.get(version).ok_or_else(|| {
                        SyncwebError::InvalidConfig(format!("mutable link version {version:?} not found"))
                    })?
                } else {
                    history
                        .current
                        .as_ref()
                        .ok_or_else(|| SyncwebError::InvalidConfig("mutable link has no current pointer".to_owned()))?
                };
                resolution_for_hash(
                    pointer.manifest,
                    pointer.version.clone(),
                    Some(pointer.sequence),
                    &state,
                )
            }
        };
        drop(state);
        Ok(resolution)
    }

    /// Parse and resolve a link URI.
    ///
    /// # Errors
    ///
    /// Returns an error if the URI cannot be parsed or the link cannot be
    /// resolved.
    pub fn resolve_uri(&self, uri: &str) -> Result<LinkResolution> {
        let link = uri.parse::<Link>()?;
        self.resolve(&link)
    }

    /// Resolve and fetch a link, trying each provider and mirror in order.
    ///
    /// # Errors
    ///
    /// Returns the first successful fetch result, or an error if resolution
    /// fails or every provider fails.
    pub fn fetch_with_mirrors<T, Fetch>(&self, link: &Link, fetch: Fetch) -> Result<T>
    where
        Fetch: FnMut(&BlobTicket) -> Result<T>,
    {
        self.resolve(link)?.fetch_with(fetch)
    }

    fn lock_state(&self) -> Result<std::sync::MutexGuard<'_, ResolverState>> {
        self.state
            .lock()
            .map_err(|error| SyncwebError::operation("link resolver state lock poisoned", error))
    }
}

/// A persisted link pointer, mirror, and revocation store.
///
/// Owns the stable-link rows of an [`IndexingDatabase`] and keeps a hydrated
/// [`LinkResolver`] in sync so CLI handlers only render results.
#[derive(Clone)]
pub struct LinkStore {
    database: IndexingDatabase,
    resolver: LinkResolver,
}

impl LinkStore {
    /// Open a link store backed by an existing indexing database.
    ///
    /// # Errors
    ///
    /// Returns an error if the persisted links cannot be read.
    pub fn with_database(database: IndexingDatabase) -> Result<Self> {
        let resolver = LinkResolver::with_database(database.clone())?;
        Ok(Self { database, resolver })
    }

    /// Open a link store backed by the database at `path`.
    ///
    /// # Errors
    ///
    /// Returns an error if the database cannot be opened or its links read.
    pub fn open(path: impl AsRef<Path>) -> Result<Self> {
        Self::with_database(IndexingDatabase::open(path)?)
    }

    /// Return the underlying indexing database.
    #[must_use]
    pub const fn database(&self) -> &IndexingDatabase {
        &self.database
    }

    /// Return the hydrated resolver.
    #[must_use]
    pub const fn resolver(&self) -> &LinkResolver {
        &self.resolver
    }

    /// Create an immutable content link.
    #[must_use]
    pub const fn create_content_link(&self, hash: Hash) -> Link {
        Link::Content(ContentLink::new(hash))
    }

    /// Create a private capability link and clear any stale revocation.
    ///
    /// # Errors
    ///
    /// Returns an error if the capability cannot be generated or persisted.
    pub fn create_private_link(&self, hash: Hash, expires: Option<u64>) -> Result<Link> {
        let expires_at = expires
            .unwrap_or_else(|| crate::parsing::current_unix_secs().saturating_add(DEFAULT_PRIVATE_LINK_TTL));
        let link = PrivateLink::generate(hash, expires_at)?;
        let (pointers, mirrors, revoked) = self.database.load_links()?;
        let retained = revoked
            .iter()
            .filter(|existing| **existing != link)
            .cloned()
            .collect::<Vec<_>>();
        if retained.len() != revoked.len() {
            self.database.save_links(&pointers, &mirrors, &retained)?;
        }
        Ok(Link::Private(link))
    }

    /// Create and sign a mutable name link, advancing the pointer sequence.
    ///
    /// With `sequence == 0` the next sequence is derived from the persisted
    /// pointer history for the same publisher and alias.
    ///
    /// # Errors
    ///
    /// Returns an error if the pointer is invalid, cannot be signed, or is not
    /// monotonically newer than the current pointer.
    pub fn create_named_link(
        &self,
        identity: &IdentityManager,
        alias_input: impl Into<String>,
        hash: Hash,
        version: Option<String>,
        sequence: u64,
    ) -> Result<Link> {
        let alias = alias_input.into();
        let (pointers, _, _) = self.database.load_links()?;
        let pointer_sequence = if sequence == 0 {
            pointers
                .iter()
                .filter(|pointer| pointer.publisher == identity.node_id() && pointer.alias == alias)
                .map(|pointer| pointer.sequence)
                .max()
                .unwrap_or(0)
                .saturating_add(1)
        } else {
            sequence
        };
        let signing_key = SigningKey::from_bytes(&identity.secret_key().to_bytes());
        let mut pointer = MutablePointer::signed_with_secret_key(
            identity.node_id(),
            alias,
            hash,
            pointer_sequence,
            identity.secret_key(),
        )?;
        if let Some(version_value) = version {
            pointer = pointer.with_version(version_value);
            pointer.sign(&signing_key)?;
        }
        let link = pointer.link()?;
        self.resolver.publish(&pointer)?;
        Ok(Link::Name(link))
    }

    /// Revoke a private capability and persist the revocation.
    ///
    /// # Errors
    ///
    /// Returns an error if the link is invalid or cannot be persisted.
    pub fn revoke(&self, private: &PrivateLink) -> Result<()> {
        self.resolver.revoke(private)?;
        let (pointers, mirrors, revoked) = self.database.load_links()?;
        if !revoked.contains(private) {
            let mut updated = revoked;
            updated.push(private.clone());
            self.database.save_links(&pointers, &mirrors, &updated)?;
        }
        Ok(())
    }

    /// Register a provider ticket as a mirror for its content hash.
    ///
    /// # Errors
    ///
    /// Returns an error if the ticket is malformed or cannot be persisted.
    pub fn register_mirror(&self, ticket: BlobTicket) -> Result<()> {
        self.resolver.register_mirror(ticket)
    }

    /// Publish a link into a managed folder document under `sys/links/`.
    ///
    /// # Errors
    ///
    /// Returns an error if the folder cannot be opened or the link payload
    /// cannot be serialized or written.
    pub async fn publish_link(&self, node: &IrohNode, namespace: &str, link: &Link) -> Result<()> {
        let namespace_id = namespace
            .parse::<NamespaceId>()
            .map_err(|error| SyncwebError::operation("invalid publish namespace", error))?;
        let folder = FolderManager::new(node).get(namespace_id).await?;
        match link {
            Link::Name(name_link) => {
                let (pointers, _, _) = self.database.load_links()?;
                if let Some(pointer) = pointers
                    .iter()
                    .find(|p| p.publisher == name_link.publisher && p.alias == name_link.alias)
                {
                    let payload = serde_json::to_vec(pointer)
                        .map_err(|error| SyncwebError::operation("failed to serialize mutable pointer", error))?;
                    folder
                        .set_blob(format!("sys/links/mutable/{}", pointer.alias), payload)
                        .await?;
                    tracing::info!(alias = %pointer.alias, namespace = %namespace_id, "published mutable pointer to folder");
                }
            }
            Link::Private(private_link) => {
                let payload = serde_json::to_vec(private_link)
                    .map_err(|error| SyncwebError::operation("failed to serialize private link", error))?;
                folder
                    .set_blob(
                        format!("sys/links/private/{}", hex::encode(private_link.capability)),
                        payload,
                    )
                    .await?;
                tracing::info!(namespace = %namespace_id, "published private link to folder");
            }
            Link::Content(_) => {
                tracing::warn!("--publish has no effect on immutable content links");
            }
        }
        Ok(())
    }

    /// Resolve a collection selector to its content hash.
    ///
    /// Accepts a raw hash, a stable link, or a local file/directory path.
    ///
    /// # Errors
    ///
    /// Returns an error if the selector is a link that cannot be resolved.
    pub fn collection_hash(&self, collection: &str) -> Result<Option<Hash>> {
        if let Ok(hash) = collection.parse() {
            return Ok(Some(hash));
        }
        if let Ok(parsed_link) = collection.parse::<Link>() {
            return Ok(Some(match parsed_link {
                Link::Content(content_link) => content_link.hash,
                Link::Private(private_link) => private_link.manifest,
                Link::Name(_) => self.resolver.resolve(&parsed_link)?.manifest,
            }));
        }
        if Path::new(collection).exists() {
            return Ok(Some(hash_source(Path::new(collection))?));
        }
        Ok(None)
    }
}

/// Hash a file or directory tree with a stable, content-addressed scheme.
///
/// # Errors
///
/// Returns an error if the source does not exist, is neither a file nor a
/// directory, or cannot be read.
pub fn hash_source(source: &Path) -> Result<Hash> {
    if source.is_file() {
        let bytes = std::fs::read(source)?;
        return Ok(Hash::from_bytes(*blake3::hash(&bytes).as_bytes()));
    }
    if let Ok(hash) = source.to_string_lossy().parse() {
        return Ok(hash);
    }
    if !source.is_dir() {
        return Err(SyncwebError::InvalidConfig(format!(
            "link source does not exist or is not a file/directory: {}",
            source.display()
        )));
    }
    let mut files = Vec::new();
    collect_files(source, source, &mut files)?;
    files.sort();
    let mut hasher = blake3::Hasher::new();
    for relative in files {
        let bytes = std::fs::read(source.join(&relative))?;
        hasher.update(relative.to_string_lossy().as_bytes());
        hasher.update(&[0]);
        hasher.update(&bytes);
        hasher.update(&[0]);
    }
    Ok(Hash::from_bytes(*hasher.finalize().as_bytes()))
}

/// Collect the relative paths of every regular file under `current`.
///
/// # Errors
///
/// Returns an error if a directory cannot be read.
pub fn collect_files(root: &Path, current: &Path, output: &mut Vec<PathBuf>) -> Result<()> {
    for directory_entry_result in std::fs::read_dir(current)? {
        let directory_entry = directory_entry_result?;
        let path = directory_entry.path();
        if path.is_dir() {
            collect_files(root, &path, output)?;
        } else if path.is_file() {
            output.push(
                path.strip_prefix(root)
                    .map_err(|error| SyncwebError::operation("failed to relativize source path", error))?
                    .to_path_buf(),
            );
        } else {
            // ignore symlinks and other non-file entries
        }
    }
    Ok(())
}

/// Try provider tickets in order until one succeeds.
///
/// # Errors
///
/// Returns an error when no ticket is supplied or every fetch attempt fails.
pub fn fetch_from_mirrors<T, Fetch>(tickets: &[BlobTicket], fetch: &mut Fetch) -> Result<T>
where
    Fetch: FnMut(&BlobTicket) -> Result<T>,
{
    if tickets.is_empty() {
        return Err(SyncwebError::InvalidConfig("link has no provider tickets".to_owned()));
    }
    let mut failures = Vec::new();
    for ticket in tickets {
        match fetch(ticket) {
            Ok(value) => return Ok(value),
            Err(error) => failures.push(error.to_string()),
        }
    }
    Err(SyncwebError::InvalidConfig(format!(
        "all mirror providers failed: {}",
        failures.join("; ")
    )))
}

fn resolution_for_hash(
    manifest: Hash,
    version: Option<String>,
    sequence: Option<u64>,
    state: &ResolverState,
) -> LinkResolution {
    let mut tickets = Vec::new();
    if let Some(mirrors) = state.mirrors.get(&manifest) {
        for mirror in mirrors {
            if !tickets.contains(&mirror.ticket) {
                tickets.push(mirror.ticket.clone());
            }
        }
    }
    LinkResolution {
        manifest,
        version,
        sequence,
        tickets,
    }
}

fn validate_path_segment(value: &str, field: &str) -> Result<()> {
    if value.is_empty() || value == "." || value == ".." {
        return Err(SyncwebError::InvalidConfig(format!(
            "{field} cannot be empty or dot-like"
        )));
    }
    if value
        .chars()
        .any(|character| character.is_control() || matches!(character, '/' | '?' | '#' | '%'))
    {
        return Err(SyncwebError::InvalidConfig(format!("{field} contains URI delimiters")));
    }
    Ok(())
}

fn next_part<'a>(parts: &mut Split<'a, char>, field: &str) -> Result<&'a str> {
    let part = parts
        .next()
        .ok_or_else(|| SyncwebError::InvalidConfig(format!("{field} is missing")))?;
    if part.is_empty() {
        return Err(SyncwebError::InvalidConfig(format!("{field} is empty")));
    }
    Ok(part)
}

#[cfg(test)]
mod tests {
    use super::*;
    use iroh::{EndpointAddr, SecretKey};

    fn ticket(seed: u8, hash: Hash) -> BlobTicket {
        let secret = SecretKey::from_bytes(&[seed; 32]);
        crate::node::blob_store::raw_blob_ticket(EndpointAddr::new(secret.public()), hash)
    }

    fn pointer(seed: u8, alias: &str, hash: Hash, sequence: u64, version: &str) -> Result<MutablePointer> {
        let secret = SecretKey::from_bytes(&[seed; 32]);
        let mut pointer = MutablePointer::new(secret.public(), alias, hash, sequence)?.with_version(version);
        pointer.sign(&SigningKey::from_bytes(&secret.to_bytes()))?;
        Ok(pointer)
    }

    #[test]
    fn immutable_links_round_trip() {
        let hash = Hash::from_bytes([7; 32]);
        let link = ContentLink::new(hash);
        assert_eq!(link.to_string(), format!("syncweb://content/{hash}"));
        assert_eq!(
            link.to_string()
                .parse::<ContentLink>()
                .expect("content link should parse"),
            link
        );
        assert_eq!(
            link.to_string().parse::<Link>().expect("link should parse"),
            Link::Content(link)
        );
    }

    #[test]
    fn signed_names_are_monotonic_and_version_pinnable() {
        let hash_one = Hash::from_bytes([1; 32]);
        let hash_two = Hash::from_bytes([2; 32]);
        let resolver = LinkResolver::new();
        let first = pointer(1, "dataset", hash_one, 1, "1.0.0").expect("pointer should build");
        let name = first.link().expect("pointer should have a link");
        resolver.publish(&first).expect("first pointer should publish");
        assert_eq!(
            resolver
                .resolve(&Link::Name(name.clone()))
                .expect("name should resolve")
                .manifest,
            hash_one
        );
        let pinned = resolver
            .resolve_version(&name, "1.0.0")
            .expect("version should resolve");
        assert_eq!(pinned.manifest, hash_one);
        let second = pointer(1, "dataset", hash_two, 2, "2.0.0").expect("pointer should build");
        resolver.publish(&second).expect("second pointer should publish");
        assert_eq!(
            resolver
                .resolve(&Link::Name(name.clone()))
                .expect("name should resolve")
                .manifest,
            hash_two
        );
        assert!(resolver.publish(&first).is_err());
        assert_eq!(
            resolver
                .resolve_version(&name, "1.0.0")
                .expect("version should resolve")
                .manifest,
            hash_one
        );
    }

    #[test]
    fn private_links_expire_and_revoke() {
        let hash = Hash::from_bytes([3; 32]);
        let cap: [u8; 32] = [1_u8; 32];
        let link = PrivateLink::new(hash, cap, 20).expect("private link should build");
        let resolver = LinkResolver::new();
        assert_eq!(
            resolver
                .resolve_at(&Link::Private(link.clone()), 10)
                .expect("private link should resolve")
                .manifest,
            hash
        );
        resolver.revoke(&link).expect("private link should revoke");
        assert!(resolver.resolve_at(&Link::Private(link.clone()), 10).is_err());
        assert!(resolver.resolve_at(&Link::Private(link), 20).is_err());
    }

    #[test]
    fn private_link_generates_random_capability() {
        let hash = Hash::from_bytes([4; 32]);
        let link = PrivateLink::generate(hash, 100).expect("should generate");
        assert_ne!(link.capability, [0_u8; 32], "capability should not be zeroed");
        assert_eq!(link.manifest, hash);
        assert_eq!(link.expires_at, 100);
        // Two generated links should differ
        let link2 = PrivateLink::generate(hash, 100).expect("should generate");
        assert_ne!(link.capability, link2.capability, "capabilities should be random");
    }

    #[test]
    fn private_link_uri_round_trip() {
        let hash = Hash::from_bytes([5; 32]);
        let cap: [u8; 32] = [
            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12,
            0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
        ];
        let link = PrivateLink::new(hash, cap, 200).expect("should build");
        let uri = link.to_string();
        assert!(uri.starts_with("syncweb://private/"));
        assert!(uri.contains("?expires=200"));
        let parsed: PrivateLink = uri.parse().expect("should parse");
        assert_eq!(parsed.manifest, hash);
        assert_eq!(parsed.capability, cap);
        assert_eq!(parsed.expires_at, 200);
    }

    #[test]
    fn mirror_fallback_tries_alternates() {
        let hash = Hash::from_bytes([4; 32]);
        let resolver = LinkResolver::new();
        let first = ticket(4, hash);
        let second = ticket(5, hash);
        resolver
            .register_mirror(first.clone())
            .expect("first mirror should register");
        resolver.register_mirror(second).expect("second mirror should register");
        let link = Link::Content(ContentLink::new(hash));
        let value = resolver
            .fetch_with_mirrors(&link, |candidate| {
                if candidate == &first {
                    Err(SyncwebError::InvalidConfig("first mirror unavailable".to_owned()))
                } else {
                    Ok("second mirror")
                }
            })
            .expect("fallback should find a mirror");
        assert_eq!(value, "second mirror");
    }
}