authsome 0.4.2__tar.gz → 0.5.0__tar.gz

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

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

authsome-0.5.0/.gitleaksignore

@@ -0,0 +1,2 @@
+# PostHog public project API key — intentionally committed, not a secret
+src/authsome/server/analytics.py:generic-api-key:50

{authsome-0.4.2 → authsome-0.5.0}/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [0.5.0](https://github.com/agentrhq/authsome/compare/authsome-v0.4.2...authsome-v0.5.0) (2026-05-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* existing local installs have an unclaimed identity under local@authsome.internal and are rejected until the user registers a principal (email+password) and claims the identity.
+* existing Fernet-encrypted vaults cannot be read back; migration requires re-importing credentials.
+* mount dashboard at / instead of /ui
+
+### Features
+
+* add admin audit dashboard ([1bc5044](https://github.com/agentrhq/authsome/commit/1bc504472ace6629e88a9ad06531c927ff31da26))
+* add Anthropic and Gemini bundled providers ([1e47c48](https://github.com/agentrhq/authsome/commit/1e47c48b07ee76d5a9dfdd58c238150316dca2a0))
+* add Anthropic and Gemini bundled providers ([e788328](https://github.com/agentrhq/authsome/commit/e78832884f69492978a097587374d0e3853371db))
+* add browser SSO via Chrome cookie reading (browser-cookie3) ([aeb4263](https://github.com/agentrhq/authsome/commit/aeb426357f43abe6a13b3684de135c3e6e110166))
+* Add docs for design of principal roles and audit ([de33f8a](https://github.com/agentrhq/authsome/commit/de33f8a5148ff9f6d30e5b392b76e57af751b5ed))
+* add principal_role parameter to AuthService and dependency injection routes ([7d43b56](https://github.com/agentrhq/authsome/commit/7d43b567c8c3e0eec8e4ef33b7fd0eb53cb431b4))
+* browser SSO via Chrome cookie reading (browser-cookie3) ([7607600](https://github.com/agentrhq/authsome/commit/7607600eba2e62125aac801cd09ad28f3948cf3c))
+* implement audit events and principal roles ([9503710](https://github.com/agentrhq/authsome/commit/950371088ba46e5f38086dd0c7fccabd0333f83d))
+* implement audit events and principal roles ([0ed077b](https://github.com/agentrhq/authsome/commit/0ed077b9df60808f840d37460de3a75c5dd8303c))
+* move daemon management commands from admin module to main CLI ([397a8e8](https://github.com/agentrhq/authsome/commit/397a8e8e0aa1142a432ba1af73a3f4235ecccfd9))
+* move daemon management commands from admin module to main CLI ([af356d5](https://github.com/agentrhq/authsome/commit/af356d5f4ff435488484c736516cdad1f61780f4))
+* replace flat master-key vault encryption with Argon2id KEK/DEK model ([b76903d](https://github.com/agentrhq/authsome/commit/b76903d74b61ff469a4221d41e95713a04bdaeb2))
+* respect AUTHSOME_DAEMON_URL in all daemon control paths ([fa23037](https://github.com/agentrhq/authsome/commit/fa23037d73c6c1cc2892654eca6a5d6931f79243))
+* respect AUTHSOME_DAEMON_URL in all daemon control paths ([1ba904b](https://github.com/agentrhq/authsome/commit/1ba904bf0db74fb20e43a370fecf559e97e1f95c))
+* server store refactor ([acb2013](https://github.com/agentrhq/authsome/commit/acb20132f04ef05c81f9d16ce6c2685607ee4171))
+
+
+### Bug Fixes
+
+* added support for cookie expiry date ([5ea8aa9](https://github.com/agentrhq/authsome/commit/5ea8aa977e8d044420d4f469c047319ed1c3765c))
+* Fix incorrect posthog key and remove unnecessary tests ([77c7bb7](https://github.com/agentrhq/authsome/commit/77c7bb7b24e9bd4f8135685127ff53617e9a73b1))
+* Fix incorrect posthog key and remove unnecessary tests ([8f8d9b9](https://github.com/agentrhq/authsome/commit/8f8d9b9e59f6896dca3f3b6b14d33f363d4738b3))
+* refresh DCR provider client on replace ([9af604d](https://github.com/agentrhq/authsome/commit/9af604d80d023ef0762f5f1c6ae41857302de0de))
+* refresh DCR provider client on replace ([595de28](https://github.com/agentrhq/authsome/commit/595de28f25f5526f63cf6e9136291d86c6972754))
+* remove extraneous admin command argument from daemon subprocess invocation ([2c43de6](https://github.com/agentrhq/authsome/commit/2c43de6449ad38f95bd80c6e6d1901b8526e952c))
+* ruff check ([6dbef78](https://github.com/agentrhq/authsome/commit/6dbef782679cdb82a0735dfd879234316d34efad))
+
+
+### Reverts
+
+* display input fields for dcr providers ([6c108cb](https://github.com/agentrhq/authsome/commit/6c108cb44f5c63ee0c069f941ff2302e9f7a9ff3))
+
+
+### Documentation
+
+* correct manual testing guide against the current CLI surface ([0a7c379](https://github.com/agentrhq/authsome/commit/0a7c379c007afe1b01d48341b2df14f199411841))
+* update manual testing guide for the unified claim flow ([70e5539](https://github.com/agentrhq/authsome/commit/70e5539a5924a96b7864862444957dc4e385f49e))
+
+
+### Code Refactoring
+
+* mount dashboard at / instead of /ui ([f8cf936](https://github.com/agentrhq/authsome/commit/f8cf93663f7a4bc757082155c6f4d6bde51da366))
+* unify local and hosted into a single deployment flow ([63bd4c9](https://github.com/agentrhq/authsome/commit/63bd4c90aa10e31d4b11ad9b190f00f1e1e1a316))
+
 ## [0.4.2](https://github.com/agentrhq/authsome/compare/authsome-v0.4.1...authsome-v0.4.2) (2026-05-25)
 
 

{authsome-0.4.2 → authsome-0.5.0}/CONTEXT.md

@@ -88,18 +88,19 @@ Think of this as the secrets layer. Encrypts and decrypts credential blobs trans
 
 ### `audit/` — Structured event recording
 
-Think of this as the append-only ledger. Records who did what and when.
+Think of this as the audit instrumentation layer. Defines what happened; `server/` decides where it goes.
 
 **Owns:**
-- `AuditEvent` model
-- `log()` / `alog()` — append to a structured JSON-lines log file
-- `setup()` / `clear()` — log file lifecycle (called by server at startup/shutdown)
+- `AuditEvent` domain model — mandatory fields: `identity`, `principal_id`, `provider`, `connection`; optional: `method`, `path`, `status`, `metadata`
+- `log()` / `alog()` — emit an `AuditEvent` as an OTel `LogRecord` via `get_logger_provider()`
+- Translation from `AuditEvent` → OTel `LogRecord`
 
 **Does not own:**
-- Business logic
-- Any storage beyond the append-only log file
+- Storage — no file I/O, no database
+- Provider lifecycle (`setup()` / `clear()` removed — owned by `server/`)
+- Knowledge of where events are routed
 
-**Imports nothing from this codebase.** Imported by: `auth/`, `server/`
+**Imports:** `opentelemetry-api` only (no SDK, no storage). **Imports nothing from this codebase.** Imported by: `server/`, `proxy/`
 
 ---
 
@@ -120,6 +121,9 @@ Think of this as the daemon process. Wires identity + auth + vault + audit toget
 - `server/app.py` — FastAPI application factory and lifespan
 - `server/routes/` — HTTP API surface
 - `server/schemas.py` — API response schemas
+- `server/audit_store.py` — `SQLiteLogExporter` (OTel `LogExporter` impl) + `AuditStore` query interface; `LoggerProvider` lifecycle (setup at startup, shutdown at teardown)
+- `server/routes/audit.py` — `GET /audit/events` (filtered, paginated admin read)
+- `POST /audit/events` — ingest endpoint for proxy-side external AuditEvents; server enriches `principal_id` from PoP JWT
 
 **All filesystem interaction for server-owned state lives here.** No other module writes to server-owned paths.
 
@@ -141,6 +145,7 @@ A mitmproxy-based HTTPS proxy. Intercepts outgoing agent requests and injects au
 - Credential loading (asks the server)
 - Route catalog construction (asks the server)
 - Provider definitions
+- Audit storage — ships External AuditEvents to server via `POST /audit/events` (fire-and-forget); does not call `audit.log()` directly
 
 **Imported by:** `cli/`
 
@@ -178,12 +183,15 @@ Click-based CLI and HTTP client. Everything here is a client to the server HTTP
 
 **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.
+**Principal**: Non-cryptographic logical partition (human or team) that owns Vaults. Identified by an opaque **PrincipalId** (e.g., `principal_abc123def456`). Has no cryptographic key. Carries exactly one **PrincipalRole**.
 _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
 
+**PrincipalRole**: Authorization tier for a Principal. Either `admin` or `user`. The first Principal created on a server is always `admin`; all subsequent Principals are `user`. Stored as a column on the Principal record — not in environment variables or a separate table.
+_Avoid_: permission level, access level, user type
+
 **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
 
@@ -192,7 +200,7 @@ _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.
+**IdentityClaimRecord**: Binding from an Identity (Handle) to a Principal (PrincipalId) with a `ClaimStatus`. Created when an authenticated Principal confirms the browser claim that `authsome init` initiates. Vault access is gated until the claim is accepted.
 _Avoid_: Claim, IdentityRegistration (as claim), join request
 
 **ClaimStatus**: Lifecycle state: `pending` → `accepted` | `rejected`.
@@ -201,9 +209,7 @@ _Avoid_: Claim, IdentityRegistration (as claim), join request
 
 ## 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.
+There is a single flow for every deployment — no deployment mode (see ADR 0007). `authsome init` creates an Identity and registers it; the daemon returns `registration_status = "claim_required"` with a browser **claim URL**. The user opens the URL and registers (or logs in) with **email + password**: the first Principal created on a server becomes `admin`, all subsequent Principals are `user`. The authenticated Principal then confirms the claim, which binds the Identity to the Principal and creates the Principal's default Vault. Until the claim is `accepted`, all vault operations return `403`. The CLI opens the claim URL automatically and polls for completion (and prints the URL to stderr for headless use).
 
 ---
 
@@ -240,6 +246,14 @@ AuthService does not query registries, does not know about server filesystem pat
 
 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.
 
+**External AuditEvent**: An event produced by the proxy layer — records an outbound HTTP call an agent made through the proxy to a third-party API (e.g., a call to `api.github.com`). Classified by provider and connection. Mandatory fields: identity, principal_id, provider, connection. Optional fields: HTTP method, path, response status.
+_Avoid_: proxy event, API event, outbound event
+
+**Internal AuditEvent**: An event produced by the server layer — records credential lifecycle operations (login, logout, token refresh, revocation) and auth flow steps.
+_Avoid_: server event, auth event, lifecycle event
+
+**Audit delivery**: External AuditEvents are shipped from the proxy to the server via `POST /audit/events` (fire-and-forget, best-effort). The proxy does not write to a local audit file. The server is the single source of truth for all audit events. `principal_id` is resolved server-side from the PoP JWT on the ingest request — the proxy does not need to supply it.
+
 ---
 
 ## Flagged Ambiguities

{authsome-0.4.2 → authsome-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authsome
-Version: 0.4.2
+Version: 0.5.0
 Summary: A portable local authentication library for AI agents and developer tools
 Author-email: Manoj Bajaj <manojbajaj95@gmail.com>
 License-Expression: MIT
@@ -14,8 +14,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.13
+Requires-Dist: aiosqlite>=0.20
 Requires-Dist: argon2-cffi>=25.1.0
+Requires-Dist: asyncpg>=0.30
 Requires-Dist: base58>=2.1.1
+Requires-Dist: browser-cookie3>=0.19
 Requires-Dist: click>=8.0
 Requires-Dist: cryptography>=41.0
 Requires-Dist: fastapi>=0.115
@@ -23,6 +26,8 @@ Requires-Dist: jinja2>=3.1
 Requires-Dist: keyring>=24.0
 Requires-Dist: loguru>=0.7
 Requires-Dist: mitmproxy>=11.0
+Requires-Dist: opentelemetry-api>=1.42.1
+Requires-Dist: opentelemetry-sdk>=1.42.1
 Requires-Dist: posthog>=3.0
 Requires-Dist: py-key-value-aio[disk]
 Requires-Dist: pydantic>=2.0
@@ -32,6 +37,7 @@ Requires-Dist: requests>=2.28
 Requires-Dist: uvicorn>=0.30
 Provides-Extra: dev
 Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: pre-commit>=4.6.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'

authsome-0.5.0/docs/adr/0005-audit-otel-sqlite.md

@@ -0,0 +1,22 @@
+# Audit events use OTel Logs API with a SQLite exporter owned by the server
+
+The proxy runs on the client machine and the server runs remotely, so writing audit events to a local file produces two disjoint logs that an IT admin cannot view in one place. We need a single server-owned audit store that both the proxy and the server write into.
+
+**Decision:** `audit/` is a pure leaf that imports only `opentelemetry-api`. It defines `AuditEvent`, translates it to an OTel `LogRecord`, and emits via the globally registered `LoggerProvider` — with no knowledge of where events go. `server/` owns a custom `SQLiteLogExporter` (implementing the OTel `LogExporter` interface), registers a `LoggerProvider` with a `BatchLogRecordProcessor` at daemon startup, and exposes `GET /audit/events` for admin queries. The proxy ships External AuditEvents to the server fire-and-forget via `POST /audit/events` rather than writing to a local file; the server enriches each inbound event with `principal_id` resolved from the PoP JWT.
+
+**Considered alternatives:**
+
+- *Flat JSON-lines file per process* — the current approach. Rejected because it produces two disjoint audit logs in the client/server topology, with no queryable interface for the admin view.
+- *Proxy hosted on server* — rejected because it routes all agent traffic through the server machine, adding a network round-trip to every API call and making the server a traffic bottleneck.
+- *Pure OTLP to an external collector* — rejected as the primary store because it requires operator-provisioned infrastructure. OTLP remains a valid future second exporter on the same `LoggerProvider` for teams that already run Grafana or Datadog.
+- *SQLite owned by `audit/`* — rejected to preserve `audit/` as a dependency-free leaf. Storage decisions belong to `server/`, consistent with how all other server-owned state is managed.
+
+**Not considered:** replacing loguru with OTel for operational logging. Loguru (68 call sites) serves developers debugging live systems — free-form, level-filtered, short-retention. Audit serves IT admins answering compliance questions — structured, required fields, long-retention, queryable. Routing loguru through the SQLite exporter would fill the admin view with operational noise. They are different things with different audiences and must stay separate.
+
+**Consequences:**
+
+- `audit/` gains `opentelemetry-api` as a dependency; `server/` gains `opentelemetry-sdk` and `aiosqlite` (or `sqlite3`).
+- `audit.setup()` / `audit.clear()` are removed; `server/app.py` lifespan manages the `LoggerProvider`.
+- The proxy's two existing direct `audit.log()` calls (`proxy_no_credentials`, `proxy_deny`) move to fire-and-forget HTTP posts to the server.
+- A second OTLP exporter can be added to the `LoggerProvider` at any time without touching `audit/` or `proxy/`.
+- All audit events — Internal (server) and External (proxy) — are queryable from a single `GET /audit/events` endpoint.

authsome-0.5.0/docs/adr/0006-principal-roles-admin-user.md

@@ -0,0 +1,18 @@
+# Principal roles: admin / user, first-created principal is admin
+
+Principals need an authorization tier to gate deployment-level operations (audit log access, provider registration/deletion, cross-vault credential revocation) from per-principal operations (own connections, claim accept/reject). We store a `role` column (`admin` | `user`) directly on the `principals` table. The first Principal created on a server is assigned `admin`; all subsequent Principals receive `user`. Role assignment is immutable at creation time (mutation is deferred to a future milestone).
+
+## Considered options
+
+**Environment variable (`AUTHSOME_ADMIN_PRINCIPALS`)** — the prior approach. Rejected because it requires knowing the PrincipalId before the server starts, cannot be changed without a restart, and is invisible to the UI and route layer.
+
+**Separate `principal_roles` table** — considered for future extensibility (multiple roles per principal). Rejected as premature: the role model is binary and a join adds complexity without benefit today.
+
+**Default admin account created at server init** — would require deciding on credentials before any real user exists. Rejected in favour of first-user-becomes-admin: the first principal to register is admin, all subsequent principals are users. (Originally justified as "zero-config" for an implicit local principal; that implicit-principal path was later removed when local and hosted were unified into a single registration + claim flow — see ADR 0007. First-principal-is-admin remains the rule, now reached the same way in every deployment.)
+
+## Consequences
+
+- `AUTHSOME_ADMIN_PRINCIPALS` env var and `is_admin_principal()` are removed entirely.
+- Admin enforcement at the route level uses a `get_admin_auth_service` FastAPI dependency (parallel to `get_protected_auth_service`) that raises `HTTP 403` for non-admin principals.
+- Admin-only routes: `GET /audit/events`, `POST /providers`, `DELETE /providers/{provider}`, `POST /connections/{provider}/revoke`.
+- Schema migration: `ALTER TABLE principals ADD COLUMN role TEXT NOT NULL DEFAULT 'user'`, followed by setting the earliest-created principal to `'admin'`.

authsome-0.5.0/docs/adr/0007-unified-deployment-flow.md

@@ -0,0 +1,36 @@
+# Unified deployment flow: one registration + claim path for every deployment
+
+The daemon previously branched on a deployment mode (`AUTHSOME_DEPLOYMENT_MODE`, defaulting to `local`) selected at startup, and ran two parallel implementations of nearly every ownership concept:
+
+- **Local**: every Identity collapsed onto one synthetic Principal (`local@authsome.internal`); no claim was required; the Ed25519 PoP key was the only credential. Implemented by `LocalOwnershipResolver` and `LocalIdentityBootstrapService`.
+- **Hosted**: each account was its own Principal authenticated by email+password in the browser; an Identity had to be explicitly claimed and accepted. Implemented by `HostedOwnershipResolver` and `HostedIdentityBootstrapService`.
+
+Two code paths doubled the test surface, scattered `if get_deployment_mode() == "hosted"` branches across `dependencies.py`, `routes/_deps.py`, `routes/ui.py`, `routes/health.py`, and `credential_service.py`, and — most importantly — meant "local and hosted behave the same" was asserted in prose but never enforced in code, so the two paths were free to drift. The synthetic local Principal also had a latent wart: a second local Identity silently inherited the *admin* Principal and its Vault, which the hosted model would never allow.
+
+## Decision
+
+Collapse to a single flow, identical for every deployment. There is no deployment mode.
+
+1. `authsome init` generates the Ed25519 Identity and registers it; the daemon returns `registration_status = "claim_required"` with a browser **claim URL**.
+2. The user opens the claim URL and **registers (or logs in) with email + password**. The first Principal created on a server becomes **admin** (ADR 0006); all subsequent Principals are users.
+3. The authenticated Principal **confirms the claim**, binding the Identity to the Principal and creating the Principal's default Vault.
+4. PoP-authenticated calls are then authorized; `OwnershipResolver.resolve` requires an *accepted* claim.
+
+The one irreducible difference between a single-machine and a networked deployment — *who authenticates the claiming Principal* — is resolved by always requiring the email+password browser step. Local is no longer special-cased; the local user is simply the first to sign up and therefore the admin.
+
+The CLI (`AuthsomeApiClient.ensure_identity_ready`) was already mode-agnostic: it reacts to `claim_required` by opening the browser and polling, so it required no behavioural change. It now prints the claim URL to stderr so headless users can complete the step manually.
+
+This supersedes the local/hosted split described in ADR 0003 (§ "local mode … hosted mode") and the "zero-config local" rationale in ADR 0006.
+
+## Considered alternatives
+
+**Single resolver with an injected claim-acceptance policy** (local auto-accepts, hosted requires a human). Keeps one code path while preserving local's zero-config experience. Rejected by explicit product decision: we want local and hosted to be byte-for-byte identical, with no second path or policy seam to maintain.
+
+**Keep two resolvers, only harden with tests + docs.** Smallest change, but leaves the drift risk and duplicate test surface in place. Rejected.
+
+## Consequences
+
+- `AUTHSOME_DEPLOYMENT_MODE`, `get_deployment_mode()`, `LOCAL_PRINCIPAL_EMAIL`, the `Local*`/`Hosted*` resolver and bootstrap classes, and the `AuthService(deployment_mode=...)` parameter are all removed. `OwnershipResolver` and `IdentityBootstrapService` are single concrete classes.
+- Admin enforcement is purely role-based: `_ensure_admin_operation_allowed` / `_ensure_provider_client_mutation_allowed` raise for any non-admin Principal, in every deployment (previously non-admins were implicitly allowed in local mode because the sole local Principal was always admin).
+- The server-rendered UI always requires a hosted browser session; the local filesystem-identity UI path is gone. `HealthResponse.mode` is removed.
+- **Breaking change.** Existing local installs have an Identity registered with no accepted claim and data under the `local@authsome.internal` Principal/Vault. After upgrading, those Identities are rejected until the user registers a Principal (email+password) and claims the Identity. A migration that rebinds the existing local Vault to a freshly registered Principal is possible but is intentionally out of scope here.