@cboxdk/id-js 0.17.0 → 0.18.0

package/dist/chunk-QQW63PGU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/issuer.ts"],"names":[],"mappings":";;;AAaO,SAAS,mBAAmB,MAAA,EAAsB;AACvD,EAAA,IAAI,GAAA;AAEJ,EAAA,IAAI;AACF,IAAA,GAAA,GAAM,IAAI,IAAI,MAAM,CAAA;AAAA,EACtB,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,mBAAmB,6CAA6C,CAAA;AAAA,EAC5E;AAEA,EAAA,IAAI,GAAA,CAAI,aAAa,QAAA,EAAU;AAC7B,IAAA;AAAA,EACF;AAEA,EAAA,MAAM,QAAA,GAAW,GAAA,CAAI,QAAA,KAAa,WAAA,IAAe,GAAA,CAAI,QAAA,KAAa,WAAA,IAAe,GAAA,CAAI,QAAA,KAAa,OAAA,IAAW,GAAA,CAAI,QAAA,KAAa,KAAA;AAE9H,EAAA,IAAI,GAAA,CAAI,QAAA,KAAa,OAAA,IAAW,QAAA,EAAU;AACxC,IAAA;AAAA,EACF;AAEA,EAAA,MAAM,IAAI,kBAAA;AAAA,IACR,CAAA,6CAAA,EAAgD,GAAA,CAAI,QAAQ,CAAA,EAAA,EAAK,IAAI,QAAQ,CAAA,EAAA;AAAA,GAC/E;AACF","file":"chunk-QQW63PGU.js","sourcesContent":["import { ConfigurationError } from './errors.js';\n\n/**\n * An issuer must be HTTPS.\n *\n * Everything this SDK does with it carries a credential: the authorization code, the PKCE\n * verifier, the client secret, the refresh token. Over `http://` a network attacker reads\n * all of them — and, worse, replaces the discovery document and JWKS, at which point a\n * forged id_token verifies cleanly and the whole verification chain proves nothing.\n *\n * Loopback is allowed because a native app's own callback listener is loopback by\n * definition (RFC 8252) and a dev instance runs there.\n */\nexport function assertSecureIssuer(issuer: string): void {\n  let url: URL;\n\n  try {\n    url = new URL(issuer);\n  } catch {\n    throw new ConfigurationError('Cbox ID config `issuer` is not a valid URL.');\n  }\n\n  if (url.protocol === 'https:') {\n    return;\n  }\n\n  const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]' || url.hostname === '::1';\n\n  if (url.protocol === 'http:' && loopback) {\n    return;\n  }\n\n  throw new ConfigurationError(\n    `Cbox ID config \\`issuer\\` must be https (got ${url.protocol}//${url.hostname}).`,\n  );\n}\n"]}

package/dist/{chunk-ASOQN47M.js → chunk-SEUD4TE4.js}

@@ -56,26 +56,6 @@ var FrontendApiError = class extends CboxIdError {
   retryAfter;
 };
 
-// src/issuer.ts
-function assertSecureIssuer(issuer) {
-  let url;
-  try {
-    url = new URL(issuer);
-  } catch {
-    throw new ConfigurationError("Cbox ID config `issuer` is not a valid URL.");
-  }
-  if (url.protocol === "https:") {
-    return;
-  }
-  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
-  if (url.protocol === "http:" && loopback) {
-    return;
-  }
-  throw new ConfigurationError(
-    `Cbox ID config \`issuer\` must be https (got ${url.protocol}//${url.hostname}).`
-  );
-}
-
-export { AuthenticationError, CboxIdError, ConfigurationError, FrontendApiError, InvalidStateError, assertSecureIssuer, oauthError };
-//# sourceMappingURL=chunk-ASOQN47M.js.map
-//# sourceMappingURL=chunk-ASOQN47M.js.map
+export { AuthenticationError, CboxIdError, ConfigurationError, FrontendApiError, InvalidStateError, oauthError };
+//# sourceMappingURL=chunk-SEUD4TE4.js.map
+//# sourceMappingURL=chunk-SEUD4TE4.js.map

package/dist/chunk-SEUD4TE4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AAIO,IAAM,WAAA,GAAN,cAA0B,KAAA,CAAM;AAAA,EACrC,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,OAAO,GAAA,CAAA,MAAA,CAAW,IAAA;AAAA,EACzB;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,WAAA,CAAY;AAAC;AAM9C,IAAM,iBAAA,GAAN,cAAgC,WAAA,CAAY;AAAC;AAa7C,IAAM,mBAAA,GAAN,cAAkC,WAAA,CAAY;AAAA,EACnD,WAAA,CACE,OAAA,EAES,KAAA,EAEA,gBAAA,EAEA,QAUA,UAAA,EACT;AACA,IAAA,KAAA,CAAM,OAAO,CAAA;AAhBJ,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA;AAEA,IAAA,IAAA,CAAA,gBAAA,GAAA,gBAAA;AAEA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAUA,IAAA,IAAA,CAAA,UAAA,GAAA,UAAA;AAAA,EAGX;AAAA,EAjBW,KAAA;AAAA,EAEA,gBAAA;AAAA,EAEA,MAAA;AAAA,EAUA,UAAA;AAAA;AAAA,EAMX,IAAI,aAAA,GAAyB;AAC3B,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AACF;AAUA,eAAsB,UAAA,CAAW,UAAoB,QAAA,EAAgD;AACnG,EAAA,MAAM,OAAO,MAAM,QAAA,CAAS,MAAK,CAAE,KAAA,CAAM,MAAM,EAAE,CAAA;AAEjD,EAAA,IAAI,IAAA;AACJ,EAAA,IAAI,WAAA;AAEJ,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAkB,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA;AAEvC,IAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,KAAW,IAAA,EAAM;AACjD,MAAA,MAAM,EAAE,KAAA,EAAO,iBAAA,EAAmB,gBAAA,EAAiB,GAAI,MAAA;AACvD,MAAA,IAAA,GAAO,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,GAAQ,KAAA,CAAA;AAC3C,MAAA,WAAA,GAAc,OAAO,gBAAA,KAAqB,QAAA,GAAW,gBAAA,GAAmB,KAAA,CAAA;AAAA,IAC1E;AAAA,EACF,CAAA,CAAA,MAAQ;AAAA,EAER;AAOA,EAAA,MAAM,MAAA,GAAS,IAAA,IAAQ,CAAA,KAAA,EAAQ,QAAA,CAAS,MAAM,CAAA,CAAA;AAM9C,EAAA,MAAM,gBAAA,GAAmB,QAAA,CAAS,OAAA,CAAQ,GAAA,CAAI,aAAa,CAAA;AAC3D,EAAA,MAAM,UAAA,GAAa,gBAAA,KAAqB,IAAA,IAAQ,OAAA,CAAQ,IAAA,CAAK,gBAAA,CAAiB,IAAA,EAAM,CAAA,GAChF,MAAA,CAAO,gBAAA,CAAiB,IAAA,EAAM,CAAA,GAC9B,MAAA;AAEJ,EAAA,OAAO,IAAI,mBAAA,CAAoB,CAAA,EAAG,QAAQ,CAAA,EAAA,EAAK,MAAM,CAAA,CAAA,EAAI,IAAA,EAAM,WAAA,EAAa,QAAA,CAAS,MAAA,EAAQ,UAAU,CAAA;AACzG;AAiBO,IAAM,gBAAA,GAAN,cAA+B,WAAA,CAAY;AAAA,EAChD,WAAA,CACE,OAAA,EACS,IAAA,EACA,MAAA,EACA,UAAA,EACT;AACA,IAAA,KAAA,CAAM,OAAO,CAAA;AAJJ,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,UAAA,GAAA,UAAA;AAAA,EAGX;AAAA,EALW,IAAA;AAAA,EACA,MAAA;AAAA,EACA,UAAA;AAIb","file":"chunk-SEUD4TE4.js","sourcesContent":["/**\n * Base class for every error this SDK throws, so callers can `catch (e) { if (e\n * instanceof CboxIdError) ... }` in one branch.\n */\nexport class CboxIdError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = new.target.name;\n  }\n}\n\n/** The client is misconfigured (a required option is missing or empty). */\nexport class ConfigurationError extends CboxIdError {}\n\n/**\n * The login `state` did not match what was stored — the callback is forged or\n * stale. Treat as a fresh start, not an error to surface to the user.\n */\nexport class InvalidStateError extends CboxIdError {}\n\n/**\n * Login could not be completed: the provider returned an error, the callback was\n * missing a code, or a token / id_token failed verification.\n *\n * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.\n * It used to be discarded at every back-channel boundary, leaving a single message string\n * for outcomes that need opposite responses: `invalid_grant` on a refresh means the\n * session is over and the person has to sign in again, while `temporarily_unavailable`\n * means try the same token in a moment. A caller reduced to matching on prose either\n * retries what can never succeed, or signs out somebody who did not need to be.\n */\nexport class AuthenticationError extends CboxIdError {\n  constructor(\n    message: string,\n    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */\n    readonly error?: string,\n    /** The server's `error_description`, verbatim. Not end-user copy. */\n    readonly errorDescription?: string,\n    /** HTTP status, for the cases where the body says nothing useful. */\n    readonly status?: number,\n    /**\n     * Seconds to wait, off the `Retry-After` header — set only on a 429.\n     *\n     * The distinction it carries is the one a caller most needs and could least infer:\n     * a 429 is the ONLY back-channel failure where the same request will succeed\n     * unchanged if you simply wait. Every other one needs a different request, or a new\n     * sign-in. Without this the SDK reported \"token refresh failed\" and a caller with a\n     * retry loop hammered a limiter that was already telling it exactly how long to stop.\n     */\n    readonly retryAfter?: number,\n  ) {\n    super(message);\n  }\n\n  /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */\n  get isRateLimited(): boolean {\n    return this.status === 429;\n  }\n}\n\n/**\n * Read an OAuth error out of a failed token-endpoint response.\n *\n * Best-effort by design: a 502 from a proxy is HTML, a captive portal is worse, and the\n * caller still needs an error rather than a parse exception. What it must never do is\n * invent a code — an absent or unparseable `error` stays undefined, so\n * `e.error === 'invalid_grant'` is true only because the server said so.\n */\nexport async function oauthError(response: Response, fallback: string): Promise<AuthenticationError> {\n  const body = await response.text().catch(() => '');\n\n  let code: string | undefined;\n  let description: string | undefined;\n\n  try {\n    const parsed: unknown = JSON.parse(body);\n\n    if (typeof parsed === 'object' && parsed !== null) {\n      const { error, error_description: errorDescription } = parsed as Record<string, unknown>;\n      code = typeof error === 'string' ? error : undefined;\n      description = typeof errorDescription === 'string' ? errorDescription : undefined;\n    }\n  } catch {\n    // Not JSON. The status and the truncated body below are all there is to report.\n  }\n\n  // THE BODY IS NEVER ECHOED. These calls carry `client_secret`, `code_verifier` and\n  // refresh tokens in their REQUEST, and a debug proxy, a captive portal or an upstream\n  // error page that reflects what it received puts those straight into a thrown message\n  // — which production apps log. Only the server's own OAuth error code travels, and\n  // failing that, the status alone.\n  const detail = code ?? `HTTP ${response.status}`;\n\n  // `Retry-After` is seconds here — Laravel's throttler writes the integer form. The\n  // HTTP-date form is legal too and is deliberately NOT parsed: guessing at a clock\n  // skew is worse than saying nothing, and `status === 429` still tells the caller to\n  // back off.\n  const retryAfterHeader = response.headers.get('retry-after');\n  const retryAfter = retryAfterHeader !== null && /^\\d+$/.test(retryAfterHeader.trim())\n    ? Number(retryAfterHeader.trim())\n    : undefined;\n\n  return new AuthenticationError(`${fallback}: ${detail}`, code, description, response.status, retryAfter);\n}\n\n/**\n * The Frontend API refused, or could not be reached.\n *\n * Carries a `code` because the four ways this goes wrong need four different responses\n * from the caller, and telling them apart from a message string is the kind of thing\n * that works until somebody rewords the message:\n *\n *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a\n *    configuration problem the developer fixes once in the console.\n *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.\n *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.\n *  - `malformed` — a 200 whose body is not the document we expect, which means something\n *    between the page and us is rewriting responses (a proxy, an extension, a captive\n *    portal). Worth distinguishing, because retrying it never helps.\n */\nexport class FrontendApiError extends CboxIdError {\n  constructor(\n    message: string,\n    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed',\n    readonly status?: number,\n    readonly retryAfter?: number,\n  ) {\n    super(message);\n  }\n}\n"]}

package/dist/{client-CdwdigzG.d.ts → client-BSZASrMo.d.ts}

@@ -78,6 +78,34 @@ interface VerifyWebhookOptions {
 }
 /** Returns `true` only when the signature is present, fresh and valid. Never throws. */
 declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+/** Headers as a `Headers` object or a plain record (Node's `IncomingHttpHeaders`, a framework's map). */
+type WebhookHeaders = Headers | Record<string, string | readonly string[] | undefined>;
+interface VerifyStandardWebhookOptions {
+    /** The RAW request body — the exact bytes received, not a re-encoded copy. */
+    payload: string;
+    /** The request headers; `webhook-id`, `webhook-timestamp` and `webhook-signature` are read. */
+    headers: WebhookHeaders;
+    /**
+     * The endpoint's secret: a `whsec_…` secret, or the 64-hex secret of an endpoint that
+     * moved from the `cbox` scheme (Cbox ID uses it as `whsec_` + base64 of the hex string,
+     * which keys the HMAC with the same bytes).
+     */
+    secret: string;
+    /** Freshness window in seconds. Defaults to 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** Injectable clock (unix seconds), for tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Verify a delivery from an endpoint on the `standard_webhooks` signature scheme
+ * ([Standard Webhooks](https://www.standardwebhooks.com/)): `webhook-signature` carries one or
+ * more space-separated `v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">`,
+ * and the timestamp must be within the freshness window. Use {@link verifyWebhook} for the
+ * default `cbox` scheme (`X-Cbox-Signature`).
+ *
+ * Returns `true` only when a signature is present, fresh and valid. Never throws.
+ */
+declare function verifyStandardWebhook(options: VerifyStandardWebhookOptions): Promise<boolean>;
 
 /** Query parameters as they arrive on your callback route. */
 interface CallbackParams {
@@ -310,4 +338,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyWebhookOptions as e, verifyWebhook as v };
+export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };

package/dist/{client-CEXddiCR.d.cts → client-BxUHm5hX.d.cts}

@@ -78,6 +78,34 @@ interface VerifyWebhookOptions {
 }
 /** Returns `true` only when the signature is present, fresh and valid. Never throws. */
 declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+/** Headers as a `Headers` object or a plain record (Node's `IncomingHttpHeaders`, a framework's map). */
+type WebhookHeaders = Headers | Record<string, string | readonly string[] | undefined>;
+interface VerifyStandardWebhookOptions {
+    /** The RAW request body — the exact bytes received, not a re-encoded copy. */
+    payload: string;
+    /** The request headers; `webhook-id`, `webhook-timestamp` and `webhook-signature` are read. */
+    headers: WebhookHeaders;
+    /**
+     * The endpoint's secret: a `whsec_…` secret, or the 64-hex secret of an endpoint that
+     * moved from the `cbox` scheme (Cbox ID uses it as `whsec_` + base64 of the hex string,
+     * which keys the HMAC with the same bytes).
+     */
+    secret: string;
+    /** Freshness window in seconds. Defaults to 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** Injectable clock (unix seconds), for tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Verify a delivery from an endpoint on the `standard_webhooks` signature scheme
+ * ([Standard Webhooks](https://www.standardwebhooks.com/)): `webhook-signature` carries one or
+ * more space-separated `v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">`,
+ * and the timestamp must be within the freshness window. Use {@link verifyWebhook} for the
+ * default `cbox` scheme (`X-Cbox-Signature`).
+ *
+ * Returns `true` only when a signature is present, fresh and valid. Never throws.
+ */
+declare function verifyStandardWebhook(options: VerifyStandardWebhookOptions): Promise<boolean>;
 
 /** Query parameters as they arrive on your callback route. */
 interface CallbackParams {
@@ -310,4 +338,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyWebhookOptions as e, verifyWebhook as v };
+export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };

package/dist/errors-D61xljZE.d.cts

@@ -0,0 +1,87 @@
+/**
+ * Base class for every error this SDK throws, so callers can `catch (e) { if (e
+ * instanceof CboxIdError) ... }` in one branch.
+ */
+declare class CboxIdError extends Error {
+    constructor(message: string);
+}
+/** The client is misconfigured (a required option is missing or empty). */
+declare class ConfigurationError extends CboxIdError {
+}
+/**
+ * The login `state` did not match what was stored — the callback is forged or
+ * stale. Treat as a fresh start, not an error to surface to the user.
+ */
+declare class InvalidStateError extends CboxIdError {
+}
+/**
+ * Login could not be completed: the provider returned an error, the callback was
+ * missing a code, or a token / id_token failed verification.
+ *
+ * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.
+ * It used to be discarded at every back-channel boundary, leaving a single message string
+ * for outcomes that need opposite responses: `invalid_grant` on a refresh means the
+ * session is over and the person has to sign in again, while `temporarily_unavailable`
+ * means try the same token in a moment. A caller reduced to matching on prose either
+ * retries what can never succeed, or signs out somebody who did not need to be.
+ */
+declare class AuthenticationError extends CboxIdError {
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    readonly error?: string | undefined;
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    readonly errorDescription?: string | undefined;
+    /** HTTP status, for the cases where the body says nothing useful. */
+    readonly status?: number | undefined;
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    error?: string | undefined, 
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    errorDescription?: string | undefined, 
+    /** HTTP status, for the cases where the body says nothing useful. */
+    status?: number | undefined, 
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    retryAfter?: number | undefined);
+    /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
+    get isRateLimited(): boolean;
+}
+/**
+ * The Frontend API refused, or could not be reached.
+ *
+ * Carries a `code` because the four ways this goes wrong need four different responses
+ * from the caller, and telling them apart from a message string is the kind of thing
+ * that works until somebody rewords the message:
+ *
+ *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a
+ *    configuration problem the developer fixes once in the console.
+ *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.
+ *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.
+ *  - `malformed` — a 200 whose body is not the document we expect, which means something
+ *    between the page and us is rewriting responses (a proxy, an extension, a captive
+ *    portal). Worth distinguishing, because retrying it never helps.
+ */
+declare class FrontendApiError extends CboxIdError {
+    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed';
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed', status?: number | undefined, retryAfter?: number | undefined);
+}
+
+export { AuthenticationError as A, CboxIdError as C, FrontendApiError as F, InvalidStateError as I, ConfigurationError as a };

package/dist/errors-D61xljZE.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Base class for every error this SDK throws, so callers can `catch (e) { if (e
+ * instanceof CboxIdError) ... }` in one branch.
+ */
+declare class CboxIdError extends Error {
+    constructor(message: string);
+}
+/** The client is misconfigured (a required option is missing or empty). */
+declare class ConfigurationError extends CboxIdError {
+}
+/**
+ * The login `state` did not match what was stored — the callback is forged or
+ * stale. Treat as a fresh start, not an error to surface to the user.
+ */
+declare class InvalidStateError extends CboxIdError {
+}
+/**
+ * Login could not be completed: the provider returned an error, the callback was
+ * missing a code, or a token / id_token failed verification.
+ *
+ * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.
+ * It used to be discarded at every back-channel boundary, leaving a single message string
+ * for outcomes that need opposite responses: `invalid_grant` on a refresh means the
+ * session is over and the person has to sign in again, while `temporarily_unavailable`
+ * means try the same token in a moment. A caller reduced to matching on prose either
+ * retries what can never succeed, or signs out somebody who did not need to be.
+ */
+declare class AuthenticationError extends CboxIdError {
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    readonly error?: string | undefined;
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    readonly errorDescription?: string | undefined;
+    /** HTTP status, for the cases where the body says nothing useful. */
+    readonly status?: number | undefined;
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    error?: string | undefined, 
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    errorDescription?: string | undefined, 
+    /** HTTP status, for the cases where the body says nothing useful. */
+    status?: number | undefined, 
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    retryAfter?: number | undefined);
+    /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
+    get isRateLimited(): boolean;
+}
+/**
+ * The Frontend API refused, or could not be reached.
+ *
+ * Carries a `code` because the four ways this goes wrong need four different responses
+ * from the caller, and telling them apart from a message string is the kind of thing
+ * that works until somebody rewords the message:
+ *
+ *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a
+ *    configuration problem the developer fixes once in the console.
+ *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.
+ *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.
+ *  - `malformed` — a 200 whose body is not the document we expect, which means something
+ *    between the page and us is rewriting responses (a proxy, an extension, a captive
+ *    portal). Worth distinguishing, because retrying it never helps.
+ */
+declare class FrontendApiError extends CboxIdError {
+    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed';
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed', status?: number | undefined, retryAfter?: number | undefined);
+}
+
+export { AuthenticationError as A, CboxIdError as C, FrontendApiError as F, InvalidStateError as I, ConfigurationError as a };

package/dist/index.cjs

@@ -106,12 +106,12 @@ function createLegacyVerifier(options) {
     );
   };
 }
-async function isSignedByCboxId(body, header, secret, toleranceSeconds) {
-  if (!header) {
+async function isSignedByCboxId(body, header2, secret, toleranceSeconds) {
+  if (!header2) {
     return false;
   }
   const parts = {};
-  for (const piece of header.split(",")) {
+  for (const piece of header2.split(",")) {
     const [key2, value] = piece.split("=", 2);
     if (key2 && value) {
       parts[key2.trim()] = value.trim();
@@ -766,6 +766,58 @@ async function verifyWebhook(options) {
   );
   return timingSafeEqual2(expected, signature);
 }
+function header(headers, name) {
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    return headers.get(name) ?? void 0;
+  }
+  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.join(" ") : value;
+}
+function base64ToBytes(value) {
+  try {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+function toBase64(bytes) {
+  let binary = "";
+  for (const byte of new Uint8Array(bytes)) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+async function verifyStandardWebhook(options) {
+  const { payload, headers, secret } = options;
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  const id = header(headers, "webhook-id");
+  const timestamp = header(headers, "webhook-timestamp");
+  const signatures = header(headers, "webhook-signature");
+  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) {
+    return false;
+  }
+  if (Math.abs(now - Number(timestamp)) > toleranceSeconds) {
+    return false;
+  }
+  const keyBytes = secret.startsWith("whsec_") ? base64ToBytes(secret.slice("whsec_".length)) : new TextEncoder().encode(secret);
+  if (keyBytes === null || keyBytes.length === 0) {
+    return false;
+  }
+  const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const expected = toBase64(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${id}.${timestamp}.${payload}`)));
+  let valid = false;
+  for (const candidate of signatures.split(" ")) {
+    const [version, signature] = candidate.split(",", 2);
+    if (version === "v1" && signature !== void 0 && timingSafeEqual2(expected, signature)) {
+      valid = true;
+    }
+  }
+  return valid;
+}
 
 // src/client.ts
 var CboxIdClient = class {
@@ -1659,6 +1711,7 @@ exports.publishManifest = publishManifest;
 exports.randomToken = randomToken;
 exports.roles = roles;
 exports.sessionId = sessionId;
+exports.verifyStandardWebhook = verifyStandardWebhook;
 exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map