guide

Encrypted Globally Unique Identifier (GUIDE) generator.

• Implementation
• Use case
• API
• Usage

Implementation

• GUIDE is using aes-256-gcm encryption.
• Identifiers are encoded using URL-safe base64 encoding.

aes-256-gcm is the closest thing I have found to a misuse resistant algorithm. If you know of a better encryption algorithm (misuse resistant) thats available to Node.js – raise an issue.

Use case

GUIDE is used to mitigate certain types of DDoS attacks.

• Protecting APIs from the DDoS attacks by encrypting the PKs

API

type GuidePayloadType = {|
  id: number | string,
  namespace: string,
  type: string
|};

/**
* @throws InvalidGuideError Throws if input guide cannot be decrypted.
* @throws UnexpectedNamespaceValueError Throws if the namespace contained in the payload does not match the expected namespace.
* @throws UnexpectedResourceTypeNameValueError Throws if the resource type name contained in the payload does not match the expected resource type name.
*/
type FromGuideType = (initializationVectorValue: string, expectedNamespace: string, expectedResourceTypeName: string, guide: string) => GuidePayloadType;

/**
 * @param initializationVectorValue Initialization vector. Must be at least 128 characters long.
 * @param namespace A namespace of the GUID (e.g. company name or the application name).
 * @param type A resource type name (e.g. article).
 */
type ToGuideType = (initializationVectorValue: string, namespace: string, type: string, id: number | string) => string;

Usage

import {
  fromGuide,
  toGuide,
} from 'guide';

const initializationVectorValue = 'lGMUlgYOZXkT7MWjRozJ7F3MlSm89SPkop2AvQciBk1xXLGCX5aUy3uIJHEInjQzyHZSnZ0NaQaVpEldAlVWeguOLYkW5ZluwbaHY0iWEgFULRV92GV5KgHj2P5YChgW';
const namespace = 'gajus';
const resourceTypeName = 'article';

const guide = toGuide(initializationVectorValue, namespace, resourceTypeName, 1);

// "ao-CZ7gmFSaFhA4tzWaM2CiOGtt772ZqJDB1k1ty3QWkc24Rx43iYuUc_S0ecZiiWS8aTP-0EQ"

const payload = fromGuide(initializationVectorValue, namespace, resourceTypeName, guide);

// {
//   "id": 1,
//   "namespace": "gajus",
//   "type": "article"
// }

Handling errors

fromGuide method can throw the following errors.
|Error constructor name|Description| |---|---| |InvalidGuideError|Throws if input guide cannot be decrypted.| |UnexpectedNamespaceValueError|Throws if the namespace contained in the payload does not match the expected namespace.| |UnexpectedResourceTypeNameValueError|Throws if the resource type name contained in the payload does not match the expected resource type name.|
Error constructors can be imported from guide package.
UnexpectedNamespaceValueError and UnexpectedResourceTypeNameValueError extend from InvalidGuideError. It is enough to check if an error object is an instance of InvalidGuideError to assert that an error is a result of an invalid GUIDE.

import {
  fromGuide,
  InvalidGuideError
} from 'guide';

try {
  fromGuide(initializationVectorValue, namespace, resourceTypeName, guide);
} catch (error) {
  if (error instanceof InvalidGuideError) {
    // Handle error.
  }

  // Re-throw other errors.
  throw error;
}