GATOS Privacy: ADR‑0004 + SPEC/TECH‑SPEC + Pointer Schema + gatos‑privacy crate #47
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| [package] | ||
| name = "gatos-privacy" | ||
| version = "0.1.0" | ||
| edition = "2021" | ||
|
|
||
| [dependencies] | ||
| gatos-ledger-core = { path = "../gatos-ledger-core" } | ||
| serde = { workspace = true, features = ["derive"] } | ||
| serde_json = { workspace = true } | ||
| blake3 = { workspace = true } | ||
| hex = { workspace = true } | ||
| anyhow = { workspace = true } | ||
|
|
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| //! gatos-privacy — Opaque Pointer types and helpers | ||
| //! | ||
| //! This crate defines the JSON-facing pointer envelope used by the | ||
| //! hybrid privacy model (ADR-0004). The struct mirrors the v1 schema | ||
| //! in `schemas/v1/privacy/opaque_pointer.schema.json`. | ||
| //! | ||
| //! Canonicalization: when computing content IDs or digests, callers | ||
| //! MUST serialize JSON using RFC 8785 JCS. This crate intentionally | ||
| //! does not take a dependency on a specific JCS implementation to | ||
| //! keep the workspace lean; higher layers may provide one. | ||
| use serde::{Deserialize, Serialize}; | ||
| use serde_json::Value; | ||
|
|
||
| #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] | ||
| #[serde(deny_unknown_fields)] | ||
| pub struct OpaquePointer { | ||
| pub kind: Kind, | ||
| pub algo: Algo, | ||
| pub digest: String, | ||
| #[serde(skip_serializing_if = "Option::is_none")] | ||
| pub ciphertext_digest: Option<String>, | ||
|
Comment on lines
+17
to
+22
There was a problem hiding this comment.
The new JSON schema explicitly permits opaque pointers that omit Useful? React with 👍 / 👎. |
||
| #[serde(skip_serializing_if = "Option::is_none")] | ||
| pub size: Option<u64>, | ||
| pub location: String, | ||
| pub capability: String, | ||
| #[serde(skip_serializing_if = "Option::is_none")] | ||
| pub extensions: Option<Value>, | ||
| } | ||
|
Comment on lines
+17
to
+29
There was a problem hiding this comment. CRITICAL: Rust struct violates schema's anyOf requirement. Line 20 declares This mismatch means:
Both #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OpaquePointer {
pub kind: Kind,
pub algo: Algo,
- pub digest: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub digest: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub ciphertext_digest: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub size: Option<u64>,
pub location: String,
pub capability: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub extensions: Option<Value>,
}Then add a validation method: impl OpaquePointer {
pub fn validate(&self) -> Result<(), &'static str> {
if self.digest.is_none() && self.ciphertext_digest.is_none() {
return Err("At least one of digest or ciphertext_digest must be present");
}
Ok(())
}
} |
||
|
|
||
| #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] | ||
| #[serde(rename_all = "snake_case")] | ||
| pub enum Kind { | ||
| OpaquePointer, | ||
| } | ||
|
Comment on lines
+31
to
+35
There was a problem hiding this comment. 🧹 Nitpick | 🔵 Trivial Consider: Single-variant enum may be premature. The However, if the enum is intentional for future extensibility, consider adding a doc comment explaining the planned variants. If future kinds are planned: /// Pointer envelope kinds.
///
/// Future variants may include `TransparentPointer`, `NullPointer`, etc.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Kind {
OpaquePointer,
// Future: TransparentPointer, NullPointer, ...
}If not: // Replace enum with constant
pub const KIND: &str = "opaque_pointer";
// In struct:
pub struct OpaquePointer {
#[serde(default = "default_kind")]
pub kind: String,
// ...
}
fn default_kind() -> String {
KIND.to_string()
}🤖 Prompt for AI Agents |
||
|
|
||
| #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] | ||
| #[serde(rename_all = "lowercase")] | ||
| pub enum Algo { | ||
| Blake3, | ||
| } | ||
|
Comment on lines
+37
to
+41
There was a problem hiding this comment. 🧹 Nitpick | 🔵 Trivial Same consideration for Algo enum: future-proof or simplify. The If the enum is intentional for crypto-agility, add documentation explaining the design choice. /// Hash algorithm for pointer digests.
///
/// Currently only BLAKE3 is supported. Future variants may include
/// SHA3-256 or other cryptographic hash functions as the ecosystem evolves.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Algo {
Blake3,
// Future: Sha3, ...
}🤖 Prompt for AI Agents |
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🧹 Nitpick | 🔵 Trivial
Minor: Indentation inconsistency in lint-md and fix-md targets.
Lines 15 and 22 use mixed tabs/spaces within bash command continuation. While functionally harmless, consider normalizing indentation to project standard (tabs or spaces) for consistency with the rest of the Makefile.
Also applies to: 22-22
🤖 Prompt for AI Agents