@ashlr/stack-core 0.1.1

package/src/providers/_helpers.ts

@@ -0,0 +1,81 @@
+import { revealSecret } from "../phantom.ts";
+import { fetchWithRetry, type RetryOptions } from "../http.ts";
+
+/**
+ * Shared helpers for every hand-written provider. Before this existed, each
+ * provider shipped a byte-for-byte copy of `readLine` and `tryRevealSecret` —
+ * one source of truth keeps behaviour consistent.
+ */
+
+export async function tryRevealSecret(key: string): Promise<string | undefined> {
+  try {
+    const value = await revealSecret(key);
+    return value.length > 0 ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read a single line from stdin. Used by every provider's PAT-paste fallback
+ * when no OAuth client is configured. Resumes stdin, reads until newline, then
+ * pauses stdin so the parent process doesn't hang waiting for EOF.
+ */
+export async function readLine(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    const onData = (chunk: Buffer) => {
+      buf += chunk.toString();
+      if (buf.includes("\n")) {
+        process.stdin.off("data", onData);
+        process.stdin.pause();
+        resolve(buf.split("\n")[0]);
+      }
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
+/**
+ * Build a standard Authorization + content-type + Accept header set for
+ * Bearer-token providers. Providers with custom auth header shapes (Anthropic,
+ * Upstash, Linear, Supabase PKCE) inline their own.
+ */
+export function bearerJsonHeaders(token: string): HeadersInit {
+  return {
+    Authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    Accept: "application/json",
+  };
+}
+
+/**
+ * Idempotent GET wrapper for the `verify` closures used by api-key providers
+ * (and for any other read-only provider call). Thin shim around
+ * `fetchWithRetry` that forces `idempotent: true` — callers are always
+ * verifying a credential via a read-only endpoint, so retrying transient
+ * 429/5xx is always safe. Keeps each provider's `verify` free of retry glue.
+ */
+export function verifyFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  opts?: RetryOptions,
+): Promise<Response> {
+  return fetchWithRetry(input, init, { ...opts, idempotent: true });
+}
+
+/**
+ * Redact all but the last `keepLast` characters of a secret for safe display.
+ * Always show at least a few asterisks so log lines that include the redacted
+ * value still read clearly. Short strings get fully hidden — the suffix alone
+ * could be enough to bruteforce a 6-char token.
+ *
+ * Usage: `ctx.log({ msg: \`token ${scrub(t)} rejected\` })` prints
+ * `token ****abcd rejected`, never the raw secret.
+ */
+export function scrub(value: string, keepLast: number = 4): string {
+  if (!value) return "";
+  if (value.length <= keepLast) return "****";
+  return `****${value.slice(-keepLast)}`;
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,27 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+export default makeApiKeyProvider({
+  name: "anthropic",
+  displayName: "Anthropic",
+  category: "ai",
+  docs: "https://docs.anthropic.com/en/api",
+  secretName: "ANTHROPIC_API_KEY",
+  howTo: "Create a key at https://console.anthropic.com/settings/keys",
+  dashboard: "https://console.anthropic.com",
+  async verify(key) {
+    try {
+      const res = await verifyFetch("https://api.anthropic.com/v1/models", {
+        headers: {
+          "x-api-key": key,
+          "anthropic-version": "2023-06-01",
+        },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as { data?: Array<{ id: string }> };
+      return { models: String(body.data?.length ?? 0) };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/providers/aws.ts

@@ -0,0 +1,198 @@
+import type { ServiceEntry } from "../config.ts";
+import { createHash, createHmac } from "node:crypto";
+import { StackError } from "../errors.ts";
+import { addSecret } from "../phantom.ts";
+import { readLine, tryRevealSecret } from "./_helpers.ts";
+import type {
+  AuthHandle,
+  HealthStatus,
+  Materialized,
+  Provider,
+  ProviderContext,
+  Resource,
+} from "./_base.ts";
+
+/**
+ * AWS — v1 accepts an IAM access key pair (access key id + secret access key).
+ * Verifies via STS GetCallerIdentity using a hand-rolled SigV4 signer so we
+ * don't pull in the AWS SDK (it's a big dep for one call). Stores keys in the
+ * Phantom vault and optionally writes ~/.aws/credentials for use by the AWS
+ * CLI / SDKs outside Stack.
+ */
+
+const SECRET_ID_KEY = "AWS_ACCESS_KEY_ID";
+const SECRET_SECRET_KEY = "AWS_SECRET_ACCESS_KEY";
+const SECRET_REGION = "AWS_REGION";
+
+const aws: Provider = {
+  name: "aws",
+  displayName: "AWS",
+  category: "cloud",
+  authKind: "api_key",
+  docs: "https://docs.aws.amazon.com/iam/",
+
+  async login(ctx: ProviderContext): Promise<AuthHandle> {
+    const cachedId = await tryRevealSecret(SECRET_ID_KEY);
+    const cachedSecret = await tryRevealSecret(SECRET_SECRET_KEY);
+    if (cachedId && cachedSecret) {
+      const identity = await callStsIdentity(cachedId, cachedSecret, "us-east-1");
+      if (identity) return { token: `${cachedId}:${cachedSecret}`, identity };
+      ctx.log({ level: "warn", msg: "Cached AWS credentials invalid." });
+    }
+    if (!ctx.interactive)
+      throw new StackError("AWS_AUTH_REQUIRED", "No valid AWS credentials in vault.");
+    process.stderr.write(
+      "\n  Create an IAM access key at https://console.aws.amazon.com/iam/home#/security_credentials\n  AWS_ACCESS_KEY_ID: ",
+    );
+    const accessKeyId = (await readLine()).trim();
+    process.stderr.write("  AWS_SECRET_ACCESS_KEY: ");
+    const secretAccessKey = (await readLine()).trim();
+    const identity = await callStsIdentity(accessKeyId, secretAccessKey, "us-east-1");
+    if (!identity) throw new StackError("AWS_AUTH_INVALID", "AWS rejected those credentials.");
+    await addSecret(SECRET_ID_KEY, accessKeyId);
+    await addSecret(SECRET_SECRET_KEY, secretAccessKey);
+    return { token: `${accessKeyId}:${secretAccessKey}`, identity };
+  },
+
+  async provision(_ctx, auth, opts): Promise<Resource> {
+    // v1: attach to the account the keys belong to.
+    const region = (opts.hints?.region as string | undefined) ?? "us-east-1";
+    return {
+      id: auth.identity?.Account ?? "unknown",
+      displayName: auth.identity?.Arn ?? "AWS account",
+      region,
+    };
+  },
+
+  async materialize(_ctx, resource, auth): Promise<Materialized> {
+    const sep = auth.token.indexOf(":");
+    if (sep <= 0 || sep === auth.token.length - 1) {
+      throw new StackError(
+        "AWS_AUTH_MALFORMED",
+        "AWS auth handle is malformed (expected accessKeyId:secretAccessKey).",
+      );
+    }
+    const accessKeyId = auth.token.slice(0, sep);
+    const secretAccessKey = auth.token.slice(sep + 1);
+    if (!accessKeyId || !secretAccessKey) {
+      throw new StackError(
+        "AWS_AUTH_MALFORMED",
+        "AWS auth handle missing access key id or secret access key.",
+      );
+    }
+    await addSecret(SECRET_REGION, resource.region ?? "us-east-1");
+    return {
+      secrets: {
+        AWS_ACCESS_KEY_ID: accessKeyId,
+        AWS_SECRET_ACCESS_KEY: secretAccessKey,
+        AWS_REGION: resource.region ?? "us-east-1",
+      },
+    };
+  },
+
+  async healthcheck(_ctx, _entry: ServiceEntry): Promise<HealthStatus> {
+    const id = await tryRevealSecret(SECRET_ID_KEY);
+    const secret = await tryRevealSecret(SECRET_SECRET_KEY);
+    const region = (await tryRevealSecret(SECRET_REGION)) ?? "us-east-1";
+    if (!id || !secret) return { kind: "error", detail: "AWS credentials missing from vault" };
+    const start = Date.now();
+    const identity = await callStsIdentity(id, secret, region);
+    const latencyMs = Date.now() - start;
+    return identity ? { kind: "ok", latencyMs } : { kind: "error", detail: "credentials invalid" };
+  },
+
+  dashboardUrl(): string {
+    return "https://console.aws.amazon.com";
+  },
+};
+
+export default aws;
+
+/**
+ * Minimal SigV4 signer for a single call: STS GetCallerIdentity. Scoped tight
+ * on purpose — any more and we should pull in @aws-sdk/client-sts.
+ */
+async function callStsIdentity(
+  accessKeyId: string,
+  secretAccessKey: string,
+  region: string,
+): Promise<Record<string, string> | undefined> {
+  // us-east-1 uses the unregional endpoint; everything else uses sts.<region>.amazonaws.com.
+  const host = region === "us-east-1" ? "sts.amazonaws.com" : `sts.${region}.amazonaws.com`;
+  const service = "sts";
+  const method = "POST";
+  const now = new Date();
+  const amzDate = toAmzDate(now);
+  const datestamp = amzDate.slice(0, 8);
+  const payload = "Action=GetCallerIdentity&Version=2011-06-15";
+  const payloadHash = createHash("sha256").update(payload).digest("hex");
+
+  const canonicalHeaders =
+    `content-type:application/x-www-form-urlencoded\n` +
+    `host:${host}\n` +
+    `x-amz-date:${amzDate}\n`;
+  const signedHeaders = "content-type;host;x-amz-date";
+  const canonicalRequest = [
+    method,
+    "/",
+    "",
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join("\n");
+  const scope = `${datestamp}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    createHash("sha256").update(canonicalRequest).digest("hex"),
+  ].join("\n");
+
+  const kDate = hmac(`AWS4${secretAccessKey}`, datestamp);
+  const kRegion = hmac(kDate, region);
+  const kService = hmac(kRegion, service);
+  const kSigning = hmac(kService, "aws4_request");
+  const signature = createHmac("sha256", kSigning).update(stringToSign).digest("hex");
+
+  const authorization =
+    `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${scope}, ` +
+    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+  try {
+    const res = await fetch(`https://${host}/`, {
+      method,
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        "x-amz-date": amzDate,
+        Authorization: authorization,
+      },
+      body: payload,
+    });
+    if (!res.ok) return undefined;
+    const xml = await res.text();
+    const arn = matchXml(xml, "Arn");
+    const userId = matchXml(xml, "UserId");
+    const account = matchXml(xml, "Account");
+    if (!arn) return undefined;
+    return {
+      Arn: arn,
+      ...(userId ? { UserId: userId } : {}),
+      ...(account ? { Account: account } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function hmac(key: string | Buffer, value: string): Buffer {
+  return createHmac("sha256", key).update(value).digest();
+}
+
+function toAmzDate(d: Date): string {
+  return d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+
+function matchXml(xml: string, tag: string): string | undefined {
+  const m = xml.match(new RegExp(`<${tag}>([^<]+)<\\/${tag}>`));
+  return m?.[1];
+}

package/src/providers/braintrust.ts

@@ -0,0 +1,33 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+/**
+ * Braintrust — LLM eval + observability. v1 accepts a Braintrust API key
+ * (create at https://www.braintrust.dev/app/settings/api-keys) and verifies
+ * via /v1/organization (hits `https://api.braintrust.dev`).
+ */
+export default makeApiKeyProvider({
+  name: "braintrust",
+  displayName: "Braintrust",
+  category: "ai",
+  docs: "https://www.braintrust.dev/docs",
+  secretName: "BRAINTRUST_API_KEY",
+  howTo: "Create a key at https://www.braintrust.dev/app/settings/api-keys",
+  dashboard: "https://www.braintrust.dev/app",
+  async verify(key) {
+    try {
+      const res = await verifyFetch("https://api.braintrust.dev/v1/organization", {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as {
+        objects?: Array<{ id?: string; name?: string }>;
+      };
+      const first = body.objects?.[0];
+      if (!first?.id) return undefined;
+      return { id: first.id, name: first.name ?? "" };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/providers/clerk.ts

@@ -0,0 +1,23 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+export default makeApiKeyProvider({
+  name: "clerk",
+  displayName: "Clerk",
+  category: "auth",
+  docs: "https://clerk.com/docs",
+  secretName: "CLERK_SECRET_KEY",
+  howTo: "Grab your secret key from https://dashboard.clerk.com → API Keys",
+  dashboard: "https://dashboard.clerk.com",
+  async verify(key) {
+    try {
+      const res = await verifyFetch("https://api.clerk.com/v1/jwks", {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!res.ok) return undefined;
+      return { verified: "true" };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/providers/cloudflare.ts

@@ -0,0 +1,146 @@
+import type { ServiceEntry } from "../config.ts";
+import { StackError } from "../errors.ts";
+import { addSecret, revealSecret } from "../phantom.ts";
+import { fetchWithRetry } from "../http.ts";
+import type {
+  AuthHandle,
+  HealthStatus,
+  Materialized,
+  Provider,
+  ProviderContext,
+  ProvisionOpts,
+  Resource,
+} from "./_base.ts";
+
+/**
+ * Cloudflare — Workers / Pages / R2 / D1 / KV all hang off one Account API
+ * token. v1 uses a user-created token (users make one at
+ * https://dash.cloudflare.com/profile/api-tokens with minimal scopes). Auto-
+ * provisioning a new Worker is intentionally deferred — most real workflows
+ * start from a template or wrangler scaffold.
+ */
+
+const API = "https://api.cloudflare.com/client/v4";
+const TOKEN_SECRET = "CLOUDFLARE_API_TOKEN";
+
+const cloudflare: Provider = {
+  name: "cloudflare",
+  displayName: "Cloudflare",
+  category: "deploy",
+  authKind: "pat",
+  docs: "https://developers.cloudflare.com/api",
+
+  async login(ctx: ProviderContext): Promise<AuthHandle> {
+    const cached = await tryRevealSecret(TOKEN_SECRET);
+    if (cached) {
+      const identity = await verifyToken(cached);
+      if (identity) return { token: cached, identity };
+      ctx.log({ level: "warn", msg: "Cached Cloudflare token invalid." });
+    }
+    if (!ctx.interactive)
+      throw new StackError("CLOUDFLARE_AUTH_REQUIRED", "No valid Cloudflare token in vault.");
+    process.stderr.write(
+      "\n  Create an API token at https://dash.cloudflare.com/profile/api-tokens\n  Scopes: Account · Workers Scripts / Pages / R2 / D1 as needed\n  Paste it here: ",
+    );
+    const token = (await readLine()).trim();
+    const identity = await verifyToken(token);
+    if (!identity) throw new StackError("CLOUDFLARE_AUTH_INVALID", "Cloudflare rejected that token.");
+    await addSecret(TOKEN_SECRET, token);
+    return { token, identity };
+  },
+
+  async provision(ctx, auth, opts: ProvisionOpts): Promise<Resource> {
+    const accounts = await fetchAccounts(auth.token);
+    if (accounts.length === 0)
+      throw new StackError("CLOUDFLARE_NO_ACCOUNT", "Token has no account scope.");
+    const accountId = (opts.hints?.accountId as string | undefined) ?? accounts[0].id;
+    if (accounts.length > 1) {
+      ctx.log({
+        level: "warn",
+        msg: `Multiple Cloudflare accounts; defaulting to "${accounts[0].name}". Pass --use <account-id> to pick.`,
+      });
+    }
+    return {
+      id: opts.existingResourceId ?? accountId,
+      displayName: accounts.find((a) => a.id === accountId)?.name ?? accountId,
+      meta: { account_id: accountId },
+    };
+  },
+
+  async materialize(_ctx, resource, auth): Promise<Materialized> {
+    return {
+      secrets: {
+        CLOUDFLARE_API_TOKEN: auth.token,
+        CLOUDFLARE_ACCOUNT_ID: resource.id,
+      },
+      urls: { dashboard: `https://dash.cloudflare.com/${resource.id}` },
+    };
+  },
+
+  async healthcheck(_ctx, _entry: ServiceEntry): Promise<HealthStatus> {
+    const token = await tryRevealSecret(TOKEN_SECRET);
+    if (!token) return { kind: "error", detail: `${TOKEN_SECRET} missing from vault` };
+    const start = Date.now();
+    const identity = await verifyToken(token);
+    const latencyMs = Date.now() - start;
+    return identity ? { kind: "ok", latencyMs } : { kind: "error", detail: "token invalid" };
+  },
+
+  dashboardUrl(entry: ServiceEntry): string {
+    return entry.resource_id
+      ? `https://dash.cloudflare.com/${entry.resource_id}`
+      : "https://dash.cloudflare.com";
+  },
+};
+
+export default cloudflare;
+
+async function verifyToken(token: string): Promise<Record<string, string> | undefined> {
+  try {
+    // Idempotent GET — healthcheck hits this on every loop.
+    const res = await fetchWithRetry(`${API}/user/tokens/verify`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as { result?: { id?: string; status?: string } };
+    if (body.result?.status !== "active") return undefined;
+    return { token_id: body.result.id ?? "" };
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchAccounts(token: string): Promise<Array<{ id: string; name: string }>> {
+  // Idempotent GET — retry transient failures on `stack add` startup.
+  const res = await fetchWithRetry(`${API}/accounts`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) return [];
+  const body = (await res.json()) as { result?: Array<{ id: string; name: string }> };
+  return body.result ?? [];
+}
+
+async function tryRevealSecret(key: string): Promise<string | undefined> {
+  try {
+    const v = await revealSecret(key);
+    return v.length > 0 ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function readLine(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    const onData = (chunk: Buffer) => {
+      buf += chunk.toString();
+      if (buf.includes("\n")) {
+        process.stdin.off("data", onData);
+        process.stdin.pause();
+        resolve(buf.split("\n")[0]);
+      }
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}

package/src/providers/convex.ts

@@ -0,0 +1,28 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+
+/**
+ * Convex — reactive backend with subscriptions + scheduled functions. v1 uses
+ * a deploy key (users create one at https://dashboard.convex.dev → Project
+ * Settings → Deploy Keys). Creating Convex deployments programmatically
+ * requires their deploy CLI with a browser flow — out of scope for v1.
+ */
+export default makeApiKeyProvider({
+  name: "convex",
+  displayName: "Convex",
+  category: "database",
+  docs: "https://docs.convex.dev",
+  secretName: "CONVEX_DEPLOY_KEY",
+  howTo:
+    "Create a deploy key at https://dashboard.convex.dev (Project → Settings → Deploy Keys).",
+  dashboard: "https://dashboard.convex.dev",
+  async verify(key) {
+    // Convex deploy keys have the shape prod:<team>:<project>|<token>. No
+    // public validate-only endpoint, so we do a shape check and defer real
+    // validation to first CLI use (convex deploy / npx convex dev).
+    if (!key.includes(":") || !key.includes("|")) return undefined;
+    const [prefix] = key.split("|");
+    const parts = prefix.split(":");
+    if (parts.length < 3) return undefined;
+    return { environment: parts[0], team: parts[1], project: parts[2] };
+  },
+});

package/src/providers/deepseek.ts

@@ -0,0 +1,24 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+export default makeApiKeyProvider({
+  name: "deepseek",
+  displayName: "DeepSeek",
+  category: "ai",
+  docs: "https://api-docs.deepseek.com",
+  secretName: "DEEPSEEK_API_KEY",
+  howTo: "Create a key at https://platform.deepseek.com/api_keys",
+  dashboard: "https://platform.deepseek.com",
+  async verify(key) {
+    try {
+      const res = await verifyFetch("https://api.deepseek.com/v1/models", {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as { data?: Array<{ id: string }> };
+      return { models: String(body.data?.length ?? 0) };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/providers/firebase.ts

@@ -0,0 +1,35 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+
+/**
+ * Firebase — v1 accepts a service-account JSON (users download from
+ * https://console.firebase.google.com → Project Settings → Service Accounts
+ * → Generate new private key). We store the entire JSON blob as a single
+ * secret and shape-check it has the fields Firebase SDKs need.
+ */
+export default makeApiKeyProvider({
+  name: "firebase",
+  displayName: "Firebase",
+  category: "database",
+  docs: "https://firebase.google.com/docs/admin/setup",
+  secretName: "FIREBASE_SERVICE_ACCOUNT_JSON",
+  howTo:
+    "Download a Service Account JSON at https://console.firebase.google.com → Settings → Service Accounts",
+  dashboard: "https://console.firebase.google.com",
+  async verify(blob) {
+    try {
+      const parsed = JSON.parse(blob) as {
+        type?: string;
+        project_id?: string;
+        client_email?: string;
+      };
+      if (parsed.type !== "service_account") return undefined;
+      if (!parsed.project_id || !parsed.client_email) return undefined;
+      return {
+        project_id: parsed.project_id,
+        client_email: parsed.client_email,
+      };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/providers/fly.ts

@@ -0,0 +1,24 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+export default makeApiKeyProvider({
+  name: "fly",
+  displayName: "Fly.io",
+  category: "deploy",
+  docs: "https://fly.io/docs/machines/api",
+  secretName: "FLY_API_TOKEN",
+  howTo: "Run `fly auth token` or create one at https://fly.io/user/personal_access_tokens",
+  dashboard: "https://fly.io/dashboard",
+  async verify(key) {
+    try {
+      const res = await verifyFetch("https://api.machines.dev/v1/apps", {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as { apps?: Array<{ name: string }> };
+      return { apps: String(body.apps?.length ?? 0) };
+    } catch {
+      return undefined;
+    }
+  },
+});