sguid

SGUID

Signed Globally Unique Identifier (SGUID) generator.

• Implementation
• Use case
• API
• Usage
• Generating key pair

Implementation

• SGUID uses Ed25519 public-key signature system.
• The resulting signature is encoded using URL-safe base64 encoding.

Use case

SGUID is used to mitigate certain types of DDoS attacks.

• Protecting APIs from the DDoS attacks by signing the resource identifiers

API

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

/**
* @throws InvalidSguidError Throws if signed message cannot be opened.
* @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 FromSguidType = (publicKey: string, expectedNamespace: string, expectedResourceTypeName: string, sguid: string) => SguidPayloadType;

/**
 * @param secretKey {@see https://github.com/gajus/sguid#generating-secret-key}
 * @param namespace A namespace of the GUID (e.g. company name or the application name).
 * @param type A resource type name (e.g. article).
 * @param id Resource identifier.
 */
type ToSguidType = (secretKey: string, namespace: string, type: string, id: number | string) => string;

Usage

import {
  fromSguid,
  toSguid,
} from 'sguid';

const secretKey = '6h2K+JuGfWTrs5Lxt+mJw9y5q+mXKCjiJgngIDWDFy23TWmjpfCnUBdO1fDzi6MxHMO2nTPazsnTcC2wuQrxVQ==';
const publicKey = 't01po6Xwp1AXTtXw84ujMRzDtp0z2s7J03AtsLkK8VU=';
const namespace = 'gajus';
const resourceTypeName = 'article';
const resourceIdentifier = 1;

const sguid = toSguid(secretKey, namespace, resourceTypeName, resourceIdentifier);

// "pbp3h9nTr0wPboKaWrg_Q77KnZW1-rBkwzzYJ0Px9Qvbq0KQvcfuR2uCRCtijQYsX98g1F50k50x5YKiCgnPAnsiaWQiOjEsIm5hbWVzcGFjZSI6ImdhanVzIiwidHlwZSI6ImFydGljbGUifQ"

const payload = fromSguid(publicKey, namespace, resourceTypeName, sguid);

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

Handling errors

fromSguid method can throw the following errors.

Error constructor name	Description
InvalidSguidError	Throws if signed message cannot be opened.
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 sguid package.

UnexpectedNamespaceValueError and UnexpectedResourceTypeNameValueError extend from InvalidSguidError. It is enough to check if an error object is an instance of InvalidSguidError to assert that an error is a result of an invalid SGUID.

import {
  fromSguid,
  InvalidSguidError
} from 'sguid';

try {
  fromSguid(initializationVectorValue, namespace, resourceTypeName, sguid);
} catch (error) {
  if (error instanceof InvalidSguidError) {
    // Handle error.
  }

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

Generating key pair

Sguid provides a CLI utility sguid new-key-pair to generate a key pair

$ npm install sguid -g
$ sguid new-key-pair

If you need to generate the key pair programmatically, use nacl.sign.keyPair().