flaghoist 0.3.1 → 0.5.0

package/README.md

@@ -19,7 +19,8 @@ into `wrangler.toml`.
 ## Managing flags
 
 Point the CLI at your server with `--url` and `--token`, or set `FLAGS_URL` and
-`FLAGS_ADMIN_TOKEN`.
+`FLAGS_ADMIN_TOKEN`. On a server with user accounts, `flaghoist login --url <server>` signs you in
+once and saves a personal access token instead.
 
 ```bash
 flaghoist flag list
@@ -31,6 +32,18 @@ flaghoist flag rollout new-checkout 25
 Rollouts are sticky. A user who lands inside 25 percent stays inside it as you go to 50, so nobody
 flickers in and out between deploys.
 
+## Managing members
+
+On a server with user accounts turned on, admins invite and manage people from the command line
+too. Invite and reset commands print a link to send yourself, and the server emails it as well when it has an email sender set up.
+
+```bash
+flaghoist users invite ada@example.com --role editor
+flaghoist users list
+flaghoist users role ada@example.com admin
+flaghoist users reset ada@example.com
+```
+
 ## Owning the code
 
 ```bash

package/dist/chunk-TQ5S6NOA.js

@@ -0,0 +1,391 @@
+// src/config.ts
+import { parse } from "smol-toml";
+var DEFAULT_CONFIG = {
+  name: "team-flags",
+  storage: "cloudflare-kv",
+  platform: "cloudflare",
+  auth: { admin: "bearer-token", read: "api-key" },
+  dashboard: true
+};
+var STORAGE_KINDS = [
+  "cloudflare-kv",
+  "redis",
+  "postgres",
+  "sqlite",
+  "memory"
+];
+var PLATFORM_KINDS = ["cloudflare", "container"];
+function containerStorageDefault(storage) {
+  return storage === "cloudflare-kv" ? "postgres" : storage;
+}
+function asContainer(config) {
+  return { ...config, platform: "container", storage: containerStorageDefault(config.storage) };
+}
+function parseConfig(text) {
+  const raw = parse(text);
+  const name = typeof raw.name === "string" && raw.name ? raw.name : DEFAULT_CONFIG.name;
+  const storage = STORAGE_KINDS.includes(raw.storage) ? raw.storage : DEFAULT_CONFIG.storage;
+  const platform = raw.platform === "container" ? "container" : DEFAULT_CONFIG.platform;
+  const authRaw = typeof raw.auth === "object" && raw.auth !== null ? raw.auth : {};
+  const admin = authRaw.admin === "oidc" ? "oidc" : "bearer-token";
+  const allowedOrigins = Array.isArray(raw.allowedOrigins) ? raw.allowedOrigins.filter((x) => typeof x === "string") : void 0;
+  const dashboard = raw.dashboard !== false;
+  const accounts = parseAccounts(raw.accounts);
+  return {
+    name,
+    storage,
+    platform,
+    auth: { admin, read: "api-key" },
+    allowedOrigins,
+    dashboard,
+    ...accounts ? { accounts } : {}
+  };
+}
+function parseAccounts(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const table = raw;
+  const enabled = table.enabled === true;
+  const ssoRaw = typeof table.sso === "object" && table.sso !== null ? table.sso : null;
+  const sso = ssoRaw && typeof ssoRaw.issuer === "string" && typeof ssoRaw.clientId === "string" ? {
+    issuer: ssoRaw.issuer,
+    clientId: ssoRaw.clientId,
+    ...typeof ssoRaw.adminGroup === "string" && ssoRaw.adminGroup ? { adminGroup: ssoRaw.adminGroup } : {}
+  } : void 0;
+  return { enabled, ...sso ? { sso } : {} };
+}
+function serializeConfig(config) {
+  const lines = [
+    `name = ${JSON.stringify(config.name)}`,
+    `storage = ${JSON.stringify(config.storage)}`
+  ];
+  if (config.platform !== "cloudflare") {
+    lines.push(`platform = ${JSON.stringify(config.platform)}`);
+  }
+  if (config.allowedOrigins && config.allowedOrigins.length > 0) {
+    lines.push(`allowedOrigins = ${JSON.stringify(config.allowedOrigins)}`);
+  }
+  if (!config.dashboard) {
+    lines.push("dashboard = false");
+  }
+  lines.push(
+    "",
+    "[auth]",
+    `admin = ${JSON.stringify(config.auth.admin)}`,
+    `read = ${JSON.stringify(config.auth.read)}`
+  );
+  if (config.accounts) {
+    lines.push(
+      "",
+      "# Accounts read AUTH_PEPPER from the environment. Never put it in this file.",
+      "[accounts]",
+      `enabled = ${config.accounts.enabled}`
+    );
+    const sso = config.accounts.sso;
+    if (sso) {
+      lines.push(
+        "",
+        "# The client secret comes from SSO_CLIENT_SECRET in the environment.",
+        "[accounts.sso]",
+        `issuer = ${JSON.stringify(sso.issuer)}`,
+        `clientId = ${JSON.stringify(sso.clientId)}`
+      );
+      if (sso.adminGroup) lines.push(`adminGroup = ${JSON.stringify(sso.adminGroup)}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/setup.ts
+import { randomBytes } from "crypto";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { createInterface } from "readline/promises";
+var MIN_PEPPER_LENGTH = 32;
+var PLATFORMS = [
+  {
+    value: "cloudflare",
+    label: "Cloudflare Workers",
+    hint: "free plan, deploys in one command"
+  },
+  {
+    value: "container",
+    label: "Container, any host",
+    hint: "Render, Fly.io, Railway, a VPS, Kubernetes"
+  }
+];
+function storageChoices(platform) {
+  if (platform === "cloudflare") {
+    return [
+      { value: "cloudflare-kv", label: "Cloudflare KV", hint: "created for you on first deploy" },
+      { value: "redis", label: "Redis", hint: "Upstash, over HTTP" },
+      { value: "postgres", label: "Postgres", hint: "an HTTP-friendly host such as Neon" },
+      { value: "memory", label: "Memory", hint: "flags are lost on restart; for trying it out" }
+    ];
+  }
+  return [
+    { value: "postgres", label: "Postgres" },
+    { value: "redis", label: "Redis" },
+    { value: "sqlite", label: "SQLite", hint: "one file on a mounted volume" },
+    { value: "memory", label: "Memory", hint: "flags are lost on restart; for trying it out" }
+  ];
+}
+function generatePepper() {
+  return randomBytes(32).toString("hex");
+}
+var NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+function validName(name) {
+  return NAME_PATTERN.test(name);
+}
+async function collectSetup(asker, preset = {}) {
+  let name = preset.name ?? "";
+  while (!validName(name)) {
+    if (name)
+      asker.say("  Use lowercase letters, digits and hyphens, starting with a letter or digit.");
+    name = (await asker.text("Project name", DEFAULT_CONFIG.name)).trim().toLowerCase();
+  }
+  const platform = preset.platform ?? await asker.choice("Where will it run?", PLATFORMS, "cloudflare");
+  const choices = storageChoices(platform);
+  const presetStorage = preset.storage && platform === "container" ? containerStorageDefault(preset.storage) : preset.storage;
+  const storage = presetStorage && choices.some((c) => c.value === presetStorage) ? presetStorage : await asker.choice("Storage", choices, choices[0].value);
+  const accountsOn = preset.accounts ?? await asker.yesNo("Accounts and roles, so each person signs in as themselves?", true);
+  const secrets = {};
+  let pepperGenerated = false;
+  let sso;
+  if (accountsOn) {
+    asker.say("");
+    asker.say("  Accounts need an AUTH_PEPPER: a secret that protects stored passwords. With it, a");
+    asker.say("  stolen copy of your database reveals no password hashes an attacker can use.");
+    asker.say(
+      "  Losing it means everyone has to reset their password, so keep a copy somewhere safe."
+    );
+    const source = await asker.choice(
+      "AUTH_PEPPER",
+      [
+        { value: "generate", label: "Generate one for me", hint: "recommended" },
+        { value: "paste", label: "I have one, let me paste it" }
+      ],
+      "generate"
+    );
+    if (source === "paste") {
+      let pasted = "";
+      while (pasted.length < MIN_PEPPER_LENGTH) {
+        if (pasted) asker.say(`  It needs at least ${MIN_PEPPER_LENGTH} characters.`);
+        pasted = (await asker.secret("Paste your AUTH_PEPPER")).trim();
+      }
+      secrets.AUTH_PEPPER = pasted;
+    } else {
+      secrets.AUTH_PEPPER = generatePepper();
+      pepperGenerated = true;
+    }
+    const wantsSso = preset.sso ?? (preset.ssoIssuer !== void 0 || await asker.yesNo("Sign in with your company's identity provider (SSO)?", false));
+    if (wantsSso) {
+      const issuer = preset.ssoIssuer ?? await askUrl(asker, "Issuer URL (for example https://acme.okta.com)");
+      const clientId = preset.ssoClientId ?? await askRequired(asker, "Client ID");
+      const adminGroup = preset.ssoAdminGroup ?? (await asker.text("Group whose members become admins (blank for none)", "")).trim();
+      const clientSecret = (await asker.secret("Client secret (blank if your app is public, or to add it later)")).trim();
+      if (clientSecret) secrets.SSO_CLIENT_SECRET = clientSecret;
+      sso = { issuer, clientId, ...adminGroup ? { adminGroup } : {} };
+    }
+  }
+  const dashboard = preset.dashboard ?? await asker.yesNo("Serve the admin dashboard at /admin?", true);
+  const config = {
+    ...DEFAULT_CONFIG,
+    name,
+    platform,
+    storage,
+    dashboard,
+    ...accountsOn ? { accounts: { enabled: true, ...sso ? { sso } : {} } } : {}
+  };
+  return { config, secrets, pepperGenerated };
+}
+async function askRequired(asker, question) {
+  let answer = "";
+  while (!answer) {
+    answer = (await asker.text(question, "")).trim();
+    if (!answer && asker.interactive === false) {
+      throw new Error(
+        `SSO needs ${question.split(" (")[0].toLowerCase()}: pass --sso-issuer and --sso-client-id.`
+      );
+    }
+  }
+  return answer;
+}
+async function askUrl(asker, question) {
+  for (; ; ) {
+    const answer = await askRequired(asker, question);
+    try {
+      const url = new URL(answer);
+      if (url.protocol === "https:" || url.hostname === "localhost") return answer;
+    } catch {
+    }
+    if (asker.interactive === false) throw new Error(`--sso-issuer must be an https:// URL.`);
+    asker.say("  That needs to be an https:// URL.");
+  }
+}
+var GITIGNORE = [".env", ".dev.vars", "node_modules", ".wrangler", ""].join("\n");
+function writeSetup(dir, result) {
+  writeFileSync(join(dir, "flaghoist.toml"), serializeConfig(result.config));
+  if (Object.keys(result.secrets).length === 0) return {};
+  const envPath = join(dir, ".env");
+  const lines = [
+    "# Secrets for this Flaghoist project. Never commit this file.",
+    ...result.config.platform === "cloudflare" ? ["# `npx flaghoist deploy` sets these as secrets on your Worker."] : [
+      "# Pass them to your container host as environment variables, or run with --env-file .env."
+    ],
+    ...Object.entries(result.secrets).map(([key, value]) => `${key}=${value}`),
+    ""
+  ];
+  writeFileSync(envPath, lines.join("\n"), { mode: 384 });
+  const gitignorePath = join(dir, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, GITIGNORE);
+  } else {
+    const current = readFileSync(gitignorePath, "utf8");
+    if (!/^\.env$/m.test(current)) {
+      writeFileSync(gitignorePath, `${current.replace(/\n?$/, "\n")}.env
+`);
+    }
+  }
+  return { envPath };
+}
+function readEnvFile(path) {
+  if (!existsSync(path)) return {};
+  const out = {};
+  for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+    const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/i.exec(line);
+    if (match && !line.trim().startsWith("#"))
+      out[match[1]] = match[2].replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+function setupSummary(result, envWritten) {
+  const { config } = result;
+  const lines = [
+    "",
+    `  name       ${config.name}`,
+    `  platform   ${config.platform === "cloudflare" ? "Cloudflare Workers" : "container"}`,
+    `  storage    ${config.storage}`,
+    `  accounts   ${config.accounts?.enabled ? "on" : "off"}`,
+    `  sso        ${config.accounts?.sso ? config.accounts.sso.issuer : "off"}`,
+    `  dashboard  ${config.dashboard ? "on" : "off"}`
+  ];
+  if (result.pepperGenerated && result.secrets.AUTH_PEPPER) {
+    lines.push(
+      "",
+      "  Your AUTH_PEPPER (save it in your password manager now; it is not shown again):",
+      "",
+      `    ${result.secrets.AUTH_PEPPER}`
+    );
+  }
+  if (envWritten) {
+    lines.push(
+      "",
+      config.platform === "cloudflare" ? "  Secrets are in .env (git-ignored). `npx flaghoist deploy` sets them on your Worker." : "  Secrets are in .env (git-ignored). Add them to your host as environment variables too."
+    );
+  }
+  return lines;
+}
+function terminalAsker(input = process.stdin, output = process.stdout) {
+  const rl = createInterface({ input, output, terminal: true });
+  let muted = false;
+  const internal = rl;
+  const write = internal._writeToOutput.bind(rl);
+  internal._writeToOutput = (text) => {
+    if (!muted) write(text);
+  };
+  return {
+    interactive: true,
+    async text(question, fallback) {
+      const answer = (await rl.question(`  ${question}${fallback ? ` (${fallback})` : ""}: `)).trim();
+      return answer || fallback;
+    },
+    async choice(question, options, fallback) {
+      output.write(`
+  ${question}
+`);
+      options.forEach((o, i) => {
+        output.write(`    ${i + 1}) ${o.label}${o.hint ? `   ${o.hint}` : ""}
+`);
+      });
+      const defaultIndex = Math.max(
+        0,
+        options.findIndex((o) => o.value === fallback)
+      ) + 1;
+      for (; ; ) {
+        const answer = (await rl.question(`  Choose (${defaultIndex}): `)).trim();
+        if (!answer) return options[defaultIndex - 1].value;
+        const index = Number(answer);
+        if (Number.isInteger(index) && index >= 1 && index <= options.length) {
+          return options[index - 1].value;
+        }
+        output.write(`  Enter a number from 1 to ${options.length}.
+`);
+      }
+    },
+    async yesNo(question, fallback) {
+      for (; ; ) {
+        const answer = (await rl.question(`
+  ${question} (${fallback ? "Y/n" : "y/N"}): `)).trim().toLowerCase();
+        if (!answer) return fallback;
+        if (answer === "y" || answer === "yes") return true;
+        if (answer === "n" || answer === "no") return false;
+      }
+    },
+    async secret(question) {
+      output.write(`  ${question}: `);
+      muted = true;
+      try {
+        return await rl.question("");
+      } finally {
+        muted = false;
+        output.write("\n");
+      }
+    },
+    say(line) {
+      output.write(`${line}
+`);
+    },
+    close() {
+      rl.close();
+    }
+  };
+}
+function defaultsAsker() {
+  return {
+    interactive: false,
+    async text(_q, fallback) {
+      return fallback;
+    },
+    async choice(_q, _options, fallback) {
+      return fallback;
+    },
+    async yesNo(_q, fallback) {
+      return fallback;
+    },
+    async secret() {
+      return "";
+    },
+    say() {
+    }
+  };
+}
+
+export {
+  DEFAULT_CONFIG,
+  STORAGE_KINDS,
+  PLATFORM_KINDS,
+  containerStorageDefault,
+  asContainer,
+  parseConfig,
+  serializeConfig,
+  MIN_PEPPER_LENGTH,
+  storageChoices,
+  generatePepper,
+  collectSetup,
+  writeSetup,
+  readEnvFile,
+  setupSummary,
+  terminalAsker,
+  defaultsAsker
+};