aiap-local-validator

Apple's in-app purchases local(on-device) receipt validator module for Node.js.

This module implements in-app purchases local receipt validation. The module has no external dependencies and implemented as a native module. For more info check: https://developer.apple.com/library/archive/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateLocally.html

Node.js native module API reference.

---

• module
  • ErrorCode
    • .internal ⇒ Number
    • .input ⇒ Number
    • .format ⇒ Number
    • .validation ⇒ Number
  • InAppReceiptField
    • .quantity ⇒ Number
    • .web_order_line_item_id ⇒ Number
    • .is_in_intro_offer_period ⇒ Number
    • .product_id ⇒ Number
    • .transaction_id ⇒ Number
    • .original_transaction_id ⇒ Number
    • .purchase_date ⇒ Number
    • .original_purchase_date ⇒ Number
    • .expires_date ⇒ Number
    • .cancellation_date ⇒ Number
    • .all ⇒ Number
  • Validator
    • new Validator()
    • Validator() ⇒ new Validator()
    • .version ⇔ String|Undefined
    • .bundleIdentifier ⇔ String|Undefined
    • .GUID ⇒ ArrayBuffer, ⇐ ArrayBuffer|String
    • .inAppReceiptFields ⇔ Number
    • .rootCertificate ⇔ ArrayBuffer
    • .validate(receipt) ⇒ Object

ErrorCode

Exported object with exception error codes. Use the 'code' property of the Error object.

ErrorCode.internal ⇒ Number

The required amount of memory can't be alocated or can't instantiate some object.

ErrorCode.input ⇒ Number

The provided argument has unsupported type or incorrect value.

ErrorCode.format ⇒ Number

The receipt has unsupported type of the data or property version. Need update the code, report npm module and update project to use the latest version.

ErrorCode.validation ⇒ Number

Any validation error.

InAppReceiptField

Represents bit-mask values of the 'InAppReceiptField' fields. The name of the emum values are same as in ouput.

Validator

Exported validator.

new Validator()

Constructs new validator.

Validator.version ⇔ String|Undefined

Default: undefined. Provide the application's version to check with the receipt. If this value exists and the receipt contains different version ⇒ Exception(ErrorCode.validation).

// From the iOS client app.
let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String

Validator.bundleIdentifier ⇔ String|Undefined

Default: undefined. Provide the application's bundle identifier to check with the receipt. If this value exists and the receipt contains different bundle identifier ⇒ Exception(ErrorCode.validation).

// From the iOS client app.
let bundleIdentifier = Bundle.main.bundleIdentifier

Validator.GUID ⇒ ArrayBuffer, ⇐ ArrayBuffer|String

Default: undefined. Provide the application's GUID as a Base64 string or as ArrayBuffer of raw GUID data to check with the receipt. If this value exists and the receipt contains different GUID ⇒ Exception(ErrorCode.validation).

// From the iOS client app.
var deviceIdentifier = UIDevice.current.identifierForVendor?.uuid
let rawDeviceIdentifierPointer = withUnsafePointer(to: &deviceIdentifier) {
    return UnsafeRawPointer($0)
}
let rawGUID = NSData(bytes: rawDeviceIdentifierPointer, length: 16) // send as raw data via 'POST' request
let base64GUID = rawGUID.base64EncodedString() // send as Base64 string via 'GET' request or any other

Validator.inAppReceiptFields ⇔ Number

Default: InAppReceiptField.all. Bit-mask value of the 'In App Receipt' fields. To reset to a default 'all' value, provide undefined value or any unsupported combination of the bit-mask value.

Validator.rootCertificate ⇔ ArrayBuffer

Default: bundled raw data of the 'Apple Inc Root Certificate' as ArrayBuffer. Instead of using bundled 'Apple Inc Root Certificate' you can provide and use your own updated. To reset to a default bundled certificate, provide undefined value.

https://www.apple.com/appleca/AppleIncRootCertificate.cer

Validator.validate(receipt) ⇔ Object

Validates the provided receipt as a Base64 String or as ArrayBuffer of raw data and returns the decrypted App Receipt and array of In-App Purchase Receipt's. If the 'version' and/or 'bundleIdentifier' and/or 'GUID' was provided and the decrypted receipt contains different values ⇒ Exception(ErrorCode.validation).

https://developer.apple.com/library/archive/releasenotes/General/ValidateAppStoreReceipt/Chapters/ReceiptFields.html

Installation via npm package.json

---

{
  "engines": {
    "node": ">=10.0.0",
    "npm": ">=6.0.0"
  },
  "dependencies": {
    "aiap-local-validator": "^1.0.2"
  }
}

Example

---

const { Validator, ErrorCode, InAppReceiptField } = require('aiap-local-validator');

try {
    const validator = new Validator();
    
    // Optinaly select fields of the 'In App Receipt', otherwise all fields.
    validator.inAppReceiptFields = InAppReceiptField.expires_date | InAppReceiptField.product_id | ...;
    
    // Optionaly, but recommended, validate the receipt with 'bundleIdentifier', 'version' and 'GUID'.
    validator.bundleIdentifier = 'my.cool.app'; // If validation was failed, the receipt was created by another app -> invalid.
    validator.version = '123'; // If validation was failed, the receipt was created by another version of the app -> invalid.
    validator.GUID = '<Base64 GUID>' | ArrayBuffer; // If validation was failed, the receipt was created on another device -> invalid.
    
    const receipt = validator.validate('<Base64 receipt>' | ArrayBuffer); 
} catch (error) {
    switch (error.code) {
        case ErrorCode.input: break;
        case ErrorCode.validation: break;
        ...
    }
}

Supported fields

All fields of 'App Receipt' and 'In-App Purchase Receipt' which are described and have a valid 'ASN.1 Field Type' are supported.

https://developer.apple.com/library/archive/releasenotes/General/ValidateAppStoreReceipt/Chapters/ReceiptFields.html

Experimantal 'In-App Purchase Receipt' fields

If the field of the 'In-App Purchase Receipt' was selected for output and has a 'RFC 3339 date' string format. Then the extra field with '_ms' prefix will be added with parsed date value in milliseconds(similar to an Apple's online validation).

License

---

MIT License

Copyright (c) 2020 - 2021 OlehKulykov [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.