feat(platform): D2: hold and scope artifacts by group

.workhorse/specs/platform/artifacts.md

@@ -29,15 +29,21 @@ A publisher sends the bytes on the connection it registers over and is issued no
 Canopy holds such an artifact in storage of its own, apart from any group's backup repo, so an artifact carries the retention, access, and cost basis of an artifact rather than those a backup repo is kept under (see [BAK](../public-server/backup.md)).
 Where Canopy puts them is its own, and no caller addresses them there.
 Canopy holds an artifact's bytes for as long as that artifact is registered, and keeps none of what it has stopped serving.
+A registration or a deregistration that fails once the bytes have moved can leave bytes no artifact reaches, and Canopy drops those as well rather than letting them accumulate.
+It does not expire bytes by age: an artifact's bytes are kept as long as it is registered however long that is, so age alone never says an artifact is finished with.
 
 Canopy serves the bytes only to a caller the artifact is offered to.
 The boundary is therefore enforced on the read rather than resting on a location being hard to guess.
+An artifact whose bytes Canopy cannot produce is answered as one that does not exist, identically to an artifact the caller is not offered, so what Canopy has failed to keep is not discoverable through the read.
 
 An artifact Canopy holds and an artifact Canopy records a location for are one thing to whoever is offered it.
 It is offered one artifact per type and platform, and where the bytes rest is not part of what it is offered.
 
 ## What a version offers
 
+A read names a version range, and an exact version is a valid one.
+An exact version is answered for itself; a range is answered for the latest published version it covers that no known issue covers.
+
 Canopy offers a caller one artifact per type and platform, chosen from the artifacts that caller may see: those belonging to no group, and those scoped to the caller's group where that group is known.
 Where several match, the most specific is offered.
 An artifact scoped to the caller's group is more specific than one belonging to no group.
@@ -72,7 +78,9 @@ Canopy records which device registered an artifact and, where the registration n
 
 ## Digests
 
-An artifact carries a digest where whoever registers it records one, and a group-scoped artifact carries one always.
-Canopy verifies a group-scoped artifact's bytes against its digest as they arrive and refuses the registration on a mismatch, so a corrupted upload is refused while whoever sent it is still there to send it again.
+An artifact carries a digest where whoever registers it records one, and an artifact Canopy holds carries one always.
+A digest is expressed in Subresource Integrity format, using SHA-256.
+A registration naming anything else is refused.
+Canopy verifies the bytes it holds against their digest as they arrive and refuses the registration on a mismatch, so a corrupted upload is refused while whoever sent it is still there to send it again.
 It verifies them again as it serves them and refuses them on a mismatch, so an artifact corrupted after it was taken in fails the read rather than reaching a server as the artifact it is not.
 An unscoped artifact is read from its location by the caller rather than by Canopy, so its digest is what that caller checks what it fetched against, and an artifact registered without one is fetched unchecked.

ERRORS.md

@@ -37,6 +37,14 @@ Issued when a database resource (such as a version, server, or other entity) can
 
 Issued when a version range is valid, but does not match any of the available versions.
 
+## Artifact not found
+
+Issued when the version has no artifact with the given id that the caller is offered. An artifact scoped to a group the caller is not in is reported the same way as one that does not exist, so which groups hold an artifact cannot be discovered through this endpoint.
+
+## Artifact digest mismatch
+
+Issued when the bytes Canopy holds for an artifact do not match the digest recorded for it. The artifact is not served: a corrupted artifact fails the read rather than reaching a server as the artifact it is not.
+
 ## Unusable range
 
 Issued when a version range is syntactically valid, but not usable to obtain concrete versions.

crates/canopy-api/src/generated.rs

@@ -7,7 +7,7 @@ pub const OPENAPI_VERSION: &str = "1.0.1";
 
 /// BLAKE3 digest of that document, so a document that changed without the
 /// version moving with it can be told from one that did not.
-pub const OPENAPI_BLAKE3: &str = "7618bb56960b10e83dac565b3dde53060531f2ef31bc1a7fa4fe6cf308ef5f02";
+pub const OPENAPI_BLAKE3: &str = "7f018c9f89e7dacc44a693ef7d042946a314225a1b998d69a4e8154ef09199a6";
 
 /// Error types.
 pub mod error {
@@ -260,6 +260,13 @@ package, or other file published for a given type and platform.*/
 ///      ],
 ///      "format": "uuid"
 ///    },
+///    "digest": {
+///      "description": "Subresource Integrity digest of the artifact's bytes, e.g.\n`sha256-LCTbqp…`, where one was recorded.",
+///      "type": [
+///        "string",
+///        "null"
+///      ]
+///    },
 ///    "download_url": {
 ///      "description": "URL the artifact can be downloaded from.",
 ///      "type": "string"
@@ -302,6 +309,10 @@ pub struct Artifact {
 releaser device rather than created by an operator.*/
     #[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
     pub device_id: ::std::option::Option<::uuid::Uuid>,
+    /**Subresource Integrity digest of the artifact's bytes, e.g.
+`sha256-LCTbqp…`, where one was recorded.*/
+    #[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
+    pub digest: ::std::option::Option<::std::string::String>,
     ///URL the artifact can be downloaded from.
     pub download_url: ::std::string::String,
     ///Unique identifier of the artifact.

crates/commons-errors/src/lib.rs

@@ -66,6 +66,12 @@ pub enum AppError {
 	#[error("no versions match given range")]
 	NoMatchingVersions,
 
+	#[error("no such artifact for this version")]
+	ArtifactNotFound,
+
+	#[error("artifact does not match its digest")]
+	ArtifactDigestMismatch,
+
 	#[error("version range is not usable")]
 	UnusableRange,
 
@@ -249,6 +255,12 @@ impl AppError {
 		match self {
 			Self::NotImplemented => StatusCode::NOT_IMPLEMENTED,
 			Self::NoMatchingVersions => StatusCode::NOT_FOUND,
+			// An artifact a caller is not offered is missing in exactly the
+			// way one that never existed is, so which groups hold an artifact
+			// is not enumerable through this endpoint.
+			// spec: ART#who-is-offered-a-group-scoped-artifact
+			Self::ArtifactNotFound => StatusCode::NOT_FOUND,
+			Self::ArtifactDigestMismatch => StatusCode::INTERNAL_SERVER_ERROR,
 			Self::UnusableRange => StatusCode::BAD_REQUEST,
 			// Both arise purely from what a client sent: a version segment in
 			// a URL path, or the `X-Version` header. Nothing on the server is
@@ -322,6 +334,8 @@ impl AppError {
 						Self::Tera(_) => "render",
 						Self::Io(_) => "io",
 						Self::NoMatchingVersions => "no-matching-versions",
+						Self::ArtifactNotFound => "artifact-not-found",
+						Self::ArtifactDigestMismatch => "artifact-digest-mismatch",
 						Self::UnusableRange => "unusable-range",
 						Self::Timesync(_) => "timesync",
 						Self::AuthMissingHeader(_) => "auth-missing-header",
@@ -376,3 +390,33 @@ impl<'de> Deserialize<'de> for AppError {
 		Ok(AppError::Problem(Box::new(value)))
 	}
 }
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	/// Input an operator or a client controls answers as their mistake, not as
+	/// a fault, and carries the slug its documentation is written under.
+	#[test]
+	fn a_client_mistake_is_not_a_fault() {
+		for (error, status, slug) in [
+			(
+				AppError::BadRequest("no".into()),
+				StatusCode::BAD_REQUEST,
+				"/errors/bad-request",
+			),
+			(
+				AppError::Conflict("taken".into()),
+				StatusCode::CONFLICT,
+				"/errors/conflict",
+			),
+		] {
+			let problem = error.to_problem_details();
+			assert_eq!(problem.status, Some(status));
+			assert_eq!(
+				problem.r#type.as_ref().map(ToString::to_string).as_deref(),
+				Some(slug)
+			);
+		}
+	}
+}

crates/commons-servers/Cargo.toml

@@ -15,6 +15,8 @@ age = { version = "0.12.1", default-features = false }
 aws-config.workspace = true
 aws-credential-types = "1.3.0"
 aws-sdk-route53 = "1.118.0"
+aws-sdk-s3.workspace = true
+aws-sdk-sts.workspace = true
 axum = { workspace = true, features = ["json", "macros"] }
 axum-client-ip = { version = "1.3.1", features = ["forwarded-header"] }
 axum-server-timing = "3.0.1"
@@ -56,9 +58,12 @@ tower-http = { version = "0.7.0", features = [
 	"trace",
 ] }
 tracing.workspace = true
+uuid = { version = "1.23.1", features = ["v4"] }
 # `verify` gives `verify_signature` on a parsed CSR — proof the sender holds the
 # key it asks Canopy to certify. Backed by ring, already a dependency here.
 x509-parser = { version = "0.18.1", features = ["verify"] }
 
 [dev-dependencies]
+aws-sdk-s3 = { workspace = true, features = ["test-util"] }
+aws-smithy-mocks.workspace = true
 axum-test = { workspace = true }