did-simple: Add docs

crates/did-chain/Cargo.toml

@@ -8,4 +8,4 @@ rust-version.workspace = true
 description = "A chain of Decentralized Identifiers"
 
 [dependencies]
-did-simple = { version = "0.0.0", path = "../did-simple" }
+did-simple = { version = "0.0.1", path = "../did-simple" }

crates/did-simple/Cargo.toml

@@ -1,17 +1,25 @@
 [package]
 name = "did-simple"
-version.workspace = true
+version = "0.0.1-beta.0"
 license.workspace = true
 repository.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 description = "Dead simple DIDs"
-publish = false
+publish = true
+
+[features]
+default = []
+
+# Only applications should enable this! If you use did-simple as a dependency,
+# don't enable this feature - let applications set it instead.
+# Enabling this feature removes the #[forbid(unsafe_code)] crate attribute.
+allow-unsafe = []
 
 [dependencies]
-thiserror = "1.0.60"
-bytes = "1.6.0"
 bs58 = "0.5.1"
+bytes = "1.6.0"
+thiserror = "1.0.60"
 
 [dev-dependencies]
 eyre = "0.6.12"

crates/did-simple/README.md

@@ -0,0 +1,43 @@
+# did-simple
+
+Dead simple [DID][spec]s (Decentralized Identifiers).
+
+This crate provides the ability to:
+* Parse did urls.
+* (optional feature) Perform cryptographic operations on the public keys
+  resolved from DIDs.
+
+We intentionally do not perform IO, such as what would be required to resolve a
+did:web. It is *your* responsibility to do IO, and then use this crate to
+validate that data and get back something that you can do cryptographic operations
+with. This ensures that this crate stays small, and that did-simple can be used
+with any backend or client and in both sync and async paradigms.
+
+Supported DID methods:
+* did:key
+* (coming soon) did:web
+
+# Security
+
+This crate enforces `#![forbid(unsafe_code)]` unless the `allow-unsafe` feature
+is enabled. Since features in rust are additive across a dependency graph, don't
+enable this feature unless you are writing an application!
+
+This crate has a very high bar for the addition of new dependencies, because
+dependencies are places where the software supply chain can be attacked. Right now,
+we have zero non-rust dependencies, and passing `no-default-features` gives you
+dependencies on only the following crates:
+
+* thiserror (proc macro)
+* bytes (no transitive deps)
+* bs58 (no transitive deps)
+
+We also test effectively every possible bit pattern when encoding and decoding
+varints, a necessary part of did:key resolution.
+
+# Breaking Changes
+
+This crate is v0.0.X, and may introduce breaking changes at any time, with any
+frequency.
+
+[spec]: https://www.w3.org/TR/did-core/

crates/did-simple/src/lib.rs

@@ -20,7 +20,7 @@
 //!
 //! [spec]: https://www.w3.org/TR/did-core/
 
-#![forbid(unsafe_code)]
+#![cfg_attr(not(feature = "allow-unsafe"), forbid(unsafe_code))]
 
 use std::str::FromStr;