
Research
Security News
The Growing Risk of Malicious Browser Extensions
Socket researchers uncover how browser extensions in trusted stores are used to hijack sessions, redirect traffic, and manipulate user behavior.
Create access, ID, and refresh tokens • Embed hundreds of scopes in a small token string • Zero-IO token verification in your services • Auto-download and cache missing keys • As easy as embassy.parseToken(token).verify()
Explore the docs »
npm install --save embassy
or
yarn add embassy
import { Embassy } from 'embassy'
const embassy = new Embassy({
domainScopes: {
users: {
readEmail: 0,
readProfile: 1,
writeProfile: 2
},
store: {
readPurchaseHistory: 0,
addToCart: 1,
submitOrder: 2,
cancelOrder: 3
}
},
keys: {
myKey: {
privateKey: 'shared-secret',
algorithm: 'HS512'
}
},
issuer: 'api.myapp.com/auth',
audience: 'api.myapp.com'
})
Embassy can be configured to find public and private keys when an unknown key ID is found, and refresh the scopes when an unknown scope is encountered. Always run smoothly without forced restarts or configuration updates. See the options »
const token = embassy.createToken({
sub: 'userid',
email: 'user@email.com'
})
const tokenString = await token.sign('myKey')
// Token expires in an hour by default
embassy.createToken docs • token.sign docs
const token = embassy.parseToken(bearerToken)
const claims = await token.verify() // Throws if invalid, expired, etc
console.log(`New request from ${claims.email}`)
embassy.parseToken docs • token.verify docs
const token = embassy.createToken({
sub: 'userid',
email: 'user@email.com'
})
const tokenString = await token.sign('myKey', {
audience: 'api.myapp.com/auth', // Prevent this from being used as an access token
expiresInSecs: 3600 * 24 * 365 // Make it last for a year
})
embassy.createToken docs • token.sign docs
const token = embassy.parseToken(bearerToken)
const claims = await token.verify({
audience: 'api.myapp.com/auth'
}) // Throws if invalid, expired, wrong audience, etc
console.log(`Checking if ${claims.email} is still in good status...`)
embassy.parseToken docs • token.verify docs
// One at a time
await token.grantScope('user|readEmail')
// Many at a time
await token.grantScopes(['user|readProfile', 'user|writeProfile'])
// You can separate the domain
await token.grantScope('store', 'readPurchaseHistory')
// Or pass an entire domain-to-scopes map
await token.grantScopes({
user: ['readProfile', 'writeProfile'],
store: ['addToCart', 'submitOrder']
})
// Signing the token will encode these scopes in a binary format, so a
// single token can hold hundreds of scopes and still stay small!
token.grantScope docs • token.grantScopes docs
Tip: Change "grant" to "revoke" and it does exactly what you'd expect!
// These each resolve with `true` or `false`:
// One at a time
await token.hasScope('user|readEmail')
// Many at a time
await token.hasScopes(['user|readProfile', 'user|writeProfile'])
// You can separate the domain
await token.hasScope('store', 'readPurchaseHistory')
// Or pass an entire domain-to-scopes map
await token.hasScopes({
user: ['readProfile', 'writeProfile'],
store: ['addToCart', 'submitOrder']
})
token.hasScope docs • token.hasScopes docs
console.log(`Request initiated by userId ${token.claims.sub}`)
token.claims.nonce = myNonce
// Token can be signed with no further action
HMAC is a symmetric signing algorithm, which means the same key is used to sign and verify the token. Embassy supports the following HMAC algorithms: HS256
, HS384
, HS512
. Trying to choose? Higher numbers mean more security, but longer tokens and steeper CPU usage. Use HS256
for access tokens since they're short-lived, and consider higher for refresh tokens.
The "shared secret" for HMAC can be any string -- but you should choose a long one! Be sure to keep it private. Never commit it to git, never send it over Slack, never give your CI/CD access to it.
Embassy supports the following RSA and Elliptic Curve signing algorithms: RS256
, RS384
, RS512
, PS256
, PS384
, PS512
, ES256
, ES384
, ES512
. The algorithms sign tokens with a private key that must be kept secret, but verify their authenticity with a public key that can be shared openly.
For most use cases, 256-bit Elliptic Curve keys (ES256) are recommended for access tokens due to their low overhead and high security. The following commands will generate a PEM-formatted key pair appropriate for use with Embassy (replace MyKeyPair
appropriately):
KEY_ID="MyKeyPair"
# Private key
openssl ecparam -genkey -name secp256k1 -noout -out "${KEY_ID}.priv.pem"
# Public key
openssl ec -in "${KEY_ID}.priv.pem" -pubout -out "${KEY_ID}.pub.pem"
Embassy is committed to supporting all active LTE versions of Node.js, and strives to stay updated for new non-LTE releases.
Embassy is Copyright (c) 2017-2021 Tom Shawver, released under the ultra-permissive ISC license. See LICENSE.txt for details.
Created by Tom Shawver in 2016 as convenience layer on top of Auth0's fantastic jsonwebtoken Node.js library. Embassy was rewritten in Typescript in 2021.
Originally created for TechnologyAdvice in Nashville, TN.
[v2.0.4] = 2021-08-16
FAQs
Simple JSON Web Tokens (JWT) with embedded scopes for services
The npm package embassy receives a total of 32 weekly downloads. As such, embassy popularity was classified as not popular.
We found that embassy demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover how browser extensions in trusted stores are used to hijack sessions, redirect traffic, and manipulate user behavior.
Research
Security News
An in-depth analysis of credential stealers, crypto drainers, cryptojackers, and clipboard hijackers abusing open source package registries to compromise Web3 development environments.
Security News
pnpm 10.12.1 introduces a global virtual store for faster installs and new options for managing dependencies with version catalogs.