Package Information
Available Nodes
Documentation generating…
Documentation
n8n-nodes-unwrap
Paste any token or encoded string. Unwrap finds out what it is, decodes it layer by layer, and verifies JWT signatures. It also goes the other way: signs JWTs, encodes, hashes (and HMACs) and encrypts.
| Operation | What it does |
|---|---|
| Decode | Detects the format and decodes it |
| Verify JWT | Checks signature and dates |
| Sign JWT | Creates a signed JWT |
| Encode | Base64, hex, URL, gzip/deflate, Basic Auth |
| Hash | SHA, MD5 or HMAC, with constant-time compare |
| Encrypt / Decrypt | AES-256-GCM with your key, on a value or on some fields |
| Verify Webhook | GitHub, Stripe, Slack, Shopify and Standard Webhooks signatures |
| Generate | UUID, random secret / AES key, password, TOTP (2FA) code |
"Bearer eyJhbGciOiJSUzI1NiIs…" → { type: "jwt", header, payload, expiresAt, expired: false, verified: false }
"H4sIAAAAAAAA%2F6tWSlSyMjQ…" → { type: "json", value: {…}, layers: ["url", "base64", "gzip"] }
"Basic YW5hOnMzY3IzdA==" → { type: "basic", username: "ana", password: "s3cr3t" }
"5e884898da28047151d0e56f8dc…" → { type: "hash", algorithms: ["SHA-256", …] }
Install
In n8n, go to Settings → Community Nodes → Install and enter n8n-nodes-unwrap.
Decode
Detects the format and peels every layer it finds: URL-encoding, base64/base64url, hex, gzip, zlib and raw deflate. It stops at something it recognizes, at plain text, or after Max Layers (5).
| Type | What you get |
|---|---|
jwt |
header, payload, issuedAt, notBefore, expiresAt, expired, expiresInSeconds, verified: false |
jwe |
header only: the payload is encrypted |
paseto |
public: the payload (not verified). local: encrypted |
fernet |
issuedAt only: the payload is encrypted |
basic |
username, password (needs the Basic prefix) |
json, saml, xml, text |
the decoded value |
hash |
the likely algorithms (bcrypt, Argon2, MD5, SHA-1, SHA-256…). Hashes cannot be decoded |
uuid |
version |
binary |
the bytes, when you force a format and the result is not text |
unknown |
not a known format. Often an opaque access token: only the server that issued it can read it |
layers always lists what was peeled, in order.
Detection is a guess. A short value can be valid hex and valid base64 at the same time. Unwrap only accepts a layer when the result makes sense (readable text or compressed data), but if it guesses wrong, set Format to the one you know.
[!WARNING]
Decode does not check signatures. Anyone can create a JWT with any content. Before trusting a token to grant access, use Verify JWT.
Verify JWT
Checks the signature and the dates. The result has valid: true, or valid: false with a reason you can test in an IF:
| reason | Meaning |
|---|---|
invalid_signature |
the signature does not match the key |
expired / not_yet_valid |
outside exp / nbf (see Clock Tolerance) |
issuer_mismatch / audience_mismatch |
iss / aud not in the accepted list |
alg_not_allowed |
the token's algorithm is not allowed for this key |
key_mismatch |
the key is of the wrong kind for the algorithm |
no_matching_key |
no JWKS key has the token's kid |
malformed |
not a signed JWT |
With If Invalid → Stop With an Error, an invalid token stops the workflow instead.
Keys:
- Credential: the JWT Auth credential that comes with n8n (the same one the native JWT node uses). Passphrase for HS256/384/512, PEM Key for RS, PS, ES and EdDSA: a public key, a certificate, or a private key (only its public half is used).
- JWKS URL: the public keys published by the issuer, for example
https://your-tenant.auth0.com/.well-known/jwks.json. An OpenID configuration URL (…/.well-known/openid-configuration) works too. Keys are cached for 10 minutes. When a token has akidthat is not in the cache, the JWKS is fetched again (at most every 30 seconds), so key rotation works.
Safe defaults:
- A passphrase only checks HS256/384/512 and a public key only checks public key algorithms. This blocks the attack where a token is signed with HS256 using the public key as the secret.
alg: noneis never accepted.- Narrow it further with Allowed Algorithms, and check Issuer and Audience whenever you know them.
Sign JWT
Write the claims in Payload and pick the JWT Auth credential: a passphrase signs HS256/384/512, a PEM private key signs RS, PS, ES or EdDSA. The algorithm comes from the credential unless you set Algorithm in the options.
iat is set to now and exp to now + Expires In (3600 seconds by default, 0 for no expiration), unless the payload already has them. Issuer, Audience and Key ID set iss, aud and the kid header.
Output: token, header, payload, expiresAt.
Encode
The reverse of Decode: Base64, Base64url, Hex, URL-encoded, Gzip + Base64, Deflate (zlib) + Base64, raw Deflate + Base64 (SAML redirect), and a Basic Auth header (Value is the username). An object becomes JSON first.
Hash
MD5, SHA-1, SHA-256/384/512 and SHA3-256/512, in hex, base64 or base64url. Turn on HMAC to sign with the Unwrap Secret credential.
Compare With checks a given hash in constant time and adds matches: true/false. It ignores case for hex and a sha256= style prefix, so it checks webhook signatures directly:
Webhook (Raw Body) → Unwrap: Hash, SHA-256, HMAC on, Value {{ $json.body }},
Compare With {{ $json.headers["x-hub-signature-256"] }} → IF matches
Hash the exact body the sender signed: a body parsed and turned back into JSON can differ (spaces, key order).
Bcrypt and Argon2 are not included: they would need an extra library. Decode still recognizes them.
Encrypt / Decrypt
AES-256-GCM with the Unwrap Secret credential. Only who has the key can read the result, and any change to it makes Decrypt fail. Decrypt gives back JSON as an object.
The credential's Secret Format:
- Passphrase: any text. Each message gets a random salt and the key comes from scrypt (N=16384, r=8, p=1). About 50 ms per item.
- Hex / Base64: a raw 32-byte key, fast. Generate one with
openssl rand -hex 32.
The output is base64 of [salt (16 bytes, passphrase only)] + IV (12) + auth tag (16) + ciphertext, so other systems can decrypt it too.
Target → Fields of the Item encrypts only some fields, in place, and keeps the rest readable (useful for personal data such as CPF or card numbers):
Fields: cpf, card.number
{ name: "Ana", cpf: "123.456.789-00", card: { number: 4111, brand: "visa" } }
→ { name: "Ana", cpf: "pX3k…", card: { number: "9fQa…", brand: "visa" } }
Decrypt with the same fields gives the original item back, with numbers, objects and lists as they were. Missing fields are skipped.
[!WARNING]
Losing the secret means losing the data. Changing the Secret Format makes old values unreadable.
Verify Webhook
Checks a webhook signature exactly as each provider documents it, with the secret in the Unwrap Secret credential:
| Provider | Headers | Notes |
|---|---|---|
| GitHub | X-Hub-Signature-256 |
|
| Shopify | X-Shopify-Hmac-Sha256 |
|
| Slack | X-Slack-Signature, X-Slack-Request-Timestamp |
the Signing Secret |
| Stripe | Stripe-Signature |
the whsec_… endpoint secret, as is |
| Standard Webhooks | webhook-* or svix-* |
Svix, Clerk, Resend…: the whsec_… secret, as is |
In the Webhook node, turn on Raw Body: the signature is over the exact bytes that arrived, and Unwrap reads them from the data binary. Headers defaults to {{ $json.headers }}.
For Stripe, Slack and Standard Webhooks, Max Age (300 s) rejects old webhooks, so a captured request cannot be sent again. The result is valid: true (with the timestamp), or valid: false with a reason: invalid_signature, missing_header or too_old.
Generate
- UUID (v4)
- Random Secret / AES Key: random bytes in hex, base64 or base64url. 32 bytes in hex is a key for the Unwrap Secret (Secret Format: Hex).
- Password: lower and upper case, digits and (optionally) symbols, at least one of each, without look-alikes (0/O, 1/l/I).
- TOTP Code (2FA): the current code of an authenticator app, from n8n's TOTP credential (the base32 secret the service shows when you set up 2FA). Output:
codeandsecondsLeft.
Explain With AI
Turn on Explain With AI in Decode or Verify JWT and a Chat Model input appears under the node. Connect any model (OpenAI, Anthropic, Gemini, Ollama…) and each result gets an explanation:
Access token from Acme's Auth0 (iss https://acme.auth0.com/) for user 42, with the scope read:invoices. It expires in 12 minutes. It was only decoded, not verified: use Verify JWT with https://acme.auth0.com/.well-known/jwks.json before trusting it.
When the format is unknown, the model suggests what it probably is; when Verify fails, it explains the reason and how to fix it.
What the AI can and cannot do:
- It only explains. Decoding, signatures, dates and
validare computed by code, and the explanation is a separate field: a model that says "valid" changes nothing. - Signatures, raw tokens, Basic Auth passwords and secrets are never sent. For unknown values only the shape goes (length, kinds of characters, the first characters).
- Mask Personal Data (on by default) hides emails, long numbers (CPF, phone, card) and fields like
name,email,cpf,address,passwordbefore sending. Turn it off only with a model you trust, such as a local one. - If the model fails (rate limit, timeout), the item keeps its result and gets
explanationErrorinstead. - One model call per item: with many items, it costs time and tokens.
Options: Explanation Language (default English) and Extra Instructions for AI.
AI Agent tool
Unwrap can be connected as a tool of the AI Agent node, so the agent can decode or verify a token when it needs to.
For a self-hosted n8n, community nodes can be used as tools only with this environment variable:
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
Tokens are sensitive: what the tool returns goes to the language model. Prefer Verify JWT results, and avoid sending live tokens to an external model if that matters for you.
Build
npm install
npm run build
npm test
npm run lint