@hostwebhook/platform-node 0.2.0 → 0.3.0

package/dist/presets-de-oauth/shopify-oauth-presets.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Shopify OAuth 2.0 configuration for HostWebhook.
+ *
+ * The app is registered in the **Dev Dashboard** (<https://dev.shopify.com/dashboard/>),
+ * not in the Partner Dashboard and not in a store's admin — both of those
+ * paths are dead: admin-created custom apps stopped being creatable on
+ * 2026-01-01. The redirect URL is
+ * `{API_URL}/api/credentials/shopify/oauth/callback`.
+ *
+ * See `docs/ADR-0007-shopify.md` for why this app uses **custom
+ * distribution**, which is the decision most of the notes below hang off.
+ *
+ * ## Three things that make Shopify unlike every other provider here
+ *
+ * **The store is part of the host.** Calls go to
+ * `https://{shop}.myshopify.com/admin/api/{version}/graphql.json`, and so does
+ * the authorization URL. That is worse than Mailchimp's `dc`, which at least
+ * arrives from Mailchimp: here the shop is **typed by the user before the flow
+ * starts**, so it is attacker-influenced input that we then put in a URL. It
+ * is validated twice — in the DTO and again here — against Shopify's own
+ * anchored pattern, and every call goes through `fetchSeguro`.
+ *
+ * **The callback is signed, and checking it is not optional.** Shopify appends
+ * an `hmac` over the rest of the query string. Skipping that check would let
+ * anyone hit our public callback with a `shop` of their choosing.
+ *
+ * **Tokens may or may not expire, and which one you get is a property of the
+ * app, not of the code.** Apps with *public* distribution created on or after
+ * 2026-04-01 must use expiring offline tokens (1 h access, 90-day refresh);
+ * apps with custom distribution are exempt and get a token that lives until
+ * the app is uninstalled. Ours is custom, so today no expiry arrives.
+ *
+ * We deliberately do **not** send `expiring: 1` in the token request — that is
+ * the flag that opts into the expiring kind, and asking for a token that dies
+ * every hour when we do not have to would buy the rotation problem for
+ * nothing. But the reader below stores `expires_in` / `refresh_token`
+ * **whenever Shopify sends them**, so the day this app goes public (which
+ * means a NEW app — distribution cannot be changed) the credential shape does
+ * not have to change with it.
+ */
+/**
+ * The Admin API version, in ONE place.
+ *
+ * Shopify ships quarterly and supports each version for at least 12 months, so
+ * this is a scheduled edit, not a fire. What is *not* optional is sending it:
+ * omit the version and Shopify "falls forward" to the oldest stable version it
+ * still serves, which means the API changes under us on a date nobody chose.
+ */
+export declare const SHOPIFY_API_VERSION = "2026-07";
+export declare const SHOPIFY_OAUTH_CONFIG: {
+    /** Env var names holding HW's registered client credentials. */
+    readonly clientIdEnv: "SHOPIFY_OAUTH_CLIENT_ID";
+    readonly clientSecretEnv: "SHOPIFY_OAUTH_CLIENT_SECRET";
+};
+/** The credential `type` string. Must also exist in `@hostwebhook/node-types`
+ *  `CREDENTIAL_TYPES` — the Mongoose enum and the DTO's `@IsIn` both come from
+ *  there, and a type missing from that list fails only at runtime. */
+export declare const SHOPIFY_CREDENTIAL_TYPE = "shopify_oauth2";
+/**
+ * What the node needs, and nothing else.
+ *
+ * These must ALSO be declared on the app's released version in the Dev
+ * Dashboard — same two-places rule as Slack, not the one-place rule of
+ * Google. A scope requested here but not declared there is refused by
+ * Shopify at the authorize step.
+ *
+ * `read_all_orders` is deliberately absent: it needs a separate approval from
+ * Shopify and only widens the window past 60 days, which nothing in v1 uses.
+ */
+export declare const SHOPIFY_DEFAULT_SCOPES: readonly ["read_orders", "write_orders", "read_customers", "write_customers", "read_products", "write_products", "read_inventory", "write_inventory"];
+/**
+ * Shopify's own pattern for a store domain, anchored at both ends.
+ *
+ * Taken from their authorization guide rather than written from scratch, and
+ * the anchors are the whole point: without them
+ * `evil.com/?x=shop.myshopify.com` passes.
+ */
+export declare const SHOP_DOMAIN_RE: RegExp;
+/**
+ * Normalize and validate a store domain, or throw.
+ *
+ * Accepts what a user actually types — trailing slash, protocol, capitals, the
+ * bare handle — and returns the canonical `{shop}.myshopify.com`. Throwing
+ * rather than returning null is on purpose: every caller builds a URL with the
+ * result, so a soft failure would produce a request to a host we did not mean
+ * to call.
+ */
+export declare function normalizeShopDomain(input: string): string;
+/**
+ * Base URL for every Admin API call made with this credential.
+ *
+ * Lives here rather than being interpolated at each call site so there is one
+ * place that knows the shape — and so a credential missing its shop fails
+ * loudly here instead of producing a request to `https://undefined…`. Same
+ * reasoning as `mailchimpApiBase(dc)`.
+ */
+export declare function shopifyGraphqlUrl(shop: string): string;
+export declare function buildShopifyAuthorizeUrl(params: {
+    shop: string;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    scopes?: readonly string[];
+}): string;
+/**
+ * The body of the authorization-code exchange, including the one flag that
+ * decides whether the resulting token works at all.
+ *
+ * ## `expiring: 1` is not optional, and this file used to say the opposite
+ *
+ * Custom-distribution apps are exempt from expiring offline tokens, so the
+ * original reasoning was that asking for a token which dies every hour would
+ * buy the rotation problem for nothing. That is right — for a custom app. This
+ * app went **public**, and Shopify then refuses the non-expiring kind outright:
+ *
+ * ```
+ * [API] Non-expiring access tokens are no longer accepted for the Admin API.
+ * Start using expiring offline tokens.
+ * ```
+ *
+ * HTTP 403 on every call, including ones touching nothing protected. Seen on
+ * 2026-08-26 the first time this was pointed at a real store: the credential
+ * connected, the shop name came back, and then not one webhook subscription
+ * could be registered — because the token TYPE is decided here and refused over
+ * there, which leaves the symptom nowhere near the cause.
+ *
+ * Sent unconditionally rather than only when public, because the failure is
+ * asymmetric: a custom app handed an expiring token still works, since
+ * `refreshAccessToken` keeps it alive, while a public app handed a
+ * non-expiring one is simply dead. And the distribution method lives in
+ * Shopify's dashboard, where this code cannot read it.
+ *
+ * Pure and exported for the same reason as `verifyShopifyOAuthHmac` below: a
+ * flag buried in a private method is a flag no spec can pin, and this one is
+ * the difference between a working integration and 403 on everything.
+ *
+ * ⚠️ No `redirect_uri`. Unlike every other provider here, Shopify's token
+ * endpoint does not take one.
+ */
+export declare function buildShopifyTokenExchangeBody(params: {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+}): URLSearchParams;
+/**
+ * Verify the `hmac` Shopify appends to the callback.
+ *
+ * The recipe, from Shopify's authorization guide: drop `hmac`, sort what is
+ * left by key, join as `k=v&k=v` with the values **decoded**, HMAC-SHA256 with
+ * the client secret, compare the **hex** digest in constant time.
+ *
+ * Pure and exported so a spec can exercise it without a Nest module — the same
+ * reason `matchesGmailQuery` and friends live outside their services. A
+ * signature check that is awkward to test is a signature check nobody tests.
+ *
+ * ⚠️ Only `hmac` is removed. Older write-ups also strip `signature`; the
+ * current guide does not, and removing a parameter that Shopify *did* include
+ * in the message would make every valid callback fail to verify.
+ */
+export declare function verifyShopifyOAuthHmac(params: {
+    query: Record<string, string | undefined>;
+    clientSecret: string;
+}): boolean;
+/** What `POST /admin/oauth/access_token` gives back. */
+export interface ShopifyTokenResponse {
+    access_token?: string;
+    scope?: string;
+    /** Only present for expiring tokens — i.e. never for a custom-distribution
+     *  app today. Its absence is normal, not an error. */
+    expires_in?: number;
+    refresh_token?: string;
+    refresh_token_expires_in?: number;
+    error?: string;
+    error_description?: string;
+}
+export interface ShopifyOAuthStoredAuth {
+    accessToken: string;
+    /** Canonical `{shop}.myshopify.com`. Without this there is no host to call
+     *  — see the note at the top. */
+    shop: string;
+    /** Scopes Shopify actually granted, which can be narrower than requested. */
+    scope: string;
+    /** Absolute ms timestamp, or null when the token does not expire. */
+    expiresAt: number | null;
+    refreshToken: string | null;
+    /** Absolute ms timestamp the refresh token itself dies, or null. */
+    refreshTokenExpiresAt: number | null;
+    /** Shop display name, for the credential list. */
+    shopName: string;
+    /** Whether a test query answered when the credential was connected. */
+    probeOk: boolean;
+}
+export interface PendingShopifyOAuthState {
+    orgId: string;
+    userId: string;
+    credentialName: string;
+    /** Set on reconnect to update an existing credential instead of creating one. */
+    credentialId?: string;
+    tags?: string[];
+    folderId?: string;
+    /** The store this flow was started for. The callback's `shop` must match it:
+     *  the callback is a public route, and without this a valid-looking request
+     *  could bind a different store to the credential. */
+    shop: string;
+    clientId: string;
+    clientSecret: string;
+    /** Absolute ms timestamp when this pending state expires. */
+    expiresAt: number;
+}

package/dist/presets-de-oauth/shopify-oauth-presets.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHOP_DOMAIN_RE = exports.SHOPIFY_DEFAULT_SCOPES = exports.SHOPIFY_CREDENTIAL_TYPE = exports.SHOPIFY_OAUTH_CONFIG = exports.SHOPIFY_API_VERSION = void 0;
+exports.normalizeShopDomain = normalizeShopDomain;
+exports.shopifyGraphqlUrl = shopifyGraphqlUrl;
+exports.buildShopifyAuthorizeUrl = buildShopifyAuthorizeUrl;
+exports.buildShopifyTokenExchangeBody = buildShopifyTokenExchangeBody;
+exports.verifyShopifyOAuthHmac = verifyShopifyOAuthHmac;
+const crypto_1 = require("crypto");
+/**
+ * Shopify OAuth 2.0 configuration for HostWebhook.
+ *
+ * The app is registered in the **Dev Dashboard** (<https://dev.shopify.com/dashboard/>),
+ * not in the Partner Dashboard and not in a store's admin — both of those
+ * paths are dead: admin-created custom apps stopped being creatable on
+ * 2026-01-01. The redirect URL is
+ * `{API_URL}/api/credentials/shopify/oauth/callback`.
+ *
+ * See `docs/ADR-0007-shopify.md` for why this app uses **custom
+ * distribution**, which is the decision most of the notes below hang off.
+ *
+ * ## Three things that make Shopify unlike every other provider here
+ *
+ * **The store is part of the host.** Calls go to
+ * `https://{shop}.myshopify.com/admin/api/{version}/graphql.json`, and so does
+ * the authorization URL. That is worse than Mailchimp's `dc`, which at least
+ * arrives from Mailchimp: here the shop is **typed by the user before the flow
+ * starts**, so it is attacker-influenced input that we then put in a URL. It
+ * is validated twice — in the DTO and again here — against Shopify's own
+ * anchored pattern, and every call goes through `fetchSeguro`.
+ *
+ * **The callback is signed, and checking it is not optional.** Shopify appends
+ * an `hmac` over the rest of the query string. Skipping that check would let
+ * anyone hit our public callback with a `shop` of their choosing.
+ *
+ * **Tokens may or may not expire, and which one you get is a property of the
+ * app, not of the code.** Apps with *public* distribution created on or after
+ * 2026-04-01 must use expiring offline tokens (1 h access, 90-day refresh);
+ * apps with custom distribution are exempt and get a token that lives until
+ * the app is uninstalled. Ours is custom, so today no expiry arrives.
+ *
+ * We deliberately do **not** send `expiring: 1` in the token request — that is
+ * the flag that opts into the expiring kind, and asking for a token that dies
+ * every hour when we do not have to would buy the rotation problem for
+ * nothing. But the reader below stores `expires_in` / `refresh_token`
+ * **whenever Shopify sends them**, so the day this app goes public (which
+ * means a NEW app — distribution cannot be changed) the credential shape does
+ * not have to change with it.
+ */
+/**
+ * The Admin API version, in ONE place.
+ *
+ * Shopify ships quarterly and supports each version for at least 12 months, so
+ * this is a scheduled edit, not a fire. What is *not* optional is sending it:
+ * omit the version and Shopify "falls forward" to the oldest stable version it
+ * still serves, which means the API changes under us on a date nobody chose.
+ */
+exports.SHOPIFY_API_VERSION = '2026-07';
+exports.SHOPIFY_OAUTH_CONFIG = {
+    /** Env var names holding HW's registered client credentials. */
+    clientIdEnv: 'SHOPIFY_OAUTH_CLIENT_ID',
+    clientSecretEnv: 'SHOPIFY_OAUTH_CLIENT_SECRET',
+};
+/** The credential `type` string. Must also exist in `@hostwebhook/node-types`
+ *  `CREDENTIAL_TYPES` — the Mongoose enum and the DTO's `@IsIn` both come from
+ *  there, and a type missing from that list fails only at runtime. */
+exports.SHOPIFY_CREDENTIAL_TYPE = 'shopify_oauth2';
+/**
+ * What the node needs, and nothing else.
+ *
+ * These must ALSO be declared on the app's released version in the Dev
+ * Dashboard — same two-places rule as Slack, not the one-place rule of
+ * Google. A scope requested here but not declared there is refused by
+ * Shopify at the authorize step.
+ *
+ * `read_all_orders` is deliberately absent: it needs a separate approval from
+ * Shopify and only widens the window past 60 days, which nothing in v1 uses.
+ */
+exports.SHOPIFY_DEFAULT_SCOPES = [
+    'read_orders',
+    'write_orders',
+    'read_customers',
+    'write_customers',
+    'read_products',
+    'write_products',
+    'read_inventory',
+    'write_inventory',
+];
+/**
+ * Shopify's own pattern for a store domain, anchored at both ends.
+ *
+ * Taken from their authorization guide rather than written from scratch, and
+ * the anchors are the whole point: without them
+ * `evil.com/?x=shop.myshopify.com` passes.
+ */
+exports.SHOP_DOMAIN_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]*\.myshopify\.com$/;
+/**
+ * Normalize and validate a store domain, or throw.
+ *
+ * Accepts what a user actually types — trailing slash, protocol, capitals, the
+ * bare handle — and returns the canonical `{shop}.myshopify.com`. Throwing
+ * rather than returning null is on purpose: every caller builds a URL with the
+ * result, so a soft failure would produce a request to a host we did not mean
+ * to call.
+ */
+function normalizeShopDomain(input) {
+    let shop = String(input ?? '')
+        .trim()
+        .toLowerCase();
+    // `https://tienda.myshopify.com/admin` → `tienda.myshopify.com`
+    shop = shop.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    // A bare handle is what people paste most often.
+    if (shop && !shop.includes('.'))
+        shop = `${shop}.myshopify.com`;
+    if (!exports.SHOP_DOMAIN_RE.test(shop)) {
+        throw new Error(`"${input}" is not a Shopify store domain. It should look like ` +
+            `your-store.myshopify.com — that is the permanent domain in Settings → ` +
+            `Domains, not a custom domain you may have pointed at the store.`);
+    }
+    return shop;
+}
+/**
+ * Base URL for every Admin API call made with this credential.
+ *
+ * Lives here rather than being interpolated at each call site so there is one
+ * place that knows the shape — and so a credential missing its shop fails
+ * loudly here instead of producing a request to `https://undefined…`. Same
+ * reasoning as `mailchimpApiBase(dc)`.
+ */
+function shopifyGraphqlUrl(shop) {
+    const domain = normalizeShopDomain(shop);
+    return `https://${domain}/admin/api/${exports.SHOPIFY_API_VERSION}/graphql.json`;
+}
+function buildShopifyAuthorizeUrl(params) {
+    const domain = normalizeShopDomain(params.shop);
+    const qs = new URLSearchParams({
+        client_id: params.clientId,
+        // Comma-separated, not space-separated. Shopify is the odd one out here.
+        scope: (params.scopes ?? exports.SHOPIFY_DEFAULT_SCOPES).join(','),
+        redirect_uri: params.redirectUri,
+        state: params.state,
+    });
+    return `https://${domain}/admin/oauth/authorize?${qs.toString()}`;
+}
+/**
+ * The body of the authorization-code exchange, including the one flag that
+ * decides whether the resulting token works at all.
+ *
+ * ## `expiring: 1` is not optional, and this file used to say the opposite
+ *
+ * Custom-distribution apps are exempt from expiring offline tokens, so the
+ * original reasoning was that asking for a token which dies every hour would
+ * buy the rotation problem for nothing. That is right — for a custom app. This
+ * app went **public**, and Shopify then refuses the non-expiring kind outright:
+ *
+ * ```
+ * [API] Non-expiring access tokens are no longer accepted for the Admin API.
+ * Start using expiring offline tokens.
+ * ```
+ *
+ * HTTP 403 on every call, including ones touching nothing protected. Seen on
+ * 2026-08-26 the first time this was pointed at a real store: the credential
+ * connected, the shop name came back, and then not one webhook subscription
+ * could be registered — because the token TYPE is decided here and refused over
+ * there, which leaves the symptom nowhere near the cause.
+ *
+ * Sent unconditionally rather than only when public, because the failure is
+ * asymmetric: a custom app handed an expiring token still works, since
+ * `refreshAccessToken` keeps it alive, while a public app handed a
+ * non-expiring one is simply dead. And the distribution method lives in
+ * Shopify's dashboard, where this code cannot read it.
+ *
+ * Pure and exported for the same reason as `verifyShopifyOAuthHmac` below: a
+ * flag buried in a private method is a flag no spec can pin, and this one is
+ * the difference between a working integration and 403 on everything.
+ *
+ * ⚠️ No `redirect_uri`. Unlike every other provider here, Shopify's token
+ * endpoint does not take one.
+ */
+function buildShopifyTokenExchangeBody(params) {
+    return new URLSearchParams({
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        code: params.code,
+        expiring: '1',
+    });
+}
+/**
+ * Verify the `hmac` Shopify appends to the callback.
+ *
+ * The recipe, from Shopify's authorization guide: drop `hmac`, sort what is
+ * left by key, join as `k=v&k=v` with the values **decoded**, HMAC-SHA256 with
+ * the client secret, compare the **hex** digest in constant time.
+ *
+ * Pure and exported so a spec can exercise it without a Nest module — the same
+ * reason `matchesGmailQuery` and friends live outside their services. A
+ * signature check that is awkward to test is a signature check nobody tests.
+ *
+ * ⚠️ Only `hmac` is removed. Older write-ups also strip `signature`; the
+ * current guide does not, and removing a parameter that Shopify *did* include
+ * in the message would make every valid callback fail to verify.
+ */
+function verifyShopifyOAuthHmac(params) {
+    const provided = params.query.hmac;
+    if (!provided)
+        return false;
+    const message = Object.keys(params.query)
+        .filter((k) => k !== 'hmac')
+        .filter((k) => params.query[k] !== undefined)
+        .sort()
+        .map((k) => `${k}=${params.query[k]}`)
+        .join('&');
+    const expected = (0, crypto_1.createHmac)('sha256', params.clientSecret)
+        .update(message, 'utf8')
+        .digest('hex');
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(provided, 'utf8');
+    // `timingSafeEqual` throws on a length mismatch, which is itself a leak of
+    // the comparison — check the length first and return the same `false`.
+    if (a.length !== b.length)
+        return false;
+    return (0, crypto_1.timingSafeEqual)(a, b);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-node",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Lo que los servicios de HostWebhook comparten del lado de NODE: cifrado y utilidades que no pueden estar escritas dos veces",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",