corteq-onepassword 0.1.5

//! # corteq-onepassword
//!
//! Secure 1Password SDK wrapper for Rust applications.
//!
//! This crate provides a safe, ergonomic interface to 1Password secrets
//! using FFI bindings to the official 1Password SDK Core library.
//!
//! ## Features
//!
//! - **Secure by default** - Secrets are wrapped in [`SecretString`] with automatic
//!   memory zeroization
//! - **Simple API** - Retrieve secrets with a single function call
//! - **Thread-safe** - Client is `Send + Sync` for use in async applications
//! - **Builder pattern** - Flexible configuration with sensible defaults
//!
//! ## Quick Start
//!
//! ```no_run
//! use corteq_onepassword::{OnePassword, ExposeSecret};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create client from OP_SERVICE_ACCOUNT_TOKEN environment variable
//!     let client = OnePassword::from_env()?
//!         .integration("my-app", "1.0.0")
//!         .connect()
//!         .await?;
//!
//!     // Resolve a secret
//!     let api_key = client.secret("op://vault/item/api-key").await?;
//!
//!     // Use the secret (expose only when needed)
//!     println!("API key length: {}", api_key.expose_secret().len());
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Authentication
//!
//! This crate uses 1Password service account tokens for authentication.
//! Personal account tokens are not supported.
//!
//! ### Environment Variable (Recommended)
//!
//! Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable:
//!
//! ```bash
//! export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
//! ```
//!
//! Then use [`OnePassword::from_env()`]:
//!
//! ```no_run
//! use corteq_onepassword::OnePassword;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let client = OnePassword::from_env()?.connect().await?;
//!     Ok(())
//! }
//! ```
//!
//! ### Explicit Token
//!
//! For testing or special deployments, use [`OnePassword::from_token()`]:
//!
//! ```no_run
//! use corteq_onepassword::OnePassword;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let token = std::env::var("MY_TOKEN")?;
//!     let client = OnePassword::from_token(&token)?
//!         .connect()
//!         .await?;
//!     Ok(())
//! }
//! ```
//!
//! ## Secret References
//!
//! Secrets are referenced using the `op://vault/item/field` format:
//!
//! - `op://Production/Database/password` - Simple reference
//! - `op://Production/Database/admin/password` - Section-scoped reference
//!
//! ## Batch Operations
//!
//! Resolve multiple secrets efficiently:
//!
//! ```no_run
//! use corteq_onepassword::{OnePassword, ExposeSecret};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let client = OnePassword::from_env()?.connect().await?;
//!
//!     // Batch resolution (returns Vec)
//!     let secrets = client.secrets(&[
//!         "op://prod/db/host",
//!         "op://prod/db/user",
//!         "op://prod/db/pass",
//!     ]).await?;
//!
//!     // Named resolution (returns SecretMap)
//!     let secrets = client.secrets_named(&[
//!         ("host", "op://prod/db/host"),
//!         ("user", "op://prod/db/user"),
//!         ("pass", "op://prod/db/pass"),
//!     ]).await?;
//!
//!     let host = secrets.get("host").expect("host secret").expose_secret();
//!     Ok(())
//! }
//! ```
//!
//! ## Sharing the Client
//!
//! The client is thread-safe and can be shared via `Arc`:
//!
//! ```no_run
//! use std::sync::Arc;
//! use corteq_onepassword::OnePassword;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let client = Arc::new(OnePassword::from_env()?.connect().await?);
//!
//!     let client1 = Arc::clone(&client);
//!     let client2 = Arc::clone(&client);
//!
//!     tokio::join!(
//!         async move { client1.secret("op://vault/item/field1").await },
//!         async move { client2.secret("op://vault/item/field2").await },
//!     );
//!     Ok(())
//! }
//! ```
//!
//! ## Feature Flags
//!
//! - `blocking` - Enable synchronous API via [`OnePasswordBuilder::connect_blocking()`]
//! - `tracing` - Enable tracing spans for observability
//!
//! ## Security
//!
//! This crate is designed with security as a primary concern:
//!
//! - **Tokens** are wrapped in [`SecretString`] and zeroized on drop
//! - **Secrets** are never logged or included in error messages
//! - **Debug** implementations redact sensitive data
//! - **Native library** is verified via SHA256 checksum at build time
//!
//! ## Platform Support
//!
//! | Platform | Architecture | Status |
//! |----------|--------------|--------|
//! | Linux    | x86_64       | ✅ Supported |
//! | Linux    | aarch64      | ✅ Supported |
//! | macOS    | x86_64       | ✅ Supported |
//! | macOS    | aarch64      | ✅ Supported |
//! | Windows  | -            | ❌ Not supported |
//! | Alpine   | -            | ❌ Not supported (musl) |

#![warn(missing_docs)]
#![warn(clippy::all)]
#![deny(unsafe_op_in_unsafe_fn)]

mod client;
mod error;
mod ffi;
mod secret;

// Public API
pub use client::{OnePassword, OnePasswordBuilder};
pub use error::{Error, Result};
pub use secret::{SecretMap, SecretReference};

// Re-export secrecy types for user convenience
// This allows users to import everything they need from this crate
pub use secrecy::{ExposeSecret, SecretString};