@typeship-ax/cli 0.8.0 → 0.9.1

package/src/console-login-check.ts

@@ -0,0 +1,88 @@
+import { openSync, readSync, closeSync, fstatSync, constants } from "node:fs";
+import { oauthJsonRequest } from "./oauth-request.js";
+import { sameConsoleLoginConfiguration, matchesConsoleBrowserEvidence, type ConsoleLoginCheck, type ConsoleLoginConfiguration } from "./console-login-contract.js";
+import { type OAuthLoginSession } from "./oauth-login.js";
+import { parseNamedCredentials, type CredentialSchemes, type NamedCredentials } from "./named-credentials.js";
+
+function readCheck(path: string): ConsoleLoginCheck {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    if (!fstatSync(fd).isFile()) throw new Error();
+    const buffer = Buffer.alloc(65_537);
+    let size = 0;
+    while (size < buffer.length) { const n = readSync(fd, buffer, size, buffer.length - size, null); if (!n) break; size += n; }
+    if (size > 65_536) throw new Error();
+    const value = JSON.parse(buffer.subarray(0, size).toString("utf8")) as ConsoleLoginCheck;
+    if (value.version !== 1 || typeof value.ticket !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(value.ticket) || !value.configuration || !Array.isArray(value.expectations) || !value.expectations.length || value.expectations.length > 3) throw new Error();
+    const endpoint = new URL(value.endpoint);
+    const development = endpoint.protocol === "http:" && ["127.0.0.1", "[::1]"].includes(endpoint.hostname);
+    if (!(endpoint.origin === "https://typeship.dev" || development) || endpoint.pathname !== "/api/authentication/browser" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error();
+    const remaining = Date.parse(value.expiresAt) - Date.now();
+    if (!Number.isFinite(remaining) || remaining <= 0 || remaining > 600_000) throw new Error();
+    return value;
+  } catch { throw new Error("Download a new login check from your Typeship Console and pass its JSON file to --console-check. Checks expire after ten minutes."); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** No traffic to Typeship occurs without the explicit --console-check action.
+ * Only the credentials selected for the identity read leave this process;
+ * refresh tokens and other stored logins are never sent to the Console. */
+export async function checkConsoleBrowserLogin(input: {
+  file: string;
+  configuration: ConsoleLoginConfiguration;
+  schemes: CredentialSchemes;
+  credentials: NamedCredentials;
+  login(timeoutMs: number): Promise<OAuthLoginSession>;
+  verify(credentials: NamedCredentials, expectations: ConsoleLoginCheck["expectations"]): Promise<void>;
+  progress(message: string): void;
+}): Promise<{ ok: true; method: "oauth_browser"; console_verified: true; revoked: boolean | null }> {
+  const check = readCheck(input.file);
+  if (!sameConsoleLoginConfiguration(input.configuration, check.configuration)) throw new Error("This CLI's authentication settings do not match the saved Target. Regenerate the CLI, select the matching environment, and download a new check.");
+  const send = async (body: Record<string, unknown>, timeoutMs = 30_000) => {
+    const response = await oauthJsonRequest(check.endpoint, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json" }, body: JSON.stringify({ ticket: check.ticket, ...body }) }, timeoutMs);
+    if (response.status === 422) throw new Error("Typeship could not verify this login. Check the expected identity, API permissions and saved Target settings, then download a new check.");
+    if (response.status !== 200 || response.data?.ok !== true) throw new Error("The Console check expired, was already used, changed, or could not be completed. Download a new check and try again.");
+    return response.data;
+  };
+  await send({ action: "inspect" });
+  let revoked: boolean | null = null;
+  try {
+    const supplied = parseNamedCredentials(input.credentials, input.schemes);
+    // Only a complete alternative that uses the fresh browser token proves
+    // browser access. An unrelated key-only alternative is not sufficient.
+    const requirement = input.configuration.requirements.find((entry) => {
+      const names = Object.keys(entry);
+      if (!names.some((name) => input.schemes[name]?.kind === "bearer") || !names.every((name) => input.schemes[name]?.kind === "bearer" || supplied[name] !== undefined)) return false;
+      const selected = input.configuration.requirements.find((candidate) => Object.keys(candidate).every((name) => names.includes(name)));
+      return selected && Object.keys(selected).some((name) => input.schemes[name]?.kind === "bearer");
+    });
+    if (!requirement) throw new Error("Supply the additional named credentials required by the identity read with --credentials @file or environment variables.");
+    input.progress("This check runs a temporary browser login. Typeship will receive only the access token and any additional credentials required for the identity read; refresh tokens stay on this computer.");
+    const session = await input.login(Math.max(1, Date.parse(check.expiresAt) - Date.now()));
+    try {
+      const evidence = { method: "oauth_browser" as const, issuer: session.issuer, clientId: session.clientId, redirectUri: session.redirectUri };
+      if (!matchesConsoleBrowserEvidence(input.configuration, evidence)) throw new Error("The browser login did not use the Target's client registration and native callback.");
+      const credentials: NamedCredentials = Object.fromEntries(Object.keys(requirement).map((name) => [name, input.schemes[name]!.kind === "bearer" ? session.accessToken : supplied[name]! ]));
+      await input.verify(credentials, check.expectations);
+      await send({ action: "complete", configuration: input.configuration, evidence, credentials, expectations: check.expectations });
+    } finally {
+      // Verification sessions never replace the customer's saved login.
+      // Revoke the temporary grant when the provider advertises an endpoint.
+      if (session.revocationUrl) {
+        try {
+          const response = await fetch(session.revocationUrl, { method: "POST", redirect: "error", credentials: "omit", signal: AbortSignal.timeout(10_000), headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ token: session.refreshToken ?? session.accessToken, token_type_hint: session.refreshToken ? "refresh_token" : "access_token", client_id: session.clientId }) });
+          void response.body?.cancel().catch(() => {});
+          revoked = response.status === 200;
+        } catch { revoked = false; }
+      }
+    }
+  } catch (error) {
+    // Report only that the attempt ended. Never send provider errors, identity
+    // values or credentials, and never replace the original local error. A
+    // consumed check rejects this report, preserving any completed API proof.
+    try { await send({ action: "fail" }, 5_000); } catch { /* Best effort; the Console can still expire the check. */ }
+    throw error;
+  }
+  return { ok: true, method: "oauth_browser", console_verified: true, revoked };
+}

package/src/console-login-contract.ts

@@ -0,0 +1,65 @@
+
+export interface ConsoleLoginConfiguration {
+  baseUrl: string;
+  environment: string | null;
+  operation: string;
+  request: { method: string; path: string; graphqlField: string | null; graphqlQuery: string | null };
+  requirements: Record<string, string[]>[];
+  issuer: string;
+  clientId: string;
+  discoveryUrl: string | null;
+  authorizationUrl: string | null;
+  tokenUrl: string | null;
+  redirectUri: string;
+  scopes: string[];
+  audience: string | null;
+  resource: string | null;
+}
+export interface ConsoleIdentityExpectation {
+  kind: "account" | "organization" | "user";
+  pointer: string;
+  expected: string | number;
+}
+export interface ConsoleLoginCheck {
+  version: 1;
+  endpoint: string;
+  ticket: string;
+  expiresAt: string;
+  configuration: ConsoleLoginConfiguration;
+  expectations: ConsoleIdentityExpectation[];
+}
+export interface ConsoleBrowserEvidence {
+  method: "oauth_browser";
+  issuer: string;
+  clientId: string;
+  redirectUri: string;
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => JSON.stringify(key) + ":" + canonical(item)).join(",") + "}";
+  return JSON.stringify(value) ?? "null";
+}
+
+/** Compare the generated product's own settings with the reviewed check.
+ * The downloaded file never supplies the CLI's OAuth or API destination. */
+export function sameConsoleLoginConfiguration(left: ConsoleLoginConfiguration, right: ConsoleLoginConfiguration): boolean {
+  const normalize = (value: ConsoleLoginConfiguration) => ({ ...value,
+    baseUrl: new URL(value.baseUrl).href,
+    scopes: [...new Set(value.scopes)].sort(),
+    requirements: value.requirements.map((entry) => Object.fromEntries(Object.entries(entry).map(([key, scopes]) => [key, [...new Set(scopes)].sort()]))),
+  });
+  try { return canonical(normalize(left)) === canonical(normalize(right)); } catch { return false; }
+}
+
+export function matchesConsoleBrowserEvidence(config: ConsoleLoginConfiguration, evidence: ConsoleBrowserEvidence): boolean {
+  try {
+    if (evidence.method !== "oauth_browser" || evidence.issuer !== config.issuer || evidence.clientId !== config.clientId) return false;
+    const configured = new URL(config.redirectUri), actual = new URL(evidence.redirectUri);
+    if (configured.protocol !== "http:" || !["127.0.0.1", "[::1]"].includes(configured.hostname) || configured.username || configured.password || configured.search || configured.hash) return false;
+    if (configured.port && configured.port !== actual.port) return false;
+    if (!actual.port) return false;
+    configured.port = actual.port;
+    return configured.href === actual.href;
+  } catch { return false; }
+}

package/src/core/http.ts

@@ -81,6 +81,23 @@ export class UnexpectedApiError extends ApiError<number, unknown> {
   }
 }
 
+/** A successful response declared JSON but carried a body that could not be parsed. */
+export class ResponseParseError extends Error {
+  readonly status: number;
+  readonly body: string;
+  readonly response: ResponseMeta;
+  override readonly cause?: unknown;
+
+  constructor(body: string, response: ResponseMeta, cause?: unknown) {
+    super("HTTP " + response.status + " response body was not valid JSON");
+    this.name = "ResponseParseError";
+    this.status = response.status;
+    this.body = body;
+    this.response = response;
+    this.cause = cause;
+  }
+}
+
 
 // ---------------------------------------------------------------------------
 // Optional runtime validation — zero-dependency, schema table in schemas.ts
@@ -222,7 +239,7 @@ function transportFailureMessage(method: string, url: string, cause: unknown): s
   return method + " " + url + " failed: " + detail;
 }
 
-/** The request never produced an HTTP response (network failure, timeout, abort). */
+/** The request failed before a complete HTTP response arrived (network failure, timeout, abort, or truncated body). */
 export class TransportError extends Error {
   override readonly cause?: unknown;
 
@@ -236,6 +253,7 @@ export class TransportError extends Error {
 type ErrorCtor = new (body: any, response: ResponseMeta) => ApiError<number, unknown>;
 
 export interface CoreRequest {
+  security?: Record<string, string[]>[];
   method: string;
   path: string;
   query?: Record<string, unknown>;
@@ -268,7 +286,39 @@ export interface RetryPolicy {
   retryNonIdempotent?: boolean;
 }
 
+export interface SecurityCredential {
+  headers?: Record<string, AuthValue>;
+  query?: Record<string, AuthValue>;
+}
+
+/** Resolve one complete alternative in spec order. Missing or incompatible
+ * combinations contribute no partial credentials. Anonymous operations send
+ * no generated credentials; explicit headers/hooks remain application owned. */
+function selectSecurity(requirements: Record<string, string[]>[], credentials: Record<string, SecurityCredential>): SecurityCredential {
+  for (const requirement of requirements) {
+    const names = Object.keys(requirement);
+    if (!names.length || names.some((name) => !Object.hasOwn(credentials, name))) continue;
+    const selected: SecurityCredential = { headers: Object.create(null), query: Object.create(null) };
+    const destinations = new Set<string>();
+    let conflict = false;
+    for (const name of names) {
+      for (const location of ["headers", "query"] as const) {
+        for (const [wire, value] of Object.entries(credentials[name]![location] ?? {})) {
+          const destination = location + ":" + (location === "headers" ? wire.toLowerCase() : wire);
+          if (destinations.has(destination)) conflict = true;
+          destinations.add(destination);
+          selected[location]![wire] = value;
+        }
+      }
+    }
+    if (!conflict) return selected;
+  }
+  return {};
+}
+
 export interface CoreConfig {
+  /** Named credentials are selected using each operation's requirements. */
+  credentials?: Record<string, SecurityCredential>;
   baseUrl: string;
   headers: Record<string, AuthValue>;
   /** Auth carried as query parameters (apiKey-in-query schemes). */
@@ -317,7 +367,7 @@ export interface DebugEvent {
   /** 1-based; >1 means this was a retry */
   attempt: number;
   requestId?: string;
-  /** transport failure message, when there was no response */
+  /** transport failure message, when the request failed before a complete response */
   error?: string;
 }
 
@@ -376,8 +426,14 @@ export class HttpCore {
     const policy: RetryPolicy = { ...this.config.retry, ...req.retry };
     const maxRetries = req.options?.maxRetries ?? policy.maxRetries ?? this.config.maxRetries;
     const timeoutMs = req.options?.timeoutMs ?? this.config.timeoutMs;
-    const retryAllowed = req.idempotent === true || req.method === "GET" || policy.retryNonIdempotent === true;
-    const retryableStatuses = policy.statuses ? new Set(policy.statuses) : RETRYABLE_STATUSES;
+    const retryAllowed =
+      req.idempotent === true ||
+      req.method === "GET" ||
+      req.idempotencyKey !== undefined ||
+      policy.retryNonIdempotent === true;
+    const retryableStatuses = policy.statuses
+      ? new Set(policy.statuses)
+      : RETRYABLE_STATUSES;
 
     // One key per logical call, reused on every retry — that's the point
     // of idempotency keys.
@@ -449,13 +505,14 @@ export class HttpCore {
         try {
           data = (await parseBody(response, req.method)) as T;
         } catch (cause) {
-          emitResponseDebug(response);
-          const error = new TransportError(
-            "The response body read was aborted before completing",
+          const parseError = cause instanceof ResponseParseError ? cause : undefined;
+          emitResponseDebug(response, parseError?.body);
+          const error = (parseError ?? new TransportError(
+            "The response body read failed before completing",
             cause,
-          ) as unknown as E;
+          )) as unknown as E;
           await this.config.onError?.(error, { method: req.method, path: req.path });
-          return { ok: false, error, response: meta(response) };
+          return { ok: false, error, response: parseError?.response ?? meta(response) };
         }
         emitResponseDebug(response, data);
         const responseMeta = meta(response, data);
@@ -527,8 +584,9 @@ export class HttpCore {
     attempt: number,
     autoIdempotencyKey?: string,
   ): Promise<Response> {
+    const selected = req.security && this.config.credentials ? selectSecurity(req.security, this.config.credentials) : {};
     const headers: Record<string, string> = {};
-    for (const [k, v] of Object.entries(this.config.headers)) {
+    for (const [k, v] of Object.entries({ ...this.config.headers, ...selected.headers })) {
       headers[k] = await resolveAuthValue(v);
     }
     if (req.idempotencyKey && autoIdempotencyKey) {
@@ -544,7 +602,7 @@ export class HttpCore {
 
     const context: RequestContext = {
       method: req.method,
-      url: await this.buildUrl(req),
+      url: await this.buildUrl(req, selected.query),
       headers,
       attempt,
     };
@@ -632,7 +690,7 @@ export class HttpCore {
     }
   }
 
-  private async buildUrl(req: CoreRequest): Promise<string> {
+  private async buildUrl(req: CoreRequest, authQuery?: Record<string, AuthValue>): Promise<string> {
     const base = this.config.baseUrl.replace(/\/+$/, "");
     const url = new URL(base + req.path);
     for (const [k, v] of Object.entries(req.query ?? {})) {
@@ -644,7 +702,7 @@ export class HttpCore {
         appendDeep(url.searchParams, k, v);
       }
     }
-    for (const [k, v] of Object.entries(this.config.query)) {
+    for (const [k, v] of Object.entries({ ...this.config.query, ...authQuery })) {
       url.searchParams.append(k, await resolveAuthValue(v));
     }
     return url.toString();
@@ -704,17 +762,28 @@ function serializeBody(req: CoreRequest): { body: NonNullable<RequestInit["body"
 
 async function parseBody(response: Response, method: string): Promise<unknown> {
   if (method === "HEAD" || response.status === 204 || response.status === 205) return undefined;
-  const contentType = response.headers.get("content-type") ?? "";
+  const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+  const mediaType = contentType.split(";", 1)[0]!.trim();
+  const slash = mediaType.indexOf("/");
+  const subtype = slash === -1 ? "" : mediaType.slice(slash + 1);
   try {
-    if (contentType.includes("json")) return await response.json();
+    if (subtype === "json" || subtype.endsWith("+json")) {
+      const body = await response.text();
+      if (body.length === 0) return undefined;
+      try {
+        return JSON.parse(body);
+      } catch (cause) {
+        throw new ResponseParseError(body, meta(response, body), cause);
+      }
+    }
     if (contentType.startsWith("text/")) return await response.text();
     if (response.body === null) return undefined;
     return await response.blob();
   } catch (cause) {
-    // A timed-out or aborted body read is a transport failure, not an
-    // empty body — surface it instead of faking success.
-    if (cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError")) throw cause;
-    return undefined;
+    if (cause instanceof ResponseParseError) throw cause;
+    // A timed-out, aborted, or prematurely terminated body is a transport
+    // failure, not an empty body — surface it instead of faking success.
+    throw cause;
   }
 }
 

package/src/credential-storage.ts

@@ -0,0 +1,183 @@
+import { spawnSync } from "node:child_process";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { FileCredentialStore, CredentialStorageError, type CredentialCodec } from "./oauth-session.js";
+
+export interface NativeCommandResult { status: number | null; stdout: string; stderr: string; error?: unknown }
+export type NativeCommand = (executable: string, args: string[], input?: string) => NativeCommandResult;
+export interface CredentialKeyStore {
+  readonly name: string;
+  read(): Buffer | null;
+  write(key: Buffer): void;
+  /** Used only when explicitly removing this wrapping key, not ordinary logout. */
+  remove(): void;
+}
+
+const nativeCommand: NativeCommand = (executable, args, input) => {
+  const result = spawnSync(executable, args, { input, encoding: "utf8", timeout: 15_000, maxBuffer: 64 * 1024, windowsHide: true, shell: false });
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "", ...(result.error ? { error: result.error } : {}) };
+};
+
+function unavailable(name: string, environmentName: string): never {
+  throw new CredentialStorageError("Cannot access " + name + ". Unlock or enable your OS credential store and retry. For a headless session, supply credentials through environment variables. Plaintext storage requires explicitly setting " + environmentName + "=file.");
+}
+function parseKey(value: string): Buffer {
+  const encoded = value.trim();
+  if (!/^[A-Za-z0-9+/]{43}=$/.test(encoded)) throw new CredentialStorageError("The OS credential key is invalid. Restore access to the original key before using the saved session.");
+  const key = Buffer.from(encoded, "base64");
+  if (key.length !== 32) throw new CredentialStorageError("The OS credential key is invalid.");
+  return key;
+}
+
+/** A small wrapping key avoids OS item-size limits; session files are encrypted
+ * separately so refresh rotation can retain the atomic file/lock transaction. */
+export function nativeCredentialKeyStore(path: string, platform: NodeJS.Platform = process.platform, run: NativeCommand = nativeCommand, environmentName = "CREDENTIAL_STORE"): CredentialKeyStore {
+  const failed = (name: string): never => unavailable(name, environmentName);
+  const identity = createHash("sha256").update(resolve(path)).digest("hex");
+  const service = "typeship.credentials." + identity;
+  const account = "session-key";
+  if (platform === "darwin") {
+    const name = "macOS Keychain";
+    const lookup = () => run("/usr/bin/security", ["find-generic-password", "-s", service, "-a", account, "-w"]);
+    return {
+      name,
+      read() {
+        const result = lookup();
+        if (!result.error && result.status === 44) return null; // errSecItemNotFound
+        if (result.error || result.status !== 0) return failed(name);
+        return parseKey(result.stdout);
+      },
+      write(key) {
+        // security's interactive command stream keeps the key off argv. All
+        // tokens below have a fixed safe alphabet; no shell or user text is run.
+        const input = "add-generic-password -U -s " + service + " -a " + account + " -w " + key.toString("base64") + "\n";
+        const result = run("/usr/bin/security", ["-i"], input);
+        if (result.error || result.status !== 0) return failed(name);
+        // Verify the write: an interactive tool's process status alone is not
+        // sufficient evidence that its command stored the requested item.
+        const saved = this.read();
+        if (!saved || !timingSafeEqual(saved, key)) return failed(name);
+      },
+      remove() {
+        const result = run("/usr/bin/security", ["delete-generic-password", "-s", service, "-a", account]);
+        if (result.error || (result.status !== 0 && result.status !== 44)) failed(name);
+      },
+    };
+  }
+  if (platform === "linux") {
+    const name = "Linux Secret Service (secret-tool)";
+    const attributes = ["service", service, "account", account];
+    return {
+      name,
+      read() {
+        const result = run("/usr/bin/secret-tool", ["lookup", ...attributes]);
+        if (!result.error && result.status === 1 && !result.stderr.trim()) return null;
+        if (result.error || result.status !== 0) return failed(name);
+        return parseKey(result.stdout);
+      },
+      write(key) {
+        const result = run("/usr/bin/secret-tool", ["store", "--label=CLI session encryption key", ...attributes], key.toString("base64"));
+        if (result.error || result.status !== 0) return failed(name);
+        const saved = this.read();
+        if (!saved || !timingSafeEqual(saved, key)) return failed(name);
+      },
+      remove() {
+        const result = run("/usr/bin/secret-tool", ["clear", ...attributes]);
+        if (result.error || result.status !== 0) failed(name);
+      },
+    };
+  }
+  if (platform === "win32") {
+    const name = "Windows DPAPI (current user)";
+    const keyPath = path + ".key";
+    const executable = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const script = `
+$ErrorActionPreference = 'Stop'
+try {
+  Add-Type -AssemblyName System.Security
+  $payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  $bytes = [Convert]::FromBase64String([string]$payload.data)
+  $entropy = [Text.Encoding]::UTF8.GetBytes([string]$payload.service)
+  $scope = [System.Security.Cryptography.DataProtectionScope]::CurrentUser
+  if ($payload.action -eq 'protect') { $result = [System.Security.Cryptography.ProtectedData]::Protect($bytes, $entropy, $scope) }
+  elseif ($payload.action -eq 'unprotect') { $result = [System.Security.Cryptography.ProtectedData]::Unprotect($bytes, $entropy, $scope) }
+  else { exit 1 }
+  [Console]::Out.Write([Convert]::ToBase64String($result))
+  exit 0
+} catch { exit 1 }
+`;
+    const crypt = (action: "protect" | "unprotect", data: string) => {
+      // EncodedCommand contains fixed code only. Sensitive data goes over stdin.
+      const result = run(executable, ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], JSON.stringify({ action, data, service }));
+      if (result.error || result.status !== 0 || !result.stdout.trim()) return failed(name);
+      return result.stdout.trim();
+    };
+    return {
+      name,
+      read() {
+        let wrapped: string;
+        try { wrapped = readFileSync(keyPath, "utf8"); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; return failed(name); }
+        return parseKey(crypt("unprotect", wrapped));
+      },
+      write(key) {
+        const wrapped = crypt("protect", key.toString("base64"));
+        const temporary = keyPath + "." + randomBytes(16).toString("hex") + ".tmp";
+        try {
+          writeFileSync(temporary, wrapped, { mode: 0o600, flag: "wx", flush: true });
+          renameSync(temporary, keyPath);
+        } finally { rmSync(temporary, { force: true }); }
+        const saved = this.read();
+        if (!saved || !timingSafeEqual(saved, key)) return failed(name);
+      },
+      remove() { rmSync(keyPath, { force: true }); },
+    };
+  }
+  return { name: "OS credential storage", read: () => failed("OS credential storage on this platform"), write: () => failed("OS credential storage on this platform"), remove: () => failed("OS credential storage on this platform") };
+}
+
+export function encryptedCredentialCodec(path: string, keyStore: CredentialKeyStore): CredentialCodec {
+  const associatedData = Buffer.from("cli-credentials-v1:" + resolve(path));
+  const key = (create: boolean) => {
+    const saved = keyStore.read();
+    if (saved) return saved;
+    if (!create || existsSync(path)) throw new CredentialStorageError("The encryption key for this saved session is missing. Restore the original OS credential store, or run logout --local to remove the saved encrypted session before logging in again.");
+    const generated = randomBytes(32);
+    keyStore.write(generated);
+    return generated;
+  };
+  return {
+    name: keyStore.name,
+    prepare() { key(true); },
+    encode(plaintext) {
+      const nonce = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", key(true), nonce);
+      cipher.setAAD(associatedData);
+      const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      return JSON.stringify({ version: 1, algorithm: "aes-256-gcm", nonce: nonce.toString("base64"), tag: cipher.getAuthTag().toString("base64"), ciphertext: ciphertext.toString("base64") });
+    },
+    decode(encoded) {
+      let envelope: { version?: unknown; algorithm?: unknown; nonce?: unknown; tag?: unknown; ciphertext?: unknown };
+      try { envelope = JSON.parse(encoded); } catch { throw new CredentialStorageError("Saved encrypted credentials are damaged. Restore the credential file before logging in again."); }
+      if (!envelope || envelope.version !== 1 || envelope.algorithm !== "aes-256-gcm" || typeof envelope.nonce !== "string" || typeof envelope.tag !== "string" || typeof envelope.ciphertext !== "string") throw new CredentialStorageError("Saved encrypted credentials use an invalid format.");
+      const secret = key(false);
+      try {
+        const nonce = Buffer.from(envelope.nonce, "base64"), tag = Buffer.from(envelope.tag, "base64");
+        if (nonce.length !== 12 || tag.length !== 16) throw new Error();
+        const decipher = createDecipheriv("aes-256-gcm", secret, nonce);
+        decipher.setAAD(associatedData); decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64")), decipher.final()]).toString("utf8");
+      } catch { throw new CredentialStorageError("Saved credentials could not be authenticated. Restore the original credential file and OS key; do not reuse this session."); }
+    },
+  };
+}
+
+/** OS protection is the default. Plaintext storage is an explicit, separate
+ * store for environments where the owner accepts that tradeoff. Never migrate
+ * or fall back silently when an OS service is unavailable. */
+export function createCredentialStore(directory: string, mode: string = "os", environmentName = "CREDENTIAL_STORE"): FileCredentialStore {
+  if (mode === "file") return new FileCredentialStore(join(directory, "credentials.json"));
+  if (mode !== "os") throw new CredentialStorageError(environmentName + " must be os or file.");
+  const path = join(directory, "credentials.enc");
+  return new FileCredentialStore(path, 40_000, encryptedCredentialCodec(path, nativeCredentialKeyStore(path, process.platform, nativeCommand, environmentName)));
+}