npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ms-token

v6.0.0

Published

utils for makeomatic mservice for encoding/decoding various token types and storing associated metadata with them

Downloads

295

Readme

Token Orchestrator

Build Status codecov

There is a common task that requires one to request challenges to be performed for a specific action. Imagine user, who wants to register for you service and you need to validate an email, or you want to issue an invitation and remove the burden of activation from a user, as well as supply extra meta information with that token. Furthermore, you often need to throttle specific requests and make sure they are not performed more than once in a certain time span. All of these tasks are easily handled by this module

Install me

npm i ms-token -S

API

Module API is pretty simple and contains only 4 functions alongside initialization. When reading docs, keep in mind that anything in [] is an optional prop.

new TokenManager(args)

  • args.backend:
    • name: supported backends include: redis
    • connection: appropriate connector, ioredis instance for redis
    • prefix: optional, used in redis backend as key prefix
  • args.encrypt, used in crypto.createCipher(algorithm, password) when encoding long tokens:
    • algorithm: one of openssl list-cipher-algorithms, example: aes192
    • sharedSecret: The password is used to derive the cipher key and initialization vector (IV). The value must be either a 'binary' encoded string or a Buffer.
const TokenManager = require('ms-token');
const Redis = require('ioredis');
const tokenManager = new TokenManager({
  backend: {
    name: 'redis',
    connection: new Redis(),
    prefix: 'ms-token:',
  },
  encrypt: {
    algorithm: 'aes256',
    sharedSecret: Buffer.from('incredibly-long-secret-ooooohooo'),
  },
});

tokenManager.create(args)

Use this to create challenge token, which should be sent to user for verification purposes.

Accepts:

  • args.action: unique action name, non-empty string
  • args.id: unique request identification. For instance, if you are going to send this to an email, use email as id. If this is going to be a token sent to the phone - use normalized phone number. Combination of action & id grants access to secret, while secret grants access to all associated metadata
  • [args.ttl]: token expiration, in seconds
  • [args.throttle]:
    • true: would be equal to args.ttl, in that case ttl must be defined
    • Number: do not allow creating token for args.{action,id} combo for Number amount of seconds. Sometimes you want throttle to be small (60 seconds), and ttl to be 15 mins (text messages), or 2 hours and 24 hours (emails)
  • [args.metadata]: Mixed content, must be able to JSON.stringify it
  • [args.secret]:
    • true, default. in that case secret would be automatically generated and would include encrypted public data + generated secret
    • false, do not generate secret. In that case it would simply use action + id for verification/unlocking
    • Object:
      • type: enumerable, acceptable values are: alphabet, number, uuid (default uuid)
      • [alphabet]: string containing characters that are allowed to be used in the secret. Only used in alphabet mode
      • [length]: length of generated secret, only used in alphabet and number mode
      • [encrypt]: defaults to true for uuid. If true - then returned token includes action, id & generated secret encrypted in it. That token alone is enough for verification function. If false - it returns plain text generated secret, you must pass action, id and secret to verification function in order for it to succeed
  • [args.regenerate]: defauls to false. If set to true would allow usage of .regenerate() API by returning uid of this challenge

Returns Object:

  • id: id from args
  • action: action from args
  • [uid]: token unique identificator, when regenerate is true
  • [secret]: send secret to user for completing challenge (for instance via SMS). Secret is not present if was set to false

tokenManager.info(args)

Returns associated data for an already created token. It doesn't perform any verifications. This action should be considered a system action, which could be used for debugging purposes.

Input:

  • args, must have one of uid, args.action and args.id combo or args.secret + args.encrypt combo
  • args.uid: String
  • args.action: String
  • args.id: String
  • args.secret: String
  • args.encrypt: Boolean - true is secret must be encrypted, false otherwise. If false then id and action must be supplied alongside secret

Response:

  • Object: associated metadata with a given input

tokenManager.regenerate(uid)

Works with both uid OR action& id combo. Sometimes challenge token might not reach the user and the user would want to ask for another challenge token. Idea of this is to accept public challenge uid, which would use previous data passed in .create(args) and generate new secret based on this. Can only be used when regenerate was set to true on the .create(args) action

Input:

  • uid - uid from .create(args), when regenerate was set to true

Response:

  • String: newly generated secret, either plain-text or encrypted based on what was passed earlier in .create(args)

tokenManager.verify(args, [opts])

Used for completing challenge by verifying user input.

Accepts:

  • args as String, we would attempt to decode & verify in according with encryption settings
  • args as Object:
    • args.action - action from .create()
    • args.id - id from .create()
    • args.token - secret from .crete() return value
  • [opts] as Object:
    • opts.erase: Defaults to true. if true, when verification succeeds - associated throttle is removed, as well as any notion of this token
    • opts.log: if true, logs attempt time.
    • opts.control: verifies that decrypted args contains same values
      • opts.id -> checks id
      • opts.action -> checks action

Response, always Object in case of successful verification:

  • id
  • action
  • uid
  • secret
  • created
  • settings
  • metadata
  • isFirstVerification - whether this was a first successful verification
  • verified - timestamp when it was verified

Otherwise rejects promise with an error

tokenManager.remove(args)

  • args as String, we would attempt to decode & verify in according with encryption settings
  • args as Object:
    • args.uid - either uid OR action & id combination
    • args.action - action from .create()
    • args.id - id from .create()