fix(docs): align README, plugin, and docs with source-of-truth#272
Open
zriyansh wants to merge 1 commit into
Open
fix(docs): align README, plugin, and docs with source-of-truth#272zriyansh wants to merge 1 commit into
zriyansh wants to merge 1 commit into
Conversation
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 agentrhq#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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aligns documentation with what the source actually does. All claims verified against
agentrhq/authsomemainat3929b86before editing.Verified findings that drove the edits
Provider count.
src/authsome/auth/bundled_providers/has 45 JSONs: 14 OAuth2 + 31 API key. Notion ships two entries (notion+notion_dcr); Klaviyo ships two (klaviyo+klaviyo-oauth). The README and the plugin manifest said "44 / 13 OAuth"; corrected.Master key path.
paths.py:get_server_home() → .authsome/server.vault/crypto.pydocstring: "master key stored in ~/.authsome/server/master.key". Three doc pages used the top-level path; corrected.Architecture layer status.
src/authsome/hasidentity/(Ed25519 keys,did:key, PoP JWT) andaudit/modules. The architecture page's Note saying "the alpha focuses on Vault and Auth" was straightforwardly wrong. Replaced with a status table reflecting reality. Onlypolicy/is genuinely planned.Hosted daemon cross-reference.
AUTHSOME_DAEMON_URLandAUTHSOME_SERVER_BASE_URLship per the 0.2.4 changelog, but the threat model classifies hosted daemons as "Caveat (VPN only)" for private and "No" for public. Cross-reference added so adopters see the constraint at the feature announcement.Files
README.md—44 → 45,13 OAuth → 14 OAuth,run python → run -- python,authsome.agentr.dev → authsome.ai(consistent with fix(docs): repoint canonical to authsome.ai and drop dead links #271)..claude-plugin/marketplace.json— same provider-count correction.docs/site/security/threat-model.mdx— data-at-rest table and offline-disk paragraph.docs/site/security/encryption.mdx—local_keybackend description.docs/site/troubleshooting/doctor.mdx— both FAIL accordions and thechmodremediation. Also routes users toauthsome initinstead of relying on side-effect-on-first-CLI-run.docs/site/concepts/credential-storage.mdx—local_keybackend description.docs/site/concepts/architecture.mdx— per-layer status table replaces the stale Note. Also updates the Vault paragraph to reference~/.authsome/server/kv_store/.docs/site/changelog.mdx— hosted daemon cross-reference.Out of scope (tracked for follow-up PRs)
credential-storage.mdxandprofiles-vs-connections.mdxdisplayprofiles/<name>/store.dbas a top-level folder, which conflicts with the canonicalserver/kv_store/layout infile-layout.mdx. The whole "profiles as folder" vs "profiles as key prefix" framing needs a dedicated rewrite.authsome-web/, separate repo.Audit claims that turned out to be wrong
--forceis documented in the CLI reference underlogin(line 74) andregister(line 228/231). No fix needed.whoamiside effect is universal, not specific. ANY first CLI command triggers home-dir init;authsome initalready exists as the explicit form.Test plan
/docs/reference/bundled-providers.chmod 0600 ~/.authsome/server/master.key.