نود Crypto در N8N

نود Crypto در N8N

نود Crypto در n8n ابزار اصلی شما برای انجام عملیات رمزنگاری رایج مثل هش کردن (Hash)، تولید HMAC، و در برخی سناریوها رمزنگاری/رمزگشایی است. اگر می‌خواهید امضا (Signature) برای API بسازید، وبهوک‌ها را اعتبارسنجی کنید، یا داده حساس را قبل از ذخیره‌سازی تغییر شکل دهید، Crypto یکی از کاربردی‌ترین نودها در ورکفلوهای واقعی است.

معرفی نود در N8N

نود Crypto برای انجام تبدیل‌های رمزنگاری روی داده‌های ورودی به کار می‌رود. این نود معمولاً در میانه یا انتهای ورکفلو قرار می‌گیرد تا خروجیِ استاندارد و امن (مثل هش/امضا) تولید کند.

  • کارکرد اصلی: تولید Hash، HMAC، و برخی تبدیل‌های رمزنگاری بر پایه الگوریتم‌ها و فرمت‌های خروجی
  • دسته‌بندی نود: Function / Data Transformation (نود ابزاری برای پردازش داده، نه یک اتصال به سرویس بیرونی)
  • اهمیت در ورکفلوها:
    • افزایش امنیت (امضا و اعتبارسنجی درخواست‌ها)
    • یکپارچه‌سازی با APIهایی که امضای HMAC می‌خواهند
    • ناشناس‌سازی یا استانداردسازی داده‌ها (هش کردن ایمیل/شماره تلفن قبل از ذخیره)

موارد استفاده

1) ساخت Signature برای APIهایی که HMAC می‌خواهند

بسیاری از APIها برای احراز اصالت درخواست، از HMAC استفاده می‌کنند. معمولاً باید یک رشته (مثلاً ترکیب timestamp + مسیر درخواست + بدنه) را با Secret امضا کنید و امضا را در Header بفرستید.

  • نودهای پیشنهادی در کنار Crypto:
    • Date & Time برای تولید timestamp
    • Set یا Code برای ساختن رشته امضا
    • HTTP Request برای ارسال درخواست با هدر امضا

2) اعتبارسنجی امضای Webhook (امن‌سازی ورودی‌ها)

سرویس‌هایی مثل Stripe/GitHub/… امضای درخواست را ارسال می‌کنند. شما می‌توانید بدنه خام را HMAC کنید و با امضای ارسالی مقایسه کنید تا مطمئن شوید درخواست جعلی نیست.

  • ترکیب کاربردی:
    • Webhook برای دریافت درخواست
    • Crypto برای تولید HMAC از payload
    • IF برای مقایسه امضای تولیدشده با امضای هدر

3) هش کردن داده برای جلوگیری از ذخیره اطلاعات حساس

اگر نیاز دارید شناسه‌ای یکتا از ایمیل/شماره بسازید، می‌توانید آن را Hash کنید و فقط هش را در دیتابیس ذخیره کنید.

  • ترکیب کاربردی:
    • Google Sheets یا Postgres برای ذخیره
    • Crypto برای هش کردن فیلد حساس
    • Merge برای اتصال داده خام و داده هش شده (در صورت نیاز)

4) تولید کلید/توکن‌های قابل استفاده در سیستم داخلی

برای ساخت tokenهای ساده (غیر JWT) می‌توانید از هش روی ترکیب مقادیر (مثل userId + timestamp + secret) استفاده کنید تا یک شناسه قابل اتکا بسازید.

پارامترها و تنظیمات

نام دقیق فیلدها ممکن است با نسخه n8n کمی تفاوت داشته باشد، اما مفاهیم و کاربردها ثابت هستند. در ادامه پارامترهای رایج نود Crypto با توضیح عملی آمده است.

Operation (عملیات)

  • نام پارامتر: Operation
  • نوع داده: گزینه‌ای (Select)
  • توضیح: نوع عملیات رمزنگاری را مشخص می‌کند (مثل Hash یا HMAC و گاهی Encrypt/Decrypt بسته به پیاده‌سازی/نسخه).
  • مثال عملی: انتخاب HMAC برای ساخت امضای درخواست API.

Algorithm (الگوریتم)

  • نام پارامتر: Algorithm
  • نوع داده: گزینه‌ای (Select)
  • توضیح: الگوریتم هش/امضا (مثل sha256، sha1، md5 و…)
  • مثال عملی: برای اکثر APIهای جدید، sha256 انتخاب استانداردتری است.

Value / Data (داده ورودی برای رمزنگاری)

  • نام پارامتر: Value (یا Data / Input)
  • نوع داده: String
  • توضیح: رشته‌ای که باید Hash یا HMAC شود. معمولاً از Expression برای خواندن از JSON ورودی استفاده می‌شود.
  • مثال عملی: {{$json.email}} یا {{$json.payload}}

Secret / Key (کلید/سکرت برای HMAC یا رمزنگاری)

  • نام پارامتر: Secret / Key
  • نوع داده: String
  • توضیح: در HMAC یا رمزنگاری به یک کلید نیاز دارید. بهتر است این مقدار از Credentials یا Environment Variables خوانده شود و داخل ورکفلو هاردکد نشود.
  • مثال عملی: {{$env.MY_API_SECRET}}

Encoding / Output Format (فرمت خروجی)

  • نام پارامتر: Encoding / Output
  • نوع داده: گزینه‌ای (Select)
  • توضیح: تعیین می‌کند خروجی به چه فرمتی برگردد (معمولاً hex یا base64).
  • مثال عملی: اگر API امضا را Base64 می‌خواهد، خروجی را base64 بگیرید.

Input Encoding (کدگذاری ورودی)

  • نام پارامتر: Input Encoding
  • نوع داده: گزینه‌ای (Select)
  • توضیح: اگر داده ورودی شما خودش به صورت base64/hex است، باید اینجا درست تنظیم شود؛ در غیر این صورت خروجی غلط می‌شود.
  • مثال عملی: اگر payload شما base64 است، Input Encoding را base64 بگذارید تا ابتدا decode شود.

نکات مهم هنگام پیکربندی

  • رشته امضا (string to sign) دقیقاً باید مطابق مستندات API ساخته شود؛ حتی یک فاصله یا ترتیب فیلدها می‌تواند امضا را نامعتبر کند.
  • در HMAC، تفاوت hex و base64 در خروجی بسیار رایج‌ترین دلیل عدم تطابق امضا است.
  • اگر داده شما JSON است، قبل از امضا کردن مشخص کنید باید raw body امضا شود یا stringify شده. برخی سرویس‌ها فقط raw body را قبول می‌کنند.
  • Secret را در نود Set/Code ننویسید؛ از $env یا Credentials استفاده کنید.

ورودی‌ها و خروجی‌ها

ورودی (Input)

این نود معمولاً از آیتم‌های ورودی n8n استفاده می‌کند و از داخل هر آیتم، رشته‌ای را برای عملیات رمزنگاری برمی‌دارد. ورودی می‌تواند هر JSON باشد، به شرطی که شما Value را با Expression به رشته درست متصل کنید.

نمونه ورودی JSON

ساختار نمونه آیتم ورودی:

{  "email": "user@example.com",  "timestamp": 1736000000,  "payload": "{"amount":100,"currency":"USD"}"}

خروجی (Output)

خروجی معمولاً همان آیتم ورودی به‌علاوه یک فیلد جدید (مثلاً hash یا signature) است که نتیجه Crypto در آن قرار دارد. نام فیلد خروجی بسته به تنظیمات یا پیاده‌سازی نود می‌تواند متفاوت باشد، اما در عمل شما آن را در ادامه ورکفلو مصرف می‌کنید (مثلاً در Header نود HTTP Request).

نمونه خروجی JSON

{  "email": "user@example.com",  "timestamp": 1736000000,  "payload": "{"amount":100,"currency":"USD"}",  "signature": "f2a1b7...9c"}

نکات پیشرفته و ترفندها

1) ساختن String To Sign به شکل دقیق با نود Code

اگر API شما می‌گوید رشته امضا باید مثلاً timestamp + “n” + method + “n” + path + “n” + body باشد، بهترین کار این است که قبل از Crypto با نود Code آن را بسازید تا کنترل کامل روی newlineها و ترتیب فیلدها داشته باشید.

2) امضای بدنه خام Webhook

برخی سرویس‌ها امضا را روی raw body حساب می‌کنند، نه روی JSON پارس‌شده. اگر بدنه در n8n تغییر کند (مثلاً دوباره stringify شود)، امضا متفاوت می‌شود. در این حالت باید مطمئن شوید همان رشته‌ای که سرویس امضا کرده را شما هم امضا می‌کنید.

3) یکسان‌سازی Encoding در کل مسیر

  • اگر خروجی Crypto را به Header می‌فرستید، مطمئن شوید API انتظار hex یا base64 دارد.
  • اگر API prefix می‌خواهد (مثلاً sha256= یا v1=) آن را با Set/Code اضافه کنید، نه داخل Crypto.

4) جلوگیری از افشای Secret در لاگ‌ها

  • Secret را در داده‌های خروجی نگه ندارید.
  • در صورت نیاز به Debug، فقط طول امضا یا چند کاراکتر اول/آخر را لاگ کنید.

محدودیت‌ها و خطاها

محدودیت‌ها

  • نود Crypto برای عملیات رمزنگاری متداول مناسب است، اما جایگزین کامل پیاده‌سازی‌های پیچیده (مثل مدیریت کامل کلیدها، چرخش کلید، یا استانداردهای خاص سازمانی) نیست.
  • اگر سرویس مقصد امضای بسیار خاص یا الگوریتم کمتر رایج بخواهد، ممکن است نیاز به نود Code و کتابخانه‌های داخلی محیط Node.js (در حد مجاز n8n) داشته باشید.
  • در سناریوهای امضای Webhook، چالش اصلی معمولاً دسترسی به raw body است، نه خود Crypto.

خطاهای رایج و راه‌حل‌ها

  • Signature mismatch
    • علت‌های رایج: اشتباه بودن encoding خروجی (hex/base64)، اشتباه در string to sign، تفاوت raw body با JSON stringify، یا secret اشتباه
    • راه‌حل: مستندات API را خط‌به‌خط چک کنید، string to sign را دقیقاً مطابق نمونه‌ها بسازید، encoding را هماهنگ کنید
  • خروجی خالی یا نامعتبر
    • علت‌های رایج: مقدار Value خالی است یا Expression به مسیر غلط اشاره می‌کند
    • راه‌حل: با نود Set یا Code مقدار ورودی را چاپ/بررسی کنید و مطمئن شوید رشته نهایی ساخته می‌شود
  • کاراکترهای اضافه مثل فاصله یا newline
    • علت‌های رایج: هنگام ساخت رشته امضا، وجود فاصله/خط جدید ناخواسته
    • راه‌حل: رشته را در Code با کنترل کامل بسازید و در صورت نیاز trim را با دقت اعمال کنید (بعضی APIها به trim حساس‌اند)

ایده ها

  • ساخت سیستم تایید اصالت وبهوک‌ها: دریافت Webhook، تولید HMAC، مقایسه با هدر و فقط در صورت معتبر بودن ادامه پردازش
  • ناشناس‌سازی داده‌های مشتریان قبل از ذخیره در Google Sheets یا Airtable با Hash کردن ایمیل/شماره
  • ساخت امضای درخواست برای APIهای مالی/صرافی/پرداخت و ارسال امن درخواست با HTTP Request
  • تولید شناسه یکتای قابل بازتولید برای Deduplication: هش کردن ترکیب (email + date + campaignId) و جلوگیری از ثبت تکراری
  • ساخت توکن یک‌بارمصرف ساده برای لینک‌های داخلی: هش کردن (userId + timestamp + secret) و اعتبارسنجی آن در یک ورکفلو دیگر

منابع و مستندات اصلی

دسته بندی: N8N برچسب ها:

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

20 + هجده =