vtc-service 0.12.0

//! `GET /v1/ceremonies` — the ceremony registry.
//!
//! The daemon is the source of truth for *which* ceremonies exist and
//! how their decision surface is shaped. Each manifest carries the
//! ceremony's metadata (purpose, package, nature, copy), the
//! simulator's input **fields** (a declarative UI schema), and a
//! **facts template** — a JSON skeleton of the verified-Facts `input`
//! document with `$field:<key>` / `$now` / `$if` directives the
//! admin-UI materializes from the field values.
//!
//! This is what makes a ceremony *over an existing effect* data, not
//! code: adding one is a manifest entry here, and the admin-UI renders
//! its whole flow + simulator from this endpoint — no per-ceremony
//! frontend. The effect a ceremony triggers (admit / depart / remint /
//! project) stays reviewed Rust; this registry only describes the
//! decision surface.

use serde::Serialize;
use serde_json::{Value as JsonValue, json};

#[derive(Serialize, utoipa::ToSchema)]
pub struct FieldOption {
    pub value: &'static str,
    pub label: &'static str,
}

/// A `showWhen` predicate, declarative so it crosses the wire: render
/// the field only when `field`'s value equals `eq` (or its truthiness
/// matches `truthy`).
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
#[derive(utoipa::ToSchema)]
pub struct ShowWhen {
    pub field: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub eq: Option<JsonValue>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub truthy: Option<bool>,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
#[derive(utoipa::ToSchema)]
pub struct FieldDef {
    pub key: &'static str,
    pub label: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<&'static str>,
    #[serde(rename = "type")]
    pub field_type: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub options: Option<Vec<FieldOption>>,
    pub default: JsonValue,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub show_when: Option<ShowWhen>,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
#[derive(utoipa::ToSchema)]
pub struct CeremonyManifest {
    pub purpose: &'static str,
    pub pkg: &'static str,
    pub nature: &'static str,
    pub label: &'static str,
    pub wired: &'static str,
    pub blurb: &'static str,
    pub fields: Vec<FieldDef>,
    /// JSON skeleton of the verified-Facts `input`, with `$field:<key>`
    /// / `$now` / `$if` directives the admin-UI materializes.
    pub facts_template: JsonValue,
}

fn role_options() -> Vec<FieldOption> {
    vec![
        FieldOption {
            value: "member",
            label: "member",
        },
        FieldOption {
            value: "moderator",
            label: "moderator",
        },
        FieldOption {
            value: "admin",
            label: "admin",
        },
    ]
}

fn base_context() -> JsonValue {
    json!({
        "community_did": "did:webvh:demo.example",
        "channel": "rest",
        "member_count": 42,
    })
}

fn manifests() -> Vec<CeremonyManifest> {
    vec![
        CeremonyManifest {
            purpose: "directory",
            pkg: "vtc.directory",
            nature: "read-only",
            label: "Directory",
            wired: "live",
            blurb: "A member views another member's record. Read-only — the verdict's allow carries a field projection, capped by the PII boundary.",
            fields: vec![
                FieldDef {
                    key: "viewerRole",
                    label: "Viewer's community role",
                    hint: Some("actor.role — admin sees the fuller record"),
                    field_type: "select",
                    options: Some(vec![
                        FieldOption {
                            value: "admin",
                            label: "admin",
                        },
                        FieldOption {
                            value: "member",
                            label: "member",
                        },
                        FieldOption {
                            value: "",
                            label: "none (authenticated)",
                        },
                    ]),
                    default: json!("member"),
                    show_when: None,
                },
                FieldDef {
                    key: "subjectIsMember",
                    label: "Subject is a member",
                    hint: Some("state.subject_member present"),
                    field_type: "toggle",
                    options: None,
                    default: json!(true),
                    show_when: None,
                },
                FieldDef {
                    key: "subjectRole",
                    label: "Subject's role",
                    hint: Some("state.subject_member.role"),
                    field_type: "select",
                    options: Some(role_options()),
                    default: json!("member"),
                    show_when: Some(ShowWhen {
                        field: "subjectIsMember",
                        eq: None,
                        truthy: Some(true),
                    }),
                },
            ],
            facts_template: json!({
                "purpose": "directory",
                "now": "$now",
                "actor": { "did": "did:key:zViewer", "role": "$field:viewerRole", "authenticated": true },
                "subject": { "did": "did:key:zTarget" },
                "context": base_context(),
                "evidence": { "request": { "fields_requested": ["did", "role", "joined_at", "status"] } },
                "state": {
                    "subject_member": {
                        "$if": "subjectIsMember",
                        "then": { "role": "$field:subjectRole", "status": "active", "joined_at": "2026-01-02T00:00:00Z" },
                        "else": null
                    }
                }
            }),
        },
        CeremonyManifest {
            purpose: "join",
            pkg: "vtc.join",
            nature: "constructive",
            label: "Join",
            wired: "live",
            blurb: "A DID joins under one of the community's published criteria. A met automatic criterion admits, a met review criterion refers to an administrator, an unmet one asks for what is missing. A policy may tighten this, never loosen it.",
            fields: vec![
                FieldDef {
                    key: "criterionAdmission",
                    label: "The governing criterion admits",
                    hint: Some("evidence.criterion.admission — the criterion's own, as published"),
                    field_type: "select",
                    options: Some(vec![
                        FieldOption {
                            value: "automatic",
                            label: "automatically",
                        },
                        FieldOption {
                            value: "review",
                            label: "after an administrator's review",
                        },
                    ]),
                    default: json!("review"),
                    show_when: None,
                },
                FieldDef {
                    key: "criterionMet",
                    label: "The submission meets it",
                    hint: Some(
                        "evidence.criterion.met — every requirement it states, verified by the host",
                    ),
                    field_type: "toggle",
                    options: None,
                    default: json!(true),
                    show_when: None,
                },
                FieldDef {
                    key: "invitationHeld",
                    label: "Presents a valid invitation",
                    hint: Some(
                        "evidence.invitation — verified, unconsumed; its role scope sets the admitted role",
                    ),
                    field_type: "toggle",
                    options: None,
                    default: json!(false),
                    show_when: None,
                },
            ],
            facts_template: json!({
                "purpose": "join",
                "now": "$now",
                "actor": { "did": "did:key:zApplicant", "authenticated": true },
                "subject": { "did": "did:key:zApplicant" },
                "context": base_context(),
                "evidence": {
                    "presentation": {
                        "verified": true,
                        "holder": "did:key:zApplicant",
                        "credentials": []
                    },
                    // Absent unless the applicant presents one: a
                    // present-but-false invitation is a different fact from no
                    // invitation.
                    "invitation": {
                        "$if": "invitationHeld",
                        "then": {
                            "verified": true,
                            "issuer": "did:example:this-community",
                            "issuer_trusted": true,
                            "scopes": [],
                            "consumed": false
                        }
                    },
                    // The host's verdict on the governing criterion. `needs` is
                    // never empty when it is not met, as the host guarantees.
                    "criterion": {
                        "id": "simulated",
                        "requirements_digest": "zSimulatedCriterion",
                        "admission": "$field:criterionAdmission",
                        "met": "$field:criterionMet",
                        "needs": {
                            "$if": "criterionMet",
                            "then": [], "else": ["credentials"]
                        },
                        "cited": false
                    }
                },
                "state": { "subject_member": null }
            }),
        },
        CeremonyManifest {
            purpose: "removal",
            pkg: "vtc.removal",
            nature: "destructive",
            label: "Leave",
            wired: "live",
            blurb: "A member departs or is removed. Self-leave is unconditional; an admin may remove a non-admin. The no-last-admin invariant + revocation are host-enforced in the effect.",
            fields: vec![
                FieldDef {
                    key: "selfLeave",
                    label: "Self-leave",
                    hint: Some("actor.did == subject.did — always allowed"),
                    field_type: "toggle",
                    options: None,
                    default: json!(false),
                    show_when: None,
                },
                FieldDef {
                    key: "subjectRole",
                    label: "Subject's role",
                    hint: Some("an admin may remove a non-admin only"),
                    field_type: "select",
                    options: Some(role_options()),
                    default: json!("member"),
                    show_when: Some(ShowWhen {
                        field: "selfLeave",
                        eq: None,
                        truthy: Some(false),
                    }),
                },
            ],
            facts_template: json!({
                "purpose": "leave",
                "now": "$now",
                "actor": { "did": "did:key:zActor", "role": "admin", "authenticated": true },
                "subject": { "did": { "$if": "selfLeave", "then": "did:key:zActor", "else": "did:key:zTarget" } },
                "context": base_context(),
                "evidence": { "request": { "disposition": "tombstone" } },
                "state": { "subject_member": { "role": "$field:subjectRole", "status": "active", "joined_at": "2026-01-02T00:00:00Z" } }
            }),
        },
        CeremonyManifest {
            purpose: "roleChange",
            pkg: "vtc.role_change",
            nature: "mutating",
            label: "Role change",
            wired: "live",
            blurb: "A member's role changes in place (the DID + VMC are unchanged; the role VAC is re-minted). The one ceremony whose allow may grant admin — gated by a verified step-up; demotions are guarded by no-last-admin.",
            fields: vec![
                FieldDef {
                    key: "targetRole",
                    label: "Target role",
                    hint: Some("evidence.request.target_role"),
                    field_type: "select",
                    options: Some(vec![
                        FieldOption {
                            value: "member",
                            label: "member",
                        },
                        FieldOption {
                            value: "moderator",
                            label: "moderator",
                        },
                        FieldOption {
                            value: "admin",
                            label: "admin (promotion)",
                        },
                    ]),
                    default: json!("moderator"),
                    show_when: None,
                },
                FieldDef {
                    key: "stepUp",
                    label: "Step-up verified",
                    hint: Some("admin needs step-up — else the verdict refers"),
                    field_type: "toggle",
                    options: None,
                    default: json!(false),
                    show_when: Some(ShowWhen {
                        field: "targetRole",
                        eq: Some(json!("admin")),
                        truthy: None,
                    }),
                },
            ],
            facts_template: json!({
                "purpose": "role-change",
                "now": "$now",
                "actor": { "did": "did:key:zAdmin", "role": "admin", "authenticated": true },
                "subject": { "did": "did:key:zTarget" },
                "context": base_context(),
                "evidence": { "request": { "target_role": "$field:targetRole", "step_up": "$field:stepUp" } },
                "state": { "subject_member": { "role": "member", "status": "active", "joined_at": "2026-01-02T00:00:00Z" } }
            }),
        },
    ]
}

/// `GET /v1/ceremonies` — list the ceremony manifests. Authenticated
/// (any session); the payload is admin-UI metadata, not secret, but
/// the surface lives behind the same gate as the rest of the API.
/// `vtc/ceremonies/list/0.1`. A signed document served by the spine
/// (`trust_tasks::community_tasks`).
pub(crate) fn list() -> CeremonyListResponse {
    CeremonyListResponse {
        ceremonies: manifests(),
    }
}

/// `{ ceremonies: […] }` — the shape `vtc/ceremonies/list/0.1` publishes. The
/// handler sent a top-level array until #1094. An array cannot grow a sibling
/// member later without breaking every reader; the envelope is why the spec
/// asks for one.
#[derive(Serialize, utoipa::ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct CeremonyListResponse {
    pub ceremonies: Vec<CeremonyManifest>,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::policy::model::PolicyPurpose;

    #[test]
    fn four_ceremonies_with_stable_purposes() {
        let m = manifests();
        let purposes: Vec<_> = m.iter().map(|c| c.purpose).collect();
        assert_eq!(purposes, vec!["directory", "join", "removal", "roleChange"]);
    }

    #[test]
    fn every_field_default_is_present_and_typed() {
        for c in manifests() {
            for f in &c.fields {
                assert!(!f.default.is_null(), "{}::{} default", c.purpose, f.key);
                if f.field_type == "select" {
                    assert!(
                        f.options.is_some(),
                        "{}::{} needs options",
                        c.purpose,
                        f.key
                    );
                }
            }
        }
    }

    #[test]
    fn facts_template_carries_the_purpose() {
        for c in manifests() {
            let p = c.facts_template.get("purpose").and_then(|v| v.as_str());
            assert!(p.is_some(), "{} facts_template purpose", c.purpose);
        }
    }

    /// The published `ceremonies/list/0.1` schema caps a blurb at 256
    /// characters, and the response validator turns an over-long one into a
    /// 500 for the whole listing — so every ceremony page goes blank, not just
    /// the one whose text grew. Cheap to check here; expensive to meet as an
    /// integration failure, which is how it was found.
    #[test]
    fn no_blurb_outgrows_the_published_schema() {
        for c in manifests() {
            assert!(
                c.blurb.chars().count() <= 256,
                "{} blurb is {} characters",
                c.purpose,
                c.blurb.chars().count()
            );
        }
    }

    fn join() -> CeremonyManifest {
        manifests()
            .into_iter()
            .find(|c| c.purpose == "join")
            .expect("join ceremony")
    }

    #[test]
    fn join_offers_both_admission_modes() {
        let join = join();
        let admission = join
            .fields
            .iter()
            .find(|f| f.key == "criterionAdmission")
            .expect("criterionAdmission field");
        let values: Vec<_> = admission
            .options
            .as_ref()
            .expect("options")
            .iter()
            .map(|o| o.value)
            .collect();
        assert_eq!(values, vec!["automatic", "review"]);
    }

    /// The simulator is only worth anything if it produces the facts the live
    /// policy reads. Both sides are checked against each other here, so a
    /// rename on either one fails rather than silently making a route
    /// unreachable in the dry-run.
    #[test]
    fn join_facts_carry_every_path_the_shipped_policy_reads() {
        let template = join().facts_template.to_string();
        let policy = crate::policy::default::default_source(PolicyPurpose::Join);
        for member in ["met", "admission"] {
            assert!(
                policy.contains(&format!("input.evidence.criterion.{member}")),
                "join.rego no longer reads criterion.{member}"
            );
            assert!(
                template.contains(&format!("\"{member}\"")),
                "the join simulator cannot set criterion.{member}"
            );
        }
        for member in ["verified", "consumed", "scopes"] {
            assert!(
                policy.contains(&format!("input.evidence.invitation.{member}")),
                "join.rego no longer reads invitation.{member}"
            );
        }
        assert!(
            template.contains("\"invitation\""),
            "the join simulator cannot present an invitation"
        );
    }
}