@ambasada/sdk 0.4.1 → 0.6.0

package/dist/apps.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Notifications for every mini app (docs/MINI-APPS.md §7). The hub tells your app who turned notifications
+ * on through a signed webhook; you keep `token ↔ your user` and send with that token:
+ *
+ *   POST /api/ambasada/webhook → const event = await ambasada.apps.verifyWebhook(req)   // AppEvent
+ *                                if (event.event === "notifications_enabled") save(event.user, event.token)
+ *   anywhere                   → await ambasada.apps.notify({ notification_id, title, body, url, tokens: [token] })
+ *
+ * The app secret signs both directions: `AMBASADA_APP_SECRET` (the deploy injects it on ambasada.dev; the hub
+ * dashboard shows it for apps hosted elsewhere; `ambasada dev` sets a fake one and plays the hub).
+ * WebCrypto only; the wire format is in @ambasada/protocol (packages/protocol/src/apps.ts).
+ */
+import type { HeaderSource } from "./webhook.js";
+export declare const APP_SIGNATURE_HEADER = "x-ambasada-signature";
+export declare const APP_TIMESTAMP_HEADER = "x-ambasada-timestamp";
+export type AppEventType = "notifications_enabled" | "notifications_disabled" | "app_added" | "app_removed" | "ping";
+/** What the hub POSTs to your webhook. `token` comes with notifications_enabled (and app_added when notifications are on). */
+export type AppEvent = {
+    event: "notifications_enabled";
+    app: string;
+    token: string;
+    user: string;
+    at: string;
+} | {
+    event: "notifications_disabled";
+    app: string;
+    user: string;
+    token?: string;
+    at: string;
+} | {
+    event: "app_added";
+    app: string;
+    user: string;
+    token?: string;
+    at: string;
+} | {
+    event: "app_removed";
+    app: string;
+    user: string;
+    token?: string;
+    at: string;
+} | {
+    event: "ping";
+    app: string;
+    at: string;
+};
+export type NotificationCategory = "transactional" | "social" | "marketing";
+export interface AppNotifyInput {
+    /** ≤ 128; (person, id) is deduped by the hub for 24 h. */
+    notification_id: string;
+    /** ≤ 40: the whole headline. */
+    title: string;
+    /** ≤ 140. */
+    body: string;
+    /** A path on your app (`/orders/184`) or a URL on its origin. */
+    url: string;
+    /** Notification tokens from `notifications_enabled`, ≤ 100 per call. */
+    tokens?: string[];
+    /** Ambasada user ids, for Verified apps with the identity scope. */
+    users?: string[];
+    /** Default "transactional", the only one Listed apps may send. */
+    category?: NotificationCategory;
+    /** Replaces an earlier unread push with the same key. */
+    collapse_key?: string;
+    ttl_seconds?: number;
+}
+export interface AppNotifyResult {
+    sent: string[];
+    /** Gone (the person turned notifications off or removed the app): forget them. */
+    invalid: string[];
+    rate_limited: string[];
+}
+/** The `x-ambasada-signature` value for a delivery (`v1=<hex>`): for tests and your own fake hub. */
+export declare const signAppWebhook: (secret: string, timestamp: number, body: string) => Promise<string>;
+/** Timestamp + signature headers for `body`, as the hub sends them. */
+export declare const appWebhookHeaders: (secret: string, body: string, timestamp?: number) => Promise<Record<string, string>>;
+export interface AppsConfig {
+    /** `AMBASADA_APP_SECRET`. */
+    appSecret?: string;
+    /** `AMBASADA_HUB_URL`, else https://hub.ambasada.id. */
+    hubUrl?: string;
+    /** Your app's origin, for the same-origin `url` rule: `AMBASADA_APP_ORIGIN`, else `PUBLIC_URL`. */
+    origin?: string;
+    fetch?: typeof fetch;
+}
+/** A fetch `Request`, or the raw body and headers exactly as received. */
+export type WebhookInput = Request | {
+    body: string | Uint8Array;
+    headers: HeaderSource;
+};
+export declare class AmbasadaApps {
+    private readonly config;
+    constructor(config: () => AppsConfig);
+    /** True when the app has its secret (hosted on ambasada.dev, `ambasada dev`, or set by hand). */
+    get configured(): boolean;
+    /**
+     * 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.
+     */
+    verifyWebhook(input: WebhookInput, secret?: string, options?: {
+        toleranceSeconds?: number;
+        now?: number;
+    }): Promise<AppEvent>;
+    /**
+     * 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 `VillageError("INVALID_REQUEST")` before sending anything. Tokens in `invalid` are gone: forget them.
+     */
+    notify(input: AppNotifyInput): Promise<AppNotifyResult>;
+}

package/dist/auth.d.ts

@@ -12,6 +12,12 @@
  * The session is an HttpOnly cookie holding the signed public profile (HMAC-SHA256 under a key
  * derived from the client secret), host-only (`__Host-` on https), so no other *.ambasada.dev product
  * can read, set or forge it. No access token is kept.
+ *
+ * Silent sign-in inside the Ambasada app (docs/MINI-APPS.md §5): the page asks the shell for a short-lived
+ * token (`auth.getToken()` from @ambasada/miniapp) and POSTs it here; the same session cookie comes back:
+ *
+ *   POST /api/auth/shell { token } → return village.auth.shell(req)                      // { user } + cookie
+ *   anywhere                       → const who = await village.auth.verifyShellToken(token) // { user_id, name, avatar }
  */
 /** The person signed in, as `GET /v1/auth/profile` returns them. */
 export interface AmbasadaUser {
@@ -32,6 +38,10 @@ export interface AuthConfig {
     clientId?: string;
     clientSecret?: string;
     issuer?: string;
+    /** Who a shell token must be for (`aud`): your app id and origin. The request's origin is added in `shell()`. */
+    audiences?: string[];
+    /** The hub, for the full profile behind a shell token (`/api/apps/profile`). */
+    hubUrl?: string;
     /** Where `/v1/auth/profile` lives (the village API). */
     apiUrl: string;
     /** Your public origin if the Worker sees another host (behind a proxy). Default: the request's origin. */
@@ -48,6 +58,7 @@ export declare const AUTH_PATHS: {
     readonly login: "/api/auth/login";
     readonly callback: "/api/auth/callback";
     readonly logout: "/api/auth/logout";
+    readonly shell: "/api/auth/shell";
 };
 /** How long a sign-in lasts (the cookie holds a profile snapshot; signing in again refreshes it). */
 export declare const SESSION_TTL_S: number;
@@ -72,6 +83,16 @@ export declare function readCookie(req: WithHeaders, name: string): string | nul
  * any control character (browsers drop tabs and newlines, so "/\t/evil" would become "//evil").
  */
 export declare function safeReturnTo(value: string | null | undefined): string;
+/** Who a verified shell token is for. Name and avatar are what Ambasada ID had when the shell minted it. */
+export interface ShellUser {
+    user_id: string;
+    name: string | null;
+    avatar: string | null;
+}
+/** JWKS cache per issuer: 1 hour, refreshed once early when a token names a key we don't have. */
+export declare const JWKS_TTL_MS = 3600000;
+/** For tests. */
+export declare function clearJwksCache(): void;
 export declare class AmbasadaAuth {
     private readonly config;
     constructor(config: () => AuthConfig);
@@ -88,6 +109,22 @@ export declare class AmbasadaAuth {
     callback(req: Request): Promise<Response>;
     /** Whoever is signed in on this request, or null (also null when sign-in is not set up). */
     user(req: WithHeaders): Promise<AmbasadaUser | 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 `VillageError("UNAUTHORIZED")`.
+     */
+    verifyShellToken(token: string, options?: {
+        audience?: string | string[];
+        now?: number;
+    }): Promise<ShellUser>;
+    /**
+     * 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 }`.
+     */
+    shell(req: Request): Promise<Response>;
     /** Clears the session and redirects to `returnTo` (default "/"). Signs out of this product only. */
     logout(req: Request, options?: {
         returnTo?: string;

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { AmbasadaApps } from "./apps.js";
 import { AmbasadaAuth } from "./auth.js";
 import { type IncomingRequest } from "./receipt.js";
 import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, FileOptions, StoredFile, StoreList, StoreWrite, ImageRequest, ImageResult, Jwk, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
@@ -27,6 +28,13 @@ export interface VillageOptions {
         issuer?: string;
         publicUrl?: string;
     };
+    /** Mini-app platform (notifications). Default: `AMBASADA_APP_SECRET`, `AMBASADA_HUB_URL`, `AMBASADA_APP_ORIGIN` (else `PUBLIC_URL`). */
+    app?: {
+        secret?: string;
+        hubUrl?: string;
+        origin?: string;
+        id?: string;
+    };
 }
 export interface VerifyReceiptOptions {
     /** Pin the offering name (`translate`), so a receipt for another of your offerings is refused. */
@@ -53,6 +61,13 @@ export declare class Village {
      * Credentials come with the deploy to ambasada.dev, and from `ambasada dev` locally.
      */
     readonly auth: AmbasadaAuth;
+    private get appOrigin();
+    private get hubUrl();
+    /**
+     * 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`.
+     */
+    readonly apps: AmbasadaApps;
     private send;
     private call;
     /** Your company id (from options, `AMBASADA_COMPANY`, or the wallet the API key belongs to). */

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  *   const { url } = await village.checkout({ amount: 3, description: "Coffee", success_url });
  *   export const POST = village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }));
  *   const user = await village.auth.user(req);            // Sign in with Ambasada (docs/AUTH.md)
+ *   await village.apps.notify({ notification_id, title, body, url, tokens });   // mini-app pushes (docs/MINI-APPS.md §7)
  *
  * Works in Node ≥ 22, Bun, Cloudflare Workers (`createAmbasada({ env })`) and Next.js route handlers.
  */
@@ -17,8 +18,10 @@ export { verifyWebhookPayload, webhookHeaders, generateWebhookSecret, WEBHOOK_HE
 export { RECEIPT_HEADER, readIncoming, verifyCallReceipt, verifyCheckoutReceiptToken } from "./receipt.js";
 export type { IncomingRequest } from "./receipt.js";
 export { defineCompany, offering } from "./define.js";
-export { AmbasadaAuth, AUTH_PATHS, SESSION_TTL_S } from "./auth.js";
-export type { AmbasadaUser, AuthConfig, LoginOptions, WithHeaders } from "./auth.js";
+export { AmbasadaAuth, AUTH_PATHS, JWKS_TTL_MS, SESSION_TTL_S } from "./auth.js";
+export type { AmbasadaUser, AuthConfig, LoginOptions, ShellUser, WithHeaders } from "./auth.js";
+export { AmbasadaApps, APP_SIGNATURE_HEADER, APP_TIMESTAMP_HEADER, appWebhookHeaders, signAppWebhook } from "./apps.js";
+export type { AppEvent, AppEventType, AppNotifyInput, AppNotifyResult, AppsConfig, NotificationCategory, WebhookInput } from "./apps.js";
 export type { CompanyConfig, OfferingDef } from "./define.js";
 /** The default client, configured from the environment at call time. */
 export declare const village: Village;

package/dist/index.js

@@ -1,3 +1,315 @@
+// ../protocol/src/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8(text) {
+  return encoder.encode(text);
+}
+function fromUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function fromBase64url(text) {
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function toBytes(data) {
+  if (typeof data === "string") return utf8(data);
+  if (data instanceof Uint8Array) return new Uint8Array(data);
+  return new Uint8Array(data);
+}
+async function sha256Hex(data) {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", toBytes(data)));
+  let hex2 = "";
+  for (const byte of digest) hex2 += byte.toString(16).padStart(2, "0");
+  return hex2;
+}
+
+// ../protocol/src/receipt.ts
+var RECEIPT_HEADER = "x-village-receipt";
+var DEFAULT_ISSUER = "village";
+var ReceiptError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "ReceiptError";
+  }
+  reason;
+};
+var ED25519 = { name: "Ed25519" };
+async function verifyReceipt(token, options) {
+  const claims = await verifySigned(token, options);
+  if (claims.kind !== void 0 || typeof claims.call_id !== "string" || typeof claims.body_sha256 !== "string") {
+    throw new ReceiptError("wrong_kind", "not a call receipt");
+  }
+  if (options.seller !== void 0 && claims.seller !== options.seller) {
+    throw new ReceiptError("wrong_seller", `receipt is for seller ${claims.seller}`);
+  }
+  if (options.offering !== void 0 && claims.offering !== options.offering) {
+    throw new ReceiptError("wrong_offering", `receipt is for offering ${claims.offering}`);
+  }
+  if (options.body !== void 0 && await sha256Hex(options.body) !== claims.body_sha256) {
+    throw new ReceiptError("body_mismatch", "request body does not match the receipt");
+  }
+  return claims;
+}
+async function verifyCheckoutReceipt(token, options) {
+  const claims = await verifySigned(token, options);
+  if (claims.kind !== "checkout" || typeof claims.session !== "string") throw new ReceiptError("wrong_kind", "not a checkout receipt");
+  if (options.seller !== void 0 && claims.seller !== options.seller) {
+    throw new ReceiptError("wrong_seller", `receipt is for seller ${claims.seller}`);
+  }
+  if (options.session !== void 0 && claims.session !== options.session) {
+    throw new ReceiptError("wrong_session", `receipt is for checkout ${claims.session}`);
+  }
+  return claims;
+}
+async function verifySigned(token, options) {
+  if (!token) throw new ReceiptError("missing", `missing ${RECEIPT_HEADER}`);
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new ReceiptError("malformed", "receipt is not a JWT");
+  const [headerPart, payloadPart, signaturePart] = parts;
+  let header3;
+  let claims;
+  try {
+    header3 = JSON.parse(fromUtf8(fromBase64url(headerPart)));
+    claims = JSON.parse(fromUtf8(fromBase64url(payloadPart)));
+  } catch {
+    throw new ReceiptError("malformed", "receipt is not valid base64url JSON");
+  }
+  if (header3.alg !== "EdDSA") throw new ReceiptError("malformed", `unsupported alg ${header3.alg}`);
+  if (typeof claims !== "object" || claims === null) throw new ReceiptError("malformed", "receipt claims are not an object");
+  const keys3 = typeof options.keys === "function" ? await options.keys() : options.keys;
+  const jwk = keys3.find((k) => (k.kid ?? k.x.slice(0, 16)) === header3.kid) ?? (keys3.length === 1 && !header3.kid ? keys3[0] : void 0);
+  if (!jwk) throw new ReceiptError("unknown_key", `no village key with kid ${header3.kid}`);
+  const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, ED25519, false, ["verify"]);
+  const ok = await crypto.subtle.verify(ED25519, key, fromBase64url(signaturePart), utf8(`${headerPart}.${payloadPart}`));
+  if (!ok) throw new ReceiptError("bad_signature", "receipt signature is invalid");
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  const skew = options.clockSkewSeconds ?? 30;
+  if (typeof claims.exp !== "number" || claims.exp + skew < now) throw new ReceiptError("expired", "receipt expired");
+  if (typeof claims.iat === "number" && claims.iat - skew > now) throw new ReceiptError("not_yet_valid", "receipt issued in the future");
+  if (claims.iss !== (options.issuer ?? DEFAULT_ISSUER)) throw new ReceiptError("wrong_issuer", `unexpected issuer ${String(claims.iss)}`);
+  return claims;
+}
+
+// ../protocol/src/webhook.ts
+var WEBHOOK_HEADERS = {
+  id: "webhook-id",
+  timestamp: "webhook-timestamp",
+  signature: "webhook-signature"
+};
+var SECRET_PREFIX = "whsec_";
+var encoder2 = new TextEncoder();
+var WebhookError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "WebhookError";
+  }
+  reason;
+};
+function generateWebhookSecret() {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  return SECRET_PREFIX + toStdBase64(bytes);
+}
+async function hmacKey(secret) {
+  const raw = secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret;
+  let bytes;
+  try {
+    bytes = fromStdBase64(raw);
+  } catch {
+    throw new WebhookError("bad_secret", "webhook secret is not whsec_<base64>");
+  }
+  return crypto.subtle.importKey("raw", bytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+}
+async function signWebhook(secret, id, timestamp, body) {
+  const mac2 = await crypto.subtle.sign("HMAC", await hmacKey(secret), encoder2.encode(`${id}.${timestamp}.${body}`));
+  return `v1,${toStdBase64(new Uint8Array(mac2))}`;
+}
+async function webhookHeaders(secret, id, timestamp, body) {
+  return {
+    [WEBHOOK_HEADERS.id]: id,
+    [WEBHOOK_HEADERS.timestamp]: String(timestamp),
+    [WEBHOOK_HEADERS.signature]: await signWebhook(secret, id, timestamp, body)
+  };
+}
+function header(headers, name) {
+  if (headers instanceof Headers) return headers.get(name);
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+}
+async function verifyWebhook(secret, headers, body, { toleranceSeconds = 300, now = Math.floor(Date.now() / 1e3) } = {}) {
+  const id = header(headers, WEBHOOK_HEADERS.id);
+  const ts = header(headers, WEBHOOK_HEADERS.timestamp);
+  const signatures = header(headers, WEBHOOK_HEADERS.signature);
+  if (!id || !ts || !signatures) throw new WebhookError("missing_headers", "missing webhook-id, webhook-timestamp or webhook-signature");
+  const timestamp = Number(ts);
+  if (!/^\d+$/.test(ts) || !Number.isSafeInteger(timestamp)) throw new WebhookError("bad_timestamp", "webhook-timestamp is not unix seconds");
+  if (timestamp < now - toleranceSeconds) throw new WebhookError("too_old", "webhook timestamp is too old");
+  if (timestamp > now + toleranceSeconds) throw new WebhookError("too_new", "webhook timestamp is in the future");
+  const text = typeof body === "string" ? body : fromUtf8(body);
+  const expected = (await signWebhook(secret, id, timestamp, text)).slice(3);
+  const match = signatures.split(" ").filter((s) => s.startsWith("v1,")).some((s) => constantTimeEqual(s.slice(3), expected));
+  if (!match) throw new WebhookError("bad_signature", "no matching webhook signature");
+  return JSON.parse(text);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function toStdBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function fromStdBase64(text) {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+// ../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 encoder3 = new TextEncoder();
+var keys = /* @__PURE__ */ new Map();
+function hmacKey2(secret) {
+  let key = keys.get(secret);
+  if (!key) {
+    key = crypto.subtle.importKey("raw", encoder3.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 hmacKey2(secret), encoder3.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 header2(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 = header2(headers, APP_TIMESTAMP_HEADER);
+  const sig = header2(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) };
+}
+
 // ../sdk/src/errors.ts
 var ERROR_STATUS = {
   // EXCHANGE.md §5 vocabulary
@@ -102,8 +414,78 @@ function errorFromResponse(status, body, fallback) {
   return new VillageError(code, fallback, status);
 }
 
+// ../sdk/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 `VillageError("INVALID_REQUEST")` before sending anything. Tokens in `invalid` are gone: forget them.
+   */
+  async notify(input) {
+    const c = this.config();
+    if (!c.appSecret) throw new VillageError("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 VillageError("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 VillageError("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 VillageError(code, `notify: ${message}`, res.status);
+    }
+    return appNotifyResult(json);
+  }
+};
+
 // ../sdk/src/auth.ts
-var AUTH_PATHS = { login: "/api/auth/login", callback: "/api/auth/callback", logout: "/api/auth/logout" };
+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";
@@ -128,11 +510,11 @@ async function pkce() {
 async function pkceChallenge(verifier) {
   return b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(verifier))));
 }
-var keys = /* @__PURE__ */ new Map();
+var keys2 = /* @__PURE__ */ new Map();
 function cookieKey(secret, purpose) {
   const id = `${purpose}
 ${secret}`;
-  let key = keys.get(id);
+  let key = keys2.get(id);
   if (!key) {
     key = crypto.subtle.importKey("raw", enc.encode(secret), "HKDF", false, ["deriveKey"]).then(
       (ikm) => crypto.subtle.deriveKey(
@@ -143,7 +525,7 @@ ${secret}`;
         ["sign", "verify"]
       )
     );
-    keys.set(id, key);
+    keys2.set(id, key);
   }
   return key;
 }
@@ -186,6 +568,21 @@ function redirect(location, cookies = []) {
   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 VillageError("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 VillageError("UNAUTHORIZED", `shell token refused: ${message}`, 401);
 var AmbasadaAuth = class {
   constructor(config) {
     this.config = config;
@@ -274,6 +671,86 @@ var AmbasadaAuth = class {
     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 `VillageError("UNAUTHORIZED")`.
+   */
+  async verifyShellToken(token, options = {}) {
+    const c = this.config();
+    if (!c.issuer) throw new VillageError("CONFIG", "silent sign-in needs AMBASADA_AUTH_ISSUER (injected on ambasada.dev and by `ambasada dev`)");
+    const issuer = c.issuer.replace(/\/+$/, "");
+    const audiences = [options.audience ?? c.audiences ?? []].flat().filter(Boolean).map((a) => a.replace(/\/+$/, ""));
+    if (!audiences.length) throw new VillageError("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 header3;
+    let claims;
+    try {
+      header3 = JSON.parse(new TextDecoder().decode(fromB64url(parts[0])));
+      claims = JSON.parse(new TextDecoder().decode(fromB64url(parts[1])));
+    } catch {
+      throw shellRefused("not a JWT");
+    }
+    if (header3.alg !== "RS256") throw shellRefused(`alg ${String(header3.alg)} (only RS256)`);
+    let keys3 = await jwks(issuer, doFetch);
+    let jwk = keys3.find((k) => k.kid === header3.kid) ?? (!header3.kid && keys3.length === 1 ? keys3[0] : void 0);
+    if (!jwk) {
+      keys3 = await jwks(issuer, doFetch, true);
+      jwk = keys3.find((k) => k.kid === header3.kid);
+    }
+    if (!jwk) throw shellRefused(`unknown key ${String(header3.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");
+    if (typeof claims.iss === "string" && claims.iss.replace(/\/+$/, "") !== issuer) throw shellRefused(`issuer ${claims.iss}`);
+    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 VillageError("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 VillageError("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 VillageError("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);
@@ -284,182 +761,6 @@ var AmbasadaAuth = class {
   }
 };
 
-// ../protocol/src/encoding.ts
-var encoder = new TextEncoder();
-var decoder = new TextDecoder();
-function utf8(text) {
-  return encoder.encode(text);
-}
-function fromUtf8(bytes) {
-  return decoder.decode(bytes);
-}
-function fromBase64url(text) {
-  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
-  const binary = atob(padded);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-function toBytes(data) {
-  if (typeof data === "string") return utf8(data);
-  if (data instanceof Uint8Array) return new Uint8Array(data);
-  return new Uint8Array(data);
-}
-async function sha256Hex(data) {
-  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", toBytes(data)));
-  let hex = "";
-  for (const byte of digest) hex += byte.toString(16).padStart(2, "0");
-  return hex;
-}
-
-// ../protocol/src/receipt.ts
-var RECEIPT_HEADER = "x-village-receipt";
-var DEFAULT_ISSUER = "village";
-var ReceiptError = class extends Error {
-  constructor(reason, message) {
-    super(message);
-    this.reason = reason;
-    this.name = "ReceiptError";
-  }
-  reason;
-};
-var ED25519 = { name: "Ed25519" };
-async function verifyReceipt(token, options) {
-  const claims = await verifySigned(token, options);
-  if (claims.kind !== void 0 || typeof claims.call_id !== "string" || typeof claims.body_sha256 !== "string") {
-    throw new ReceiptError("wrong_kind", "not a call receipt");
-  }
-  if (options.seller !== void 0 && claims.seller !== options.seller) {
-    throw new ReceiptError("wrong_seller", `receipt is for seller ${claims.seller}`);
-  }
-  if (options.offering !== void 0 && claims.offering !== options.offering) {
-    throw new ReceiptError("wrong_offering", `receipt is for offering ${claims.offering}`);
-  }
-  if (options.body !== void 0 && await sha256Hex(options.body) !== claims.body_sha256) {
-    throw new ReceiptError("body_mismatch", "request body does not match the receipt");
-  }
-  return claims;
-}
-async function verifyCheckoutReceipt(token, options) {
-  const claims = await verifySigned(token, options);
-  if (claims.kind !== "checkout" || typeof claims.session !== "string") throw new ReceiptError("wrong_kind", "not a checkout receipt");
-  if (options.seller !== void 0 && claims.seller !== options.seller) {
-    throw new ReceiptError("wrong_seller", `receipt is for seller ${claims.seller}`);
-  }
-  if (options.session !== void 0 && claims.session !== options.session) {
-    throw new ReceiptError("wrong_session", `receipt is for checkout ${claims.session}`);
-  }
-  return claims;
-}
-async function verifySigned(token, options) {
-  if (!token) throw new ReceiptError("missing", `missing ${RECEIPT_HEADER}`);
-  const parts = token.split(".");
-  if (parts.length !== 3) throw new ReceiptError("malformed", "receipt is not a JWT");
-  const [headerPart, payloadPart, signaturePart] = parts;
-  let header2;
-  let claims;
-  try {
-    header2 = JSON.parse(fromUtf8(fromBase64url(headerPart)));
-    claims = JSON.parse(fromUtf8(fromBase64url(payloadPart)));
-  } catch {
-    throw new ReceiptError("malformed", "receipt is not valid base64url JSON");
-  }
-  if (header2.alg !== "EdDSA") throw new ReceiptError("malformed", `unsupported alg ${header2.alg}`);
-  if (typeof claims !== "object" || claims === null) throw new ReceiptError("malformed", "receipt claims are not an object");
-  const keys2 = typeof options.keys === "function" ? await options.keys() : options.keys;
-  const jwk = keys2.find((k) => (k.kid ?? k.x.slice(0, 16)) === header2.kid) ?? (keys2.length === 1 && !header2.kid ? keys2[0] : void 0);
-  if (!jwk) throw new ReceiptError("unknown_key", `no village key with kid ${header2.kid}`);
-  const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, ED25519, false, ["verify"]);
-  const ok = await crypto.subtle.verify(ED25519, key, fromBase64url(signaturePart), utf8(`${headerPart}.${payloadPart}`));
-  if (!ok) throw new ReceiptError("bad_signature", "receipt signature is invalid");
-  const now = options.now ?? Math.floor(Date.now() / 1e3);
-  const skew = options.clockSkewSeconds ?? 30;
-  if (typeof claims.exp !== "number" || claims.exp + skew < now) throw new ReceiptError("expired", "receipt expired");
-  if (typeof claims.iat === "number" && claims.iat - skew > now) throw new ReceiptError("not_yet_valid", "receipt issued in the future");
-  if (claims.iss !== (options.issuer ?? DEFAULT_ISSUER)) throw new ReceiptError("wrong_issuer", `unexpected issuer ${String(claims.iss)}`);
-  return claims;
-}
-
-// ../protocol/src/webhook.ts
-var WEBHOOK_HEADERS = {
-  id: "webhook-id",
-  timestamp: "webhook-timestamp",
-  signature: "webhook-signature"
-};
-var SECRET_PREFIX = "whsec_";
-var encoder2 = new TextEncoder();
-var WebhookError = class extends Error {
-  constructor(reason, message) {
-    super(message);
-    this.reason = reason;
-    this.name = "WebhookError";
-  }
-  reason;
-};
-function generateWebhookSecret() {
-  const bytes = new Uint8Array(24);
-  crypto.getRandomValues(bytes);
-  return SECRET_PREFIX + toStdBase64(bytes);
-}
-async function hmacKey(secret) {
-  const raw = secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret;
-  let bytes;
-  try {
-    bytes = fromStdBase64(raw);
-  } catch {
-    throw new WebhookError("bad_secret", "webhook secret is not whsec_<base64>");
-  }
-  return crypto.subtle.importKey("raw", bytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-}
-async function signWebhook(secret, id, timestamp, body) {
-  const mac = await crypto.subtle.sign("HMAC", await hmacKey(secret), encoder2.encode(`${id}.${timestamp}.${body}`));
-  return `v1,${toStdBase64(new Uint8Array(mac))}`;
-}
-async function webhookHeaders(secret, id, timestamp, body) {
-  return {
-    [WEBHOOK_HEADERS.id]: id,
-    [WEBHOOK_HEADERS.timestamp]: String(timestamp),
-    [WEBHOOK_HEADERS.signature]: await signWebhook(secret, id, timestamp, body)
-  };
-}
-function header(headers, name) {
-  if (headers instanceof Headers) return headers.get(name);
-  const value = headers[name] ?? headers[name.toLowerCase()];
-  return Array.isArray(value) ? value[0] ?? null : value ?? null;
-}
-async function verifyWebhook(secret, headers, body, { toleranceSeconds = 300, now = Math.floor(Date.now() / 1e3) } = {}) {
-  const id = header(headers, WEBHOOK_HEADERS.id);
-  const ts = header(headers, WEBHOOK_HEADERS.timestamp);
-  const signatures = header(headers, WEBHOOK_HEADERS.signature);
-  if (!id || !ts || !signatures) throw new WebhookError("missing_headers", "missing webhook-id, webhook-timestamp or webhook-signature");
-  const timestamp = Number(ts);
-  if (!/^\d+$/.test(ts) || !Number.isSafeInteger(timestamp)) throw new WebhookError("bad_timestamp", "webhook-timestamp is not unix seconds");
-  if (timestamp < now - toleranceSeconds) throw new WebhookError("too_old", "webhook timestamp is too old");
-  if (timestamp > now + toleranceSeconds) throw new WebhookError("too_new", "webhook timestamp is in the future");
-  const text = typeof body === "string" ? body : fromUtf8(body);
-  const expected = (await signWebhook(secret, id, timestamp, text)).slice(3);
-  const match = signatures.split(" ").filter((s) => s.startsWith("v1,")).some((s) => constantTimeEqual(s.slice(3), expected));
-  if (!match) throw new WebhookError("bad_signature", "no matching webhook signature");
-  return JSON.parse(text);
-}
-function constantTimeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
-function toStdBase64(bytes) {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary);
-}
-function fromStdBase64(text) {
-  const binary = atob(text);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-
 // ../sdk/src/webhook.ts
 function getHeader(headers, name) {
   if (typeof headers.get === "function") return headers.get(name);
@@ -626,6 +927,26 @@ var Village = class {
     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 ──────────────────────────────────────────────────────────────────
@@ -960,10 +1281,10 @@ function cachedKeys(load, ttlMs = 10 * 6e4) {
   let cached;
   return () => {
     if (!cached || Date.now() - cached.at > ttlMs) {
-      const keys2 = load();
-      const entry = { at: Date.now(), keys: keys2 };
+      const keys3 = load();
+      const entry = { at: Date.now(), keys: keys3 };
       cached = entry;
-      keys2.catch(() => {
+      keys3.catch(() => {
         if (cached === entry) cached = void 0;
       });
     }
@@ -988,11 +1309,15 @@ function offering(def) {
 var village = new Village();
 var index_default = village;
 export {
+  APP_SIGNATURE_HEADER2 as APP_SIGNATURE_HEADER,
+  APP_TIMESTAMP_HEADER2 as APP_TIMESTAMP_HEADER,
   AUTH_PATHS,
+  AmbasadaApps,
   AmbasadaAuth,
   DEFAULT_API_URL,
   DEFAULT_MODEL,
   ERROR_STATUS,
+  JWKS_TTL_MS,
   RECEIPT_HEADER2 as RECEIPT_HEADER,
   ReceiptInvalidError,
   SESSION_TTL_S,
@@ -1000,6 +1325,7 @@ export {
   VillageError,
   WEBHOOK_HEADERS,
   WebhookInvalidError,
+  appWebhookHeaders2 as appWebhookHeaders,
   createAmbasada,
   index_default as default,
   defineCompany,
@@ -1008,6 +1334,7 @@ export {
   isVillageError,
   offering,
   readIncoming,
+  signAppWebhook2 as signAppWebhook,
   verifyCallReceipt,
   verifyCheckoutReceiptToken,
   verifyWebhookPayload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/sdk",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "TypeScript SDK for the Hack A Ton village: Checkout, webhooks, receipts, Pay, needs, LLM, images, tools, files, listings, wallet.",
   "type": "module",
   "license": "MIT",