stripe 8.186.0 → 8.189.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # CHANGELOG
 
+## 8.189.0 - 2021-11-16
+* [#1295](https://github.com/stripe/stripe-node/pull/1295) API Updates
+  * Add support for new resource `ShippingRate`
+  * Add support for `shipping_options` on `CheckoutSessionCreateParams` and `Checkout.Session`
+  * Add support for `shipping_rate` on `Checkout.Session`
+
+## 8.188.0 - 2021-11-12
+* [#1293](https://github.com/stripe/stripe-node/pull/1293) API Updates
+  * Add support for new value `agrobank` on enums `Charge.payment_method_details.fpx.bank`, `PaymentIntentCreateParams.payment_method_data.fpx.bank`, `PaymentIntentUpdateParams.payment_method_data.fpx.bank`, `PaymentIntentConfirmParams.payment_method_data.fpx.bank`, `PaymentMethodCreateParams.fpx.bank`, and `PaymentMethod.fpx.bank`
+
+## 8.187.0 - 2021-11-11
+* [#1292](https://github.com/stripe/stripe-node/pull/1292) API Updates
+  * Add support for `expire` method on resource `Checkout.Session`
+  * Add support for `status` on `Checkout.Session`
+* [#1288](https://github.com/stripe/stripe-node/pull/1288) Add SubtleCryptoProvider and update Webhooks to allow async crypto.
+* [#1291](https://github.com/stripe/stripe-node/pull/1291) Better types in `lib.d.ts`
+
+## 8.186.1 - 2021-11-04
+* [#1284](https://github.com/stripe/stripe-node/pull/1284) API Updates
+  * Remove support for `ownership_declaration_shown_and_signed` on `TokenCreateParams.account`. This API was unused.
+  * Add support for `ownership_declaration_shown_and_signed` on `TokenCreateParams.account.company`
+  
+
 ## 8.186.0 - 2021-11-01
 * [#1283](https://github.com/stripe/stripe-node/pull/1283) API Updates
   * Add support for `ownership_declaration` on `AccountUpdateParams.company`, `AccountCreateParams.company`, `Account.company`, and `TokenCreateParams.account.company`

package/VERSION

@@ -1 +1 @@
-8.186.0
+8.189.0

package/lib/Webhooks.js

@@ -19,6 +19,25 @@ const Webhook = {
     return jsonPayload;
   },
 
+  async constructEventAsync(
+    payload,
+    header,
+    secret,
+    tolerance,
+    cryptoProvider
+  ) {
+    await this.signature.verifyHeaderAsync(
+      payload,
+      header,
+      secret,
+      tolerance || Webhook.DEFAULT_TOLERANCE,
+      cryptoProvider
+    );
+
+    const jsonPayload = JSON.parse(payload);
+    return jsonPayload;
+  },
+
   /**
    * Generates a header to be used for webhook mocking
    *
@@ -62,81 +81,156 @@ const Webhook = {
 const signature = {
   EXPECTED_SCHEME: 'v1',
 
-  verifyHeader(payload, header, secret, tolerance, cryptoProvider) {
-    payload = Buffer.isBuffer(payload) ? payload.toString('utf8') : payload;
+  verifyHeader(
+    encodedPayload,
+    encodedHeader,
+    secret,
+    tolerance,
+    cryptoProvider
+  ) {
+    const {
+      decodedHeader: header,
+      decodedPayload: payload,
+      details,
+    } = parseEventDetails(encodedPayload, encodedHeader, this.EXPECTED_SCHEME);
 
-    // Express's type for `Request#headers` is `string | []string`
-    // which is because the `set-cookie` header is an array,
-    // but no other headers are an array (docs: https://nodejs.org/api/http.html#http_message_headers)
-    // (Express's Request class is an extension of http.IncomingMessage, and doesn't appear to be relevantly modified: https://github.com/expressjs/express/blob/master/lib/request.js#L31)
-    if (Array.isArray(header)) {
-      throw new Error(
-        'Unexpected: An array was passed as a header, which should not be possible for the stripe-signature header.'
-      );
-    }
-
-    header = Buffer.isBuffer(header) ? header.toString('utf8') : header;
+    cryptoProvider = cryptoProvider || getNodeCryptoProvider();
+    const expectedSignature = cryptoProvider.computeHMACSignature(
+      makeHMACContent(payload, details),
+      secret
+    );
 
-    const details = parseHeader(header, this.EXPECTED_SCHEME);
+    validateComputedSignature(
+      payload,
+      header,
+      details,
+      expectedSignature,
+      tolerance
+    );
 
-    if (!details || details.timestamp === -1) {
-      throw new StripeSignatureVerificationError({
-        message: 'Unable to extract timestamp and signatures from header',
-        detail: {
-          header,
-          payload,
-        },
-      });
-    }
+    return true;
+  },
 
-    if (!details.signatures.length) {
-      throw new StripeSignatureVerificationError({
-        message: 'No signatures found with expected scheme',
-        detail: {
-          header,
-          payload,
-        },
-      });
-    }
+  async verifyHeaderAsync(
+    encodedPayload,
+    encodedHeader,
+    secret,
+    tolerance,
+    cryptoProvider
+  ) {
+    const {
+      decodedHeader: header,
+      decodedPayload: payload,
+      details,
+    } = parseEventDetails(encodedPayload, encodedHeader, this.EXPECTED_SCHEME);
 
     cryptoProvider = cryptoProvider || getNodeCryptoProvider();
-    const expectedSignature = cryptoProvider.computeHMACSignature(
-      `${details.timestamp}.${payload}`,
+
+    const expectedSignature = await cryptoProvider.computeHMACSignatureAsync(
+      makeHMACContent(payload, details),
       secret
     );
 
-    const signatureFound = !!details.signatures.filter(
-      utils.secureCompare.bind(utils, expectedSignature)
-    ).length;
-
-    if (!signatureFound) {
-      throw new StripeSignatureVerificationError({
-        message:
-          'No signatures found matching the expected signature for payload.' +
-          ' Are you passing the raw request body you received from Stripe?' +
-          ' https://github.com/stripe/stripe-node#webhook-signing',
-        detail: {
-          header,
-          payload,
-        },
-      });
-    }
+    return validateComputedSignature(
+      payload,
+      header,
+      details,
+      expectedSignature,
+      tolerance
+    );
+  },
+};
 
-    const timestampAge = Math.floor(Date.now() / 1000) - details.timestamp;
+function makeHMACContent(payload, details) {
+  return `${details.timestamp}.${payload}`;
+}
 
-    if (tolerance > 0 && timestampAge > tolerance) {
-      throw new StripeSignatureVerificationError({
-        message: 'Timestamp outside the tolerance zone',
-        detail: {
-          header,
-          payload,
-        },
-      });
-    }
+function parseEventDetails(encodedPayload, encodedHeader, expectedScheme) {
+  const decodedPayload = Buffer.isBuffer(encodedPayload)
+    ? encodedPayload.toString('utf8')
+    : encodedPayload;
+
+  // Express's type for `Request#headers` is `string | []string`
+  // which is because the `set-cookie` header is an array,
+  // but no other headers are an array (docs: https://nodejs.org/api/http.html#http_message_headers)
+  // (Express's Request class is an extension of http.IncomingMessage, and doesn't appear to be relevantly modified: https://github.com/expressjs/express/blob/master/lib/request.js#L31)
+  if (Array.isArray(encodedHeader)) {
+    throw new Error(
+      'Unexpected: An array was passed as a header, which should not be possible for the stripe-signature header.'
+    );
+  }
 
-    return true;
-  },
-};
+  const decodedHeader = Buffer.isBuffer(encodedHeader)
+    ? encodedHeader.toString('utf8')
+    : encodedHeader;
+
+  const details = parseHeader(decodedHeader, expectedScheme);
+
+  if (!details || details.timestamp === -1) {
+    throw new StripeSignatureVerificationError({
+      message: 'Unable to extract timestamp and signatures from header',
+      detail: {
+        decodedHeader,
+        decodedPayload,
+      },
+    });
+  }
+
+  if (!details.signatures.length) {
+    throw new StripeSignatureVerificationError({
+      message: 'No signatures found with expected scheme',
+      detail: {
+        decodedHeader,
+        decodedPayload,
+      },
+    });
+  }
+
+  return {
+    decodedPayload,
+    decodedHeader,
+    details,
+  };
+}
+
+function validateComputedSignature(
+  payload,
+  header,
+  details,
+  expectedSignature,
+  tolerance
+) {
+  const signatureFound = !!details.signatures.filter(
+    utils.secureCompare.bind(utils, expectedSignature)
+  ).length;
+
+  if (!signatureFound) {
+    throw new StripeSignatureVerificationError({
+      message:
+        'No signatures found matching the expected signature for payload.' +
+        ' Are you passing the raw request body you received from Stripe?' +
+        ' https://github.com/stripe/stripe-node#webhook-signing',
+      detail: {
+        header,
+        payload,
+      },
+    });
+  }
+
+  const timestampAge = Math.floor(Date.now() / 1000) - details.timestamp;
+
+  if (tolerance > 0 && timestampAge > tolerance) {
+    throw new StripeSignatureVerificationError({
+      message: 'Timestamp outside the tolerance zone',
+      detail: {
+        header,
+        payload,
+      },
+    });
+  }
+
+  return true;
+}
 
 function parseHeader(header, scheme) {
   if (typeof header !== 'string') {

package/lib/crypto/CryptoProvider.js

@@ -16,6 +16,21 @@ class CryptoProvider {
   computeHMACSignature(payload, secret) {
     throw new Error('computeHMACSignature not implemented.');
   }
+
+  /**
+   * Asynchronous version of `computeHMACSignature`. Some implementations may
+   * only allow support async signature computation.
+   *
+   * Computes a SHA-256 HMAC given a secret and a payload (encoded in UTF-8).
+   * The output HMAC should be encoded in hexadecimal.
+   *
+   * Sample values for implementations:
+   * - computeHMACSignature('', 'test_secret') => 'f7f9bd47fb987337b5796fdc1fdb9ba221d0d5396814bfcaf9521f43fd8927fd'
+   * - computeHMACSignature('\ud83d\ude00', 'test_secret') => '837da296d05c4fe31f61d5d7ead035099d9585a5bcde87de952012a78f0b0c43
+   */
+  computeHMACSignatureAsync(payload, secret) {
+    throw new Error('computeHMACSignatureAsync not implemented.');
+  }
 }
 
 module.exports = CryptoProvider;

package/lib/crypto/NodeCryptoProvider.js

@@ -15,6 +15,12 @@ class NodeCryptoProvider extends CryptoProvider {
       .update(payload, 'utf8')
       .digest('hex');
   }
+
+  /** @override */
+  async computeHMACSignatureAsync(payload, secret) {
+    const signature = await this.computeHMACSignature(payload, secret);
+    return signature;
+  }
 }
 
 module.exports = NodeCryptoProvider;

package/lib/crypto/SubtleCryptoProvider.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const CryptoProvider = require('./CryptoProvider');
+
+/**
+ * `CryptoProvider which uses the SubtleCrypto interface of the Web Crypto API.
+ *
+ * This only supports asynchronous operations.
+ */
+class SubtleCryptoProvider extends CryptoProvider {
+  constructor(subtleCrypto) {
+    super();
+
+    // If no subtle crypto is interface, default to the global namespace. This
+    // is to allow custom interfaces (eg. using the Node webcrypto interface in
+    // tests).
+    this.subtleCrypto = subtleCrypto || crypto.subtle;
+  }
+
+  /** @override */
+  computeHMACSignature(payload, secret) {
+    throw new Error(
+      'SubtleCryptoProvider cannot be used in a synchronous context.'
+    );
+  }
+
+  /** @override */
+  async computeHMACSignatureAsync(payload, secret) {
+    const encoder = new TextEncoder('utf-8');
+
+    const key = await this.subtleCrypto.importKey(
+      'raw',
+      encoder.encode(secret),
+      {
+        name: 'HMAC',
+        hash: {name: 'SHA-256'},
+      },
+      false,
+      ['sign']
+    );
+
+    const signatureBuffer = await this.subtleCrypto.sign(
+      'hmac',
+      key,
+      encoder.encode(payload)
+    );
+
+    // crypto.subtle returns the signature in base64 format. This must be
+    // encoded in hex to match the CryptoProvider contract. We map each byte in
+    // the buffer to its corresponding hex octet and then combine into a string.
+    const signatureBytes = new Uint8Array(signatureBuffer);
+    const signatureHexCodes = new Array(signatureBytes.length);
+
+    for (let i = 0; i < signatureBytes.length; i++) {
+      signatureHexCodes[i] = byteHexMapping[signatureBytes[i]];
+    }
+
+    return signatureHexCodes.join('');
+  }
+}
+
+// Cached mapping of byte to hex representation. We do this once to avoid re-
+// computing every time we need to convert the result of a signature to hex.
+const byteHexMapping = new Array(256);
+for (let i = 0; i < byteHexMapping.length; i++) {
+  byteHexMapping[i] = i.toString(16).padStart(2, '0');
+}
+
+module.exports = SubtleCryptoProvider;

package/lib/net/NodeHttpClient.js

@@ -97,7 +97,7 @@ class NodeHttpClientResponse extends HttpClientResponse {
 
   toStream(streamCompleteCallback) {
     // The raw response is itself the stream, so we just return that. To be
-    // backwards comaptible, we should invoke the streamCompleteCallback only
+    // backwards compatible, we should invoke the streamCompleteCallback only
     // once the stream has been fully consumed.
     this._res.once('end', () => streamCompleteCallback());
     return this._res;

package/lib/resources/Checkout/Sessions.js

@@ -24,6 +24,11 @@ module.exports = StripeResource.extend({
     methodType: 'list',
   }),
 
+  expire: stripeMethod({
+    method: 'POST',
+    path: '/{session}/expire',
+  }),
+
   listLineItems: stripeMethod({
     method: 'GET',
     path: '/{session}/line_items',

package/lib/resources/ShippingRates.js

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec
+
+'use strict';
+
+const StripeResource = require('../StripeResource');
+const stripeMethod = StripeResource.method;
+
+module.exports = StripeResource.extend({
+  path: 'shipping_rates',
+
+  create: stripeMethod({
+    method: 'POST',
+    path: '',
+  }),
+
+  retrieve: stripeMethod({
+    method: 'GET',
+    path: '/{shippingRateToken}',
+  }),
+
+  update: stripeMethod({
+    method: 'POST',
+    path: '/{shippingRateToken}',
+  }),
+
+  list: stripeMethod({
+    method: 'GET',
+    path: '',
+    methodType: 'list',
+  }),
+});

package/lib/resources.js

@@ -43,6 +43,7 @@ module.exports = {
   Reviews: require('./resources/Reviews'),
   SetupAttempts: require('./resources/SetupAttempts'),
   SetupIntents: require('./resources/SetupIntents'),
+  ShippingRates: require('./resources/ShippingRates'),
   Skus: require('./resources/SKUs'),
   Sources: require('./resources/Sources'),
   Subscriptions: require('./resources/Subscriptions'),

package/lib/stripe.js

@@ -154,6 +154,28 @@ Stripe.createFetchHttpClient = (fetchFn) => {
   return new FetchHttpClient(fetchFn);
 };
 
+/**
+ * Create a CryptoProvider which uses the built-in Node crypto libraries for
+ * its crypto operations.
+ */
+Stripe.createNodeCryptoProvider = () => {
+  const NodeCryptoProvider = require('./crypto/NodeCryptoProvider');
+  return new NodeCryptoProvider();
+};
+
+/**
+ * Creates a CryptoProvider which uses the Subtle Crypto API from the Web
+ * Crypto API spec for its crypto operations.
+ *
+ * A SubtleCrypto interface can optionally be passed in as a parameter. If none
+ * is passed, will default to the default `crypto.subtle` object in the global
+ * scope.
+ */
+Stripe.createSubtleCryptoProvider = (subtleCrypto) => {
+  const SubtleCryptoProvider = require('./crypto/SubtleCryptoProvider');
+  return new SubtleCryptoProvider(subtleCrypto);
+};
+
 Stripe.prototype = {
   /**
    * @deprecated will be removed in a future major version. Use the config object instead:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stripe",
-  "version": "8.186.0",
+  "version": "8.189.0",
   "description": "Stripe API wrapper",
   "keywords": [
     "stripe",
@@ -54,8 +54,8 @@
   "license": "MIT",
   "scripts": {
     "clean": "rm -rf ./.nyc_output ./node_modules/.cache ./coverage",
-    "mocha": "nyc mocha",
-    "mocha-only": "mocha",
+    "mocha": "nyc mocha --config=test/.mocharc.js",
+    "mocha-only": "mocha --config=test/.mocharc.js",
     "test": "yarn lint && yarn test-typescript && yarn mocha",
     "test-typescript": "tsc --build types/test",
     "lint": "eslint --ext .js,.jsx,.ts .",

package/types/2020-08-27/Accounts.d.ts

@@ -1075,7 +1075,7 @@ declare module 'stripe' {
       expand?: Array<string>;
 
       /**
-       * A card or bank account to attach to the account for receiving [payouts](https://stripe.com/docs/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/stripe-js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/docs/api#account_create_bank_account) creation.
+       * A card or bank account to attach to the account for receiving [payouts](https://stripe.com/docs/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/docs/api#account_create_bank_account) creation.
        *
        * By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the bank account or card creation API.
        */
@@ -2150,7 +2150,7 @@ declare module 'stripe' {
       expand?: Array<string>;
 
       /**
-       * A card or bank account to attach to the account for receiving [payouts](https://stripe.com/docs/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/stripe-js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/docs/api#account_create_bank_account) creation.
+       * A card or bank account to attach to the account for receiving [payouts](https://stripe.com/docs/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/docs/api#account_create_bank_account) creation.
        *
        * By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the bank account or card creation API.
        */

package/types/2020-08-27/Charges.d.ts

@@ -1128,7 +1128,7 @@ declare module 'stripe' {
           account_holder_type: Fpx.AccountHolderType | null;
 
           /**
-           * The customer's bank. Can be one of `affin_bank`, `alliance_bank`, `ambank`, `bank_islam`, `bank_muamalat`, `bank_rakyat`, `bsn`, `cimb`, `hong_leong_bank`, `hsbc`, `kfh`, `maybank2u`, `ocbc`, `public_bank`, `rhb`, `standard_chartered`, `uob`, `deutsche_bank`, `maybank2e`, or `pb_enterprise`.
+           * The customer's bank. Can be one of `affin_bank`, `agrobank`, `alliance_bank`, `ambank`, `bank_islam`, `bank_muamalat`, `bank_rakyat`, `bsn`, `cimb`, `hong_leong_bank`, `hsbc`, `kfh`, `maybank2u`, `ocbc`, `public_bank`, `rhb`, `standard_chartered`, `uob`, `deutsche_bank`, `maybank2e`, or `pb_enterprise`.
            */
           bank: Fpx.Bank;
 
@@ -1143,6 +1143,7 @@ declare module 'stripe' {
 
           type Bank =
             | 'affin_bank'
+            | 'agrobank'
             | 'alliance_bank'
             | 'ambank'
             | 'bank_islam'
@@ -1667,7 +1668,7 @@ declare module 'stripe' {
       application_fee_amount?: number;
 
       /**
-       * Whether to immediately capture the charge. Defaults to `true`. When `false`, the charge issues an authorization (or pre-authorization), and will need to be [captured](https://stripe.com/docs/api#capture_charge) later. Uncaptured charges expire in _seven days_. For more information, see the [authorizing charges and settling later](https://stripe.com/docs/charges/placing-a-hold) documentation.
+       * Whether to immediately capture the charge. Defaults to `true`. When `false`, the charge issues an authorization (or pre-authorization), and will need to be [captured](https://stripe.com/docs/api#capture_charge) later. Uncaptured charges expire after a set number of days (7 by default). For more information, see the [authorizing charges and settling later](https://stripe.com/docs/charges/placing-a-hold) documentation.
        */
       capture?: boolean;
 
@@ -2017,7 +2018,7 @@ declare module 'stripe' {
       /**
        * Capture the payment of an existing, uncaptured, charge. This is the second half of the two-step payment flow, where first you [created a charge](https://stripe.com/docs/api#create_charge) with the capture option set to false.
        *
-       * Uncaptured payments expire exactly seven days after they are created. If they are not captured by that point in time, they will be marked as refunded and will no longer be capturable.
+       * Uncaptured payments expire a set number of days after they are created ([7 by default](https://stripe.com/docs/charges/placing-a-hold)). If they are not captured by that point in time, they will be marked as refunded and will no longer be capturable.
        */
       capture(
         id: string,