Enables single-command self-deployment of the authsome daemon in a
container without requiring Python or uv on the host.
- Multi-stage Dockerfile: ui-builder (Node 24/pnpm) → py-builder (uv
wheel) → slim Python 3.13 runtime, non-root authsome user
- docker-compose.yml with named volume and restart: unless-stopped
- .dockerignore to keep the build context minimal
- docs/guides/self-hosting.md covering quick-start, env vars, volume
backup/restore, TLS with Caddy, and local builds
- .github/workflows/docker.yml CI job that builds the image on every PR
- README.md self-hosting quick-start section
Closes#366
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove references to five pages that do not exist:
reference/provider-schema, reference/file-layout,
concepts/profiles-vs-connections, security/hosted-deployment,
guides/profiles.
Strategy: strip the links/sentences from the 59 source files rather than
creating stub pages. Card blocks pointing to missing pages are removed;
inline sentence references are removed or reworded so the surrounding
prose stays coherent.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Delete the server-rendered dashboard pages, remove the static asset mount, and route the Next dashboard provider login form through the browser-session auth path.
The guide had drifted well beyond the deployment-flow change:
- Commands moved under the `provider` and `connections` groups
(`provider list`, `provider inspect`, `provider register|remove|revoke`,
`connections inspect`, `connections set-default`). Update every invocation.
- Remove the documented `get`, `export`, `--show-secret`, and `--json`
commands/flags — none exist. `connections inspect` is always redacted
and there is no human-table mode; output is always JSON (`{"v": 1, ...}`).
- Add sections for `scan`, `profile`, and `daemon restart`/`logs`.
- Note admin-only operations (register/revoke) and JSON-shaped expected
output throughout; fix the `daemon status` health block (no `mode`).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: b68c1ae5d66c
The first protected command now registers the identity and blocks on a
browser email+password registration + claim (first account = admin),
matching the single deployment flow. Also drop the removed `mode` field
from the daemon health block.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: 68b4ca3c1fc0
The daemon branched on AUTHSOME_DEPLOYMENT_MODE and ran two parallel
implementations of nearly every ownership concept. "Local and hosted
behave the same" was asserted in prose (ADR 0006) but never enforced in
code, so the paths were free to drift, and the synthetic local principal
let a second local identity silently inherit the admin principal.
Collapse to one flow, identical for every deployment: authsome init
registers an identity and gets back a browser claim URL; the user
registers email+password (first principal becomes admin); that principal
confirms the claim; PoP calls are then authorized.
- Remove AUTHSOME_DEPLOYMENT_MODE, get_deployment_mode(),
LOCAL_PRINCIPAL_EMAIL, the Local*/Hosted* resolver and bootstrap
classes, and the AuthService(deployment_mode=...) parameter.
- OwnershipResolver and IdentityBootstrapService become single concrete
classes (the former hosted, claim-based implementations).
- Admin gating is purely role-based: non-admin principals are blocked in
every deployment (previously implicitly allowed in local mode).
- The server UI always requires a hosted browser session; remove the
vestigial HealthResponse.mode field.
- CLI ensure_identity_ready was already mode-agnostic; it now prints the
claim URL to stderr for headless use.
Add ADR 0007 recording the decision; amend ADR 0006 and CONTEXT.md.
BREAKING CHANGE: 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.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: d31cf246f6f2
Login sections (§2–4) now include explicit human action steps — what
to open in the browser, what credentials to enter, and how to confirm
completion. Proxy section (§9) simplified to a single GitHub whoami
call through the proxy. Daemon note updated to reflect the orphaned-
process fix.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: e51d7e04524d
Two bugs found during manual testing:
- `AuthsomeError.__str__` already prepends the class name, but
`app.py` was passing `str(exc)` as the `message` field in error
responses. The client then reconstructed the exception with that
string as its args[0], causing `str()` to prepend the class name a
second time (e.g. "ProviderNotFoundError: ProviderNotFoundError: …").
Fixed by using `Exception.__str__(exc)` so the server sends the raw
message without the class-name prefix.
- `daemon stop` returned a no-op message when no PID file existed,
leaving an orphaned daemon (e.g. after `rm -rf ~/.authsome`) running
on port 7998. Added `_find_pid_by_port` as a fallback: if there is
no PID record but a process is listening on the daemon port, it is
terminated through the normal SIGTERM→SIGKILL path.
Also updates the manual-testing guide to reflect the secure local
browser bridge used by all login flows.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: 37d02f2f4c99
Resolved three conflict regions in favour of docs/update-architecture-language,
which reflects the current v4 design (PrincipalId, IdentityClaimRecord,
vault-scoped connections). Also removed the stale "Principals & Ownership"
section whose terms (PrincipalHandle, Claim) were superseded and contradicted
the resolved Identity & Authentication definitions.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: 62b5aef9947b
- Add ADR-0003: proxy unmatched requests pass through in local mode
- Add docs/agents/ guidance files (domain, issue-tracker, triage-labels)
- Add "Composition over inheritance" principle to AGENTS.md and CONTRIBUTING.md
- Fix AGENTS.md Architecture section: remove "Identity = Profile", update
AuthService constructor (vault_id/principal_id), fix storage key patterns
to vault:<vault_id>:..., add five-registry model description
- Update UBIQUITOUS_LANGUAGE.md: retire Profile term, add Principal, PrincipalId,
VaultId, VaultHandle, IdentityClaimRecord, ClaimStatus, PrincipalVaultBindingRecord,
ActiveIdentity, StorageSubstrate, StorageNamespace, SecretSource, Repository;
update Relationships and Example dialogue to reflect Principal/Vault model
- Add docs/refactor.md: storage composition refactor plan (Phases 1-9); mark
Principal/Vault/Claim architecture as implemented, keep open storage phases
Note: the feature/principal-vault-identity-design branch adds
docs/adr/0003-principal-owned-vault.md — that file must be renamed to
0004-principal-owned-vault.md before that PR merges to avoid collision with
the new ADR-0003 added here.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: c7b941617a23
- Add ClaimStatus enum (PENDING/ACCEPTED/REJECTED) to IdentityClaimRecord
with accept_claim() and reject_claim() on IdentityClaimRegistry
- HostedOwnershipResolver.resolve() now gates vault access on ACCEPTED;
PENDING raises 403, REJECTED raises 403 with distinct message
- ensure_claimed_identity() auto-accepts on UI form submission — the form
IS the approval act in this release; PENDING is transit state only
- Remove AuthService vault_id fallback (vault_id or identity); _coll now
raises ValueError if vault_id is None, making missing wiring explicit
- /ready endpoint resolves vault_id via ownership_resolver instead of
constructing AuthService with the identity handle as a stopgap
- create_auth_service() requires explicit vault_id parameter
- Rewrite ADR 0003 and update UBIQUITOUS_LANGUAGE.md to reflect opaque
VaultId design (single segment, not principal_handle/vault_handle)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: 8f56337e3615
Extends ADR 0003 with the full vault design: Principal owns one or more
named Vaults (VaultHandle), storage keys move to
vault:<principal>:<vault_handle>:..., AuthService gains a vault_handle
argument, and the domain model is split across three registries
(principals.json, identities.json, vaults.json). One vault per principal
for now; structure supports multiple without a future breaking change.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: fd3f66ffdce4
Path 2 now offers two tracks: GitHub + OpenAI for users who want a
runnable demo, and Notion via MCP for the zero-setup case (DCR
auto-registers a client, no OAuth app needed). Each track is a tab.
The GitHub + OpenAI track ends in a minimal agent script that stars
agentrhq/authsome and asks gpt-5 to write a one-line celebration.
It uses only the standard library so there's nothing to pip install.
The script lives inside an Accordion so it doesn't dominate the page
for readers who only want to see how the login flow works.
Also clarifies what the OAuth bridge stores versus the access token
GitHub returns, since that confused readers who thought they'd need
a separate PAT to make API calls.
New users hit `authsome login github` in the quickstart without
knowing GitHub requires them to register an OAuth app first. The
existing Tip mentioned client_id and client_secret were needed but
not how to obtain them, so first-timers got stuck.
The quickstart's CLI-driven path now has a "Register the GitHub
OAuth app" section before the login steps. It covers the developer
settings page, the form fields (Authorization callback URL must be
exact; Device Flow on), and a warning to save the Client Secret
before navigating away (GitHub shows it once). The login steps
were reordered into four: run login, paste credentials in the
local bridge, approve on GitHub, confirm.
The same walkthrough is mirrored in integrations/oauth/github.mdx
Prerequisites so the per-provider page stays the canonical
reference. Both pages share a single screenshot of the local bridge
form at /images/login-github-authsome.png.
The credential-storage and profiles-vs-connections pages described
profiles as separate SQLite files under ~/.authsome/profiles/<name>/
with per-profile flock locking. The actual implementation moved to
a single DiskStore at ~/.authsome/server/kv_store/ with profile
names used as key prefixes, and the daemon is the only writer.
The storage layout trees on both pages drop the profiles/ folder
and now reflect the canonical layout in reference/file-layout.mdx.
The 'Locking' section is replaced with a Concurrency section that
explains the daemon as single writer; the per-profile flock story
is gone. The 'at a glance' table now describes profiles as key
prefixes in a shared store. The OAuth client-credentials row moves
from per-profile to server-scoped (server:<provider>:client),
matching how the daemon actually stores them. 'Which one is active'
now says explicitly that a profile is an identity handle scoped
through the PoP token.
PR #281 is the upstream rename of "profile" to "principal"; this
PR keeps the existing terminology to land cleanly ahead of that
bigger naming change.
The skill rewrite (PR #284) and README update standardized on
"authsome <command>" (assumes "uv tool install authsome") and on
agent-driven login flows. The docs site still spoke "uvx authsome"
everywhere and didn't surface the auth-error decision tree the
skill teaches. This brings the docs in line.
Four kinds of change in one PR.
1. CLI prefix sweep ("uvx authsome" to "authsome").
Mechanical find/replace across docs/site/ excluding installation.mdx.
812 occurrences updated. installation.mdx keeps the literal "uvx"
references because they explain the one-off run path.
2. installation.mdx rewrite.
- "uv (recommended)" tab leads, with "uv tool install authsome".
- pip second.
- uvx demoted to "one-off, no install" with @latest pattern shown.
- From source unchanged.
- A Note at the top declares: every command in the docs is the
installed form; uvx users prefix with "uvx authsome@latest".
- All subsequent code blocks updated to bare "authsome".
3. New troubleshooting/auth-errors.mdx page.
Captures the decision tree the skill teaches: 401 -> revoke +
re-login; 403 -> "authsome login --scopes" (not re-registering);
wrong client creds -> "authsome remove" then re-login. Registered
in docs.json under Troubleshooting.
4. quickstart.mdx pivoted to two paths + help reflex.
Path 1: agent-driven. Install the skill, ask the agent to do a
task that needs an external service. The agent runs login itself.
Path 2: CLI-driven. The existing manual walkthrough, preserved.
Adds a Tip about reading "authsome --help" and "authsome <cmd>
--help" before guessing flags.
5. Agent-mode note on the four skill-based integration pages.
claude-code, codex, cursor, opencode each get a one-paragraph Note
clarifying that the agent runs login, opens the browser on the
user's machine for OAuth, and that users should not paste keys
into prompts or pre-run login commands. The four SDK-style
integration pages (langchain, llamaindex, openai-agents-sdk,
anthropic-sdk) are unchanged because their pattern is
developer-driven, not agent-driven.
Verified clean: no "uvx authsome" outside installation.mdx,
docs.json valid, no em-dashes introduced.
Two classes of bugs corrected, both verified against main at 69a0cb9.
Skill (skills/authsome/references/adding-provider.md):
- OAuth redirect URL was http://localhost:7999/callback. Source truth
is http://127.0.0.1:7998/auth/callback/oauth (server/urls.py:8-9
and the matching user-facing doc in custom-providers.mdx). Agents
following the skill would tell users to register OAuth apps with
a redirect URI that does not match what authsome actually serves,
causing every PKCE login to fail.
- Step numbering had two "3." entries and no "4."; renumbered.
- Provider registration link pointed at the stale
raw.githubusercontent.com/manojbajaj95/authsome fork; repointed
to agentrhq.
Stale repo owner in actively-rendered surfaces:
- CONTRIBUTING.md: git clone URL.
- docs/site/README.md: link to the repo.
- docs/site/reference/bundled-providers.mdx: "open a pull request
against" link in the upstream contribution section.
- docs/site/concepts/credential-storage.mdx: replaced
"manojbajaj95" example label with "octocat" so the sample
connection record reads as a generic GitHub username.
- src/authsome/ui/templates/_layout.html: dashboard sidebar
"Support" link and topbar "GitHub" button.
- src/authsome/ui/templates/overview.html: dashboard "Contact Us"
button on the overview page.
Out of scope:
- pyproject.toml author attribution stays as Manoj Bajaj; that is
the actual maintainer's name, not a stale fork reference.
- CHANGELOG.md has ~100 manojbajaj95 commit URLs but release-please
regenerates it; manual edits would be overwritten on next release.
Adds the Principal-owned vault design to the domain language:
- CONTEXT.md (new): canonical glossary for Principal, PrincipalHandle,
PrincipalRegistry, Claim, ClaimStatus, and the on-behalf-of model
- docs/adr/0003-principal-owned-vault.md: records the trade-off between
identity-scoped and principal-scoped vault namespaces, and why
profile/email were rejected as vault keys
- docs/UBIQUITOUS_LANGUAGE.md: adds Principal/Claim terms, retires Profile
(breaking change in v0.4), updates Relationships and example dialogue
Vault keys move from identity:<handle>:... to principal:<handle>:...
AuthService constructor gains `principal` param alongside `identity`.
All accepted agents under a Principal share its connections.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: ccd880046890
Per-agent access control and firewall rules were not shipped — move back
to Coming next. Available today now reflects only changelog-confirmed
features. Add multi-user support to Coming next.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: cd99c854018c
- doctor: fix spec_version always showing FAIL — server returned the version
number "3" instead of "ok", so the CLI check `val == "ok"` always failed
on healthy installs
- register --force: was not skipping the confirmation prompt; --force now
implies --yes so a single flag covers both server-side overwrite and client
prompt bypass (matching gh/fly/docker convention)
- --quiet: was silencing ALL output including primary data rows; add emit()
to ContextObj (never quiet-suppressed) and use it for list table rows and
doctor check lines — informational headers remain quiet-suppressible
- log: switch from raw loguru client log to structured server audit log
(NDJSON); display as human-readable table with timestamp/event/provider/
status columns; --raw flag retains access to the client debug log
- add CLI design review report at docs/internal/cli-design-review.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: e28262984429
The earlier audit surfaced contradictions between docs and code that
were verified against agentrhq/authsome main at 3929b86. This fixes
the verified gaps; the rest is tracked for follow-up PRs.
Provider count: source has 45 JSONs (14 OAuth2 + 31 API key) in
src/authsome/auth/bundled_providers/. Notion ships as two entries
(notion + notion_dcr) and Klaviyo as two (klaviyo + klaviyo-oauth).
- README.md: 44 -> 45 and 13 OAuth -> 14 OAuth.
- .claude-plugin/marketplace.json: same correction in the plugin
description.
Master key path: paths.py routes the server master key to
~/.authsome/server/master.key, confirmed by vault/crypto.py and
health.py. Three doc pages had the wrong (top-level) path.
- security/threat-model.mdx: data-at-rest table and offline-disk
paragraph.
- security/encryption.mdx: local_key backend description.
- troubleshooting/doctor.mdx: both accordion FAIL examples and the
chmod remediation. Also points users at "authsome init" instead of
the side-effect-on-first-run workaround.
- concepts/credential-storage.mdx: local_key backend description.
- concepts/architecture.mdx: vault wrapping description.
Architecture layer status: src/authsome/ ships identity/ (Ed25519
keys, did:key DIDs, PoP JWT), audit/ (structured JSON events), in
addition to vault/ and auth/. Only policy/ is still planned.
- concepts/architecture.mdx: replace the "alpha focuses on Vault and
Auth" Note with a per-layer status table reflecting reality. Also
updates the SQLite backend description to the kv_store path
(~/.authsome/server/kv_store/) consistent with the canonical
filesystem layout.
Hosted daemon cross-reference: changelog 0.2.4 ships
AUTHSOME_DAEMON_URL and AUTHSOME_SERVER_BASE_URL, but the threat
model classifies hosted daemons as "Caveat (VPN only)" for private
and "No" for public. Cross-reference added to the changelog entry so
adopters see the constraint at the point of the feature
announcement.
Domain: README links updated from authsome.agentr.dev to
authsome.ai for consistency with the docs canonical URL fixed in
#271.
Out of scope (separate follow-ups):
- Profile-as-folder trees in credential-storage.mdx and
profiles-vs-connections.mdx still show profiles/<name>/store.db,
which conflicts with the new server/kv_store/ architecture. Needs
a dedicated rewrite of those pages.
- mitmproxy CA install procedure (10 pages mention it; none have an
install command).
- Anthropic bundling.
- Marketing site sitemap on authsome-web.
Mintlify generates the sitemap from seo.metatags.canonical, and the
canonical was still pointing at authsome.agentr.dev. Every <loc> in
https://authsome.ai/docs/sitemap.xml carried the old domain even
though the docs are now hosted at authsome.ai.
Domain rename:
- docs.json canonical to https://authsome.ai/docs.
- docs.json footer "Home" link to https://authsome.ai.
- custom-providers.mdx schema URL to authsome.ai.
Security disclosure:
- Drop the security@agentr.dev email path from disclosure.mdx and
route all reports through GitHub's private security advisory flow.
The email was the only contact path that needed mailbox
maintenance; GitHub advisories give us the same private channel
without it.
Dead links (target files deleted upstream in 019bdd1 and ec06181):
- roadmap.mdx: drop both references to docs/authsome-design.md
(moved to docs/internal/, not public-facing).
- daemon-trust-boundary.mdx: replace authsome-design.md reference
with a link to the public /roadmap page.
- encryption.mdx: drop docs/specs/authsome-v1.md reference; keep
the prose describing the future portable spec.
- credential-storage.mdx: same fix as encryption.mdx, also drops
one stale manojbajaj95 owner reference incidentally.
Navbar previously rendered "Authsome" as plain text with no logo or
favicon. This adds the Authsome `#` mark + wordmark as SVG logos (light
and dark variants), a favicon, and a Discord community link. The PyPI
link gets a Python brand icon, and Discord moves into footer socials
alongside GitHub.
llms.txt drops out of the navbar — it already lives in the footer's
Docs column, and the navbar slot is more valuable for the community
link.
Profile is now a pure credential namespace scoped by the Identity handle,
not an independently managed entity. The two were always 1:1 but modelled
as separate concepts; this commit makes that explicit.
Key changes:
- Add `active_identity` to GlobalConfig; `ensure_local_identity` reads it
and errors hard if the configured handle is missing on disk (no silent
re-creation)
- `authsome init` writes `active_identity` to config after registration
- Collapse `registered: bool` + `registration_status: str` on
IdentityMetadata into a single `registered: bool`; add `mark_registered()`
- Remove vestigial `Identity` dataclass, `DEFAULT_IDENTITY`, `current()`
- Remove `name`, `description`, `owner_email` from IdentityMetadata (deferred
to hosted version)
- Remove `ProfileMetadata`, `ProfileNotFoundError`, `create_profile`,
`list_profiles`, `get_profile`, `set_default_profile`, `default_profile`
shim in save_config — profile is a side-effect of identity registration
- Add hard-error test for missing configured identity
- Update UBIQUITOUS_LANGUAGE.md, AGENTS.md architecture section, and
ADR 0002 to reflect current code (fix stale AuthsomeContext, AuthClient,
config.json path, ProfileMetadata references)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: 614885258a45
Make the daemon identity registry authoritative for protected PoP requests and remove implicit default-profile identity behavior.
Store daemon-owned state under server/ while keeping CLI signing identity files under identities/.
BREAKING CHANGE: Existing implicit default-profile installs must run authsome init again; profile:default credentials are not migrated.
Entire-Checkpoint: 557455816515
Manoj Bajaj