vta-service 0.10.0

//! Local search over the credential vault — DCQL-*shaped* filtering that
//! returns lightweight **descriptors**, never credential bodies (task 1.3 of
//! the VTI credential architecture,
//! `docs/05-design-notes/vti-credential-architecture.md` §5 search, §14
//! invariants).
//!
//! ## What this is — and what it deliberately is not
//!
//! This is the *local* search primitive the holder's agent uses to find the
//! credentials it already holds, matching on the indexed envelope fields
//! `{type, community_did, issuer_did, purpose, status}`. The filter is
//! **DCQL-shaped** — it expresses the same "find credentials matching these
//! criteria" intent — but it is **not** the TDK DCQL model. Full
//! claims-level DCQL matching (querying into the credential body) arrives
//! later with TDK Phase 0c; this layer never parses a body, so it can only
//! match the indexed metadata, by design.
//!
//! ## No-enumeration invariant (§14.1, §16 "Ask first" / "Never")
//!
//! The spec is categorical: *no endpoint returns a holder's credential
//! list; discovery is DCQL-targeted only.* This module is the storage-layer
//! expression of that rule, and it enforces it three ways:
//!
//! 1. **At least one explicit filter is required.** An empty
//!    [`CredentialQuery`] (no field set) is rejected with
//!    [`AppError::Validation`] *before any I/O* — there is no
//!    "return everything" path to reach.
//! 2. **There is no return-all primitive.** Every search starts from an
//!    index scan on a concrete `(field, value)` pair (reusing
//!    [`super::index::scan`] via [`super::storage::find_by_index`]), so a
//!    caller can only ever retrieve credentials it can already *name* by an
//!    indexed value.
//! 3. **Descriptors never carry the body.** The returned
//!    [`CredentialDescriptor`] is a metadata projection — id, types, issuer,
//!    purpose, status, validity window. The opaque (and at-rest-encrypted)
//!    `body` is never read into a descriptor, so a search result cannot leak
//!    credential contents even to an authorised caller.
//!
//! Higher layers (routes / operations / DCQL) built on top must preserve all
//! three properties; this module gives them only a targeted primitive to
//! build on, never a firehose.
//!
//! ## Revoked / expired credentials are never surfaced (§14 invariant 5)
//!
//! Search **unconditionally excludes** any matched credential whose
//! [`CredentialStatus`] is [`CredentialStatus::Revoked`] or
//! [`CredentialStatus::Expired`]. A credential the status task ([`super::status`])
//! has marked revoked must not reach a verifier as a candidate to present
//! (`vti-credential-architecture.md` §14 invariant 5: *a revoked credential MUST be
//! excluded from search results*). The exclusion is applied **after** the
//! indexed filter match, so it holds even when the caller does not constrain
//! on `status` — and even if a caller explicitly asks for
//! `status = revoked`, the result is empty (there is no "show me my revoked
//! credentials" surface here). `Unknown` and `Valid` are surfaced; resolving
//! `Unknown` → `Valid`/`Revoked` is the status task's job, run before a
//! present.

use vti_common::error::AppError;
use vti_common::store::KeyspaceHandle;

use super::model::{CredentialPurpose, CredentialStatus, IndexField, StoredCredential};

/// A lightweight, body-free projection of a matched [`StoredCredential`].
///
/// This is what local search returns: enough metadata for the holder's agent
/// to decide *which* credential(s) to act on (and then fetch the full record
/// by id via [`super::storage::get`] when it genuinely needs the body), with
/// **no** credential contents. The opaque `body` is intentionally absent — a
/// search result must never be a vector for leaking credential material
/// (§14, §16 "Never: disclosing claims beyond the DCQL request").
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CredentialDescriptor {
    /// Local handle — the id under which the full record can be fetched.
    pub id: String,
    /// VC `type` tags carried by the credential.
    pub types: Vec<String>,
    /// Issuer DID, when the stored envelope records one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub issuer_did: Option<String>,
    /// Semantic purpose (invite / membership / role / …), when known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose: Option<CredentialPurpose>,
    /// Lifecycle status (valid / expired / revoked / unknown).
    pub status: CredentialStatus,
    /// RFC 3339 validity-window start, when the envelope declares one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub valid_from: Option<String>,
    /// RFC 3339 validity-window end, when the envelope declares one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub valid_until: Option<String>,
}

impl CredentialDescriptor {
    /// Project a full record down to its body-free descriptor. The `body`
    /// field is *not* read — this is the only place the metadata→descriptor
    /// mapping lives, so "descriptors never carry the body" is enforced in
    /// one spot.
    fn from_record(cred: &StoredCredential) -> Self {
        CredentialDescriptor {
            id: cred.id.clone(),
            types: cred.types.clone(),
            issuer_did: cred.issuer_did.clone(),
            purpose: cred.purpose.clone(),
            status: cred.status,
            valid_from: cred.valid_from.clone(),
            valid_until: cred.valid_until.clone(),
        }
    }
}

/// A DCQL-*shaped* filter over the vault's indexed envelope fields.
///
/// Every field is optional, and the fields that are `Some` are combined with
/// **AND** semantics: a credential matches only if it satisfies *all* set
/// constraints. At least one field must be set — an all-`None` query is
/// rejected (no-enumeration, §14.1).
///
/// `r#type` matches a single VC `type` tag: a credential is a match if *any*
/// of its `types` equals the requested tag (the index already records each
/// tag independently).
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CredentialQuery {
    /// Match credentials carrying this VC `type` tag.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub r#type: Option<String>,
    /// Match credentials for this community / context DID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub community_did: Option<String>,
    /// Match credentials from this issuer DID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub issuer_did: Option<String>,
    /// Match credentials with this semantic purpose.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose: Option<CredentialPurpose>,
    /// Match credentials with this lifecycle status.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<CredentialStatus>,
}

impl CredentialQuery {
    /// `true` when no filter field is set. Such a query is **not runnable** —
    /// running it would be a wallet enumeration. [`search`] rejects it.
    pub fn is_empty(&self) -> bool {
        self.r#type.is_none()
            && self.community_did.is_none()
            && self.issuer_did.is_none()
            && self.purpose.is_none()
            && self.status.is_none()
    }

    /// The ordered list of set `(field, value)` constraints. The first entry
    /// is used as the index-scan anchor (it bounds the candidate set to one
    /// indexed value); the rest are applied as in-memory predicates.
    fn constraints(&self) -> Vec<(IndexField, String)> {
        let mut c = Vec::new();
        if let Some(t) = &self.r#type {
            c.push((IndexField::Type, t.clone()));
        }
        if let Some(d) = &self.community_did {
            c.push((IndexField::CommunityDid, d.clone()));
        }
        if let Some(d) = &self.issuer_did {
            c.push((IndexField::IssuerDid, d.clone()));
        }
        if let Some(p) = &self.purpose {
            c.push((IndexField::Purpose, p.as_index_token()));
        }
        if let Some(s) = &self.status {
            c.push((IndexField::Status, s.as_index_token().to_string()));
        }
        c
    }
}

/// Does `cred` satisfy a single `(field, value)` constraint? Mirrors the
/// index semantics in [`StoredCredential::index_terms`] so the in-memory
/// re-check of the non-anchor constraints agrees exactly with what the index
/// scan would have matched.
fn matches_constraint(cred: &StoredCredential, field: IndexField, value: &str) -> bool {
    match field {
        IndexField::Type => cred.types.iter().any(|t| t == value),
        IndexField::CommunityDid => cred.community_did.as_deref() == Some(value),
        IndexField::IssuerDid => cred.issuer_did.as_deref() == Some(value),
        IndexField::Purpose => cred
            .purpose
            .as_ref()
            .map(|p| p.as_index_token() == value)
            .unwrap_or(false),
        IndexField::Status => cred.status.as_index_token() == value,
    }
}

/// Run a local, DCQL-shaped search over the vault and return body-free
/// [`CredentialDescriptor`]s for the matched set.
///
/// **Requires at least one filter.** An empty [`CredentialQuery`] is rejected
/// with [`AppError::Validation`] before any I/O — there is no return-all
/// path, by design (no-enumeration, §14.1 / §16). When several filters are
/// set they are AND-combined: a credential must satisfy every constraint.
///
/// Mechanics: the first set constraint anchors an index scan (via
/// [`super::storage::find_by_index`]), bounding the candidate set to records
/// already known to match one indexed value; the remaining constraints are
/// applied as in-memory predicates. Bodies are loaded only to evaluate those
/// predicates and are **never** placed in the returned descriptors.
pub async fn search(
    vault: &KeyspaceHandle,
    query: &CredentialQuery,
) -> Result<Vec<CredentialDescriptor>, AppError> {
    // No-enumeration gate: reject an unfiltered query outright, before any
    // store access. This is the load-bearing check — without an explicit
    // filter there is no way to start a scan, so the vault cannot be
    // enumerated.
    if query.is_empty() {
        return Err(AppError::Validation(
            "credential search requires at least one filter \
             (type, community_did, issuer_did, purpose, or status); \
             an unfiltered query would enumerate the wallet and is refused"
                .to_string(),
        ));
    }

    let constraints = query.constraints();
    // `constraints()` is non-empty here: `is_empty()` is false, and the two
    // are computed from the same fields. Index 0 is the scan anchor.
    let (anchor_field, anchor_value) = &constraints[0];
    let candidates = super::storage::find_by_index(vault, *anchor_field, anchor_value).await?;

    let mut out = Vec::new();
    for cred in &candidates {
        // Archival lifecycle: an archived or soft-deleted credential is hidden
        // from search the same way revoked/expired ones are — it's not a
        // candidate to present. (The status index still lists it; the
        // exclusion is applied here, after the indexed match.)
        if !cred.is_active() {
            continue;
        }
        // §14 invariant 5: a revoked (or expired) credential is never a search result,
        // regardless of the filter — not even when the caller explicitly asks
        // for `status = revoked`. This is the load-bearing exclusion that keeps
        // the status task's revocation verdict from being undone by search
        // surfacing the credential to a verifier as presentable.
        if is_excluded_status(cred.status) {
            continue;
        }
        // The anchor already matched via the index; re-check the remaining
        // constraints in memory. AND semantics: any miss drops the record.
        let all_match = constraints[1..]
            .iter()
            .all(|(field, value)| matches_constraint(cred, *field, value));
        if all_match {
            out.push(CredentialDescriptor::from_record(cred));
        }
    }
    Ok(out)
}

/// `true` for the lifecycle states that must never appear in a search result
/// (§14 invariant 5). A [`CredentialStatus::Revoked`] credential is unpresentable, and an
/// [`CredentialStatus::Expired`] one is past its validity window — neither is a
/// candidate the holder's agent should offer. [`CredentialStatus::Valid`] and
/// [`CredentialStatus::Unknown`] are surfaced.
fn is_excluded_status(status: CredentialStatus) -> bool {
    matches!(
        status,
        CredentialStatus::Revoked | CredentialStatus::Expired
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::vault::model::{CredentialFormat, CredentialPurpose, CredentialStatus};
    use crate::vault::storage::put;
    use vti_common::config::StoreConfig;
    use vti_common::store::Store;

    fn fresh_vault() -> (tempfile::TempDir, Store, KeyspaceHandle) {
        let dir = tempfile::tempdir().expect("tempdir");
        let store = Store::open(&StoreConfig {
            data_dir: dir.path().to_path_buf(),
        })
        .expect("open store");
        let ks = store
            .keyspace(crate::keyspaces::VAULT)
            .expect("vault keyspace");
        (dir, store, ks)
    }

    fn sample(id: &str) -> StoredCredential {
        StoredCredential {
            id: id.to_string(),
            format: CredentialFormat::SdJwtVc,
            types: vec!["VerifiableCredential".into(), "InvitationCredential".into()],
            schema_id: Some("schema:invite:1".into()),
            community_did: Some("did:web:acme".into()),
            subject_did: Some("did:key:zAlice".into()),
            issuer_did: Some("did:web:issuer.example".into()),
            purpose: Some(CredentialPurpose::Invite),
            status: CredentialStatus::Unknown,
            valid_from: Some("2026-01-01T00:00:00Z".into()),
            valid_until: Some("2027-01-01T00:00:00Z".into()),
            received_at: "2026-06-03T00:00:00Z".into(),
            source: Some("exchange:thread-42".into()),
            tags: std::collections::BTreeMap::from([("label".into(), "alice-invite".into())]),
            body: b"opaque.credential.bytes".to_vec(),
            lifecycle: vti_common::vault::VaultStatus::Active,
            archived_at: None,
            deleted_at: None,
            grace_until: None,
        }
    }

    #[tokio::test]
    async fn search_by_indexed_field_returns_descriptors() {
        let (_dir, _store, vault) = fresh_vault();
        put(&vault, &sample("cred-1")).await.unwrap();

        let q = CredentialQuery {
            issuer_did: Some("did:web:issuer.example".into()),
            ..Default::default()
        };
        let hits = search(&vault, &q).await.unwrap();
        assert_eq!(hits.len(), 1);
        let d = &hits[0];
        assert_eq!(d.id, "cred-1");
        assert_eq!(
            d.types,
            vec![
                "VerifiableCredential".to_string(),
                "InvitationCredential".to_string()
            ]
        );
        assert_eq!(d.issuer_did.as_deref(), Some("did:web:issuer.example"));
        assert_eq!(d.purpose, Some(CredentialPurpose::Invite));
        assert_eq!(d.status, CredentialStatus::Unknown);
        assert_eq!(d.valid_from.as_deref(), Some("2026-01-01T00:00:00Z"));
        assert_eq!(d.valid_until.as_deref(), Some("2027-01-01T00:00:00Z"));
    }

    #[tokio::test]
    async fn search_matches_any_type_tag() {
        let (_dir, _store, vault) = fresh_vault();
        put(&vault, &sample("cred-1")).await.unwrap();

        for tag in ["VerifiableCredential", "InvitationCredential"] {
            let q = CredentialQuery {
                r#type: Some(tag.into()),
                ..Default::default()
            };
            let hits = search(&vault, &q).await.unwrap();
            assert_eq!(hits.len(), 1, "type tag {tag} must match");
            assert_eq!(hits[0].id, "cred-1");
        }
    }

    /// CRITICAL: the descriptor never carries the credential body. We prove
    /// it structurally (no `body` field) by serialising the descriptor and
    /// confirming the opaque body bytes are absent from the JSON.
    #[tokio::test]
    async fn descriptors_never_contain_the_body() {
        let (_dir, _store, vault) = fresh_vault();
        put(&vault, &sample("cred-1")).await.unwrap();

        let q = CredentialQuery {
            community_did: Some("did:web:acme".into()),
            ..Default::default()
        };
        let hits = search(&vault, &q).await.unwrap();
        assert_eq!(hits.len(), 1);

        let json = serde_json::to_string(&hits[0]).unwrap();
        assert!(
            !json.contains("opaque.credential.bytes"),
            "descriptor JSON must not contain the credential body"
        );
        assert!(
            !json.contains("body"),
            "descriptor must not even have a body field"
        );
        // It must, however, carry the metadata the holder agent needs.
        assert!(json.contains("cred-1"));
    }

    /// NEGATIVE / no-enumeration test: an unfiltered query is impossible to
    /// run. There is no return-all path; the empty query is refused.
    #[tokio::test]
    async fn unfiltered_query_is_rejected_no_enumeration() {
        let (_dir, _store, vault) = fresh_vault();
        // Several credentials exist...
        put(&vault, &sample("cred-1")).await.unwrap();
        let mut other = sample("cred-2");
        other.issuer_did = Some("did:web:other".into());
        other.community_did = Some("did:web:other-co".into());
        put(&vault, &other).await.unwrap();

        // ...but a no-filter query cannot retrieve any of them.
        let empty = CredentialQuery::default();
        assert!(empty.is_empty());
        let err = search(&vault, &empty).await.unwrap_err();
        assert!(
            matches!(err, AppError::Validation(_)),
            "an unfiltered (enumerate-all) query must be rejected, got {err:?}"
        );

        // And there is genuinely no other entry point that returns the set:
        // the only way to get results is to name an indexed value. Naming a
        // value the caller already knows returns exactly that one.
        let q = CredentialQuery {
            issuer_did: Some("did:web:other".into()),
            ..Default::default()
        };
        let hits = search(&vault, &q).await.unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].id, "cred-2");
    }

    #[tokio::test]
    async fn multiple_filters_are_and_combined() {
        let (_dir, _store, vault) = fresh_vault();

        // Two credentials share a community but differ by issuer + purpose.
        let mut a = sample("cred-a");
        a.issuer_did = Some("did:web:issuer-a".into());
        a.purpose = Some(CredentialPurpose::Membership);

        let mut b = sample("cred-b");
        b.issuer_did = Some("did:web:issuer-b".into());
        b.purpose = Some(CredentialPurpose::Invite);

        put(&vault, &a).await.unwrap();
        put(&vault, &b).await.unwrap();

        // Filter on shared community alone → both.
        let q = CredentialQuery {
            community_did: Some("did:web:acme".into()),
            ..Default::default()
        };
        let mut ids = search(&vault, &q)
            .await
            .unwrap()
            .into_iter()
            .map(|d| d.id)
            .collect::<Vec<_>>();
        ids.sort();
        assert_eq!(ids, vec!["cred-a", "cred-b"]);

        // Add a purpose constraint → AND narrows to exactly one.
        let q = CredentialQuery {
            community_did: Some("did:web:acme".into()),
            purpose: Some(CredentialPurpose::Membership),
            ..Default::default()
        };
        let hits = search(&vault, &q).await.unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].id, "cred-a");

        // Contradictory AND (community matches, issuer doesn't) → empty,
        // never an error and never a wider fallback.
        let q = CredentialQuery {
            community_did: Some("did:web:acme".into()),
            issuer_did: Some("did:web:nobody".into()),
            ..Default::default()
        };
        assert!(search(&vault, &q).await.unwrap().is_empty());
    }

    #[tokio::test]
    async fn search_by_status_filter_surfaces_valid() {
        let (_dir, _store, vault) = fresh_vault();
        let mut valid = sample("cred-valid");
        valid.status = CredentialStatus::Valid;
        put(&vault, &valid).await.unwrap();

        let q = CredentialQuery {
            status: Some(CredentialStatus::Valid),
            ..Default::default()
        };
        let hits = search(&vault, &q).await.unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].id, "cred-valid");
        assert_eq!(hits[0].status, CredentialStatus::Valid);
    }

    /// §14 invariant 5: revoked credentials are excluded from search — even when the
    /// caller explicitly filters `status = revoked`, there is no "show me my
    /// revoked credentials" surface here.
    #[tokio::test]
    async fn revoked_and_expired_are_excluded_from_search() {
        let (_dir, _store, vault) = fresh_vault();
        let mut valid = sample("cred-valid");
        valid.status = CredentialStatus::Valid;
        let mut revoked = sample("cred-revoked");
        revoked.status = CredentialStatus::Revoked;
        revoked.issuer_did = Some("did:web:issuer-r".into());
        let mut expired = sample("cred-expired");
        expired.status = CredentialStatus::Expired;
        expired.issuer_did = Some("did:web:issuer-e".into());
        put(&vault, &valid).await.unwrap();
        put(&vault, &revoked).await.unwrap();
        put(&vault, &expired).await.unwrap();

        // A shared-community search returns ONLY the valid credential; the
        // revoked and expired ones are dropped.
        let q = CredentialQuery {
            community_did: Some("did:web:acme".into()),
            ..Default::default()
        };
        let hits = search(&vault, &q).await.unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].id, "cred-valid");

        // Explicitly asking for revoked still returns nothing.
        let q = CredentialQuery {
            status: Some(CredentialStatus::Revoked),
            ..Default::default()
        };
        assert!(
            search(&vault, &q).await.unwrap().is_empty(),
            "there is no search surface that returns revoked credentials"
        );

        // Likewise for expired.
        let q = CredentialQuery {
            status: Some(CredentialStatus::Expired),
            ..Default::default()
        };
        assert!(search(&vault, &q).await.unwrap().is_empty());
    }

    #[tokio::test]
    async fn no_match_returns_empty_not_error() {
        let (_dir, _store, vault) = fresh_vault();
        put(&vault, &sample("cred-1")).await.unwrap();

        let q = CredentialQuery {
            issuer_did: Some("did:web:nonexistent".into()),
            ..Default::default()
        };
        assert!(search(&vault, &q).await.unwrap().is_empty());
    }
}