@usequeek/app-sdk 0.4.0

package/dist/resync.js

@@ -0,0 +1,203 @@
+import { isInstallationGone, isInstallationPending, isResyncCooldown, RETRY_JITTER_MAX_MS, } from "./app-auth.js";
+import { QueekApiError, queekApiErrorFromResponse } from "./client.js";
+import { createLogger } from "./logger.js";
+import { resolveAppApiBase } from "./tokens.js";
+const MAX_LIST_ATTEMPTS = 3;
+const LIST_BACKOFF_BASE_MS = 250;
+const LIST_BACKOFF_MAX_MS = 5_000;
+/** Per-installation resync attempts before a retryable refusal is skipped or aborts the run. */
+const MAX_RESYNC_ATTEMPTS = 3;
+const RESYNC_BACKOFF_BASE_MS = 250;
+const RESYNC_BACKOFF_MAX_MS = 5_000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function resyncFromQueek(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const userAgent = options.userAgent ?? "queek-app/1.0";
+    const logger = options.logger ?? createLogger({ service: "queek-app-resync" });
+    const sleep = options.sleep ?? defaultSleep;
+    const random = options.random ?? Math.random;
+    const jittered = (baseMs) => baseMs + Math.floor(random() * RETRY_JITTER_MAX_MS);
+    const appBase = resolveAppApiBase(options.apiBase, options.allowedApiHosts ?? []);
+    async function appFetch(path, init) {
+        // Signed per attempt (never reused past its ≤10-min window, never logged).
+        const jwt = options.tokens.signJwt();
+        const headers = new Headers();
+        headers.set("Authorization", `Bearer ${jwt}`);
+        headers.set("Accept", "application/json");
+        headers.set("User-Agent", userAgent);
+        let response;
+        try {
+            response = await fetchImpl(`${appBase}${path}`, { method: init.method, headers });
+        }
+        catch (cause) {
+            throw new QueekApiError({
+                status: 0,
+                code: "network_error",
+                message: cause instanceof Error ? `Could not reach Queek: ${cause.message}` : "Could not reach Queek.",
+            });
+        }
+        return response;
+    }
+    /** Parse an app-endpoint failure without acting on it: the caller below
+     *  decides by status + code (pending/cooldown/throttle/gone/halt). */
+    async function readAppError(response) {
+        const text = await response.text();
+        const parsed = text === "" ? null : tryParseJson(text);
+        return queekApiErrorFromResponse(response.status, parsed, response.headers);
+    }
+    // -- List (opaque keyset cursor, secret-free) ------------------------------
+    // The cursor is never interpreted — echoed back verbatim until
+    // `next_cursor` is null (rev 8: keyset on a stable unique key, scoped to
+    // the calling app; inserts/uninstalls mid-walk never skip or duplicate).
+    const listed = [];
+    let cursor = null;
+    let attempt = 0;
+    let listDone = false;
+    while (!listDone) {
+        const path = cursor === null ? `/installations` : `/installations?cursor=${encodeURIComponent(cursor)}`;
+        let response;
+        try {
+            response = await appFetch(path, { method: "GET" });
+        }
+        catch (error) {
+            if (error instanceof QueekApiError &&
+                error.code === "network_error" &&
+                attempt < MAX_LIST_ATTEMPTS - 1) {
+                await sleep(jittered(Math.min(LIST_BACKOFF_MAX_MS, LIST_BACKOFF_BASE_MS * 2 ** attempt)));
+                attempt += 1;
+                continue;
+            }
+            throw error;
+        }
+        if (response.status === 429) {
+            if (attempt < MAX_LIST_ATTEMPTS - 1) {
+                const retryAfter = queekApiErrorFromResponse(429, null, response.headers).retryAfterMs;
+                await sleep(jittered(retryAfter ?? LIST_BACKOFF_BASE_MS));
+                attempt += 1;
+                continue;
+            }
+            throw queekApiErrorFromResponse(response.status, null, response.headers);
+        }
+        if (!response.ok || response.status !== 200) {
+            // 401/403 halt inside (invalid_client / kill switch); 404-gone is a
+            // no-op against the empty id; anything else propagates.
+            await options.tokens.handleAppEndpointError(await readAppError(response), { id: "", pid: "" });
+        }
+        const page = (await response.json());
+        for (const item of page.data ?? [])
+            listed.push(item);
+        attempt = 0; // a good page resets the backoff budget for the next page
+        cursor = typeof page.next_cursor === "string" && page.next_cursor !== "" ? page.next_cursor : null;
+        listDone = cursor === null;
+    }
+    // -- Resync each, drop cached tokens, purge the absent ----------------------
+    const result = {
+        listed: [],
+        resyncRequested: [],
+        cooldownSkipped: [],
+        pendingSkipped: [],
+        purged: [],
+    };
+    const listedIds = new Set();
+    for (const item of listed) {
+        listedIds.add(item.id);
+        result.listed.push(item.id);
+        const resyncPath = `/installations/${encodeURIComponent(item.id)}/resync`;
+        for (let attempt = 0;; attempt++) {
+            const response = await appFetch(resyncPath, { method: "POST" });
+            if (response.status === 202) {
+                result.resyncRequested.push(item.id);
+                await options.tokens.clearInstallationPending(item.id);
+                break;
+            }
+            const error = await readAppError(response);
+            if (response.status === 429 && isResyncCooldown(error.code)) {
+                // Rotation cooldown (≤1/hour): skip this installation, no retry loop.
+                result.cooldownSkipped.push(item.id);
+                logger.warn("queek resync skipped: rotation cooldown", { installation: item.id });
+                break;
+            }
+            if (response.status === 429) {
+                // Per-app bucket (rev 8): back off on `Retry-After` (jittered) and
+                // retry — never recorded as a cooldown skip. An exhausted budget
+                // aborts the run: the whole app is throttled, so pushing on would
+                // only deepen it; the caller retries later.
+                if (attempt >= MAX_RESYNC_ATTEMPTS - 1)
+                    throw error;
+                await sleep(jittered(error.retryAfterMs ?? RESYNC_BACKOFF_BASE_MS));
+                continue;
+            }
+            if (response.status === 409 && isInstallationPending(error.code)) {
+                // Pending installation (rev 8, mark persisted per B2 review r2):
+                // retry later with backoff — NEVER purge. An exhausted budget
+                // skips (recorded); the persisted mark survives restarts, so the
+                // purge-absent step below (and after a restart) keeps the row.
+                await options.tokens.markInstallationPending(item.id);
+                if (attempt >= MAX_RESYNC_ATTEMPTS - 1) {
+                    result.pendingSkipped.push(item.id);
+                    logger.warn("queek resync skipped: installation pending", { installation: item.id });
+                    break;
+                }
+                const backoff = Math.min(RESYNC_BACKOFF_MAX_MS, RESYNC_BACKOFF_BASE_MS * 2 ** attempt);
+                await sleep(jittered(backoff));
+                continue;
+            }
+            try {
+                // 404-gone purges inside; 401/403-halt throws the halted error; a
+                // 409 with any OTHER code rethrows here untouched (never purged).
+                await options.tokens.handleAppEndpointError(error, { id: item.id, pid: item.id });
+            }
+            catch (endpointError) {
+                // Gone server-side: the row is already purged inside — record it
+                // and keep going. Anything else (halt et al.) aborts the run.
+                if (endpointError instanceof QueekApiError &&
+                    endpointError.status === 404 &&
+                    isInstallationGone(endpointError.code)) {
+                    result.purged.push(item.id);
+                    break;
+                }
+                throw endpointError;
+            }
+        }
+    }
+    // Drop cached tokens for everything still listed (a post-outage token
+    // may be revoked server-side; the next call re-mints cleanly)…
+    for (const id of listedIds) {
+        await options.store.clearCachedToken(id);
+    }
+    // …and purge local rows Queek no longer lists (uninstall-while-down) —
+    // EXCEPT rows carrying the persisted pending mark. The list covers
+    // ACTIVE installations only (rev 8), so absence alone never purges a
+    // pending row — including after a process restart, because the mark
+    // lives in the store column, not in memory. The row stays for a later
+    // run, when it is active (listed + resynced), gone (404 → purged), or
+    // still pending (kept again).
+    const local = await options.store.listInstallations();
+    for (const row of local) {
+        if (!listedIds.has(row.installationId)) {
+            if (await options.tokens.isKnownPending(row.installationId)) {
+                logger.warn("queek resync kept a pending installation absent from Queek's list", {
+                    installation: row.installationPid,
+                });
+                continue;
+            }
+            await options.store.deleteInstallation(row.installationId);
+            result.purged.push(row.installationId);
+            logger.warn("queek resync purged an installation absent from Queek's list", {
+                installation: row.installationPid,
+            });
+        }
+    }
+    return result;
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 500) };
+    }
+}
+//# sourceMappingURL=resync.js.map

package/dist/resync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resync.js","sourceRoot":"","sources":["../src/resync.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server-only entry (S4 stage 2): session-token verification needs the
+ * per-installation `embsec_…` secret, which must never enter a browser
+ * bundle. Import the verifier from `@usequeek/app-sdk/server`, never from
+ * the main entry.
+ */
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,cAAc,CAAC"}

package/dist/server.js

@@ -0,0 +1,8 @@
+/**
+ * Server-only entry (S4 stage 2): session-token verification needs the
+ * per-installation `embsec_…` secret, which must never enter a browser
+ * bundle. Import the verifier from `@usequeek/app-sdk/server`, never from
+ * the main entry.
+ */
+export { EMBED_SECRET_PREFIX, SESSION_CLOCK_TOLERANCE_SECONDS, sessionTokenInstallationId, verifySessionToken, verifySessionTokenDetailed, } from "./session.js";
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,cAAc,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Dashboard session tokens (S4 stage 2): 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.
+ *
+ * Server-only: the secret must never enter a browser bundle, so this module
+ * ships behind the `./server` export, not the main entry. Style mirrors
+ * `signatures.ts` — a boolean fast path plus a detailed variant returning
+ * `{ ok } | { ok: false, reason }`.
+ */
+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). */
+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 {
+    installationId: string;
+    vendorId: string;
+    appSlug: string;
+    appId: string;
+    subject: string;
+    sessionId: string;
+    issuedAt: number;
+    expiresAt: number;
+}
+export interface SessionTokenBinding {
+    installationId: string;
+    vendorId: string;
+    appSlug: string;
+    appId: string;
+}
+export interface VerifySessionTokenOptions {
+    /** The per-installation `embsec_…` secret, raw UTF-8 bytes (never decoded). */
+    secret: string;
+    /** Single expected audience: the app slug. */
+    audience: string;
+    /** Expected issuer: the Queek api_base. */
+    issuer: string;
+    /**
+     * The installation row the token must belong to (the app backend'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()`.
+     */
+    expected: SessionTokenBinding;
+    clockToleranceSeconds?: number;
+}
+export declare function verifySessionToken(token: string, options: VerifySessionTokenOptions): Promise<boolean>;
+export declare function verifySessionTokenDetailed(token: string, options: VerifySessionTokenOptions): Promise<{
+    ok: true;
+    claims: SessionTokenClaims;
+} | {
+    ok: false;
+    reason: SessionTokenFailure;
+}>;
+/**
+ * ROUTING HINT ONLY — the `installation_id` claim read WITHOUT verifying
+ * anything, so a server can load the installation whose embed secret then
+ * verifies the token with `verifySessionToken`. Never trust it on its
+ * own: a caller that skips the verify has no authentication at all.
+ * 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,GACnB,SAAS,GACT,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC,CA2ChG;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvE"}

package/dist/session.js

@@ -0,0 +1,155 @@
+import { decodeJwt, decodeProtectedHeader, jwtVerify } from "jose";
+/**
+ * Dashboard session tokens (S4 stage 2): 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.
+ *
+ * Server-only: the secret must never enter a browser bundle, so this module
+ * ships behind the `./server` export, not the main entry. Style mirrors
+ * `signatures.ts` — a boolean fast path plus a detailed variant returning
+ * `{ ok } | { ok: false, reason }`.
+ */
+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). */
+export const SESSION_CLOCK_TOLERANCE_SECONDS = 20;
+export async function verifySessionToken(token, options) {
+    const result = await verifySessionTokenDetailed(token, options);
+    return result.ok;
+}
+export async function verifySessionTokenDetailed(token, options) {
+    if (!token) {
+        return { ok: false, reason: "missing_token" };
+    }
+    const { secret, audience, issuer } = options;
+    if (!secret?.startsWith(EMBED_SECRET_PREFIX)) {
+        return { ok: false, reason: "missing_secret" };
+    }
+    // Fail closed on the algorithm before jose sees the token: a foreign alg
+    // (none, RS256, …) is rejected here with wrong_algorithm regardless of
+    // how jose shapes the downstream error (key-type TypeError vs
+    // JOSEAlgNotAllowed). An undecodable header falls through to jwtVerify,
+    // which rejects it as invalid_signature.
+    const headerAlg = readTokenAlg(token);
+    if (headerAlg !== null && headerAlg !== SESSION_TOKEN_ALG) {
+        return { ok: false, reason: "wrong_algorithm" };
+    }
+    let payload;
+    try {
+        const verified = await jwtVerify(token, new TextEncoder().encode(secret), {
+            algorithms: ["HS256"],
+            audience,
+            issuer,
+            clockTolerance: options.clockToleranceSeconds ?? SESSION_CLOCK_TOLERANCE_SECONDS,
+        });
+        payload = verified.payload;
+    }
+    catch (error) {
+        return { ok: false, reason: classifyJoseError(error) };
+    }
+    const claims = readSessionClaims(payload);
+    const { expected } = options;
+    if (!claims ||
+        claims.installationId !== expected.installationId ||
+        claims.vendorId !== expected.vendorId ||
+        claims.appSlug !== expected.appSlug ||
+        claims.appId !== expected.appId) {
+        return { ok: false, reason: "binding_mismatch" };
+    }
+    return { ok: true, claims };
+}
+/**
+ * ROUTING HINT ONLY — the `installation_id` claim read WITHOUT verifying
+ * anything, so a server can load the installation whose embed secret then
+ * verifies the token with `verifySessionToken`. Never trust it on its
+ * own: a caller that skips the verify has no authentication at all.
+ * Null for anything that is not a decodable JWT carrying the claim.
+ */
+export function sessionTokenInstallationId(token) {
+    try {
+        const claim = decodeJwt(token).installation_id;
+        return typeof claim === "string" && claim.length > 0 ? claim : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The token's `alg` without verifying anything. Returns null when the
+ * header is missing or undecodable, so malformed tokens keep flowing to
+ * jwtVerify (invalid_signature) instead of being mislabelled.
+ */
+function readTokenAlg(token) {
+    try {
+        const alg = decodeProtectedHeader(token).alg;
+        return typeof alg === "string" ? alg : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSessionClaims(payload) {
+    const pick = (key) => typeof payload[key] === "string" && payload[key].length > 0 ? payload[key] : null;
+    const installationId = pick("installation_id");
+    const vendorId = pick("vendor_id");
+    const appSlug = pick("app_slug");
+    const appId = pick("app_id");
+    const subject = typeof payload.sub === "string" ? payload.sub : null;
+    const sessionId = pick("sid");
+    const issuedAt = typeof payload.iat === "number" ? payload.iat : null;
+    const expiresAt = typeof payload.exp === "number" ? payload.exp : null;
+    if (!installationId ||
+        !vendorId ||
+        !appSlug ||
+        !appId ||
+        !subject ||
+        !sessionId ||
+        issuedAt === null ||
+        expiresAt === null) {
+        return null;
+    }
+    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
+    // 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 —
+    // the header pre-check fails closed first). Anything else — JWSInvalid,
+    // JWSSignatureVerificationFailed, key TypeErrors, garbage input — is an
+    // invalid signature. No fuzzy matching: a renamed jose error must fall
+    // through loudly, not hide behind a regex.
+    const shaped = error;
+    const claim = typeof shaped?.claim === "string" ? shaped.claim : "";
+    if (claim === "exp") {
+        return "expired";
+    }
+    if (claim === "nbf") {
+        return "not_yet_valid";
+    }
+    if (claim === "aud") {
+        return "wrong_audience";
+    }
+    if (claim === "iss") {
+        return "wrong_issuer";
+    }
+    const code = typeof shaped?.code === "string" ? shaped.code : "";
+    if (code === "ERR_JWT_EXPIRED") {
+        return "expired";
+    }
+    if (code === "ERR_JOSE_ALG_NOT_ALLOWED") {
+        return "wrong_algorithm";
+    }
+    const name = typeof shaped?.name === "string" ? shaped.name : "";
+    if (name === "JWTExpired") {
+        return "expired";
+    }
+    if (name === "JOSEAlgNotAllowed") {
+        return "wrong_algorithm";
+    }
+    return "invalid_signature";
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/signatures.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Standard Webhooks verification, byte-for-byte compatible with Queek's
+ * `App\Services\Webhooks\WebhookSigner` (queek_backend).
+ *
+ * Signed content: `{id}.{timestamp}.{body}` where `body` is the RAW request
+ * bytes. Re-serialising JSON before verifying breaks the MAC — verify first,
+ * parse second.
+ *
+ * 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()`.
+ *
+ * Header names: `webhook-id`, `webhook-timestamp`, `webhook-signature`.
+ * The signature header may carry several space-delimited `v1,<base64>`
+ * signatures (rotation grace window): ANY match verifies.
+ */
+export declare const WEBHOOK_ID_HEADER = "webhook-id";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+export declare const SECRET_PREFIX = "whsec_";
+/** Maximum age of a delivery before it is rejected as stale (5 minutes, the Standard Webhooks default). */
+export declare const MAX_TIMESTAMP_SKEW_SECONDS: number;
+export interface SignatureInput {
+    /** Value of the `webhook-id` header. */
+    id: string;
+    /** Value of the `webhook-timestamp` header (unix seconds, as sent). */
+    timestamp: string;
+    /** Raw request body bytes, untouched. */
+    body: string;
+    /** Value of the `webhook-signature` header (one or more space-delimited signatures). */
+    signatureHeader: string;
+    /** The endpoint/app `whsec_…` secret. */
+    secret: string;
+}
+export interface VerifyOptions {
+    /** Unix seconds to judge freshness against (defaults to now). Exposed for tests. */
+    nowSeconds?: number;
+    /** Allowed clock skew in seconds (defaults to MAX_TIMESTAMP_SKEW_SECONDS). */
+    maxSkewSeconds?: number;
+    /** Skip the freshness check (NOT recommended; exposed for replaying stored fixtures). */
+    skipFreshnessCheck?: boolean;
+}
+export declare function secretKeyBytes(secret: string): Buffer;
+/** One `v1,<base64>` signature for one secret — mirrors `WebhookSigner::sign()`. */
+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";
+export declare function verifyQueekSignature(input: SignatureInput, options?: VerifyOptions): boolean;
+export declare function verifyQueekSignatureDetailed(input: SignatureInput, options?: VerifyOptions): {
+    ok: true;
+} | {
+    ok: false;
+    reason: SignatureFailure;
+};
+//# sourceMappingURL=signatures.d.ts.map

package/dist/signatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signatures.d.ts","sourceRoot":"","sources":["../src/signatures.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAC5D,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAC5D,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,2GAA2G;AAC3G,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAarD;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAKR;AAED,2DAA2D;AAC3D,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAE5F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAEhG;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,aAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAyBxD"}

package/dist/signatures.js

@@ -0,0 +1,74 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Standard Webhooks verification, byte-for-byte compatible with Queek's
+ * `App\Services\Webhooks\WebhookSigner` (queek_backend).
+ *
+ * Signed content: `{id}.{timestamp}.{body}` where `body` is the RAW request
+ * bytes. Re-serialising JSON before verifying breaks the MAC — verify first,
+ * parse second.
+ *
+ * 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()`.
+ *
+ * Header names: `webhook-id`, `webhook-timestamp`, `webhook-signature`.
+ * The signature header may carry several space-delimited `v1,<base64>`
+ * signatures (rotation grace window): ANY match verifies.
+ */
+export const WEBHOOK_ID_HEADER = "webhook-id";
+export const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+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;
+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.
+        if (decoded.length > 0 && decoded.toString("base64").replace(/=+$/, "") === encoded.replace(/=+$/, "")) {
+            return decoded;
+        }
+        return Buffer.from(secret, "utf8");
+    }
+    catch {
+        return Buffer.from(secret, "utf8");
+    }
+}
+/** One `v1,<base64>` signature for one secret — mirrors `WebhookSigner::sign()`. */
+export function signQueekPayload(eventId, timestamp, body, secret) {
+    const mac = createHmac("sha256", secretKeyBytes(secret))
+        .update(`${eventId}.${timestamp}.${body}`, "utf8")
+        .digest();
+    return `v1,${mac.toString("base64")}`;
+}
+export function verifyQueekSignature(input, options = {}) {
+    return verifyQueekSignatureDetailed(input, options).ok;
+}
+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) {
+            return { ok: false, reason: "stale_timestamp" };
+        }
+    }
+    const expected = signQueekPayload(id, timestamp, body, secret);
+    const expectedBuf = Buffer.from(expected, "utf8");
+    for (const candidate of signatureHeader.trim().split(/\s+/)) {
+        if (candidate === "")
+            continue;
+        const candidateBuf = Buffer.from(candidate, "utf8");
+        if (candidateBuf.length === expectedBuf.length && timingSafeEqual(candidateBuf, expectedBuf)) {
+            return { ok: true };
+        }
+    }
+    return { ok: false, reason: "signature_mismatch" };
+}
+//# sourceMappingURL=signatures.js.map

package/dist/signatures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signatures.js","sourceRoot":"","sources":["../src/signatures.ts"],"names":[],"mappings":"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"}