@ambasada/sdk 0.8.1 → 0.8.3

package/dist/platform.js

@@ -0,0 +1,821 @@
+// ../protocol/src/apps.ts
+var APP_SIGNATURE_HEADER = "x-ambasada-signature";
+var APP_TIMESTAMP_HEADER = "x-ambasada-timestamp";
+var APP_WEBHOOK_TOLERANCE_S = 300;
+var DEFAULT_HUB_URL = "https://hub.ambasada.id";
+var APP_NOTIFY_PATH = "/api/apps/notify";
+var AppWebhookError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "AppWebhookError";
+  }
+  reason;
+};
+var encoder = new TextEncoder();
+var keys = /* @__PURE__ */ new Map();
+function hmacKey(secret) {
+  let key = keys.get(secret);
+  if (!key) {
+    key = crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    keys.set(secret, key);
+  }
+  return key;
+}
+var hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+async function mac(secret, timestamp, body) {
+  return new Uint8Array(await crypto.subtle.sign("HMAC", await hmacKey(secret), encoder.encode(`${timestamp}.${body}`)));
+}
+async function signAppWebhook(secret, timestamp, body) {
+  if (!secret) throw new AppWebhookError("bad_secret", "no app secret");
+  return `v1=${hex(await mac(secret, String(timestamp), body))}`;
+}
+async function appWebhookHeaders(secret, body, timestamp = Math.floor(Date.now() / 1e3)) {
+  return { [APP_TIMESTAMP_HEADER]: String(timestamp), [APP_SIGNATURE_HEADER]: await signAppWebhook(secret, timestamp, body), "content-type": "application/json" };
+}
+function decodeSignature(value) {
+  if (/^[0-9a-f]{64}$/i.test(value)) return Uint8Array.from(value.match(/../g), (h) => parseInt(h, 16));
+  try {
+    const std = value.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(std + "===".slice((std.length + 3) % 4));
+    return bin.length === 32 ? Uint8Array.from(bin, (c) => c.charCodeAt(0)) : null;
+  } catch {
+    return null;
+  }
+}
+function equal(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+function header(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name);
+  const record = headers;
+  const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+  const value = key === void 0 ? void 0 : record[key];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+}
+async function verifyAppWebhook(secret, headers, body, { toleranceSeconds = APP_WEBHOOK_TOLERANCE_S, now = Math.floor(Date.now() / 1e3) } = {}) {
+  if (!secret) throw new AppWebhookError("bad_secret", "no app secret: set AMBASADA_APP_SECRET (injected on ambasada.dev; from the hub dashboard elsewhere)");
+  const ts = header(headers, APP_TIMESTAMP_HEADER);
+  const sig = header(headers, APP_SIGNATURE_HEADER);
+  if (!ts || !sig) throw new AppWebhookError("missing_headers", `missing ${APP_TIMESTAMP_HEADER} or ${APP_SIGNATURE_HEADER}`);
+  if (!/^\d+$/.test(ts.trim())) throw new AppWebhookError("bad_timestamp", `${APP_TIMESTAMP_HEADER} is not unix seconds`);
+  let timestamp = Number(ts.trim());
+  if (timestamp > 1e12) timestamp = Math.floor(timestamp / 1e3);
+  if (timestamp < now - toleranceSeconds) throw new AppWebhookError("too_old", "webhook timestamp is too old");
+  if (timestamp > now + toleranceSeconds) throw new AppWebhookError("too_new", "webhook timestamp is in the future");
+  const expected = await mac(secret, ts.trim(), body);
+  const candidates = sig.split(/[\s,]+/).map((part) => /^v1=(.+)$/.exec(part.trim())?.[1]).filter((v) => !!v).map(decodeSignature).filter((v) => v !== null);
+  if (!candidates.some((c) => equal(c, expected))) throw new AppWebhookError("bad_signature", "webhook signature does not match: check AMBASADA_APP_SECRET");
+  let event;
+  try {
+    event = JSON.parse(body);
+  } catch {
+    throw new AppWebhookError("bad_body", "webhook body is not JSON");
+  }
+  if (!event || typeof event !== "object" || typeof event.event !== "string") throw new AppWebhookError("bad_body", 'webhook body has no "event"');
+  return event;
+}
+var NOTIFY_LIMITS = { notification_id: 128, title: 40, body: 140, recipients: 100, collapse_key: 128, ttl_seconds: 7 * 24 * 3600 };
+var CATEGORIES = ["transactional", "social", "marketing"];
+function appNotifyBody(input, origin) {
+  const fail = (message) => {
+    throw new Error(message);
+  };
+  const id = typeof input.notification_id === "string" ? input.notification_id : "";
+  if (!id || id.length > NOTIFY_LIMITS.notification_id) fail(`notification_id must be 1\u2013${NOTIFY_LIMITS.notification_id} characters`);
+  const title = typeof input.title === "string" ? input.title.trim() : "";
+  if (!title || title.length > NOTIFY_LIMITS.title) fail(`title must be 1\u2013${NOTIFY_LIMITS.title} characters (got ${title.length})`);
+  const body = typeof input.body === "string" ? input.body.trim() : "";
+  if (body.length > NOTIFY_LIMITS.body) fail(`body must be at most ${NOTIFY_LIMITS.body} characters (got ${body.length})`);
+  const url = typeof input.url === "string" ? input.url.trim() : "";
+  if (!url) fail("url is required: a path on your app (/orders/184) or a URL on its origin");
+  if (url.startsWith("/")) {
+    if (url.startsWith("//") || url.startsWith("/\\") || /[\u0000-\u001f\u007f]/.test(url)) fail(`url ${JSON.stringify(url)} is not a path on your app`);
+  } else {
+    let parsed = null;
+    try {
+      parsed = new URL(url);
+    } catch {
+      fail(`url ${JSON.stringify(url)} is not a URL or a path`);
+    }
+    if (parsed.protocol !== "https:" && !(origin && parsed.origin === new URL(origin).origin && /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(parsed.origin))) fail("url must be https");
+    if (parsed.username || parsed.password) fail("url must not carry credentials");
+    if (origin && parsed.origin !== new URL(origin).origin) fail(`url must be on your app's origin ${new URL(origin).origin} (got ${parsed.origin})`);
+  }
+  const tokens = input.tokens ?? [];
+  const users = input.users ?? [];
+  if (!Array.isArray(tokens) || !Array.isArray(users)) fail("tokens and users must be arrays");
+  if (tokens.length && users.length) fail("send tokens or users, not both");
+  const recipients = tokens.length ? tokens : users;
+  if (!recipients.length) fail("no recipients: pass tokens (from notifications_enabled) or users");
+  if (recipients.length > NOTIFY_LIMITS.recipients) fail(`at most ${NOTIFY_LIMITS.recipients} recipients per call (got ${recipients.length})`);
+  if (recipients.some((r) => typeof r !== "string" || !r)) fail("recipients must be non-empty strings");
+  const category = input.category ?? "transactional";
+  if (!CATEGORIES.includes(category)) fail(`category must be one of ${CATEGORIES.join(", ")}`);
+  if (input.collapse_key !== void 0 && (typeof input.collapse_key !== "string" || !input.collapse_key || input.collapse_key.length > NOTIFY_LIMITS.collapse_key)) fail(`collapse_key must be 1\u2013${NOTIFY_LIMITS.collapse_key} characters`);
+  if (input.ttl_seconds !== void 0 && (!Number.isInteger(input.ttl_seconds) || input.ttl_seconds < 0 || input.ttl_seconds > NOTIFY_LIMITS.ttl_seconds)) fail(`ttl_seconds must be an integer 0\u2013${NOTIFY_LIMITS.ttl_seconds}`);
+  return {
+    notification_id: id,
+    title,
+    body,
+    url,
+    ...tokens.length ? { tokens } : { users },
+    category,
+    ...input.collapse_key !== void 0 ? { collapse_key: input.collapse_key } : {},
+    ...input.ttl_seconds !== void 0 ? { ttl_seconds: input.ttl_seconds } : {}
+  };
+}
+function appNotifyResult(json) {
+  const o = json && typeof json === "object" ? json : {};
+  const list = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+  return { sent: list(o.sent), invalid: list(o.invalid), rate_limited: list(o.rate_limited) };
+}
+
+// src/errors.ts
+var ERROR_STATUS = {
+  // EXCHANGE.md §5 vocabulary
+  INSUFFICIENT_FUNDS: 402,
+  OFFLINE: 503,
+  TIMEOUT: 504,
+  SCHEMA_INVALID: 502,
+  CAP_BUYER_HOURLY: 429,
+  CAP_SELLER_RATE: 429,
+  DEAL_EXHAUSTED: 409,
+  DEPTH_EXCEEDED: 422,
+  BUDGET_EXCEEDED: 402,
+  // Gateway and bank
+  UPSTREAM_ERROR: 502,
+  PRICE_ABOVE_MAX: 409,
+  SELF_PURCHASE: 403,
+  INVALID_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  IDEMPOTENCY_CONFLICT: 422,
+  IDEMPOTENCY_IN_PROGRESS: 409,
+  HOLD_NOT_ACTIVE: 409,
+  INTERNAL: 500,
+  // Spending limits and approvals (checkout stream)
+  CAP_PER_PAYMENT: 403,
+  CAP_BUYER_DAILY: 429,
+  CAP_PAYEE_DAILY: 429,
+  CAP_VISITOR_DAILY: 429,
+  APPROVAL_REQUIRED: 403,
+  APPROVAL_INVALID: 403,
+  APPROVALS_PENDING: 429,
+  // LLMOK mapping (utilities stream, docs/LLMOK.md)
+  PROVIDER_BUDGET: 503,
+  PROVIDER_DENIED: 502,
+  // Clock windows (agent stream): deploys / steering refused while frozen
+  FROZEN: 403,
+  // Exchange stream: an agent sent too many inbox messages
+  CAP_INBOX_RATE: 429,
+  // SDK-side
+  NETWORK: 0,
+  CONFIG: 0,
+  RECEIPT_INVALID: 402,
+  WEBHOOK_INVALID: 400
+};
+var BRAND = /* @__PURE__ */ Symbol.for("ambasada.error");
+var AmbasadaError = class _AmbasadaError extends Error {
+  code;
+  /** HTTP status (0 when the request never got an answer). */
+  status;
+  details;
+  constructor(code, message, status, details = {}) {
+    super(message);
+    this.name = "AmbasadaError";
+    this.code = code;
+    this.status = status ?? ERROR_STATUS[code] ?? 500;
+    this.details = details;
+    Object.defineProperty(this, BRAND, { value: true });
+  }
+  /** `instanceof AmbasadaError` holds across bundled copies; subclasses keep the usual prototype check. */
+  static [Symbol.hasInstance](value) {
+    if (this !== _AmbasadaError) return Function.prototype[Symbol.hasInstance].call(this, value);
+    return typeof value === "object" && value !== null && value[BRAND] === true;
+  }
+  get callId() {
+    return this.details.call_id;
+  }
+  get refunded() {
+    return this.details.refunded === true;
+  }
+  get approvalId() {
+    return this.details.approval_id;
+  }
+  /** The wire shape, e.g. to pass an error on from your own endpoint. */
+  toJSON() {
+    return { error: { code: this.code, message: this.message, ...this.details } };
+  }
+  /** A `Response` with the wire shape and status (402 for receipt problems). */
+  toResponse() {
+    return Response.json(this.toJSON(), { status: this.status || 500 });
+  }
+};
+var WebhookInvalidError = class extends AmbasadaError {
+  reason;
+  constructor(reason, message) {
+    super("WEBHOOK_INVALID", message, 400, { reason });
+    this.name = "WebhookInvalidError";
+    this.reason = reason;
+  }
+};
+function isAmbasadaError(value, code) {
+  return value instanceof AmbasadaError && (code === void 0 || value.code === code);
+}
+function errorFromResponse(status, body, fallback) {
+  const error = typeof body === "object" && body !== null ? body.error : void 0;
+  if (typeof error === "object" && error !== null && typeof error.code === "string") {
+    const { code: code2, message, ...details } = error;
+    return new AmbasadaError(code2, typeof message === "string" ? message : code2, status, details);
+  }
+  const code = status === 401 ? "UNAUTHORIZED" : status === 404 ? "NOT_FOUND" : status >= 500 ? "INTERNAL" : "INVALID_REQUEST";
+  return new AmbasadaError(code, fallback, status);
+}
+
+// src/apps.ts
+var APP_SIGNATURE_HEADER2 = "x-ambasada-signature";
+var APP_TIMESTAMP_HEADER2 = "x-ambasada-timestamp";
+var signAppWebhook2 = (secret, timestamp, body) => signAppWebhook(secret, timestamp, body);
+var appWebhookHeaders2 = (secret, body, timestamp) => appWebhookHeaders(secret, body, timestamp);
+var AmbasadaApps = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /** True when the app has its secret (hosted on ambasada.dev, `ambasada dev`, or set by hand). */
+  get configured() {
+    return !!this.config().appSecret;
+  }
+  /**
+   * Verifies a webhook from the hub (signature, 5-minute window) and returns the event, or throws
+   * `WebhookInvalidError` (answer it with `error.toResponse()`, a 400). Read nothing from the request before.
+   */
+  async verifyWebhook(input, secret, options = {}) {
+    const key = secret ?? this.config().appSecret;
+    if (!key) throw new WebhookInvalidError("bad_secret", "no app secret: set AMBASADA_APP_SECRET (injected on ambasada.dev, from the hub dashboard elsewhere) or pass it");
+    const isRequest = typeof input.text === "function" && input.headers instanceof Headers;
+    const headers = isRequest ? input.headers : input.headers;
+    const raw = isRequest ? await input.text() : input.body;
+    const body = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    try {
+      return await verifyAppWebhook(key, headers, body, options);
+    } catch (error) {
+      if (error instanceof AppWebhookError) throw new WebhookInvalidError(error.reason, error.message);
+      throw error;
+    }
+  }
+  /**
+   * Sends a push to the people behind `tokens` (or `users`, for Verified apps with `identity`) through the hub.
+   * Checks the limits first (title ≤ 40, body ≤ 140, id ≤ 128, ≤ 100 recipients, `url` on your origin) and
+   * throws `AmbasadaError("INVALID_REQUEST")` before sending anything. Tokens in `invalid` are gone: forget them.
+   */
+  async notify(input) {
+    const c = this.config();
+    if (!c.appSecret) throw new AmbasadaError("CONFIG", "no app secret: set AMBASADA_APP_SECRET (injected on ambasada.dev; `ambasada dev` sets one for the mock hub)");
+    let body;
+    try {
+      body = appNotifyBody(input, c.origin);
+    } catch (error) {
+      throw new AmbasadaError("INVALID_REQUEST", error.message, 400);
+    }
+    const url = `${(c.hubUrl ?? DEFAULT_HUB_URL).replace(/\/+$/, "")}${APP_NOTIFY_PATH}`;
+    const doFetch = c.fetch ?? ((i, init) => fetch(i, init));
+    let res;
+    try {
+      res = await doFetch(url, {
+        method: "POST",
+        headers: { authorization: `Bearer ${c.appSecret}`, "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(15e3)
+      });
+    } catch (error) {
+      throw new AmbasadaError("NETWORK", `POST ${url}: ${error.message}`, 0);
+    }
+    const json = await res.json().catch(() => null);
+    if (!res.ok) {
+      const err = json?.error;
+      const code = typeof err === "object" && err?.code ? err.code : res.status === 401 || res.status === 403 ? "UNAUTHORIZED" : res.status === 429 ? "CAP_SELLER_RATE" : res.status >= 500 ? "UPSTREAM_ERROR" : "INVALID_REQUEST";
+      const message = typeof err === "string" ? err : err?.message ?? `the hub answered ${res.status}`;
+      throw new AmbasadaError(code, `notify: ${message}`, res.status);
+    }
+    return appNotifyResult(json);
+  }
+};
+
+// src/auth.ts
+var AUTH_PATHS = { login: "/api/auth/login", callback: "/api/auth/callback", logout: "/api/auth/logout", shell: "/api/auth/shell" };
+var SESSION_TTL_S = 7 * 24 * 3600;
+var STATE_TTL_S = 600;
+var SESSION_COOKIE = "ambasada_session";
+var STATE_COOKIE = "ambasada_auth";
+var enc = new TextEncoder();
+function b64url(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(text) {
+  const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+var random = (n) => b64url(crypto.getRandomValues(new Uint8Array(n)));
+async function pkce() {
+  const verifier = random(32);
+  return { verifier, challenge: await pkceChallenge(verifier) };
+}
+async function pkceChallenge(verifier) {
+  return b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(verifier))));
+}
+var keys2 = /* @__PURE__ */ new Map();
+function cookieKey(secret, purpose) {
+  const id = `${purpose}
+${secret}`;
+  let key = keys2.get(id);
+  if (!key) {
+    key = crypto.subtle.importKey("raw", enc.encode(secret), "HKDF", false, ["deriveKey"]).then(
+      (ikm) => crypto.subtle.deriveKey(
+        { name: "HKDF", hash: "SHA-256", salt: enc.encode("ambasada auth cookie v1"), info: enc.encode(purpose) },
+        ikm,
+        { name: "HMAC", hash: "SHA-256", length: 256 },
+        false,
+        ["sign", "verify"]
+      )
+    );
+    keys2.set(id, key);
+  }
+  return key;
+}
+async function signCookie(secret, purpose, payload) {
+  const body = b64url(enc.encode(JSON.stringify(payload)));
+  const sig = await crypto.subtle.sign("HMAC", await cookieKey(secret, purpose), enc.encode(body));
+  return `${body}.${b64url(new Uint8Array(sig))}`;
+}
+async function verifyCookie(secret, purpose, value, now = Date.now()) {
+  if (!value) return null;
+  const [body, sig, extra] = value.split(".");
+  if (!body || !sig || extra !== void 0) return null;
+  try {
+    const ok = await crypto.subtle.verify("HMAC", await cookieKey(secret, purpose), fromB64url(sig), enc.encode(body));
+    if (!ok) return null;
+    const payload = JSON.parse(new TextDecoder().decode(fromB64url(body)));
+    return typeof payload.exp === "number" && payload.exp * 1e3 > now ? payload : null;
+  } catch {
+    return null;
+  }
+}
+function readCookie(req, name) {
+  for (const part of (req.headers.get("cookie") ?? "").split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
+  }
+  return null;
+}
+var cookieName = (base, secure) => secure ? `__Host-${base}` : base;
+var readOurCookie = (req, base) => readCookie(req, cookieName(base, true)) ?? readCookie(req, base);
+function setCookie(base, value, secure, maxAge) {
+  return `${cookieName(base, secure)}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+function safeReturnTo(value) {
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\") || /[\u0000-\u001f\u007f]/.test(value)) return "/";
+  return value;
+}
+function redirect(location, cookies = []) {
+  const headers = new Headers({ location, "cache-control": "no-store" });
+  for (const c of cookies) headers.append("set-cookie", c);
+  return new Response(null, { status: 303, headers });
+}
+var JWKS_TTL_MS = 36e5;
+var LEEWAY_S = 30;
+var jwksCache = /* @__PURE__ */ new Map();
+async function jwks(issuer, doFetch, refresh = false) {
+  const cached = jwksCache.get(issuer);
+  if (cached && !refresh && Date.now() - cached.at < JWKS_TTL_MS) return cached.keys;
+  if (cached && refresh && Date.now() - cached.at < 6e4) return cached.keys;
+  const res = await doFetch(`${issuer}/.well-known/jwks.json`, { headers: { accept: "application/json" } });
+  if (!res.ok) throw new AmbasadaError("UPSTREAM_ERROR", `could not read the Ambasada ID keys (${res.status})`, 502);
+  const body = await res.json();
+  const keys3 = (body.keys ?? []).filter((k) => k.kty === "RSA" && k.n && k.e);
+  jwksCache.set(issuer, { at: Date.now(), keys: keys3 });
+  return keys3;
+}
+var shellRefused = (message) => new AmbasadaError("UNAUTHORIZED", `shell token refused: ${message}`, 401);
+var AmbasadaAuth = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /** True when the product has credentials (hosted on ambasada.dev, or `ambasada dev`). */
+  get configured() {
+    const c = this.config();
+    return !!(c.clientId && c.clientSecret && c.issuer);
+  }
+  settings(req) {
+    const c = this.config();
+    if (!c.clientId || !c.clientSecret || !c.issuer) {
+      throw new AmbasadaError("CONFIG", "Sign in with Ambasada is not set up: it works on https://<slug>.ambasada.dev after `ambasada deploy`, and locally under `ambasada dev` (AMBASADA_AUTH_CLIENT_ID / _SECRET / _ISSUER)");
+    }
+    const origin = (c.publicUrl ? new URL(c.publicUrl) : new URL(req.url)).origin;
+    return {
+      clientId: c.clientId,
+      clientSecret: c.clientSecret,
+      issuer: c.issuer.replace(/\/+$/, ""),
+      apiUrl: c.apiUrl.replace(/\/+$/, ""),
+      origin,
+      secure: origin.startsWith("https:"),
+      redirectUri: `${origin}${AUTH_PATHS.callback}`,
+      // Called as a plain function: workerd refuses `fetch` invoked as a method of another object.
+      fetch: c.fetch ?? ((input, init) => fetch(input, init))
+    };
+  }
+  /** Redirects to Ambasada ID (consent screen) with PKCE; a short-lived signed cookie holds the state. */
+  async login(req, options = {}) {
+    const s = this.settings(req);
+    const { verifier, challenge } = await pkce();
+    const state = random(16);
+    const returnTo = safeReturnTo(options.returnTo ?? new URL(req.url).searchParams.get("returnTo"));
+    const url = new URL(`${s.issuer}/oauth/authorize`);
+    url.search = new URLSearchParams({
+      response_type: "code",
+      client_id: s.clientId,
+      redirect_uri: s.redirectUri,
+      scope: options.email ? "openid profile email" : "openid profile",
+      state,
+      code_challenge: challenge,
+      code_challenge_method: "S256"
+    }).toString();
+    const value = await signCookie(s.clientSecret, "state", { state, verifier, returnTo, exp: Math.floor(Date.now() / 1e3) + STATE_TTL_S });
+    return redirect(url.toString(), [setCookie(STATE_COOKIE, value, s.secure, STATE_TTL_S)]);
+  }
+  /**
+   * Ambasada ID sends the person back here: checks the state, exchanges the code (with the PKCE
+   * verifier and the client secret), reads their profile from the Ambasada API, sets the session cookie
+   * and redirects to `returnTo`. A refused consent goes back to `returnTo` signed out.
+   */
+  async callback(req) {
+    const s = this.settings(req);
+    const params = new URL(req.url).searchParams;
+    const clear = setCookie(STATE_COOKIE, "", s.secure, 0);
+    const saved = await verifyCookie(s.clientSecret, "state", readOurCookie(req, STATE_COOKIE));
+    if (!saved || !params.get("state") || params.get("state") !== saved.state) {
+      throw new AmbasadaError("UNAUTHORIZED", "sign-in expired or was started elsewhere: try again", 400);
+    }
+    const returnTo = safeReturnTo(saved.returnTo);
+    if (params.get("error")) return redirect(returnTo, [clear]);
+    const code = params.get("code");
+    if (!code) throw new AmbasadaError("INVALID_REQUEST", "no authorization code", 400);
+    const token = await s.fetch(`${s.issuer}/oauth/token`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        accept: "application/json",
+        authorization: `Basic ${btoa(`${encodeURIComponent(s.clientId)}:${encodeURIComponent(s.clientSecret)}`)}`
+      },
+      body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: s.redirectUri, code_verifier: saved.verifier })
+    });
+    const tokens = await token.json().catch(() => ({}));
+    if (!token.ok || !tokens.access_token) throw new AmbasadaError("UNAUTHORIZED", `Ambasada ID refused the sign-in (${tokens.error ?? token.status})`, 401);
+    const res = await s.fetch(`${s.apiUrl}/v1/auth/profile`, { headers: { authorization: `Bearer ${tokens.access_token}`, accept: "application/json" } });
+    if (!res.ok) throw new AmbasadaError("UPSTREAM_ERROR", `could not read the Ambasada profile (${res.status})`, 502);
+    const user = await res.json();
+    const exp = Math.floor(Date.now() / 1e3) + SESSION_TTL_S;
+    const session = await signCookie(s.clientSecret, "session", { user, exp });
+    return redirect(returnTo, [clear, setCookie(SESSION_COOKIE, session, s.secure, SESSION_TTL_S)]);
+  }
+  /** Whoever is signed in on this request, or null (also null when sign-in is not set up). */
+  async user(req) {
+    const secret = this.config().clientSecret;
+    if (!this.configured || !secret) return null;
+    return (await verifyCookie(secret, "session", readOurCookie(req, SESSION_COOKIE)))?.user ?? null;
+  }
+  /**
+   * Verifies a shell token (Clerk JWT template `ambasada-miniapp`, RS256, 60 s) against
+   * `<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json` (cached 1 h): signature, expiry, issuer, and that its `aud`
+   * is this app (its id or origin). Returns who it is, or throws `AmbasadaError("UNAUTHORIZED")`.
+   */
+  async verifyShellToken(token, options = {}) {
+    const c = this.config();
+    if (!c.issuer) throw new AmbasadaError("CONFIG", "silent sign-in needs AMBASADA_AUTH_ISSUER (injected on ambasada.dev and by `ambasada dev`)");
+    const trusted = [c.issuer, c.hubUrl].filter((v) => !!v).map((v) => v.replace(/\/+$/, ""));
+    const audiences = [options.audience ?? c.audiences ?? []].flat().filter(Boolean).map((a) => a.replace(/\/+$/, ""));
+    if (!audiences.length) throw new AmbasadaError("CONFIG", "silent sign-in needs to know this app: set AMBASADA_APP_ORIGIN or PUBLIC_URL, or pass { audience }");
+    const doFetch = c.fetch ?? ((input, init) => fetch(input, init));
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3) throw shellRefused("not a JWT");
+    let header2;
+    let claims;
+    try {
+      header2 = JSON.parse(new TextDecoder().decode(fromB64url(parts[0])));
+      claims = JSON.parse(new TextDecoder().decode(fromB64url(parts[1])));
+    } catch {
+      throw shellRefused("not a JWT");
+    }
+    if (header2.alg !== "RS256") throw shellRefused(`alg ${String(header2.alg)} (only RS256)`);
+    const iss = typeof claims.iss === "string" ? claims.iss.replace(/\/+$/, "") : null;
+    if (iss && !trusted.includes(iss)) throw shellRefused(`issuer ${claims.iss}`);
+    const issuer = iss ?? trusted[0];
+    let keys3 = await jwks(issuer, doFetch);
+    let jwk = keys3.find((k) => k.kid === header2.kid) ?? (!header2.kid && keys3.length === 1 ? keys3[0] : void 0);
+    if (!jwk) {
+      keys3 = await jwks(issuer, doFetch, true);
+      jwk = keys3.find((k) => k.kid === header2.kid);
+    }
+    if (!jwk) throw shellRefused(`unknown key ${String(header2.kid)}`);
+    const key = await crypto.subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true }, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+    const ok = await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, fromB64url(parts[2]), enc.encode(`${parts[0]}.${parts[1]}`));
+    if (!ok) throw shellRefused("bad signature");
+    const now = Math.floor((options.now ?? Date.now()) / 1e3);
+    if (typeof claims.exp !== "number" || claims.exp + LEEWAY_S < now) throw shellRefused("expired");
+    if (typeof claims.nbf === "number" && claims.nbf - LEEWAY_S > now) throw shellRefused("not valid yet");
+    if (typeof claims.iat === "number" && claims.iat - LEEWAY_S > now) throw shellRefused("issued in the future");
+    const aud = [claims.aud].flat().filter((a) => typeof a === "string").map((a) => a.replace(/\/+$/, ""));
+    if (!aud.some((a) => audiences.includes(a))) throw shellRefused(`it is for ${aud.join(", ") || "no app"}, not this one`);
+    if (typeof claims.sub !== "string" || !claims.sub) throw shellRefused("no subject");
+    const text = (v) => typeof v === "string" && v ? v : null;
+    return { user_id: claims.sub, name: text(claims.name), avatar: text(claims.avatar) ?? text(claims.picture) ?? text(claims.image_url) };
+  }
+  /**
+   * Silent sign-in: `POST /api/auth/shell` with `{ "token": "<auth.getToken() token>" }` (or `Authorization: Bearer`).
+   * Verifies it, reads the full profile from the hub (falling back to what the token carries) and sets the same
+   * session cookie as `callback()`, so a person signed in inside the app and one signed in on the web look the same.
+   * Answers `{ user }`.
+   */
+  async shell(req) {
+    const s = this.settings(req);
+    if (req.method !== "POST") throw new AmbasadaError("INVALID_REQUEST", "POST the shell token as JSON { token }", 405);
+    let token = /^Bearer\s+(.+)$/i.exec(req.headers.get("authorization") ?? "")?.[1]?.trim();
+    if (!token) {
+      if (!(req.headers.get("content-type") ?? "").includes("application/json")) throw new AmbasadaError("INVALID_REQUEST", "send the token as JSON { token }", 415);
+      const body = await req.json().catch(() => null);
+      token = typeof body?.token === "string" ? body.token : void 0;
+    }
+    if (!token) throw new AmbasadaError("INVALID_REQUEST", "no shell token", 400);
+    const audiences = [...this.config().audiences ?? [], s.origin];
+    const who = await this.verifyShellToken(token, { audience: audiences });
+    let user = { id: who.user_id, name: who.name, avatar_url: who.avatar, builder: false, builder_since: null, member_since: null, pass: null };
+    const hub = this.config().hubUrl;
+    if (hub) {
+      try {
+        const res = await s.fetch(`${hub.replace(/\/+$/, "")}/api/apps/profile`, { headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
+        if (res.ok) {
+          const profile = await res.json();
+          if (profile.id === who.user_id) user = { ...user, ...profile, id: who.user_id };
+        } else await res.body?.cancel();
+      } catch {
+      }
+    }
+    const exp = Math.floor(Date.now() / 1e3) + SESSION_TTL_S;
+    const session = await signCookie(s.clientSecret, "session", { user, exp });
+    const headers = new Headers({ "cache-control": "no-store", "content-type": "application/json" });
+    headers.append("set-cookie", setCookie(SESSION_COOKIE, session, s.secure, SESSION_TTL_S));
+    return new Response(JSON.stringify({ user }), { status: 200, headers });
+  }
+  /** Clears the session and redirects to `returnTo` (default "/"). Signs out of this product only. */
+  logout(req, options = {}) {
+    const url = new URL(req.url);
+    const publicUrl = this.config().publicUrl;
+    const secure = (publicUrl ? new URL(publicUrl) : url).protocol === "https:";
+    const returnTo = safeReturnTo(options.returnTo ?? url.searchParams.get("returnTo"));
+    return redirect(returnTo, [setCookie(SESSION_COOKIE, "", secure, 0)]);
+  }
+};
+
+// src/client.ts
+var DEFAULT_API_URL = "https://api.ambasada.dev";
+function processEnv() {
+  const p = globalThis.process;
+  return p?.env ?? {};
+}
+var Ambasada = class {
+  options;
+  keyLoader;
+  projectPromise;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  env(name) {
+    const v = this.options.env?.[name];
+    return typeof v === "string" ? v : processEnv()[name];
+  }
+  get apiUrl() {
+    return (this.options.apiUrl ?? this.env("AMBASADA_API_URL") ?? this.env("VILLAGE_API_URL") ?? DEFAULT_API_URL).replace(/\/+$/, "");
+  }
+  get apiKey() {
+    const key = this.options.apiKey ?? (this.env("AMBASADA_API_KEY") ?? this.env("VILLAGE_API_KEY"));
+    if (!key) throw new AmbasadaError("CONFIG", "no API key: set AMBASADA_API_KEY (a project key from developer.ambasada.dev, or `ambasada login`) or pass { apiKey }");
+    return key;
+  }
+  /**
+   * Sign in with Ambasada (docs/AUTH.md): `login(req)`, `callback(req)`, `user(req)`, `logout(req)`.
+   * Credentials come with the deploy to ambasada.dev, and from `ambasada dev` locally.
+   */
+  auth = new AmbasadaAuth(() => ({
+    clientId: this.options.auth?.clientId ?? this.env("AMBASADA_AUTH_CLIENT_ID"),
+    clientSecret: this.options.auth?.clientSecret ?? this.env("AMBASADA_AUTH_CLIENT_SECRET"),
+    issuer: this.options.auth?.issuer ?? this.env("AMBASADA_AUTH_ISSUER"),
+    publicUrl: this.options.auth?.publicUrl ?? this.env("PUBLIC_URL"),
+    apiUrl: this.apiUrl,
+    // Silent sign-in: a shell token must be for this app, by id or origin.
+    audiences: [this.appOrigin, this.options.app?.id ?? this.env("AMBASADA_APP_ID") ?? this.env("AMBASADA_COMPANY")].filter((a) => !!a),
+    hubUrl: this.hubUrl,
+    fetch: this.options.fetch
+  }));
+  get appOrigin() {
+    const url = this.options.app?.origin ?? this.env("AMBASADA_APP_ORIGIN") ?? this.options.auth?.publicUrl ?? this.env("PUBLIC_URL");
+    return url && URL.canParse(url) ? new URL(url).origin : void 0;
+  }
+  get hubUrl() {
+    return this.options.app?.hubUrl ?? this.env("AMBASADA_HUB_URL");
+  }
+  /**
+   * The mini-app platform (docs/MINI-APPS.md §7): `verifyWebhook(req)` for the hub's app events and
+   * `notify({ … })` to push to people who turned notifications on. Uses `AMBASADA_APP_SECRET`.
+   */
+  apps = new AmbasadaApps(() => ({
+    appSecret: this.options.app?.secret ?? this.env("AMBASADA_APP_SECRET"),
+    hubUrl: this.hubUrl,
+    origin: this.appOrigin,
+    fetch: this.options.fetch
+  }));
+  // ── HTTP ──────────────────────────────────────────────────────────────────
+  async send(method, path, opts = {}) {
+    const url = new URL(this.apiUrl + path);
+    for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+    const headers = { accept: "application/json" };
+    if (opts.auth !== false) headers.authorization = `Bearer ${this.apiKey}`;
+    let body = opts.raw;
+    if (opts.body !== void 0) {
+      body = JSON.stringify(opts.body);
+      headers["content-type"] = "application/json";
+    }
+    for (const [k, v] of Object.entries(opts.headers ?? {})) if (v !== void 0) headers[k.toLowerCase()] = v;
+    const doFetch = this.options.fetch ?? fetch;
+    const attempt = () => {
+      const timeout = AbortSignal.timeout(this.options.timeoutMs ?? 45e3);
+      const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+      return doFetch(url, { method, headers, body, signal });
+    };
+    let res;
+    try {
+      res = await attempt();
+    } catch (error) {
+      if (opts.signal?.aborted) throw error;
+      if (!opts.retry) throw new AmbasadaError("NETWORK", `${method} ${url.pathname}: ${error.message}`, 0);
+      try {
+        res = await attempt();
+      } catch (again) {
+        throw new AmbasadaError("NETWORK", `${method} ${url.pathname}: ${again.message}`, 0);
+      }
+    }
+    const text = await res.text();
+    let json = text;
+    if (text && (res.headers.get("content-type") ?? "").includes("json")) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+      }
+    }
+    if (!res.ok) throw errorFromResponse(res.status, json, `${method} ${url.pathname} \u2192 ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+    return { status: res.status, headers: res.headers, json };
+  }
+  async call(method, path, opts) {
+    return (await this.send(method, path, opts)).json;
+  }
+  // ── identity, keys ────────────────────────────────────────────────────────
+  /** Your app's id (from options, `AMBASADA_APP_ID`, or the project the API key belongs to). */
+  project() {
+    const known = this.options.project ?? this.env("AMBASADA_APP_ID") ?? this.env("AMBASADA_COMPANY");
+    if (known) return Promise.resolve(known);
+    this.projectPromise ??= this.call("GET", "/v1/key").then(
+      (k) => k.id,
+      (error) => {
+        this.projectPromise = void 0;
+        throw error;
+      }
+    );
+    return this.projectPromise;
+  }
+  /** The API's signing keys (`/.well-known/jwks.json`, cached). */
+  keys() {
+    const given = this.options.keys;
+    if (Array.isArray(given)) return Promise.resolve(given);
+    if (typeof given === "function") return given();
+    this.keyLoader ??= cachedKeys(() => this.call("GET", "/.well-known/jwks.json", { auth: false }).then((r) => r.keys));
+    return this.keyLoader();
+  }
+  // ── storage ───────────────────────────────────────────────────────────────
+  files = {
+    /**
+     * Stores bytes, a Blob, or a URL to copy (`POST /v1/files`). Returns a public URL. For an app's own
+     * uploads prefer its bucket, `env.FILES` (docs/STORAGE.md).
+     */
+    put: (data, options = {}) => {
+      const query = { ttl_seconds: options.ttlSeconds };
+      if (typeof data === "string") return this.call("POST", "/v1/files", { body: { url: data, content_type: options.contentType }, query });
+      const contentType = options.contentType ?? (data instanceof Blob && data.type ? data.type : "application/octet-stream");
+      return this.call("POST", "/v1/files", { raw: data, headers: { "content-type": contentType }, query });
+    }
+  };
+  /**
+   * Your project's JSON key-value store (`/v1/store`): 1 MB per project (keys + values), free. For more,
+   * use the app's own D1, KV and R2 (docs/STORAGE.md).
+   */
+  store = {
+    /** The value, or null when the key is not set. */
+    get: async (key) => {
+      try {
+        return (await this.call("GET", `/v1/store/${encodeURIComponent(key)}`)).value;
+      } catch (error) {
+        if (error instanceof AmbasadaError && error.status === 404) return null;
+        throw error;
+      }
+    },
+    /** Saves any JSON value (fails with INVALID_REQUEST when the store would pass 1 MB). */
+    set: (key, value) => {
+      if (value === void 0) throw new AmbasadaError("INVALID_REQUEST", "store.set needs a JSON value (use store.delete to remove a key)");
+      return this.call("PUT", `/v1/store/${encodeURIComponent(key)}`, { body: value });
+    },
+    /** `set` under its other name. */
+    put: (key, value) => this.store.set(key, value),
+    /** True when the key existed. */
+    delete: async (key) => (await this.call("DELETE", `/v1/store/${encodeURIComponent(key)}`)).deleted,
+    /** Keys (up to 1000, optionally under a prefix) and how much of the 1 MB is used. */
+    list: (prefix) => this.call("GET", "/v1/store", { query: { prefix } })
+  };
+};
+function cachedKeys(load, ttlMs = 10 * 6e4) {
+  let cached;
+  return () => {
+    if (!cached || Date.now() - cached.at > ttlMs) {
+      const keys3 = load();
+      const entry = { at: Date.now(), keys: keys3 };
+      cached = entry;
+      keys3.catch(() => {
+        if (cached === entry) cached = void 0;
+      });
+    }
+    return cached.keys;
+  };
+}
+function createAmbasada(options = {}) {
+  return new Ambasada(options);
+}
+
+// src/headers.ts
+function getHeader(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name);
+  const record = headers;
+  const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+  const value = key === void 0 ? void 0 : record[key];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+}
+
+// src/define.ts
+var MINIAPP_ENTRY = /^\/(?:[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)?$/;
+function defineApp(config) {
+  if (typeof config.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(config.id)) throw new Error(`app id "${String(config.id)}" must be a lowercase slug (a-z, 0-9, -)`);
+  const m = config.miniapp;
+  if (m !== void 0) {
+    if (!m || typeof m !== "object") throw new Error(`${config.id}: miniapp must be { entry: "/app" }`);
+    if (typeof m.entry !== "string" || !MINIAPP_ENTRY.test(m.entry) || m.entry.split("/").includes("..")) {
+      throw new Error(`${config.id}: miniapp.entry must be a path like "/app" or "/" (got ${JSON.stringify(m.entry)})`);
+    }
+    if (m.icon !== void 0 && (typeof m.icon !== "string" || !m.icon.startsWith("/"))) throw new Error(`${config.id}: miniapp.icon must be a path like "/icon.png"`);
+    if (m.accent !== void 0 && !/^#[0-9a-fA-F]{6}$/.test(m.accent)) throw new Error(`${config.id}: miniapp.accent must be a #RRGGBB colour`);
+  }
+  return config;
+}
+
+// src/platform.ts
+var ambasada = new Ambasada();
+var platform_default = ambasada;
+export {
+  APP_SIGNATURE_HEADER2 as APP_SIGNATURE_HEADER,
+  APP_TIMESTAMP_HEADER2 as APP_TIMESTAMP_HEADER,
+  AUTH_PATHS,
+  Ambasada,
+  AmbasadaApps,
+  AmbasadaAuth,
+  AmbasadaError,
+  DEFAULT_API_URL,
+  ERROR_STATUS,
+  JWKS_TTL_MS,
+  MINIAPP_ENTRY,
+  SESSION_TTL_S,
+  WebhookInvalidError,
+  ambasada,
+  appWebhookHeaders2 as appWebhookHeaders,
+  createAmbasada,
+  platform_default as default,
+  defineApp,
+  errorFromResponse,
+  getHeader,
+  isAmbasadaError,
+  signAppWebhook2 as signAppWebhook
+};