@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/expo/scripts/verify.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# verify.sh — Expo / EAS config gate.
+#
+# Run from the root of an Expo project:
+#   bash scripts/verify.sh
+#
+# Checks the EMITTED CONFIG ARTIFACTS, not your process:
+#   1. eas.json parses as JSON and declares a build.production profile.
+#   2. If EAS Update / expo-updates is in use, a runtimeVersion policy is declared
+#      (a hardcoded literal string is WARNED, not failed).
+#   3. No keystore / .p12 / .mobileprovision is tracked, and no obvious plaintext
+#      secret sits in app.config / app.json.
+#   4. Informational: flag dead newArchEnabled config on SDK >= 55 (Legacy
+#      Architecture was removed; the flag no longer exists in app.json).
+#
+# Read-only. Exits 0 on a clean OR empty/non-Expo target (no false failure).
+# Hard violations exit 1; soft issues print warnings only.
+# Portable to stock macOS bash 3.2.
+set -eu
+
+YELLOW=$'\033[1;33m'
+RED=$'\033[0;31m'
+GREEN=$'\033[0;32m'
+RESET=$'\033[0m'
+
+errors=0
+
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$1"; }
+info() { printf '==> %s\n' "$1"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$1"; errors=$((errors + 1)); }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# JSON validity helper: prefer node, fall back to python3, else skip the parse.
+json_valid() {
+  if have node; then
+    node -e "JSON.parse(require('fs').readFileSync('$1','utf8'))" >/dev/null 2>&1
+  elif have python3; then
+    python3 -c "import json,sys; json.load(open('$1'))" >/dev/null 2>&1
+  else
+    return 2  # cannot verify
+  fi
+}
+
+# Guard: only meaningful inside an Expo project. Empty/unrelated dir -> clean exit.
+app_config=""
+for f in app.config.ts app.config.js app.config.mjs app.config.cjs app.json app.config.json; do
+  [ -f "$f" ] && app_config="$f" && break
+done
+
+if [ -z "$app_config" ] && [ ! -f eas.json ]; then
+  warn "no app.config/app.json/eas.json in $PWD — not an Expo project; nothing to check"
+  exit 0
+fi
+
+# 1. eas.json — valid JSON + production profile.
+if [ -f eas.json ]; then
+  info "eas.json"
+  rc=0; json_valid eas.json || rc=$?
+  if [ "$rc" -eq 1 ]; then
+    fail "eas.json is not valid JSON"
+  elif [ "$rc" -eq 2 ]; then
+    warn "no node/python3 on PATH — skipping eas.json JSON parse"
+  fi
+  # production profile (tolerant grep; works even without a JSON parser)
+  if ! grep -Eq '"production"[[:space:]]*:' eas.json; then
+    fail "eas.json has no build.production profile — add one before releasing"
+  fi
+else
+  warn "no eas.json — run 'eas build:configure' to create build profiles"
+fi
+
+# 2. runtimeVersion policy, only if EAS Update / expo-updates is in use.
+uses_updates=false
+if [ -f package.json ] && grep -q 'expo-updates' package.json; then uses_updates=true; fi
+if [ -n "$app_config" ] && grep -q 'expo-updates\|EAS Update\|"updates"' "$app_config"; then uses_updates=true; fi
+
+if [ "$uses_updates" = true ]; then
+  info "runtimeVersion policy (EAS Update detected)"
+  if [ -n "$app_config" ]; then
+    if grep -q 'runtimeVersion' "$app_config"; then
+      # A policy object is good; a bare string literal is a footgun -> warn.
+      if grep -Eq 'runtimeVersion["'\'' ]*:[^{]*"[0-9A-Za-z._-]+"' "$app_config"; then
+        warn "runtimeVersion looks like a hardcoded literal in $app_config — prefer { policy: 'fingerprint' } so it tracks the native runtime"
+      fi
+    else
+      fail "EAS Update is in use but no runtimeVersion is declared in $app_config — add { policy: 'fingerprint' }"
+    fi
+  else
+    warn "EAS Update detected but no app.config to inspect for runtimeVersion"
+  fi
+fi
+
+# 3. Tracked credentials / secrets.
+info "credentials & secrets"
+secret_hits=$(find . \
+  -path ./node_modules -prune -o \
+  -type f \( -name '*.jks' -o -name '*.keystore' -o -name '*.p12' -o -name '*.mobileprovision' \) -print 2>/dev/null)
+if [ -n "$secret_hits" ]; then
+  fail "signing material is present in the tree (let EAS manage credentials, gitignore these):"
+  printf '%s\n' "$secret_hits" | sed 's/^/    /'
+fi
+
+# Plaintext secrets in app config (heuristic).
+if [ -n "$app_config" ]; then
+  if grep -Eiq '(api[_-]?key|secret|password|access[_-]?token|private[_-]?key)["'\'' ]*[:=]["'\'' ]*[A-Za-z0-9_\-]{12,}' "$app_config"; then
+    fail "possible plaintext secret in $app_config — app config ships in the public bundle; use EAS env vars or a backend"
+  fi
+fi
+
+# 4. New Architecture state (informational). Since SDK 55 the Legacy Architecture
+#    is gone and the New Architecture is always on; the newArchEnabled flag was
+#    removed from app.json. On SDK >= 55 any lingering flag is dead config.
+if [ -f package.json ]; then
+  sdk_major=$(grep -Eo '"expo"[[:space:]]*:[[:space:]]*"[~^>=<[:space:]]*[0-9]+' package.json 2>/dev/null \
+    | grep -Eo '[0-9]+$' | head -n1 || true)
+  if [ -n "${sdk_major:-}" ] && [ "$sdk_major" -ge 55 ] 2>/dev/null; then
+    if grep -Eq 'newArchEnabled' "${app_config:-/dev/null}" 2>/dev/null; then
+      warn "newArchEnabled is set in $app_config but was removed in SDK 55 — the New Architecture is always on now; delete the dead flag"
+    else
+      info "SDK $sdk_major detected — Legacy Architecture removed; New Architecture is always enabled"
+    fi
+  elif [ -n "${sdk_major:-}" ] && [ "$sdk_major" -eq 54 ] 2>/dev/null; then
+    info "SDK 54 detected — the last Legacy-Architecture release; SDK 55+ removed it, so plan your upgrade onto New Arch"
+  fi
+fi
+
+# Summary.
+if [ "$errors" -gt 0 ]; then
+  printf '%s%d hard violation(s).%s\n' "$RED" "$errors" "$RESET"
+  exit 1
+fi
+printf '%sall checks passed.%s\n' "$GREEN" "$RESET"

package/skills/shared/fal/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: fal
+description: "Use when calling a fal.ai endpoint by id to generate image, audio, or video from JS/Python/curl: subscribe vs submit, queue states, ED25519 webhook signature verification, per-call cost, or migrating off @fal-ai/serverless-client. NOT which model or art direction (that is ai-media); NOT the same models on another platform (that is replicate)."
+tags: [fal, fal-ai, inference, image-generation, video-generation, queue, webhooks, serverless]
+recommends: [ai-media, replicate, replicate-images, modal, webhooks]
+origin: ai-hub
+---
+
+# fal
+
+The wire to fal.ai's fast, pre-warmed media endpoints: call a model by id, control the queue, get the file back. fal is the **fast-media path** — latency-optimized image (FLUX, Seedream, SD), audio (TTS, music), and video (Veo, Wan, Kling, Hailuo) endpoints you invoke by id with `FAL_KEY`.
+
+You own the *mechanics*: auth, call mode, queue states, webhook signatures, file I/O, per-call cost.
+
+## When NOT to use
+
+| You want… | Go to |
+| --- | --- |
+| Which model / what to generate / art direction / multi-provider media pipeline | `ai-media` |
+| The same kind of models on **Replicate** (`replicate.run` / predictions) | `replicate` — images-specifically `replicate-images` |
+| Renting a **raw GPU pod** you SSH into to train or custom-serve | `runpod` |
+| Deploying **your own** Python function as an autoscaling endpoint | `modal` |
+| Cheap hosted **LLM text/chat** completions | `together-fireworks` |
+| The generic provider-agnostic webhook receiver/verifier pattern | `webhooks` |
+
+Rule: if you are not invoking a fal endpoint id with `FAL_KEY`, you are in the wrong skill.
+
+## Setup & auth
+
+```bash
+# JS — current client. NOT @fal-ai/serverless-client (deprecated, migrate).
+npm i @fal-ai/client          # latest 1.10.1
+
+# Python
+pip install fal-client
+```
+
+```bash
+export FAL_KEY="key_id:key_secret"
+```
+
+```ts
+import { fal } from "@fal-ai/client";
+// Reads FAL_KEY from env automatically; or set it explicitly:
+fal.config({ credentials: process.env.FAL_KEY });
+```
+
+Rule: **never ship `FAL_KEY` to a browser bundle.** Proxy every call through your own server. Why: a key in client-side JS lets anyone drain your account — fal endpoints bill per call with no per-request cap.
+
+## Pick a call mode
+
+All three modes hit the same queue. Choose by how long the job runs and where you call it from.
+
+| Situation | Mode | Why |
+| --- | --- | --- |
+| Need the result now, can block, single short job (image, short TTS) | `subscribe` | Submits + auto-polls until done; feels synchronous, no polling code |
+| Long job (video), batch, or running in a serverless/edge handler that can't hold a connection | `submit` + `webhook_url` (or poll) | Returns a `request_id` instantly; result arrives later, no held connection |
+| Trivially short call, you accept no queue control | `run` | Direct synchronous call — no status, no logs; drops on long jobs |
+
+```ts
+// Bad: run() on a 60s video — connection can drop, no retry, no progress.
+const res = await fal.run("fal-ai/veo3", { input });
+
+// Good: submit + webhook for anything that takes more than a few seconds.
+const { request_id } = await fal.queue.submit("fal-ai/veo3", {
+  input,
+  webhookUrl: "https://api.example.com/fal/webhook",
+});
+```
+
+## subscribe — block and stream progress
+
+```ts
+const result = await fal.subscribe("fal-ai/flux/dev", {
+  input: { prompt: "a red bicycle on a wet street, cinematic" },
+  logs: true,
+  onQueueUpdate: (update) => {
+    if (update.status === "IN_PROGRESS") {
+      update.logs?.forEach((l) => console.log(l.message)); // stream to user
+    }
+  },
+});
+console.log(result.data.images[0].url); // hosted output URL
+```
+
+```python
+import fal_client
+
+def on_update(update):
+    if isinstance(update, fal_client.InProgress):
+        for log in update.logs:
+            print(log["message"])
+
+result = fal_client.subscribe(
+    "fal-ai/flux/dev",
+    arguments={"prompt": "a red bicycle on a wet street, cinematic"},
+    with_logs=True,
+    on_queue_update=on_update,
+)
+print(result["images"][0]["url"])
+```
+
+Python has an async twin for every method — `subscribe_async`, `submit_async`, `run_async`. Use them inside an event loop.
+
+## submit + queue polling
+
+When you cannot or will not block, submit and poll the queue yourself.
+
+```ts
+const { request_id } = await fal.queue.submit("fal-ai/flux/dev", { input });
+
+// Poll. Status moves IN_QUEUE -> IN_PROGRESS -> COMPLETED.
+const status = await fal.queue.status("fal-ai/flux/dev", {
+  requestId: request_id,
+  logs: true,
+});
+
+// Once COMPLETED, fetch the result.
+const result = await fal.queue.result("fal-ai/flux/dev", { requestId: request_id });
+console.log(result.data.images[0].url);
+```
+
+Rule: **back off between polls** — start at ~1s, grow to a few seconds. Why: a tight `while` loop polling `queue.status` hammers the API and gains nothing; the job finishes when it finishes. For anything long-running, prefer a webhook over any polling at all.
+
+## Webhooks
+
+Pass `webhook_url` (camelCase `webhookUrl` in the JS client) on `submit`; fal POSTs the result when the job finishes.
+
+```jsonc
+// Success
+{ "request_id": "...", "gateway_request_id": "...", "status": "OK", "payload": { /* result */ } }
+// Failure
+{ "request_id": "...", "status": "ERROR", "error": "..." }
+// Result couldn't be serialized
+{ "request_id": "...", "status": "OK", "payload": null, "payload_error": "..." }
+```
+
+Delivery facts you must design for:
+
+- The initial POST has a **15-second timeout**. On timeout or non-2xx, fal **retries up to 10 times over ~2 hours**.
+- Therefore your handler **must be idempotent** — the same `request_id` can arrive more than once. Dedupe on `request_id` (e.g. an upsert keyed on it) before acting.
+- **Verify the ED25519 signature** before trusting the body — four `X-Fal-Webhook-*` headers + a JWKS fetched from `https://rest.fal.ai/.well-known/jwks.json`. Why: an unverified webhook endpoint is a public write to your DB / spend trigger.
+
+The full verification (header parsing, JWKS caching, ±5-minute timestamp check, message construction, per-key verify) and a complete idempotent handler in Node and Python live in [`references/queue-and-webhooks.md`](references/queue-and-webhooks.md).
+
+## File inputs and outputs
+
+Upload a local file to get a URL, then pass that URL into `input` for image-to-X jobs. Outputs always come back as hosted URLs.
+
+```ts
+const url = await fal.storage.upload(file); // File/Blob -> hosted URL
+const out = await fal.subscribe("fal-ai/flux/dev/image-to-image", {
+  input: { image_url: url, prompt: "make it snow" },
+});
+```
+
+```python
+url = fal_client.upload_file("input.png")
+out = fal_client.subscribe(
+    "fal-ai/flux/dev/image-to-image",
+    arguments={"image_url": url, "prompt": "make it snow"},
+)
+```
+
+## Cost control
+
+Pricing is **pay-per-use, per-model unit** — never flat. The unit differs by model, so always read the model's pricing tab before you ship a loop.
+
+| Unit | Used by | 2026 example |
+| --- | --- | --- |
+| Per image | image diffusion | Seedream V4 ~`$0.03`/image |
+| Per second of output | video | Wan 2.5 ~`$0.05`/s; Veo 3 ~`$0.4`/s |
+| Per megapixel | some image models | varies — read the tab |
+| GPU-hour | fal-served compute | A100 40GB `$0.99`/h, H100 80GB `$1.89`/h (2026-05-13) |
+
+Spend knobs, by modality:
+
+- **Image:** lower `num_inference_steps`, drop resolution / megapixels, cut `num_images`.
+- **Video:** shorten `duration`, lower fps/resolution — per-second pricing scales linearly.
+- **Batch:** fal **batch inference is 50% of serverless price** — use it for offline bulk jobs where latency does not matter.
+
+Worked estimate: 500 Seedream V4 images at ~$0.03 ≈ **$15** serverless, ≈ **$7.50** on the batch path.
+
+The full model-family map and per-modality knob list live in [`references/models-and-cost.md`](references/models-and-cost.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `FAL_KEY` in a browser bundle | Anyone reads it and bills your account | Proxy through your server |
+| `run` for a 30–60s video | Connection drops, no retry, no progress | `submit` + `webhook_url` |
+| Webhook handler with no signature check | Public write / spend trigger anyone can forge | Verify ED25519 against the JWKS |
+| Non-idempotent webhook handler | 10 retries over 2h create duplicate side effects | Dedupe on `request_id` |
+| Ignoring the model's pricing unit | "$0.05" is per-second, not per-video — surprise bill | Read the pricing tab; pick the right knob |
+| Tight `while` loop on `queue.status` | Hammers the API, gains nothing | Back off, or use a webhook |
+| `@fal-ai/serverless-client` | Deprecated; missing fixes and APIs | `@fal-ai/client` (v1.10.1) |

package/skills/shared/fal/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — fal
+
+These cases are run by the repo's eval harness: it loads `cases.yaml` and scores the skill's `description` + body against the `should_trigger` / `should_not_trigger` routing and the `capability` rubric. The `should_trigger` prompts (including the non-obvious "subscribe vs submit" and "signature won't verify" ones, and the Spanish webhook prompt) check that fal fires when an agent is wiring a fal endpoint call. The `should_not_trigger` prompts check the boundaries — each `route_to` id (`ai-media`, `replicate`, `runpod`, `modal`) must exist as a sibling skill for the routing to resolve. Because fal emits a checkable artifact (runnable client code + a webhook handler), the `capability` case is the real rigor check: the produced flow must hit every `must_include` item — current client + `FAL_KEY`, `submit` + `webhook_url` for the long job with the why, the webhook payload shape, ED25519 verification against the JWKS, an idempotent handler, reading the output URL, and a per-second cost estimate with the batch path. Run the harness from the repo root against `skills/fal/`.

package/skills/shared/fal/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: fal
+
+should_trigger:
+  - prompt: "Generate an image with fal-ai/flux/dev from this prompt and save the output URL"
+    why: Core synchronous generation against a fal endpoint id — the central use case.
+  - prompt: "Should I use subscribe or submit for a 30-second Veo video on fal?"
+    why: Call-mode decision; non-obvious — the right answer is submit + webhook, not subscribe or run.
+  - prompt: "My fal webhook signature verification keeps failing"
+    why: ED25519 / JWKS verification path; non-obvious failure that lives entirely in this skill.
+  - prompt: "How much will 500 Seedream images cost on fal, and is batch cheaper?"
+    why: Per-unit pricing estimate plus the 50% batch path.
+  - prompt: "Genera un vídeo con fal y recíbelo por webhook verificando la firma"
+    why: Spanish; submit + webhook + signature verification end to end.
+  - prompt: "Migrate our code off @fal-ai/serverless-client to the current fal client"
+    why: Deprecated-client migration is an explicit in-scope task.
+
+should_not_trigger:
+  - prompt: "Which video model gives the best cinematic look for our ad?"
+    route_to: ai-media
+    why: Model choice and art direction, not the fal call mechanics.
+  - prompt: "Run this same FLUX model on Replicate instead"
+    route_to: replicate
+    why: Different platform with a different API (replicate.run / predictions).
+  - prompt: "Spin up an A100 pod I can SSH into and train on"
+    route_to: runpod
+    why: Raw GPU rental, not endpoint inference.
+  - prompt: "Deploy my own Python inference function as an autoscaling endpoint"
+    route_to: modal
+    why: Serving your own code, not calling fal's hosted endpoints.
+
+capability:
+  - scenario: >
+      Given a FAL_KEY, a prompt, and a requirement to generate a long video and
+      receive it via webhook, produce the end-to-end flow.
+    must_include:
+      - "@fal-ai/client (or fal-client) install + FAL_KEY auth"
+      - "submit with webhook_url for the long job — NOT run/subscribe — with the why (no held connection / drop risk)"
+      - "webhook payload shape: request_id, status (OK/ERROR), payload (and payload_error case)"
+      - "ED25519 signature verification using the four X-Fal-Webhook-* headers and JWKS at rest.fal.ai/.well-known/jwks.json"
+      - "idempotent handler tolerating the 10-retries-over-2h duplicate deliveries (dedupe on request_id)"
+      - "reading the output URL from the result payload"
+      - "a per-second cost estimate and mention of the 50% batch path"

package/skills/shared/fal/references/models-and-cost.md

@@ -0,0 +1,53 @@
+# Models & cost
+
+How to find a fal endpoint, what its schema is, and what it costs. fal hosts hundreds of model endpoints across three modalities; you call them by id.
+
+## Finding an endpoint id and its schema
+
+1. Browse the fal model gallery; each model page shows its **endpoint id** (e.g. `fal-ai/flux/dev`), an input schema, an output schema, and a **pricing tab**.
+2. The endpoint id is what you pass to `subscribe` / `submit` / `run`.
+3. The input schema tells you required fields (`prompt`, `image_url`, `duration`, …) and the optional spend knobs.
+4. Sub-paths select a variant — e.g. `fal-ai/flux/dev` vs `fal-ai/flux/dev/image-to-image`.
+
+## Model-family map (2026)
+
+| Modality | Family | Example endpoints | Typical input |
+| --- | --- | --- | --- |
+| Image | FLUX | `fal-ai/flux/dev`, `fal-ai/flux-pro` | prompt, size, steps |
+| Image | Seedream | `fal-ai/bytedance/seedream/v4` | prompt, num_images |
+| Image | Stable Diffusion | `fal-ai/stable-diffusion-v35-large` | prompt, steps |
+| Video | Veo | `fal-ai/veo3` | prompt, duration |
+| Video | Wan | `fal-ai/wan-2.5` | prompt, duration, image_url |
+| Video | Kling / Hailuo | `fal-ai/kling-video/...`, `fal-ai/minimax/hailuo-...` | prompt, duration |
+| Audio | TTS | text-to-speech endpoints | text, voice |
+| Audio | Music | music-generation endpoints | prompt, duration |
+
+Endpoint ids shift as model versions ship — always confirm the id on the model page.
+
+## Pricing-unit cheatsheet
+
+Pricing is per-model and per-unit; the unit varies. Read the model page's pricing tab every time.
+
+| Unit | Modality | 2026 example (accessed 2026-06-02) |
+| --- | --- | --- |
+| Per image | image | Seedream V4 ~`$0.03`/image |
+| Per second of output | video | Wan 2.5 ~`$0.05`/s; Veo 3 ~`$0.4`/s |
+| Per megapixel | some image models | varies by model |
+| GPU-hour | fal-served compute | A100 40GB `$0.99`/h, H100 80GB `$1.89`/h (2026-05-13) |
+
+**Batch inference is 50% of the serverless price** — use it for offline bulk where latency does not matter.
+
+## Spend-control knobs by modality
+
+| Modality | Knobs that cut cost | Note |
+| --- | --- | --- |
+| Image | `num_inference_steps`, resolution / megapixels, `num_images` | fewer steps + smaller output = cheaper, usually fine |
+| Video | `duration`, fps, resolution | per-second pricing scales linearly with duration |
+| Audio | output length / duration | longer audio = more compute |
+
+## Worked estimates
+
+- 500 Seedream V4 images at ~$0.03 ≈ **$15** serverless; ≈ **$7.50** on the batch path.
+- A 10-second Veo 3 clip at ~$0.4/s ≈ **$4**; the same length on Wan 2.5 at ~$0.05/s ≈ **$0.50**.
+
+Cost moves with the unit and the model. Re-derive the estimate from the pricing tab before committing to a loop.

package/skills/shared/fal/references/queue-and-webhooks.md

@@ -0,0 +1,153 @@
+# Queue & webhooks — full async lifecycle
+
+The complete async path for fal jobs you cannot block on: submit, deliver by webhook, verify, dedupe.
+
+## Lifecycle
+
+```text
+submit(endpoint, { input, webhook_url })
+        │  returns { request_id } instantly
+        ▼
+   fal queue:  IN_QUEUE ──▶ IN_PROGRESS ──▶ COMPLETED
+        │                                      │
+        │  (you poll)                          │  (fal pushes)
+        ▼                                      ▼
+ queue.status(endpoint, { requestId })   POST webhook_url  { request_id, status, payload }
+ queue.result(endpoint, { requestId })   ── verify signature, dedupe, act ──
+```
+
+Pick **one** delivery mechanism per job: poll the queue *or* receive a webhook. Webhooks win for long jobs — no held connection, no polling cost.
+
+## Webhook payload shapes
+
+```jsonc
+// Success — result is in payload
+{ "request_id": "764cabcf-...", "gateway_request_id": "764cabcf-...", "status": "OK", "payload": { "images": [{ "url": "https://..." }] } }
+
+// Job failed
+{ "request_id": "764cabcf-...", "status": "ERROR", "error": "..." }
+
+// Job succeeded but result couldn't be serialized into the webhook
+{ "request_id": "764cabcf-...", "status": "OK", "payload": null, "payload_error": "..." }
+```
+
+`gateway_request_id` equals `request_id` in normal cases. Always branch on `status` first, then check `payload` vs `payload_error`.
+
+## Delivery, retries, idempotency
+
+- Initial POST has a **15-second timeout**. Respond fast — enqueue the work, return 200, process async.
+- On timeout or any non-2xx, fal **retries up to 10 times over roughly 2 hours**.
+- Your handler **must be idempotent**: the same `request_id` can arrive multiple times. Dedupe before side effects.
+
+```ts
+// Idempotent guard — record the request_id first; skip if already seen.
+const seen = await db.webhookEvents.findUnique({ where: { requestId } });
+if (seen) return res.status(200).end();      // already processed, ack the retry
+await db.webhookEvents.create({ data: { requestId } });
+// ...now do the side effect exactly once
+```
+
+## ED25519 signature verification
+
+Four headers travel with every webhook:
+
+| Header | Meaning |
+| --- | --- |
+| `X-Fal-Webhook-Request-Id` | the job's request id |
+| `X-Fal-Webhook-User-Id` | your fal user id |
+| `X-Fal-Webhook-Timestamp` | unix seconds when fal signed |
+| `X-Fal-Webhook-Signature` | hex-encoded ED25519 signature |
+
+Verification algorithm:
+
+1. Reject if `|now - timestamp| > 300` seconds (±5 min) — blocks replay.
+2. Fetch the JWKS from `https://rest.fal.ai/.well-known/jwks.json`; **cache it ≤ 24h**. Each key's `x` field is a base64url-encoded ED25519 public key.
+3. Build the signed message as four newline-joined parts: `request_id`, `user_id`, `timestamp`, and the **hex SHA-256 of the raw request body**.
+4. Hex-decode the signature.
+5. ED25519-verify the message against each JWKS key until one passes. If none pass, reject.
+
+Use the **raw** request body for the SHA-256 — re-serialized JSON will not match.
+
+### Node
+
+```ts
+import { createHash, verify } from "node:crypto";
+
+let jwksCache: { keys: any[]; at: number } | null = null;
+async function getJwks() {
+  if (jwksCache && Date.now() - jwksCache.at < 24 * 3600_000) return jwksCache.keys;
+  const r = await fetch("https://rest.fal.ai/.well-known/jwks.json");
+  const { keys } = await r.json();
+  jwksCache = { keys, at: Date.now() };
+  return keys;
+}
+
+export async function verifyFalWebhook(headers: Record<string, string>, rawBody: Buffer) {
+  const reqId = headers["x-fal-webhook-request-id"];
+  const userId = headers["x-fal-webhook-user-id"];
+  const ts = headers["x-fal-webhook-timestamp"];
+  const sigHex = headers["x-fal-webhook-signature"];
+  if (!reqId || !userId || !ts || !sigHex) return false;
+  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
+
+  const bodyHash = createHash("sha256").update(rawBody).digest("hex");
+  const message = Buffer.from([reqId, userId, ts, bodyHash].join("\n"), "utf-8");
+  const sig = Buffer.from(sigHex, "hex");
+
+  for (const jwk of await getJwks()) {
+    const pub = Buffer.from(jwk.x, "base64url"); // 32-byte raw ed25519 key
+    const der = Buffer.concat([
+      Buffer.from("302a300506032b6570032100", "hex"), // SPKI prefix for ed25519
+      pub,
+    ]);
+    const keyObj = { key: der, format: "der" as const, type: "spki" as const };
+    if (verify(null, message, keyObj as any, sig)) return true;
+  }
+  return false;
+}
+```
+
+### Python
+
+```python
+import time, hashlib, httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.exceptions import InvalidSignature
+
+_jwks = {"keys": None, "at": 0.0}
+
+def _get_jwks():
+    if _jwks["keys"] and time.time() - _jwks["at"] < 24 * 3600:
+        return _jwks["keys"]
+    keys = httpx.get("https://rest.fal.ai/.well-known/jwks.json").json()["keys"]
+    _jwks.update(keys=keys, at=time.time())
+    return keys
+
+def verify_fal_webhook(headers: dict, raw_body: bytes) -> bool:
+    import base64
+    req_id = headers.get("x-fal-webhook-request-id")
+    user_id = headers.get("x-fal-webhook-user-id")
+    ts = headers.get("x-fal-webhook-timestamp")
+    sig_hex = headers.get("x-fal-webhook-signature")
+    if not all([req_id, user_id, ts, sig_hex]):
+        return False
+    if abs(time.time() - int(ts)) > 300:
+        return False
+
+    body_hash = hashlib.sha256(raw_body).hexdigest()
+    message = "\n".join([req_id, user_id, ts, body_hash]).encode()
+    sig = bytes.fromhex(sig_hex)
+
+    for jwk in _get_jwks():
+        pub = base64.urlsafe_b64decode(jwk["x"] + "==")  # 32-byte raw key
+        try:
+            Ed25519PublicKey.from_public_bytes(pub).verify(sig, message)
+            return True
+        except InvalidSignature:
+            continue
+    return False
+```
+
+## Optional: IP allowlisting
+
+For an extra layer, restrict your endpoint to fal's egress ranges. Fetch `webhook_ip_ranges` from `https://api.fal.ai/v1/meta`. Ranges rotate — refresh periodically; do not hardcode. Signature verification is the primary defense; IP allowlisting is belt-and-suspenders.

package/skills/shared/fal/scripts/verify.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# verify.sh — static, offline checks for the fal skill's worked code.
+# Read-only. No network, no real FAL_KEY. Exit 0 on a clean/empty target.
+#
+# Usage: scripts/verify.sh [TARGET_DIR]
+#   TARGET_DIR defaults to the skill root (parent of this script's dir).
+# Checks the SKILL.md + references code fences for:
+#   1. no deprecated @fal-ai/serverless-client (must use @fal-ai/client)
+#   2. webhook section names all four X-Fal-Webhook-* headers + the JWKS URL
+#   3. long-job guidance uses submit/webhook_url and flags run as not-for-long-jobs
+#   4. FAL_KEY is referenced and no hardcoded key literal is present
+
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+target="${1:-$(cd "$here/.." && pwd)}"
+
+fail=0
+note() { printf '  - %s\n' "$1"; }
+err()  { printf 'FAIL: %s\n' "$1"; fail=1; }
+
+# Gather the skill's markdown files. Empty target => nothing to check => pass.
+# Portable to bash 3.2 (default macOS) — no mapfile.
+files="$(find "$target" -type f -name '*.md' 2>/dev/null | sort)"
+if [ -z "$files" ]; then
+  echo "verify(fal): no markdown files under $target — nothing to check."
+  exit 0
+fi
+file_count="$(printf '%s\n' "$files" | wc -l | tr -d ' ')"
+
+# Concatenated corpus for grep (read-only).
+corpus="$(printf '%s\n' "$files" | while IFS= read -r f; do cat "$f"; done 2>/dev/null || true)"
+
+# 1. deprecated client must not appear.
+if grep -q '@fal-ai/serverless-client' <<<"$corpus"; then
+  # Allowed only when explicitly flagged as deprecated/NOT/migrate on the same line.
+  if grep '@fal-ai/serverless-client' <<<"$corpus" \
+       | grep -qviE 'deprecat|NOT |migrate|anti-pattern'; then
+    err "deprecated @fal-ai/serverless-client referenced without a deprecation flag"
+  fi
+fi
+grep -q '@fal-ai/client' <<<"$corpus" || err "current @fal-ai/client never referenced"
+
+# 2. webhook headers + JWKS URL (only enforce if a webhook section exists).
+if grep -qi 'webhook' <<<"$corpus"; then
+  for h in X-Fal-Webhook-Request-Id X-Fal-Webhook-User-Id \
+           X-Fal-Webhook-Timestamp X-Fal-Webhook-Signature; do
+    grep -qi "$h" <<<"$corpus" || err "webhook header $h not documented"
+  done
+  grep -q 'rest.fal.ai/.well-known/jwks.json' <<<"$corpus" \
+    || err "JWKS URL rest.fal.ai/.well-known/jwks.json not referenced"
+fi
+
+# 3. long-job guidance: submit/webhook present, run flagged as not-for-long-jobs.
+grep -qiE 'webhook_url|webhookUrl' <<<"$corpus" || err "webhook_url not in guidance"
+grep -qi 'submit' <<<"$corpus" || err "submit call mode not documented"
+grep -qiE 'run.*(drop|long|no queue|few second)' <<<"$corpus" \
+  || err "'run' not flagged as unsuitable for long jobs"
+
+# 4. FAL_KEY referenced; no hardcoded key literal.
+grep -q 'FAL_KEY' <<<"$corpus" || err "FAL_KEY auth not referenced"
+# A real key looks like key_id:key_secret with long hex-ish parts; placeholders are fine.
+if grep -oE 'key_[0-9a-f]{16,}:[0-9a-f]{16,}' <<<"$corpus" >/dev/null; then
+  err "a hardcoded FAL_KEY literal appears in the docs"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify(fal): checks failed."
+  exit 1
+fi
+echo "verify(fal): all static checks passed ($file_count files)."
+exit 0