shipmail-cli 0.6.1 → 0.6.2

package/README.md

@@ -8,7 +8,22 @@ npx -y shipmail-cli --help
 
 ## Authentication
 
-Most commands require an API key. Create one in the Shipmail dashboard and export it:
+Sign in once through the browser, with no API key to copy:
+
+```bash
+shipmail login
+```
+
+The CLI opens Shipmail, you choose the organizations it may reach, and it saves the login in the
+macOS Keychain, in the Secret Service through `secret-tool` on Linux, or otherwise in
+`~/.config/shipmail/credentials.json`, readable only by you. The login refreshes itself.
+`shipmail login --no-browser` prints the URL without opening a browser. If the login can reach
+several organizations, pick one with `--organization org_...` or `SHIPMAIL_ORGANIZATION`, or save a
+default with `shipmail login --organization org_...`. `shipmail logout` revokes the login and
+deletes it.
+
+An API key still works and takes precedence over the login. Create one in the Shipmail dashboard
+and export it:
 
 ```bash
 export SHIPMAIL_API_KEY="sm_live_..."
@@ -31,7 +46,7 @@ shipmail domains verify dom_123
 shipmail mailboxes create --domain-id dom_123 --address hello --password-file ./mailbox-password.txt --display-name "Hello"
 shipmail mailboxes suspend mbx_123
 shipmail mailboxes resume mbx_123
-shipmail mailboxes forwarding-add mbx_123 --destination owner@example.net
+shipmail mailboxes forwarding-add mbx_123 --destination owner@example.net --recipient support@example.com
 shipmail mailboxes forwarding mbx_123
 shipmail mailboxes forwarding-remove mbx_123 fwd_123
 shipmail mailboxes rules mbx_123

package/dist/cli.d.ts

@@ -1,4 +1,27 @@
 #!/usr/bin/env node
+import { z } from 'zod';
+
+declare const storedLoginSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    clientId: z.ZodString;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodNumber;
+    tokenEndpoint: z.ZodString;
+    revocationEndpoint: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type StoredLogin = z.infer<typeof storedLoginSchema>;
+type CredentialBackend = {
+    readonly kind: "keychain" | "secret-tool" | "file";
+    read(baseUrl: string): Promise<StoredLogin | null>;
+    write(login: StoredLogin): Promise<void>;
+    delete(baseUrl: string): Promise<void>;
+};
+type CredentialStore = CredentialBackend & {
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+};
+
 type Output = {
     write(chunk: string): void;
 };
@@ -8,6 +31,9 @@ type RunCliOptions = {
     readonly stdout?: Output | undefined;
     readonly stderr?: Output | undefined;
     readonly fetch?: typeof fetch | undefined;
+    readonly credentialStore?: CredentialStore | undefined;
+    readonly openBrowser?: ((url: string) => void) | undefined;
+    readonly loginTimeoutMs?: number | undefined;
 };
 declare function runCli(argv: readonly string[], options?: RunCliOptions): Promise<number>;
 declare function isMainModule(moduleUrl?: string, argvPath?: string | undefined): boolean;

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { realpathSync } from "fs";
-import { readFile, writeFile } from "fs/promises";
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import { env as processEnv, exit, stderr, stdout } from "process";
 import { fileURLToPath } from "url";
 import {
@@ -14,8 +14,642 @@ import {
   WEBHOOK_EVENT_TYPES
 } from "shipmail";
 
+// src/credentials.ts
+import { spawn } from "child_process";
+import { randomBytes } from "crypto";
+import { constants } from "fs";
+import { access, chmod, link, mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { delimiter, dirname, join } from "path";
+import { z } from "zod";
+var KEYCHAIN_SERVICE = "shipmail-cli";
+var storedLoginSchema = z.object({
+  baseUrl: z.string(),
+  clientId: z.string(),
+  accessToken: z.string(),
+  refreshToken: z.string().optional(),
+  expiresAt: z.number(),
+  tokenEndpoint: z.string(),
+  revocationEndpoint: z.string().optional(),
+  organizationId: z.string().optional()
+});
+var fileContentsSchema = z.object({ logins: z.record(z.string(), storedLoginSchema) });
+function parseLogin(raw) {
+  try {
+    const parsed = storedLoginSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+var runCommand = (command, args, input) => new Promise((resolve, reject) => {
+  const child = spawn(command, [...args], { stdio: ["pipe", "pipe", "ignore"] });
+  let stdout2 = "";
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    stdout2 += chunk;
+  });
+  child.on("error", reject);
+  child.on("close", (code) => resolve({ code: code ?? 1, stdout: stdout2 }));
+  child.stdin.end(input ?? "");
+});
+var SECURITY_MAX_LINE = 4e3;
+var KEYCHAIN_ITEM_NOT_FOUND = 44;
+function securityQuote(value) {
+  if (/[\r\n]/.test(value)) throw new Error("A Keychain value cannot contain a line break.");
+  return `"${value.replace(/["\\]/g, (character) => `\\${character}`)}"`;
+}
+function keychainStore(run) {
+  return {
+    kind: "keychain",
+    async read(baseUrl2) {
+      const result = await run("security", [
+        "find-generic-password",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        baseUrl2,
+        "-w"
+      ]);
+      return result.code === 0 ? parseLogin(result.stdout.trim()) : null;
+    },
+    // The secret goes to security -i on stdin, never into argv, where ps could read it.
+    async write(login2) {
+      const command = [
+        "add-generic-password",
+        "-U",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        login2.baseUrl,
+        "-l",
+        "Shipmail CLI",
+        "-w",
+        JSON.stringify(login2)
+      ].map(securityQuote).join(" ");
+      if (command.length > SECURITY_MAX_LINE) {
+        throw new Error("The login is too large for the macOS Keychain.");
+      }
+      const result = await run("security", ["-i"], `${command}
+`);
+      if (result.code !== 0) throw new Error("Could not save the login to the macOS Keychain.");
+    },
+    async delete(baseUrl2) {
+      const result = await run("security", [
+        "delete-generic-password",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        baseUrl2
+      ]);
+      if (result.code !== 0 && result.code !== KEYCHAIN_ITEM_NOT_FOUND) {
+        throw new Error("Could not delete the login from the macOS Keychain.");
+      }
+    }
+  };
+}
+function secretToolStore(run) {
+  const attributes = (baseUrl2) => ["service", KEYCHAIN_SERVICE, "account", baseUrl2];
+  return {
+    kind: "secret-tool",
+    async read(baseUrl2) {
+      const result = await run("secret-tool", ["lookup", ...attributes(baseUrl2)]);
+      return result.code === 0 ? parseLogin(result.stdout.trim()) : null;
+    },
+    async write(login2) {
+      const result = await run(
+        "secret-tool",
+        ["store", "--label=Shipmail CLI", ...attributes(login2.baseUrl)],
+        JSON.stringify(login2)
+      );
+      if (result.code !== 0) throw new Error("Could not save the login with secret-tool.");
+    },
+    // secret-tool clear exits 0 when nothing matched as well, so any other exit is a failure.
+    async delete(baseUrl2) {
+      const result = await run("secret-tool", ["clear", ...attributes(baseUrl2)]);
+      if (result.code !== 0) throw new Error("Could not delete the login with secret-tool.");
+    }
+  };
+}
+function credentialsFilePath(env) {
+  const configHome = env["XDG_CONFIG_HOME"] || join(env["HOME"] || homedir(), ".config");
+  return join(configHome, "shipmail", "credentials.json");
+}
+function fileStore(path) {
+  const directory = dirname(path);
+  async function readAll() {
+    let raw;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch {
+      return {};
+    }
+    try {
+      const parsed = fileContentsSchema.safeParse(JSON.parse(raw));
+      return parsed.success ? parsed.data.logins : {};
+    } catch {
+      return {};
+    }
+  }
+  async function writeAll(logins) {
+    await mkdir(directory, { recursive: true, mode: 448 });
+    await chmod(directory, 448);
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify({ logins }, null, 2)}
+`, { mode: 384 });
+    await chmod(temporary, 384);
+    await rename(temporary, path);
+  }
+  return {
+    kind: "file",
+    async read(baseUrl2) {
+      return (await readAll())[baseUrl2] ?? null;
+    },
+    async write(login2) {
+      await writeAll({ ...await readAll(), [login2.baseUrl]: login2 });
+    },
+    async delete(baseUrl2) {
+      const logins = await readAll();
+      if (!(baseUrl2 in logins)) return;
+      const rest = { ...logins };
+      delete rest[baseUrl2];
+      await writeAll(rest);
+    }
+  };
+}
+var LOCK_WAIT_MS = 6e4;
+var LOCK_RETRY_MS = 50;
+function errorCode(error) {
+  return error instanceof Error && "code" in error ? error.code : void 0;
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) === "EPERM";
+  }
+}
+async function readLock(path) {
+  return readFile(path, "utf8").catch(() => null);
+}
+function lockHolder(content) {
+  const match = /^(\d+) [0-9a-f]+$/.exec(content);
+  return match?.[1] ? Number(match[1]) : null;
+}
+async function tryCreateLock(path, owner) {
+  const staged = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  await writeFile(staged, owner, { mode: 384, flag: "wx" });
+  try {
+    await link(staged, path);
+    return true;
+  } catch (error) {
+    if (errorCode(error) === "EEXIST") return false;
+    throw error;
+  } finally {
+    await unlink(staged).catch(() => void 0);
+  }
+}
+function abandoned(content) {
+  const holder = lockHolder(content);
+  return holder === null || !processAlive(holder);
+}
+async function breakLock(path, observed, owner) {
+  const breaker = `${path}.break`;
+  if (!await tryCreateLock(breaker, owner)) {
+    const content = await readLock(breaker);
+    if (content !== null && abandoned(content) && await readLock(breaker) === content) {
+      await unlink(breaker).catch(() => void 0);
+    }
+    return;
+  }
+  try {
+    if (await readLock(path) === observed) await unlink(path).catch(() => void 0);
+  } finally {
+    if (await readLock(breaker) === owner) await unlink(breaker).catch(() => void 0);
+  }
+}
+async function withFileLock(path, fn, waitMs = LOCK_WAIT_MS) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  const owner = `${process.pid} ${randomBytes(16).toString("hex")}`;
+  const deadline = Date.now() + waitMs;
+  while (!await tryCreateLock(path, owner)) {
+    if (Date.now() > deadline) {
+      throw new Error(
+        `Another shipmail command is using the saved login. If none is running, delete ${path}.`
+      );
+    }
+    const observed = await readLock(path);
+    if (observed !== null && abandoned(observed)) await breakLock(path, observed, owner);
+    await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+  }
+  try {
+    return await fn();
+  } finally {
+    if (await readLock(path) === owner) await unlink(path).catch(() => void 0);
+  }
+}
+async function onPath(command, env) {
+  for (const directory of (env["PATH"] ?? "").split(delimiter)) {
+    if (!directory) continue;
+    try {
+      await access(join(directory, command), constants.X_OK);
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+async function defaultCredentialStore(options) {
+  const path = credentialsFilePath(options.env);
+  const file = fileStore(path);
+  const lockPath = join(dirname(path), "credentials.lock");
+  const withLock = (fn) => withFileLock(lockPath, fn);
+  const fileNotice = () => options.notice(`Saved the login in ${path}, readable only by you. No system keychain found.`);
+  let native = null;
+  if (options.platform === "darwin") native = keychainStore(options.run);
+  else if (options.platform === "linux" && await onPath("secret-tool", options.env)) {
+    native = secretToolStore(options.run);
+  }
+  if (!native) {
+    return {
+      kind: "file",
+      read: file.read,
+      async write(login2) {
+        await file.write(login2);
+        fileNotice();
+      },
+      delete: file.delete,
+      withLock
+    };
+  }
+  const store = native;
+  return {
+    kind: store.kind,
+    async read(baseUrl2) {
+      return await file.read(baseUrl2) ?? await store.read(baseUrl2).catch(() => null);
+    },
+    async write(login2) {
+      try {
+        await store.write(login2);
+      } catch {
+        await file.write(login2);
+        fileNotice();
+        await store.delete(login2.baseUrl).catch(() => void 0);
+        return;
+      }
+      await file.delete(login2.baseUrl);
+    },
+    async delete(baseUrl2) {
+      const nativeError = await store.delete(baseUrl2).then(
+        () => null,
+        (error) => error instanceof Error ? error : new Error(String(error))
+      );
+      if (nativeError) throw nativeError;
+      await file.delete(baseUrl2);
+    },
+    withLock
+  };
+}
+
+// src/oauth.ts
+import { spawn as spawn2 } from "child_process";
+import { createHash, randomBytes as randomBytes2 } from "crypto";
+import { createServer } from "http";
+import { z as z2 } from "zod";
+var LOGIN_TIMEOUT_MS = 5 * 6e4;
+var REQUEST_TIMEOUT_MS = 3e4;
+var SCOPE = "openid profile email offline_access";
+var REGISTERED_REDIRECT_URI = "http://127.0.0.1/callback";
+var protectedResourceSchema = z2.object({
+  resource: z2.string(),
+  authorization_servers: z2.array(z2.string()).min(1)
+});
+var authorizationServerSchema = z2.object({
+  issuer: z2.string(),
+  authorization_endpoint: z2.string(),
+  token_endpoint: z2.string(),
+  registration_endpoint: z2.string().optional(),
+  revocation_endpoint: z2.string().optional(),
+  code_challenge_methods_supported: z2.array(z2.string()).optional()
+});
+var registrationSchema = z2.object({ client_id: z2.string().min(1) });
+var tokenSchema = z2.object({
+  access_token: z2.string().min(1),
+  token_type: z2.string(),
+  expires_in: z2.number().optional(),
+  refresh_token: z2.string().optional()
+});
+var oauthErrorSchema = z2.object({
+  error: z2.string(),
+  error_description: z2.string().optional()
+});
+var OAuthError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "OAuthError";
+  }
+};
+function trimSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+async function getJson(fetchFn, url) {
+  const response = await fetchFn(url, {
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok)
+    throw new Error(`Sign-in discovery failed: ${url} returned ${response.status}.`);
+  return response.json();
+}
+function parseOrThrow(schema, value, what) {
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) throw new Error(`The server sent an invalid ${what}.`);
+  return parsed.data;
+}
+function sameOrigin(url, origin, what) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`The server sent an invalid ${what}.`);
+  }
+  if (parsed.origin !== origin) throw new Error(`The ${what} is not on ${origin}.`);
+  return url;
+}
+async function discoverOAuthServer(apiBaseUrl, fetchFn) {
+  const origin = new URL(apiBaseUrl).origin;
+  const resource = `${origin}/api/v1`;
+  const protectedResource = parseOrThrow(
+    protectedResourceSchema,
+    await getJson(fetchFn, `${origin}/.well-known/oauth-protected-resource/api/v1`),
+    "protected resource document"
+  );
+  if (trimSlash(protectedResource.resource) !== resource) {
+    throw new Error(`The protected resource document is not for ${resource}.`);
+  }
+  const [issuer = ""] = protectedResource.authorization_servers;
+  const issuerUrl = new URL(sameOrigin(issuer, origin, "authorization server"));
+  const issuerPath = trimSlash(issuerUrl.pathname);
+  const metadata = parseOrThrow(
+    authorizationServerSchema,
+    await getJson(fetchFn, `${origin}/.well-known/oauth-authorization-server${issuerPath}`),
+    "authorization server document"
+  );
+  if (trimSlash(metadata.issuer) !== trimSlash(issuer)) {
+    throw new Error("The authorization server document names a different issuer.");
+  }
+  if (metadata.code_challenge_methods_supported && !metadata.code_challenge_methods_supported.includes("S256")) {
+    throw new Error("The authorization server does not support PKCE with S256.");
+  }
+  return {
+    resource,
+    authorizationEndpoint: sameOrigin(
+      metadata.authorization_endpoint,
+      origin,
+      "authorization endpoint"
+    ),
+    tokenEndpoint: sameOrigin(metadata.token_endpoint, origin, "token endpoint"),
+    registrationEndpoint: metadata.registration_endpoint === void 0 ? void 0 : sameOrigin(metadata.registration_endpoint, origin, "registration endpoint"),
+    revocationEndpoint: metadata.revocation_endpoint === void 0 ? void 0 : sameOrigin(metadata.revocation_endpoint, origin, "revocation endpoint")
+  };
+}
+async function oauthFailure(response, fallback) {
+  const body = await response.json().catch(() => null);
+  const parsed = oauthErrorSchema.safeParse(body);
+  if (!parsed.success)
+    return new OAuthError("server_error", `${fallback} (HTTP ${response.status}).`);
+  return new OAuthError(
+    parsed.data.error,
+    parsed.data.error_description ? `${fallback}: ${parsed.data.error_description}` : `${fallback}: ${parsed.data.error}`
+  );
+}
+async function registerClient(server, fetchFn) {
+  if (!server.registrationEndpoint) {
+    throw new Error("The authorization server does not allow client registration.");
+  }
+  const response = await fetchFn(server.registrationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify({
+      client_name: "Shipmail CLI",
+      application_type: "native",
+      redirect_uris: [REGISTERED_REDIRECT_URI],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+    }),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) throw await oauthFailure(response, "Client registration failed");
+  return parseOrThrow(registrationSchema, await response.json(), "client registration").client_id;
+}
+async function tokenRequest(tokenEndpoint, fetchFn, params, failure) {
+  const response = await fetchFn(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: new URLSearchParams(params).toString(),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) throw await oauthFailure(response, failure);
+  const tokens = parseOrThrow(tokenSchema, await response.json(), "token response");
+  if (tokens.token_type.toLowerCase() !== "bearer") {
+    throw new Error("The server issued an unsupported token type.");
+  }
+  return tokens;
+}
+function storedTokens(tokens, previousRefreshToken, now) {
+  const refreshToken = tokens.refresh_token ?? previousRefreshToken;
+  return {
+    accessToken: tokens.access_token,
+    ...refreshToken ? { refreshToken } : {},
+    expiresAt: now + (tokens.expires_in ?? 3600) * 1e3
+  };
+}
+async function refreshLogin(login2, fetchFn, now = Date.now()) {
+  if (!login2.refreshToken) {
+    throw new OAuthError("invalid_grant", "The login has expired and cannot be refreshed");
+  }
+  const tokens = await tokenRequest(
+    login2.tokenEndpoint,
+    fetchFn,
+    {
+      grant_type: "refresh_token",
+      refresh_token: login2.refreshToken,
+      client_id: login2.clientId,
+      resource: `${new URL(login2.baseUrl).origin}/api/v1`
+    },
+    "Token refresh failed"
+  );
+  return { ...login2, ...storedTokens(tokens, login2.refreshToken, now) };
+}
+async function revokeToken(revocationEndpoint, clientId, token, fetchFn) {
+  const response = await fetchFn(revocationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      token,
+      token_type_hint: "refresh_token",
+      client_id: clientId
+    }).toString(),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) throw await oauthFailure(response, "Token revocation failed");
+}
+function randomToken(bytes) {
+  return randomBytes2(bytes).toString("base64url");
+}
+function codeChallenge(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+function callbackPage(message) {
+  return `<!doctype html><meta charset="utf-8"><title>Shipmail CLI</title><p>${message}</p>
+`;
+}
+var LOOPBACK_ORIGIN = "http://127.0.0.1";
+function callbackTarget(target) {
+  if (!target?.startsWith("/")) return null;
+  try {
+    const url = new URL(target, LOOPBACK_ORIGIN);
+    return url.origin === LOOPBACK_ORIGIN ? url : null;
+  } catch {
+    return null;
+  }
+}
+async function startLoopbackListener(expectedState, timeoutMs) {
+  let settle;
+  const code = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  const server = createServer((request, response) => {
+    const plain = (status, message) => response.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" }).end(`${message}
+`);
+    if (request.method !== "GET") {
+      plain(405, "Method not allowed");
+      return;
+    }
+    const url = callbackTarget(request.url);
+    if (!url || url.pathname !== "/callback") {
+      plain(404, "Not found");
+      return;
+    }
+    const reply = (status, message) => response.writeHead(status, { "Content-Type": "text/html; charset=utf-8", Connection: "close" }).end(callbackPage(message));
+    if (url.searchParams.get("state") !== expectedState) {
+      reply(400, "This sign-in link does not match the CLI. Run shipmail login again.");
+      return;
+    }
+    const error = url.searchParams.get("error");
+    if (error) {
+      const description = url.searchParams.get("error_description");
+      reply(400, "Sign-in was not completed. You can close this tab.");
+      settle?.reject(new OAuthError(error, `Sign-in failed: ${description ?? error}`));
+      return;
+    }
+    const authorizationCode = url.searchParams.get("code");
+    if (!authorizationCode) {
+      reply(400, "The sign-in response had no code. Run shipmail login again.");
+      settle?.reject(new Error("The sign-in response had no authorization code."));
+      return;
+    }
+    reply(200, "Signed in to the Shipmail CLI. You can close this tab.");
+    settle?.resolve(authorizationCode);
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    server.close();
+    throw new Error("Could not open a local port for the sign-in callback.");
+  }
+  const { port } = address;
+  const timer = setTimeout(() => {
+    settle?.reject(
+      new Error("Timed out waiting for the browser sign-in. Run shipmail login again.")
+    );
+  }, timeoutMs);
+  return {
+    redirectUri: `http://127.0.0.1:${port}/callback`,
+    code,
+    close() {
+      clearTimeout(timer);
+      server.close();
+      server.closeAllConnections();
+    }
+  };
+}
+function openInBrowser(url) {
+  const [command, args, verbatim] = process.platform === "darwin" ? ["open", [url], false] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', `"${url}"`], true] : ["xdg-open", [url], false];
+  try {
+    const child = spawn2(command, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsVerbatimArguments: verbatim
+    });
+    child.on("error", () => void 0);
+    child.unref();
+  } catch {
+  }
+}
+async function login(options) {
+  const server = await discoverOAuthServer(options.baseUrl, options.fetch);
+  const existing = await options.store.read(options.baseUrl);
+  const clientId = existing?.clientId ?? await registerClient(server, options.fetch);
+  const verifier = randomToken(32);
+  const state = randomToken(16);
+  const listener = await startLoopbackListener(state, options.timeoutMs);
+  try {
+    const authorizeUrl = new URL(server.authorizationEndpoint);
+    authorizeUrl.search = new URLSearchParams({
+      response_type: "code",
+      client_id: clientId,
+      redirect_uri: listener.redirectUri,
+      scope: SCOPE,
+      state,
+      code_challenge: codeChallenge(verifier),
+      code_challenge_method: "S256",
+      resource: server.resource
+    }).toString();
+    options.print("Open this URL to sign in to Shipmail:");
+    options.print(authorizeUrl.toString());
+    options.openBrowser?.(authorizeUrl.toString());
+    const code = await listener.code;
+    const tokens = await tokenRequest(
+      server.tokenEndpoint,
+      options.fetch,
+      {
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: listener.redirectUri,
+        client_id: clientId,
+        code_verifier: verifier,
+        resource: server.resource
+      },
+      "Sign-in failed"
+    );
+    const organizationId = options.organizationId ?? existing?.organizationId;
+    const stored = {
+      baseUrl: options.baseUrl,
+      clientId,
+      ...storedTokens(tokens, void 0, Date.now()),
+      tokenEndpoint: server.tokenEndpoint,
+      ...server.revocationEndpoint ? { revocationEndpoint: server.revocationEndpoint } : {},
+      ...organizationId ? { organizationId } : {}
+    };
+    await options.store.withLock(() => options.store.write(stored));
+    return stored;
+  } finally {
+    listener.close();
+  }
+}
+
 // src/version.ts
-var VERSION = "0.6.1";
+var VERSION = "0.6.2";
 
 // src/cli.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -166,29 +800,152 @@ function baseUrl(parsed, env) {
   if (!raw) return DEFAULT_BASE_URL;
   return validateBaseUrl(raw, env["SHIPMAIL_ALLOW_INSECURE_BASE_URL"] === "1");
 }
-function requireApiKey(parsed, env) {
+var REFRESH_MARGIN_MS = 6e4;
+function cliEnv(options) {
+  return options.env ?? processEnv;
+}
+async function credentialStore(options) {
+  if (options.credentialStore) return options.credentialStore;
+  const errOut = options.stderr ?? stderr;
+  return defaultCredentialStore({
+    env: cliEnv(options),
+    platform: process.platform,
+    run: runCommand,
+    notice: (message) => errOut.write(`${message}
+`)
+  });
+}
+function isFresh(login2) {
+  return login2.expiresAt - Date.now() > REFRESH_MARGIN_MS;
+}
+function sameGeneration(a, b) {
+  return a.accessToken === b.accessToken && a.refreshToken === b.refreshToken;
+}
+async function freshLogin(stored, store, fetchFn) {
+  if (isFresh(stored)) return stored;
+  return store.withLock(async () => {
+    const current = await store.read(stored.baseUrl);
+    if (!current) throw new Error("You were signed out. Run shipmail login.");
+    if (isFresh(current)) return current;
+    try {
+      const refreshed = await refreshLogin(current, fetchFn);
+      const latest = await store.read(stored.baseUrl);
+      if (latest && sameGeneration(latest, current)) await store.write(refreshed);
+      return refreshed;
+    } catch (err) {
+      if (!(err instanceof OAuthError) || err.code !== "invalid_grant") throw err;
+      const latest = await store.read(stored.baseUrl);
+      if (latest && !sameGeneration(latest, current)) {
+        if (isFresh(latest)) return latest;
+        throw new Error(
+          "Your Shipmail login changed while it was refreshing. Run the command again.",
+          { cause: err }
+        );
+      }
+      if (latest) await store.delete(stored.baseUrl);
+      throw new Error("Your Shipmail login has expired or was revoked. Run shipmail login.", {
+        cause: err
+      });
+    }
+  });
+}
+async function resolveCredential(parsed, options) {
+  const env = cliEnv(options);
   const key = apiKey(parsed, env);
-  if (!key) {
-    throw new CliUsageError("Missing API key. Set SHIPMAIL_API_KEY or pass --api-key sm_live_...");
+  if (key) return { kind: "api-key", token: key };
+  const store = await credentialStore(options);
+  const stored = await store.read(baseUrl(parsed, env));
+  if (!stored) {
+    throw new CliUsageError(
+      "Not signed in. Run shipmail login, set SHIPMAIL_API_KEY, or pass --api-key sm_live_..."
+    );
   }
-  return key;
+  const current = await freshLogin(stored, store, options.fetch ?? fetch);
+  return {
+    kind: "oauth",
+    token: current.accessToken,
+    organizationId: getString(parsed.options, "organization") ?? env["SHIPMAIL_ORGANIZATION"] ?? current.organizationId
+  };
+}
+function organizationHeader(credential) {
+  return credential.kind === "oauth" && credential.organizationId ? { "X-Shipmail-Organization": credential.organizationId } : {};
 }
-function createClient(parsed, options) {
-  const env = options.env ?? processEnv;
+async function createClient(parsed, options) {
+  const env = cliEnv(options);
+  const credential = await resolveCredential(parsed, options);
   const config = {
-    apiKey: requireApiKey(parsed, env),
+    apiKey: credential.token,
     baseUrl: baseUrl(parsed, env),
+    defaultHeaders: organizationHeader(credential),
     ...options.fetch ? { fetch: options.fetch } : {}
   };
   return new ShipmailClient(config);
 }
+async function runLogin(parsed, options, out) {
+  const env = cliEnv(options);
+  const errOut = options.stderr ?? stderr;
+  const base = baseUrl(parsed, env);
+  const noBrowser = getBoolean(parsed.options, "no-browser") ?? false;
+  const stored = await login({
+    baseUrl: base,
+    fetch: options.fetch ?? fetch,
+    store: await credentialStore(options),
+    openBrowser: noBrowser ? null : options.openBrowser ?? openInBrowser,
+    print: (line) => errOut.write(`${line}
+`),
+    timeoutMs: options.loginTimeoutMs ?? LOGIN_TIMEOUT_MS,
+    organizationId: getString(parsed.options, "organization")
+  });
+  const organization = stored.organizationId ? ` Default organization: ${stored.organizationId}.` : "";
+  out.write(`Signed in to ${new URL(base).origin}.${organization}
+`);
+}
+async function runLogout(parsed, options, out) {
+  const env = cliEnv(options);
+  const errOut = options.stderr ?? stderr;
+  const base = baseUrl(parsed, env);
+  const origin = new URL(base).origin;
+  const store = await credentialStore(options);
+  const signedOut = await store.withLock(async () => {
+    const stored = await store.read(base);
+    if (!stored) return false;
+    if (stored.revocationEndpoint && stored.refreshToken) {
+      try {
+        await revokeToken(
+          stored.revocationEndpoint,
+          stored.clientId,
+          stored.refreshToken,
+          options.fetch ?? fetch
+        );
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        errOut.write(`Could not revoke the login at the server: ${reason}
+`);
+      }
+    }
+    const latest = await store.read(base);
+    if (latest && !sameGeneration(latest, stored)) {
+      throw new Error("A new login was saved while signing out. Run shipmail logout again.");
+    }
+    try {
+      await store.delete(base);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new Error(`${reason} The login is still saved on this computer.`, { cause: err });
+    }
+    return true;
+  });
+  out.write(signedOut ? `Signed out of ${origin}.
+` : `Not signed in to ${origin}.
+`);
+}
 function writeJson(out, value) {
   out.write(`${JSON.stringify(value, null, 2)}
 `);
 }
 async function readJsonInput(value) {
   if (value === void 0) return void 0;
-  const raw = value.startsWith("@") ? await readFile(value.slice(1), "utf8") : value;
+  const raw = value.startsWith("@") ? await readFile2(value.slice(1), "utf8") : value;
   try {
     return JSON.parse(raw);
   } catch {
@@ -197,7 +954,7 @@ async function readJsonInput(value) {
 }
 async function readTextInput(value) {
   if (value === void 0) return void 0;
-  if (value.startsWith("@")) return readFile(value.slice(1), "utf8");
+  if (value.startsWith("@")) return readFile2(value.slice(1), "utf8");
   return value;
 }
 function isJsonObject(value) {
@@ -353,7 +1110,9 @@ async function rawApiRequest(parsed, runOptions, method, path, body, authRequire
     ...parseHeaders(getStringList(parsed.options, "header"))
   };
   if (authRequired) {
-    headers["Authorization"] = `Bearer ${requireApiKey(parsed, env)}`;
+    const credential = await resolveCredential(parsed, runOptions);
+    headers["Authorization"] = `Bearer ${credential.token}`;
+    Object.assign(headers, organizationHeader(credential));
   } else {
     const key = apiKey(parsed, env);
     if (key) headers["Authorization"] = `Bearer ${key}`;
@@ -379,7 +1138,7 @@ async function rawApiRequest(parsed, runOptions, method, path, body, authRequire
 async function writeRawResponse(parsed, io, response) {
   const outputPath = getString(parsed.options, "output");
   if (outputPath) {
-    await writeFile(outputPath, Buffer.from(await response.arrayBuffer()));
+    await writeFile2(outputPath, Buffer.from(await response.arrayBuffer()));
     io.stdout.write(`${outputPath}
 `);
     return;
@@ -400,8 +1159,11 @@ function usage() {
   return `shipmail-cli v${VERSION}
 
 Usage:
+  shipmail login [--no-browser] [--organization org_...]
+  shipmail logout
   shipmail status
   shipmail capabilities
+  shipmail organization access
   shipmail api <METHOD> <PATH> [--data JSON|@file] [--output file]
   shipmail automations list
   shipmail automations create --name "Daily brief" --definition JSON|@file [--idempotency-key key]
@@ -431,7 +1193,7 @@ Usage:
   shipmail mailboxes identities <id>
   shipmail mailboxes rules <id>
   shipmail mailboxes forwarding <id>
-  shipmail mailboxes forwarding-add <id> --destination owner@example.com [--sender newsletter@example.com]
+  shipmail mailboxes forwarding-add <id> --destination owner@example.com [--sender newsletter@example.com] [--recipient support@example.com]
   shipmail mailboxes forwarding-remove <id> <forwarding-id>
   shipmail mailboxes delivery-routing <id>
   shipmail mailboxes delivery-routing-set <id> --mode keep|fixed|round-robin [--destination-mailbox-id mbx_...] [--fallback-mailbox-id mbx_...]
@@ -541,18 +1303,44 @@ Newsletter block prose:
 Newsletter feeds:
   --feed-entry-url <url>  Link this issue's Atom feed title to an http(s) URL instead of its Shipmail archive.
 
+Sign-in:
+  Run shipmail login once to sign in through the browser instead of using an API key.
+  Run shipmail login --help for details.
+
 Global options:
-  --api-key <key>       API key. Defaults to SHIPMAIL_API_KEY.
+  --api-key <key>       API key. Defaults to SHIPMAIL_API_KEY, then the shipmail login session.
+  --organization <id>   Organization for a login that can reach several. Defaults to
+                        SHIPMAIL_ORGANIZATION, then the one saved by shipmail login.
   --base-url <url>      API base URL. Defaults to SHIPMAIL_BASE_URL or ${DEFAULT_BASE_URL}.
   --header "K: V"       Extra header for the generic api command. Repeatable.
 
 Environment:
   SHIPMAIL_API_KEY      API key for authenticated commands.
+  SHIPMAIL_ORGANIZATION Organization ID sent with a shipmail login session.
   SHIPMAIL_BASE_URL     Optional API base URL. Must be https on shipmail.to.
   SHIPMAIL_ALLOW_INSECURE_BASE_URL=1
                         Permit a non-https or non-shipmail.to base URL (development only).
 `;
 }
+function loginUsage() {
+  return `Usage:
+  shipmail login [--no-browser] [--organization org_...]
+  shipmail logout
+
+shipmail login opens Shipmail in your browser. Sign in, choose the organizations the CLI may
+reach, and approve. The CLI then runs commands without an API key.
+
+  --no-browser          Print the sign-in URL without opening a browser.
+  --organization <id>   Save a default organization, for a login that can reach several.
+
+The login is saved in the macOS Keychain, in the Secret Service through secret-tool on Linux,
+or otherwise in $XDG_CONFIG_HOME/shipmail/credentials.json (~/.config/shipmail/ by default),
+readable only by you. It refreshes itself. An API key from --api-key or SHIPMAIL_API_KEY takes
+precedence over the login.
+
+shipmail logout revokes the login at Shipmail and deletes it from this computer.
+`;
+}
 function requirePositional(positional, index, label) {
   const value = positional[index];
   if (!value) throw new CliUsageError(`Missing ${label}.`);
@@ -775,7 +1563,7 @@ async function runMailboxes(client, parsed, out) {
     if (!passwordValue && !passwordFile && !generatePassword) {
       throw new CliUsageError("Missing --password, --password-file, or --generate-password.");
     }
-    const password = passwordFile ? (await readFile(passwordFile, "utf8")).replace(/\r?\n$/, "") : passwordValue;
+    const password = passwordFile ? (await readFile2(passwordFile, "utf8")).replace(/\r?\n$/, "") : passwordValue;
     const credentials = generatePassword ? { generate_password: true } : password ? { password } : void 0;
     if (!credentials) {
       throw new CliUsageError("Mailbox password must not be empty.");
@@ -912,7 +1700,8 @@ async function runMailboxes(client, parsed, out) {
         requirePositional(parsed.positional, 2, "mailbox id"),
         {
           destination: getRequiredString(parsed.options, "destination"),
-          sender: getString(parsed.options, "sender") ?? null
+          sender: getString(parsed.options, "sender") ?? null,
+          recipient: getString(parsed.options, "recipient") ?? null
         }
       )
     );
@@ -976,7 +1765,7 @@ async function runMailboxes(client, parsed, out) {
   if (subcommand === "stage-attachment") {
     const mailboxId = requirePositional(parsed.positional, 2, "mailbox id");
     const filePath = requirePositional(parsed.positional, 3, "file");
-    const data = await readFile(realpathSync(filePath));
+    const data = await readFile2(realpathSync(filePath));
     writeJson(
       out,
       await client.mailboxes.stageAttachment(mailboxId, {
@@ -990,14 +1779,14 @@ async function runMailboxes(client, parsed, out) {
   if (subcommand === "prepare-attachment-upload") {
     const mailboxId = requirePositional(parsed.positional, 2, "mailbox id");
     const filePath = requirePositional(parsed.positional, 3, "file");
-    const data = await readFile(realpathSync(filePath));
+    const data = await readFile2(realpathSync(filePath));
     writeJson(
       out,
       await client.mailboxes.prepareStagedAttachmentUpload(mailboxId, {
         filename: getString(parsed.options, "filename") ?? filePath.split(/[\\/]/).at(-1) ?? "attachment",
         content_type: getString(parsed.options, "content-type") ?? "application/octet-stream",
         size: data.byteLength,
-        sha256: createHash("sha256").update(data).digest("hex")
+        sha256: createHash2("sha256").update(data).digest("hex")
       })
     );
     return;
@@ -1795,7 +2584,7 @@ async function runNewsletterAssets(client, parsed, out, fetchImpl) {
   }
   if (subcommand === "upload") {
     const filePath = requirePositional(parsed.positional, 2, "file");
-    const data = await readFile(realpathSync(filePath));
+    const data = await readFile2(realpathSync(filePath));
     const filename = getString(parsed.options, "filename") ?? filePath.split(/[\\/]/).at(-1) ?? "newsletter-asset";
     const contentType = newsletterAssetContentType(
       filePath,
@@ -1806,7 +2595,7 @@ async function runNewsletterAssets(client, parsed, out, fetchImpl) {
       filename,
       content_type: contentType,
       size: data.byteLength,
-      sha256: createHash("sha256").update(data).digest("hex")
+      sha256: createHash2("sha256").update(data).digest("hex")
     });
     await putPreparedNewsletterBytes(fetchImpl, prepared.upload_url, prepared.upload_headers, data);
     if (prepared.kind === "video") {
@@ -1869,7 +2658,7 @@ function newsletterAssetContentType(filePath, declared) {
 async function readNewsletterVideoThumbnail(options) {
   const thumbnailPath = getString(options, "thumbnail");
   if (!thumbnailPath) throw new CliUsageError("Video uploads require --thumbnail <jpeg-file>.");
-  const bytes = await readFile(realpathSync(thumbnailPath));
+  const bytes = await readFile2(realpathSync(thumbnailPath));
   if (bytes.byteLength < 3 || bytes[0] !== 255 || bytes[1] !== 216 || bytes[2] !== 255) {
     throw new CliUsageError("--thumbnail must be a JPEG file.");
   }
@@ -2215,6 +3004,11 @@ ${JSON.stringify(err.body, null, 2)}
     const messageId = shipmailError instanceof ReconciliationRequiredError && shipmailError.messageId ? ` message_id=${shipmailError.messageId}` : "";
     errOut.write(`Error: ${shipmailError.message}${status}${requestId}${messageId}
 `);
+    if (shipmailError.actionUrl) {
+      const reason = shipmailError.reason ? ` (${shipmailError.reason})` : "";
+      errOut.write(`Ask the organization owner to open${reason}: ${shipmailError.actionUrl}
+`);
+    }
     return;
   }
   errOut.write(`Error: ${err instanceof Error ? err.message : String(err)}
@@ -2231,6 +3025,10 @@ async function runCli(argv, options = {}) {
 `);
       return 0;
     }
+    if ((command === "login" || command === "logout") && optionValue(parsed.options, "help")) {
+      out.write(loginUsage());
+      return 0;
+    }
     if (!command || command === "help" || command === "-h" || optionValue(parsed.options, "help")) {
       out.write(usage());
       return 0;
@@ -2260,8 +3058,21 @@ async function runCli(argv, options = {}) {
       await writeRawResponse(parsed, { stdout: out }, response);
       return 0;
     }
-    const client = createClient(parsed, options);
-    if (command === "automations") await runAutomations(client, parsed, out);
+    if (command === "login") {
+      await runLogin(parsed, options, out);
+      return 0;
+    }
+    if (command === "logout") {
+      await runLogout(parsed, options, out);
+      return 0;
+    }
+    const client = await createClient(parsed, options);
+    if (command === "organization") {
+      if (parsed.positional[1] !== "access") {
+        throw new CliUsageError("Unknown organization command.");
+      }
+      writeJson(out, await client.organization.access());
+    } else if (command === "automations") await runAutomations(client, parsed, out);
     else if (command === "domains") await runDomains(client, parsed, out);
     else if (command === "mailboxes") await runMailboxes(client, parsed, out);
     else if (command === "members") await runMembers(client, parsed, out);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipmail-cli",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Official CLI for the Shipmail API",
   "type": "module",
   "bin": {
@@ -41,7 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "shipmail": "0.6.2"
+    "shipmail": "0.6.3",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "tsup": "^8.4.0",