Disclaimers

This is beta software. Use in production at your own risk.

Currently validateRequest and handleCallback only support online mode.

About

Provides functionality for some of the more tedious requirements when building a Shopify app such as consistent hmac validation behavior for authentication, proxies, etc. Provided as general use functions but can easily be adapted for use as express middleware.

This is not meant to be a batteries included solution. For that checkout shopify-express

Installation

Note: requires NodeJS >= 8.6.0

npm install @satel/shopify-app-utils

or

yarn add @satel/shopify-app-utils

Documentation

Table of Contents

• createOAuth
  • Parameters
  • Examples
• validateRequest
  • Parameters
• validateRequest~generateNonce
  • Parameters
• validateRequest~onAuthenticated
  • Parameters
• validateRequest~onRedirect
  • Parameters
• validateRequest~onFailed
  • Parameters
• handleCallback
  • Parameters
• handleCallback~validateNonce
  • Parameters
• handleCallback~onAuthenticated
  • Parameters
• handleCallback~onFailed
  • Parameters
• validateHMAC
  • Parameters
  • Examples
• generateRedirect
  • Parameters
  • Examples
• generateJSRedirect
  • Parameters
• validateDomain
  • Parameters
  • Examples
• validateTimestamp
  • Parameters
  • Examples
• validateSignature
  • Parameters
  • Examples
• computeHMAC
  • Parameters
  • Examples

createOAuth

Creates instances of validateRequest & handleCallback wrapped in a closure

Parameters

• options object
  • options.host string the base url of the app
  • options.redirectRoute string the route where oauth2 redirects will be handled
  • options.scope Array<string> scope your app will require
  • options.key string shopify app api key
  • options.secret string shopify app shared secret
  • options.online boolean do you require an online token (optional, default false)
  • options.offline boolean do you require an offline token (optional, default false)

Examples

const oauth = require('@satel/shopify-app-utils');

const { validateRequest, handleCallback } = oauth.create({
  host: 'https://my-app.com',
  redirectRoute: '/redirect',
  scope: ['read_products'],
  key: 'MY_KEY',
  secret: 'MY_SECRET',
  online: true,
});

validateRequest

TODO

Parameters

• options object
  • options.url string url of the request to validate
  • options.jwt string jwt associated with the current request
  • options.host string the base url of the app
  • options.redirectRoute string the route where oauth2 redirects will be handled
  • options.scope Array<string> scope your app will require
  • options.key string shopify app api key
  • options.secret string shopify app shared secret
  • options.online boolean do you require an online token (optional, default false)
  • options.offline boolean do you require an offline token (optional, default false)
  • options.generateNonce validateRequest~generateNonce
  • options.onAuthenticated validateRequest~onAuthenticated
  • options.onRedirect validateRequest~onRedirect
  • options.onFailed validateRequest~onFailed

validateRequest~generateNonce

Used to generate a nonce to be used in a redirect url

Type: Function

Parameters

• options object
  • options.shop string the .myshopify domain

Returns string

validateRequest~onAuthenticated

Called when a request is authorized

Type: Function

Parameters

• options object
  • options.shop string the .myshopify domain
  • options.appScope Array<string> the application scope (when jwt was generated)
  • options.userScope (Array<string> | undefined) the user scope (only applicable to online tokens)
  • options.decoded object decoded body of the jwt

validateRequest~onRedirect

Called when a redirect is required

Type: Function

Parameters

• options object
  • options.url string the redirect url
  • options.html string a js based redirect for use in iframes

validateRequest~onFailed

Called when unable to redirect or authorize

Type: Function

Parameters

• options object

handleCallback

Parameters

• options object
  • options.url string
  • options.key string shopify app api key
  • options.secret string shopify app shared secret
  • options.validateNonce handleCallback~validateNonce
  • options.onAuthenticated handleCallback~onAuthenticated
  • options.onFailed handleCallback~onFailed
  • options.margin number (optional, default 60)

handleCallback~validateNonce

Used to validate a previously generated nonce

Type: Function

Parameters

• options object
  • options.shop string the .myshopify domain
  • options.nonce string the retrieved nonce

Returns (boolean | Promise<boolean>)

handleCallback~onAuthenticated

Called when a request is authorized

Type: Function

Parameters

• options object
  • options.token string the shopify access token
  • options.online string indicates if the current token is online or offline
  • options.jwt string a jwt token
  • options.shop string the .myshopify domain
  • options.appScope Array<string> the application scope (when jwt was generated)
  • options.userScope (Array<string> | undefined) the user scope (only applicable to online tokens)

handleCallback~onFailed

Called when request cannot be authorized

Type: Function

Parameters

• options object

validateHMAC

• See: https://help.shopify.com/en/api/getting-started/authentication/oauth#verification

Parses the url and validates the HMAC provided by shopify

Parameters

• options Object
  • options.url string
  • options.secret string

Examples

// Import
import { oauth } from '@satel/shopify-app-utils';
const { oauth } = require('@satel/shopify-app-utils');
const { validateHMAC } = oauth;

// Directly
const validateHMAC = require('@satel/shopify-app-utils/oauth/hmac');

// General
const validHMAC = validateHMAC({ url, secret: 'hush' });

// Express
app.use(req => {
  const validHMAC = validateHMAC({ url: req.url, secret: 'hush' });
});

Returns boolean

generateRedirect

Generates the url / html based redirect to start the oauth2 process

Parameters

• options Object
  • options.shop string
  • options.apiKey string
  • options.nonce string
  • options.redirect string
  • options.scope Array<string>
  • options.online boolean (optional, default false)
  • options.iframe boolean (optional, default false)

Examples

// Full Page App
res.redirect(
  generateRedirect({
    shop: 'example.myshopify.com',
    apiKey: 'MY_APP_API_KEY',
    nonce: 'unique-request-identifier',
    redirect: 'https://my-app.com/path/to/redirect',
    scope: ['read_products', 'write_products', 'etc'],
  }),
);

// Embedded online app
res.send(
  generateRedirect({
    shop: 'example.myshopify.com',
    apiKey: 'MY_APP_API_KEY',
    nonce: 'unique-request-identifier',
    redirect: 'https://my-app.com/path/to/redirect',
    scope: ['read_products', 'write_products', 'etc'],
    online: true,
    iframe: true,
  }),
);

Returns string

generateJSRedirect

Pass in a url and it returns an html document that will redirect top rather than the iFrame

Parameters

• options Object
  • options.url string

Returns string

validateDomain

Checks if a string is a valid .myshopify.com domain (exclude the protocol)

Parameters

• options Object
  • options.shop string

Examples

const validDomain = validateDomain({ shop: 'my-shop.myshopify.com' });

Returns boolean

validateTimestamp

Verifies the shopify timestamp generally provided with authenticated responses from shopify

Parameters

• $0 Object
  • $0.timestamp
  • $0.margin (optional, default 60)
• options Object
• timestamp string
• margin number Timestamp must be withing margin of now (optional, default 60)

Examples

const validTimestamp = validateTimestamp({ timestamp: '1533160800', margin: 60 * 5 });

Returns boolean

validateSignature

• See: https://help.shopify.com/en/api/guides/application-proxies

Parses the url and validates proxied requests from Shopify

Parameters

• options Object
  • options.url string
  • options.secret string

Examples

// Import
import { proxy } from '@satel/shopify-app-utils';
const { proxy } = require('@satel/shopify-app-utils');
const { validateSignature } = proxy;

// Directly
const validateSignature = require('@satel/shopify-app-utils/oauth/proxy');

// General
const valid = validateSignature({ url, secret: 'hush' });

// Express
app.use(req => {
  const valid = validateSignature({ url: req.url, secret: 'hush' });
});

Returns boolean

computeHMAC

Produces a hex encoded Sha256 hmac

Parameters

• options Object
  • options.text string
  • options.secret string

Examples

const hash = computeHMAC({
  text: 'message',
  secret: 'hush',
});

Returns string