main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-adom-auth description: >- Adom sign-in inside Hydrogen on Linux: the login/logout auth intent flow, where the session token lives (~/.config/hydrogen-desktop/hydrogen-session.txt), and how the session feeds setup. Use when Adom login fails, the session token expired, the user wants to sign in or out of Adom, or clear the Adom session.

Hydrogen -- Authentication Reference

Auth Flow Overview

Hydrogen uses an auth intent flow (no email/password entry in the app). The backend creates a short-lived intent token on the Carbon API, opens the user's default browser to the Adom login page, and polls until the user completes sign-in in the browser.

Sequence

  1. Hydrogen calls invoke('auth_intent_start') -> backend POSTs to https://carbon.adom.inc/auth/intents with {"max_age": 7776000} (90-day session).
  2. Carbon returns {token, confirmation_code, expires_at, auth_url}.
  3. Hydrogen opens the browser to the auth_url Carbon returned, falling back to https://hydrogen.adom.inc/auth/intent?token={token} (singular intent, token as a query param — NOT /auth/intents/{token}). On Linux the browser opens through Hydrogen's browser launcher, which honours the Browser Picker's choice of browser and profile.
  4. Hydrogen displays the confirmation code on screen and shows a spinner.
  5. Frontend polls invoke('auth_intent_poll', {token}) every 2 seconds. Backend GETs https://carbon.adom.inc/auth/intents/{token}/status.
  6. When the user confirms in the browser, the response includes {state: "authenticated", session_token: "..."}.
  7. The backend saves the session token to Hydrogen's app-data directory on the host (the hydrogen-session.txt file) and a replay copy alongside it.
  8. Frontend redirects to the dashboard.

Source files

  • Login page: src/routes/auth/login/+page.svelte
  • Auth backend: src-tauri/crates/hydrogen-setup/src/app_glue.rs (auth_intent_start, auth_intent_poll) and src-tauri/crates/hydrogen-app/src/lib.rs (auth_proxy, check_replay_credentials, replay_adom_login).
  • Auth components: src/lib/components/auth/ (Header, Form, Footer, SubmitButton, Error, Success)
  • User API: src/lib/api/authenticated_user.ts

Session Token

Location: Hydrogen's app-data directory on the host (the hydrogen-session.txt file).

On Linux every auth file is in Hydrogen's state folder ~/.config/hydrogen-desktop/ on the host (not in the workspace):

File Purpose
hydrogen-session.txt The Adom session token. Read by the auth proxy; deleted on logout or a 401.
replay-session.txt Replay copy; lets the login page sign you back in without a browser ("Signing you in... Ns").
replay-claude-credentials.json Claude Code credentials kept across a virgin reset (see hydrogen-claude-auth).

From the workspace, the host's home is visible at /mnt/host/home/<user>/, but the supported way to get the token is the control API below.

A plain-text file containing the Adom session cookie value. Created by either:

  • The auth intent flow (on successful poll)
  • The auth proxy (when Carbon returns a set-cookie: session_token=... header)

The auth proxy (invoke('auth_proxy', ...)) reads this file and attaches it as a Cookie: session_token=... header on every request to carbon.adom.inc.

Token lifecycle

  • Created: on login (auth intent or browser set-cookie capture)
  • Refreshed: automatically when the auth proxy receives a new set-cookie
  • Cleared: on logout (auth_proxy({path: "/auth/clear-local"})) or on 401 response (backend auto-deletes the file)
  • Max age: 90 days (set at intent creation)

Reading the token programmatically

BASE="$(cat ~/.adom/hydrogen-control-url)"   # normally http://127.0.0.1:47084
curl -s "$BASE/auth-token"                    # the saved Adom session token
cat /var/run/adom/api-key                     # the same account's key, written into the workspace

Hydrogen writes /var/run/adom/api-key (mode 644) at every launch and once during setup's activate-editor step, after sign-in. adom-cli, adom-wiki and the editor use it.


Auth Proxy

The backend command auth_proxy is the gateway for all authenticated requests to the Adom Carbon API. It:

  1. Reads the session token from disk
  2. Attaches it as a cookie to the outgoing request
  3. Captures any set-cookie response and updates the saved token
  4. On 401, deletes the token and returns {expired: true}
  5. Supports a special path: "/auth/clear-local" to delete the token file

Base URL: https://carbon.adom.inc

// Example: get the current user
const result = await invoke('auth_proxy', {
  path: '/api/me',
  method: 'GET'
});
// result = { status: 200, data: { id: "...", name: "jlauer12", ... }, ok: true }

Credential Replay

On login page mount, Hydrogen checks for saved credentials before starting the full auth intent flow:

  1. invoke('check_replay_credentials') checks if replay files exist on disk.
  2. If the replay-session file exists (has_adom = true), the login page shows "Signing you in... Ns" and counts down.
  3. invoke('replay_adom_login') attempts to authenticate using the saved session token.
  4. If replay succeeds, the user is logged in without opening a browser.
  5. If replay fails, Hydrogen falls back to the normal auth intent flow.

This makes re-login after a virgin reset instant when the user chose to preserve the Adom session token.


Claude Credentials

Location: Hydrogen's app-data directory on the host (the replay-claude-credentials.json file).

Stores Claude Code credentials so they survive a virgin reset (see hydrogen-claude-auth).

Virgin reset options for auth

The virgin reset panel (Setup Panel -> Virgin Reset) has per-item toggles:

Toggle File What it clears
Adom session token hydrogen-session.txt Adom login. Next launch requires re-auth.
Claude credentials replay-claude-credentials.json Claude Code OAuth. Next bootstrap re-authenticates Claude.

These are independent -- you can wipe Claude creds without losing Adom login, or vice versa.

CSS selectors for virgin reset auth options

label.virgin-opt  -- each checkbox row
input[type="checkbox"]  -- the toggle (bind:checked to virginOpts.adom_token / virginOpts.claude_token)
.virgin-hint  -- shows filename (hydrogen-session.txt / replay-claude-credentials.json)
.vp-badge  -- status badge ("exists" / "clean")
.vp-exists  -- green badge (file exists)
.vp-clean  -- gray badge (file gone)

Profile Menu

Location: Top-right corner of the editor nav bar. Source: src/lib/components/editor/EditorNav.svelte (lines ~2403-2443)

Click the circular user avatar to open a dropdown with two sections.

Item Icon Action
Your profile mdi:account-circle-outline Navigates to /users/{username}
Your repositories mdi:folder-outline Navigates to /users/{username}/repositories
Your molecules mdi:atom Navigates to /users/{username}/molecules
Log out mdi:logout Confirms, then clears session + redirects to login

CRITICAL: Logout is ONLY in the profile menu (top-right avatar), NOT in the Adom menu (top-left logo). Do not look for logout in the wrong menu.

CSS selectors

Element Selector
Profile dropdown container .profile-dropdown-container
Avatar button .profile-dropdown-button
Avatar image .profile-dropdown-button img
Dropdown (open) .profile-dropdown-content.open
Menu items .profile-dropdown-content .dropdown-link
Menu item icons .dropdown-link span

Eval examples (/eval-in {target:"shell"})

// Open the profile menu
document.querySelector('.profile-dropdown-button')?.click();

// Click "Your profile"
var links = document.querySelectorAll('.profile-dropdown-content .dropdown-link');
if (links[0]) links[0].click();

// Click "Your repositories"
if (links[1]) links[1].click();

// Click "Your molecules"
if (links[2]) links[2].click();

// Click "Log out"
var logoutBtn = Array.from(document.querySelectorAll('.profile-dropdown-content .dropdown-link'))
  .find(function(e) { return e.textContent.includes('Log out'); });
if (logoutBtn) logoutBtn.click();
// Note: this triggers a confirm dialog. To auto-confirm, you need to handle the dialog.

// Read the current user's avatar URL
var avatar = document.querySelector('.profile-dropdown-button img');
avatar ? avatar.src : 'no avatar';

// Read the current username from the avatar alt text
avatar ? avatar.alt : 'unknown';

Logout Flow

  1. User clicks "Log out" in profile menu.
  2. showConfirm('Are you sure you want to log out?', 'Log Out') -- confirmation dialog.
  3. If confirmed (app mode):
    • invoke('auth_proxy', {path: '/auth/logout', method: 'DELETE'}) -- server-side logout
    • invoke('auth_proxy', {path: '/auth/clear-local', method: 'POST'}) -- deletes hydrogen-session.txt
    • Clears auth-related domain preferences from localStorage['hydrogen-url-routing-prefs']
  4. Redirects to /auth/login.

Login Page UI

Route: /auth/login

App mode (auth intent)

  • Adom logo + "Log in to Hydrogen" header
  • Confirmation code in a monospace box (.confirmation-code)
  • Spinner + "Waiting for you to sign in..."
  • "Open browser again" button (.retry-button)

Browser mode (email/password)

  • Standard form with email + password fields
  • "Log In" submit button
  • Footer with registration link

Auth intent CSS selectors

Element Selector
Container .intent-container
Confirmation code .confirmation-code
Spinner .spinner
Status message .intent-message
Hint text .intent-hint
Success message .intent-success
Error message .intent-error
Retry button .retry-button

Eval on the login page (/eval-in {target:"shell"})

// Check auth intent state
document.querySelector('.intent-message')?.textContent;
// -> "Waiting for you to sign in..." or "Authenticated! Redirecting..."

// Read the confirmation code
document.querySelector('.confirmation-code')?.textContent;

// Click retry
document.querySelector('.retry-button')?.click();

How Auth Affects Setup Steps

The setup/bootstrap process depends on a valid session token:

The activate-editor step waits for the Adom sign-in (the editor mounts only after login), then binds the workspace to this launch: environment, the api-key write-through and the relay. If the token is missing or expired, adom-cli in the workspace cannot authenticate: sign in again, then run setup again from the Adom menu > Setup Steps.


Control API Auth Endpoints

Method Path Description
GET /auth-token Read the saved Adom session token (same-origin callers only)
POST /claude-auth Start Claude Code OAuth (PKCE)
GET /oauth/callback Receives OAuth redirect (auto, do not call)
POST /start-oauth-proxy Spin up temp TCP listener for OAuth callback
POST/GET /auth/proxy Proxy request to Carbon API with session token

See the hydrogen-settings skill (API Explorer section) for the full endpoint reference.


Cross-references

  • hydrogen-claude-auth -- Claude Code sign-in, separate from Adom
  • hydrogen-profile-menu -- where login/logout live in the UI
  • hydrogen-settings -- API Explorer (auth endpoints tab)
  • hydrogen-networking -- how to reach the control API port
  • hydrogen-api -- the control API
  • hydrogen-key-values -- the account's cloud key-value store