@modelprofile.com/authswitch 8.1.0 → 9.0.0

package/readme.md

@@ -32,7 +32,11 @@ bindings, durable device-operation receipts, Codex enrollment records, and nativ
 owns OpenAI device login, targeted reauthentication, and proactive refresh for grants
 added through this API. Management snapshots expose separate account and login rows,
 including each login's purpose, owner, health, problem and available actions; neither
-snapshots nor events contain credentials.
+snapshots nor events contain credentials. A login that a native tool refreshes also names
+that tool -- `ownerTool` is `claude_code`, `codex` or `opencode`, and `null` exactly when no
+native tool holds it, because the authority refreshes it or nothing does. The authority
+names it rather than leaving a consumer to derive it from the purpose, which would be wrong
+as soon as two purposes share a tool or one tool gains a second purpose.
 
 ```ts
 import { randomUUID } from 'node:crypto';
@@ -49,10 +53,16 @@ const receipt = await client.getOperation(operation.id);
 ```
 
 Browser code can import the credential-free DTOs from
-`@modelprofile.com/authswitch/authority-contract`. A backend binds an account to a
-runtime incarnation by exact account ID, login ID and purpose, and keeps the returned
-capability private. Targeted reauthentication likewise requires the exact login; an
-account's presentation default never selects a grant for either action. Completed and
+`@modelprofile.com/authswitch/authority-contract`. The backend-only binding, access and release
+requests are named by `@modelprofile.com/authswitch/authority-runtime-contract`, and the one-time
+import's own DTOs by `@modelprofile.com/authswitch/authority-import-contract`; those capabilities must
+never reach a browser. Two of the three runtime requests are served on the runtime socket -- resolving
+access and releasing a binding -- while `authswitch.authority.bind` is served on the **management** socket
+by design: minting a capability is the act that authorizes a runtime, so only a trusted management caller
+may perform it, and a container that is given the runtime directory can use a binding it was handed but can
+never create one. A backend binds an account to a runtime incarnation by exact account ID, login ID and
+purpose, and keeps the returned capability private. Targeted reauthentication likewise requires the
+exact login; an account's presentation default never selects a grant for either action. Completed and
 interrupted operations remain discoverable through `getOperation()` and paged
 `listOperations()`. A completed receipt and its account/grant change commit together, so
 the receipt resolves a lost response or an event that arrives first. Add and reauthentication
@@ -76,6 +86,48 @@ the runtime and clears its durable run before internal revocation. Binding relea
 or changes ownership of the account grant. External-binding recovery after an owner crash remains
 a prerequisite for the full account-mutation cutover.
 
+Every route on either socket answers in one of three ways: a result, a **refusal**, or a fault. A refusal
+is an answer -- the daemon completed its check, nothing was left half-done, and its message says what the
+owner does instead -- so it crosses the wire marked, with the message verbatim beside
+`{ reason, code }`. A fault is anything the daemon did not decide: the transport replaces its text with
+`Internal server error`, and a caller must never present that as if it said what to do next. A malformed
+request is neither; it keeps its own text and carries no marker, because a caller's own bug is not an
+instruction for an owner.
+
+`asAuthSwitchRefusal(error)` from `@modelprofile.com/authswitch/authority-contract` is the one reader of
+that marker: it answers `{ code, instruction }` for a refusal and `null` for a fault. The code is the
+closed `TAuthSwitchRefusalCode` set, which is what a client branches on without reading the text:
+`authority_closing`, `not_found`, `account_changed`, `account_busy`, `login_unavailable`,
+`binding_unauthorized`, `native_owner_holds_login`, `claude_home_unregistered`, `claude_handoff_pending`,
+`claude_receipt_missing` and `import_refusal`, plus the two the legacy commands answer with on this side of
+the socket, `authority_holds_login` and `authority_unavailable` (see "The legacy fence" below). The
+instruction is authored for the owner and contains no path, credential or digest; only an importer refusal
+may name the process the owner has to stop. The set is producer-owned: a consumer branches on the codes it
+knows and keeps a default branch, which is what lets the authority name a new one without breaking it.
+
+The runtime's own answers are named the same way. `authswitch.authority.bind` refuses `login_unavailable`
+when the authority does not hold the login itself, and `authswitch.authority.resolveAccess` refuses
+`binding_unauthorized` for a capability that authorizes nothing -- missing, wrong, or superseded while the
+credential was being resolved. Those are one answer on purpose: an absent binding and a wrong capability are
+compared against the same zero hash, so nothing distinguishes them, and the repair is the same either way --
+bind again. A binding whose account has since been reauthorized reads `login_unavailable` instead, because
+binding again cannot help until that account holds a login again. A device sign-in or preuse operation this
+authority does not hold reads `not_found`, from whichever route met it. Two things stay unmarked faults on
+purpose. What the shared managed-access loop refuses is one: it serves a bound runtime and the
+credential-free usage reader alike, and those two repair differently. Binding an *account* this authority
+does not hold at all is the other: the storage layer throws `Account is not available for this runtime.`,
+which a socket caller reads as `Internal server error`, because naming it is a decision about which layer
+authors owner instructions rather than a wording fix.
+
+The import routes keep the marker they published in 8.1.0, `authswitch_import_refusal`, and
+`isAuthSwitchImportRefusal` from `@modelprofile.com/authswitch/authority-import-contract` is the same
+reader asking for the `import_refusal` code, so a consumer written against 8.1.0 keeps working and a
+client of this release still reads the payload a daemon of that release answers with. The distinction
+matters most for `import.submit`: a refusal there is a submit that decided -- it left nothing half-done,
+and the ledger row it wrote says where that source stands -- while an unmarked failure leaves the outcome
+unknown, and that source must then be read with `authswitch.authority.import.status` rather than
+submitted again.
+
 `AuthSwitchClient.subscribe(onSnapshot, onEvent, signal, { onStatus })` reports `current`
 after a fresh snapshot or verified heartbeat, `unavailable` on disconnect or resync, and
 `closed` on abort. Keep cached account actions disabled while status is not `current`.
@@ -167,6 +219,35 @@ If the daemon is unavailable before the first response, it fails with a fixed di
 stderr and leaves stdout empty. The older native-store commands documented below still coexist until the coordinated
 major-version migration and removal; these authority routes never use them.
 
+### The Claude native home
+
+The daemon serves Claude Code's own credential store, which stays the native store that Claude Code
+reads. `authswitch.authority.claude.switch`, `.handoff` and `.handoffs` on the management socket move
+that one home between two authority logins and report the journal of those moves, and
+`authswitch.authority.usage` answers for an Anthropic account from it. The home is
+`CLAUDE_CONFIG_DIR` or `~/.claude`, and the authority identifies it by the hash of the credential file
+Claude Code owns -- the same value the import publishes as that source's path hash, which is what lets a
+verified receipt adopt it.
+
+The daemon is wired for that home whether or not Claude Code is installed, so `doctor` reports
+`claudeNativeAuthority: configured` on any host; the `claudeHomes` page is what says whether a home has
+been adopted. Until a verified `claude_native` import has adopted one, every Claude route refuses. A
+`CLAUDE_CONFIG_DIR` that is not an absolute path is refused when the daemon starts, because the same
+variable also decides which file the import would read; it is never resolved against a working directory.
+
+A switch is only attempted when the host can prove Claude Code uses that native login: exactly the
+verified Claude Code release, a subscriber login in the store, no credential override in the
+environment, no managed or local settings selecting another auth source, and no scoped Claude session
+running. Anything else refuses and leaves both logins where they were. A move that reaches the home and
+then cannot complete that proof is quarantined with `problem: unsupported_effective_auth`, and the
+handoff's optional `proofFailure` names which condition failed -- `unsupported_release`, `subscription`,
+`override`, `settings`, `profile`, `profile_unreadable` or `running_session` -- so an owner is told what
+to change. It is absent whenever `problem` is anything else. The settings that proof reads are the ones
+the daemon may speak for: the user settings file of the resolved home and the managed settings directory.
+A project's `.claude/settings.json` is read from the working directory of each running Claude session,
+never from the daemon's own, which is its service unit's and selects nothing. While a login is in the
+native home, Claude Code is its only refresher; the authority takes it back by the same journaled handoff.
+
 ## The one-time account import
 
 The three `authority import` commands move the accounts that existed before the authority into it.
@@ -189,6 +270,12 @@ Each source is classified by who refreshes its login **after** the import.
   credential. It is verified by a provider read with the access token already in the store, which rotates
   nothing. Two refreshers on one rotating refresh token is the failure this avoids.
 
+A verified Claude projection also adopts the native home it came from, so the daemon may serve Claude
+switches for it. The receipt is what adopts it, and a home belongs to one login at a time: a second home
+for a login another one already holds -- a `.credentials.json` copied to another `CLAUDE_CONFIG_DIR` --
+and a home whose active login has since moved are both refused with the importer's own code, so the
+submit is known to have decided, the ledger row stays `verified` and no home changed.
+
 `import submit` takes the source id and the digest the owner read in the inventory. The daemon re-reads the
 source itself and refuses if the digest changed, so approving one source can never import a different one;
 no credential crosses the socket for a source this package can read. It refuses while an authswitch watch, a
@@ -196,7 +283,13 @@ native harness process or Codex's app-server is running, and an app-server it ca
 An adopt whose refresh fails, or whose answer is lost, is never retried: the source is quarantined, its grant
 is left needing re-authentication, and the command says so. A projection fails differently, because nothing
 rotating was ever sent for it: a native store that could not be proven live stays a pending native owner and
-is imported by submitting the same source again once its own tool has refreshed it.
+is imported by submitting the same source again once its own tool has refreshed it. That refresh rewrites the
+file, so the retry carries the digest the inventory prints afterwards: a row waiting for its native owner
+follows its own tool's bytes, and nothing else does. What it never follows is another login. A row names the
+account and the grant it was approved for, and a source that now holds a different account's login is refused
+with that stated -- before the account is registered, because the provider read that proves a projection asks
+about the identity the new bytes themselves carry and would prove the wrong login perfectly well. Neither
+that refusal nor "already imported" ever clears: no route forgets a row or re-points it at another account.
 
 `import status` reads the migration ledger, the grants and the handoffs -- never the host -- and reports, per
 source, where it stands, which owner refreshes its login now, and what to do next: nothing, submit the same
@@ -210,6 +303,17 @@ An import deletes nothing: retiring the legacy files is a separate, later step.
 deliberately not backed up, so losing it costs one device sign-in per account -- and the remote-control
 enrollments and runtime bindings with it.
 
+**Where a daemon reads those stores is stated by whoever builds it, never defaulted.** The legacy stores are
+this user's real credentials, and every location they are found at comes from the environment, so
+`AuthSwitchAuthorityDaemon` takes a required `legacyImport`: either the locations to read (an `env` and an
+absolute `homeDirectory`, plus the provider operations that import uses) or `'none'`, which builds a daemon
+with no account import at all and answers `import inventory`, `import status` and `import submit` with the
+`import_refusal` code -- a decided refusal of the closed set, never an empty inventory and never a fault, so
+a caller reads it exactly as it reads every other import refusal. A construction that names neither -- no
+locations and no `'none'` -- is refused before the daemon exists, rather than reading whichever host happened
+to start it. The per-user daemon this package installs -- `authswitch authority daemon`, the service unit's
+own entry point -- is the one place that takes those locations from this host.
+
 `AuthSwitchClient.getUsage(accountId, loginId)` reads OpenAI managed limits or a Claude
 host login's profile and usage through the management socket. The tagged, credential-free
 reading preserves Claude's labelled five-hour, weekly and model windows, plan provenance,
@@ -235,7 +339,7 @@ generated prose and credentials are absent from persistence and management respo
 removal and targeted reauthentication refuse while that account has an active preuse request.
 
 A trusted in-process daemon host can call `AuthSwitchAuthorityDaemon.startManagedCodex()`
-for a bound account and workspace. It owns a private Codex 0.155.1 app-server, passes only
+for a bound account and workspace. It owns a private Codex 0.157.0 app-server, passes only
 the authority's current access token through Codex's external-token login, answers its
 unauthorized callback through the authority, and revokes the binding on stop. The returned
 runtime exposes an interactive `codex --remote unix://…` launch descriptor and native
@@ -251,15 +355,27 @@ gone; an uncertain launch remains blocked. Callers must explicitly stop owned pr
 after their work finishes. Once reauthentication starts, it holds new admissions until the
 device operation settles. Only the private socket directory is removed on close. Codex's
 credential store remains ephemeral and does not read or write `auth.json` in that home.
+Codex binds the app-server socket in its own per-user directory,
+`<realpath /tmp>/codex-daemon-<euid>`, and publishes the private socket path as a link to it.
+The daemon checks that publication with `@modelprofile.com/mcp-crossharness`'s
+`observeCodexUnixSocket` and connects only when the link is exactly Codex's own, in a
+directory other users cannot rewrite, and the socket behind it is the user's own in a 0700
+directory of the user's; anything else fails the start with that package's error. Codex keeps a
+zero-byte startup lock in that directory for each socket path it has served; the file is
+Codex's own and authswitch does not remove it.
+Managed Codex runs only the verified Codex release: a `codex` that reports any other
+version is refused before it starts, so an automatic Codex update stops new managed
+sessions until authswitch has verified that release.
 Managed-Codex process ownership observation is qualified on Linux and reads exact argument
 boundaries from `/proc`; on other hosts doctor reports the process observation as unknown,
 and authority actions that require survivor proof refuse instead of guessing.
-Codex 0.155.1 does not persist an unused thread created by `thread/start`; resume applies
+Codex 0.157.0 does not persist an unused thread created by `thread/start`; resume applies
 after Codex has committed a rollout. The existing CLI has not yet been moved to this path.
 
 This SDK is additive at this stage. The commands documented below still use the existing
-credential stores. The authority daemon does not import those stores automatically,
-replace their active native sessions, or take over their refresh grants. An active
+credential stores, except that the legacy fence below refuses them a login the authority
+holds. The authority daemon does not import those stores automatically, replace their
+active native sessions, or take over their refresh grants. An active
 Codex/OpenCode native grant remains pending until its owner is idle and an explicit
 handoff verifies the latest native source. Claude Code's own native credential files
 remain vendor-owned; a container setup-token grant is a separate grant under the same
@@ -290,6 +406,62 @@ restore system could have written.
 The store is deliberately not backed up: its refresh grants are sealed to this host's TPM,
 so a lost store is recovered by one device re-login per account.
 
+### The legacy fence
+
+Once the authority has taken a saved copy over, the legacy `save` and `switch` must not write it again: an
+adopted copy's refresh token was rotated away by the import, and activating it would hand a tool a dead
+login. `runAuthSwitchMutation` -- the one path the command line, the guide, `watch` and the hosted
+`AuthSwitchService` all take -- asks first, and decides in three branches.
+
+- **The authority answers**: it is asked for this record's ledger row through `import status` on the
+  management socket, keyed by the same source id the importer uses (a hash of the saved copy's path). A
+  `verified` or `complete` row refuses with `authority_holds_login`; any other row, or none, lets the command
+  run. An authority that answers decides, whether or not its service unit is installed.
+- **Nothing answers within four seconds -- no socket, a silent one, or no `XDG_RUNTIME_DIR` -- and the
+  authority's service unit is installed**: the command refuses with `authority_unavailable` and the
+  instruction to run `authswitch authority service start`. Unknown is never treated as idle.
+- **Nothing answers and no unit is installed**: the legacy commands behave exactly as before. This is every
+  host before the cutover.
+
+What tells the second branch from the third is durable, never the socket: the runtime directory is tmpfs,
+so after a reboot the socket is absent until the user service starts -- exactly when a fence keyed on it
+would open. The evidence is the unit `authswitch authority service install` writes,
+`$XDG_DATA_HOME/systemd/user/authswitch-authority.service` (default
+`~/.local/share/systemd/user/authswitch-authority.service`), read through smartdaemon's
+`SystemdUnitFile.inspect()`. The installer and the fence derive that directory from one rule,
+`$XDG_DATA_HOME` or else the home directory; the installer takes both from its own process and its account's
+home, the fence from the locations its caller states. The two agree unless `$HOME` is overridden while
+`XDG_DATA_HOME` is unset, and then every store the fence guards lies under that overridden home too. The fence
+writes nothing and keeps no record of its own.
+
+The check works without a login session. Reading the unit needs only its directory, so a cron job or a plain
+ssh command with no `XDG_RUNTIME_DIR` is decided by the unit exactly like a desktop session: no unit, the
+legacy commands run; the unit installed, they refuse with `authority_unavailable`. The stated
+`XDG_RUNTIME_DIR` names only the socket to ask; an absent one is never replaced by this process's own. The
+answer depends on the unit directory derived from the stated `XDG_DATA_HOME` or home, and on nothing else:
+a malformed `XDG_RUNTIME_DIR` or `XDG_CONFIG_HOME` never refuses the command, and neither does a malformed
+process `XDG_DATA_HOME` when the caller states other locations. A unit that cannot be inspected -- a file the
+installer would not have written, a directory another user can write -- refuses rather than being read as
+absent, and so does a stated `XDG_DATA_HOME` that names no usable unit directory, because the reader can
+then tell an installed authority from none no better. On a platform without systemd no unit can be
+installed.
+
+The unit says an authority exists, not which stores it imports from, so while an installed authority is
+stopped the legacy save and switch refuse for every saved copy of every store, until it runs again. A
+record the importer could never have read -- an account id that names no saved-copy file -- is never asked
+about.
+
+`drop` / `rm` and the `remove` mutation are deliberately not fenced: they delete the user's own saved copy
+and write no credential. A projected source is never fenced either -- its native store stays with its own
+tool. The command line takes this host's locations only when it composes its own harnesses, and with
+injected harnesses is fenced only by locations its caller states; `AuthSwitchOperations`,
+`runAuthSwitchMutation` and an `AuthSwitchService` given its harnesses take the locations as a required
+argument (`authSwitchHostLegacyFence()` names this host's, `'none'` states that a
+caller owns no authority), so no library path reads a host it was not given. `AuthSwitchOperations` and the
+hosted service ask the fence before their AGL coordinator as well, so a refused mutation never has its host
+stop the runtimes it would restart. The hosted service reports a fence refusal as the operation's problem, in
+the instruction's own words.
+
 ## Usage
 
 Run `authswitch`, `authswitch -i`, or `authswitch --interactive` for an interactive guide. Use the arrow keys and
@@ -452,9 +624,12 @@ login. `activateCredential(providerId, credential)` preserves and verifies the
 outgoing native login before activation; the caller retains ownership of the
 incoming credential's durable storage. Both are backend APIs, never wire payloads.
 
-`AuthSwitchOperations` is shared by the command, guide and TUI. Its optional
-coordinator receives only the harness, operation, account ID, consent to wait,
-and a credential-location fingerprint. AGL owns private-controller discovery;
+`AuthSwitchOperations` is shared by the command, guide and TUI, and is built
+with a coordinator (or `undefined`) and the legacy fence locations described in
+"The legacy fence". A host that injects its own harnesses into `AuthSwitchService`
+states that fence as the third argument. The coordinator receives only the
+harness, operation, account ID, consent to wait, and a credential-location
+fingerprint. AGL owns private-controller discovery;
 authswitch uses `agl authswitch --request <json>` without an AGL package dependency.
 A failed or ambiguous transport never falls through to a second local mutation.
 AGL and the CLI must use matching credential locations and compatible versions.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/authswitch',
-  version: '8.1.0',
+  version: '9.0.0',
   description: 'Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status'
 }

package/ts/authority-contract.ts

@@ -2,6 +2,106 @@ import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
 import type { IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
 export type { IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
 
+/**
+ * Why the authority declined, as a closed set a client branches on without reading the text.
+ *
+ * A refusal is an answer: the daemon did the check, nothing was left half-done, and the message says what
+ * the owner does instead. Everything else stays a fault whose text the transport replaces, and a caller
+ * must never present a fault as if it said what to do next.
+ */
+export type TAuthSwitchRefusalCode =
+  | 'authority_closing'
+  | 'not_found'
+  | 'account_changed'
+  | 'account_busy'
+  | 'login_unavailable'
+  /** A runtime capability that is missing, wrong or superseded: deliberately one answer, and one repair. */
+  | 'binding_unauthorized'
+  /** The authority holds this login, so the legacy path that used to move it no longer may. */
+  | 'authority_holds_login'
+  /** An authority is installed on this host and is not answering, so nothing may assume it holds nothing. */
+  | 'authority_unavailable'
+  | 'native_owner_holds_login'
+  | 'claude_home_unregistered'
+  | 'claude_handoff_pending'
+  | 'claude_receipt_missing'
+  | 'import_refusal';
+
+/** The marker the importer has published since 8.1.0; it keeps its own value on the wire. */
+export const authSwitchImportRefusalMarker = 'authswitch_import_refusal';
+export const authSwitchRefusalReason = 'authswitch_refusal';
+
+export type TAuthSwitchRefusalReason = typeof authSwitchRefusalReason | typeof authSwitchImportRefusalMarker;
+
+/** Everything a refusal puts on the wire beside its message: two literals, never a value of its own. */
+export interface IAuthSwitchRefusalData {
+  reason: TAuthSwitchRefusalReason;
+  code: TAuthSwitchRefusalCode;
+}
+
+/** What the owner is told when the answer is an instruction rather than a fault. */
+export interface IAuthSwitchRefusal {
+  code: TAuthSwitchRefusalCode;
+  /** The instruction, authored by the handler that declined. */
+  instruction: string;
+}
+
+const refusalCodes: ReadonlySet<string> = new Set<TAuthSwitchRefusalCode>([
+  'authority_closing', 'not_found', 'account_changed', 'account_busy',
+  'login_unavailable', 'binding_unauthorized', 'native_owner_holds_login', 'claude_home_unregistered',
+  'claude_handoff_pending', 'claude_receipt_missing', 'import_refusal',
+  'authority_holds_login', 'authority_unavailable',
+]);
+
+const isRefusalCode = (value: unknown): value is TAuthSwitchRefusalCode =>
+  typeof value === 'string' && refusalCodes.has(value);
+
+/** The importer keeps the marker it published; every other code shares the authority's own. */
+const reasonOf = (code: TAuthSwitchRefusalCode): TAuthSwitchRefusalReason =>
+  code === 'import_refusal' ? authSwitchImportRefusalMarker : authSwitchRefusalReason;
+
+/**
+ * One refusal, thrown by a handler and turned into a marked answer by the router that owns the wire.
+ *
+ * It accepts nothing but a code of the closed set and the text the owner is to read, and builds the marker
+ * from the code alone, so no handler can attach a value of its own to what a client branches on.
+ */
+export class AuthSwitchRefusal extends Error {
+  public readonly code: TAuthSwitchRefusalCode;
+
+  constructor(code: TAuthSwitchRefusalCode, instruction: string) {
+    super(instruction);
+    this.code = code;
+  }
+
+  /** Everything this refusal puts on the wire beside its message. */
+  public get data(): IAuthSwitchRefusalData { return { reason: reasonOf(this.code), code: this.code }; }
+}
+
+/**
+ * The refusal an error answer carries, or null when it is a fault whose text says nothing.
+ *
+ * This is the only reader of `errorData` in the package: the importer's published predicate is expressed
+ * through it, so a caller never has to know which of the two markers a route uses.
+ *
+ * 8.1.0 marked the importer's refusal with the reason alone. A per-user daemon keeps running across an
+ * upgrade until its owner restarts it, so a newer client still meets that payload, and it names the one
+ * refusal that release could answer with -- which is why it is read rather than treated as a fault.
+ */
+export const asAuthSwitchRefusal = (error: unknown): IAuthSwitchRefusal | null => {
+  if (error instanceof AuthSwitchRefusal) return { code: error.code, instruction: error.message };
+  if (typeof error !== 'object' || error === null || !('errorData' in error)) return null;
+  const data: unknown = error.errorData;
+  if (typeof data !== 'object' || data === null || !('reason' in data)) return null;
+  const code: unknown = 'code' in data ? data.code : undefined;
+  const instruction = 'message' in error && typeof error.message === 'string' ? error.message : '';
+  if (data.reason === authSwitchImportRefusalMarker) {
+    return code === undefined || code === 'import_refusal' ? { code: 'import_refusal', instruction } : null;
+  }
+  if (data.reason !== authSwitchRefusalReason || !isRefusalCode(code)) return null;
+  return { code, instruction };
+};
+
 /** Credential-free account management contract. Safe to import in browser code. */
 export type TAuthSwitchLoginPurpose = 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native';
 export type TAuthSwitchLoginHealth = 'ready' | 'refreshing' | 'retry_wait' | 'needs_reauth' | 'unverified' | 'pending_handoff' | 'handoff_quarantined' | 'removed';
@@ -17,6 +117,16 @@ export interface IAuthSwitchAccount {
   statusObservedAt: string;
 }
 
+/**
+ * Which tool refreshes a natively owned login, named rather than inferred.
+ *
+ * `owner` says that a native tool holds the login; this says which one, so a consumer presents "Claude Code"
+ * or "Codex" without deriving it from `purpose` -- a derivation that would be wrong the moment two purposes
+ * share a tool, and that belongs to the side that decides ownership in the first place. It is `null` exactly
+ * when no native tool refreshes the login: the authority does, or nothing does.
+ */
+export type TAuthSwitchLoginOwnerTool = 'claude_code' | 'codex' | 'opencode';
+
 /** One independently owned login. Native ownership does not imply observed health. */
 export interface IAuthSwitchLogin {
   id: string;
@@ -24,6 +134,8 @@ export interface IAuthSwitchLogin {
   providerId: string;
   purpose: TAuthSwitchLoginPurpose;
   owner: 'daemon' | 'claude_native' | 'legacy_native' | 'none';
+  /** The native tool that refreshes this login, or null when the authority or nobody does. */
+  ownerTool: TAuthSwitchLoginOwnerTool | null;
   health: TAuthSwitchLoginHealth;
   problem: 'none' | 'provider_unavailable' | 'exchange_uncertain' | 'provider_rejected' | 'native_owner';
   grantGeneration: number;
@@ -234,6 +346,17 @@ export interface IAuthSwitchPreuseOperation {
   revision: number;
 }
 
+/**
+ * Why the host could not prove that Claude Code uses its own native login.
+ *
+ * Each value names one condition of that proof, so an owner is told what to change: install the supported
+ * release, sign in to a subscriber plan, remove a credential override or a settings source, let the
+ * profile read succeed, or close the running session.
+ */
+export type TAuthSwitchClaudeProofFailure =
+  | 'unsupported_release' | 'override' | 'profile' | 'profile_unreadable'
+  | 'settings' | 'subscription' | 'running_session';
+
 /** Credential-free native file ownership result. It makes no claim about a running session's active request. */
 export interface IAuthSwitchClaudeNativeHandoff {
   id: string;
@@ -243,6 +366,8 @@ export interface IAuthSwitchClaudeNativeHandoff {
   phase: 'reserved' | 'prepared' | 'committed' | 'aborted' | 'quarantined';
   problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
   runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
+  /** Which condition of the native-login proof failed, when `problem` is `unsupported_effective_auth`. */
+  proofFailure?: TAuthSwitchClaudeProofFailure;
   updatedAt: string;
 }
 

package/ts/authority-import-contract.ts

@@ -1,4 +1,5 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
+import { asAuthSwitchRefusal, authSwitchImportRefusalMarker } from './authority-contract.js';
 
 /**
  * The one-time account import: reading the legacy stores that existed before the authority, and the
@@ -148,20 +149,20 @@ export type TAuthSwitchImportAction = 'none' | 'resume' | 'device_login';
 /**
  * Marks an error answer whose text is an instruction for the owner, not a report of a fault.
  *
- * The daemon sets it on the refusals the importer authors and on nothing else. Every other failure answers
- * with the transport's own sanitised text, which a caller must never present as if it said what to do next --
- * for a submit in particular, an unmarked failure means the outcome is unknown and the source must be read
- * with `authswitch.authority.import.status` rather than submitted again.
+ * The daemon sets it on the refusals the importer authors and on nothing else: a refusal any other route
+ * authors carries the authority's own marker, and a failure neither of them decided answers with the
+ * transport's sanitised text, which a caller must never present as if it said what to do next. For a
+ * submit in particular, an unmarked failure means the outcome is unknown and the source must be read with
+ * `authswitch.authority.import.status` rather than submitted again.
+ *
+ * It is one code of the authority's refusal contract (`./authority-contract`), which every route now uses;
+ * this marker keeps its own value on the wire so a consumer written against 8.1.0 keeps working.
  */
-export const authSwitchImportRefusalReason = 'authswitch_import_refusal';
+export const authSwitchImportRefusalReason = authSwitchImportRefusalMarker;
 
 /** True when the daemon answered with an importer refusal, so `error.message` is the instruction to show. */
-export const isAuthSwitchImportRefusal = (error: unknown): boolean => {
-  if (typeof error !== 'object' || error === null || !('errorData' in error)) return false;
-  const data = error.errorData;
-  return typeof data === 'object' && data !== null && 'reason' in data
-    && data.reason === authSwitchImportRefusalReason;
-};
+export const isAuthSwitchImportRefusal = (error: unknown): boolean =>
+  asAuthSwitchRefusal(error)?.code === 'import_refusal';
 
 /**
  * Where one source stands, read from the migration ledger, the grant it produced and its handoff.

package/ts/authority-paths.ts

@@ -0,0 +1,69 @@
+import * as plugins from './plugins.js';
+
+/**
+ * Where this user's authority lives: its sockets, its store and the service unit that runs it.
+ *
+ * These rules sit in a leaf module because two sides read them. `AuthSwitchAuthorityService` installs and
+ * runs the daemon there, and the legacy fence (`./classes.legacyfence`) asks the same socket and looks for
+ * the same unit -- without importing the daemon, whose module graph reaches back to the legacy operations
+ * the fence guards.
+ */
+
+export interface IAuthSwitchAuthorityPaths {
+  runtimeDirectory: string;
+  dataDirectory: string;
+  databaseSocketPath: string;
+  authoritySocketPath: string;
+  runtimeSocketPath: string;
+  runtimeSocketDirectory: string;
+}
+
+/** The authority's sockets. */
+export type TAuthSwitchAuthoritySocketPaths = Omit<IAuthSwitchAuthorityPaths, 'dataDirectory'>;
+
+/**
+ * The sockets under one runtime directory, derived from it alone.
+ *
+ * The legacy fence asks the socket a caller states and must not depend on anything this process holds --
+ * its home or its `XDG_DATA_HOME`, which only the store's directory needs.
+ */
+export const authSwitchAuthoritySocketPaths = (
+  runtimeDirectory: string | undefined): TAuthSwitchAuthoritySocketPaths => {
+  if (!runtimeDirectory || !plugins.path.isAbsolute(runtimeDirectory)) {
+    throw new Error('A private XDG_RUNTIME_DIR is required for authswitch authority.');
+  }
+  const socketDirectory = plugins.path.join(runtimeDirectory, 'authswitch');
+  const runtimeSocketDirectory = plugins.path.join(socketDirectory, 'runtime');
+  return {
+    runtimeDirectory,
+    databaseSocketPath: plugins.path.join(socketDirectory, 'internal', 'db.sock'),
+    authoritySocketPath: plugins.path.join(socketDirectory, 'management', 'authority.sock'),
+    runtimeSocketPath: plugins.path.join(runtimeSocketDirectory, 'runtime.sock'),
+    runtimeSocketDirectory,
+  };
+};
+
+/** Canonical per-user paths. An explicit runtime directory is also usable by a trusted container host. */
+export const resolveAuthSwitchAuthorityPaths = (runtimeDirectory = process.env.XDG_RUNTIME_DIR): IAuthSwitchAuthorityPaths => {
+  const sockets = authSwitchAuthoritySocketPaths(runtimeDirectory);
+  const home = plugins.os.userInfo().homedir;
+  const dataHome = process.env.XDG_DATA_HOME || plugins.path.join(home, '.local/share');
+  if (!plugins.path.isAbsolute(dataHome)) throw new Error('XDG_DATA_HOME must be an absolute path.');
+  return { ...sockets, dataDirectory: plugins.path.join(dataHome, 'authswitch', 'authority') };
+};
+
+/** The user service `authswitch authority service install` writes. */
+export const authSwitchAuthorityUnitName = 'authswitch-authority.service';
+
+/**
+ * The directory that unit is installed into, from a stated environment and home directory.
+ *
+ * It is the rule smartdaemon applies to a user unit when it is given no directory --
+ * `$XDG_DATA_HOME/systemd/user`, default `~/.local/share/systemd/user` -- stated here so the installer passes
+ * it explicitly and the fence derives it from the locations its caller states rather than from this process.
+ */
+export const authSwitchAuthorityUnitDirectory = (env: NodeJS.ProcessEnv, homeDirectory: string): string => {
+  const dataHome = env.XDG_DATA_HOME || plugins.path.join(homeDirectory, '.local/share');
+  if (!plugins.path.isAbsolute(dataHome)) throw new Error('XDG_DATA_HOME must be an absolute path.');
+  return plugins.path.join(dataHome, 'systemd/user');
+};

package/ts/authority-runtime-contract.ts

@@ -1,7 +1,17 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
 import type { IAuthSwitchBinding } from './authority-contract.js';
 
-/** Backend-only binding operation. The capability must never enter a browser-facing response. */
+/**
+ * Backend-only binding operation, served on the MANAGEMENT socket. Not a misplacement -- the rule.
+ *
+ * The other two requests in this file are answered on the runtime socket, whose directory a container may
+ * be given. This one is not, because it mints the capability those two spend: minting is the act that
+ * authorizes a runtime, so it belongs to a caller already trusted with account management. A container
+ * holding the runtime directory can therefore use the binding it was handed, and can never create one --
+ * not for itself, and not for another account.
+ *
+ * The capability must never enter a browser-facing response.
+ */
 export interface IReq_AuthSwitchBindAccount extends ITypedRequest {
   method: 'authswitch.authority.bind';
   request: {