+1

CHANGELOG.md

··· 12 12 - Remove bearer token authentication fallback from AppView [#26](https://issues.opake.app/issues/26.html) 13 13 14 14 ### Added 15 15 + - Add directory record type and mkdir command [#98](https://issues.opake.app/issues/98.html) 15 16 - Add issue tracker link to README [#142](https://issues.opake.app/issues/142.html) 16 17 - Add crosslink-issue-renderer submodule and CI/CD pipeline [#141](https://issues.opake.app/issues/141.html) 17 18 - Migrate from chainlink to crosslink and slim project docs [#137](https://issues.opake.app/issues/137.html)

+30

crates/opake-cli/src/commands/mkdir.rs

··· 1 1 + use anyhow::Result; 2 2 + use chrono::Utc; 3 3 + use clap::Args; 4 4 + use opake_core::client::Session; 5 5 + use opake_core::directories; 6 6 + 7 7 + use crate::commands::Execute; 8 8 + use crate::session::{self, CommandContext}; 9 9 + 10 10 + #[derive(Args)] 11 11 + /// Create a directory 12 12 + pub struct MkdirCommand { 13 13 + /// Name for the directory 14 14 + name: String, 15 15 + } 16 16 + 17 17 + impl Execute for MkdirCommand { 18 18 + async fn execute(self, ctx: &CommandContext) -> Result<Option<Session>> { 19 19 + let mut client = session::load_client(&ctx.did)?; 20 20 + let now = Utc::now().to_rfc3339(); 21 21 + 22 22 + let root_uri = directories::get_or_create_root(&mut client, &ctx.did, &now).await?; 23 23 + let directory_uri = directories::create_directory(&mut client, &self.name, &now).await?; 24 24 + directories::add_entry(&mut client, &root_uri, &directory_uri, &now).await?; 25 25 + 26 26 + println!("{} → {}", self.name, directory_uri); 27 27 + 28 28 + Ok(session::refreshed_session(&client)) 29 29 + } 30 30 + }

+1

crates/opake-cli/src/commands/mod.rs

··· 5 5 pub mod login; 6 6 pub mod logout; 7 7 pub mod ls; 8 8 + pub mod mkdir; 8 9 pub mod resolve; 9 10 pub mod revoke; 10 11 pub mod rm;

+2

crates/opake-cli/src/main.rs

··· 39 39 Download(commands::download::DownloadCommand), 40 40 Inbox(commands::inbox::InboxCommand), 41 41 Ls(commands::ls::LsCommand), 42 42 + Mkdir(commands::mkdir::MkdirCommand), 42 43 Rm(commands::rm::RmCommand), 43 44 Resolve(commands::resolve::ResolveCommand), 44 45 Share(commands::share::ShareCommand), ··· 95 96 Command::Download(cmd) => run_with_context(as_flag.as_deref(), cmd).await?, 96 97 Command::Inbox(cmd) => run_with_context(as_flag.as_deref(), cmd).await?, 97 98 Command::Ls(cmd) => run_with_context(as_flag.as_deref(), cmd).await?, 99 99 + Command::Mkdir(cmd) => run_with_context(as_flag.as_deref(), cmd).await?, 98 100 Command::Rm(cmd) => run_with_context(as_flag.as_deref(), cmd).await?, 99 101 Command::Resolve(cmd) => run_with_context(as_flag.as_deref(), cmd).await?, 100 102 Command::Share(cmd) => run_with_context(as_flag.as_deref(), cmd).await?,

+76

crates/opake-core/src/directories/create.rs

··· 1 1 + use log::debug; 2 2 + 3 3 + use crate::client::{Transport, XrpcClient}; 4 4 + use crate::error::Error; 5 5 + use crate::records::Directory; 6 6 + 7 7 + use super::DIRECTORY_COLLECTION; 8 8 + 9 9 + /// Create a new directory record. Returns its AT-URI. 10 10 + pub async fn create_directory( 11 11 + client: &mut XrpcClient<impl Transport>, 12 12 + name: &str, 13 13 + created_at: &str, 14 14 + ) -> Result<String, Error> { 15 15 + let directory = Directory::new(name.to_string(), created_at.to_string()); 16 16 + 17 17 + debug!("creating directory {:?}", name); 18 18 + let record_ref = client 19 19 + .create_record(DIRECTORY_COLLECTION, &directory) 20 20 + .await?; 21 21 + 22 22 + Ok(record_ref.uri) 23 23 + } 24 24 + 25 25 + #[cfg(test)] 26 26 + mod tests { 27 27 + use super::*; 28 28 + use crate::client::RequestBody; 29 29 + use crate::records::Directory; 30 30 + use crate::test_utils::MockTransport; 31 31 + 32 32 + use super::super::tests::{create_record_response, mock_client, TEST_DID}; 33 33 + 34 34 + #[tokio::test] 35 35 + async fn happy_path() { 36 36 + let uri = format!("at://{TEST_DID}/app.opake.cloud.directory/tid123"); 37 37 + let mock = MockTransport::new(); 38 38 + mock.enqueue(create_record_response(&uri)); 39 39 + 40 40 + let mut client = mock_client(mock.clone()); 41 41 + let result = create_directory(&mut client, "Photos", "2026-03-01T00:00:00Z") 42 42 + .await 43 43 + .unwrap(); 44 44 + 45 45 + assert_eq!(result, uri); 46 46 + 47 47 + let reqs = mock.requests(); 48 48 + assert_eq!(reqs.len(), 1); 49 49 + assert!(reqs[0].url.contains("createRecord")); 50 50 + 51 51 + match &reqs[0].body { 52 52 + Some(RequestBody::Json(v)) => { 53 53 + assert_eq!(v["collection"], "app.opake.cloud.directory"); 54 54 + let record: Directory = serde_json::from_value(v["record"].clone()).unwrap(); 55 55 + assert_eq!(record.name, "Photos"); 56 56 + assert!(record.entries.is_empty()); 57 57 + } 58 58 + _ => panic!("expected JSON body"), 59 59 + } 60 60 + } 61 61 + 62 62 + #[tokio::test] 63 63 + async fn pds_error_propagates() { 64 64 + let mock = MockTransport::new(); 65 65 + mock.enqueue(crate::client::HttpResponse { 66 66 + status: 500, 67 67 + body: br#"{"error":"InternalServerError","message":"oops"}"#.to_vec(), 68 68 + }); 69 69 + 70 70 + let mut client = mock_client(mock); 71 71 + let err = create_directory(&mut client, "Broken", "2026-03-01T00:00:00Z") 72 72 + .await 73 73 + .unwrap_err(); 74 74 + assert!(matches!(err, Error::Xrpc { .. })); 75 75 + } 76 76 + }

+145

crates/opake-core/src/directories/delete.rs

··· 1 1 + use log::debug; 2 2 + 3 3 + use crate::atproto; 4 4 + use crate::client::{Transport, XrpcClient}; 5 5 + use crate::error::Error; 6 6 + use crate::records::{self, Directory}; 7 7 + 8 8 + use super::{DIRECTORY_COLLECTION, ROOT_DIRECTORY_RKEY}; 9 9 + 10 10 + /// Delete a directory record by AT-URI. 11 11 + /// 12 12 + /// Rejects deletion of the root directory (rkey "self") and non-empty 13 13 + /// directories. Validates the collection is `app.opake.cloud.directory`. 14 14 + pub async fn delete_directory( 15 15 + client: &mut XrpcClient<impl Transport>, 16 16 + uri: &str, 17 17 + ) -> Result<(), Error> { 18 18 + let at_uri = atproto::parse_at_uri(uri)?; 19 19 + 20 20 + if at_uri.collection != DIRECTORY_COLLECTION { 21 21 + return Err(Error::InvalidRecord(format!( 22 22 + "expected a directory URI ({}), got collection: {}", 23 23 + DIRECTORY_COLLECTION, at_uri.collection, 24 24 + ))); 25 25 + } 26 26 + 27 27 + if at_uri.rkey == ROOT_DIRECTORY_RKEY { 28 28 + return Err(Error::InvalidRecord( 29 29 + "cannot delete the root directory".into(), 30 30 + )); 31 31 + } 32 32 + 33 33 + debug!("fetching directory to check emptiness: {}", uri); 34 34 + let entry = client 35 35 + .get_record(&at_uri.authority, &at_uri.collection, &at_uri.rkey) 36 36 + .await?; 37 37 + 38 38 + let directory: Directory = serde_json::from_value(entry.value)?; 39 39 + records::check_version(directory.version)?; 40 40 + 41 41 + if !directory.entries.is_empty() { 42 42 + return Err(Error::InvalidRecord(format!( 43 43 + "directory is not empty ({} entries)", 44 44 + directory.entries.len(), 45 45 + ))); 46 46 + } 47 47 + 48 48 + debug!("deleting directory {}", uri); 49 49 + client 50 50 + .delete_record(&at_uri.collection, &at_uri.rkey) 51 51 + .await?; 52 52 + 53 53 + Ok(()) 54 54 + } 55 55 + 56 56 + #[cfg(test)] 57 57 + mod tests { 58 58 + use super::*; 59 59 + use crate::client::HttpResponse; 60 60 + use crate::test_utils::MockTransport; 61 61 + 62 62 + use super::super::tests::{ 63 63 + dummy_directory, dummy_directory_with_entries, get_record_response, mock_client, TEST_DID, 64 64 + }; 65 65 + 66 66 + #[tokio::test] 67 67 + async fn happy_path() { 68 68 + let directory = dummy_directory("Photos"); 69 69 + let uri = format!("at://{TEST_DID}/app.opake.cloud.directory/dir1"); 70 70 + let mock = MockTransport::new(); 71 71 + mock.enqueue(get_record_response(&uri, &directory)); 72 72 + mock.enqueue(HttpResponse { 73 73 + status: 200, 74 74 + body: b"{}".to_vec(), 75 75 + }); 76 76 + 77 77 + let mut client = mock_client(mock.clone()); 78 78 + delete_directory(&mut client, &uri).await.unwrap(); 79 79 + 80 80 + let reqs = mock.requests(); 81 81 + assert_eq!(reqs.len(), 2); 82 82 + assert!(reqs[0].url.contains("getRecord")); 83 83 + assert!(reqs[1].url.contains("deleteRecord")); 84 84 + } 85 85 + 86 86 + #[tokio::test] 87 87 + async fn rejects_root_deletion() { 88 88 + let mock = MockTransport::new(); 89 89 + let mut client = mock_client(mock); 90 90 + let uri = format!("at://{TEST_DID}/app.opake.cloud.directory/self"); 91 91 + 92 92 + let err = delete_directory(&mut client, &uri).await.unwrap_err(); 93 93 + assert!(err.to_string().contains("root directory")); 94 94 + } 95 95 + 96 96 + #[tokio::test] 97 97 + async fn rejects_non_empty_directory() { 98 98 + let directory = dummy_directory_with_entries( 99 99 + "Photos", 100 100 + vec!["at://did:plc:test/app.opake.cloud.document/doc1".into()], 101 101 + ); 102 102 + let uri = format!("at://{TEST_DID}/app.opake.cloud.directory/dir1"); 103 103 + let mock = MockTransport::new(); 104 104 + mock.enqueue(get_record_response(&uri, &directory)); 105 105 + 106 106 + let mut client = mock_client(mock); 107 107 + let err = delete_directory(&mut client, &uri).await.unwrap_err(); 108 108 + assert!(err.to_string().contains("not empty")); 109 109 + } 110 110 + 111 111 + #[tokio::test] 112 112 + async fn rejects_wrong_collection() { 113 113 + let mock = MockTransport::new(); 114 114 + let mut client = mock_client(mock); 115 115 + let uri = format!("at://{TEST_DID}/app.opake.cloud.document/abc"); 116 116 + 117 117 + let err = delete_directory(&mut client, &uri).await.unwrap_err(); 118 118 + assert!(err.to_string().contains("expected a directory URI")); 119 119 + } 120 120 + 121 121 + #[tokio::test] 122 122 + async fn rejects_invalid_uri() { 123 123 + let mock = MockTransport::new(); 124 124 + let mut client = mock_client(mock); 125 125 + 126 126 + let err = delete_directory(&mut client, "not-a-uri") 127 127 + .await 128 128 + .unwrap_err(); 129 129 + assert!(err.to_string().contains("AT-URI")); 130 130 + } 131 131 + 132 132 + #[tokio::test] 133 133 + async fn pds_404_on_fetch() { 134 134 + let uri = format!("at://{TEST_DID}/app.opake.cloud.directory/gone"); 135 135 + let mock = MockTransport::new(); 136 136 + mock.enqueue(HttpResponse { 137 137 + status: 404, 138 138 + body: br#"{"error":"RecordNotFound","message":"no such record"}"#.to_vec(), 139 139 + }); 140 140 + 141 141 + let mut client = mock_client(mock); 142 142 + let err = delete_directory(&mut client, &uri).await.unwrap_err(); 143 143 + assert!(matches!(err, Error::NotFound(_))); 144 144 + } 145 145 + }

+213

crates/opake-core/src/directories/entries.rs

··· 1 1 + use log::debug; 2 2 + 3 3 + use crate::atproto; 4 4 + use crate::client::{Transport, XrpcClient}; 5 5 + use crate::error::Error; 6 6 + use crate::records::{self, Directory}; 7 7 + 8 8 + use super::DIRECTORY_COLLECTION; 9 9 + 10 10 + /// Add a child entry to a directory (fetch-modify-put). 11 11 + /// 12 12 + /// Rejects duplicates. Appends to the end of the entries list. 13 13 + pub async fn add_entry( 14 14 + client: &mut XrpcClient<impl Transport>, 15 15 + directory_uri: &str, 16 16 + entry_uri: &str, 17 17 + modified_at: &str, 18 18 + ) -> Result<(), Error> { 19 19 + let at_uri = atproto::parse_at_uri(directory_uri)?; 20 20 + 21 21 + debug!("fetching directory {}", directory_uri); 22 22 + let entry = client 23 23 + .get_record(&at_uri.authority, &at_uri.collection, &at_uri.rkey) 24 24 + .await?; 25 25 + 26 26 + let mut directory: Directory = serde_json::from_value(entry.value)?; 27 27 + records::check_version(directory.version)?; 28 28 + 29 29 + if directory.entries.iter().any(|e| e == entry_uri) { 30 30 + return Err(Error::InvalidRecord(format!( 31 31 + "{entry_uri} is already in this directory" 32 32 + ))); 33 33 + } 34 34 + 35 35 + debug!("adding entry {}", entry_uri); 36 36 + directory.entries.push(entry_uri.to_string()); 37 37 + directory.modified_at = Some(modified_at.to_string()); 38 38 + 39 39 + client 40 40 + .put_record(DIRECTORY_COLLECTION, &at_uri.rkey, &directory) 41 41 + .await?; 42 42 + 43 43 + Ok(()) 44 44 + } 45 45 + 46 46 + /// Remove a child entry from a directory (fetch-modify-put). 47 47 + /// 48 48 + /// Errors if the entry is not present. 49 49 + pub async fn remove_entry( 50 50 + client: &mut XrpcClient<impl Transport>, 51 51 + directory_uri: &str, 52 52 + entry_uri: &str, 53 53 + modified_at: &str, 54 54 + ) -> Result<(), Error> { 55 55 + let at_uri = atproto::parse_at_uri(directory_uri)?; 56 56 + 57 57 + debug!("fetching directory {}", directory_uri); 58 58 + let entry = client 59 59 + .get_record(&at_uri.authority, &at_uri.collection, &at_uri.rkey) 60 60 + .await?; 61 61 + 62 62 + let mut directory: Directory = serde_json::from_value(entry.value)?; 63 63 + records::check_version(directory.version)?; 64 64 + 65 65 + let original_len = directory.entries.len(); 66 66 + directory.entries.retain(|e| e != entry_uri); 67 67 + 68 68 + if directory.entries.len() == original_len { 69 69 + return Err(Error::NotFound(format!( 70 70 + "{entry_uri} not found in directory" 71 71 + ))); 72 72 + } 73 73 + 74 74 + debug!("removed entry {}", entry_uri); 75 75 + directory.modified_at = Some(modified_at.to_string()); 76 76 + 77 77 + client 78 78 + .put_record(DIRECTORY_COLLECTION, &at_uri.rkey, &directory) 79 79 + .await?; 80 80 + 81 81 + Ok(()) 82 82 + } 83 83 + 84 84 + #[cfg(test)] 85 85 + mod tests { 86 86 + use super::*; 87 87 + use crate::client::RequestBody; 88 88 + use crate::records::{Directory, SCHEMA_VERSION}; 89 89 + use crate::test_utils::MockTransport; 90 90 + 91 91 + use super::super::tests::{ 92 92 + dummy_directory_with_entries, get_record_response, mock_client, put_record_response, 93 93 + }; 94 94 + 95 95 + const DIR_URI: &str = "at://did:plc:test/app.opake.cloud.directory/dir1"; 96 96 + const DOC_URI: &str = "at://did:plc:test/app.opake.cloud.document/doc1"; 97 97 + const DOC_URI_2: &str = "at://did:plc:test/app.opake.cloud.document/doc2"; 98 98 + 99 99 + #[tokio::test] 100 100 + async fn add_entry_happy_path() { 101 101 + let directory = dummy_directory_with_entries("/", vec![]); 102 102 + let mock = MockTransport::new(); 103 103 + mock.enqueue(get_record_response(DIR_URI, &directory)); 104 104 + mock.enqueue(put_record_response(DIR_URI)); 105 105 + 106 106 + let mut client = mock_client(mock.clone()); 107 107 + add_entry(&mut client, DIR_URI, DOC_URI, "2026-03-01T12:00:00Z") 108 108 + .await 109 109 + .unwrap(); 110 110 + 111 111 + let reqs = mock.requests(); 112 112 + assert_eq!(reqs.len(), 2); 113 113 + assert!(reqs[0].url.contains("getRecord")); 114 114 + assert!(reqs[1].url.contains("putRecord")); 115 115 + 116 116 + match &reqs[1].body { 117 117 + Some(RequestBody::Json(v)) => { 118 118 + let updated: Directory = serde_json::from_value(v["record"].clone()).unwrap(); 119 119 + assert_eq!(updated.entries, vec![DOC_URI]); 120 120 + assert_eq!(updated.modified_at.unwrap(), "2026-03-01T12:00:00Z"); 121 121 + } 122 122 + _ => panic!("expected JSON body"), 123 123 + } 124 124 + } 125 125 + 126 126 + #[tokio::test] 127 127 + async fn add_entry_rejects_duplicate() { 128 128 + let directory = dummy_directory_with_entries("/", vec![DOC_URI.into()]); 129 129 + let mock = MockTransport::new(); 130 130 + mock.enqueue(get_record_response(DIR_URI, &directory)); 131 131 + 132 132 + let mut client = mock_client(mock); 133 133 + let err = add_entry(&mut client, DIR_URI, DOC_URI, "2026-03-01T12:00:00Z") 134 134 + .await 135 135 + .unwrap_err(); 136 136 + 137 137 + assert!(err.to_string().contains("already in this directory")); 138 138 + } 139 139 + 140 140 + #[tokio::test] 141 141 + async fn add_entry_rejects_future_version() { 142 142 + let mut directory = dummy_directory_with_entries("/", vec![]); 143 143 + directory.version = SCHEMA_VERSION + 1; 144 144 + 145 145 + let mock = MockTransport::new(); 146 146 + mock.enqueue(get_record_response(DIR_URI, &directory)); 147 147 + 148 148 + let mut client = mock_client(mock); 149 149 + let err = add_entry(&mut client, DIR_URI, DOC_URI, "2026-03-01T12:00:00Z") 150 150 + .await 151 151 + .unwrap_err(); 152 152 + 153 153 + assert!(err.to_string().contains("schema version")); 154 154 + } 155 155 + 156 156 + #[tokio::test] 157 157 + async fn remove_entry_happy_path() { 158 158 + let directory = dummy_directory_with_entries("/", vec![DOC_URI.into(), DOC_URI_2.into()]); 159 159 + let mock = MockTransport::new(); 160 160 + mock.enqueue(get_record_response(DIR_URI, &directory)); 161 161 + mock.enqueue(put_record_response(DIR_URI)); 162 162 + 163 163 + let mut client = mock_client(mock.clone()); 164 164 + remove_entry(&mut client, DIR_URI, DOC_URI, "2026-03-01T12:00:00Z") 165 165 + .await 166 166 + .unwrap(); 167 167 + 168 168 + let reqs = mock.requests(); 169 169 + match &reqs[1].body { 170 170 + Some(RequestBody::Json(v)) => { 171 171 + let updated: Directory = serde_json::from_value(v["record"].clone()).unwrap(); 172 172 + assert_eq!(updated.entries, vec![DOC_URI_2]); 173 173 + assert!(updated.modified_at.is_some()); 174 174 + } 175 175 + _ => panic!("expected JSON body"), 176 176 + } 177 177 + } 178 178 + 179 179 + #[tokio::test] 180 180 + async fn remove_entry_not_found() { 181 181 + let directory = dummy_directory_with_entries("/", vec![DOC_URI.into()]); 182 182 + let mock = MockTransport::new(); 183 183 + mock.enqueue(get_record_response(DIR_URI, &directory)); 184 184 + 185 185 + let mut client = mock_client(mock); 186 186 + let err = remove_entry( 187 187 + &mut client, 188 188 + DIR_URI, 189 189 + "at://did:plc:test/app.opake.cloud.document/nope", 190 190 + "2026-03-01T12:00:00Z", 191 191 + ) 192 192 + .await 193 193 + .unwrap_err(); 194 194 + 195 195 + assert!(matches!(err, Error::NotFound(_))); 196 196 + } 197 197 + 198 198 + #[tokio::test] 199 199 + async fn remove_entry_rejects_future_version() { 200 200 + let mut directory = dummy_directory_with_entries("/", vec![DOC_URI.into()]); 201 201 + directory.version = SCHEMA_VERSION + 1; 202 202 + 203 203 + let mock = MockTransport::new(); 204 204 + mock.enqueue(get_record_response(DIR_URI, &directory)); 205 205 + 206 206 + let mut client = mock_client(mock); 207 207 + let err = remove_entry(&mut client, DIR_URI, DOC_URI, "2026-03-01T12:00:00Z") 208 208 + .await 209 209 + .unwrap_err(); 210 210 + 211 211 + assert!(err.to_string().contains("schema version")); 212 212 + } 213 213 + }

+114

crates/opake-core/src/directories/get_or_create_root.rs

··· 1 1 + use log::debug; 2 2 + 3 3 + use crate::client::{Transport, XrpcClient}; 4 4 + use crate::error::Error; 5 5 + use crate::records::Directory; 6 6 + 7 7 + use super::{DIRECTORY_COLLECTION, ROOT_DIRECTORY_NAME, ROOT_DIRECTORY_RKEY}; 8 8 + 9 9 + /// Get the root directory's AT-URI, creating it if it doesn't exist. 10 10 + /// 11 11 + /// The root directory is a singleton at rkey "self" with name "/". 12 12 + /// Uses `put_record` for creation (idempotent upsert with explicit rkey). 13 13 + pub async fn get_or_create_root( 14 14 + client: &mut XrpcClient<impl Transport>, 15 15 + did: &str, 16 16 + created_at: &str, 17 17 + ) -> Result<String, Error> { 18 18 + debug!("checking for root directory"); 19 19 + match client 20 20 + .get_record(did, DIRECTORY_COLLECTION, ROOT_DIRECTORY_RKEY) 21 21 + .await 22 22 + { 23 23 + Ok(entry) => { 24 24 + debug!("root directory exists: {}", entry.uri); 25 25 + Ok(entry.uri) 26 26 + } 27 27 + Err(Error::NotFound(_)) => { 28 28 + debug!("root directory not found, creating"); 29 29 + let root = Directory::new(ROOT_DIRECTORY_NAME.to_string(), created_at.to_string()); 30 30 + let record_ref = client 31 31 + .put_record(DIRECTORY_COLLECTION, ROOT_DIRECTORY_RKEY, &root) 32 32 + .await?; 33 33 + Ok(record_ref.uri) 34 34 + } 35 35 + Err(e) => Err(e), 36 36 + } 37 37 + } 38 38 + 39 39 + #[cfg(test)] 40 40 + mod tests { 41 41 + use super::*; 42 42 + use crate::client::RequestBody; 43 43 + use crate::records::Directory; 44 44 + use crate::test_utils::MockTransport; 45 45 + 46 46 + use super::super::tests::{ 47 47 + dummy_directory, get_record_response, mock_client, not_found_response, put_record_response, 48 48 + TEST_DID, 49 49 + }; 50 50 + 51 51 + const ROOT_URI: &str = "at://did:plc:test/app.opake.cloud.directory/self"; 52 52 + 53 53 + #[tokio::test] 54 54 + async fn returns_existing_root() { 55 55 + let root = dummy_directory("/"); 56 56 + let mock = MockTransport::new(); 57 57 + mock.enqueue(get_record_response(ROOT_URI, &root)); 58 58 + 59 59 + let mut client = mock_client(mock.clone()); 60 60 + let uri = get_or_create_root(&mut client, TEST_DID, "2026-03-01T00:00:00Z") 61 61 + .await 62 62 + .unwrap(); 63 63 + 64 64 + assert_eq!(uri, ROOT_URI); 65 65 + 66 66 + let reqs = mock.requests(); 67 67 + assert_eq!(reqs.len(), 1); 68 68 + assert!(reqs[0].url.contains("getRecord")); 69 69 + } 70 70 + 71 71 + #[tokio::test] 72 72 + async fn creates_root_on_404() { 73 73 + let mock = MockTransport::new(); 74 74 + mock.enqueue(not_found_response()); 75 75 + mock.enqueue(put_record_response(ROOT_URI)); 76 76 + 77 77 + let mut client = mock_client(mock.clone()); 78 78 + let uri = get_or_create_root(&mut client, TEST_DID, "2026-03-01T00:00:00Z") 79 79 + .await 80 80 + .unwrap(); 81 81 + 82 82 + assert_eq!(uri, ROOT_URI); 83 83 + 84 84 + let reqs = mock.requests(); 85 85 + assert_eq!(reqs.len(), 2); 86 86 + assert!(reqs[0].url.contains("getRecord")); 87 87 + assert!(reqs[1].url.contains("putRecord")); 88 88 + 89 89 + match &reqs[1].body { 90 90 + Some(RequestBody::Json(v)) => { 91 91 + assert_eq!(v["rkey"], "self"); 92 92 + let record: Directory = serde_json::from_value(v["record"].clone()).unwrap(); 93 93 + assert_eq!(record.name, "/"); 94 94 + assert!(record.entries.is_empty()); 95 95 + } 96 96 + _ => panic!("expected JSON body"), 97 97 + } 98 98 + } 99 99 + 100 100 + #[tokio::test] 101 101 + async fn propagates_non_404_errors() { 102 102 + let mock = MockTransport::new(); 103 103 + mock.enqueue(crate::client::HttpResponse { 104 104 + status: 500, 105 105 + body: br#"{"error":"InternalServerError","message":"boom"}"#.to_vec(), 106 106 + }); 107 107 + 108 108 + let mut client = mock_client(mock); 109 109 + let err = get_or_create_root(&mut client, TEST_DID, "2026-03-01T00:00:00Z") 110 110 + .await 111 111 + .unwrap_err(); 112 112 + assert!(matches!(err, Error::Xrpc { .. })); 113 113 + } 114 114 + }

+147

crates/opake-core/src/directories/list.rs

··· 1 1 + use crate::client::{list_collection, Transport, XrpcClient}; 2 2 + use crate::error::Error; 3 3 + use crate::records::Directory; 4 4 + 5 5 + use super::DIRECTORY_COLLECTION; 6 6 + 7 7 + /// A directory listing entry with its AT-URI and parsed metadata. 8 8 + #[derive(Debug)] 9 9 + pub struct DirectoryEntry { 10 10 + pub uri: String, 11 11 + pub name: String, 12 12 + pub entry_count: usize, 13 13 + pub created_at: String, 14 14 + } 15 15 + 16 16 + /// Fetch all directory records, paginating through the full collection. 17 17 + /// Silently skips records that can't be parsed or have an unsupported 18 18 + /// schema version. 19 19 + pub async fn list_directories( 20 20 + client: &mut XrpcClient<impl Transport>, 21 21 + ) -> Result<Vec<DirectoryEntry>, Error> { 22 22 + list_collection(client, DIRECTORY_COLLECTION, |uri, directory: Directory| { 23 23 + DirectoryEntry { 24 24 + uri: uri.to_owned(), 25 25 + name: directory.name, 26 26 + entry_count: directory.entries.len(), 27 27 + created_at: directory.created_at, 28 28 + } 29 29 + }) 30 30 + .await 31 31 + } 32 32 + 33 33 + #[cfg(test)] 34 34 + mod tests { 35 35 + use super::*; 36 36 + use crate::client::HttpResponse; 37 37 + use crate::records; 38 38 + use crate::test_utils::MockTransport; 39 39 + 40 40 + use super::super::tests::{ 41 41 + dummy_directory, dummy_directory_with_entries, list_records_response, mock_client, 42 42 + }; 43 43 + 44 44 + #[tokio::test] 45 45 + async fn single_directory() { 46 46 + let mock = MockTransport::new(); 47 47 + mock.enqueue(list_records_response( 48 48 + &[("dir1", dummy_directory("Photos"))], 49 49 + None, 50 50 + )); 51 51 + 52 52 + let mut client = mock_client(mock.clone()); 53 53 + let entries = list_directories(&mut client).await.unwrap(); 54 54 + 55 55 + assert_eq!(entries.len(), 1); 56 56 + assert_eq!(entries[0].name, "Photos"); 57 57 + assert_eq!(entries[0].entry_count, 0); 58 58 + assert!(entries[0].uri.contains("dir1")); 59 59 + 60 60 + let reqs = mock.requests(); 61 61 + assert!(reqs[0].url.contains("app.opake.cloud.directory")); 62 62 + } 63 63 + 64 64 + #[tokio::test] 65 65 + async fn multiple_directories() { 66 66 + let docs = vec![ 67 67 + ("dir1", dummy_directory("Photos")), 68 68 + ( 69 69 + "dir2", 70 70 + dummy_directory_with_entries( 71 71 + "Documents", 72 72 + vec!["at://did:plc:test/app.opake.cloud.document/a".into()], 73 73 + ), 74 74 + ), 75 75 + ]; 76 76 + let mock = MockTransport::new(); 77 77 + mock.enqueue(list_records_response(&docs, None)); 78 78 + 79 79 + let mut client = mock_client(mock); 80 80 + let entries = list_directories(&mut client).await.unwrap(); 81 81 + 82 82 + assert_eq!(entries.len(), 2); 83 83 + assert_eq!(entries[0].name, "Photos"); 84 84 + assert_eq!(entries[0].entry_count, 0); 85 85 + assert_eq!(entries[1].name, "Documents"); 86 86 + assert_eq!(entries[1].entry_count, 1); 87 87 + } 88 88 + 89 89 + #[tokio::test] 90 90 + async fn paginates() { 91 91 + let mock = MockTransport::new(); 92 92 + mock.enqueue(list_records_response( 93 93 + &[("d1", dummy_directory("First"))], 94 94 + Some("cursor-1"), 95 95 + )); 96 96 + mock.enqueue(list_records_response( 97 97 + &[("d2", dummy_directory("Second"))], 98 98 + None, 99 99 + )); 100 100 + 101 101 + let mut client = mock_client(mock.clone()); 102 102 + let entries = list_directories(&mut client).await.unwrap(); 103 103 + 104 104 + assert_eq!(entries.len(), 2); 105 105 + assert_eq!(entries[0].name, "First"); 106 106 + assert_eq!(entries[1].name, "Second"); 107 107 + 108 108 + let reqs = mock.requests(); 109 109 + assert!(reqs[1].url.contains("cursor=cursor-1")); 110 110 + } 111 111 + 112 112 + #[tokio::test] 113 113 + async fn empty_collection() { 114 114 + let mock = MockTransport::new(); 115 115 + mock.enqueue(list_records_response(&[], None)); 116 116 + 117 117 + let mut client = mock_client(mock); 118 118 + let entries = list_directories(&mut client).await.unwrap(); 119 119 + assert!(entries.is_empty()); 120 120 + } 121 121 + 122 122 + #[tokio::test] 123 123 + async fn skips_future_version() { 124 124 + let mut directory = dummy_directory("Future"); 125 125 + directory.version = records::SCHEMA_VERSION + 1; 126 126 + 127 127 + let mock = MockTransport::new(); 128 128 + mock.enqueue(list_records_response(&[("d1", directory)], None)); 129 129 + 130 130 + let mut client = mock_client(mock); 131 131 + let entries = list_directories(&mut client).await.unwrap(); 132 132 + assert!(entries.is_empty()); 133 133 + } 134 134 + 135 135 + #[tokio::test] 136 136 + async fn pds_error_propagates() { 137 137 + let mock = MockTransport::new(); 138 138 + mock.enqueue(HttpResponse { 139 139 + status: 500, 140 140 + body: br#"{"error":"InternalServerError","message":"boom"}"#.to_vec(), 141 141 + }); 142 142 + 143 143 + let mut client = mock_client(mock); 144 144 + let err = list_directories(&mut client).await.unwrap_err(); 145 145 + assert!(matches!(err, Error::Xrpc { .. })); 146 146 + } 147 147 + }

+120

crates/opake-core/src/directories/mod.rs

··· 1 1 + // Directory operations: create, list, delete, manage entries. 2 2 + // 3 3 + // Directories are purely organizational — no crypto, no encryption. They 4 4 + // own their children via an ordered AT-URI array (children-on-parent model). 5 5 + // The root directory is a lazy-created singleton at rkey "self". 6 6 + 7 7 + mod create; 8 8 + mod delete; 9 9 + mod entries; 10 10 + mod get_or_create_root; 11 11 + mod list; 12 12 + 13 13 + pub use create::create_directory; 14 14 + pub use delete::delete_directory; 15 15 + pub use entries::{add_entry, remove_entry}; 16 16 + pub use get_or_create_root::get_or_create_root; 17 17 + pub use list::{list_directories, DirectoryEntry}; 18 18 + 19 19 + pub const DIRECTORY_COLLECTION: &str = "app.opake.cloud.directory"; 20 20 + pub const ROOT_DIRECTORY_RKEY: &str = "self"; 21 21 + pub const ROOT_DIRECTORY_NAME: &str = "/"; 22 22 + 23 23 + #[cfg(test)] 24 24 + pub(crate) mod tests { 25 25 + use crate::client::{HttpResponse, Session, XrpcClient}; 26 26 + use crate::records::Directory; 27 27 + use crate::test_utils::MockTransport; 28 28 + 29 29 + use super::*; 30 30 + 31 31 + pub const TEST_DID: &str = "did:plc:test"; 32 32 + 33 33 + pub fn mock_client(mock: MockTransport) -> XrpcClient<MockTransport> { 34 34 + let session = Session { 35 35 + did: TEST_DID.into(), 36 36 + handle: "test.handle".into(), 37 37 + access_jwt: "test-jwt".into(), 38 38 + refresh_jwt: "test-refresh".into(), 39 39 + }; 40 40 + XrpcClient::with_session(mock, "https://pds.test".into(), session) 41 41 + } 42 42 + 43 43 + pub fn dummy_directory(name: &str) -> Directory { 44 44 + Directory::new(name.into(), "2026-03-01T00:00:00Z".into()) 45 45 + } 46 46 + 47 47 + pub fn dummy_directory_with_entries(name: &str, entries: Vec<String>) -> Directory { 48 48 + Directory { 49 49 + entries, 50 50 + ..Directory::new(name.into(), "2026-03-01T00:00:00Z".into()) 51 51 + } 52 52 + } 53 53 + 54 54 + pub fn create_record_response(uri: &str) -> HttpResponse { 55 55 + HttpResponse { 56 56 + status: 200, 57 57 + body: serde_json::to_vec(&serde_json::json!({ 58 58 + "uri": uri, 59 59 + "cid": "bafydirectory", 60 60 + })) 61 61 + .unwrap(), 62 62 + } 63 63 + } 64 64 + 65 65 + pub fn put_record_response(uri: &str) -> HttpResponse { 66 66 + HttpResponse { 67 67 + status: 200, 68 68 + body: serde_json::to_vec(&serde_json::json!({ 69 69 + "uri": uri, 70 70 + "cid": "bafyupdated", 71 71 + })) 72 72 + .unwrap(), 73 73 + } 74 74 + } 75 75 + 76 76 + pub fn get_record_response(uri: &str, directory: &Directory) -> HttpResponse { 77 77 + HttpResponse { 78 78 + status: 200, 79 79 + body: serde_json::to_vec(&serde_json::json!({ 80 80 + "uri": uri, 81 81 + "cid": "bafydirectory", 82 82 + "value": directory, 83 83 + })) 84 84 + .unwrap(), 85 85 + } 86 86 + } 87 87 + 88 88 + pub fn list_records_response( 89 89 + directories: &[(&str, Directory)], 90 90 + cursor: Option<&str>, 91 91 + ) -> HttpResponse { 92 92 + let records: Vec<serde_json::Value> = directories 93 93 + .iter() 94 94 + .map(|(rkey, dir)| { 95 95 + serde_json::json!({ 96 96 + "uri": format!("at://{TEST_DID}/{DIRECTORY_COLLECTION}/{rkey}"), 97 97 + "cid": "bafydirectory", 98 98 + "value": dir, 99 99 + }) 100 100 + }) 101 101 + .collect(); 102 102 + 103 103 + let mut body = serde_json::json!({ "records": records }); 104 104 + if let Some(c) = cursor { 105 105 + body["cursor"] = serde_json::Value::String(c.into()); 106 106 + } 107 107 + 108 108 + HttpResponse { 109 109 + status: 200, 110 110 + body: serde_json::to_vec(&body).unwrap(), 111 111 + } 112 112 + } 113 113 + 114 114 + pub fn not_found_response() -> HttpResponse { 115 115 + HttpResponse { 116 116 + status: 404, 117 117 + body: br#"{"error":"RecordNotFound","message":"no such record"}"#.to_vec(), 118 118 + } 119 119 + } 120 120 + }

+1

crates/opake-core/src/lib.rs

··· 17 17 pub mod atproto; 18 18 pub mod client; 19 19 pub mod crypto; 20 20 + pub mod directories; 20 21 pub mod documents; 21 22 pub mod error; 22 23 pub mod keyrings;

+28

crates/opake-core/src/records/directory.rs

··· 1 1 + use serde::{Deserialize, Serialize}; 2 2 + 3 3 + use super::{default_version, SCHEMA_VERSION}; 4 4 + 5 5 + #[derive(Debug, Clone, Serialize, Deserialize)] 6 6 + #[serde(rename_all = "camelCase")] 7 7 + pub struct Directory { 8 8 + #[serde(default = "default_version")] 9 9 + pub version: u32, 10 10 + pub name: String, 11 11 + #[serde(default, skip_serializing_if = "Vec::is_empty")] 12 12 + pub entries: Vec<String>, 13 13 + pub created_at: String, 14 14 + #[serde(skip_serializing_if = "Option::is_none")] 15 15 + pub modified_at: Option<String>, 16 16 + } 17 17 + 18 18 + impl Directory { 19 19 + pub fn new(name: String, created_at: String) -> Self { 20 20 + Self { 21 21 + version: SCHEMA_VERSION, 22 22 + name, 23 23 + entries: Vec::new(), 24 24 + created_at, 25 25 + modified_at: None, 26 26 + } 27 27 + } 28 28 + }

+2 -5

crates/opake-core/src/records/document.rs

··· 43 43 #[serde(default, skip_serializing_if = "Vec::is_empty")] 44 44 pub tags: Vec<String>, 45 45 #[serde(skip_serializing_if = "Option::is_none")] 46 46 - pub parent: Option<String>, 47 47 - #[serde(skip_serializing_if = "Option::is_none")] 48 46 pub description: Option<String>, 49 47 #[serde(skip_serializing_if = "Option::is_none")] 50 48 pub visibility: Option<String>, ··· 55 53 56 54 impl Document { 57 55 /// Construct a new document with the current schema version and sensible 58 58 - /// defaults for optional fields. Callers set tags/parent/description/etc. 59 59 - /// via struct update syntax: `Document::new(..) { tags, ..Document::new(..) }` 56 56 + /// defaults for optional fields. Callers set tags/description/etc. via 57 57 + /// struct update syntax: `Document::new(..) { tags, ..Document::new(..) }` 60 58 pub fn new(name: String, blob: BlobRef, encryption: Encryption, created_at: String) -> Self { 61 59 Self { 62 60 version: SCHEMA_VERSION, ··· 66 64 blob, 67 65 encryption, 68 66 tags: Vec::new(), 69 69 - parent: None, 70 67 description: None, 71 68 visibility: None, 72 69 created_at,

+44 -1

crates/opake-core/src/records/mod.rs

··· 7 7 // `atproto` module. The ones used as record fields are re-exported here. 8 8 9 9 mod defs; 10 10 + mod directory; 10 11 mod document; 11 12 mod grant; 12 13 mod keyring; ··· 20 21 21 22 // Re-export all record types at the `records::` level. 22 23 pub use defs::{EncryptionEnvelope, KeyringRef, WrappedKey}; 24 24 + pub use directory::Directory; 23 25 pub use document::{DirectEncryption, Document, Encryption, KeyringEncryption}; 24 26 pub use grant::Grant; 25 27 pub use keyring::{KeyHistoryEntry, Keyring}; ··· 42 44 }; 43 45 } 44 46 45 45 - impl_versioned!(Document, PublicKeyRecord, Grant, Keyring); 47 47 + impl_versioned!(Directory, Document, PublicKeyRecord, Grant, Keyring); 46 48 47 49 fn default_version() -> u32 { 48 50 SCHEMA_VERSION ··· 109 111 let json = serde_json::to_value(&record).unwrap(); 110 112 // atproto $bytes convention: { "$bytes": "<base64>" } 111 113 assert!(json["publicKey"]["$bytes"].is_string()); 114 114 + } 115 115 + 116 116 + #[test] 117 117 + fn directory_roundtrips_through_json() { 118 118 + let directory = Directory::new("/".into(), "2026-03-01T00:00:00Z".into()); 119 119 + let json = serde_json::to_string(&directory).unwrap(); 120 120 + let parsed: Directory = serde_json::from_str(&json).unwrap(); 121 121 + 122 122 + assert_eq!(parsed.version, SCHEMA_VERSION); 123 123 + assert_eq!(parsed.name, "/"); 124 124 + assert!(parsed.entries.is_empty()); 125 125 + assert_eq!(parsed.created_at, "2026-03-01T00:00:00Z"); 126 126 + assert!(parsed.modified_at.is_none()); 127 127 + } 128 128 + 129 129 + #[test] 130 130 + fn directory_entries_omitted_when_empty() { 131 131 + let directory = Directory::new("Photos".into(), "2026-03-01T00:00:00Z".into()); 132 132 + let json = serde_json::to_value(&directory).unwrap(); 133 133 + assert!( 134 134 + json.get("entries").is_none(), 135 135 + "empty entries should be omitted from serialization" 136 136 + ); 137 137 + } 138 138 + 139 139 + #[test] 140 140 + fn directory_with_entries_roundtrips() { 141 141 + let mut directory = Directory::new("Photos".into(), "2026-03-01T00:00:00Z".into()); 142 142 + directory.entries = vec![ 143 143 + "at://did:plc:test/app.opake.cloud.document/abc".into(), 144 144 + "at://did:plc:test/app.opake.cloud.directory/def".into(), 145 145 + ]; 146 146 + directory.modified_at = Some("2026-03-01T12:00:00Z".into()); 147 147 + 148 148 + let json = serde_json::to_string(&directory).unwrap(); 149 149 + let parsed: Directory = serde_json::from_str(&json).unwrap(); 150 150 + 151 151 + assert_eq!(parsed.entries.len(), 2); 152 152 + assert!(parsed.entries[0].contains("document")); 153 153 + assert!(parsed.entries[1].contains("directory")); 154 154 + assert_eq!(parsed.modified_at.unwrap(), "2026-03-01T12:00:00Z"); 112 155 } 113 156 114 157 #[test]

+41 -3

lexicons/EXAMPLES.md

··· 16 16 17 17 This record uses rkey `self` (like `app.bsky.actor.profile`) — there's only one per account. The key is published automatically on `opake login`. 18 18 19 19 - ## 1. Alice creates a private encrypted document 19 19 + ## 1. Root directory (created on first `opake mkdir`) 20 20 + 21 21 + The root directory is a singleton at rkey `self`. It's lazy-created the first time a user creates a directory. 22 22 + 23 23 + ```json 24 24 + { 25 25 + "$type": "app.opake.cloud.directory", 26 26 + "version": 1, 27 27 + "name": "/", 28 28 + "entries": [ 29 29 + "at://did:plc:alice123/app.opake.cloud.directory/3k..." 30 30 + ], 31 31 + "createdAt": "2026-03-01T10:00:00.000Z", 32 32 + "modifiedAt": "2026-03-01T10:00:00.000Z" 33 33 + } 34 34 + ``` 35 35 + 36 36 + Directories are purely organizational — no encryption, no crypto. The `entries` array is an ordered list of AT-URIs pointing to documents or other directories (children-on-parent model). You can derive the child type from the collection segment of the URI. 37 37 + 38 38 + ## 2. A named directory 39 39 + 40 40 + ```json 41 41 + { 42 42 + "$type": "app.opake.cloud.directory", 43 43 + "version": 1, 44 44 + "name": "Photos", 45 45 + "entries": [ 46 46 + "at://did:plc:alice123/app.opake.cloud.document/3kabcd", 47 47 + "at://did:plc:alice123/app.opake.cloud.document/3kefgh", 48 48 + "at://did:plc:alice123/app.opake.cloud.directory/3kijkl" 49 49 + ], 50 50 + "createdAt": "2026-03-01T10:05:00.000Z", 51 51 + "modifiedAt": "2026-03-01T11:30:00.000Z" 52 52 + } 53 53 + ``` 54 54 + 55 55 + This directory contains two documents and a subdirectory. Non-root directories use TID rkeys (created via `createRecord`). 56 56 + 57 57 + ## 3. Alice creates a private encrypted document 20 58 21 59 ```json 22 60 { ··· 56 94 can decrypt. 57 95 58 96 59 59 - ## 2. Alice shares the document with Bob via a grant 97 97 + ## 4. Alice shares the document with Bob via a grant 60 98 61 99 ```json 62 100 { ··· 87 125 the document with a fresh content key. 88 126 89 127 90 90 - ## 3. Keyring-based group sharing (family photos) 128 128 + ## 5. Keyring-based group sharing (family photos) 91 129 92 130 ### First, the keyring: 93 131

+1

lexicons/README.md

··· 15 15 | NSID | Type | Purpose | 16 16 |------|------|---------| 17 17 | `app.opake.cloud.defs` | defs | Shared type definitions (encryption envelope, wrapped key, etc.) | 18 18 + | `app.opake.cloud.directory` | record | A directory containing an ordered list of child document/directory AT-URIs | 18 19 | `app.opake.cloud.document` | record | An encrypted file/document with metadata | 19 20 | `app.opake.cloud.publicKey` | record | Singleton X25519 encryption public key (rkey: `self`) for key discovery | 20 21 | `app.opake.cloud.keyring` | record | A named group with a shared symmetric key, wrapped to each member |

+35

lexicons/app.opake.cloud.directory.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "app.opake.cloud.directory", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "record", 7 7 + "description": "A directory in the personal cloud. Contains an ordered list of AT-URIs referencing documents or other directories. The root directory is a singleton at rkey 'self'.", 8 8 + "key": "any", 9 9 + "record": { 10 10 + "type": "object", 11 11 + "required": ["version", "name", "createdAt"], 12 12 + "properties": { 13 13 + "version": { 14 14 + "type": "integer", 15 15 + "description": "Schema version for the app.opake.cloud.* namespace.", 16 16 + "minimum": 1 17 17 + }, 18 18 + "name": { 19 19 + "type": "string", 20 20 + "description": "Human-readable directory name. '/' for root.", 21 21 + "maxLength": 512 22 22 + }, 23 23 + "entries": { 24 24 + "type": "array", 25 25 + "description": "Ordered list of AT-URIs of child documents or directories.", 26 26 + "items": { "type": "string", "format": "at-uri" }, 27 27 + "maxLength": 10000 28 28 + }, 29 29 + "createdAt": { "type": "string", "format": "datetime" }, 30 30 + "modifiedAt": { "type": "string", "format": "datetime" } 31 31 + } 32 32 + } 33 33 + } 34 34 + } 35 35 + }

-5

lexicons/app.opake.cloud.document.json

··· 50 50 "items": { "type": "string", "maxLength": 128 }, 51 51 "maxLength": 32 52 52 }, 53 53 - "parent": { 54 54 - "type": "string", 55 55 - "format": "at-uri", 56 56 - "description": "Optional reference to a parent document (for folder-like hierarchy). Points to another app.opake.cloud.document record." 57 57 - }, 58 53 "description": { 59 54 "type": "string", 60 55 "description": "Optional plaintext description or summary.",