Skip to content

t1k:unity:base:upm-auth

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: browser login, device flow, interactive login, npm login, scoped registry, the1studio registry, unity registry, upm auth, upm token expired, upmconfig, web login

/t1k:unity:base:upm-auth

Unity reads UPM scoped-registry credentials from ~/.upmconfig.toml. Token lifetimes, hosts, which file each client reads, machine tokens for CI and every error live in the shared t1k:registry skill (its auth-paths and errors pages, theonekit-core); this page holds only the Unity-side steps and does not repeat them.

There is one automatic path and one fallback. Try them in this order:

#PathCommand
1Automatic (GitHub identity, no click)bun <claudeDir>/scripts/registry-auth-sync.cjs --force
2Fallback (browser web login, a human clicks)bun <skill>/scripts/upm-web-login.cjs [registry-url]

Check first. bun <claudeDir>/scripts/registry-auth-sync.cjs --check --json prints one outcome per registry; exit 0 unless a stored token was rejected. The engine lives in t1k-base and is the only file that mints a token or writes the credential lines; this skill never re-implements it. Kill switch: T1K_SKIP_REGISTRY_AUTH=1. The doctor has a “registry auth” check.

Terminal window
bun <claudeDir>/scripts/studio-auth-login.cjs # once per machine (GitHub device flow)
bun <claudeDir>/scripts/registry-auth-sync.cjs --force # mint/refresh now

If --check --json then reports the registry as ok, stop: restart Unity and you are done. If the outcome is anything else (registry not enabled for you, no grant, unreachable), go to the fallback below; the t1k:registry auth-paths page explains each outcome and how to enable a registry. Do not tell a user the automatic path works for a registry the check did not report as ok.

Terminal window
bun <skill>/scripts/upm-web-login.cjs [registry-url] [--check] [--json] [--timeout-sec <n>]

Runs npm’s browser login in a private temp userconfig, then copies the resulting token into ~/.upmconfig.toml in the shape Unity reads ([npmAuth."<registry-url>/"], token, alwaysAuth = true). The token also stays in ~/.npmrc, so other npm tooling against that host keeps working. --check reports locally, without dialling out, whether a stored token is present and unexpired; the registry only confirms it for real at fetch time. The page a human can open directly instead is the registry token page named on the t1k:registry auth-paths page.

Do not let CI reach this path. It blocks on a human click. CI uses machine tokens, described in the t1k:registry auth-paths page (Machine tokens).

Handover: the URL must reach the human in about a second while the child blocks for minutes

Section titled “Handover: the URL must reach the human in about a second while the child blocks for minutes”

The script emits LOGIN_URL=<url> on stdout the moment npm prints it and then keeps running.

  1. Start it in the background with output to a scratchpad log (run_in_background: true):
    Terminal window
    bun <skill>/scripts/upm-web-login.cjs > <scratch>/upm-login.log 2>&1
  2. Wait for the URL to appear, then read it:
    Terminal window
    until grep -q '^LOGIN_URL=' <scratch>/upm-login.log; do sleep 0.5; done
    grep '^LOGIN_URL=' <scratch>/upm-login.log | cut -d= -f2-
  3. Open the exact page, then print the opener’s own state and the plain URL as fallback, never “should have opened” (rules/one-click-handoff.md):
    Terminal window
    bun -e 'const{openSources,describeSources}=require(process.env.HOME+"/.claude/scripts/lib/secret-prompt-sources.cjs");openSources([{name:"Unity UPM login",url:process.argv[1]}]).then(r=>console.log(describeSources(r)))' "<url>"
  4. Tell the user what to click, then wait in-turn with a Monitor until-loop on the log. Cover BOTH outcomes: the success marker and the failure signatures (bun ERR!, upm-web-login:, a non-zero exit, the timeout message). A filter that only watches for success goes silent on a crash and looks identical to “still waiting”.
  5. Report the config path and expiry, and tell the user to restart Unity.

Exit codes: 0 success | 1 no token, malformed token, write failure, timeout, or npm could not be run. The token is never printed.

  • First-time setup of the studio UPM registry on a dev machine.
  • Unity reports 401 / “no auth token” resolving scoped-registry packages.
  • The token expired (--check says so, or Logs/upm.log does).

$HOME is where Unity reads .upmconfig.toml: on Windows run under Git Bash, where $HOME = %USERPROFILE%.

Both paths run inline in the main session: the web handover must reach a human and be waited on in-turn, which a delegated sub-agent cannot do. Failure diagnosis stays on the reasoning tier. Never echo a token value.

  • A stale token fails silently, not loudly. Always check this first. Package Manager does not error when a scoped-registry token is stale, missing or expired: it silently evicts the packages it could not fetch and keeps going. The next compile then reports a mass CS0246 cascade across unrelated files that looks exactly like a code regression. Check Logs/upm.log for lacks valid authentication credentials / [ERROR] lines, and run --check, before assuming the code broke (rules/reproducible-on-every-machine-unity.md Rule 2).
  • Do not cite a separate UPM-login skill by name. The only skill in this area is this one, t1k:unity:base:upm-auth; the publish side is t1k:registry.
  • The web path delegates credential handling to npm; it decides only host and file. registry-auth-files.cjs (core module t1k-base) owns the ~/.upmconfig.toml shape, the 0600 mode, the atomic rename and the one-time .t1k-bak backup. Do not hand-roll TOML writing here. A token that is not a plain three-part JWT is refused before anything is written.
  • HTTPS is mandatory for remote registries, so the returned token never crosses the network in clear text. Plain HTTP is accepted only for a loopback host (localhost, 127.0.0.1, [::1]) used for local development.
  • A password login does not exist any more. Do not look for one or script one; use the two paths above.
  • t1k:registry (theonekit-core) — auth paths, error table, publish flow, preflight.
  • scripts/upm-web-login.cjs — the fallback (path 2).
  • t1k:unity:base:publish-package — the Unity side of publishing.
  • t1k:unity:base:addressables, t1k:unity:base:text-config — adjacent Unity infra.