SGUID
Signed Globally Unique Identifier (SGUID) generator.
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.
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 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 string;
Usage
; const secretKey = '6h2K+JuGfWTrs5Lxt+mJw9y5q+mXKCjiJgngIDWDFy23TWmjpfCnUBdO1fDzi6MxHMO2nTPazsnTcC2wuQrxVQ==';const publicKey = 't01po6Xwp1AXTtXw84ujMRzDtp0z2s7J03AtsLkK8VU=';const namespace = 'gajus';const resourceTypeName = 'article';const resourceIdentifier = 1; const sguid = ; // "pbp3h9nTr0wPboKaWrg_Q77KnZW1-rBkwzzYJ0Px9Qvbq0KQvcfuR2uCRCtijQYsX98g1F50k50x5YKiCgnPAnsiaWQiOjEsIm5hbWVzcGFjZSI6ImdhanVzIiwidHlwZSI6ImFydGljbGUifQ" const payload = ; // {// "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.
; try ; 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()
.