Token chain: add ~/.adom/session.json as the standard ambient fallback (platform-neutral; WSL2 /var/run precedent; unblocks Adom Anywhere direct calls)

Overview Files Skills Discover Packages Releases Dependencies Issues5 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 2mo ago ·closed by Colby Knox

Ask: add ~/.adom/session.json (key session_token) to the token resolution chain as a last-resort ambient fallback, on every platform.

Proposed chain: ADOM_WIKI_TOKEN env, then /var/run/adom/api-key, then the CLI's own stored token (auth token), then NEW: ~/.adom/session.json -> session_token. Explicit sources keep beating the ambient one; nothing existing changes behavior.

Why this location, and why it is NOT a Windows-specific ask even though a Windows use case surfaced it:

Precedent on Linux already exists. Hydrogen's WSL2 container hit real trouble because /var/run/adom/api-key lives in a tmp filesystem that disappears across restarts, and the fix direction chosen then was "an adom CLI that needs auth should look in standard persistent places." ~/.adom/ is that standard place: it is the Adom state dir on every platform (containers, the ah WSL2 workspace, and Windows PCs alike), and session.json is written there by the platform sign-in (Adom Bridge writes it on Windows; the same file exists in ah workspaces). One dirs::home_dir().join(".adom/session.json") read, zero platform-conditional code.
The motivating case: Adom Anywhere (Adom Bridge 2.0.21+) makes a local Claude Desktop / Codex on a Windows PC a first-class wiki author. The Bridge installer puts adom-wiki.exe on PATH and the user has already signed in to Adom Bridge (session.json exists), but a DIRECT adom-wiki call still 401s because nothing in the chain looks there. Today we bridge the gap by proxying through adom-bridge-cli wiki_exec (ab injects ADOM_WIKI_TOKEN from session.json), which works but means bare adom-wiki is broken out of the box on exactly the machines we are now promoting it on.
Freshness for free. session.json is read per invocation, so when the platform session rotates, the CLI keeps working with no re-auth step; a copied token in the CLI's own config goes stale instead. This also makes the stubbed auth login browser flow unnecessary on any machine with an Adom sign-in already present: the platform sign-in becomes the CLI's sign-in.
The wiki already accepts this token type. Adom Bridge authenticates its own wiki fetches with the session.json token as a Bearer today (private-page resolution, hero fetches), so no server change is involved.

One consideration to preserve: the env var must keep absolute precedence, since it is the documented escape hatch for the disabled-session-token recovery flow (the galliaApril ACL incident).

If accepted, the same convention is worth adopting across the other adom CLIs that need auth (adom-cli has the same fresh-Windows gap, and today supports no env token at all), so that "signed in to Adom on this machine" means every Adom CLI just works. Happy to test a build on both a Windows box and an ah workspace the day it lands.

2 Replies

Colby Knox · 2mo ago

Shipped in adom-wiki-cli 1.4.0, live on the wiki (all 5 platforms through the release gate).

Chain, first match wins: ADOM_WIKI_TOKEN, ADOMPKG_TOKEN, stored config token, /var/run/adom/api-key, ~/.adom/session.json session_token. Exactly your proposal with one deliberate ordering call: the container api-key file sits AFTER the stored config token, not before it, because it is an ambient source too and your own principle (explicit beats ambient) should apply to it; env keeps absolute precedence per the recovery-flow requirement, which also means env now beats a stored token (previously config won; that was the same trap class as the registry_url pin we fixed in 1.1.0, so the flip is on purpose and in the changelog).

Details as asked: one dirs::home_dir() read, zero platform conditionals; read fresh per invocation so rotation never strands the CLI; tolerant parse (any other fields in session.json ignored; empty or junk falls through); empty values fall through at EVERY link, so ADOM_WIKI_TOKEN= does not shadow the chain. doctor and auth token report the active source, including the new ambient:~/.adom/session.json. SKILL.md documents the chain.

Verified live on this container: env-first confirmed, container leg unchanged, and with /var/run/adom/api-key masked (proot bind), whoami authenticated through session.json alone.

adom-cli got the same convention today (its #3): ADOM_API_TOKEN kept, ADOM_API_KEY accepted as the alias, same session.json tail, shipped as 0.5.14 in wiki package adom/adom-cli 4.1.2. Your Windows box and ah workspace tests are welcome on both; the bare-exe-just-works behavior you described is exactly what should now happen wherever Adom Bridge has written session.json.

John Lauer · 2mo ago

Follow-up: verified adom-wiki 1.4.1 ambient auth natively on a Windows PC (not just the container). Fresh box, no ADOM_WIKI_TOKEN, no stored config token: adom-wiki auth token reports token_source: ambient:~/.adom/session.json and whoami authenticates as the signed-in user. So the "signed in to Adom on the machine means the CLI just works" promise holds on Windows too.

Shipping in ab 2.0.25: the installer bundles adom-wiki 1.4.1, and because ambient auth works, a local Claude Desktop / Codex agent can run adom-wiki directly (not only through ab's wiki_exec token injection). Nothing needed from you; just confirming the Windows leg is good.