@nurix/nustack 0.10.0-dev.10

package/dist/lib/auth_grant.js

@@ -0,0 +1,398 @@
+import os from "node:os";
+import { createHash, randomBytes } from "node:crypto";
+import { assertSafeNuStackUrl } from "./guards.js";
+import { getOrCreateDeviceId } from "./device_identity.js";
+import { deleteDeviceCredential, readCredentialFailure, readDeviceCredential, writeDeviceCredential } from "./device_keychain.js";
+import { openLoopbackListener } from "./loopback.js";
+const REQUEST_TIMEOUT_MS = 10_000;
+const BOOTSTRAP_TIMEOUT_MS = 25_000;
+const ACCESS_TOKEN_SKEW_MS = 30_000;
+const LOOPBACK_TIMEOUT_MS = 10 * 60_000;
+const MACHINE_SCOPE = "offline_access";
+export const CLI_CODE_PAGE_PATH = "/pages/cli-code";
+export const DEVICE_HEADER = "X-NuStack-Device";
+export function deadCredentialCopy(reason) {
+    if (reason === "older-schema")
+        return "This machine's sign-in predates the current NuStack CLI — run `nustack login` to sign in again.";
+    if (reason === "invalid_grant")
+        return "Your sign-in on this device is no longer valid — run `nustack login` to reconnect.";
+    return "Signed out on this device — run `nustack login` first.";
+}
+let cliVersion = "0";
+export function setCliVersion(version) {
+    if (version.trim())
+        cliVersion = version.trim();
+}
+export function userAgent() {
+    return `nustack-cli/${cliVersion} (${os.hostname()}; ${process.platform})`;
+}
+let resolvedDeviceId = null;
+let lastDeadReason = null;
+export function knownDeviceId() {
+    return resolvedDeviceId;
+}
+export function signedOutReason() {
+    return lastDeadReason;
+}
+export function signedOutCopy() {
+    return deadCredentialCopy(lastDeadReason);
+}
+export async function fetchAuthConfig(nustackBaseUrl) {
+    const response = await fetch(`${nustackBaseUrl}/api/v1/auth/config`, {
+        headers: { Accept: "application/json", "User-Agent": userAgent() },
+        signal: AbortSignal.timeout(BOOTSTRAP_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || typeof payload?.auth_base_url !== "string" || typeof payload?.client_id !== "string") {
+        throw new Error(`this NuStack does not describe its auth service (HTTP ${response.status}) — it may predate machine grants`);
+    }
+    const resources = Array.isArray(payload.resources) ? payload.resources.filter((r) => typeof r === "string") : [];
+    if (resources.length === 0)
+        throw new Error("this NuStack names no resource for a machine to hold — its auth configuration is incomplete");
+    return { authBaseUrl: assertSafeNuStackUrl(payload.auth_base_url), clientId: payload.client_id, resources };
+}
+export async function discover(authBaseUrl) {
+    const response = await fetch(`${authBaseUrl}/api/auth/.well-known/openid-configuration`, {
+        headers: { Accept: "application/json", "User-Agent": userAgent() },
+        signal: AbortSignal.timeout(BOOTSTRAP_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.issuer || !payload.authorization_endpoint || !payload.token_endpoint) {
+        throw new Error(`the auth service at ${authBaseUrl} published no usable discovery document (HTTP ${response.status})`);
+    }
+    return {
+        issuer: payload.issuer,
+        authorizationEndpoint: payload.authorization_endpoint,
+        tokenEndpoint: payload.token_endpoint,
+        revocationEndpoint: payload.revocation_endpoint ?? `${authBaseUrl}/api/auth/oauth2/revoke`,
+    };
+}
+export function mintPkce() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge, state: randomBytes(16).toString("base64url") };
+}
+export function buildAuthorizeUrl(config, discovery, request) {
+    const url = new URL(discovery.authorizationEndpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", config.clientId);
+    url.searchParams.set("redirect_uri", request.redirectUri);
+    url.searchParams.set("scope", MACHINE_SCOPE);
+    url.searchParams.set("state", request.pkce.state);
+    url.searchParams.set("code_challenge", request.pkce.challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    for (const resource of config.resources)
+        url.searchParams.append("resource", resource);
+    if (request.force)
+        url.searchParams.set("prompt", "login");
+    return url.toString();
+}
+export function cliCodePageUrl(authBaseUrl) {
+    return `${authBaseUrl}${CLI_CODE_PAGE_PATH}`;
+}
+export async function exchangeCode(config, discovery, input) {
+    const form = new URLSearchParams({
+        grant_type: "authorization_code",
+        code: input.code,
+        code_verifier: input.verifier,
+        redirect_uri: input.redirectUri,
+        client_id: config.clientId,
+    });
+    for (const resource of config.resources)
+        form.append("resource", resource);
+    const response = await fetch(discovery.tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", "User-Agent": userAgent() },
+        body: form.toString(),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || typeof payload?.access_token !== "string") {
+        if (payload?.error === "invalid_grant")
+            throw new Error("That code expired or was already used — run `nustack login` again.");
+        throw new Error(payload?.error_description ?? payload?.error ?? `the auth service refused the code (HTTP ${response.status})`);
+    }
+    if (typeof payload.refresh_token !== "string" || !payload.refresh_token) {
+        throw new Error("The auth service issued no refresh token — the sign-in cannot be kept on this machine.");
+    }
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token,
+        expiresInSeconds: typeof payload.expires_in === "number" ? payload.expires_in : 0,
+    };
+}
+export function decodeJwtPayload(token) {
+    const segment = token.split(".")[1];
+    if (!segment)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function persistGrant(config, discovery, issued) {
+    const deviceId = await getOrCreateDeviceId();
+    resolvedDeviceId = deviceId;
+    const claims = decodeJwtPayload(issued.accessToken);
+    const userEmail = typeof claims?.email === "string" ? claims.email : "";
+    const apiResource = config.resources[0];
+    await writeDeviceCredential({
+        refresh_token: issued.refreshToken,
+        auth_base_url: config.authBaseUrl,
+        issuer: discovery.issuer,
+        device_id: deviceId,
+        user_email: userEmail,
+        granted_resources: config.resources,
+        client_id: config.clientId,
+        access_tokens: { [apiResource]: { token: issued.accessToken, expires_at_ms: Date.now() + issued.expiresInSeconds * 1000 } },
+    });
+    lastDeadReason = null;
+    return { userEmail, deviceId, authBaseUrl: config.authBaseUrl };
+}
+export async function prepareLogin(nustackBaseUrl) {
+    const config = await fetchAuthConfig(nustackBaseUrl);
+    const discovery = await discover(config.authBaseUrl);
+    return { config, discovery };
+}
+export async function loginWithPastedCode(ctx, steps) {
+    const pkce = mintPkce();
+    const redirectUri = cliCodePageUrl(ctx.config.authBaseUrl);
+    steps.onAuthorizeUrl(buildAuthorizeUrl(ctx.config, ctx.discovery, { redirectUri, pkce, force: steps.force }));
+    const code = (await steps.promptForCode()).trim();
+    if (!code)
+        throw new Error("No code was entered — run `nustack login` again.");
+    const issued = await exchangeCode(ctx.config, ctx.discovery, { code, verifier: pkce.verifier, redirectUri });
+    return persistGrant(ctx.config, ctx.discovery, issued);
+}
+export async function loginWithLoopback(ctx, steps) {
+    const pkce = mintPkce();
+    const listener = await openLoopbackListener(pkce.state);
+    let timer = null;
+    try {
+        steps.onAuthorizeUrl(buildAuthorizeUrl(ctx.config, ctx.discovery, { redirectUri: listener.redirectUri, pkce, force: steps.force }));
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("Timed out waiting for the browser — run `nustack login` again, or `nustack login --manual`.")), steps.timeoutMs ?? LOOPBACK_TIMEOUT_MS);
+        });
+        const switched = steps.switchToPaste ? steps.switchToPaste().then(() => "paste") : new Promise(() => { });
+        const outcome = await Promise.race([listener.callback.then((callback) => ({ callback })), switched, timeout]);
+        if (outcome === "paste") {
+            await listener.close();
+            return loginWithPastedCode(ctx, steps);
+        }
+        const { callback } = outcome;
+        if (callback.iss !== null && callback.iss !== ctx.discovery.issuer) {
+            throw new Error(`The sign-in came back from ${callback.iss}, not from ${ctx.discovery.issuer} — refusing it.`);
+        }
+        const issued = await exchangeCode(ctx.config, ctx.discovery, { code: callback.code, verifier: pkce.verifier, redirectUri: listener.redirectUri });
+        return persistGrant(ctx.config, ctx.discovery, issued);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        await listener.close().catch(() => undefined);
+    }
+}
+export function readAnswer(status, body) {
+    const record = body && typeof body === "object" ? body : null;
+    const str = (key) => {
+        const value = record?.[key];
+        return typeof value === "string" && value.length > 0 ? value : null;
+    };
+    if (status >= 200 && status < 300) {
+        return { kind: "tokens", hasAccessToken: str("access_token") !== null, hasRefreshToken: str("refresh_token") !== null };
+    }
+    if (status >= 500)
+        return { kind: "unusable" };
+    return { kind: "refusal", code: str("error") };
+}
+export function classifyAnswer(answer) {
+    switch (answer.kind) {
+        case "tokens":
+            return answer.hasAccessToken ? "signed_in" : "transport_error";
+        case "refusal":
+            if (answer.code === "invalid_grant")
+                return "credential_dead";
+            if (answer.code === "invalid_target")
+                return "needs_reauthorization";
+            return "transport_error";
+        default:
+            return "transport_error";
+    }
+}
+export function classifyRefresh(status, body) {
+    return classifyAnswer(readAnswer(status, body));
+}
+export async function refreshGrant(tokenEndpoint, refreshToken, resource, clientId) {
+    const form = new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: clientId, resource });
+    const response = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", "User-Agent": userAgent() },
+        body: form.toString(),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    switch (classifyRefresh(response.status, payload)) {
+        case "signed_in":
+            return {
+                kind: "minted",
+                accessToken: payload.access_token,
+                expiresInSeconds: typeof payload.expires_in === "number" ? payload.expires_in : 0,
+                ...(typeof payload.refresh_token === "string" ? { rotatedRefreshToken: payload.refresh_token } : {}),
+            };
+        case "credential_dead":
+            return { kind: "dead", reason: "invalid_grant" };
+        case "needs_reauthorization":
+            return { kind: "needs_reauthorization", resource };
+        default:
+            throw new Error(`token refresh failed: HTTP ${response.status}`);
+    }
+}
+function isAlreadyEnded(status, payload) {
+    if (status !== 400 || !payload)
+        return false;
+    if (payload.error === "invalid_grant")
+        return true;
+    return payload.error === "invalid_request" && /revoked|not found|expired|invalid/i.test(payload.error_description ?? "");
+}
+export async function revokeGrant(input) {
+    try {
+        const endpoint = await discover(input.authBaseUrl)
+            .then((d) => d.revocationEndpoint)
+            .catch(() => `${input.authBaseUrl}/api/auth/oauth2/revoke`);
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", "User-Agent": userAgent() },
+            body: new URLSearchParams({ token: input.refreshToken, token_type_hint: "refresh_token", client_id: input.clientId }).toString(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (response.ok)
+            return "revoked";
+        if (response.status >= 500)
+            return "unreachable";
+        const payload = (await response.json().catch(() => null));
+        return isAlreadyEnded(response.status, payload) ? "already_ended" : "refused";
+    }
+    catch {
+        return "unreachable";
+    }
+}
+async function readStoredGrant() {
+    const deviceId = await getOrCreateDeviceId();
+    resolvedDeviceId = deviceId;
+    const credential = await readDeviceCredential(deviceId);
+    if (!credential) {
+        const failure = await readCredentialFailure(deviceId);
+        return { deviceId, grant: null, failure: failure === "older-schema" ? "older-schema" : null };
+    }
+    return {
+        deviceId,
+        failure: null,
+        grant: {
+            deviceId,
+            refreshToken: credential.refresh_token,
+            authBaseUrl: credential.auth_base_url,
+            issuer: credential.issuer,
+            userEmail: credential.user_email,
+            grantedResources: Array.isArray(credential.granted_resources) ? credential.granted_resources : [],
+            clientId: typeof credential.client_id === "string" ? credential.client_id : null,
+            accessTokens: credential.access_tokens ?? {},
+        },
+    };
+}
+async function clientIdFor(grant, nustackBaseUrl) {
+    if (grant.clientId)
+        return grant.clientId;
+    if (!nustackBaseUrl)
+        throw new Error("this machine's grant names no client and no NuStack URL was given to ask");
+    return (await fetchAuthConfig(nustackBaseUrl)).clientId;
+}
+async function refreshAndPersist(grant, audience, nustackBaseUrl) {
+    const clientId = await clientIdFor(grant, nustackBaseUrl);
+    const refreshed = await refreshGrant(`${grant.authBaseUrl}/api/auth/oauth2/token`, grant.refreshToken, audience, clientId);
+    if (refreshed.kind !== "minted")
+        return refreshed;
+    const claims = decodeJwtPayload(refreshed.accessToken);
+    const userEmail = (typeof claims?.email === "string" && claims.email) || grant.userEmail;
+    await writeDeviceCredential({
+        refresh_token: refreshed.rotatedRefreshToken ?? grant.refreshToken,
+        auth_base_url: grant.authBaseUrl,
+        issuer: grant.issuer,
+        device_id: grant.deviceId,
+        user_email: userEmail,
+        granted_resources: grant.grantedResources,
+        client_id: clientId,
+        access_tokens: {
+            ...grant.accessTokens,
+            [audience]: { token: refreshed.accessToken, expires_at_ms: Date.now() + refreshed.expiresInSeconds * 1000 },
+        },
+    });
+    return refreshed;
+}
+export async function resolveAccessToken(nustackBaseUrl, resource) {
+    const { deviceId, grant, failure } = await readStoredGrant();
+    if (!grant) {
+        if (failure)
+            lastDeadReason = failure;
+        return { kind: "none", reason: failure };
+    }
+    const audience = resource ?? grant.grantedResources[0];
+    if (!audience)
+        return { kind: "none", reason: null };
+    const cached = grant.accessTokens[audience];
+    if (cached && cached.expires_at_ms - ACCESS_TOKEN_SKEW_MS > Date.now()) {
+        return { kind: "ok", session: { accessToken: cached.token, userEmail: grant.userEmail, deviceId, authBaseUrl: grant.authBaseUrl } };
+    }
+    const refreshed = await refreshAndPersist(grant, audience, nustackBaseUrl);
+    if (refreshed.kind === "dead") {
+        lastDeadReason = refreshed.reason;
+        await deleteDeviceCredential(deviceId).catch(() => false);
+        return { kind: "dead", reason: refreshed.reason };
+    }
+    if (refreshed.kind === "needs_reauthorization")
+        return { kind: "needs_reauthorization", resource: audience };
+    lastDeadReason = null;
+    const claims = decodeJwtPayload(refreshed.accessToken);
+    const userEmail = (typeof claims?.email === "string" && claims.email) || grant.userEmail;
+    return { kind: "ok", session: { accessToken: refreshed.accessToken, userEmail, deviceId, authBaseUrl: grant.authBaseUrl } };
+}
+export async function ensureAccessToken(nustackBaseUrl, resource) {
+    const outcome = await resolveAccessToken(nustackBaseUrl, resource);
+    return outcome.kind === "ok" ? { accessToken: outcome.session.accessToken, userEmail: outcome.session.userEmail } : null;
+}
+export async function refreshAccessTokenAfterRefusal(staleToken, nustackBaseUrl, resource) {
+    const { deviceId, grant } = await readStoredGrant();
+    if (!grant)
+        return null;
+    const audience = resource ?? grant.grantedResources[0];
+    if (!audience)
+        return null;
+    const cached = grant.accessTokens[audience];
+    if (cached && cached.token !== staleToken)
+        return cached.token;
+    const refreshed = await refreshAndPersist(grant, audience, nustackBaseUrl);
+    if (refreshed.kind === "dead") {
+        lastDeadReason = refreshed.reason;
+        await deleteDeviceCredential(deviceId).catch(() => false);
+        return null;
+    }
+    if (refreshed.kind === "needs_reauthorization")
+        return null;
+    return refreshed.accessToken;
+}
+export async function readGrant() {
+    const { grant } = await readStoredGrant();
+    if (!grant)
+        return null;
+    return {
+        grantToken: grant.refreshToken,
+        authBaseUrl: grant.authBaseUrl,
+        issuer: grant.issuer,
+        deviceId: grant.deviceId,
+        userEmail: grant.userEmail,
+        grantedResources: grant.grantedResources,
+        clientId: grant.clientId,
+    };
+}

package/dist/lib/auth_recovery.js

@@ -0,0 +1,49 @@
+import * as p from "@clack/prompts";
+import { deadCredentialCopy, ensureAccessToken, resolveAccessToken } from "./auth_grant.js";
+import { performDeviceLogin } from "../commands/login.js";
+import { isInteractive } from "./interactive.js";
+let lastFailure = { code: "SIGNED_OUT", message: deadCredentialCopy(null), retryable: false };
+export function lastAuthFailure() {
+    return lastFailure;
+}
+function describeFailure(outcome) {
+    if (outcome === "unreachable") {
+        return { code: "AUTH_UNAVAILABLE", message: "Couldn't reach the auth service to refresh this machine's sign-in — try again in a moment.", retryable: true };
+    }
+    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 };
+    }
+    return { code: "SIGNED_OUT", message: deadCredentialCopy(outcome.reason), retryable: false };
+}
+function reconnectingCopy(outcome) {
+    if (outcome.kind === "needs_reauthorization")
+        return `This machine isn't approved for ${outcome.resource} yet. Opening the browser to sign in…`;
+    if (outcome.kind === "dead")
+        return "This machine's access was revoked. Opening the browser to sign in…";
+    if (outcome.reason === "older-schema")
+        return "This machine's sign-in predates the current NuStack CLI. Opening the browser to sign in…";
+    return "Not signed in on this machine. Opening the browser to sign in…";
+}
+export async function ensureAuthWithRecovery(baseUrl, json) {
+    let outcome;
+    try {
+        outcome = await resolveAccessToken(baseUrl);
+    }
+    catch {
+        lastFailure = describeFailure("unreachable");
+        return null;
+    }
+    if (outcome.kind === "ok")
+        return { accessToken: outcome.session.accessToken, userEmail: outcome.session.userEmail };
+    lastFailure = describeFailure(outcome);
+    if (json || !isInteractive())
+        return null;
+    p.log.warn(reconnectingCopy(outcome));
+    const didLogin = await performDeviceLogin(baseUrl, process.cwd(), { reauthorize: true });
+    if (!didLogin)
+        return null;
+    return ensureAccessToken(baseUrl).catch(() => {
+        lastFailure = describeFailure("unreachable");
+        return null;
+    });
+}

package/dist/lib/browser_opener.js

@@ -0,0 +1,24 @@
+import { spawn } from "node:child_process";
+import { assertSafeBrowserUrl } from "./guards.js";
+export function launchBrowser(url) {
+    let safeUrl;
+    try {
+        safeUrl = assertSafeBrowserUrl(url);
+    }
+    catch {
+        return;
+    }
+    const override = process.env.NUSTACK_BROWSER_OPENER?.trim();
+    const [command, args] = override
+        ? [override, [safeUrl]]
+        : process.platform === "darwin"
+            ? ["open", [safeUrl]]
+            : process.platform === "win32"
+                ? ["cmd", ["/c", "start", "", safeUrl]]
+                : ["xdg-open", [safeUrl]];
+    try {
+        spawn(command, args, { detached: true, stdio: "ignore" }).unref();
+    }
+    catch {
+    }
+}

package/dist/lib/device_identity.js

@@ -0,0 +1,28 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+function deviceIdFilePath() {
+    return path.join(os.homedir(), ".nustack", "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");
+    return deviceId;
+}
+export async function clearDeviceId() {
+    const file = deviceIdFilePath();
+    if (!existsSync(file))
+        return false;
+    await rm(file, { force: true });
+    return true;
+}

package/dist/lib/device_keychain.js

@@ -0,0 +1,101 @@
+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";
+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;
+    try {
+        parsed = JSON.parse(raw.trim());
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return { ok: false, reason: "malformed" };
+    const payload = parsed;
+    if (typeof payload.schema_version !== "number")
+        return { ok: false, reason: "missing-field" };
+    if (payload.schema_version > KEYCHAIN_SCHEMA_VERSION)
+        return { ok: false, reason: "future-schema" };
+    if (payload.schema_version < KEYCHAIN_SCHEMA_VERSION)
+        return { ok: false, reason: "older-schema" };
+    for (const field of REQUIRED_FIELDS) {
+        if (typeof payload[field] !== "string")
+            return { ok: false, reason: "missing-field" };
+    }
+    return { ok: true, payload };
+}
+export function mergeCredential(existing, update) {
+    const sameVersion = existing?.schema_version === KEYCHAIN_SCHEMA_VERSION;
+    const merged = { ...(sameVersion ? existing : {}) };
+    for (const [key, value] of Object.entries(update)) {
+        if (value === null || value === undefined)
+            continue;
+        merged[key] = value;
+    }
+    merged.schema_version = KEYCHAIN_SCHEMA_VERSION;
+    return merged;
+}
+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)]);
+}
+export async function readDeviceCredential(deviceId) {
+    const decoded = await readDecoded(deviceId);
+    return decoded?.ok ? decoded.payload : null;
+}
+export async function readCredentialFailure(deviceId) {
+    const decoded = await readDecoded(deviceId);
+    return decoded && !decoded.ok ? decoded.reason : null;
+}
+async function readRawCredential(deviceId) {
+    const decoded = await readDecoded(deviceId);
+    if (!decoded)
+        return null;
+    if (decoded.ok)
+        return decoded.payload;
+    return decoded.reason === "older-schema" || decoded.reason === "future-schema" ? decoded.stored : null;
+}
+async function readDecoded(deviceId) {
+    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 };
+    }
+    catch {
+        return null;
+    }
+}
+export async function deleteDeviceCredential(deviceId) {
+    try {
+        await runFile(securityBin(), ["delete-generic-password", "-s", SERVICE, "-a", deviceId]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/env_file.js

@@ -0,0 +1,75 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { assertSafeEnvKey, assertSafeEnvValue } from "./guards.js";
+import { writeFileSecure } from "./secure_file.js";
+const BLOCK_START = "# >>> nustack:managed — do not edit by hand; the nustack CLI rewrites this block >>>";
+const BLOCK_END = "# <<< nustack:managed <<<";
+export async function readManagedValues(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    const content = await readFile(filePath, "utf8");
+    const block = extractBlock(content);
+    if (block === null)
+        return {};
+    const values = {};
+    for (const line of block.split("\n")) {
+        const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+        if (match && match[1] !== undefined && match[2] !== undefined) {
+            values[match[1]] = match[2];
+        }
+    }
+    return values;
+}
+export async function upsertManagedValues(filePath, updates) {
+    const currentValues = await readManagedValues(filePath);
+    const mergedValues = { ...currentValues, ...updates };
+    const lines = Object.entries(mergedValues).map(([key, value]) => `${assertSafeEnvKey(key)}=${assertSafeEnvValue(key, value)}`);
+    const block = [BLOCK_START, ...lines, BLOCK_END].join("\n");
+    const existingContent = existsSync(filePath) ? await readFile(filePath, "utf8") : "";
+    await writeFileSecure(filePath, replaceBlock(existingContent, block));
+}
+export async function writeManagedValues(filePath, values) {
+    const lines = Object.entries(values).map(([key, value]) => `${assertSafeEnvKey(key)}=${assertSafeEnvValue(key, value)}`);
+    const block = [BLOCK_START, ...lines, BLOCK_END].join("\n");
+    const existingContent = existsSync(filePath) ? await readFile(filePath, "utf8") : "";
+    await writeFileSecure(filePath, replaceBlock(existingContent, block));
+}
+export async function removeManagedValues(filePath, keys) {
+    const currentValues = await readManagedValues(filePath);
+    const removedKeys = keys.filter((key) => key in currentValues);
+    if (removedKeys.length === 0)
+        return [];
+    for (const key of removedKeys)
+        delete currentValues[key];
+    await writeManagedValues(filePath, currentValues);
+    return removedKeys;
+}
+export async function ensureEnvGitignored(cwd) {
+    const gitignorePath = path.join(cwd, ".gitignore");
+    const content = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+    const hasEnvRule = content
+        .split("\n")
+        .some((line) => [".env", "*.env", ".env*"].includes(line.trim()));
+    if (hasEnvRule)
+        return false;
+    const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+    await appendFile(gitignorePath, `${separator}.env\n`);
+    return true;
+}
+function extractBlock(content) {
+    const start = content.indexOf(BLOCK_START);
+    const end = content.indexOf(BLOCK_END);
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    return content.slice(start + BLOCK_START.length, end).trim();
+}
+function replaceBlock(content, block) {
+    const start = content.indexOf(BLOCK_START);
+    const end = content.indexOf(BLOCK_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return content.slice(0, start) + block + content.slice(end + BLOCK_END.length);
+    }
+    const separator = content === "" ? "" : content.endsWith("\n") ? "\n" : "\n\n";
+    return content + separator + block + "\n";
+}