authsome 0.2.2__tar.gz → 0.2.2rc35__tar.gz

{authsome-0.2.2 → authsome-0.2.2rc35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authsome
-Version: 0.2.2
+Version: 0.2.2rc35
 Summary: A portable local authentication library for AI agents and developer tools
 Author-email: Manoj Bajaj <manojbajaj95@gmail.com>
 License-Expression: MIT
@@ -38,8 +38,8 @@ Description-Content-Type: text/markdown
 [![codecov](https://codecov.io/gh/manojbajaj95/authsome/branch/main/graph/badge.svg)](https://codecov.io/gh/manojbajaj95/authsome)
 
 ```text
-              __  __
-  ____ ___  _/ /_/ /_  _________  ____ ___  ___
+               __  __
+  ____ ___  __/ /_/ /_  _________  ____ ___  ___
  / __ `/ / / / __/ __ \/ ___/ __ \/ __ `__ \/ _ \
 / /_/ / /_/ / /_/ / / (__  ) /_/ / / / / / /  __/
 \__,_/\__,_/\__/_/ /_/____/\____/_/ /_/ /_/\___/
@@ -94,8 +94,8 @@ Then agents get valid credentials on demand:
 authsome get github --field access_token --show-secret
 # → ghu_...
 
-authsome export github --format env
-# → Successfully exported credentials to environment.
+export $(authsome export github)
+# → sets GITHUB_ACCESS_TOKEN in current shell
 
 authsome run python my_agent.py
 # runs behind a local auth proxy that injects headers at request time
@@ -135,13 +135,27 @@ authsome list                          # all connections + token status
 
 ## Docs
 
-- [CLI reference](docs/cli.md)
-- [Providers](docs/providers.md)
-- [Architecture](docs/architecture.md)
+The full documentation site lives in [`docs/site/`](docs/site/)
+
+- [Quickstart](docs/site/quickstart.mdx)
+- [CLI reference](docs/site/reference/cli.mdx)
+- [Architecture](docs/site/concepts/architecture.mdx)
+- [Custom providers](docs/site/guides/custom-providers.mdx)
+- [Troubleshooting](docs/site/troubleshooting/doctor.mdx)
+
+To preview locally:
+
+```bash
+cd docs/site
+npm i -g mint   # requires Node.js >= 20.17.0
+mint dev
+```
+
+
 
 ## Specs
 
-- [Authsome v1](specs/authsome-v1.md)
+- [Authsome v1](docs/specs/authsome-v1.md)
 
 ## License
 

{authsome-0.2.2 → authsome-0.2.2rc35}/README.md

@@ -8,8 +8,8 @@
 [![codecov](https://codecov.io/gh/manojbajaj95/authsome/branch/main/graph/badge.svg)](https://codecov.io/gh/manojbajaj95/authsome)
 
 ```text
-              __  __
-  ____ ___  _/ /_/ /_  _________  ____ ___  ___
+               __  __
+  ____ ___  __/ /_/ /_  _________  ____ ___  ___
  / __ `/ / / / __/ __ \/ ___/ __ \/ __ `__ \/ _ \
 / /_/ / /_/ / /_/ / / (__  ) /_/ / / / / / /  __/
 \__,_/\__,_/\__/_/ /_/____/\____/_/ /_/ /_/\___/
@@ -64,8 +64,8 @@ Then agents get valid credentials on demand:
 authsome get github --field access_token --show-secret
 # → ghu_...
 
-authsome export github --format env
-# → Successfully exported credentials to environment.
+export $(authsome export github)
+# → sets GITHUB_ACCESS_TOKEN in current shell
 
 authsome run python my_agent.py
 # runs behind a local auth proxy that injects headers at request time
@@ -105,13 +105,27 @@ authsome list                          # all connections + token status
 
 ## Docs
 
-- [CLI reference](docs/cli.md)
-- [Providers](docs/providers.md)
-- [Architecture](docs/architecture.md)
+The full documentation site lives in [`docs/site/`](docs/site/)
+
+- [Quickstart](docs/site/quickstart.mdx)
+- [CLI reference](docs/site/reference/cli.mdx)
+- [Architecture](docs/site/concepts/architecture.mdx)
+- [Custom providers](docs/site/guides/custom-providers.mdx)
+- [Troubleshooting](docs/site/troubleshooting/doctor.mdx)
+
+To preview locally:
+
+```bash
+cd docs/site
+npm i -g mint   # requires Node.js >= 20.17.0
+mint dev
+```
+
+
 
 ## Specs
 
-- [Authsome v1](specs/authsome-v1.md)
+- [Authsome v1](docs/specs/authsome-v1.md)
 
 ## License
 

{authsome-0.2.2 → authsome-0.2.2rc35}/docs/cli.md

@@ -14,7 +14,7 @@ All commands support `--json` for machine-readable output.
 | `inspect <provider>` | Show the full provider definition schema. |
 | `login <provider>` | Authenticate with a provider using its configured flow. |
 | `get <provider>` | Get connection metadata (secrets redacted by default). |
-| `export <provider>` | Export credentials in `env` or `json` format. |
+| `export <provider>` | Export credentials in `env`, `shell`, or `json` format. |
 | `run -- <cmd>` | Run a subprocess behind the local auth injection proxy. |
 | `logout <provider>` | Log out of a connection and remove local state. |
 | `revoke <provider>` | Complete reset of the provider, removing all connections and client secrets. |
@@ -97,10 +97,17 @@ authsome export <provider> [OPTIONS]
 | Option | Description |
 |--------|-------------|
 | `--connection <name>` | Connection name (default: `default`). |
-| `--format <fmt>` | Output format: `env` (default) or `json`. |
+| `--format <fmt>` | Output format: `env` (default), `shell`, or `json`. |
 
 ```bash
-authsome export github --format env    # inject GITHUB_TOKEN into environment
+# Output KEY=VALUE pairs (useful for chaining)
+authsome export github --format env
+
+# Chaining example
+export $(authsome export github)
+
+# Save to a .env file
+authsome export github > .env
 ```
 
 ### `run`

authsome-0.2.2rc35/docs/site/README.md

@@ -0,0 +1,50 @@
+# authsome docs
+
+The Mintlify documentation site for [authsome](https://github.com/manojbajaj95/authsome).
+
+## Local preview
+
+Requires Node.js `>=20.17.0`.
+
+```bash
+npm i -g mint
+mint dev
+```
+
+The site renders at `http://localhost:3000` with hot reload.
+
+## Validate before committing
+
+```bash
+mint broken-links     # check internal links
+mint a11y             # check accessibility issues
+mint validate         # run schema + content validation
+```
+
+## Structure
+
+```
+docs/site/
+  docs.json                    Mintlify config: theme, navigation, navbar
+  index.mdx                    Landing page
+  quickstart.mdx               First-run walkthrough
+  guides/                      Task-oriented guides
+  concepts/                    Architecture and core concepts
+  reference/                   CLI, schema, env vars, bundled providers
+  troubleshooting/             Diagnostic pages
+```
+
+## Adding a page
+
+1. Create the MDX file in the right subfolder.
+2. Add it to the appropriate `pages` list in `docs.json` — pages not referenced in `docs.json` are hidden from the sidebar.
+3. Run `mint dev` to preview, then `mint broken-links` and `mint validate` before opening a PR.
+
+## Style
+
+Match the surrounding pages:
+
+- Sentence case for headings.
+- Code blocks always have a language tag.
+- Internal links use root-relative paths without file extensions: `/guides/login-with-oauth`, not `./login-with-oauth.mdx`.
+- Prefer Mintlify components (`<Steps>`, `<CodeGroup>`, `<Tabs>`, `<Card>`, `<Columns>`, `<Tip>`, `<Warning>`) over plain Markdown when they help.

authsome-0.2.2rc35/docs/site/concepts/architecture.mdx

@@ -0,0 +1,138 @@
+---
+title: "Architecture"
+description: "Five layers — identity, policy, vault, auth, audit — composed by an explicit orchestrator."
+---
+
+Authsome is layered. Each layer has one bounded responsibility. Layers do not reach sideways into other layers — explicit orchestrators compose them. This makes every layer independently testable and independently swappable.
+
+Two deployment modes share the same layered architecture:
+
+- **Sidecar mode** — `authsome run -- python agent.py`. Transparent credential injection through an HTTP proxy. No auth code in the agent.
+- **Library mode** — `from authsome.context import AuthsomeContext`. A direct programmatic API.
+
+```text
+agent
+  ↓  HTTP request via HTTP_PROXY=localhost:<port>
+[ sidecar ]              proxy-mode orchestrator
+  ↓
+identity     →  signed principal chain (actor=agent, subject=user)
+  ↓
+policy       →  allow / deny
+  ↓
+vault        →  encrypted credential record
+  ↓  if expired:
+auth (low)   →  external token endpoint → fresh credential
+  ↓
+sidecar      →  vault.write(fresh credential)
+  ↓
+sidecar injects Authorization header
+  ↓
+external API
+  ↓
+audit        ←  append-only log entry at every step
+```
+
+## The five layers
+
+| Layer | Owns | Does not own |
+|------|------|--------------|
+| Identity | Agent identity, principal chain token | Credentials, access decisions, token expiry |
+| Policy | Access control, allow/deny decisions | Credentials, token refresh, encryption |
+| Vault | Minimal encrypted KV interface (`get`/`put`/`delete`/`list`) | OAuth, providers, expiry, refresh, policy |
+| Auth | Token refresh, OAuth acquisition flows | Persistent storage, access decisions |
+| Audit | Append-only event log | Decisions, credentials, request flow |
+
+<Note>
+  Identity, Policy, and Audit are part of the long-term architecture. The current alpha implementation focuses on Vault and Auth. The CLI emits audit events to `~/.authsome/audit.log` today; identity and policy enforcement are planned.
+</Note>
+
+## Vault: minimal storage
+
+The Vault is intentionally small. It exposes a generic encrypted key-value interface and nothing else.
+
+```python
+vault.get(key)
+vault.put(key, value)
+vault.delete(key)
+vault.list(prefix)
+```
+
+Vault does not know about OAuth, providers, token expiry, refresh, policy, audit, or principal-chain semantics. It stores and retrieves credential records by key. Orchestrators decide which keys to read, whether access is allowed, whether a token must be refreshed, and what should be audited.
+
+The local backend uses encrypted SQLite under `~/.authsome/profiles/<name>/store.db`. Field-level encryption uses AES-256-GCM with a 256-bit data key and a 96-bit nonce per encryption. The data key is wrapped by either a local file (`~/.authsome/master.key`, mode `0600`) or the OS keyring.
+
+See [Credential storage](/concepts/credential-storage) for the storage model and key namespace.
+
+## Auth: two levels
+
+The Auth layer has two intentionally separate surfaces.
+
+**Low level (`auth.flows`).** A pure function. Receives expired credentials and refresh material. Calls the external token endpoint. Returns fresh credentials and updated expiry. No vault access. No side effects. Independently testable.
+
+**High level (`AuthLayer`).** A stateful orchestrator with a vault dependency. Reads the credential from the vault, calls the stateless refresh if expired, writes the result back, returns a usable token. This is what library users call.
+
+```python
+from authsome.context import AuthsomeContext
+
+ctx = AuthsomeContext.create()
+token = ctx.auth.get_access_token("github", connection="default")
+```
+
+Acquisition flows shipped today: PKCE (RFC 7636), Device Authorization Grant (RFC 8628), Dynamic Client Registration + PKCE, and an API-key flow.
+
+## AuthsomeContext: the orchestrator
+
+`AuthsomeContext` is the runtime wiring container assembled once per CLI invocation. It holds `Vault`, `AuthLayer`, and `ProxyRunner` as attributes. No business logic of its own.
+
+```python
+from authsome.context import AuthsomeContext
+
+ctx = AuthsomeContext.create()
+ctx.auth         # AuthLayer
+ctx.vault        # Vault
+ctx.proxy        # ProxyRunner
+ctx.home         # Path to ~/.authsome
+```
+
+Library callers use `AuthsomeContext` directly. The CLI creates one context per invocation.
+
+## Proxy: sidecar orchestrator
+
+In sidecar mode, the proxy runner is the orchestrator.
+
+1. Starts the HTTP proxy on a random local port.
+2. Spawns the agent as a subprocess with `HTTP_PROXY` set to the local proxy address.
+3. Intercepts outbound HTTP requests from the agent.
+4. Looks up the matching provider by `host_url`, asks the AuthLayer for fresh credentials, and injects them into the `Authorization` header.
+5. Writes refreshed credentials back to the vault.
+6. Tears down cleanly when the agent exits.
+
+See [Proxy injection](/concepts/proxy-injection) for the routing contract and known limitations.
+
+## Storage layout
+
+```text
+~/.authsome/
+  config.json         global settings, encryption mode, active profile
+  master.key          encryption key, mode 0600
+  audit.log           append-only audit events
+  providers/          user-defined provider definitions
+  profiles/
+    default/
+      store.db        per-profile credential store (SQLite)
+      lock            advisory write lock
+```
+
+Profiles isolate credential sets — for example `default`, `work`, or a profile per agent.
+
+## Standards
+
+| Concern | v1 |
+|---------|-----|
+| Token refresh | OAuth 2.0 (RFC 6749) |
+| Browser-less OAuth | Device Authorization Grant (RFC 8628) |
+| PKCE | RFC 7636 |
+| Encryption at rest | AES-256-GCM, 256-bit key, 96-bit nonce |
+| Agent identity (planned) | Ed25519, `agent://local/<name>` URIs |
+| Principal chain (planned) | Local signed JWT, RFC 8693 later |
+| Policy (planned) | Cedar |

authsome-0.2.2rc35/docs/site/concepts/credential-storage.mdx

@@ -0,0 +1,160 @@
+---
+title: "Credential storage"
+description: "How authsome encrypts, namespaces, and locks the per-profile credential vault."
+---
+
+Authsome stores all credentials in a per-profile encrypted SQLite vault under `~/.authsome/`. The vault speaks a minimal key-value interface — orchestrators on top of it (`AuthLayer`, the proxy) decide which keys to read and write.
+
+## Storage layout
+
+```text
+~/.authsome/
+  config.json
+  master.key                       # mode 0600
+  audit.log
+  providers/
+    <name>.json                    # user-registered providers (override bundled)
+  profiles/
+    default/
+      store.db                     # SQLite vault
+      lock                         # advisory write lock
+```
+
+Profiles are independent credential namespaces. Connections in `default` are invisible to `work` and vice versa.
+
+## Key namespace
+
+Inside a profile's `store.db`, keys follow this shape:
+
+```text
+profile:<profile>:<provider>:metadata
+profile:<profile>:<provider>:state
+profile:<profile>:<provider>:client
+profile:<profile>:<provider>:connection:<connection_name>
+```
+
+| Key | Holds |
+|-----|-------|
+| `metadata` | Non-secret per-profile record: known connection names, default connection, last-used connection. |
+| `state` | Transient per-profile state: last refresh attempt, last refresh error. |
+| `client` | OAuth client credentials (`client_id`, encrypted `client_secret`). One per provider per profile. |
+| `connection:<name>` | The credential record for a named connection: tokens, scopes, expiry, account info. |
+
+Provider definitions are not stored in the vault. They live on the filesystem in `~/.authsome/providers/<name>.json` (user-registered, takes precedence) or as bundled JSON files inside the package.
+
+## Encryption
+
+Sensitive fields are encrypted at rest using AES-256-GCM.
+
+| Property | Value |
+|----------|-------|
+| Algorithm | AES-256-GCM |
+| Master key | 256 bits, generated on first init |
+| Nonce | 96 bits, generated per encryption |
+
+The master key is held by one of two backends, selected by `config.encryption.mode`:
+
+- **`local_key`** (default) — the key is stored as base64-encoded JSON in `~/.authsome/master.key` with mode `0600`. File permissions are the only protection at rest.
+- **`keyring`** — the key is stored in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) via the `keyring` library.
+
+```json
+{
+  "spec_version": 1,
+  "default_profile": "default",
+  "encryption": {
+    "mode": "local_key"
+  }
+}
+```
+
+### Sensitive fields
+
+The following fields are always encrypted at rest:
+
+- `access_token`
+- `refresh_token`
+- `api_key`
+- `client_secret`
+- ID tokens, when stored
+- Provider-issued secrets
+
+`client_id` is not sensitive and is stored in plaintext.
+
+### Wire format
+
+Each encrypted value is stored as a compact dot-separated string:
+
+```text
+base64(nonce) . base64(ciphertext || tag)
+```
+
+For example, a sample stored ciphertext looks like:
+
+```text
+8Tn9Cw7yL2pQ4Vx0.4FzM3KDGbR1X...UC7qE9wA
+```
+
+This is the format `LocalFileCrypto.encrypt` and `KeyringCrypto.encrypt` produce in `src/authsome/vault/crypto.py`.
+
+<Note>
+  The portable spec ([`docs/specs/authsome-v1.md` §11.4](https://github.com/manojbajaj95/authsome/blob/main/docs/specs/authsome-v1.md)) defines a richer JSON envelope (`{enc, alg, kid, nonce, ciphertext, tag}`) as the cross-language interop target. The current Python implementation uses the compact format above; a future migration may switch to the JSON envelope when a second-language port lands.
+</Note>
+
+## The three states
+
+Every provider in a profile is always in exactly one of three states. The state is derived at runtime from what is stored — it is not a persisted field.
+
+| State | Meaning |
+|------|---------|
+| `available` | The provider definition exists. No credentials are stored for this profile. |
+| `configured` | OAuth2 client credentials are saved for this profile. The user has not yet logged in. API-key providers skip this state. |
+| `connected` | A valid connection record exists with an access token or API key. |
+
+```text
+available → configured   authsome login (collects OAuth client creds)
+configured → connected   authsome login (completes auth flow)
+available → connected    authsome login (api_key providers)
+connected → available    authsome revoke or authsome remove
+```
+
+If a provider is already `connected`, `authsome login <provider>` exits with an error. Pass `--force` to overwrite an existing connection.
+
+## Locking
+
+Writes acquire an advisory `fcntl.flock` on the per-profile `lock` file. Multiple authsome processes can read concurrently but serialize writes within the same profile. Locks across profiles are independent.
+
+## Connection record example
+
+A connected GitHub OAuth2 connection on disk looks like this (with sensitive fields encrypted):
+
+```json
+{
+  "schema_version": 1,
+  "provider": "github",
+  "profile": "default",
+  "connection_name": "default",
+  "auth_type": "oauth2",
+  "status": "connected",
+  "scopes": ["repo", "read:user"],
+  "access_token": {
+    "enc": 1,
+    "alg": "AES-256-GCM",
+    "kid": "local",
+    "nonce": "...",
+    "ciphertext": "...",
+    "tag": "..."
+  },
+  "refresh_token": { "enc": 1, "alg": "AES-256-GCM", "...": "..." },
+  "token_type": "Bearer",
+  "expires_at": "2026-05-01T15:40:22Z",
+  "obtained_at": "2026-04-30T14:40:22Z",
+  "account": { "id": "12345", "label": "manojbajaj95" },
+  "metadata": {}
+}
+```
+
+## Trust boundary
+
+Authsome assumes the local machine and user account are trusted relative to remote services. Encryption at rest protects against offline file access (a stolen disk image or an unauthorized user reading your home directory). It does not protect against a compromised running process.
+
+For runtime headers on the wire, see [Proxy injection](/concepts/proxy-injection).

authsome-0.2.2rc35/docs/site/concepts/provider-registry.mdx

@@ -0,0 +1,130 @@
+---
+title: "Provider registry"
+description: "How authsome resolves provider definitions from bundled JSON, user overrides, and registered custom providers."
+---
+
+A provider is an external service authsome can authenticate against — `github`, `google`, `openai`, and so on. Each provider is described by a JSON definition that tells authsome which authentication flow to run, where the OAuth endpoints live, and how to inject credentials into outbound requests.
+
+The provider registry is the system that resolves a provider name to its definition.
+
+## Resolution order
+
+When authsome looks up a provider by name, it checks two sources in this order:
+
+1. **User overrides** at `~/.authsome/providers/<name>.json`. These always win.
+2. **Bundled providers** shipped inside the `authsome` package (`src/authsome/auth/bundled_providers/`).
+
+This means you can override any bundled provider — for example, to point GitHub at a GitHub Enterprise instance, or to add custom scopes — by dropping a JSON file with the same name into `~/.authsome/providers/`.
+
+## Provider sources
+
+`authsome list` shows whether each provider came from the bundled set or from a user-registered file.
+
+```text
+$ authsome list
+Providers: 35 total, 2 connected
+
+Provider                     Source    Auth      Connection  Status
+GitHub [github]              bundled   oauth2    default     connected
+OpenAI [openai]              bundled   api_key   default     connected
+Acme CRM [acmecrm]           custom    oauth2    -           not_connected
+```
+
+The `--json` output exposes the same split as `bundled` and `custom` arrays.
+
+## What a provider definition contains
+
+Every provider definition declares:
+
+- An identity (`name`, `display_name`).
+- An auth type (`oauth2` or `api_key`) and a default flow (`pkce`, `device_code`, `dcr_pkce`, or `api_key`).
+- A flow-specific config block (`oauth` or `api_key`).
+- An optional `host_url` for proxy routing.
+- An optional `export.env` map describing which environment variables hold which credential fields.
+
+A minimal OAuth2 provider:
+
+```json
+{
+  "schema_version": 1,
+  "name": "github",
+  "display_name": "GitHub",
+  "auth_type": "oauth2",
+  "flow": "pkce",
+  "oauth": {
+    "authorization_url": "https://github.com/login/oauth/authorize",
+    "token_url": "https://github.com/login/oauth/access_token",
+    "scopes": ["repo", "read:user"],
+    "pkce": true,
+    "supports_device_flow": true,
+    "supports_dcr": false
+  },
+  "host_url": "api.github.com",
+  "export": {
+    "env": { "access_token": "GITHUB_ACCESS_TOKEN" }
+  }
+}
+```
+
+A minimal API-key provider:
+
+```json
+{
+  "schema_version": 1,
+  "name": "openai",
+  "display_name": "OpenAI",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer"
+  },
+  "host_url": "api.openai.com",
+  "export": {
+    "env": { "api_key": "OPENAI_API_KEY" }
+  }
+}
+```
+
+For the full schema with every field, see the [Provider schema reference](/reference/provider-schema).
+
+## Bundled providers do not imply bundled credentials
+
+A bundled provider definition only describes how to talk to a service. It does not include OAuth client credentials. The first time you log in to an OAuth2 provider, authsome collects your `client_id` and `client_secret` through a secure browser bridge and stores them encrypted in your profile.
+
+For services that support Dynamic Client Registration (DCR), the `dcr_pkce` flow registers a fresh OAuth client automatically — no `client_id` collection needed.
+
+## Multi-tenant and self-hosted providers
+
+For services where the base URL varies per deployment (GitHub Enterprise, Okta, GitLab self-managed), the provider definition uses `oauth.base_url` as a default and `{base_url}` as a placeholder in URL fields:
+
+```json
+{
+  "oauth": {
+    "base_url": "https://github.com",
+    "authorization_url": "{base_url}/login/oauth/authorize",
+    "token_url": "{base_url}/login/oauth/access_token"
+  }
+}
+```
+
+During `authsome login`, the user is prompted for the base URL with the JSON value as the default. A custom base URL is saved to the profile and used for all future token refreshes on that connection.
+
+## Adding your own providers
+
+Two ways:
+
+1. **Drop a file at `~/.authsome/providers/<name>.json`.** Authsome picks it up on the next CLI invocation.
+2. **Register through the CLI.** `authsome register ./acmecrm.json` validates the JSON, copies it into `~/.authsome/providers/`, and confirms the new provider appears in `authsome list`.
+
+See [Custom providers](/guides/custom-providers) for a full walkthrough.
+
+## Override a bundled provider
+
+To override a bundled provider — for example, to add a scope to GitHub — copy the bundled JSON, edit it, and place it under `~/.authsome/providers/github.json`. Authsome resolves your file first.
+
+```bash
+authsome inspect github > ~/.authsome/providers/github.json
+# edit the file
+authsome list   # source now shows "custom" for github
+```