sgu

sguid

Signed Globally Unique Identifier (SGUID) generator.

Showing:

Popularity

Downloads/wk

130

GitHub Stars

33

Maintenance

Last Commit

3yrs ago

Contributors

1

Package

Dependencies

5

Size (min+gzip)

12.4KB

License

BSD-3-Clause

Type Definitions

Tree-Shakeable

No?

Categories

Readme

SGUID

Travis build status Coveralls NPM version Canonical Code Style Twitter Follow

Signed Globally Unique Identifier (SGUID) generator.

Implementation

Use case

SGUID is used to mitigate certain types of DDoS attacks.

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 nameDescription
InvalidSguidErrorThrows if signed message cannot be opened.
UnexpectedNamespaceValueErrorThrows if the namespace contained in the payload does not match the expected namespace.
UnexpectedResourceTypeNameValueErrorThrows 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().

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100