@usequeek/app-sdk 0.7.2 → 0.8.1

package/dist/proxy.d.ts

@@ -30,12 +30,19 @@ export declare const PROXY_NONCE_PARAM = "jti";
 export declare const PROXY_SHOP_PARAM = "shop";
 export declare const PROXY_CUSTOMER_PARAM = "logged_in_customer_id";
 export declare const PROXY_KID_PARAM = "kid";
+export declare const PROXY_SURFACE_PARAM = "surface";
+/**
+ * The Queek surface that made a call. Queek signs it on every proxy call and
+ * is the only one that sets it: a shopper cannot choose it. `storefront` is a
+ * shopper, `dashboard` the merchant dashboard, `ai` Queek AI reading a tool.
+ */
+export type ProxySurface = "storefront" | "dashboard" | "ai";
 /** Default allowed clock skew in seconds; the floor (60s) below applies regardless. */
 export declare const PROXY_MAX_SKEW_SECONDS = 300;
 /** Query params as any framework holds them (duplicates collapse to the first value). */
 export type ProxyQuery = Record<string, string | string[] | null | undefined>;
 /** Failure reason when proxy verification rejects a query. */
-export type ProxyFailure = "missing_params" | "stale_timestamp" | "missing_secret" | "signature_mismatch" | "unknown_installation" | "replayed";
+export type ProxyFailure = "missing_params" | "stale_timestamp" | "missing_secret" | "signature_mismatch" | "unknown_installation" | "surface_mismatch" | "replayed";
 /**
  * The canonical string the MAC covers, exactly as Queek builds it (sig
  * excluded, keys byte-sorted, percent-encoded pairs).
@@ -48,6 +55,13 @@ export declare function buildProxyCanonicalString(path: string, params: Record<s
  */
 export declare function signProxyQuery(path: string, params: Record<string, string>, secret: string): string;
 export interface ProxyVerifyOptions {
+    /**
+     * Require this signed `surface`. A call signed for another surface (or for
+     * none) fails with `surface_mismatch`, after its signature verified. Set it
+     * on a handler that serves merchant data (`dashboard`) so a shopper's call
+     * cannot reach it.
+     */
+    expectedSurface?: ProxySurface;
     /** Unix seconds to judge freshness against (defaults to now). Exposed for tests. */
     nowSeconds?: number;
     /** Allowed clock skew in seconds (defaults to PROXY_MAX_SKEW_SECONDS; floored at 60). */
@@ -61,6 +75,7 @@ export interface ProxyVerifyOptions {
  */
 export declare function verifyProxyQueryDetailed(path: string, query: ProxyQuery, secrets: string[], options?: ProxyVerifyOptions): {
     ok: true;
+    surface: string;
 } | {
     ok: false;
     reason: ProxyFailure;
@@ -79,10 +94,11 @@ export type ProxyVerification = {
     ok: true;
     installation: InstallationRecord;
     params: Record<string, string>;
+    surface: string;
 } | {
     ok: false;
     reason: ProxyFailure;
-    status: 401;
+    status: 401 | 403;
 };
 /**
  * Layer 1: verify one signed proxy query from plain data — no `Request`, no
@@ -109,6 +125,7 @@ export interface ProxyRequestOptions extends ProxyStoreOptions {
 export type ProxyResponder = (verified: {
     installation: InstallationRecord;
     params: Record<string, string>;
+    surface: string;
 }) => Response | Promise<Response>;
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads the query
@@ -117,3 +134,46 @@ export type ProxyResponder = (verified: {
  * anything else answers 405.
  */
 export declare function handleProxyRequest(request: Request, options: ProxyRequestOptions, onVerified: ProxyResponder): Promise<Response>;
+/** A verified call to a declared AI read tool: Queek's signed params, the tool key and the actor's ROLE (never a user id). */
+export interface AiToolCall {
+    /** The installation p_id the call is for (the signed `kid`). */
+    kid: string;
+    shop: string;
+    /** Everything Queek signed: the tool's inputs as strings, `kid`, `shop`, `ts`, `actor_role` and the rest. */
+    params: Record<string, string>;
+    tool: string;
+    actorRole: string;
+}
+/**
+ * What a tool answers: an OBJECT matching its manifest `ai.tools[].output`, never a bare array. A list tool
+ * (`output.list: true`) answers `{ rows: [{ ...declared fields }] }`; any other tool answers the declared fields
+ * object. Queek drops every undeclared field. (`length?: never` is what keeps an array out of the type.)
+ */
+export type AiToolOutput = {
+    [field: string]: unknown;
+    length?: never;
+};
+export type AiToolHandler = (call: AiToolCall) => Promise<AiToolOutput> | AiToolOutput;
+export interface AiToolRequestOptions extends Omit<ProxyVerifyOptions, "expectedSurface"> {
+    /** The manifest `extensions.proxy.subpath`; the signed path is `/apps/<subpath>/ai/<tool>`. */
+    subpath: string;
+    /** The active proxy secrets of installation `kid`, current first (empty when unknown). */
+    secrets: (kid: string) => Promise<string[]> | string[];
+    /** The read tools the manifest `ai.tools` declares, by key. Only these are served. */
+    tools: Record<string, AiToolHandler>;
+    /**
+     * Makes each call single-use: when given, a verified call's `jti` is claimed atomically in this store, exactly as
+     * `verifyProxyDelivery` does, and a replay answers 401 `replayed`. Pass the installation store. Without it a
+     * captured call can be replayed inside the skew window.
+     */
+    replayStore?: Pick<InstallationStore, "claimWebhookId">;
+}
+/**
+ * Layer 2 for Queek AI read tools (manifest `ai.tools`): `GET ai/{tool}` signed with `surface=ai`. The signature and
+ * the surface are verified first (401, or 403 for a genuine call signed for another surface). `surface=ai` is served
+ * only by a declared tool handler (403 for an undeclared key), a storefront or dashboard call at this path is
+ * refused, and an AI call never reaches `handleProxyRequest`'s responder. A handler that answers anything but an
+ * object (a bare array, a scalar) is answered 500. Pass `replayStore` to make each call single-use; a tool only
+ * reads, so without it a replay inside the skew window repeats nothing but the read.
+ */
+export declare function handleAiToolRequest(request: Request, tool: string, options: AiToolRequestOptions): Promise<Response>;

package/dist/proxy.js

@@ -32,6 +32,7 @@ export const PROXY_NONCE_PARAM = "jti";
 export const PROXY_SHOP_PARAM = "shop";
 export const PROXY_CUSTOMER_PARAM = "logged_in_customer_id";
 export const PROXY_KID_PARAM = "kid";
+export const PROXY_SURFACE_PARAM = "surface";
 /** Default allowed clock skew in seconds; the floor (60s) below applies regardless. */
 export const PROXY_MAX_SKEW_SECONDS = 300;
 /** RFC 3986 percent-encoding: everything except `[A-Za-z0-9-_.~]` is `%XX` (upper-case hex), the encoding Queek signs with. */
@@ -89,6 +90,13 @@ function proxySkewExceeded(ts, options) {
     const maxSkew = Math.max(60, options.maxSkewSeconds ?? PROXY_MAX_SKEW_SECONDS);
     return Math.abs(now - Number(ts)) > maxSkew;
 }
+/** The signed surface, or `""` when the call carries none. Trust it only after the MAC verified. */
+function signedSurface(params) {
+    return params[PROXY_SURFACE_PARAM] ?? "";
+}
+function surfaceAllowed(params, options) {
+    return options.expectedSurface === undefined || signedSurface(params) === options.expectedSurface;
+}
 function proxyMacMatches(path, params, sig, secret) {
     if (secret === "")
         return false;
@@ -117,7 +125,9 @@ export function verifyProxyQueryDetailed(path, query, secrets, options = {}) {
     }
     for (const secret of secrets) {
         if (proxyMacMatches(path, params, sig, secret)) {
-            return { ok: true };
+            return surfaceAllowed(params, options)
+                ? { ok: true, surface: signedSurface(params) }
+                : { ok: false, reason: "surface_mismatch" };
         }
     }
     return { ok: false, reason: "signature_mismatch" };
@@ -136,7 +146,11 @@ export function verifyProxyQuery(path, query, secrets, options = {}) {
  * read cannot be replayed.
  */
 export async function verifyProxyDelivery(input, options) {
-    const fail = (reason) => ({ ok: false, reason, status: 401 });
+    const fail = (reason, status = 401) => ({
+        ok: false,
+        reason,
+        status,
+    });
     const params = normalizeQuery(input.query);
     const { sig, ts, jti } = readProxyFields(params);
     if (sig === "" || ts === "" || jti === "" || !/^\d+$/.test(ts)) {
@@ -171,12 +185,25 @@ export async function verifyProxyDelivery(input, options) {
     if (!installation) {
         return fail("signature_mismatch");
     }
+    // A genuine signature for another surface is forbidden, not unauthenticated.
+    if (!surfaceAllowed(params, options)) {
+        return fail("surface_mismatch", 403);
+    }
     if (options.enforceReplay ?? true) {
         if (!(await options.store.claimWebhookId(`proxy-jti:${jti}`))) {
             return fail("replayed");
         }
     }
-    return { ok: true, installation, params };
+    return { ok: true, installation, params, surface: signedSurface(params) };
+}
+/** The query of a Web `Request`, duplicates collapsing to the first value like `URLSearchParams.get`. */
+function requestQuery(request) {
+    const url = new URL(request.url);
+    const query = {};
+    for (const key of url.searchParams.keys()) {
+        query[key] = url.searchParams.get(key);
+    }
+    return query;
 }
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads the query
@@ -188,15 +215,68 @@ export async function handleProxyRequest(request, options, onVerified) {
     if (request.method.toUpperCase() !== "GET") {
         return toResponse({ status: 405, body: { ok: false, error: "method_not_allowed" } });
     }
-    const url = new URL(request.url);
-    const query = {};
-    for (const key of url.searchParams.keys()) {
-        query[key] = url.searchParams.get(key);
-    }
+    const query = requestQuery(request);
     const verified = await verifyProxyDelivery({ path: options.path, query }, options);
     if (!verified.ok) {
         const result = { status: verified.status, body: { ok: false, error: verified.reason } };
         return toResponse(result);
     }
-    return onVerified({ installation: verified.installation, params: verified.params });
+    // A responder serves storefront and dashboard calls. An AI call is served only by a declared tool handler.
+    if (verified.surface === "ai") {
+        return toResponse({ status: 403, body: { ok: false, error: "forbidden" } });
+    }
+    return onVerified({
+        installation: verified.installation,
+        params: verified.params,
+        surface: verified.surface,
+    });
+}
+/**
+ * Layer 2 for Queek AI read tools (manifest `ai.tools`): `GET ai/{tool}` signed with `surface=ai`. The signature and
+ * the surface are verified first (401, or 403 for a genuine call signed for another surface). `surface=ai` is served
+ * only by a declared tool handler (403 for an undeclared key), a storefront or dashboard call at this path is
+ * refused, and an AI call never reaches `handleProxyRequest`'s responder. A handler that answers anything but an
+ * object (a bare array, a scalar) is answered 500. Pass `replayStore` to make each call single-use; a tool only
+ * reads, so without it a replay inside the skew window repeats nothing but the read.
+ */
+export async function handleAiToolRequest(request, tool, options) {
+    if (request.method.toUpperCase() !== "GET") {
+        return toResponse({ status: 405, body: { ok: false, error: "method_not_allowed" } });
+    }
+    const { subpath, secrets, tools, replayStore, ...verifyOptions } = options;
+    const query = requestQuery(request);
+    const params = normalizeQuery(query);
+    const kid = params[PROXY_KID_PARAM] ?? "";
+    const verified = verifyProxyQueryDetailed(`/apps/${subpath}/ai/${tool}`, query, await secrets(kid), {
+        ...verifyOptions,
+        expectedSurface: "ai",
+    });
+    if (!verified.ok) {
+        return toResponse({
+            status: verified.reason === "surface_mismatch" ? 403 : 401,
+            body: { ok: false, error: verified.reason },
+        });
+    }
+    if (replayStore && !(await replayStore.claimWebhookId(`proxy-jti:${params[PROXY_NONCE_PARAM]}`))) {
+        return toResponse({ status: 401, body: { ok: false, error: "replayed" } });
+    }
+    const handler = Object.hasOwn(tools, tool) ? tools[tool] : undefined;
+    if (!handler) {
+        return toResponse({ status: 403, body: { ok: false, error: "forbidden" } });
+    }
+    const output = await handler({
+        kid,
+        shop: params[PROXY_SHOP_PARAM] ?? "",
+        params,
+        tool,
+        actorRole: params.actor_role ?? "",
+    });
+    if (output === null || typeof output !== "object" || Array.isArray(output)) {
+        return toResponse({ status: 500, body: { ok: false, error: "invalid_tool_output" } });
+    }
+    return toResponse({
+        status: 200,
+        body: output,
+        headers: { "Cache-Control": "private, no-store, max-age=0" },
+    });
 }

package/dist/webhooks.d.ts

@@ -1,4 +1,4 @@
-import { type CoreDelivery, type DeliveryErrorHandler, type DeliveryResult } from "./delivery.js";
+import { type DeliveryErrorHandler, type DeliveryResult, type WebhookDelivery } from "./delivery.js";
 import type { InstallationRecord, InstallationStore } from "./store.js";
 /**
  * Framework-agnostic receiver for Queek topic deliveries (one signed POST
@@ -79,6 +79,11 @@ export interface WebhookHandlerOptions {
  * 200 for a handled, repeated or unhandled-topic delivery; 500 when your
  * handler throws (the claim is released so Queek's retry can land).
  *
+ * `method` `GET` or `HEAD` is the review probe: 200 `{ ok: true }` with
+ * `Cache-Control: no-store` and no handler; with a signature (over the
+ * empty body) 200 when it verifies against an installation secret and 401
+ * when not.
+ *
  * @example
  * const result = await handleWebhookDelivery(
  *   { rawBody, headers },
@@ -93,10 +98,11 @@ export interface WebhookHandlerOptions {
  * );
  * // reply with result.status and result.body
  */
-export declare function handleWebhookDelivery(input: CoreDelivery, options: WebhookHandlerOptions): Promise<DeliveryResult>;
+export declare function handleWebhookDelivery(input: WebhookDelivery, options: WebhookHandlerOptions): Promise<DeliveryResult>;
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads
  * `await request.arrayBuffer()` + headers, calls the core, builds the
- * `Response`. Only `POST` is served; anything else answers 405.
+ * `Response`. `POST` is a delivery; `GET` and `HEAD` are the review probe
+ * (see `handleWebhookDelivery`); anything else answers 405.
  */
 export declare function handleWebhookRequest(request: Request, options: WebhookHandlerOptions): Promise<Response>;

package/dist/webhooks.js

@@ -1,4 +1,4 @@
-import { decodeBody, readHeader, reportDeliveryFailure, toResponse, } from "./delivery.js";
+import { decodeBody, isProbeMethod, isUnsignedProbe, probeResult, readHeader, reportDeliveryFailure, toResponse, } from "./delivery.js";
 import { isFreshTimestamp, MAX_TIMESTAMP_SKEW_SECONDS, verifyQueekSignature, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./signatures.js";
 /**
  * Framework-agnostic receiver for Queek topic deliveries (one signed POST
@@ -57,6 +57,50 @@ async function defaultResolveSecret(store, rawBody, headers, envelope) {
     }
     return null;
 }
+/**
+ * Resolve the endpoint secret that signed a delivery and verify freshness
+ * and the MAC against it. The single verification path of a delivery AND of
+ * a signed review probe (empty body, no envelope).
+ */
+async function verifyAgainstResolvedSecret(options, rawBody, headers, envelope) {
+    const resolution = options.resolveSecret
+        ? await options.resolveSecret(envelope, rawBody, headers)
+        : await defaultResolveSecret(options.store, rawBody, headers, envelope);
+    if (!resolution) {
+        return { ok: false, error: "unknown_installation" };
+    }
+    // Freshness is enforced HERE, once, against the resolved secret — the
+    // lookup above deliberately skips it so a stale delivery cannot be
+    // misattributed before it is rejected.
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (!isFreshTimestamp(headers.timestamp, now, options.maxSkewSeconds ?? MAX_TIMESTAMP_SKEW_SECONDS)) {
+        return { ok: false, error: "stale timestamp" };
+    }
+    // Freshness was enforced above; this re-checks the MAC only, so a
+    // custom resolver cannot claim an installation without its secret.
+    if (!verifyQueekSignature({ ...headers, body: rawBody, secret: resolution.secret }, { skipFreshnessCheck: true })) {
+        return { ok: false, error: "signature mismatch" };
+    }
+    return { ok: true, resolution };
+}
+/**
+ * The review probe (`GET` / `HEAD`): 200 without running a handler or
+ * touching the store. A probe that carries a signature is verified like a
+ * delivery, over the empty body and against the stored endpoint secrets:
+ * 200 when it verifies, 401 when not. A valid probe claims nothing.
+ */
+async function probeDelivery(input, options) {
+    if (isUnsignedProbe(input.headers))
+        return probeResult(200);
+    const id = readHeader(input.headers, WEBHOOK_ID_HEADER);
+    const timestamp = readHeader(input.headers, WEBHOOK_TIMESTAMP_HEADER);
+    const signatureHeader = readHeader(input.headers, WEBHOOK_SIGNATURE_HEADER);
+    if (!id || !timestamp || !signatureHeader) {
+        return probeResult(401, "missing signature headers");
+    }
+    const verified = await verifyAgainstResolvedSecret(options, "", { id, timestamp, signatureHeader }, null);
+    return verified.ok ? probeResult(200) : probeResult(401, verified.error);
+}
 /**
  * Layer 1: handle one signed Queek topic delivery from plain data — no
  * `Request`, no framework. Same options, same behaviour, same
@@ -67,6 +111,11 @@ async function defaultResolveSecret(store, rawBody, headers, envelope) {
  * 200 for a handled, repeated or unhandled-topic delivery; 500 when your
  * handler throws (the claim is released so Queek's retry can land).
  *
+ * `method` `GET` or `HEAD` is the review probe: 200 `{ ok: true }` with
+ * `Cache-Control: no-store` and no handler; with a signature (over the
+ * empty body) 200 when it verifies against an installation secret and 401
+ * when not.
+ *
  * @example
  * const result = await handleWebhookDelivery(
  *   { rawBody, headers },
@@ -82,7 +131,8 @@ async function defaultResolveSecret(store, rawBody, headers, envelope) {
  * // reply with result.status and result.body
  */
 export async function handleWebhookDelivery(input, options) {
-    const maxSkew = options.maxSkewSeconds ?? MAX_TIMESTAMP_SKEW_SECONDS;
+    if (isProbeMethod(input.method))
+        return probeDelivery(input, options);
     const rawBody = decodeBody(input.rawBody);
     const id = readHeader(input.headers, WEBHOOK_ID_HEADER);
     const timestamp = readHeader(input.headers, WEBHOOK_TIMESTAMP_HEADER);
@@ -103,24 +153,10 @@ export async function handleWebhookDelivery(input, options) {
         return { status: 400, body: { ok: false, error: "invalid_envelope" } };
     }
     const headers = { id, timestamp, signatureHeader };
-    const resolution = options.resolveSecret
-        ? await options.resolveSecret(envelope, rawBody, headers)
-        : await defaultResolveSecret(options.store, rawBody, headers, envelope);
-    if (!resolution) {
-        return { status: 401, body: { ok: false, error: "unknown_installation" } };
-    }
-    // Freshness is enforced HERE, once, against the resolved secret — the
-    // lookup above deliberately skips it so a stale delivery cannot be
-    // misattributed before it is rejected.
-    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
-    if (!isFreshTimestamp(timestamp, now, maxSkew)) {
-        return { status: 401, body: { ok: false, error: "stale timestamp" } };
-    }
-    // Freshness was enforced above; this re-checks the MAC only, so a
-    // custom resolver cannot claim an installation without its secret.
-    if (!verifyQueekSignature({ ...headers, body: rawBody, secret: resolution.secret }, { skipFreshnessCheck: true })) {
-        return { status: 401, body: { ok: false, error: "signature mismatch" } };
-    }
+    const verified = await verifyAgainstResolvedSecret(options, rawBody, headers, envelope);
+    if (!verified.ok)
+        return { status: 401, body: { ok: false, error: verified.error } };
+    const resolution = verified.resolution;
     const installation = await options.store.getInstallation(resolution.installationId);
     if (!installation) {
         return { status: 401, body: { ok: false, error: "unknown_installation" } };
@@ -151,14 +187,17 @@ export async function handleWebhookDelivery(input, options) {
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads
  * `await request.arrayBuffer()` + headers, calls the core, builds the
- * `Response`. Only `POST` is served; anything else answers 405.
+ * `Response`. `POST` is a delivery; `GET` and `HEAD` are the review probe
+ * (see `handleWebhookDelivery`); anything else answers 405.
  */
 export async function handleWebhookRequest(request, options) {
-    if (request.method.toUpperCase() !== "POST") {
+    const method = request.method.toUpperCase();
+    if (method !== "POST" && !isProbeMethod(method)) {
         return toResponse({ status: 405, body: { ok: false, error: "method_not_allowed" } });
     }
     return toResponse(await handleWebhookDelivery({
         rawBody: new Uint8Array(await request.arrayBuffer()),
         headers: request.headers,
-    }, options));
+        method,
+    }, options), method);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/app-sdk",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "private": false,
   "license": "MIT",
   "author": "Queekx Technology LTD",