@voxgig/sdkgen 4.29.0 → 4.30.1

package/project/.sdk/tm/rust/feature/secrets/plugins/minivault.rs

@@ -1,43 +1,7 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (rust/plugins/minivault/src/lib.rs)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (rust/plugins/minivault/src/lib.rs)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-//! The mini vault: every secret a project owns, encrypted, in one file.
-//!
-//! A store this library owns outright rather than a client for a server
-//! somebody else runs. It has a master key and restricted keys, and it is
-//! the port's worked example of a definition publishing an API beside its
-//! provider: a chain READS, and writing is a deliberate act with an
-//! interface of its own.
-//!
-//! ```no_run
-//! use crate::feature::secrets::sekreto::{Options, ProviderSpec, Sekreto};
-//! use voxgig_sekreto_minivault::{createvault, minivault, vaultof, VaultOptions};
-//!
-//! let vault = createvault(&VaultOptions {
-//!     file: "app.skmv".to_string(),
-//!     passphrase: "master".to_string(),
-//!     ..Default::default()
-//! })
-//! .unwrap();
-//! vault.set("api.token", "tok01").unwrap();
-//!
-//! let mut secrets = Sekreto::new(Options {
-//!     plugins: vec![minivault()],
-//!     providers: vec![ProviderSpec {
-//!         kind: "minivault".to_string(),
-//!         file: "app.skmv".to_string(),
-//!         passphrase: "master".to_string(),
-//!         ..Default::default()
-//!     }],
-//!     ..Default::default()
-//! })
-//! .unwrap();
-//!
-//! let _ = secrets.get("api.token").unwrap();            // the chain reads
-//! let _ = vaultof(&secrets, "").unwrap().list().unwrap(); // the API writes
-//! ```
-//!
-//! A port of typescript/plugins/minivault.ts, which is canonical.
+#![doc = include_str!("../COMMENT-NOTES.md")]
 
 mod format;
 
@@ -72,20 +36,6 @@ pub const VAULT_EXPORT: &str = "vault";
 
 // --- the lock every handle on one file shares -------------------------
 
-/// Each `Vault` is its own object, so two handles on one path did not
-/// coordinate: both could finish `load` before either saved, and the
-/// second rename then discarded the first one's change while reporting
-/// success. Keyed by the ABSOLUTE path, so two handles spelled
-/// differently still meet.
-///
-/// A guarantee WITHIN one process, which is what DOCS.md promises and what
-/// the go port arranges the same way. Two processes still race, and the
-/// format's answer to that is the exclusive create and the atomic rename:
-/// a reader sees one whole vault or the other, never half of one.
-///
-/// `std::sync`, although a `Vault` is `Rc` and never crosses a thread:
-/// what races is the FILE, and two threads each opening their own handle
-/// on one path is exactly the case this exists for.
 static LOCKS: OnceLock<Mutex<HashMap<PathBuf, Arc<Mutex<()>>>>> = OnceLock::new();
 
 fn lockfor(file: &str) -> Arc<Mutex<()>> {
@@ -99,9 +49,6 @@ fn lockfor(file: &str) -> Arc<Mutex<()>> {
 
 // --- base64 ----------------------------------------------------------
 
-/// Here rather than in the HTTP plugin: a vault opens no socket, and
-/// reaching that crate for two functions would link a TLS stack into a
-/// program whose only store is a local file.
 const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
 fn b64(raw: &[u8]) -> String {
@@ -168,12 +115,6 @@ fn unb64(text: &str, what: &str) -> Answer<Vec<u8>> {
 
 // --- the rings -------------------------------------------------------
 
-/// A MASTER's ring holds the root and no grants; a RESTRICTED key's holds
-/// grants and no root, EVEN WHEN IT WAS GRANTED NOTHING. That asymmetry is
-/// the format rather than a saving: a ring with a root reaches every name
-/// there will ever be, so a grant list beside it would be a second answer
-/// to the same question - and an empty grant map is still a grant map, as
-/// the go port learned by writing twelve bytes fewer than everyone else.
 fn masterring(root: &[u8]) -> String {
     let mut out = Value::map();
     out.set("v", Value::Num(format::FORMAT as f64));
@@ -221,13 +162,6 @@ fn jsontrue(held: &Value, key: &str) -> bool {
 
 // --- the vault -------------------------------------------------------
 
-/// What a key may do. `grants` is empty for a master key, which reads and
-/// writes every name there is.
-///
-/// FIELDS THE CALLER CANNOT WRITE THROUGH, so the defect the review round
-/// found in the canonical - a caller flipping its own `write` bit on the
-/// record it was handed - cannot be written at all. A clone makes a new
-/// value and changes nothing the vault reads.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct VaultKeyInfo {
     pub key: String,
@@ -239,11 +173,9 @@ pub struct VaultKeyInfo {
 /// How a vault file is opened as one key.
 #[derive(Clone, Debug, Default)]
 pub struct VaultOptions {
-    /// The vault file.
     pub file: String,
     /// Which key to open with. Empty means `master`.
     pub key: String,
-    /// What unwraps that key.
     pub passphrase: String,
     /// The PBKDF2 round count used when this handle CREATES a key.
     /// Reading uses what the file records for the key being opened.
@@ -256,14 +188,10 @@ pub struct VaultOptions {
     pub create: bool,
 }
 
-/// What mints a restricted key.
 #[derive(Clone, Debug, Default)]
 pub struct GrantSpec {
-    /// The id the new key answers to.
     pub key: String,
-    /// What will unwrap it.
     pub passphrase: String,
-    /// The names it may read.
     pub names: Vec<String>,
     /// Whether it may overwrite those names. It can never create one.
     pub write: bool,
@@ -292,16 +220,6 @@ struct Held {
     opened: RefCell<Option<Opened>>,
 }
 
-/// A handle on one vault file, opened as ONE key.
-///
-/// Every method answers as that key: `list` shows the names it may read,
-/// `get` answers for those and misses on the rest, and the master-only
-/// ones refuse for any other key. Nothing is read or derived until the
-/// first call that needs the file, so putting a vault in a chain costs no
-/// key derivation until a secret is actually wanted.
-///
-/// Cheap to clone: the handle is shared, not copied, so the definition can
-/// export one and keep one.
 #[derive(Clone)]
 pub struct Vault {
     held: Rc<Held>,
@@ -368,8 +286,6 @@ pub fn createvault(options: &VaultOptions) -> Answer<Vault> {
         ITERATIONS
     };
 
-    // No existence check first: the check and the write would be two
-    // steps, and `putnew` refuses an existing file in ONE.
     putnew(&options.file, &newvault(key, &options.passphrase, iterations)?)?;
 
     openvault(options)
@@ -415,11 +331,6 @@ fn sealkey(
 
 // --- the file on disk -------------------------------------------------
 
-/// Writes a vault file that is not there yet, and REFUSES one that is.
-///
-/// `create_new` is `O_EXCL`, and the mode goes on at creation rather than
-/// after: a `set_permissions` once the bytes are written leaves the file
-/// readable for as long as it takes to write them.
 fn putnew(path: &str, made: &VaultFile) -> Answer<()> {
     let mut open = fs::OpenOptions::new();
     open.write(true).create_new(true);
@@ -458,12 +369,10 @@ fn readmaybe(path: &str) -> Answer<Option<Vec<u8>>> {
 }
 
 impl Vault {
-    /// The file this handle reads.
     pub fn file(&self) -> &str {
         &self.held.file
     }
 
-    /// The key id this handle opens with.
     pub fn key(&self) -> &str {
         &self.held.key
     }
@@ -473,15 +382,6 @@ impl Vault {
         *self.held.opened.borrow_mut() = None;
     }
 
-    /// Replaces the file rather than editing it in place. The rename is
-    /// what makes a concurrent reader see either the old file or the new
-    /// one, so a write interrupted halfway leaves a vault rather than
-    /// wreckage.
-    ///
-    /// THE TEMPORARY IS RANDOM AND EXCLUSIVE. `<vault>.<pid>.tmp` is a
-    /// name anyone can predict, and an ordinary create FOLLOWS a symlink,
-    /// so anyone who could write the vault's directory could point that
-    /// name at another file and have the next save truncate it.
     fn save(&self, made: &VaultFile) -> Answer<()> {
         let suffix = random(8)?;
         let temp = format!("{}.{}.tmp", self.held.file, hex(&suffix));
@@ -503,12 +403,6 @@ impl Vault {
         match readmaybe(&self.held.file)? {
             Some(raw) => Ok(raw),
             None => {
-                // A vault is configured deliberately, with a key. Its
-                // absence is a broken deployment and never "no secrets
-                // here": answering a miss would send the chain on to a
-                // weaker store, which is the failure mode this library
-                // most has to avoid. `create` is the caller saying the
-                // opposite, in writing.
                 if !self.held.create {
                     return fail(&format!("no vault file: {}", self.held.file));
                 }
@@ -636,13 +530,11 @@ impl Vault {
         }
     }
 
-    /// Derive the key and read the file NOW rather than at first use.
     pub fn open(&self) -> Answer<VaultKeyInfo> {
         self.load()?;
         Ok(self.info())
     }
 
-    /// The names this key can read, sorted.
     pub fn list(&self) -> Answer<Vec<String>> {
         let file = self.load()?;
         let info = self.info();
@@ -756,7 +648,6 @@ impl Vault {
         self.save(&file)
     }
 
-    /// Drop a name. Master only.
     pub fn remove(&self, name: &str) -> Answer<()> {
         checkname(name)?;
 
@@ -818,7 +709,6 @@ impl Vault {
         Ok(out)
     }
 
-    /// Mint a restricted key. Master only.
     pub fn grant(&self, spec: &GrantSpec) -> Answer<()> {
         let one = lockfor(&self.held.file);
         let _guard = one.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
@@ -887,12 +777,6 @@ impl Vault {
         self.save(&file)
     }
 
-    /// Take a new root key, re-encrypt every value under it, and DROP
-    /// EVERY OTHER KEY. Master only.
-    ///
-    /// The other keys go because they must: their rings are sealed under
-    /// passphrases this process does not have, so there is no way to hand
-    /// them keys they can unwrap. Re-grant afterwards.
     pub fn rotate(&self) -> Answer<()> {
         let one = lockfor(&self.held.file);
         let _guard = one.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
@@ -905,8 +789,6 @@ impl Vault {
             None => self.held.iterations,
         };
 
-        // Read everything out under the old root before anything changes:
-        // once the root is replaced the old derived keys are unreachable.
         let oldnamekey = mac(&oldroot, LABEL_NAMES);
         let mut held = Vec::new();
 
@@ -952,8 +834,6 @@ impl Vault {
             entries,
         })?;
 
-        // The ring this handle holds is the OLD one, so the next call must
-        // derive again rather than answer from it.
         self.close();
 
         Ok(())
@@ -981,18 +861,6 @@ impl Provider for MiniVaultProvider {
     }
 }
 
-/// The `minivault` provider kind, as a voxgig/plugin definition.
-///
-/// Written out rather than built by `providerplugin`, because this
-/// definition publishes TWO exports: `provider`, the read half every kind
-/// publishes, and `vault`, the programmatic API. voxgig/plugin's exports
-/// are how a definition offers an application more than the host's own
-/// vocabulary, and a store that can only be read is half a vault.
-///
-/// Both cross as `Value::Opaque` - plugin's escape hatch for "a client the
-/// library never inspects" - which is what `providerplugin` already does
-/// for the provider. No slot table: unlike the ports whose value model
-/// carries only numbers and strings, rust can put the handle itself in.
 pub fn minivault() -> Definition {
     let mut definition = Definition::named("minivault");
 
@@ -1058,10 +926,6 @@ pub fn vaultof(secrets: &Sekreto, store: &str) -> Answer<Vault> {
         return held("minivault", "no minivault store in this chain");
     }
 
-    // A NAMED STORE MUST EXIST, and the alias must not stand in for it.
-    // `exports` falls back to the alias when the exact ref misses, so
-    // asking for `minivault` in a chain whose only vault is named `app`
-    // used to hand back the `app` vault - and then write to it.
     let missing = format!("no minivault store named {} in this chain", store);
     let eref = if "minivault" == store {
         "minivault".to_string()

package/project/.sdk/tm/rust/feature/secrets/plugins/onepassword.rs

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (rust/plugins/onepassword/src/lib.rs)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (rust/plugins/onepassword/src/lib.rs)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! The 1Password Connect provider, as a voxgig/plugin definition.
 
@@ -11,12 +11,6 @@ use crate::feature::secrets::sekreto::{checkaddr, checkname, providerplugin, Ans
 use super::httpjson::json::Json;
 use super::httpjson::{fetchjson, http, trimslash};
 
-/// 1Password, through a Connect server.
-///
-/// The item titled `api.token` (titles keep their dots), in the named
-/// vault. The value is the field with purpose PASSWORD, or the field
-/// labelled `value`. A vault that cannot be found is an error - config
-/// names it, so its absence is a broken store, not a missing secret.
 #[derive(Default)]
 pub struct OnePasswordProvider {
     pub addr: String,

package/project/.sdk/tm/rust/feature/secrets/plugins/secretspec.rs

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (rust/plugins/secretspec/src/lib.rs)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (rust/plugins/secretspec/src/lib.rs)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! The SecretSpec provider, as a voxgig/plugin definition.
 //!
@@ -13,30 +13,6 @@ use std::rc::Rc;
 use crate::feature::secrets::plugin::catalog::Definition;
 use crate::feature::secrets::sekreto::{envkey, providerplugin, Answer, Provider, SekretoError};
 
-/// SecretSpec (https://secretspec.dev).
-///
-/// SecretSpec is a declaration - a `secretspec.toml` naming the secrets a
-/// project needs - plus a chain of its own backends to satisfy them from.
-/// That makes it the same shape as sekreto one level down, and the reason
-/// to support it is the same reason sekreto exists: a project that has
-/// already declared its secrets there should not have to declare them
-/// again here.
-///
-/// Read through its CLI, as boru is, because that is the interface it
-/// offers a program in another language: `secretspec get API_TOKEN`
-/// prints the value on stdout and nothing else. A sekreto name maps to a
-/// SecretSpec key exactly as it maps to an environment variable -
-/// `api.token` is `API_TOKEN` - which is the convention SecretSpec's own
-/// examples use.
-///
-/// `backend` selects one of SecretSpec's backends (`--provider`, e.g.
-/// `keyring` or `dotenv://.env`) and is called `backend` here only
-/// because `provider` already means something else in this library.
-///
-/// A reason is required, not optional: SecretSpec records every read in
-/// an audit log and refuses to read at all without one. sekreto sends
-/// `sekreto` unless told otherwise, so the audit trail says which tool
-/// asked.
 pub struct SecretSpecProvider {
     pub command: String,
     pub file: String,
@@ -114,19 +90,6 @@ impl Provider for SecretSpecProvider {
     }
 }
 
-/// Does this SecretSpec failure mean "no such secret" rather than "I
-/// could not answer"?
-///
-/// SecretSpec says `Secret 'API_TOKEN' not found` for both a name it does
-/// not declare and one declared with no value, and both are misses: this
-/// store does not hold it, so the chain carries on.
-///
-/// MATCHED ON THE WHOLE PHRASE, NOT ON "not found". SecretSpec also says
-/// `Provider backend 'keyring' not found`, which is a store that could
-/// not answer at all - and reading that as a miss is the worst failure
-/// this library has, because the chain then falls through to a weaker
-/// store without saying so. The key is required to appear, so the two
-/// cannot be confused.
 fn secretspecmiss(why: &str, key: &str) -> bool {
     why.contains(&format!("Secret '{}' not found", key))
 }

package/project/.sdk/tm/rust/feature/secrets/sekreto/addr.rs

@@ -1,24 +1,9 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (rust/src/addr.rs)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (rust/src/addr.rs)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-//! The plaintext-address guard, in the core because it is pure - a
-//! handful of string steps, no socket - and because it is on the spec:
-//! every port answers the same for every address in spec/def/store.aon.
-//! The plugins that dial an address call `checkaddr` before they do.
-//!
-//! A port of typescript/src/provider/addr.ts.
 
 use super::sekreto::{Answer, SekretoError};
 
-/// An address with any userinfo replaced by `[redacted]`, for messages.
-///
-/// Every refusal below names the address it refused, and one of them fires
-/// precisely because the address carries a credential - so printing it
-/// verbatim wrote the password to stderr and into the logs. It cannot be
-/// cleaned up afterwards either: that password was never resolved as a
-/// secret, so `redact` has never seen it and never will. The host is what a
-/// reader needs to identify which chain entry is at fault; the userinfo is
-/// not.
 pub fn safeaddr(addr: &str) -> String {
     let mark = match addr.find("://") {
         Some(at) => at,
@@ -38,36 +23,6 @@ pub fn safeaddr(addr: &str) -> String {
 }
 
 
-/// Refuse to send a secret-bearing credential in the clear.
-///
-/// A vault API is HTTPS in any real deployment; plaintext is a dev-mode
-/// convenience. Sending a token over http to anything but the local
-/// machine puts both the token and the secret it fetches on the wire for
-/// anyone on the path, so sekreto will not do it. Loopback stays allowed:
-/// that is `vault server -dev`, `boru vault serve`, and this repo's own
-/// test harness.
-///
-/// https is dialled by whichever plugin needs it, with the server
-/// certificate and the host name both verified and `SEKRETO_CA_BUNDLE`
-/// adding trust roots for an internal CA. See
-/// `plugins/httpjson/src/http.rs` - the transport is a plugin's business,
-/// while this check is pure string work and therefore the core's.
-///
-/// The address is read by hand, in the same handful of steps in every port,
-/// rather than by each platform's URL parser. That is deliberate. Twelve
-/// parsers disagree about malformed input - where userinfo ends, whether
-/// `0177.0.0.1` is loopback, what an unclosed bracket means - and a check
-/// that answers differently in different ports is not a check. (Rust has no
-/// URL parser in std in any case, and a crate for one is exactly what this
-/// library does not take.)
-///
-/// The rule this parse obeys, and the reason it can be trusted: it is never
-/// more permissive than the HTTP client that will dial the address. It ends
-/// the authority at `/`, `?` or `#` only, so a client that also breaks on
-/// `\` (WHATWG does) can only ever see a SHORTER host than this does. It
-/// refuses userinfo outright rather than locating its end. It compares the
-/// host literally, so a numeric form no parser here agrees on is refused
-/// rather than guessed at.
 pub fn checkaddr(addr: &str) -> Answer<()> {
     let scheme = if addr.starts_with("https://") {
         "https://"
@@ -86,13 +41,6 @@ pub fn checkaddr(addr: &str) -> Answer<()> {
         None => rest,
     };
 
-    // Userinfo is refused outright rather than parsed around, and on https
-    // as well as http. No store this library speaks authenticates by
-    // userinfo - they take a token or a signature - so an address carrying
-    // one is a mistake at best. At worst it is the attack this whole
-    // function exists to stop: `http://localhost:8200@evil.example.com/` is
-    // a request to evil.example.com that reads, to anything that splits the
-    // authority on ':', as loopback.
     if authority.contains('@') {
         return Err(SekretoError::new(format!(
             "sekreto: refusing an address with embedded credentials: {}",

package/project/.sdk/tm/rust/feature/secrets/sekreto/mod.rs

@@ -1,35 +1,6 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (rust/src/lib.rs)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (rust/src/lib.rs)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-//! sekreto: one interface for secrets, wherever they live.
-//!
-//! An app asks a `Sekreto` for `api.token` and never learns whether the
-//! value came from the environment, a `.env` file, HashiCorp Vault, AWS,
-//! GCP, Azure or a boru vault. Swapping the chain is a config change, not
-//! a code change.
-//!
-//! THIS IS THE CORE, AND ITS ONLY DEPENDENCY IS `voxgig_plugin`. Four
-//! provider kinds are built in - `env`, `memory`, `dotenv` and `file` -
-//! and what makes them built in is that they read at most a local file. No
-//! TLS, no socket, no subprocess, no hash function: the manifest here
-//! names no TLS crate at all, so a consumer whose chain is `[dotenv, env]`
-//! compiles none of one.
-//!
-//! Every kind that opens a socket, signs a request or spawns a process is
-//! a voxgig/plugin definition in its own crate under `plugins/`, and a
-//! `Sekreto` can build exactly the ones its constructor was handed:
-//!
-//! ```ignore
-//! use voxgig_sekreto::{Options, ProviderSpec, Sekreto};
-//!
-//! let secrets = Sekreto::new(Options {
-//!     plugins: vec![voxgig_sekreto_hashicorp::plugin()],
-//!     providers: vec![ProviderSpec::of("hashicorp")],
-//!     ..Default::default()
-//! })?;
-//! ```
-//!
-//! See `docs/design/plugin-providers.md`.
 
 pub mod addr;
 pub mod providers;