authsome 0.3.2__tar.gz → 0.4.1__tar.gz

authsome-0.4.1/.github/release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.1"
+}

{authsome-0.3.2 → authsome-0.4.1}/AGENTS.md

@@ -56,6 +56,8 @@ These rules govern all changes to this codebase — apply them without exception
 
 **Deep modules over shallow ones.** Prefer a small surface area with rich internals over many thin wrappers. More files is not more modular.
 
+**Composition over inheritance.** Prefer small collaborators wired together through explicit dependencies over inheritance hierarchies. Use inheritance only when there is a real subtype relationship and composition would make the design less clear.
+
 **Single responsibility and separation of concerns.** Auth authenticates. Vault stores credentials. CLI presents output. A flow must not write to storage; storage must not know about OAuth. If a function is hard to name, it's doing too many things.
 
 **No premature optimization.** Don't add caching, batching, or concurrency before a measured performance problem exists. Simple and slow is fixable; complex and wrong is not.
@@ -102,15 +104,24 @@ These rules govern all changes to this codebase — apply them without exception
 
 ## Architecture
 
-**Identity (`src/authsome/identity/`)** manages local Ed25519 key pairs and `did:key` DIDs. `ensure_local_identity(home, active_handle)` returns the identity named in `GlobalConfig.active_identity`, or creates a new one if none exists. Key material lives at `~/.authsome/identities/<handle>.key` (mode `0600`); metadata at `~/.authsome/identities/<handle>.json`. Identity = Profile: the handle is both the cryptographic identity name and the credential namespace key.
+**Identity (`src/authsome/identity/local.py`)** manages local Ed25519 key pairs and `did:key` DIDs. Key material lives at `~/.authsome/identities/<handle>.key` (mode `0600`); metadata at `~/.authsome/identities/<handle>.json`. An Identity is a cryptographic agent — it is not a credential namespace. Credential namespacing is owned by a Vault (see below).
 
-**PoP Auth (`src/authsome/identity/proof.py`)** implements Proof-of-Possession JWT creation and validation. Every protected daemon request carries `Authorization: PoP <jwt>` signed with the local Ed25519 key. The JWT is bound to the specific HTTP method, path, and body SHA-256. The daemon validates the signature, checks the `jti` replay cache, and confirms `sub` (handle) → `iss` (DID) via the Identity Registry.
+**Principal & Vault domain models (`src/authsome/identity/principal.py`)** define the two concepts that own credentials. A **Principal** is a non-cryptographic logical partition (human or team) identified by an opaque `PrincipalId`. A **Vault** is a named credential store owned by exactly one Principal and identified by an opaque `VaultId`. Credentials are scoped to a vault: `vault:<vault_id>:...`. An Identity claims membership in a Principal via an `IdentityClaimRecord`; the claim must be accepted before vault access is granted.
 
-**Identity Registry (`src/authsome/identity/registry.py`)** is the daemon-owned authoritative handle→DID mapping, persisted at `~/.authsome/server/identity_registry.json`.
+**Five server-owned registries** persist in `~/.authsome/server/` and are implemented in `src/authsome/server/registries.py`:
+| Registry | File | Authoritative for |
+|----------|------|-------------------|
+| `IdentityRegistry` | `identity_registry.json` | Handle → DID mapping (PoP JWT validation) |
+| `PrincipalRegistry` | `principal_registry.json` | PrincipalId → email |
+| `VaultRegistry` | `vault_registry.json` | VaultId → VaultHandle |
+| `IdentityClaimRegistry` | `identity_claim_registry.json` | Identity → Principal claim + ClaimStatus |
+| `PrincipalVaultBindingRegistry` | `principal_vault_binding_registry.json` | Principal → default Vault binding |
+
+**PoP Auth (`src/authsome/identity/proof.py`)** implements Proof-of-Possession JWT creation and validation. Every protected daemon request carries `Authorization: PoP <jwt>` signed with the local Ed25519 key. The JWT is bound to the specific HTTP method, path, and body SHA-256. The daemon validates the signature, checks the `jti` replay cache, and confirms `sub` (handle) → `iss` (DID) via the Identity Registry.
 
-**AuthService (`src/authsome/auth/service.py`)** is the authentication and credential lifecycle layer. It owns OAuth flows, token refresh, login/logout/revoke. Constructed with `vault` and `identity` (the handle); all store keys are namespaced as `profile:<handle>:...`.
+**AuthService (`src/authsome/server/credential_service.py`)** is the authentication and credential lifecycle coordinator. It owns OAuth flows, token refresh, login/logout/revoke. Lives in `server/` because it coordinates `auth/` flows with `vault/` storage and `audit/` logging. Constructed with `(vault, identity, principal_id, vault_id)`; all credential store keys are namespaced as `vault:<vault_id>:...`. The caller (server dependency injection) resolves `vault_id` from the `PrincipalVaultBindingRegistry` before constructing `AuthService`.
 
-**Flows (`src/authsome/auth/flows/`)** implement the `AuthFlow.authenticate()` interface. Each flow returns a `ConnectionRecord`.
+**Flows (`src/authsome/auth/flows/`)** implement the `AuthFlow.authenticate()` interface. Each flow returns a `ConnectionRecord`. The `auth/` module is a leaf — it imports nothing from `vault/`, `audit/`, or `server/`.
 
 | Flow | Class | Notes |
 |------|-------|-------|
@@ -119,19 +130,19 @@ These rules govern all changes to this codebase — apply them without exception
 | `dcr_pkce` | `DcrPkceFlow` | Dynamic Client Registration then PKCE |
 | `api_key` | `ApiKeyFlow` | Prompts via secure browser bridge |
 
-**Provider Registry (`src/authsome/auth/service.py`)** resolves providers in this order: local `~/.authsome/providers/<name>.json` overrides bundled JSON in `src/authsome/bundled_providers/`. Bundled providers (GitHub, Google, Okta, Linear, OpenAI) are loaded via `importlib.resources`.
+**Provider Registry** resolves providers in this order: custom providers stored in the vault under the `providers` collection override bundled JSON in `src/authsome/auth/bundled_providers/`. Bundled providers (GitHub, Google, Okta, Linear, OpenAI) are loaded via `importlib.resources`.
 
 **Vault (`src/authsome/vault/`)** is the encrypted KV store. The master key lives at `~/.authsome/server/master.key` (mode `0600`) or in the OS keyring. All credential blobs are encrypted at rest; the AuthService reads and writes plaintext through the Vault without knowing encryption details.
 
 **Storage** uses a DiskStore-backed KV at `~/.authsome/server/kv_store/`. Store keys follow the pattern:
 ```
-profile:<handle>:<provider>:connection:<connection_name>
-profile:<handle>:<provider>:metadata
-profile:<handle>:<provider>:state
+vault:<vault_id>:<provider>:connection:<connection_name>
+vault:<vault_id>:<provider>:metadata
+vault:<vault_id>:<provider>:state
 server:<provider>:client
 ```
 
-**Config** (`GlobalConfig`) is stored in the KV store under `config/global`. Key field: `active_identity` (the handle of the current identity). Encryption mode is set via `config.encryption.mode` (`local_key` or `keyring`).
+**Config** (`GlobalConfig`) is stored in the KV store under `config/global`. Key fields: `active_identity` (the handle of the current identity), `vault_id` (the active vault resolved at `authsome init`). Encryption mode is set via `config.encryption.mode` (`local_key` or `keyring`).
 
 **CLI (`src/authsome/cli/main.py`)** is Click-based. All commands support `--json` for machine-readable output. `authsome init` creates the local identity, registers it with the daemon, and writes `active_identity` to config.
 

{authsome-0.3.2 → authsome-0.4.1}/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [0.4.1](https://github.com/agentrhq/authsome/compare/authsome-v0.4.0...authsome-v0.4.1) (2026-05-25)
+
+
+### Features
+
+* enable provider configuration management for hosted admins with required credential inputs and scope persistence ([e26d584](https://github.com/agentrhq/authsome/commit/e26d5841f34467af77e67903eaf6ee8b97d59313))
+* enable provider configuration management for hosted admins with… ([30b2f8a](https://github.com/agentrhq/authsome/commit/30b2f8a3814a04b710fd37206889e3e1a71fd43f))
+
+
+### Bug Fixes
+
+* rename AUTHSOME_ADMIN_PRINCIPLES environment variable to fix typo ([10f17f4](https://github.com/agentrhq/authsome/commit/10f17f48e35f118e76d7cb5c797a498408c51db7))
+
+## [0.4.0](https://github.com/agentrhq/authsome/compare/authsome-v0.3.2...authsome-v0.4.0) (2026-05-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* Create version 0.4 which adds support for principal, identity, vault key loading precedence and many more fixes
+
+### Features
+
+* ClaimStatus lifecycle, vault_id gating, ADR 0003 alignment ([d8553ba](https://github.com/agentrhq/authsome/commit/d8553baabbfba595580fd0d6d0c0a90ba282e911))
+* Cleanup server routes ([225d7fd](https://github.com/agentrhq/authsome/commit/225d7fdcfba184c60bffdb70ba28e9576109b25c))
+* disable analytics automatically when running under pytest and add verification tests ([d1abc48](https://github.com/agentrhq/authsome/commit/d1abc48f11255419f5d58cc13d5280fa221a3b21))
+* implement HostedAccountService for email/password authentication and JWT session management ([c161ab9](https://github.com/agentrhq/authsome/commit/c161ab96d0d78ad02ce98b5ad4c0269ba3fd0530))
+* implement master key rotation via rekey command and API endpoint ([f78f872](https://github.com/agentrhq/authsome/commit/f78f872624b1da899d76dd0c1a04ee81fafca772))
+* implement opt-out telemetry support via environment variables and add associated documentation and tests ([9d7c88f](https://github.com/agentrhq/authsome/commit/9d7c88fb0a1a777b535f5e06b11a60a00eda263c))
+* implement opt-out telemetry support via environment variables and add associated tests ([1c1554c](https://github.com/agentrhq/authsome/commit/1c1554c9cf3fbf093d107d7c6a3fd15103572096))
+* implement vault rekey functionality with encryption source validation and add corresponding API and unit tests. ([e7f4187](https://github.com/agentrhq/authsome/commit/e7f418707aacde9b7705a5f79c8a84b28878715d))
+* login flow ([e0ea86d](https://github.com/agentrhq/authsome/commit/e0ea86dc99de0d1d616b3c609e48c2ba6a61d516))
+* scope connections to vault, add claim flow and principal concept ([d3f2006](https://github.com/agentrhq/authsome/commit/d3f2006d67c572fef7dd05b539c7e2c83de8ddaa))
+
+
+### Bug Fixes
+
+* correct import path and test fixture for ready endpoint ([3951af8](https://github.com/agentrhq/authsome/commit/3951af82390994ad6d5acbdc06e59d91c8ccd962))
+* deduplicate error class name in daemon responses and stop orphaned daemon ([76e2320](https://github.com/agentrhq/authsome/commit/76e2320c96e1e06eaa9d6822e98f33f8e027db1c))
+* improve whoami robustness by handling connection failures gracefully and isolating keyring tests ([83709f4](https://github.com/agentrhq/authsome/commit/83709f4e373a3057b49af0e3b9e40b2166883d43))
+
+
+### Documentation
+
+* add dedicated Hermes Agent integration page, drop stale Hermes refs ([b7297dd](https://github.com/agentrhq/authsome/commit/b7297dd5e658bf20baf0251a21460f6c6b5b7048))
+* add dedicated Hermes Agent integration page, drop stale Hermes refs ([e12082f](https://github.com/agentrhq/authsome/commit/e12082f0786504e5049550375ea97831657125e7))
+* add hosted UI auth and identity claim design spec ([e552805](https://github.com/agentrhq/authsome/commit/e5528053c146e6a8652cd8fe44409d286d8a2d6a))
+* fix CONTEXT.md dependency graph and direction ([17fff13](https://github.com/agentrhq/authsome/commit/17fff13aa893d049b65e16e1922f80130f388da2))
+* make auth/ a leaf module, move AuthService to server/ ([d92611c](https://github.com/agentrhq/authsome/commit/d92611ccd4fc987595034b1e6b1ee49e1049af16))
+* resolve merge conflicts in UBIQUITOUS_LANGUAGE.md ([48229eb](https://github.com/agentrhq/authsome/commit/48229eb8b456cbdaeeb7a7a1a2e0bf02800fb21e))
+* rewrite CONTEXT.md with module boundaries, create TODOS.md ([c7a1629](https://github.com/agentrhq/authsome/commit/c7a1629166324729a9e14868ebaa9ad082165053))
+* rewrite login and proxy sections in manual-testing guide ([3719d13](https://github.com/agentrhq/authsome/commit/3719d13a960430d2839df85b458d55ec83071006))
+* update architecture language, retire Profile, add Principal/Vault/Claim terms ([8dc663e](https://github.com/agentrhq/authsome/commit/8dc663e21e505a5327a7168ea47a245ed94b8db7))
+
+
+### Code Refactoring
+
+* Create version 0.4 which adds support for principal, identity, vault key loading precedence and many more fixes ([bb5a2a6](https://github.com/agentrhq/authsome/commit/bb5a2a615291a89bfd5c1a581692b2d86a82dca4))
+
 ## [0.3.2](https://github.com/agentrhq/authsome/compare/authsome-v0.3.1...authsome-v0.3.2) (2026-05-20)
 
 

authsome-0.4.1/CONTEXT.md

@@ -0,0 +1,251 @@
+# authsome
+
+authsome is the local auth layer for AI agents — it answers which agent, acting on behalf of whom, accessed what credential, and was that allowed.
+
+## Module Responsibilities
+
+Each module has one job. `identity/`, `auth/`, `vault/`, and `audit/` are **leaf modules** — they import nothing from this codebase and can be used and tested in isolation. `server/` is the only composition root.
+
+```
+identity/  ←─┐
+auth/      ←─┤
+vault/     ←─┤  server/  ←── cli/   (via HTTP, not Python import)
+audit/     ←─┘            ←── proxy/ (via HTTP, not Python import)
+```
+
+---
+
+### `identity/` — Cryptographic identity primitives
+
+Think of this as the OpenID Connect layer. Handles key material, DIDs, and proof-of-possession tokens.
+
+**Owns:**
+- Ed25519 key pair generation and serialization (`local.py`)
+- `did:key` DID derivation from public keys (`local.py`)
+- `IdentityMetadata` model — client-side cached state for a local identity
+- `IdentityRegistration` model — the server's record of a registered handle/DID binding
+- PoP JWT creation and validation (`proof.py`)
+- `ClaimStatus`, `PrincipalRecord`, `VaultRecord`, `IdentityClaimRecord`, `PrincipalVaultBindingRecord` — shared domain models
+
+**Does not own:**
+- Filesystem-backed registries (those are server state, not identity primitives)
+- Client config management (that is `cli/` territory)
+- Principal/vault lifecycle decisions (that is `server/` territory)
+
+**Imports nothing from this codebase.** Used by: `server/`, `cli/`
+
+---
+
+### `auth/` — OAuth and API key flow implementations
+
+Think of this as the OAuth 2.0 protocol library. Each flow takes provider config and credentials in, returns tokens out. No storage, no audit, no identity imports.
+
+**Owns:**
+- OAuth 2.0 flows: PKCE, Device Code, DCR+PKCE (`flows/`)
+- API key collection flow (`flows/api_key.py`)
+- Flow base class and token refresh logic
+- Provider models: `ProviderDefinition`, `OAuthConfig`, `ApiKeyConfig`, bundled provider JSON
+- Credential models: `ConnectionRecord`, `ProviderClientRecord`, `ProviderMetadataRecord`, `ProviderStateRecord`
+- `AuthSession` — transient flow session state
+
+**Does not own:**
+- Credential persistence (that is `vault/` + `server/` territory)
+- Audit logging (that is `audit/` + `server/` territory)
+- Proxy route catalog building
+- Server registry reads
+
+**Imports nothing from this codebase.** Used by: `server/`
+
+---
+
+### `server/` — CredentialService and application orchestration
+
+`server/` owns `CredentialService` (currently called `AuthService`) — the stateful coordinator that wires `auth/` flows with `vault/` storage and `audit/` logging. It is the only place where flows, storage, and audit are combined.
+
+`CredentialService` is constructed per-request by the server with `(vault, identity, principal_id, vault_id)` and calls `auth/` flows to execute protocols, `vault/` to persist results, and `audit/` to record events.
+
+> Current state: `AuthService` lives in `auth/` and imports `vault/` and `audit/` directly. Moving it to `server/` (TODOS phase E) makes `auth/` a true leaf.
+
+---
+
+### `vault/` — Encrypted credential storage
+
+Think of this as the secrets layer. Encrypts and decrypts credential blobs transparently.
+
+**Owns:**
+- `Vault` — AES-256-GCM encrypted KV wrapper over `AsyncKeyValue`
+- `VaultCrypto` — key management (local file, OS keyring)
+- Encrypted get/put/delete/list over named collections
+
+**Does not own:**
+- Server filesystem layout or path resolution
+- Registry lookups
+- Business logic about which vault belongs to which principal
+
+**Imports nothing from this codebase.** Imported by: `auth/`, `server/`
+
+---
+
+### `audit/` — Structured event recording
+
+Think of this as the append-only ledger. Records who did what and when.
+
+**Owns:**
+- `AuditEvent` model
+- `log()` / `alog()` — append to a structured JSON-lines log file
+- `setup()` / `clear()` — log file lifecycle (called by server at startup/shutdown)
+
+**Does not own:**
+- Business logic
+- Any storage beyond the append-only log file
+
+**Imports nothing from this codebase.** Imported by: `auth/`, `server/`
+
+---
+
+### `server/` — Application orchestration and server-owned state
+
+Think of this as the daemon process. Wires identity + auth + vault + audit together. Owns all server-side persistence.
+
+**Owns:**
+- `server/registries.py` — all filesystem-backed registry implementations:
+  - `IdentityRegistry` (handle → DID)
+  - `PrincipalRegistry` (principal_id → email)
+  - `VaultRegistry` (vault_id → handle)
+  - `IdentityClaimRegistry` (identity → principal + ClaimStatus)
+  - `PrincipalVaultBindingRegistry` (principal → default vault)
+- `server/ownership.py` — `OwnershipResolver` (local and hosted variants), `ResolvedOwnership`
+- `server/identity_bootstrap.py` — deployment-specific identity registration behavior
+- `server/dependencies.py` — infrastructure wiring (paths, store, vault, config)
+- `server/app.py` — FastAPI application factory and lifespan
+- `server/routes/` — HTTP API surface
+- `server/schemas.py` — API response schemas
+
+**All filesystem interaction for server-owned state lives here.** No other module writes to server-owned paths.
+
+**Imported by:** nothing (top of the import graph)
+
+---
+
+### `proxy/` — Credential injection proxy
+
+A mitmproxy-based HTTPS proxy. Intercepts outgoing agent requests and injects auth headers.
+
+**Owns:**
+- `proxy/server.py` — mitmproxy addon that intercepts requests
+- `proxy/runner.py` — background thread lifecycle
+- `proxy/router.py` — `RouteMatch` / `RouteResolution` types
+- `proxy/certs.py` — CA certificate management
+
+**Does not own:**
+- Credential loading (asks the server)
+- Route catalog construction (asks the server)
+- Provider definitions
+
+**Imported by:** `cli/`
+
+---
+
+### `cli/` — Client to the daemon
+
+Click-based CLI and HTTP client. Everything here is a client to the server HTTP API.
+
+**Owns:**
+- `cli/main.py` — Click command tree
+- `cli/client.py` — `RuntimeClient` (async HTTP client for daemon requests, attaches PoP JWT)
+- `cli/client_config.py` — client-owned config (`active_identity`, `vault_id`, proxy settings)
+- `cli/context.py` — `CliRuntime` wiring container
+- `cli/daemon_control.py` — start/stop the daemon process
+
+**Does not own:**
+- Server registry operations
+- Direct vault or store access
+- Identity key generation (delegates to `identity/`, result stored by CLI via `identity/local.py`)
+
+**Imported by:** nothing (entry point)
+
+---
+
+## Domain Language
+
+### Identity & Authentication
+
+**Identity**: The cryptographic agent — Ed25519 key pair, `did:key` DID, and human-readable Handle. Created locally; registered with the daemon. Is not a credential namespace.
+
+**Handle**: Human-readable name for an Identity (e.g., `brisk-boldly-clearly-1234`). Used as `sub` in PoP JWTs.
+
+**DID**: `did:key` Ed25519 identifier derived from the Identity's public key. Used as `iss` in PoP JWTs.
+
+**PoP JWT**: Short-lived (60 s) Proof-of-Possession token signed with the Identity's Ed25519 private key. Bound to `htm`, `htu`, `body_sha256`. Sent as `Authorization: PoP <token>`.
+
+**Principal**: Non-cryptographic logical partition (human or team) that owns Vaults. Identified by an opaque **PrincipalId** (e.g., `principal_abc123def456`). Has no cryptographic key.
+_Avoid_: User, account, PrincipalHandle, profile
+
+**PrincipalId**: Opaque stable identifier for a Principal. Never the email or handle — those can change; the PrincipalId cannot.
+_Avoid_: principal_handle, principal_name, username
+
+**Vault**: Named credential store owned by exactly one Principal. Identified by an opaque **VaultId** (e.g., `vault_a1b2c3d4e5f6`). All credential store keys are prefixed `vault:<vault_id>:...`.
+_Avoid_: credential store, token store, secret store, profile store
+
+**VaultId**: Opaque stable identifier for a Vault. Used as the storage key segment. Stable across naming changes.
+_Avoid_: vault_name, vault_handle
+
+**VaultHandle**: Human-readable name for a Vault (e.g., `default`). Used in UIs and CLI; the VaultId is authoritative in storage.
+
+**IdentityClaimRecord**: Binding from an Identity (Handle) to a Principal (PrincipalId) with a `ClaimStatus`. Created during `authsome init --email`. Vault access is gated until the claim is accepted.
+_Avoid_: Claim, IdentityRegistration (as claim), join request
+
+**ClaimStatus**: Lifecycle state: `pending` → `accepted` | `rejected`.
+
+---
+
+## Initialization & Claim Flow
+
+**Local mode**: `authsome init` creates an Identity, auto-accepts its claim under the implicit local Principal, and creates the default Vault. No email required.
+
+**Hosted mode**: `authsome init --email manoj@example.com` creates an Identity, creates or finds the Principal by email, and registers an `IdentityClaimRecord` with `claim_status = pending`. A human reviews the claim in the UI and accepts or rejects it. All vault operations return `403` until the claim is accepted.
+
+---
+
+## Key Relationships
+
+- An **Identity** is a cryptographic agent. It does not own credentials directly.
+- An **Identity** claims a **Principal** via an **IdentityClaimRecord**. Claim must be `accepted` for vault access.
+- A **Principal** owns one or more **Vaults** via **PrincipalVaultBindingRecords**. The server resolves the default Vault before constructing `AuthService`.
+- A **Vault** contains zero or more **Connections**, each scoped to one **Provider**.
+- Multiple Identities may share one Vault by claiming the same Principal.
+- A **ConnectionRecord** belongs to exactly one Vault. `vault:<vault_id>:...` is the key prefix.
+- **ClientCredentials** are server-scoped — one `ProviderClientRecord` per Provider, shared across all Vaults.
+
+---
+
+## AuthService Contract
+
+`AuthService` is a per-request credential lifecycle object constructed by the server:
+
+```python
+AuthService(vault=vault, identity=handle, principal_id=pid, vault_id=vid, deployment_mode=mode)
+```
+
+- `identity` — agent Handle, used for audit logging only
+- `principal_id` — resolved by `OwnershipResolver` from the PoP JWT subject
+- `vault_id` — resolved from `PrincipalVaultBindingRegistry` by the server before constructing AuthService
+- `vault` — the encrypted KV store; AuthService reads/writes only through this
+
+AuthService does not query registries, does not know about server filesystem paths, and does not build proxy route catalogs.
+
+---
+
+## Audit Contract
+
+Every `AuditEvent` carries `identity` (the agent Handle) and `principal_id` (the PrincipalId). Both are required — every auditable action has an acting agent and an owning principal.
+
+---
+
+## Flagged Ambiguities
+
+- **"PrincipalHandle"** — retired. The Principal is now identified by an opaque `PrincipalId`. Do not use PrincipalHandle in new code.
+- **"VaultHandle"** — the human-readable display name. Do not use VaultHandle as a storage key; use VaultId.
+- **"Claim"** — use `IdentityClaimRecord` for the binding object; use "claim" (lowercase) only as a verb.
+- **"identity=server"** — a temporary hack in `app.py` where `AuthService` is instantiated at startup without a real identity. This is a known violation to be removed.
+- **"credential"** — use **Connection** for the full authenticated session; use **access token** / **API key** for the individual secret.

{authsome-0.3.2 → authsome-0.4.1}/CONTRIBUTING.md

@@ -33,6 +33,9 @@ Reach for a well-maintained dependency before writing your own crypto, HTTP clie
 **Deep modules over shallow ones.**
 Prefer a module with a small surface area and rich internals over a sprawl of thin wrappers. A single `AuthClient` that handles everything cleanly beats a dozen one-method classes. More files is not more modular.
 
+**Composition over inheritance.**
+Prefer small collaborators wired together through explicit dependencies over inheritance hierarchies. Use inheritance only when there is a real subtype relationship and composition would make the design less clear.
+
 **Single responsibility and separation of concerns.**
 Auth authenticates. Vault stores credentials. The CLI presents output. These boundaries are not negotiable — a flow should not write to storage, and storage should not know about OAuth. If a function is hard to name, it's doing too many things.
 

{authsome-0.3.2 → authsome-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authsome
-Version: 0.3.2
+Version: 0.4.1
 Summary: A portable local authentication library for AI agents and developer tools
 Author-email: Manoj Bajaj <manojbajaj95@gmail.com>
 License-Expression: MIT
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.13
+Requires-Dist: argon2-cffi>=25.1.0
 Requires-Dist: base58>=2.1.1
 Requires-Dist: click>=8.0
 Requires-Dist: cryptography>=41.0
@@ -205,6 +206,14 @@ npm i -g mint   # requires Node.js >= 20.17.0
 mint dev
 ```
 
+## Telemetry
+
+Authsome's daemon can emit product analytics through PostHog. You can disable telemetry with any of these environment variables:
+
+- `DO_NOT_TRACK=1` disables analytics using the standard opt-out convention.
+- `POSTHOG_DISABLED=1` disables analytics using PostHog's recommended kill switch.
+- `AUTHSOME_ANALYTICS=0` disables analytics with an Authsome-specific override.
+
 ## Community
 
 - **[Discord](https://discord.gg/9YP2C9tvMp)** for questions, help, and showing what you're building.

{authsome-0.3.2 → authsome-0.4.1}/README.md

@@ -165,6 +165,14 @@ npm i -g mint   # requires Node.js >= 20.17.0
 mint dev
 ```
 
+## Telemetry
+
+Authsome's daemon can emit product analytics through PostHog. You can disable telemetry with any of these environment variables:
+
+- `DO_NOT_TRACK=1` disables analytics using the standard opt-out convention.
+- `POSTHOG_DISABLED=1` disables analytics using PostHog's recommended kill switch.
+- `AUTHSOME_ANALYTICS=0` disables analytics with an Authsome-specific override.
+
 ## Community
 
 - **[Discord](https://discord.gg/9YP2C9tvMp)** for questions, help, and showing what you're building.