@ashlr/stack-core 0.1.1 → 0.3.0

package/src/ai/phantom-wire.ts

@@ -1,46 +1,47 @@
 /**
- * Recipe → Phantom envelope + webhook stub materializer.
+ * Recipe → Phantom vault check + webhook stub materializer.
  *
  * For each provider in a Recipe:
- *   1. Pre-create Phantom envelopes (one per declared secret) so `stack add`
- *      slots its real values into an already-rotating slot.
+ *   1. Report which declared secrets are already in the Phantom vault and
+ *      which are missing. `stack add` stores the real values; this step never
+ *      writes to the vault. Phantom Secrets refuses secret values in argv and
+ *      denies overwriting existing names, so placeholder entries would either
+ *      fail or block the real value from landing later.
  *   2. For webhook-capable providers (Stripe, Clerk, Supabase, GitHub),
  *      scaffold a commented-out handler stub in `.stack/webhooks/<provider>.ts`
- *      so the user has somewhere concrete to land the signature verification.
+ *      as an example only. Signature verification is not implemented: the
+ *      stub's TODO states the trust limitation — a present signature header
+ *      authenticates nothing and the body is untrusted input — and points at
+ *      the provider-specific verification to add before deploying a handler.
  *
- * This is the Stack moat: `stack apply` ends with envelopes + stubs waiting
- * for the real credentials, which the provider-specific `addCommand` flow
- * then fills in. An opt-out (`--no-wire`) exists for users who want pure
- * provisioning without Phantom-assisted rotation.
+ * An opt-out (`--no-wire`) skips both steps.
+ *
+ * Recipe manifests are unsigned: signature verification is not implemented.
+ * Checking provider names against the catalog does not authenticate a recipe's
+ * origin or integrity; callers must use recipes from a trusted source.
  */
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { findProviderRef } from "../catalog.ts";
-import {
-  assertPhantomInstalled,
-  exec as phantomExec,
-  PhantomExecResult,
-} from "../phantom.ts";
 import { PhantomNotInstalledError } from "../errors.ts";
+import { assertPhantomInstalled, listSecrets } from "../phantom.ts";
 import type { Recipe } from "./recipe.ts";
 
 export interface WireResult {
-  /** `PROVIDER:SECRET_NAME` entries successfully added to Phantom. */
-  envelopes: string[];
+  /** `PROVIDER:SECRET_NAME` entries already stored in the Phantom vault. */
+  present: string[];
+  /** `PROVIDER:SECRET_NAME` entries the recipe declares but the vault lacks. */
+  missing: string[];
   /** Absolute paths of webhook stub files created. */
   webhooks: string[];
-  /** Names of providers skipped (phantom missing, unknown provider, etc). */
+  /** Names of providers skipped (phantom missing, vault unreadable, unknown provider). */
   skipped: string[];
 }
 
-const PLACEHOLDER = "TODO_STACK_APPLY";
-
 /**
- * Providers with webhooks worth pre-wiring. Keep this list tight — each entry
- * gets a hand-maintained stub in `webhookStubFor`. Adding a new provider here
- * without also adding its stub produces an empty file, which is worse than
- * no file.
+ * Providers with webhooks worth pre-wiring. Keep this list tight and update
+ * the provider-specific secret and signature header mappings for each entry.
  */
 const WEBHOOK_PROVIDERS = new Set(["stripe", "clerk", "supabase", "github"]);
 
@@ -48,7 +49,7 @@ export async function wirePhantomForRecipe(
   recipe: Recipe,
   opts: { cwd?: string; noWire?: boolean } = {},
 ): Promise<WireResult> {
-  const result: WireResult = { envelopes: [], webhooks: [], skipped: [] };
+  const result: WireResult = { present: [], missing: [], webhooks: [], skipped: [] };
   if (opts.noWire) return result;
 
   const cwd = opts.cwd ?? process.cwd();
@@ -57,7 +58,7 @@ export async function wirePhantomForRecipe(
     await assertPhantomInstalled();
   } catch (err) {
     if (err instanceof PhantomNotInstalledError) {
-      // Phantom missing → skip envelope creation but still drop webhook stubs
+      // Phantom missing → skip the vault check but still drop webhook stubs
       // (they're just files). Surface the provider names so the CLI can tell
       // the user why nothing landed in the vault.
       for (const p of recipe.providers) result.skipped.push(p.name);
@@ -72,16 +73,16 @@ export async function wirePhantomForRecipe(
     throw err;
   }
 
+  const stored = await listVaultNames(cwd);
+
   for (const { name } of recipe.providers) {
     const ref = findProviderRef(name);
-    if (!ref) {
+    if (!ref || !stored) {
       result.skipped.push(name);
-      continue;
-    }
-
-    for (const secret of ref.secrets) {
-      const added = await addEnvelope(secret, cwd);
-      if (added) result.envelopes.push(`${name}:${secret}`);
+    } else {
+      for (const secret of ref.secrets) {
+        (stored.has(secret) ? result.present : result.missing).push(`${name}:${secret}`);
+      }
     }
 
     if (WEBHOOK_PROVIDERS.has(name)) {
@@ -94,34 +95,15 @@ export async function wirePhantomForRecipe(
 }
 
 /**
- * Shell `phantom add <KEY> <placeholder>` with opportunistic `--rotate`.
- * Try with `--rotate` first; if the running Phantom doesn't support the flag,
- * fall back to a flagless add. Returns true when the envelope was written.
+ * Secret names in the project's Phantom vault, via `phantom list --json`
+ * (names and metadata only, never values). Returns undefined when the vault
+ * can't be read (not initialized, older Phantom without `--json`, etc).
  */
-async function addEnvelope(key: string, cwd: string): Promise<boolean> {
-  const rotateAttempt = await tryExec(["add", key, PLACEHOLDER, "--rotate"], cwd);
-  if (rotateAttempt.code === 0) return true;
-
-  // Heuristic for "Phantom rejected --rotate because it's an older build":
-  // stderr mentions the flag name or "unknown option". On any other failure,
-  // we already logged it via stderr — the caller's noWire path can skip.
-  const stderrLower = rotateAttempt.stderr.toLowerCase();
-  const looksLikeUnknownFlag =
-    stderrLower.includes("--rotate") ||
-    stderrLower.includes("unknown option") ||
-    stderrLower.includes("unrecognized");
-
-  if (!looksLikeUnknownFlag) return false;
-
-  const fallback = await tryExec(["add", key, PLACEHOLDER], cwd);
-  return fallback.code === 0;
-}
-
-async function tryExec(args: string[], cwd: string): Promise<PhantomExecResult> {
+async function listVaultNames(cwd: string): Promise<Set<string> | undefined> {
   try {
-    return await phantomExec(args, { cwd, allowFailure: true });
+    return new Set(await listSecrets(cwd));
   } catch {
-    return { stdout: "", stderr: "", code: 1 };
+    return undefined;
   }
 }
 
@@ -135,20 +117,53 @@ async function writeWebhookStub(cwd: string, provider: string): Promise<string>
 function webhookStubFor(provider: string): string {
   const base = `// Auto-generated by \`stack apply\` — webhook handler stub for ${provider}.
 // Fill in the secret retrieval + signature verification before deploying.
+// This entire example is commented out and does not verify signatures.
+// If uncommented as-is, it accepts any non-empty signature header and returns
+// 200 without authenticating the request. Implement verification first.
 //
-// Secret envelope lives in Phantom; read it at call time with:
+// The secret lives in Phantom; read it at call time with:
 //   phantom reveal ${webhookSecretKeyFor(provider)}
 //
 // export async function handle${capitalize(provider)}Webhook(req: Request): Promise<Response> {
 //   const signature = req.headers.get("${signatureHeaderFor(provider)}");
+//   if (!signature) return new Response("Missing signature", { status: 400 });
 //   const body = await req.text();
-//   // TODO: verify(signature, body) before trusting.
+//   // TODO(security): signature verification is NOT implemented here. The
+//   // header check above proves only that a signature header arrived; its
+//   // value is never compared to anything. Until this TODO is done, \`body\`
+//   // is unauthenticated, attacker-controlled input — anyone who can POST
+//   // to this endpoint can forge a ${provider} webhook.
+//   // ${verificationHintFor(provider)}
+//   // Verify over the exact raw body bytes with the webhook secret
+//   // (\`phantom reveal ${webhookSecretKeyFor(provider)}\`) and compare in
+//   // constant time; reject missing or invalid signatures, and only then
+//   // parse, trust, or act on the body.
 //   return new Response("ok", { status: 200 });
 // }
 `;
   return base;
 }
 
+/**
+ * One-line pointer to the provider's documented signature scheme, inlined into
+ * the stub's TODO so the implementer starts at the right verification API.
+ * Falls back to a generic instruction for providers added later.
+ */
+function verificationHintFor(provider: string): string {
+  switch (provider) {
+    case "stripe":
+      return "Stripe: `stripe.webhooks.constructEvent` — HMAC-SHA256 with timestamp tolerance.";
+    case "clerk":
+      return "Clerk (svix): `new Webhook(secret).verify(body, headers)`.";
+    case "supabase":
+      return "Supabase: `x-supabase-signature` per Supabase's documented webhook scheme.";
+    case "github":
+      return "GitHub: `x-hub-signature-256` is `sha256=` + HMAC-SHA256 of the raw body.";
+    default:
+      return "Verify per the provider's documented signature scheme.";
+  }
+}
+
 function webhookSecretKeyFor(provider: string): string {
   switch (provider) {
     case "stripe":

package/src/ai/recipe.ts

@@ -176,3 +176,72 @@ function coerceRecipe(raw: Record<string, unknown>, fallbackId: string): Recipe
   }
   return recipe;
 }
+
+/**
+ * Remote recipe marketplace.
+ *
+ * Opt-in via env var — local recipes always take precedence.
+ * Set STACK_RECIPE_BASE_URL to enable remote fallback, e.g.:
+ *   STACK_RECIPE_BASE_URL=https://rjowfztlxxstcrwjdaet.supabase.co/functions/v1/list-recipes
+ */
+const REMOTE_BASE_URL = process.env.STACK_RECIPE_BASE_URL;
+
+/** Fetch all recipes from the remote marketplace (opt-in). Returns [] if disabled or unreachable. */
+export async function listRemoteRecipes(): Promise<Recipe[]> {
+  if (!REMOTE_BASE_URL) return [];
+  try {
+    const res = await fetch(REMOTE_BASE_URL, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return [];
+    const json = (await res.json()) as { recipes?: unknown[] };
+    const rows = Array.isArray(json.recipes) ? json.recipes : [];
+    return rows.map((row) => {
+      const r = row as Record<string, unknown>;
+      return coerceRecipe(
+        {
+          id: r.slug,
+          query: r.query,
+          createdAt: r.created_at,
+          providers: r.providers,
+          guidance: undefined,
+        },
+        String(r.slug ?? ""),
+      );
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fetch a single recipe by slug from the remote marketplace (opt-in).
+ * Returns undefined if disabled, not found, or unreachable.
+ */
+export async function getRemoteRecipe(slug: string): Promise<Recipe | undefined> {
+  if (!REMOTE_BASE_URL) return undefined;
+  try {
+    const url = `${REMOTE_BASE_URL}?slug=${encodeURIComponent(slug)}`;
+    const res = await fetch(url, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return undefined;
+    const json = (await res.json()) as { recipe?: unknown };
+    if (!json.recipe || typeof json.recipe !== "object") return undefined;
+    const r = json.recipe as Record<string, unknown>;
+    return coerceRecipe(
+      {
+        id: r.slug,
+        query: r.query,
+        createdAt: r.created_at,
+        providers: r.providers,
+        guidance: undefined,
+      },
+      String(r.slug ?? ""),
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/base-urls.ts

@@ -0,0 +1,71 @@
+/**
+ * Model provider base URLs, overridable from the environment.
+ *
+ * `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL` and `OLLAMA_HOST` let a gateway
+ * (a LiteLLM proxy, a Phantom proxy, or Ollama on another machine) sit in
+ * front of the providers. Unset or blank values give exactly the URLs Stack
+ * always used. Values are read when called, not at import.
+ */
+
+type Env = Record<string, string | undefined>;
+
+export const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com";
+export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+export const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434";
+
+/** Trim whitespace and trailing slashes; `undefined` when nothing is left. */
+function clean(raw: string | undefined): string | undefined {
+  const v = raw?.trim().replace(/\/+$/, "").trim();
+  return v ? v : undefined;
+}
+
+/**
+ * A keyed gateway URL must be https, or plain http only to the loopback
+ * literals 127.0.0.1 and [::1], so an API key is never sent in clear text
+ * across a network. Throws with the variable name only, never the URL (it
+ * can carry credentials).
+ */
+export function assertGatewayUrl(name: string, value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${name} is not a valid URL`);
+  }
+  if (url.protocol === "https:") return value;
+  if (url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "[::1]")) {
+    return value;
+  }
+  throw new Error(`${name} must use https, or http only to 127.0.0.1 or [::1]`);
+}
+
+/** Anthropic API root; Stack appends `/v1/...`. */
+export function anthropicBaseUrl(env: Env = process.env): string {
+  const v = clean(env.ANTHROPIC_BASE_URL);
+  return v ? assertGatewayUrl("ANTHROPIC_BASE_URL", v) : DEFAULT_ANTHROPIC_BASE_URL;
+}
+
+/** OpenAI API root including `/v1`, the same convention as the OpenAI SDKs. */
+export function openaiBaseUrl(env: Env = process.env): string {
+  const v = clean(env.OPENAI_BASE_URL);
+  return v ? assertGatewayUrl("OPENAI_BASE_URL", v) : DEFAULT_OPENAI_BASE_URL;
+}
+
+/**
+ * Ollama server root. `OLLAMA_HOST` may be `host`, `host:port`, `:port`
+ * (localhost) or a full `http://` / `https://` URL, as Ollama itself
+ * accepts. A missing scheme becomes `http://`, a missing port 11434.
+ */
+export function ollamaBaseUrl(env: Env = process.env): string {
+  let v = clean(env.OLLAMA_HOST);
+  if (!v) return DEFAULT_OLLAMA_BASE_URL;
+  if (/^https?:\/\//i.test(v)) return v;
+  if (v.startsWith(":")) v = `localhost${v}`;
+  const slash = v.indexOf("/");
+  const authority = slash === -1 ? v : v.slice(0, slash);
+  const path = slash === -1 ? "" : v.slice(slash);
+  const close = authority.lastIndexOf("]");
+  const hasPort =
+    close === -1 ? authority.includes(":") : authority.slice(close + 1).startsWith(":");
+  return `http://${authority}${hasPort ? "" : ":11434"}${path}`;
+}