# Developer Guide
This guide helps contributors get started with developing corteq-onepassword.
## Prerequisites
- **Rust 1.75+** - Install via [rustup](https://rustup.rs/)
- **Git** - For version control
- **1Password Service Account Token** (optional) - Only required for integration tests
## Getting Started
### 1. Clone the Repository
```bash
git clone https://github.com/trendium-labs/corteq-onepassword.git
cd corteq-onepassword
```
### 2. Install Git Hooks
Run tests once to install pre-commit hooks (managed by husky-rs):
```bash
cargo test
```
This installs hooks that run before each commit:
- `cargo fmt` - Formats code automatically
- `cargo test` - Runs all tests
### 3. Build the Project
```bash
cargo build
```
The build script automatically downloads the 1Password SDK native library for your platform.
## Project Structure
```
corteq-onepassword/
├── src/
│ ├── lib.rs # Crate root, public API exports
│ ├── client.rs # OnePassword client and builder
│ ├── error.rs # Error types
│ ├── ffi/ # FFI bindings to native library
│ │ ├── mod.rs
│ │ ├── loader.rs # Library loading
│ │ └── protocol.rs # JSON-RPC protocol
│ └── secret.rs # SecretReference, SecretMap
├── tests/
│ └── integration/ # Integration tests (require token)
├── examples/ # Usage examples
├── .husky/hooks/ # Git hooks (version-controlled)
└── build.rs # Downloads native SDK library
```
## Running Tests
### Unit Tests (no token required)
```bash
cargo test
```
### Integration Tests (requires token)
Set the environment variable and run:
```bash
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
export TEST_SECRET_REF="op://vault/item/field" # A secret you have access to
cargo test
```
### Doc Tests
```bash
cargo test --doc
```
### All Tests with All Features
```bash
cargo test --all-features
```
## Code Style
### Formatting
Code is formatted with `rustfmt`. The pre-commit hook runs this automatically, but you can run it manually:
```bash
cargo fmt
```
Check formatting without modifying files:
```bash
cargo fmt -- --check
```
### Linting
Run clippy for lints:
```bash
cargo clippy --all-features
```
## Feature Flags
| `blocking` | Enables `connect_blocking()` for synchronous usage |
| `tracing` | Enables tracing spans for observability |
Build with features:
```bash
cargo build --features blocking,tracing
```
## Running Examples
```bash
# Set your token first
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
# Run an example
cargo run --example basic
cargo run --example batch
cargo run --example shared_client
```
## Security Guidelines
When contributing, follow these security practices:
1. **Never log secrets** - Use `expose_secret()` only when passing to consumers
2. **Don't print secret values** - Print length or `[REDACTED]` in examples/tests
3. **Use `SecretString`** - All sensitive data should use secure wrappers
4. **Validate inputs** - Check token/reference formats before use
## Making Changes
### Before Committing
The pre-commit hook handles this automatically, but manually:
```bash
cargo fmt
cargo test
cargo clippy
```
### Bypassing Hooks (emergency only)
```bash
git commit --no-verify -m "emergency fix"
```
### Disabling Hook Installation
To build without installing hooks:
```bash
NO_HUSKY_HOOKS=1 cargo build
```
## Documentation
Generate and view documentation:
```bash
cargo doc --open
```
## Troubleshooting
### Build Fails: Library Download
If the native library fails to download during build:
1. Check your internet connection
2. Verify the build script can access GitHub releases
3. Check `build.rs` for the expected SDK version
### Tests Fail: Missing Token
Integration tests are skipped without `OP_SERVICE_ACCOUNT_TOKEN`. This is expected behavior.
### Hooks Not Running
Re-install hooks by running:
```bash
cargo clean && cargo test
```
## Platform Support
| Linux | x86_64 | ✅ Supported |
| Linux | aarch64 | ✅ Supported |
| macOS | x86_64 | ✅ Supported |
| macOS | aarch64 | ✅ Supported |
| Windows | - | ❌ Not supported |
| Alpine | - | ❌ Not supported (musl) |
## Updating the 1Password SDK
When a new version of the 1Password SDK is released on PyPI, follow these steps to update the bundled native libraries.
### Files to Update
Three files contain version information that must stay in sync:
| `build.rs` | 13 | `SDK_VERSION` | `"0.3.2"` |
| `scripts/download-libs.sh` | 11 | `SDK_VERSION` | `"0.3.2"` |
| `src/ffi/bindings.rs` | 50 | `sdk_version` | `"0030201"` |
### SDK Version Format
The `sdk_version` in `bindings.rs` uses a packed numeric format: `"XXXYYBB"`
- `XXX` = major version (zero-padded to 3 digits)
- `YY` = minor version (zero-padded to 2 digits)
- `BB` = build number (always `01` for releases)
**Examples:**
| 0.3.2 | `"0030201"` |
| 0.4.0 | `"0040001"` |
| 1.0.0 | `"1000001"` |
| 1.2.3 | `"1020301"` |
### Update Process
1. **Check for new versions**
Visit https://pypi.org/project/onepassword-sdk/ to see the latest release.
2. **Update version constants**
Edit the three files listed above with the new version number.
```bash
const SDK_VERSION: &str = "0.4.0";
SDK_VERSION="0.4.0"
sdk_version: "0040001".to_string(),
```
3. **Download new libraries**
Run the download script to fetch libraries for all platforms:
```bash
./scripts/download-libs.sh
```
This downloads from PyPI, verifies SHA256 checksums, and extracts to `src/libs/`.
4. **Verify the update**
```bash
cargo clean
cargo build
cargo test
```
5. **Commit all changes**
Include both source changes and the updated binary libraries:
```bash
git add build.rs scripts/download-libs.sh src/ffi/bindings.rs src/libs/
git commit -m "chore: update 1Password SDK to X.Y.Z"
```
### Troubleshooting
**Download script fails:**
- Ensure `curl`, `jq`, `unzip`, and `sha256sum` are installed
- Check that PyPI is accessible from your network
**Build fails after update:**
- The SDK API may have changed; check 1Password release notes
- Verify the `sdk_version` format matches what the native library expects
**Tests fail:**
- New SDK versions may have different error messages or behavior
- Review test assertions against new SDK behavior
## Questions?
Open an issue on GitHub if you have questions or run into problems.