@usequeek/app-sdk 0.6.1 → 0.7.0

package/dist/scopes.js

@@ -1,11 +1,10 @@
 import { isInstallationGone, UnknownInstallationError } from "./app-auth.js";
-import { newIdempotencyKey, QueekApiError, queekApiErrorFromResponse } from "./client.js";
+import { DEFAULT_REQUEST_TIMEOUT_MS, newIdempotencyKey, QueekApiError, queekApiErrorFromResponse, requestSignal, transportError, tryParseJson, } from "./client.js";
 import { isAllowedOpenTarget } from "./frame.js";
 import { installationScopesEqual } from "./install-handlers.js";
 import { resolveAppApiBase } from "./tokens.js";
 /**
- * Optional scopes (plan item 6, Shopify `scopes.query / request / revoke`
- * parity — symbol names cited only).
+ * Optional scopes: query, request and revoke.
  *
  * - `queryScopes`: the cached effective grant split against the app's own
  *   declared-optional list. Store-read only, never a fetch: the app-credential
@@ -17,25 +16,24 @@ import { resolveAppApiBase } from "./tokens.js";
  *   consent — it hands the app a link shaped like the bridge
  *   `open`/`navigate` targets (dashboard-relative path, or an absolute URL
  *   under a given dashboard origin) for the app to open via `sendOpen` or
- *   redirect to. The consent screen itself ships with the dashboard (plan
- *   item 8), which honours this link shape.
+ *   redirect to. Opening it requires a dashboard that supports the consent
+ *   screen, which honours this link shape.
  * - `revokeScopes`: `POST
  *   /api/v1/apps/installations/{installation}/scopes/revoke` with the app
- *   JWT (same credential as mint/resync — never auth:sanctum, never the
- *   installation token). Body `{scopes[]}` (1–50, backend
- *   `RevokeAppScopesRequest`); an `Idempotency-Key` rides the write for
+ *   JWT (same credential as mint/resync — not the installation token).
+ *   Body `{scopes[]}` (1–50); an `Idempotency-Key` rides the write for
  *   discipline (generated when the caller does not supply one — the client
  *   write discipline), though the route is naturally idempotent: revoking
  *   a never-granted optional scope is 200 with no change. Required scopes
  *   refuse 422 `app_scope_required` (surfaced as `AppScopeRequiredError`).
  *   On 200 the cached grant is refreshed from the response and the cached
  *   token dropped only when the grant moved (same compare-and-clear as the
- *   scopes_update handler — the backend rewrites live token rows in place,
- *   so the drop is backstop, not mechanism).
+ *   scopes_update handler — Queek rewrites live token rows in place, so
+ *   the drop is a backstop, not the mechanism).
  *
  * Types here are hand-written: the revoke endpoint and the scopes_update
- * handoff live on the app-credential surface, which the frozen
- * `openapi/merchant.json` does not cover (types are generated app-side by
+ * handoff live on the app-credential surface, which the bundled
+ * `openapi/merchant.json` snapshot does not cover (types are generated app-side by
  * `queek app codegen`; the merchant spec file is never hand-edited).
  */
 /** 422 on the revoke endpoint: required scopes are never revocable (uninstall is the remedy). */
@@ -48,8 +46,8 @@ export function isAppScopeRequired(status, code) {
 }
 /**
  * A required-scope refusal, typed so callers switch on the class (or
- * `code`), never on `message`. Carries the offending scopes when the
- * backend named them.
+ * `code`), never on `message`. Carries the offending scopes when Queek
+ * named them.
  */
 export class AppScopeRequiredError extends QueekApiError {
     scopes;
@@ -79,13 +77,13 @@ export class InvalidScopesError extends Error {
         this.name = "InvalidScopesError";
     }
 }
-/** Backend `RevokeAppScopesRequest` bounds, mirrored client-side. */
+/** Bounds of the revoke request (1–50 scopes), mirrored client-side. */
 export const MAX_SCOPE_LIST = 50;
 export const MAX_SCOPE_LENGTH = 120;
 /**
  * Validate + normalise a scope list (trim, drop empties, dedupe keeping
- * first order). Mirrors the backend contract (`required array min:1
- * max:50`, string items) so a malformed call fails before any fetch.
+ * first order). Mirrors the revoke endpoint's rules (a required array of
+ * 1–50 string items) so a malformed call fails before any fetch.
  */
 export function normaliseScopeList(scopes) {
     if (!Array.isArray(scopes)) {
@@ -134,8 +132,7 @@ export function revokeScopesPath(installationId) {
  * under `dashboardOrigin` (refused exactly like `sendOpen` refuses a bad
  * target).
  *
- * Link shape (the SDK↔dashboard contract the consent screen honours —
- * the only query route the dashboard `AppsPage` serves):
+ * Link shape (the contract the dashboard's consent screen honours):
  * `/apps?app={slug}&view=scopes&scopes={a},{b}` (each scope
  * URL-encoded, comma-separated). The link carries the slug + the scope
  * list only: the dashboard resolves the installation from the signed-in
@@ -164,6 +161,20 @@ export function buildScopeRequestLink(options) {
     }
     return link;
 }
+/**
+ * Build the optional-scopes session for one installation: read the cached
+ * grant, build the dashboard consent link, and revoke optional scopes.
+ *
+ * @example
+ * const scopes = createInstallationScopesClient({
+ *   installationId,
+ *   store,
+ *   signJwt: () => tokens.signJwt(),
+ *   appSlug: "my-app",
+ *   optionalScopes: ["merchant-orders-read"],
+ * });
+ * const { granted } = await scopes.queryScopes();
+ */
 export function createInstallationScopesClient(options) {
     if (!options.installationId || options.installationId.trim() === "") {
         throw new InvalidScopesError("An installation id is required.");
@@ -193,7 +204,7 @@ export function createInstallationScopesClient(options) {
      * The dashboard deep link that opens the merchant's consent screen in
      * the dashboard. Pure (no store, no network): the app opens it via
      * `sendOpen` or a redirect and the merchant consents in the dashboard
-     * (shipped with dashboard item 8). Shaped like the bridge `open`
+     * (requires a dashboard that supports the consent screen). Shaped like the bridge `open`
      * targets — dashboard-relative, or absolute under the dashboard origin
      * when one is configured.
      */
@@ -209,14 +220,13 @@ export function createInstallationScopesClient(options) {
         });
     }
     /**
-     * App-initiated revoke of optional scopes (backend
-     * `AppInstallationController::revokeScopes`): the app JWT signs the call
+     * App-initiated revoke of optional scopes: the app JWT signs the call
      * (same credential as mint/resync), an `Idempotency-Key` rides the write
      * for discipline only (the route is naturally idempotent), and on 200
      * the cached grant is refreshed from the response with the cached token
      * dropped only when the grant moved (same compare-and-clear as the
-     * scopes_update handler — backstop, since the backend rewrites live
-     * token rows in place). A required scope refuses 422
+     * scopes_update handler — a backstop, since Queek rewrites live token
+     * rows in place). A required scope refuses 422
      * `app_scope_required` as `AppScopeRequiredError`; a gone installation
      * purges the local row and rethrows; anything else propagates untouched.
      * A 401 never halts here — the mint path owns that mapping and halts on
@@ -243,15 +253,11 @@ export function createInstallationScopesClient(options) {
                 method: "POST",
                 headers,
                 body: JSON.stringify({ scopes: requested }),
-                signal: revokeOptions.signal,
+                signal: requestSignal(revokeOptions.signal, DEFAULT_REQUEST_TIMEOUT_MS),
             });
         }
         catch (cause) {
-            throw new QueekApiError({
-                status: 0,
-                code: "network_error",
-                message: cause instanceof Error ? `Could not reach Queek: ${cause.message}` : "Could not reach Queek.",
-            });
+            throw transportError(cause, revokeOptions.signal);
         }
         const text = await response.text();
         const parsed = text === "" ? null : tryParseJson(text);
@@ -282,16 +288,7 @@ function parseRevokeBody(body) {
     const record = (typeof body === "object" && body !== null ? body : {});
     const scopes = record.scopes;
     if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string")) {
-        throw new Error("Malformed revoke response: expected {scopes: string[]}.");
+        throw new Error("Malformed revoke response: expected {scopes: string[]}. The grant was not refreshed; call queryScopes() after Queek delivers the scopes update, or retry.");
     }
     return [...scopes];
 }
-function tryParseJson(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return { message: text.slice(0, 500) };
-    }
-}
-//# sourceMappingURL=scopes.js.map

package/dist/server.d.ts

@@ -6,4 +6,3 @@
  */
 export type { SessionTokenBinding, SessionTokenClaims, SessionTokenFailure, VerifySessionTokenOptions, } from "./session.js";
 export { EMBED_SECRET_PREFIX, SESSION_CLOCK_TOLERANCE_SECONDS, sessionTokenInstallationId, verifySessionToken, verifySessionTokenDetailed, } from "./session.js";
-//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -5,4 +5,3 @@
  * the main entry.
  */
 export { EMBED_SECRET_PREFIX, SESSION_CLOCK_TOLERANCE_SECONDS, sessionTokenInstallationId, verifySessionToken, verifySessionTokenDetailed, } from "./session.js";
-//# sourceMappingURL=server.js.map

package/dist/session.d.ts

@@ -1,16 +1,15 @@
 /**
- * Dashboard session tokens: short-lived HS256 JWTs the backend mints per
- * installation for the framed merchant page. The app backend verifies them
- * with the per-installation `embsec_…` secret before trusting any call
- * that carries one.
+ * Dashboard session tokens: short-lived HS256 JWTs Queek mints per
+ * installation for the framed merchant page. The app's server verifies
+ * them with the per-installation `embsec_…` secret before trusting any
+ * call that carries one.
  *
- * ONE token type, exactly Shopify's `id_token` shape: the dashboard puts
- * the same token in the first-load URL param (`queek_token`, stripped on
- * arrival) and answers bridge `ready` requests with it, so the app's
- * exchange endpoint verifies first-load and refresh tokens with this one
- * verifier. No purpose split: extra claims the mint may carry are ignored,
- * never gated — identity binding (installation, audience, issuer, expiry)
- * is the whole check.
+ * ONE token type: the dashboard puts the same token in the first-load URL
+ * param (`queek_token`, stripped on arrival) and answers bridge `ready`
+ * requests with it, so the app's exchange endpoint verifies first-load and
+ * refresh tokens with this one verifier. No purpose split: extra claims the
+ * mint may carry are ignored, never gated — identity binding
+ * (installation, audience, issuer, expiry) is the whole check.
  *
  * Server-only: the secret must never enter a browser bundle, so this module
  * ships behind the `./server` export, not the main entry. Style mirrors
@@ -20,7 +19,7 @@
 export declare const EMBED_SECRET_PREFIX = "embsec_";
 /** The only JWS algorithm the dashboard mints (HS256 over the embsec_ secret). */
 export declare const SESSION_TOKEN_ALG = "HS256";
-/** Backend skew the verifier tolerates (matches the mint side). */
+/** Clock skew the verifier tolerates, in seconds (matches the mint side). */
 export declare const SESSION_CLOCK_TOLERANCE_SECONDS = 20;
 export type SessionTokenFailure = "missing_token" | "missing_secret" | "wrong_algorithm" | "invalid_signature" | "expired" | "not_yet_valid" | "wrong_audience" | "wrong_issuer" | "binding_mismatch";
 export interface SessionTokenClaims {
@@ -46,20 +45,40 @@ export interface VerifySessionTokenOptions {
     audience: string;
     /**
      * Expected issuer: the handoff `api_base` VERBATIM
-     * (`installation.apiBase` — it equals the bare `app.url` the backend
-     * signs as `iss`). Never a prefix or a suffix of it.
+     * (`installation.apiBase` — it equals the bare `app.url` Queek signs as
+     * `iss`). Never a prefix or a suffix of it.
      */
     issuer: string;
     /**
-     * The installation row the token must belong to (the app backend's own
+     * The installation row the token must belong to (the app server's own
      * record). Every field is compared — a token minted for another
      * installation fails closed even when its signature and audience check
-     * out, mirroring the backend `verify()`.
+     * out.
      */
     expected: SessionTokenBinding;
     clockToleranceSeconds?: number;
 }
+/**
+ * True when `token` is a valid dashboard session token for the installation
+ * in `options.expected`. See {@link verifySessionTokenDetailed} for the
+ * reason a token was refused.
+ */
 export declare function verifySessionToken(token: string, options: VerifySessionTokenOptions): Promise<boolean>;
+/**
+ * Verify a dashboard session token: algorithm pin, signature, audience,
+ * issuer, expiry (20 s clock tolerance), then the installation binding.
+ * Returns the claims on success and a stable `reason` on failure. Answer 401
+ * for every failure.
+ *
+ * @example
+ * const checked = await verifySessionTokenDetailed(token, {
+ *   secret: installation.embedSecret ?? "",
+ *   audience: "my-app",
+ *   issuer: installation.apiBase,
+ *   expected: { installationId, vendorId, appSlug: "my-app", appId },
+ * });
+ * if (!checked.ok) return new Response(checked.reason, { status: 401 });
+ */
 export declare function verifySessionTokenDetailed(token: string, options: VerifySessionTokenOptions): Promise<{
     ok: true;
     claims: SessionTokenClaims;
@@ -75,4 +94,3 @@ export declare function verifySessionTokenDetailed(token: string, options: Verif
  * Null for anything that is not a decodable JWT carrying the claim.
  */
 export declare function sessionTokenInstallationId(token: string): string | null;
-//# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -1,17 +1,16 @@
 import { decodeJwt, decodeProtectedHeader, jwtVerify } from "jose";
 /**
- * Dashboard session tokens: short-lived HS256 JWTs the backend mints per
- * installation for the framed merchant page. The app backend verifies them
- * with the per-installation `embsec_…` secret before trusting any call
- * that carries one.
+ * Dashboard session tokens: short-lived HS256 JWTs Queek mints per
+ * installation for the framed merchant page. The app's server verifies
+ * them with the per-installation `embsec_…` secret before trusting any
+ * call that carries one.
  *
- * ONE token type, exactly Shopify's `id_token` shape: the dashboard puts
- * the same token in the first-load URL param (`queek_token`, stripped on
- * arrival) and answers bridge `ready` requests with it, so the app's
- * exchange endpoint verifies first-load and refresh tokens with this one
- * verifier. No purpose split: extra claims the mint may carry are ignored,
- * never gated — identity binding (installation, audience, issuer, expiry)
- * is the whole check.
+ * ONE token type: the dashboard puts the same token in the first-load URL
+ * param (`queek_token`, stripped on arrival) and answers bridge `ready`
+ * requests with it, so the app's exchange endpoint verifies first-load and
+ * refresh tokens with this one verifier. No purpose split: extra claims the
+ * mint may carry are ignored, never gated — identity binding
+ * (installation, audience, issuer, expiry) is the whole check.
  *
  * Server-only: the secret must never enter a browser bundle, so this module
  * ships behind the `./server` export, not the main entry. Style mirrors
@@ -21,12 +20,32 @@ import { decodeJwt, decodeProtectedHeader, jwtVerify } from "jose";
 export const EMBED_SECRET_PREFIX = "embsec_";
 /** The only JWS algorithm the dashboard mints (HS256 over the embsec_ secret). */
 export const SESSION_TOKEN_ALG = "HS256";
-/** Backend skew the verifier tolerates (matches the mint side). */
+/** Clock skew the verifier tolerates, in seconds (matches the mint side). */
 export const SESSION_CLOCK_TOLERANCE_SECONDS = 20;
+/**
+ * True when `token` is a valid dashboard session token for the installation
+ * in `options.expected`. See {@link verifySessionTokenDetailed} for the
+ * reason a token was refused.
+ */
 export async function verifySessionToken(token, options) {
     const result = await verifySessionTokenDetailed(token, options);
     return result.ok;
 }
+/**
+ * Verify a dashboard session token: algorithm pin, signature, audience,
+ * issuer, expiry (20 s clock tolerance), then the installation binding.
+ * Returns the claims on success and a stable `reason` on failure. Answer 401
+ * for every failure.
+ *
+ * @example
+ * const checked = await verifySessionTokenDetailed(token, {
+ *   secret: installation.embedSecret ?? "",
+ *   audience: "my-app",
+ *   issuer: installation.apiBase,
+ *   expected: { installationId, vendorId, appSlug: "my-app", appId },
+ * });
+ * if (!checked.ok) return new Response(checked.reason, { status: 401 });
+ */
 export async function verifySessionTokenDetailed(token, options) {
     const envelope = await verifyTokenEnvelope(token, options);
     if (!envelope.ok)
@@ -132,8 +151,7 @@ function readSessionClaims(payload) {
     return { installationId, vendorId, appSlug, appId, subject, sessionId, issuedAt, expiresAt };
 }
 function classifyJoseError(error) {
-    // Exact jose v6 pins (verified against jose@6.2.12 — codes, names, and
-    // the `claim` field probed, not guessed): claim failures carry code
+    // Exact jose v6 error shapes (jose@6.2.12): claim failures carry code
     // ERR_JWT_CLAIM_VALIDATION_FAILED and name the claim; expiry also
     // surfaces as JWTExpired / ERR_JWT_EXPIRED; algorithm refusal is
     // JOSEAlgNotAllowed / ERR_JOSE_ALG_NOT_ALLOWED (unreachable in practice —
@@ -171,4 +189,3 @@ function classifyJoseError(error) {
     }
     return "invalid_signature";
 }
-//# sourceMappingURL=session.js.map

package/dist/signatures.d.ts

@@ -1,6 +1,7 @@
 /**
- * Standard Webhooks verification, byte-for-byte compatible with Queek's
- * `App\Services\Webhooks\WebhookSigner` (queek_backend).
+ * Standard Webhooks verification, byte-for-byte compatible with the way
+ * Queek signs deliveries
+ * (https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md).
  *
  * Signed content: `{id}.{timestamp}.{body}` where `body` is the RAW request
  * bytes. Re-serialising JSON before verifying breaks the MAC — verify first,
@@ -8,7 +9,7 @@
  *
  * The MAC key is the DECODED bytes of the `whsec_<base64>` secret, not the
  * printable string. A secret without the prefix (or with undecodable base64)
- * falls back to the raw string, exactly like the backend's `keyFor()`.
+ * falls back to the raw string, exactly like Queek's signer.
  *
  * Header names: `webhook-id`, `webhook-timestamp`, `webhook-signature`.
  * The signature header may carry several space-delimited `v1,<base64>`
@@ -40,16 +41,41 @@ export interface VerifyOptions {
     /** Skip the freshness check (NOT recommended; exposed for replaying stored fixtures). */
     skipFreshnessCheck?: boolean;
 }
+/**
+ * True when `timestamp` is a plain unix-seconds integer within `maxSkewSeconds`
+ * of `nowSeconds`, in either direction. Anything else (`""`, `"1e3"`,
+ * `"0x10"`, `"12.5"`) is stale: the signed header must be what Queek sent.
+ */
+export declare function isFreshTimestamp(timestamp: string, nowSeconds: number, maxSkewSeconds: number): boolean;
+/** The decoded MAC key for a `whsec_` secret (a secret that is not valid base64 is used as raw text). */
 export declare function secretKeyBytes(secret: string): Buffer;
-/** One `v1,<base64>` signature for one secret — mirrors `WebhookSigner::sign()`. */
+/** One `v1,<base64>` signature for one secret, in the format Queek sends. */
 export declare function signQueekPayload(eventId: string, timestamp: number | string, body: string, secret: string): string;
 /** Failure reason when verification rejects a delivery. */
 export type SignatureFailure = "missing_headers" | "stale_timestamp" | "signature_mismatch";
+/**
+ * True when one of the signatures in the header matches the body, and the
+ * timestamp is within the skew window. The compare is constant-time and
+ * covers every signature in the header (a secret rotation sends two).
+ *
+ * @example
+ * const ok = verifyQueekSignature({
+ *   id: request.headers.get("webhook-id") ?? "",
+ *   timestamp: request.headers.get("webhook-timestamp") ?? "",
+ *   signatureHeader: request.headers.get("webhook-signature") ?? "",
+ *   body: await request.text(), // the raw text, before any JSON.parse
+ *   secret: installation.webhookSecret,
+ * });
+ */
 export declare function verifyQueekSignature(input: SignatureInput, options?: VerifyOptions): boolean;
+/**
+ * Like {@link verifyQueekSignature}, but says why a delivery was rejected:
+ * `missing_headers`, `stale_timestamp` or `signature_mismatch`. Log the
+ * reason; answer 401 either way.
+ */
 export declare function verifyQueekSignatureDetailed(input: SignatureInput, options?: VerifyOptions): {
     ok: true;
 } | {
     ok: false;
     reason: SignatureFailure;
 };
-//# sourceMappingURL=signatures.d.ts.map

package/dist/signatures.js

@@ -1,7 +1,8 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 /**
- * Standard Webhooks verification, byte-for-byte compatible with Queek's
- * `App\Services\Webhooks\WebhookSigner` (queek_backend).
+ * Standard Webhooks verification, byte-for-byte compatible with the way
+ * Queek signs deliveries
+ * (https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md).
  *
  * Signed content: `{id}.{timestamp}.{body}` where `body` is the RAW request
  * bytes. Re-serialising JSON before verifying breaks the MAC — verify first,
@@ -9,7 +10,7 @@ import { createHmac, timingSafeEqual } from "node:crypto";
  *
  * The MAC key is the DECODED bytes of the `whsec_<base64>` secret, not the
  * printable string. A secret without the prefix (or with undecodable base64)
- * falls back to the raw string, exactly like the backend's `keyFor()`.
+ * falls back to the raw string, exactly like Queek's signer.
  *
  * Header names: `webhook-id`, `webhook-timestamp`, `webhook-signature`.
  * The signature header may carry several space-delimited `v1,<base64>`
@@ -21,12 +22,21 @@ export const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
 export const SECRET_PREFIX = "whsec_";
 /** Maximum age of a delivery before it is rejected as stale (5 minutes, the Standard Webhooks default). */
 export const MAX_TIMESTAMP_SKEW_SECONDS = 5 * 60;
+/**
+ * True when `timestamp` is a plain unix-seconds integer within `maxSkewSeconds`
+ * of `nowSeconds`, in either direction. Anything else (`""`, `"1e3"`,
+ * `"0x10"`, `"12.5"`) is stale: the signed header must be what Queek sent.
+ */
+export function isFreshTimestamp(timestamp, nowSeconds, maxSkewSeconds) {
+    return /^\d{1,15}$/.test(timestamp) && Math.abs(nowSeconds - Number(timestamp)) <= maxSkewSeconds;
+}
+/** The decoded MAC key for a `whsec_` secret (a secret that is not valid base64 is used as raw text). */
 export function secretKeyBytes(secret) {
     const encoded = secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret;
     try {
         const decoded = Buffer.from(encoded, "base64");
-        // Round-trip guard: the backend uses `base64_decode($encoded, true) ?: $secret`,
-        // i.e. undecodable input falls back to the raw secret string.
+        // Round-trip guard: Queek's signer falls back to the raw secret string
+        // when the input is not strictly valid base64.
         if (decoded.length > 0 && decoded.toString("base64").replace(/=+$/, "") === encoded.replace(/=+$/, "")) {
             return decoded;
         }
@@ -36,26 +46,44 @@ export function secretKeyBytes(secret) {
         return Buffer.from(secret, "utf8");
     }
 }
-/** One `v1,<base64>` signature for one secret — mirrors `WebhookSigner::sign()`. */
+/** One `v1,<base64>` signature for one secret, in the format Queek sends. */
 export function signQueekPayload(eventId, timestamp, body, secret) {
     const mac = createHmac("sha256", secretKeyBytes(secret))
         .update(`${eventId}.${timestamp}.${body}`, "utf8")
         .digest();
     return `v1,${mac.toString("base64")}`;
 }
+/**
+ * True when one of the signatures in the header matches the body, and the
+ * timestamp is within the skew window. The compare is constant-time and
+ * covers every signature in the header (a secret rotation sends two).
+ *
+ * @example
+ * const ok = verifyQueekSignature({
+ *   id: request.headers.get("webhook-id") ?? "",
+ *   timestamp: request.headers.get("webhook-timestamp") ?? "",
+ *   signatureHeader: request.headers.get("webhook-signature") ?? "",
+ *   body: await request.text(), // the raw text, before any JSON.parse
+ *   secret: installation.webhookSecret,
+ * });
+ */
 export function verifyQueekSignature(input, options = {}) {
     return verifyQueekSignatureDetailed(input, options).ok;
 }
+/**
+ * Like {@link verifyQueekSignature}, but says why a delivery was rejected:
+ * `missing_headers`, `stale_timestamp` or `signature_mismatch`. Log the
+ * reason; answer 401 either way.
+ */
 export function verifyQueekSignatureDetailed(input, options = {}) {
     const { id, timestamp, body, signatureHeader, secret } = input;
     if (!id || !timestamp || !signatureHeader || !secret) {
         return { ok: false, reason: "missing_headers" };
     }
     if (!options.skipFreshnessCheck) {
-        const ts = Number(timestamp);
         const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
         const maxSkew = options.maxSkewSeconds ?? MAX_TIMESTAMP_SKEW_SECONDS;
-        if (!Number.isFinite(ts) || Math.abs(now - ts) > maxSkew) {
+        if (!isFreshTimestamp(timestamp, now, maxSkew)) {
             return { ok: false, reason: "stale_timestamp" };
         }
     }
@@ -71,4 +99,3 @@ export function verifyQueekSignatureDetailed(input, options = {}) {
     }
     return { ok: false, reason: "signature_mismatch" };
 }
-//# sourceMappingURL=signatures.js.map

package/dist/store.d.ts

@@ -1,26 +1,24 @@
 import { Pool } from "pg";
 /**
- * The app database holds INSTALLATIONS ONLY (decision
- * 2026-09-23-queek-apps-separate-ts-hono-codebase-public-surface-only).
- * Business data lives in Queek (product metafields,
- * orders.integrator_metadata) — never here.
+ * The app database holds INSTALLATIONS ONLY. Business data lives in Queek
+ * (for example in product metafields) — never here.
  *
- * S1 (SDK 0.2.0): no store-callable credential crosses the install handoff
- * any more, so there is no `api_key` column. The app mints short-lived
+ * No store-callable credential crosses the install handoff, so there is no
+ * `api_key` column. The app mints short-lived
  * installation tokens with its asymmetric app key and caches ONE token per
  * installation here (`token_enc` + `token_expires_at` + `token_kid`);
  * `webhook_secret` AND the whole `settings` blob stay encrypted at rest
  * (AES-256-GCM via node:crypto, key from `APP_ENCRYPTION_KEY`): manifests
- * may declare `secret` settings (API keys, webhook secrets) and the backend
+ * may declare `secret` settings (API keys, webhook secrets) and Queek
  * encrypts those too, so the SDK must not be weaker. NOTHING secret is ever
  * logged: only ids and the store p_id may appear in logs.
  */
 export interface InstallationRecord {
-    /** Queek installation id (string form of the backend UUID). */
+    /** Queek installation id (string form of the UUID). */
     installationId: string;
     /** Queek installation p_id (short public id, safe to log). */
     installationPid: string;
-    /** Vendor id (backend UUID, string form). */
+    /** Vendor id (UUID, string form). */
     vendorId: string;
     /** Store p_id (safe to log). */
     storePid: string | null;
@@ -54,9 +52,9 @@ export interface InstallationRecord {
     webhookSecret: string | null;
     /**
      * Plaintext per-installation proxy secret — memory only, persisted as
-     * `proxy_secret_enc`, null when the app has no proxy. Signs
-     * slot-claims (booking app); never logged (the logger redacts
-     * secret-named keys).
+     * `proxy_secret_enc`, null when the app has no proxy. Signs claims such
+     * as booking slot-claims; never logged (the logger redacts secret-named
+     * keys).
      */
     proxySecret: string | null;
     /**
@@ -76,6 +74,12 @@ export interface WebhookSecretCandidate {
     installationId: string;
     secret: string;
 }
+/**
+ * Where installations live. The SDK ships `SqliteInstallationStore` (local
+ * and test) and `PostgresInstallationStore` (production); both encrypt
+ * secrets at rest. Implement this interface to use another database, and
+ * keep `claimWebhookId` atomic: handlers rely on it to run each delivery once.
+ */
 export interface InstallationStore {
     saveInstallation(record: InstallationRecord): Promise<void> | void;
     getInstallation(installationId: string): Promise<InstallationRecord | null> | InstallationRecord | null;
@@ -152,19 +156,17 @@ export interface SqliteStoreOptions {
  * built-in `node:sqlite` (`DatabaseSync` — synchronous, file-backed, WAL
  * mode).
  *
- * Why not better-sqlite3: its prebuilt binary segfaults on the project's
- * Node 22.12 runtime (observed, not theorised), and building from source
- * would force a C++ toolchain into every environment — dev Macs, CI, and
- * the slim alpine app images. `node:sqlite` is dependency-free with an
- * identical synchronous shape.
+ * Why not better-sqlite3: its prebuilt binary segfaults on Node 22.12, and
+ * building from source would force a C++ toolchain into every environment
+ * — dev Macs, CI, and slim alpine images. `node:sqlite` is
+ * dependency-free with an identical synchronous shape.
  *
- * `node:sqlite` needs no flag since Node 22.13.0 (pinned runtime 22.23.3;
- * an ExperimentalWarning on stderr remains — Stability 1.1). Devs on an
- * older 22 minor set `NODE_OPTIONS=--experimental-sqlite` in their shell.
- * Revisit when the apps run on a Node line where it is fully stable — the
- * swap is contained here, behind `InstallationStore`.
+ * `node:sqlite` needs no flag since Node 22.13.0 (an ExperimentalWarning on
+ * stderr remains — Stability 1.1). Devs on an older 22 minor set
+ * `NODE_OPTIONS=--experimental-sqlite` in their shell. The swap to another
+ * driver is contained here, behind `InstallationStore`.
  *
- * 0.1.x → 0.2.0 upgrade: databases created by SDK 0.1.x carry a legacy
+ * Legacy upgrade: databases created by SDK 0.1.x carry a legacy
  * `api_key_enc` column (the handoff no longer delivers that key, so its
  * value is dead — minted tokens replace it; resync restores connectivity).
  * Opening such a database adds the token-cache columns and drops
@@ -195,8 +197,7 @@ export declare class SqliteInstallationStore implements InstallationStore {
 }
 /**
  * Canonical integer-string form of a Queek `p_id`: the handoff contract
- * types p_ids as strings and the backend casts on the wire, but the
- * tolerance stays — a JSON integer would reach here as a JS number, and
+ * types p_ids as strings, but the tolerance stays — a JSON integer would reach here as a JS number, and
  * `node:sqlite` binds that number into a TEXT column as `"1021.0"`, which
  * never equals the proxy `kid` (`"1021"`). Non-numeric pids pass through
  * untouched.
@@ -308,4 +309,3 @@ export interface InstallationStoreSelector {
  * container-local database).
  */
 export declare function createInstallationStore(options: InstallationStoreSelector): InstallationStore;
-//# sourceMappingURL=store.d.ts.map