@nurix/nustack 0.10.0-dev.15 → 0.10.0-dev.16

package/README.md

@@ -74,4 +74,5 @@ nustack telemetry [status|enable|disable|reinstall]
 
 - **`--json` almost everywhere** — most commands emit the `nustackJsonVersion: 1` machine envelope with `--json`; errors are typed (`{ error: { code, message } }`), never a bare HTTP status. Four surfaces break the pattern by design — `describe`, `search`, `search services`, and the `workspace sync` family emit a bare array/object instead, because the desktop and the agents pin those exact shapes.
 - **Base URL** — `--nustack-url` flag → `NUSTACK_URL` env → the hosted default (`https://apps.nustack.ai`).
+- **Credential** — `NUSTACK_TOKEN` (a personal access token from `nustack token create`, for pipelines and agents; wins over every store, never refreshes, never opens a browser) → the OS store (macOS Keychain, libsecret on Linux) → `~/.nustack/credentials.json` (`0600`) where no OS store exists. `NUSTACK_CREDENTIAL_STORE=auto|keychain|libsecret|file` overrides the probe.
 - **Organization context** — `nustack organization use` persists the selection locally; commands send it as a header the server re-proves against your memberships on every request.

package/dist/commands/doctor.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { resolveNuStackUrl } from "../lib/nustack_client.js";
-import { ensureAccessToken } from "../lib/auth_grant.js";
-import { isKeychainAvailable } from "../lib/device_keychain.js";
+import { stat } from "node:fs/promises";
+import { ensureAccessToken, ENV_TOKEN_VARIABLE, envToken } from "../lib/auth_grant.js";
+import { credentialsFilePath, selectCredentialStore } from "../lib/credential_store.js";
 import { resolveProjectId } from "../lib/project_context.js";
 import { readManagedValues } from "../lib/env_file.js";
 import { readProjectManifests, diagnoseManifests } from "../lib/onboarding/manifest_writer.js";
@@ -19,6 +20,33 @@ import { NotARepositoryError } from "../lib/git-sync/core/git_runner.js";
 import { listBundles, sweepExpiredBundles } from "../lib/git-sync/recovery/store.js";
 import { inspectRecoveryKey } from "../lib/git-sync/recovery/crypto.js";
 import { NUSTACK_JSON_VERSION } from "../lib/json_output.js";
+async function credentialStoreRows(environmentInUse) {
+    if (environmentInUse)
+        return [{ check: "Credential source", status: "ok", detail: "environment — no store is read" }];
+    let store;
+    try {
+        store = selectCredentialStore();
+    }
+    catch (error) {
+        return [{ check: "Credential source", status: "error", detail: error instanceof Error ? error.message : String(error) }];
+    }
+    const rows = [
+        { check: "Credential source", status: "ok", detail: store.name === "file" ? "file — no OS keychain on this machine" : store.name },
+    ];
+    if (store.name === "file") {
+        const filePath = credentialsFilePath();
+        try {
+            const mode = (await stat(filePath)).mode & 0o777;
+            rows.push(mode === 0o600
+                ? { check: "Credential file mode", status: "ok", detail: "0600" }
+                : { check: "Credential file mode", status: "warn", detail: `0${mode.toString(8)} — expected 0600; run \`chmod 600 ~/.nustack/credentials.json\`` });
+        }
+        catch {
+            rows.push({ check: "Credential file mode", status: "info", detail: "no credential file yet — sign in to create it" });
+        }
+    }
+    return rows;
+}
 export async function runDoctor(options) {
     const cwd = process.cwd();
     const baseUrl = resolveNuStackUrl(options);
@@ -28,12 +56,18 @@ export async function runDoctor(options) {
     const add = (area, check, status, detail = "") => {
         rows.push({ area, check, status, detail });
     };
+    const fromEnv = envToken();
     const deviceAuth = await ensureAccessToken(baseUrl).catch(() => null);
-    if (deviceAuth)
+    if (fromEnv?.kind === "malformed")
+        add("identity", "Device sign-in", "error", fromEnv.message);
+    else if (fromEnv)
+        add("identity", "Device sign-in", "ok", `${ENV_TOKEN_VARIABLE} is set — the environment's token is used`);
+    else if (deviceAuth)
         add("identity", "Device sign-in", "ok", `signed in as ${deviceAuth.userEmail}`);
     else
         add("identity", "Device sign-in", "error", "signed out — run `nustack login`");
-    add("identity", "OS keychain", isKeychainAvailable() ? "ok" : "warn", isKeychainAvailable() ? "available" : "unavailable — sign-in relies on the 24h approval window");
+    for (const row of await credentialStoreRows(fromEnv !== null))
+        add("identity", row.check, row.status, row.detail);
     add("api", "NuStack reachability", ...(await probeReachability(baseUrl)));
     let store = null;
     try {

package/dist/commands/login.js

@@ -1,9 +1,9 @@
 import * as p from "@clack/prompts";
 import { resolveNuStackUrl } from "../lib/nustack_client.js";
 import { launchBrowser } from "../lib/browser_opener.js";
-import { isKeychainAvailable } from "../lib/device_keychain.js";
+import { selectCredentialStore } from "../lib/credential_store.js";
 import { isInteractive } from "../lib/interactive.js";
-import { ensureAccessToken, loginWithLoopback, loginWithPastedCode, prepareLogin, } from "../lib/auth_grant.js";
+import { ensureAccessToken, ENV_TOKEN_VARIABLE, envToken, loginWithLoopback, loginWithPastedCode, prepareLogin, } from "../lib/auth_grant.js";
 async function readStdinLine() {
     return new Promise((resolve) => {
         let buffered = "";
@@ -79,8 +79,16 @@ async function loopbackFlow(ctx, flags) {
     }
 }
 export async function performDeviceLogin(baseUrl, _cwd = process.cwd(), flags = {}) {
-    if (!isKeychainAvailable()) {
-        p.log.error("No OS keychain on this platform — NuStack keeps a machine's sign-in only in the keychain.");
+    if (envToken()) {
+        p.log.info(`${ENV_TOKEN_VARIABLE} is set — this process authenticates with it, and no sign-in is stored on this machine. Unset it to sign in as a person.`);
+        return true;
+    }
+    let store;
+    try {
+        store = selectCredentialStore();
+    }
+    catch (error) {
+        p.log.error(error instanceof Error ? error.message : String(error));
         return false;
     }
     if (!flags.force && !flags.reauthorize) {
@@ -118,7 +126,12 @@ export async function performDeviceLogin(baseUrl, _cwd = process.cwd(), flags =
         return false;
     }
     p.log.success(`Signed in as ${result.userEmail || "this account"}`);
-    p.log.info("This machine's grant is saved to your keychain — the desktop shares it. Manage it with `nustack device list`.");
+    if (store.name === "file") {
+        p.log.info(`This machine's grant is saved to ~/.nustack/credentials.json, readable only by you — no OS keychain here. Manage it with \`nustack device list\`.`);
+    }
+    else {
+        p.log.info("This machine's grant is saved to your keychain — the desktop shares it. Manage it with `nustack device list`.");
+    }
     return true;
 }
 export async function runLogin(options, flags = {}) {
@@ -130,5 +143,5 @@ export async function runLogin(options, flags = {}) {
         process.exitCode = 1;
         return;
     }
-    p.outro("Signed in on this device.");
+    p.outro(envToken() ? "Nothing was written." : "Signed in on this device.");
 }

package/dist/commands/logout.js

@@ -1,13 +1,20 @@
 import * as p from "@clack/prompts";
 import { resolveNuStackUrl } from "../lib/nustack_client.js";
 import { clearDeviceId } from "../lib/device_identity.js";
-import { deleteDeviceCredential, isKeychainAvailable } from "../lib/device_keychain.js";
-import { fetchAuthConfig, readGrant, revokeGrant } from "../lib/auth_grant.js";
+import { deleteDeviceCredential } from "../lib/device_keychain.js";
+import { selectCredentialStore } from "../lib/credential_store.js";
+import { ENV_TOKEN_VARIABLE, envToken, fetchAuthConfig, readGrant, revokeGrant } from "../lib/auth_grant.js";
 const SHARED_SIGNOUT_NOTE = "This signs out both the CLI and the desktop on this machine.";
 export async function runLogout(options, flags = {}) {
     p.intro("nustack logout");
     const baseUrl = resolveNuStackUrl(options);
-    const grant = isKeychainAvailable() ? await readGrant() : null;
+    if (envToken()) {
+        p.log.info(`${ENV_TOKEN_VARIABLE} is set — the environment holds this process's credential, and there is nothing stored on this machine to end. Unset the variable, or revoke the token with \`nustack token revoke\`.`);
+        p.outro("Nothing was changed.");
+        return;
+    }
+    const store = selectCredentialStore();
+    const grant = await readGrant();
     if (grant) {
         const clientId = grant.clientId ?? (await fetchAuthConfig(baseUrl).then((c) => c.clientId).catch(() => null));
         const outcome = clientId ? await revokeGrant({ authBaseUrl: grant.authBaseUrl, refreshToken: grant.grantToken, clientId }) : "unreachable";
@@ -25,12 +32,13 @@ export async function runLogout(options, flags = {}) {
         }
         const cleared = await deleteDeviceCredential(grant.deviceId);
         if (cleared)
-            p.log.success("Cleared the keychain grant.");
+            p.log.success(store.name === "keychain" ? "Cleared the keychain grant." : `Cleared the stored grant (${store.name}).`);
     }
     else {
-        p.log.info("No keychain credential to clear on this machine.");
+        p.log.info(store.name === "keychain" ? "No keychain credential to clear on this machine." : `No stored credential to clear on this machine (${store.name}).`);
     }
-    p.log.info(SHARED_SIGNOUT_NOTE);
+    if (store.name === "keychain")
+        p.log.info(SHARED_SIGNOUT_NOTE);
     if (flags.forgetDevice) {
         const forgot = await clearDeviceId();
         if (forgot) {

package/dist/commands/token.js

@@ -0,0 +1,102 @@
+import { createPersonalToken, listPersonalTokens, PersonalTokenRequestError, resolveNuStackUrl, revokePersonalToken } from "../lib/nustack_client.js";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+const MAX_EXPIRY_DAYS = 365;
+async function requireAuth(command, json, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const auth = await ensureAuthWithRecovery(baseUrl, json);
+    if (!auth) {
+        const failure = lastAuthFailure();
+        if (json)
+            printJsonError(command, { code: failure.code, message: failure.message });
+        else {
+            console.error(failure.message);
+            process.exitCode = 1;
+        }
+        return null;
+    }
+    return { baseUrl, accessToken: auth.accessToken };
+}
+function refuse(command, json, error) {
+    const code = error instanceof PersonalTokenRequestError ? error.code : "REQUEST_FAILED";
+    const message = error instanceof Error ? error.message : String(error);
+    if (json)
+        printJsonError(command, { code, message });
+    else {
+        console.error(message);
+        process.exitCode = 1;
+    }
+}
+export async function runTokenCreate(options, globals) {
+    const json = options.json === true;
+    const label = options.label?.trim() ?? "";
+    if (!label)
+        return refuse("token create", json, new PersonalTokenRequestError("VALIDATION_FAILED", "A label is required: `nustack token create --label <name>`."));
+    let expiresInDays;
+    if (options.expires !== undefined) {
+        const parsed = Number(options.expires);
+        if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_EXPIRY_DAYS) {
+            return refuse("token create", json, new PersonalTokenRequestError("VALIDATION_FAILED", `--expires is a whole number of days, 1–${MAX_EXPIRY_DAYS}.`));
+        }
+        expiresInDays = parsed;
+    }
+    const auth = await requireAuth("token create", json, globals);
+    if (!auth)
+        return;
+    try {
+        const minted = await createPersonalToken(auth.baseUrl, auth.accessToken, { label, ...(expiresInDays ? { expiresInDays } : {}) });
+        if (json) {
+            printJsonSuccess("token create", minted);
+            return;
+        }
+        console.error(`Minted \`${minted.token.label}\` (${minted.token.tokenPrefix}…)${minted.token.expiresAt ? `, expires ${minted.token.expiresAt}` : ""}.`);
+        console.error(`This is the only time the secret is shown. Store it as ${"NUSTACK_TOKEN"} in your pipeline; revoke it with \`nustack token revoke ${minted.token.id}\`.`);
+        console.log(minted.secret);
+    }
+    catch (error) {
+        refuse("token create", json, error);
+    }
+}
+export async function runTokenList(options, globals) {
+    const json = options.json === true;
+    const auth = await requireAuth("token list", json, globals);
+    if (!auth)
+        return;
+    try {
+        const tokens = await listPersonalTokens(auth.baseUrl, auth.accessToken);
+        if (json) {
+            printJsonSuccess("token list", { tokens });
+            return;
+        }
+        if (tokens.length === 0) {
+            console.log("No personal access tokens. Mint one with `nustack token create --label <name>`.");
+            return;
+        }
+        for (const token of tokens) {
+            const state = token.revokedAt ? `revoked ${token.revokedAt}` : token.expiresAt ? `expires ${token.expiresAt}` : "no expiry";
+            console.log(`${token.id.padEnd(38)} ${`${token.tokenPrefix}…`.padEnd(18)} ${token.label.padEnd(24)} ${state.padEnd(30)} last used ${token.lastUsedAt ?? "never"}`);
+        }
+    }
+    catch (error) {
+        refuse("token list", json, error);
+    }
+}
+export async function runTokenRevoke(tokenId, options, globals) {
+    const json = options.json === true;
+    if (!tokenId?.trim())
+        return refuse("token revoke", json, new PersonalTokenRequestError("VALIDATION_FAILED", "A token id is required: `nustack token revoke <id>` (see `nustack token list`)."));
+    const auth = await requireAuth("token revoke", json, globals);
+    if (!auth)
+        return;
+    try {
+        const revoked = await revokePersonalToken(auth.baseUrl, auth.accessToken, tokenId.trim());
+        if (json) {
+            printJsonSuccess("token revoke", revoked);
+            return;
+        }
+        console.log(`Revoked ${revoked.id} at ${revoked.revokedAt}.`);
+    }
+    catch (error) {
+        refuse("token revoke", json, error);
+    }
+}

package/dist/index.js

@@ -10,6 +10,7 @@ import { runDescribe } from "./commands/describe.js";
 import { runValidate } from "./commands/validate.js";
 import { runGraph } from "./commands/graph.js";
 import { runDoctor } from "./commands/doctor.js";
+import { runTokenCreate, runTokenList, runTokenRevoke } from "./commands/token.js";
 import { runOpen } from "./commands/open.js";
 import { runBootstrap } from "./commands/bootstrap.js";
 import { runLogout } from "./commands/logout.js";
@@ -108,6 +109,24 @@ program
     .option("--env <name>", "pick a specific endpoint environment (default: dev)")
     .option("--json", "print the resolved URL as the machine envelope instead of launching")
     .action(async (service, options) => runOpen(service, options, program.opts()));
+const token = program.command("token").description("Mint, list and revoke your personal access tokens (the NUSTACK_TOKEN a pipeline or agent uses)");
+token
+    .command("create")
+    .description("Mint a personal access token; the secret is printed once, on stdout alone")
+    .requiredOption("--label <label>", "a name for the token, unique among your live ones")
+    .option("--expires <days>", "days until the token expires (1–365); no expiry when omitted")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runTokenCreate(options, program.opts()));
+token
+    .command("list")
+    .description("List your personal access tokens (never a secret)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runTokenList(options, program.opts()));
+token
+    .command("revoke <token-id>")
+    .description("Revoke a personal access token; it stops working on the next request")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (tokenId, options) => runTokenRevoke(tokenId, options, program.opts()));
 const device = program.command("device").description("Inspect your signed-in devices and end this machine's access");
 device
     .command("list")

package/dist/lib/auth_grant.js

@@ -279,6 +279,28 @@ export async function revokeGrant(input) {
         return "unreachable";
     }
 }
+export const ENV_TOKEN_VARIABLE = "NUSTACK_TOKEN";
+export const PERSONAL_TOKEN_PREFIX = "nst_pat_";
+export function envToken() {
+    const raw = process.env[ENV_TOKEN_VARIABLE]?.trim();
+    if (!raw)
+        return null;
+    const halves = raw.startsWith(PERSONAL_TOKEN_PREFIX) ? raw.slice(PERSONAL_TOKEN_PREFIX.length).split("_") : [];
+    if (halves.length !== 2 || !halves[0] || !halves[1]) {
+        return {
+            kind: "malformed",
+            message: `${ENV_TOKEN_VARIABLE} is not a NuStack personal access token — expected \`${PERSONAL_TOKEN_PREFIX}<id>_<secret>\`, as \`nustack token create\` prints it.`,
+        };
+    }
+    return { kind: "ok", token: raw };
+}
+export class TokenRefusedError extends Error {
+    code = "TOKEN_REFUSED";
+    constructor() {
+        super(`${ENV_TOKEN_VARIABLE} was refused by NuStack — it is revoked, expired, or was minted for another NuStack. Mint a new one with \`nustack token create\`.`);
+        this.name = "TokenRefusedError";
+    }
+}
 async function readStoredGrant() {
     const deviceId = await getOrCreateDeviceId();
     resolvedDeviceId = deviceId;
@@ -332,6 +354,14 @@ async function refreshAndPersist(grant, audience, nustackBaseUrl) {
     return refreshed;
 }
 export async function resolveAccessToken(nustackBaseUrl, resource) {
+    const fromEnv = envToken();
+    if (fromEnv) {
+        if (fromEnv.kind === "malformed")
+            return { kind: "malformed_token", message: fromEnv.message };
+        const deviceId = resolvedDeviceId ?? (await getOrCreateDeviceId());
+        resolvedDeviceId = deviceId;
+        return { kind: "ok", session: { accessToken: fromEnv.token, userEmail: "", deviceId, authBaseUrl: "" } };
+    }
     const { deviceId, grant, failure } = await readStoredGrant();
     if (!grant) {
         if (failure)
@@ -363,6 +393,8 @@ export async function ensureAccessToken(nustackBaseUrl, resource) {
     return outcome.kind === "ok" ? { accessToken: outcome.session.accessToken, userEmail: outcome.session.userEmail } : null;
 }
 export async function refreshAccessTokenAfterRefusal(staleToken, nustackBaseUrl, resource) {
+    if (envToken())
+        return null;
     const { deviceId, grant } = await readStoredGrant();
     if (!grant)
         return null;

package/dist/lib/auth_recovery.js

@@ -13,6 +13,8 @@ function describeFailure(outcome) {
     if (outcome.kind === "needs_reauthorization") {
         return { code: "REAUTHORIZATION_REQUIRED", message: `This machine isn't approved for ${outcome.resource} yet — run \`nustack login\` to approve it.`, retryable: false };
     }
+    if (outcome.kind === "malformed_token")
+        return { code: "TOKEN_MALFORMED", message: outcome.message, retryable: false };
     return { code: "SIGNED_OUT", message: deadCredentialCopy(outcome.reason), retryable: false };
 }
 function reconnectingCopy(outcome) {
@@ -36,7 +38,7 @@ export async function ensureAuthWithRecovery(baseUrl, json) {
     if (outcome.kind === "ok")
         return { accessToken: outcome.session.accessToken, userEmail: outcome.session.userEmail };
     lastFailure = describeFailure(outcome);
-    if (json || !isInteractive())
+    if (json || !isInteractive() || outcome.kind === "malformed_token")
         return null;
     p.log.warn(reconnectingCopy(outcome));
     const didLogin = await performDeviceLogin(baseUrl, process.cwd(), { reauthorize: true });

package/dist/lib/credential_store.js

@@ -0,0 +1,106 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureNuStackLayout, nustackHomeDir } from "./local_store/paths.js";
+import { libsecretStore, isLibsecretAvailable } from "./libsecret_store.js";
+const runFile = promisify(execFile);
+const DEFAULT_SECURITY_BIN = "/usr/bin/security";
+const SERVICE = "nustack-device";
+const OWNER_ONLY_FILE = 0o600;
+export class CredentialStoreUnavailableError extends Error {
+    constructor(name) {
+        super(`NUSTACK_CREDENTIAL_STORE=${name} names a store this machine does not have — unset it, or use \`file\`.`);
+        this.name = "CredentialStoreUnavailableError";
+    }
+}
+function securityBin() {
+    return process.env.NUSTACK_KEYCHAIN_BIN?.trim() || DEFAULT_SECURITY_BIN;
+}
+export function isKeychainAvailable() {
+    const override = process.env.NUSTACK_KEYCHAIN_BIN?.trim();
+    if (override)
+        return existsSync(override);
+    return process.platform === "darwin" && existsSync(DEFAULT_SECURITY_BIN);
+}
+export const keychainStore = {
+    name: "keychain",
+    async readRaw(account) {
+        try {
+            const { stdout } = await runFile(securityBin(), ["find-generic-password", "-s", SERVICE, "-a", account, "-w"]);
+            return stdout.trim();
+        }
+        catch {
+            return null;
+        }
+    },
+    async writeRaw(account, payload) {
+        await runFile(securityBin(), ["add-generic-password", "-U", "-s", SERVICE, "-a", account, "-w", payload]);
+    },
+    async deleteRaw(account) {
+        try {
+            await runFile(securityBin(), ["delete-generic-password", "-s", SERVICE, "-a", account]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+export function credentialsFilePath() {
+    return path.join(nustackHomeDir(), "credentials.json");
+}
+async function readCredentialsFile(account) {
+    try {
+        const raw = await readFile(credentialsFilePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        if (parsed.device_id !== account)
+            return null;
+        return raw.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export const fileStore = {
+    name: "file",
+    readRaw: readCredentialsFile,
+    async writeRaw(_account, payload) {
+        await ensureNuStackLayout();
+        const target = credentialsFilePath();
+        const staging = `${target}.${process.pid}.tmp`;
+        await writeFile(staging, `${payload}\n`, { encoding: "utf8", mode: OWNER_ONLY_FILE });
+        await rename(staging, target);
+    },
+    async deleteRaw(account) {
+        if (!(await readCredentialsFile(account)))
+            return false;
+        await rm(credentialsFilePath(), { force: true });
+        return true;
+    },
+};
+export function selectCredentialStore() {
+    const requested = (process.env.NUSTACK_CREDENTIAL_STORE ?? "auto").trim().toLowerCase();
+    if (requested === "keychain") {
+        if (!isKeychainAvailable())
+            throw new CredentialStoreUnavailableError(requested);
+        return keychainStore;
+    }
+    if (requested === "libsecret") {
+        if (!isLibsecretAvailable())
+            throw new CredentialStoreUnavailableError(requested);
+        return libsecretStore;
+    }
+    if (requested === "file")
+        return fileStore;
+    if (requested !== "auto")
+        throw new CredentialStoreUnavailableError(requested);
+    if (isKeychainAvailable())
+        return keychainStore;
+    if (isLibsecretAvailable())
+        return libsecretStore;
+    return fileStore;
+}

package/dist/lib/device_identity.js

@@ -1,22 +1,22 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { readFile, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import os from "node:os";
 import path from "node:path";
+import { ensureNuStackLayout, nustackHomeDir } from "./local_store/paths.js";
+import { writeFileSecure } from "./secure_file.js";
 function deviceIdFilePath() {
-    return path.join(os.homedir(), ".nustack", "device_id");
+    return path.join(nustackHomeDir(), "device_id");
 }
 export async function getOrCreateDeviceId() {
     const file = deviceIdFilePath();
-    const dir = path.dirname(file);
     if (existsSync(file)) {
         const existing = (await readFile(file, "utf8")).trim();
         if (existing)
             return existing;
     }
     const deviceId = `dev_${randomBytes(16).toString("hex")}`;
-    await mkdir(dir, { recursive: true });
-    await writeFile(file, `${deviceId}\n`, "utf8");
+    await ensureNuStackLayout();
+    await writeFileSecure(file, `${deviceId}\n`);
     return deviceId;
 }
 export async function clearDeviceId() {

package/dist/lib/device_keychain.js

@@ -1,18 +1,6 @@
-import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
-import { promisify } from "node:util";
-const runFile = promisify(execFile);
-const DEFAULT_SECURITY_BIN = "/usr/bin/security";
-const SERVICE = "nustack-device";
+import { selectCredentialStore } from "./credential_store.js";
+export { isKeychainAvailable } from "./credential_store.js";
 export const KEYCHAIN_SCHEMA_VERSION = 3;
-function securityBin() {
-    return process.env.NUSTACK_KEYCHAIN_BIN?.trim() || DEFAULT_SECURITY_BIN;
-}
-export function isKeychainAvailable() {
-    if (process.env.NUSTACK_KEYCHAIN_BIN)
-        return true;
-    return process.platform === "darwin" && existsSync(DEFAULT_SECURITY_BIN);
-}
 const REQUIRED_FIELDS = ["refresh_token", "auth_base_url", "issuer", "device_id", "user_email"];
 export function decodeCredential(raw) {
     let parsed;
@@ -51,7 +39,7 @@ export function mergeCredential(existing, update) {
 export async function writeDeviceCredential(input) {
     const stored = await readRawCredential(input.device_id);
     const payload = mergeCredential(stored, input);
-    await runFile(securityBin(), ["add-generic-password", "-U", "-s", SERVICE, "-a", input.device_id, "-w", JSON.stringify(payload)]);
+    await selectCredentialStore().writeRaw(input.device_id, JSON.stringify(payload));
 }
 export async function readDeviceCredential(deviceId) {
     const decoded = await readDecoded(deviceId);
@@ -70,32 +58,23 @@ async function readRawCredential(deviceId) {
     return decoded.reason === "older-schema" || decoded.reason === "future-schema" ? decoded.stored : null;
 }
 async function readDecoded(deviceId) {
+    const raw = await selectCredentialStore().readRaw(deviceId);
+    if (raw === null)
+        return null;
+    const decoded = decodeCredential(raw);
+    if (decoded.ok)
+        return decoded;
+    let stored = null;
     try {
-        const { stdout } = await runFile(securityBin(), ["find-generic-password", "-s", SERVICE, "-a", deviceId, "-w"]);
-        const decoded = decodeCredential(stdout.trim());
-        if (decoded.ok)
-            return decoded;
-        let stored = null;
-        try {
-            const parsed = JSON.parse(stdout.trim());
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
-                stored = parsed;
-        }
-        catch {
-            stored = null;
-        }
-        return { ...decoded, stored };
+        const parsed = JSON.parse(raw.trim());
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            stored = parsed;
     }
     catch {
-        return null;
+        stored = null;
     }
+    return { ...decoded, stored };
 }
 export async function deleteDeviceCredential(deviceId) {
-    try {
-        await runFile(securityBin(), ["delete-generic-password", "-s", SERVICE, "-a", deviceId]);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return selectCredentialStore().deleteRaw(deviceId);
 }

package/dist/lib/libsecret_store.js

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+const runFile = promisify(execFile);
+const DEFAULT_SECRET_TOOL_BIN = "/usr/bin/secret-tool";
+const SERVICE = "nustack-device";
+const LABEL = "NuStack device credential";
+function secretToolBin() {
+    return process.env.NUSTACK_SECRET_TOOL_BIN?.trim() || DEFAULT_SECRET_TOOL_BIN;
+}
+export function isLibsecretAvailable() {
+    if (process.env.NUSTACK_SECRET_TOOL_BIN)
+        return true;
+    return process.platform === "linux" && existsSync(DEFAULT_SECRET_TOOL_BIN);
+}
+function attributes(account) {
+    return ["service", SERVICE, "account", account];
+}
+export const libsecretStore = {
+    name: "libsecret",
+    async readRaw(account) {
+        try {
+            const { stdout } = await runFile(secretToolBin(), ["lookup", ...attributes(account)]);
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    },
+    writeRaw(account, payload) {
+        return new Promise((resolve, reject) => {
+            const child = execFile(secretToolBin(), ["store", `--label=${LABEL}`, ...attributes(account)], (error) => error ? reject(error) : resolve());
+            child.stdin?.end(payload);
+        });
+    },
+    async deleteRaw(account) {
+        if (!(await this.readRaw(account)))
+            return false;
+        try {
+            await runFile(secretToolBin(), ["clear", ...attributes(account)]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/dist/lib/nustack_client.js

@@ -1,6 +1,6 @@
 import { assertSafeNuStackUrl, assertSafeOpaqueId } from "./guards.js";
 import { createSseParser } from "./sse_framing.js";
-import { DEVICE_HEADER, knownDeviceId, refreshAccessTokenAfterRefusal, userAgent } from "./auth_grant.js";
+import { DEVICE_HEADER, envToken, knownDeviceId, refreshAccessTokenAfterRefusal, TokenRefusedError, userAgent } from "./auth_grant.js";
 import { getOrCreateDeviceId } from "./device_identity.js";
 const DEFAULT_NUSTACK_URL = "https://apps.nustack.ai";
 const REQUEST_TIMEOUT_MS = 10_000;
@@ -12,6 +12,8 @@ async function authorizedFetch(input, init = {}) {
     const bearer = headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
     if (response.status !== 401 || !bearer || isStreamBody(init.body))
         return response;
+    if (envToken())
+        throw new TokenRefusedError();
     const fresh = await refreshAccessTokenAfterRefusal(bearer).catch(() => null);
     if (!fresh)
         return response;
@@ -282,6 +284,46 @@ export async function listOrganizations(baseUrl, accessToken) {
     }
     return payload.data.items;
 }
+export class PersonalTokenRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PersonalTokenRequestError";
+    }
+}
+async function readTokenEnvelope(response, label) {
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || payload?.data === undefined) {
+        throw new PersonalTokenRequestError(payload?.error?.code ?? "REQUEST_FAILED", errorMessage(payload, response.status, label));
+    }
+    return payload.data;
+}
+export async function listPersonalTokens(baseUrl, accessToken) {
+    const response = await authorizedFetch(`${baseUrl}/api/v2/tokens`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const data = await readTokenEnvelope(response, "token list failed");
+    return Array.isArray(data.items) ? data.items : [];
+}
+export async function createPersonalToken(baseUrl, accessToken, params) {
+    const response = await authorizedFetch(`${baseUrl}/api/v2/tokens`, {
+        method: "POST",
+        headers: { ...authHeaders(accessToken), "Content-Type": "application/json" },
+        body: JSON.stringify(params),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    return readTokenEnvelope(response, "token create failed");
+}
+export async function revokePersonalToken(baseUrl, accessToken, tokenId) {
+    const response = await authorizedFetch(`${baseUrl}/api/v2/tokens/${encodeURIComponent(assertSafeOpaqueId("The token id", tokenId))}`, {
+        method: "DELETE",
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    return readTokenEnvelope(response, "token revoke failed");
+}
 export async function createOrganization(baseUrl, accessToken, params, idempotencyKey) {
     const response = await authorizedFetch(`${baseUrl}/api/v2/organizations`, {
         method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.10.0-dev.15",
+  "version": "0.10.0-dev.16",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -33,8 +33,8 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/nustack.studio": "0.0.0",
-    "@nurix/nustack.ui": "0.0.0"
+    "@nurix/nustack.ui": "0.0.0",
+    "@nurix/nustack.studio": "0.0.0"
   },
   "publishConfig": {
     "access": "public"