t1k:unity:base:upm-auth
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: browser login, device flow, interactive login, npm login, scoped registry, the1studio registry, unity registry, upm auth, upm token expired, upmconfig, web login
How to invoke
Section titled “How to invoke”/t1k:unity:base:upm-authUnity UPM Auth Setup
Section titled “Unity UPM Auth Setup”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:
| # | Path | Command |
|---|---|---|
| 1 | Automatic (GitHub identity, no click) | bun <claudeDir>/scripts/registry-auth-sync.cjs --force |
| 2 | Fallback (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.
1. Automatic path
Section titled “1. Automatic path”bun <claudeDir>/scripts/studio-auth-login.cjs # once per machine (GitHub device flow)bun <claudeDir>/scripts/registry-auth-sync.cjs --force # mint/refresh nowIf --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.
2. Fallback: web login
Section titled “2. Fallback: web login”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.
- 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 - Wait for the URL to appear, then read it:
Terminal window until grep -q '^LOGIN_URL=' <scratch>/upm-login.log; do sleep 0.5; donegrep '^LOGIN_URL=' <scratch>/upm-login.log | cut -d= -f2- - 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>" - Tell the user what to click, then wait in-turn with a
Monitoruntil-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”. - 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.
When to use
Section titled “When to use”- 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 (
--checksays so, orLogs/upm.logdoes).
Platforms
Section titled “Platforms”$HOME is where Unity reads .upmconfig.toml: on Windows run under Git Bash, where $HOME =
%USERPROFILE%.
Executed by
Section titled “Executed by”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.
Hard rules
Section titled “Hard rules”- 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
CS0246cascade across unrelated files that looks exactly like a code regression. CheckLogs/upm.logforlacks valid authentication credentials/[ERROR]lines, and run--check, before assuming the code broke (rules/reproducible-on-every-machine-unity.mdRule 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 ist1k:registry. - The web path delegates credential handling to npm; it decides only host and file.
registry-auth-files.cjs(core modulet1k-base) owns the~/.upmconfig.tomlshape, the0600mode, the atomic rename and the one-time.t1k-bakbackup. 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.
Related
Section titled “Related”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.