Sealed approvals: the approval attestation and oxy seal --flow b582948f1912

//! A person's approval of one job of one run, signed (oxygenhub#235): the

//! approval attestation, the signer's signature over it, and the signer's

//! identity, so it verifies with nothing else. The hub decides whether the

//! signer may approve; the signature makes the decision theirs, and binds

//! it to exactly that job, state, plan and environment.

use crate::attest::{Attest, AttestBody};

use crate::cbor::{self, Value};

use crate::hash::ObjectRef;

use crate::identity::{verify, Domain, Identity, SecretKey, Signature};

use crate::objects::{array, bytes, Hlc, ObjectError};

/// What is approved.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Statement {

    pub repo: [u8; 16],

    /// The run, as its URL on the hub.

    pub run: String,

    pub job: String,

    /// The job's hash with its sandbox (OxygenFlow spec 6.2).

    pub job_hash: ObjectRef,

    pub state: ObjectRef,

    /// The blobs the job takes as inputs (a plan), any order.

    pub inputs: Vec<ObjectRef>,

    pub environment: String,

    pub approve: bool,

}

#[derive(Debug, thiserror::Error)]

pub enum ApprovalError {

    #[error("the attestation is not an approval")]

    NotApproval,

    #[error("no signature by the signer {0}")]

    Unsigned(String),

    #[error("the signature does not verify: {0}")]

    BadSignature(String),

    #[error("{0}")]

    Schema(String),

}

impl From<ObjectError> for ApprovalError {

    fn from(e: ObjectError) -> Self {

        ApprovalError::Schema(e.to_string())

    }

}

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct SignedApproval {

    pub attest: Attest,

    pub sigs: Vec<Signature>,

    pub signer: Identity,

}

impl SignedApproval {

    pub fn sign(s: &Statement, signer: &Identity, sk: &SecretKey) -> SignedApproval {

        let mut inputs = s.inputs.clone();

        inputs.sort();

        inputs.dedup();

        let attest = Attest {

            repo: s.repo,

            hlc: Hlc::now(),

            body: AttestBody::Approval {

                run: s.run.clone(),

                job: s.job.clone(),

                job_hash: s.job_hash,

                state: s.state,

                inputs,

                environment: s.environment.clone(),

                approve: s.approve,

            },

        };

        let sig = sk.sign(Domain::Attest, &signer.hash(), &attest.hash());

        SignedApproval {

            attest,

            sigs: vec![sig],

            signer: signer.clone(),

        }

    }

    /// What was approved, read back from the attestation.

    pub fn statement(&self) -> Result<Statement, ApprovalError> {

        let AttestBody::Approval {

            run,

            job,

            job_hash,

            state,

            inputs,

            environment,

            approve,

        } = &self.attest.body

        else {

            return Err(ApprovalError::NotApproval);

        };

        Ok(Statement {

            repo: self.attest.repo,

            run: run.clone(),

            job: job.clone(),

            job_hash: *job_hash,

            state: *state,

            inputs: inputs.clone(),

            environment: environment.clone(),

            approve: *approve,

        })

    }

    /// It is an approval and the signer signed it. Whether the signer may

    /// approve is the reader's call.

    pub fn verify(&self) -> Result<(), ApprovalError> {

        self.statement()?;

        let key = self.signer.hash();

        let sig = self

            .sigs

            .iter()

            .find(|s| s.key == key)

            .ok_or_else(|| ApprovalError::Unsigned(key.short(12)))?;

        verify(&self.signer, sig, Domain::Attest, &self.attest.hash())

            .map_err(|e| ApprovalError::BadSignature(e.to_string()))

    }

    /// Whether `s` is what this approves (the time it was made aside).

    pub fn covers(&self, s: &Statement) -> bool {

        let mut want = s.inputs.clone();

        want.sort();

        want.dedup();

        self.statement().is_ok_and(|mine| {

            mine == Statement {

                inputs: want,

                ..s.clone()

            }

        })

    }

    /// `[attest, [Signature], identity]`, each object as its bytes.

    pub fn encode(&self) -> Vec<u8> {

        cbor::encode(&Value::Array(vec![

            Value::Bytes(self.attest.encode()),

            Value::Array(self.sigs.iter().map(|s| s.to_value()).collect()),

            Value::Bytes(self.signer.encode()),

        ]))

    }

    pub fn decode(b: &[u8]) -> Result<SignedApproval, ApprovalError> {

        let v = cbor::decode(b).map_err(ObjectError::from)?;

        let a = array(&v, "signed approval")?;

        if a.len() != 3 {

            return Err(ApprovalError::Schema(

                "signed approval: expected [attest, sigs, identity]".into(),

            ));

        }

        Ok(SignedApproval {

            attest: Attest::decode(bytes(&a[0], "attest")?)?,

            sigs: array(&a[1], "sigs")?

                .iter()

                .map(Signature::from_value)

                .collect::<Result<_, _>>()?,

            signer: Identity::decode(bytes(&a[2], "identity")?)?,

        })

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    use crate::identity::SecretKey;

    fn statement() -> Statement {

        Statement {

            repo: [7; 16],

            run: "https://hub.example/andy/infra/flow/8".into(),

            job: "apply".into(),

            job_hash: ObjectRef([1; 32]),

            state: ObjectRef([2; 32]),

            inputs: vec![ObjectRef([4; 32]), ObjectRef([3; 32])],

            environment: "prod".into(),

            approve: true,

        }

    }

    #[test]

    fn an_approval_signs_exactly_one_job_state_plan_and_environment() {

        let sk = SecretKey::generate();

        let id = sk.identity("Andy", "[email protected]", 1);

        let sa = SignedApproval::sign(&statement(), &id, &sk);

        sa.verify().unwrap();

        let back = SignedApproval::decode(&sa.encode()).unwrap();

        assert_eq!(back, sa, "round trip");

        assert!(back.covers(&statement()), "inputs in any order");

        for other in [

            Statement {

                inputs: vec![ObjectRef([9; 32])],

                ..statement()

            },

            Statement {

                state: ObjectRef([8; 32]),

                ..statement()

            },

            Statement {

                job_hash: ObjectRef([8; 32]),

                ..statement()

            },

            Statement {

                run: "https://hub.example/andy/infra/flow/9".into(),

                ..statement()

            },

            Statement {

                environment: "dev".into(),

                ..statement()

            },

            Statement {

                approve: false,

                ..statement()

            },

        ] {

            assert!(!back.covers(&other), "{other:?}");

        }

        // Changed after signing: the signature no longer holds.

        let mut forged = sa.clone();

        if let AttestBody::Approval { inputs, .. } = &mut forged.attest.body {

            inputs[0] = ObjectRef([9; 32]);

        }

        assert!(forged.verify().is_err());

        // Signed by someone else than the identity it carries.

        let other_sk = SecretKey::generate();

        let mut stolen = SignedApproval::sign(&statement(), &id, &other_sk);

        stolen.signer = id.clone();

        assert!(stolen.verify().is_err());

    }

}

//! `oxy seal --flow RUN_URL --job NAME [--reject]` (oxygenhub#235): sign an

//! approval of one job of one run with your key, so the hub can show, and

//! anyone can check, who released it. The hub says what the job is (its

//! hash with its sandbox, the state, the plan it takes, the environment);

//! the signature covers exactly that and nothing else.

use super::{open, ui};

use anyhow::{anyhow, bail, Context, Result};

use oxy_core::approval::{SignedApproval, Statement};

use oxy_core::hash::ObjectRef;

use serde_json::Value;

/// `https://hub/OWNER/NAME/flow/N` to the hub's base, `OWNER/NAME`, N and

/// the repository's URL.

fn run_url(url: &str) -> Result<(String, String, i64, String)> {

    let url = url.trim_end_matches('/');

    let (repo_url, n) = url

        .rsplit_once("/flow/")

        .ok_or_else(|| anyhow!("{url} is not a run URL (…/OWNER/NAME/flow/N)"))?;

    let number: i64 = n

        .parse()

        .map_err(|_| anyhow!("{url} is not a run URL (…/OWNER/NAME/flow/N)"))?;

    let (rest, name) = repo_url

        .rsplit_once('/')

        .ok_or_else(|| anyhow!("{url} is not a run URL"))?;

    let (base, owner) = rest

        .rsplit_once('/')

        .ok_or_else(|| anyhow!("{url} is not a run URL"))?;

    Ok((

        base.to_string(),

        format!("{owner}/{name}"),

        number,

        repo_url.to_string(),

    ))

}

fn to_hex(b: &[u8]) -> String {

    b.iter().map(|x| format!("{x:02x}")).collect()

}

fn oref(v: &Value, key: &str) -> Result<ObjectRef> {

    v.get(key)

        .and_then(Value::as_str)

        .and_then(ObjectRef::from_hex)

        .ok_or_else(|| anyhow!("the hub's statement has no valid {key}"))

}

pub fn seal(url: &str, job: &str, reject: bool, as_json: bool) -> Result<i32> {

    let repo = open()?;

    let (base, slug, number, repo_url) = run_url(url)?;

    let options = repo.options_for_url(&repo_url);

    let api = format!("{base}/api/v1/repos/{slug}/flow/runs/{number}/jobs/{job}/approval");

    let body = oxy_core::protocol::http_get(&api, &options).map_err(|e| anyhow!("{e}"))?;

    let v: Value = serde_json::from_slice(&body).context("the hub did not answer with JSON")?;

    let repo_hex = v.get("repo").and_then(Value::as_str).unwrap_or("");

    let mine = to_hex(&repo.id()?);

    if repo_hex != mine {

        bail!("run #{number} belongs to repository {repo_hex}, not this checkout's ({mine}): run oxy seal --flow from a checkout of {slug}");

    }

    let mut repo_id = [0u8; 16];

    for (i, b) in repo_id.iter_mut().enumerate() {

        *b = u8::from_str_radix(&repo_hex[i * 2..i * 2 + 2], 16)?;

    }

    let inputs = v

        .get("inputs")

        .and_then(Value::as_array)

        .map(|a| {

            a.iter()

                .filter_map(|x| x.as_str().and_then(ObjectRef::from_hex))

                .collect::<Vec<_>>()

        })

        .unwrap_or_default();

    let statement = Statement {

        repo: repo_id,

        run: v

            .get("run")

            .and_then(Value::as_str)

            .unwrap_or(url)

            .to_string(),

        job: job.to_string(),

        job_hash: oref(&v, "job_hash")?,

        state: oref(&v, "state")?,

        inputs,

        environment: v

            .get("environment")

            .and_then(Value::as_str)

            .unwrap_or("")

            .to_string(),

        approve: !reject,

    };

    let (key, sk) = repo

        .secret_key()?

        .ok_or_else(|| anyhow!("no signing key: create one with `oxy identity new`"))?;

    let me = repo.identity(&key)?;

    let signed = SignedApproval::sign(&statement, &me, &sk);

    let post = format!("{base}/api/v1/repos/{slug}/flow/runs/{number}/jobs/{job}/seal");

    let payload = serde_json::json!({ "signed": to_hex(&signed.encode()) }).to_string();

    let (code, answer) = oxy_core::protocol::http_json("POST", &post, Some(&payload), &options)

        .map_err(|e| anyhow!("{e}"))?;

    if !(200..300).contains(&code) {

        let why = serde_json::from_str::<Value>(&answer)

            .ok()

            .and_then(|v| v.get("error").and_then(Value::as_str).map(String::from));

        bail!(

            "the hub refused the seal (HTTP {code}): {}",

            why.unwrap_or(answer)

        );

    }

    if as_json {

        println!("{answer}");

    } else {

        let verb = if reject { "Rejected" } else { "Approved" };

        println!(

            "{} {job} of run #{number} with key {}",

            ui::done(verb),

            &key.to_hex()[..12]

        );

        println!(

            "  state {} · job {}",

            &statement.state.to_hex()[..12],

            &statement.job_hash.to_hex()[..12]

        );

        for i in &statement.inputs {

            println!("  takes {}", &i.to_hex()[..12]);

        }

        if !statement.environment.is_empty() {

            println!("  for environment {}", statement.environment);

        }

    }

    Ok(0)

}

#[cfg(test)]

mod tests {

    #[test]

    fn run_urls_are_read() {

        let (base, slug, n, repo) =

            super::run_url("https://oxygenhub.io/andymccall/oxygenhub-gcp/flow/8/").unwrap();

        assert_eq!(

            (base.as_str(), slug.as_str(), n, repo.as_str()),

            (

                "https://oxygenhub.io",

                "andymccall/oxygenhub-gcp",

                8,

                "https://oxygenhub.io/andymccall/oxygenhub-gcp"

            )

        );

        assert!(super::run_url("https://oxygenhub.io/andymccall/x/proposal/3").is_err());

        assert!(super::run_url("https://oxygenhub.io/andymccall/x/flow/abc").is_err());

    }

}

    /// A person approved (or rejected) one job of one run (OxygenFlow

    /// approval gates; oxygenhub#235): the job as hashed with its sandbox,

    /// on that state, taking exactly those input blobs (a reviewed plan),

    /// for that environment. It approves nothing else.

    Approval {

        run: String,

        job: String,

        job_hash: ObjectRef,

        state: ObjectRef,

        inputs: Vec<ObjectRef>,

        environment: String,

        approve: bool,

    },

            AttestBody::Approval { .. } => "approval",

            ]),

            AttestBody::Approval {

                run,

                job,

                job_hash,

                state,

                inputs,

                environment,

                approve,

            } => Value::map([

                (0, Value::Text(run.clone())),

                (1, Value::Text(job.clone())),

                (2, Value::Bytes(job_hash.0.to_vec())),

                (3, Value::Bytes(state.0.to_vec())),

                (

                    4,

                    Value::Array(inputs.iter().map(|i| Value::Bytes(i.0.to_vec())).collect()),

                ),

                (5, Value::Text(environment.clone())),

                (6, Value::Uint(u64::from(*approve))),

            "approval" => {

                let inputs = array(field(b, 4, "inputs")?, "inputs")?

                    .iter()

                    .map(|h| oref(h, "input"))

                    .collect::<Result<Vec<_>, _>>()?;

                if !inputs.windows(2).all(|w| w[0] < w[1]) {

                    return Err(ObjectError::Schema(

                        "approval: inputs must be sorted and unique".into(),

                    ));

                }

                AttestBody::Approval {

                    run: text(field(b, 0, "run")?, "run")?.to_owned(),

                    job: text(field(b, 1, "job")?, "job")?.to_owned(),

                    job_hash: oref(field(b, 2, "job_hash")?, "job_hash")?,

                    state: oref(field(b, 3, "state")?, "state")?,

                    inputs,

                    environment: text(field(b, 5, "environment")?, "environment")?.to_owned(),

                    approve: match uint(field(b, 6, "approve")?, "approve")? {

                        0 => false,

                        1 => true,

                        _ => return Err(ObjectError::Schema("approval: approve is 0 or 1".into())),

                    },

                }

            }

pub mod approval;

  kind    [1]: "ref" | "tag" | "seal" | "rotate" | "revoke" | "lock" | "receipt" | "approval"

approval: { run: text, job: text, job_hash: ObjectRef, state: ObjectRef,

            inputs: [ObjectRef], environment: text, approve: 0 | 1 }  // sorted, unique inputs

An **approval** is a person's decision about one job of one OxygenFlow run (an approval gate, OxygenFlow spec §5.3.2): the job as hashed with its sandbox, on that state, taking exactly those input blobs (for a deploy, the reviewed plan), for that environment. It approves nothing else: another run, state, plan or environment needs another approval. It is handed to the hub as `[attest bytes, [Signature], identity bytes]`, signed in domain `attest` by the approver's own key (`oxy seal --flow URL --job NAME`, `--reject` to reject), so it verifies with nothing else; whether the signer may approve is the hub's rule (a key linked to an account with the gate's role; delegated keys only where the repository allows). The hub keeps it in the repository, so it can be verified without the hub.

mod approve;

        /// Approve a job of a hub run that waits for a sealed approval: `--flow https://hub/OWNER/NAME/flow/N --job apply`

        #[arg(long, conflicts_with_all = ["changes", "proposal"], requires = "job")]

        flow: Option<String>,

        /// The job to approve, with --flow

        #[arg(long, requires = "flow")]

        job: Option<String>,

        /// Reject the job instead of approving it, with --flow

        #[arg(long, requires = "flow")]

        reject: bool,

            flow: Some(url),

            job: Some(job),

            reject,

            json,

            ..

        } => approve::seal(&url, &job, reject, json),

        Cmd::Seal {

            ..