hermoso 0.1.24 → 0.1.30

package/README.md

@@ -5,7 +5,7 @@ scripts. Research the ads already winning in a market, generate finished image &
 composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad
 campaigns behind them — all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
 
-**205 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**262 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
 catalog with exact per-render credit costs plus the full capability map.
 
 ## Instant: the hosted Claude.ai connector
@@ -46,7 +46,7 @@ Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-### What the 205 tools cover
+### What the 262 tools cover
 
 **Ad spy / research** — `find_competitors`, `competitor_teardown`, `pull_competitor_ads`, `research_ads`; the
 Meta / Google / LinkedIn ad libraries (`search_meta_ads`, `search_google_ads`, `search_linkedin_ads`); organic
@@ -55,6 +55,9 @@ social (`search_tiktok`, `search_instagram`, `search_youtube`, `search_reddit`,
 
 **Create** — `draft_brand` → `plan_ad` → `render_ad` (the Studio quality pipeline: composited text, clean speech,
 music, brand end card), or `generate_image` / `generate_video` / `generate_avatar` (UGC creators + lip-sync).
+The workspace's **saved cast** is reusable: `list_creators` returns every saved creator with their portrait url,
+`save_creator` adds one, `delete_creator` drops one — re-pass a portrait to `generate_avatar` / `generate_video` /
+`recast_motion` and the SAME person stars in every ad, instead of a new face each render.
 Also `make_template_ad` (native HTML ad formats), `make_explainer`, `product_sizzle`, `make_thumbnail`,
 `remix_static`, `recast_motion`, `reframe_video`, `upscale_video`, `dub_video`, `change_voice`, `finish_video`,
 `fix_beat`, `stitch_video`, `clip_video`, `post_edit`, plus `plan_variations` + `score_ad` to fan out and rank.
@@ -135,6 +138,7 @@ Then invoke `/hermoso-ad-from-brand an ad for yourbrand.com — our hero product
 | `HERMOSO_API_BASE` | The Hermoso API origin (default `https://app.hermoso.ai` — set `http://localhost:3000` if you run the app yourself) |
 | `HERMOSO_TOKEN` | Bearer agent key (`hmk_…`) — required against the hosted app |
 | `HERMOSO_PROFILE` | Brand-workspace id, for accounts with multiple brand profiles |
+| `HERMOSO_OWNER` | Only for a brand **another account shared with you** (a team workspace): the owning account id. Set it together with `HERMOSO_PROFILE`, and set `HERMOSO_PROFILE` to that workspace's **profileUuid** — a brand's short slug is refused. Run `list_brands` (or `hermoso brands`) to print both values for every workspace you can enter. The server re-authorizes the pair on every request, so a wrong value is refused, never trusted. |
 
 `mcp/http.mjs` is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in
 this repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.

package/bin/hermoso.mjs

@@ -78,6 +78,7 @@ async function main() {
   process.env.HERMOSO_API_BASE = process.env.HERMOSO_API_BASE || cfg.apiBase || 'https://app.hermoso.ai';
   if (cfg.token && !process.env.HERMOSO_TOKEN) process.env.HERMOSO_TOKEN = cfg.token;
   if (cfg.profile && !process.env.HERMOSO_PROFILE) process.env.HERMOSO_PROFILE = cfg.profile;
+  if (cfg.owner && !process.env.HERMOSO_OWNER) process.env.HERMOSO_OWNER = cfg.owner; // shared team workspace: the owning account (server re-authorizes it)
 
   // `hermoso mcp` → run the stdio MCP server (Claude Code / Cursor / Codex spawn this, e.g. `npx -y hermoso mcp`).
   // It OWNS stdout as the JSON-RPC channel, so hand off immediately and print nothing to stdout here. The

package/mcp/client.mjs

@@ -17,11 +17,31 @@ const TOKEN = process.env.HERMOSO_TOKEN || '';
 // header > key.keyProfileId > 'default' (adapters/auth/middleware.js), so always sending the header permanently
 // masks the brand `use_brand` saved against the key — connectors on any non-default brand then look disconnected.
 export const PROFILE = process.env.HERMOSO_PROFILE || '';
+// SHARED TEAM WORKSPACE: the OWNING account. The web client sends this as x-hermoso-owner from PROFILE_OWNER
+// (public/app.js ctxHeaders) whenever the active brand belongs to someone else's account; the MCP twins never did,
+// so a member driving Hermoso headlessly resolved every brand-scoped read against their OWN empty account —
+// resolveWs's `if (owner && owner !== own)` branch simply never ran and it fell through to the own-account path.
+// Symptom (live 2026-07-31): 0 connectors over MCP on a workspace showing 10 in the browser, with NO error.
+// SAFE TO SEND: the server RE-AUTHORIZES it against profile_members on every request (adapters/auth/middleware.js
+// resolveWs), so a forged or stale value is 403'd, never trusted. Like the profile header it must stay UNSET by
+// default — sending an owner for your own account would make resolveWs take the shared branch against yourself.
+// PAIR IT WITH THE PROFILE UUID, not the slug: profile_members keys on profiles.id, so a client_slug is the one
+// thing isMember() cannot match and it 403s. list_brands names both values for every workspace you can enter.
+export const OWNER = process.env.HERMOSO_OWNER || '';
+// The env-var prefix THIS build reads. tools.mjs is byte-identical across the two twins, so it cannot
+// hardcode either name when it tells a user which variables to set — it asks its own client.
+export const ENV_PREFIX = 'HERMOSO';
 
 function headers(extra = {}) {
   const ctx = mcpCtx.getStore();
-  const prof = ctx?.profile || PROFILE; // omitted when unpinned so the key's saved brand wins server-side
-  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...extra };
+  // A HOSTED-CONNECTOR request (mcp/http.mjs) is a DIFFERENT TENANT from the process serving it, so its ctx is the
+  // ONLY scope it may carry: falling through to this process's HERMOSO_PROFILE / HERMOSO_OWNER would scope one
+  // customer's tool call to whatever workspace the SERVER's environment happens to name — a cross-tenant leak that
+  // is invisible because it succeeds. stdio/CLI keeps the env fallback: there the process and the caller are the
+  // same person. Presence of the ctx store IS "remote" (see isRemote below).
+  const prof = ctx ? (ctx.profile || '') : PROFILE; // omitted when unpinned so the key's saved brand wins server-side
+  const own = ctx ? (ctx.owner || '') : OWNER; // the wire name is x-hermoso-owner on BOTH twins — it is the server's header, not a brand
+  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...(own ? { 'x-hermoso-owner': own } : {}), ...extra };
   const tok = ctx?.token || TOKEN;
   if (tok) h.Authorization = `Bearer ${tok}`;
   return h;
@@ -54,6 +74,14 @@ export async function apiPost(p, body = {}) {
   return unwrap(res);
 }
 
+// PATCH — a PARTIAL update, and the distinction is load-bearing on the schedule routes: an omitted key means
+// "leave that field exactly as it was", so sending a whole object where a patch was meant would blank the fields
+// the caller never mentioned. Only ever send the keys that are actually changing.
+export async function apiPatch(p, body = {}) {
+  const res = await fetch(`${API_BASE}${p}`, { method: 'PATCH', headers: headers(), body: JSON.stringify(body) });
+  return unwrap(res);
+}
+
 export async function apiDelete(p) {
   const res = await fetch(`${API_BASE}${p}`, { method: 'DELETE', headers: headers() });
   return unwrap(res);
@@ -67,6 +95,42 @@ export async function apiPut(p, body = {}) {
 // A hosted-connector call (via mcp/http.mjs) has an mcpCtx store; local stdio/CLI does not. Used to REFUSE local-path
 // file reads on the hosted connector (it runs on the SERVER host, not the user's machine — an LFI/exfil vector).
 export const isRemote = () => !!mcpCtx.getStore();
+
+// ── WHICH WORKSPACE'S STORE KEYS THIS CALL WRITES ──────────────────────────────────────────────────────────────
+// The suffix synced store keys carry (`` = the bare/anchor keys, `<clientSlug>` = a sub-brand). It comes from the
+// SERVER (`GET /api/workspace` → resolveWs), never from this process's environment, because on the hosted twin the
+// caller and the process are different tenants: HERMOSO_PROFILE names whatever workspace the SERVER's env happens to
+// mention, which for a hosted connector is nothing at all. That is how `use_brand "Client X"` kept reading and
+// WRITING the anchor brand (live 2026-08-01), and how draft_brand's save overwrote the default brand's profile.
+let _suffixMemo = null; // stdio/CLI only: one process = one caller, so a module-level memo is honest here
+async function fetchStoreSuffix() {
+  const w = await apiGet('/api/workspace'); // throws on failure — see storeSuffix()
+  if (!w || typeof w.storeSuffix !== 'string') throw new Error('Could not resolve this workspace.');
+  return w.storeSuffix;
+}
+export async function storeSuffix() {
+  const ctx = mcpCtx.getStore();
+  if (ctx) {
+    // HOSTED: memoize on the PER-REQUEST ctx object only. A module-level cache here would serve one customer's
+    // workspace suffix to the next caller on the same process — a silent cross-tenant write.
+    if (ctx._storeSuffix === undefined) ctx._storeSuffix = await fetchStoreSuffix();
+    return ctx._storeSuffix;
+  }
+  if (_suffixMemo === null) {
+    // stdio/CLI: the env pin is a REAL local authority (the process and the caller are the same person), so it is
+    // the fallback when an older server has no /api/workspace. A hosted call has no such fallback and must throw:
+    // guessing `bare` on a failed read is how the anchor brand gets overwritten, and a FAILED READ IS NOT EMPTY.
+    try { _suffixMemo = await fetchStoreSuffix(); }
+    catch { _suffixMemo = PROFILE && PROFILE !== 'default' ? PROFILE : ''; }
+  }
+  return _suffixMemo;
+}
+// use_brand / create_brand re-pin the key SERVER-SIDE, so the memo must not outlive the switch.
+export function forgetWorkspaceScope() {
+  _suffixMemo = null;
+  const ctx = mcpCtx.getStore();
+  if (ctx) delete ctx._storeSuffix;
+}
 // Upload raw file BYTES to /api/upload (150MB, persists → returns {url,kind,bytes}). Overrides the JSON content-type so
 // the server reads the raw body. Lets an agent post ARBITRARY user files (not just Hermoso renders).
 export async function apiUpload(p, buf, { contentType = 'application/octet-stream', fileName = '' } = {}) {
@@ -131,4 +195,4 @@ export async function toRef(srcOrPath) {
   return `data:${mime};base64,${buf.toString('base64')}`;
 }
 
-export const authState = () => ({ apiBase: API_BASE, hasToken: !!TOKEN, profile: PROFILE });
+export const authState = () => ({ apiBase: API_BASE, hasToken: !!TOKEN, profile: PROFILE, owner: OWNER });

package/mcp/http.mjs

@@ -13,6 +13,7 @@
 //
 // When the cloud step happens, the remaining work is small and explicit (see ENABLE CHECKLIST at the bottom).
 // ───────────────────────────────────────────────────────────────────────────────────────────────────────
+import { randomUUID } from 'node:crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { registerTools, MCP_INSTRUCTIONS } from './tools.mjs';
@@ -29,39 +30,148 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
   const BASE = (publicBaseUrl || process.env.HERMOSO_PUBLIC_URL || '').replace(/\/+$/, '');
 
   // RFC 9728 protected-resource metadata — tells Claude.ai where to get a token. (Authorization-server metadata
-  // is served by the auth provider itself, e.g. Firebase/your IdP.)
+  // is served by the auth provider itself, e.g. Firebase/your IdP.) Scopes match the AS metadata + minted token
+  // (mcp/oauth.mjs): hermoso.research / hermoso.generate.
   app.get('/.well-known/oauth-protected-resource', (req, res) => res.json({
     resource: `${BASE}/mcp`,
     authorization_servers: [process.env.HERMOSO_OAUTH_ISSUER].filter(Boolean),
-    scopes_supported: ['hermoso.generate', 'hermoso.research'],
+    scopes_supported: ['hermoso.research', 'hermoso.generate'],
     bearer_methods_supported: ['header'],
   }));
 
   // Per-session Streamable-HTTP transports. Each authenticated session gets its own McpServer with the same tools.
-  const sessions = new Map(); // mcp-session-id -> { transport, server }
+  //
+  // ── A SESSION IS EXPENSIVE, AND THIS MAP IS WHY PROD OOM'd (2026-08-01) ───────────────────────────────────────
+  // registerTools() builds 248 tool definitions with their zod schemas: **~36 MB of RETAINED heap per McpServer**
+  // (measured, node --expose-gc, 25 instances). This map used to be unbounded and never expired — the only removal
+  // was transport.onclose, which never fires for a client that simply goes away. Prod took 238 `initialize`
+  // handshakes in 49 minutes (238 × 36 MB = ~8.6 GB) on a 4 GiB, maxScale=1 instance and died of
+  // `FATAL ERROR: Reached heap limit` six times in that hour, every crash a full outage.
+  //
+  // The 400-on-a-session-miss below was the ACCELERANT: a client that cannot re-initialize opens a NEW session
+  // instead of reusing its own, so the leak fed itself. Both are fixed here — bound + expire the map, and answer
+  // the one status code that obliges a client to re-initialize.
+  const SESSION_MAX = Math.max(2, Number(process.env.MCP_SESSION_MAX || 16));            // ~580 MB ceiling for MCP
+  const SESSION_IDLE_MS = Math.max(1000, Number(process.env.MCP_SESSION_IDLE_MS || 30 * 60e3)); // 1s floor so the expiry is TESTABLE; a short TTL is merely wasteful now that eviction is recoverable
+  const sessions = new Map(); // mcp-session-id -> { transport, server, user, lastSeen }  (insertion-ordered = LRU)
   const challenge = (res) => res.status(401).set('WWW-Authenticate', `Bearer resource_metadata="${BASE}/.well-known/oauth-protected-resource"`).json({ error: 'Authentication required' });
 
+  // Tear a session down for real — dropping the map entry alone would leave the 36 MB McpServer reachable from
+  // the transport's own callbacks. Deleting FIRST makes this re-entrant-safe: transport.close() fires onclose,
+  // which calls back in here, and the second pass is a no-op.
+  function dropSession(id, why) {
+    const e = sessions.get(id);
+    if (!e) return false;
+    sessions.delete(id);
+    try { e.transport.close(); } catch {}
+    try { e.server.close(); } catch {}
+    if (why) console.error(`[mcp-remote] session ${id} closed (${why}); ${sessions.size} live`);
+    return true;
+  }
+  // Idle expiry + hard LRU cap. Evicting a LIVE session is safe now and only now: the evicted client's next call
+  // gets the 404 that makes it start a fresh session, instead of the 400 that bricked it forever.
+  function sweepSessions() {
+    const now = Date.now();
+    for (const [id, e] of sessions) if (now - e.lastSeen > SESSION_IDLE_MS) dropSession(id, 'idle');
+    while (sessions.size > SESSION_MAX) dropSession(sessions.keys().next().value, 'over cap');
+  }
+  const sweeper = setInterval(sweepSessions, 60e3);
+  sweeper.unref?.(); // never hold the process open for this
+
+  // MCP spec 2025-06-18, Transports § Session Management: a server that no longer has a session MUST answer 404,
+  // and on 404 the client MUST start a new session with a fresh InitializeRequest. 400 carries no such obligation,
+  // so a 400 here is permanent death for that connection — which is exactly what every deploy used to do to every
+  // hosted customer. -32001 "Session not found" is the SDK's own code for this case; we mint it ourselves because
+  // the SDK's branch is unreachable when there is no initialized transport left to compare the id against.
+  const sessionGone = (res) => res.status(404).json({ jsonrpc: '2.0', error: { code: -32001, message: 'Session not found' }, id: null });
+  // The SDK's own answer for a non-initialize request that names no session at all. We reply BEFORE constructing
+  // anything: building a 36 MB McpServer purely to have it reject the request is what turned a retry storm into
+  // an OOM. Status and message are byte-identical to the SDK's, so no client sees a behaviour change.
+  const needSession = (res) => res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Bad Request: Mcp-Session-Id header is required' }, id: null });
+  const hasInitialize = (body) => (Array.isArray(body) ? body : [body]).some((m) => m && m.method === 'initialize');
+
+  // ── PRE-AUTH DISCOVERY (registry crawlers + evaluating agents) ────────────────────────────────────────────────
+  // A tokenless caller may run the ZERO-SPEND MCP handshake — initialize, notifications/initialized, ping, tools/list
+  // — so a directory (registry.modelcontextprotocol.io) or an agent deciding whether to connect sees the REAL tool
+  // catalog first. Everything that spends (tools/call) stays strictly bearer-gated below: no anonymous spend, ever.
+  // Served from a fresh anonymous MCP server per request in the SDK's stateless mode (sessionIdGenerator undefined +
+  // JSON responses). Per-request instances are the supported shape — a single shared stateless transport 500s on the
+  // second standalone request (initialize and tools/list arrive as separate HTTP calls with no session between them).
+  const PREAUTH_METHODS = new Set(['initialize', 'notifications/initialized', 'ping', 'tools/list',
+    // Other zero-spend capability lists directory scanners (Smithery/Glama) probe anonymously. The only registered
+    // resources are the ChatGPT Apps SDK ui:// widget templates (static HTML, zero spend) — so resources/read is
+    // pre-auth too, letting ChatGPT/scanners fetch the templates. tools/call remains strictly bearer-gated.
+    'resources/list', 'resources/read', 'resources/templates/list', 'prompts/list', 'triggers/list']);
+  const isAllPreauth = (body) => {
+    const arr = Array.isArray(body) ? body : [body];
+    const methods = arr.map((m) => m && m.method).filter((v) => typeof v === 'string');
+    return methods.length > 0 && methods.every((m) => PREAUTH_METHODS.has(m)); // a batch mixing in tools/call is NOT pre-auth
+  };
+  async function serveAnonDiscovery(req, res) {
+    const server = new McpServer({ name: 'hermoso', version: '1.0.0' }, { instructions: MCP_INSTRUCTIONS });
+    registerTools(server); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+    res.on('close', () => { try { transport.close(); server.close(); } catch {} });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  }
+
   app.all('/mcp', async (req, res) => {
-    // EVERY call must carry a valid bearer — fail CLOSED (Claude.ai has historically made tokenless probe calls).
     const auth = req.headers.authorization || '';
     const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
     const user = token ? await verifyBearer(token).catch(() => null) : null;
-    if (!user) return challenge(res);
+    if (!user) {
+      // No valid bearer: allow ONLY the read-only discovery handshake (POST), fail CLOSED for everything else.
+      if (req.method === 'POST' && isAllPreauth(req.body)) return serveAnonDiscovery(req, res).catch(() => { try { challenge(res); } catch {} });
+      return challenge(res);
+    }
 
     const sid = req.headers['mcp-session-id'];
-    let entry = sid && sessions.get(sid);
+    let entry = sid ? sessions.get(sid) : null;
+
     if (!entry) {
+      const init = req.method === 'POST' && hasInitialize(req.body);
+      // A session id we do not have → 404, and WITHOUT allocating. This is the whole of D1b: 404 is the only status
+      // that obliges a client to re-initialize, so a restart, a deploy or an LRU eviction becomes a reconnect
+      // instead of a permanently bricked connector. It applies to every method — a stale id is stale for GET and
+      // DELETE too. The one exception is an `initialize`, which IS a client starting over: strict in what we send,
+      // liberal in what we accept, because the entire point of this fix is that nothing here bricks a client.
+      if (sid && !init) return sessionGone(res);
+      // Only an `initialize` may mint a session. Anything else naming no session at all is the SDK's own 400 —
+      // answered here so we never pay 36 MB to build a server whose only job would be to reject the request.
+      if (!init) return needSession(res);
+      sweepSessions(); // make room before allocating, so the cap is a ceiling and not a suggestion
       const server = new McpServer({ name: 'hermoso', version: '1.0.0' }, { instructions: MCP_INSTRUCTIONS });
       registerTools(server); // the SAME tools as stdio — but here every /api call they make carries this user's token
       const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => 'sess_' + Math.random().toString(36).slice(2),
-        onsessioninitialized: (id) => sessions.set(id, entry),
+        // CSPRNG, per the spec's SHOULD for session ids (Math.random() is not one).
+        sessionIdGenerator: () => 'sess_' + randomUUID().replace(/-/g, ''),
+        onsessioninitialized: (id) => { entry.lastSeen = Date.now(); sessions.set(id, entry); sweepSessions(); },
       });
-      transport.onclose = () => { if (transport.sessionId) sessions.delete(transport.sessionId); };
-      entry = { transport, server, user };
+      transport.onclose = () => { if (transport.sessionId) dropSession(transport.sessionId, 'transport closed'); };
+      entry = { transport, server, user, lastSeen: Date.now() };
       await server.connect(transport);
+      // If the handshake never completes (client drops, initialize rejected), nothing is in the map and both
+      // objects are otherwise reachable only from this request's still-open response — close them explicitly
+      // rather than leaving 36 MB pinned by a dead socket.
+      res.on('close', () => { if (!transport.sessionId || !sessions.has(transport.sessionId)) { try { transport.close(); } catch {} try { server.close(); } catch {} } });
+    } else {
+      // Touch = LRU. Re-inserting moves the key to the end of the Map's insertion order, so the cap evicts the
+      // genuinely coldest session rather than the oldest-established one (which is often the most active).
+      entry.lastSeen = Date.now();
+      sessions.delete(sid); sessions.set(sid, entry);
     }
-    await mcpCtx.run({ token }, () => entry.transport.handleRequest(req, res, req.body)); // the caller's bearer rides into every /api call the tools make — spend bills THEIR account
+    // The caller's bearer rides into every /api call the tools make — spend bills THEIR account. `remote: true`
+    // says what this store IS: a per-request tenant scope on a shared, multi-tenant process. client.mjs treats the
+    // presence of this store as the signal to STOP falling back to the process's own HERMOSO_PROFILE / HERMOSO_OWNER,
+    // which belong to whoever runs the box, not to whoever is calling.
+    //
+    // NOTE WHAT IS DELIBERATELY *NOT* HERE: a profile or an owner read off the request. There is nowhere honest to
+    // read them FROM — a header on the MCP POST would be caller-supplied, and a shared workspace resolved from a
+    // forgeable value is exactly the hole resolveWs exists to close. The workspace a hosted connector acts in is
+    // pinned SERVER-SIDE on the agent key (use_brand → /api/keys/brand, membership-checked) and re-authorized by
+    // resolveWs on every request, so it resolves identically here and over stdio without this transport naming it.
+    await mcpCtx.run({ token, remote: true }, () => entry.transport.handleRequest(req, res, req.body));
   });
 
   console.error(`[mcp-remote] mounted at ${BASE || '(set HERMOSO_PUBLIC_URL)'}/mcp`);