سکرت‌ها

یک پروژهٔ سکرت مجموعه‌ای از سکرت‌هاست، مثلاً همهٔ کلیدهای یک فروشگاه. هر پروژه محیط‌هایی دارد، به‌طور پیش‌فرض پروداکشن (production)، پیش‌نمایش (preview) و توسعه (development)، و هر سکرت در هر محیط مقدار و نسخه‌های خودش را دارد. نام پروژه حروف کوچک، رقم و خط تیره است؛ نام سکرت حروف، رقم و _، تا ۶۴ کاراکتر، و با رقم شروع نمی‌شود (مثل STRIPE_KEY).

cloudhost secrets create shop --rotate-days 90
# created secrets project shop (production, preview, development)
printf %s "$STRIPE_KEY" | cloudhost secrets set STRIPE_KEY --project shop --env production
cloudhost secrets list --project shop
cloudhost secrets get STRIPE_KEY --project shop --env production

مقدار هیچ‌وقت از خط فرمان گرفته نمی‌شود تا در تاریخچهٔ پوسته نماند: آن را از ورودی استاندارد بدهید یا وقتی پرسید تایپ کنید. بدون --env، secrets set مقدار را در همهٔ محیط‌های پروژه می‌گذارد.

# cloudhost.toml
[secrets]
project = "shop"
env = "development"

با بخش [secrets] در فایل پروژه، یا متغیر CLOUDHOST_SECRETS_PROJECT، دیگر لازم نیست هر بار --project بنویسید.

در داشبورد، سکرت‌ها فهرست پروژه‌های سکرت تیم است با تعداد سکرت‌ها، توکن‌ها و خواندن‌های ۳۰ روز گذشته. «ایجاد» از همین‌جا یا از دکمهٔ «ایجاد» بالای صفحه است.

• سکرت‌ها: جدول نام، محیط‌ها (پروداکشن، پیش‌نمایش، توسعه)، نوع (حساس یا ساده)، آخرین تغییر و تغییردهنده؛ افزودن، وارد کردن فایل .env، ویرایش و نمایش مقدار (با تایید دوم).
• نسخه‌ها: تاریخچهٔ هر سکرت در هر محیط با زمان، نویسنده و یادداشت، و «بازگشت به این نسخه».
• توکن‌ها، دسترسی، گزارش، مصرف و تنظیمات (محیط‌ها، یادآوری چرخش، اتصال به فانکشن و برنامه، حذف پروژه).

همهٔ دستورهای بالا --project هم می‌گیرند (پیش‌فرض: فایل پروژه).

cloudhost run --env production -- node server.js
cloudhost run -- npm run dev              # development, or env in [secrets]
# in CI, with a read token instead of signing in:
CLOUDHOST_SECRETS_TOKEN=$TOKEN cloudhost run --project shop --env production -- npm test

run -- مقدارهای همان لحظه را می‌گیرد، روی متغیرهای محیطی فعلی می‌گذارد و فرمان را اجرا می‌کند؛ هیچ فایلی نوشته نمی‌شود. secrets pull برای ابزارهایی است که فقط .env می‌خوانند: سکرت‌های حساس را کنار می‌گذارد و نامشان را در سر فایل می‌نویسد. فایلی را که خودش ننوشته بدون --yes بازنویسی نمی‌کند.

برای سرور، CI یا اسکریپتی بیرون از پلتفرم یک توکن پروژه ایجاد کنید. هر توکن فقط یک پروژه را می‌بیند، فقط‌خواندنی (read) یا با نوشتن (write) است، به همهٔ محیط‌ها یا چند تا می‌رسد و می‌تواند تاریخ انقضا داشته باشد. شکلش chsm_<id>_<secret> است و فقط یک بار نشان داده می‌شود.

cloudhost secrets tokens create ci --project shop --access read --env production --expires 90
# token chsm_3f9a1c2b7d4e_…   (shown once)
cloudhost secrets tokens --project shop
cloudhost secrets tokens revoke 3f9a1c2b7d4e --project shop

توکن هیچ‌وقت بیش از سازنده‌اش دسترسی ندارد، و ایجادش در داشبورد تایید دوم می‌خواهد. توکنی که فقط یک محیط دارد ?env لازم ندارد. ابطال روی همان سرور فوری است و روی بقیه تا ۱۵ ثانیه.

مسیرها زیر /v1/secrets/projects/<project> هستند. مسیرهای مقدار (فهرست، خواندن، ثبت، وارد کردن، چرخش، نسخه‌ها، بازگشت، خروجی) هم توکن پروژه می‌گیرند و هم کلید API تیم؛ مدیریت (پروژه‌ها، محیط‌ها، توکن‌ها، دسترسی، گزارش، مصرف، اتصال) فقط کلید API یا نشست. همه در مرجع API.

curl "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY?env=production" \
  -H "Authorization: Bearer $TOKEN"
# {"name":"STRIPE_KEY","environment":"production","version":3,"type":"sensitive","updated_at":"…","value":"…"}

خطاها {"error": {"code", "message"}} هستند: 401 unauthorized برای توکن نادرست یا باطل، 403 forbidden برای توکن فقط‌خواندنی یا محیطی که توکن به آن نمی‌رسد، 404 not_found برای پروژه یا سکرتی که نیست (یا پروژهٔ دیگری که توکن نمی‌بیند)، 403 step_up_required وقتی نشست داشبورد تایید دوم لازم دارد.

import { Secrets } from "@cloudhost/secrets"

// token: a project token, or CLOUDHOST_SECRETS_TOKEN; project: or CLOUDHOST_SECRETS_PROJECT
const secrets = new Secrets({ token: process.env.SECRETS_TOKEN, project: "shop", env: "production" })

const key = await secrets.get("STRIPE_KEY")
const all = await secrets.all()                 // { NAME: value } of the environment
await secrets.set("LOG_LEVEL", "info", { environments: ["development"], type: "plain" })
await secrets.rollback("STRIPE_KEY", { env: "production", to: 3 })

SDK فقط API بالا را صدا می‌زند و وابستگی ندارد، پس در Node، مرورگر و فانکشن‌ها کار می‌کند. هر خواندن ۶۰ ثانیه در حافظه می‌ماند (cacheTtl)؛ بعد از آن مقدار قبلی فوراً داده می‌شود و مقدار جدید پشت صحنه گرفته می‌شود، پس برنامهٔ در حال اجرا چرخش را در حدود یک دقیقه بی‌راه‌اندازی دوباره می‌بیند. خطاها SecretsError با status و code هستند.

یک فانکشن یا برنامه می‌تواند یک پروژهٔ سکرت را بخواند. مقدارها همراه پیکربندی امضاشدهٔ استقرار به سرورها می‌رسند و فقط در حافظهٔ همان فانکشن باز می‌شوند: نه درخواست شبکه، نه توکن در کد، نه فایل روی دیسک.

cloudhost secrets link --project shop --to my-api                    # env.SECRETS
cloudhost secrets link --project shop --to my-api --mode variables   # each secret as env.NAME
cloudhost secrets unlink --project shop --to my-api

• استقرار پروداکشن مقدارهای محیط پروداکشن را می‌گیرد و پیش‌نمایش‌ها مقدارهای پیش‌نمایش را. محیط توسعه برای run -- و pull روی دستگاه خودتان است.
• در حالت متغیرها، اگر متغیر خود پروژه یا تیم همان نام را داشته باشد، آن برنده است.
• هر فانکشن یا برنامه یک پروژهٔ سکرت می‌خواند. اتصال، دسترسی خواندن محیط‌های پروداکشن و پیش‌نمایش را می‌خواهد، چون مقدارها را به آن کد می‌دهد.
• هر تغییر، چرخش یا بازگشت بی‌استقرار دوباره به فانکشن‌های متصل‌شده می‌رسد. پروژه‌ای را که فانکشنی می‌خواند نمی‌شود حذف کرد؛ اول اتصال را بردارید.

پروژهٔ محدود را فقط مالک‌ها، مدیرها و کسانی که در فهرستش هستند می‌بینند؛ بیلد کردن یا محدود کردن آن و افزودن افراد به فهرست کار مالک یا ادمین است (PUT /v1/secrets/projects/<project>/access/<person> با {"access": "read"|"write"}). عضوی که با گروه دسترسی به چند پروژه محدود شده به سکرت‌ها نمی‌رسد، و کلید یک بیلد هیچ مقداری نمی‌خواند.

هر خواندن، تغییر، چرخش، بازگشت، pull و خروجی، ایجاد و ابطال توکن، تغییر دسترسی و اتصال ثبت می‌شود: زمان، پروژه، سکرت، محیط، نسخه، چه کسی (شخص، کلید API یا توکن) و آدرس IP. مقدار هیچ‌وقت ثبت نمی‌شود. خواندن‌های یکسان در یک دقیقه یک ردیف با شمارش‌اند.

cloudhost secrets audit --project shop --limit 50
curl "https://api.ibel.ai/v1/secrets/projects/shop/audit?secret=STRIPE_KEY&env=production" -H "Authorization: Bearer $KEY"
curl "https://api.ibel.ai/v1/secrets/audit?action=read" -H "Authorization: Bearer $KEY"   # the whole team (owner or admin)

نتیجه صفحه‌به‌صفحه است: next را به‌عنوان before بفرستید.

برای پروژه (--rotate-days) یا هر سکرت (rotate_days) بگویید هر چند روز باید عوض شود. وقتی موعد یک سکرت رسید، فهرست آن را «موعد چرخش» نشان می‌دهد و توسعه‌دهنده‌ها و مدیرهای تیم یک بار در مرکز اعلان و با ایمیل خبر می‌شوند.

printf %s "$NEW_PASSWORD" | cloudhost secrets rotate DB_PASSWORD --project shop --env production
cloudhost secrets rotate WEBHOOK_SECRET --project shop --generate --length 48   # shown once
cloudhost secrets versions DB_PASSWORD --project shop --env production
cloudhost secrets rollback DB_PASSWORD --project shop --env production --to 3

چرخش یک نسخهٔ جدید است؛ بدون مقدار، یک مقدار تصادفی ساخته و یک بار نشان داده می‌شود. بازگشت مقدار نسخهٔ قدیمی را نسخهٔ جدید جاری می‌کند، پس تاریخچه هیچ‌وقت بازنویسی نمی‌شود.

سکرت‌ها، متغیرهای محیطی، نسخه‌ها و گزارش هر تیم در انبارهٔ جدای همان تیم نگه داشته می‌شوند و هر مقدار با کلید همان تیم رمزنگاری می‌شود. این کلید هیچ‌جا کامل نوشته نمی‌شود: به سه بخش تقسیم شده و هر بخش را یکی از سه سرور کلید باز می‌کند که نزد سه ارائه‌دهندهٔ ابری جدا در ایران اجرا می‌شوند. برای باز کردن کلید دو سرور از سه کافی است و یک بخش به‌تنهایی هیچ چیزی دربارهٔ کلید نمی‌گوید.

• یک سرور دزدیده‌شده، یک ارائه‌دهنده یا حتی همهٔ فایل‌های ذخیره‌شده با هم برای خواندن مقدارهای شما کافی نیست.
• سرورهای کلید کلید خود را فقط در حافظهٔ قفل‌شده نگه می‌دارند (بدون دیسک، بدون swap)، فقط به سرویس سکرت‌های ما با گواهی دوطرفه پاسخ می‌دهند و هر درخواست را ثبت می‌کنند.
• اگر یکی از سرورهای کلید از کار بیفتد، سکرت‌ها بی‌وقفه کار می‌کنند.
• هر سرور اجرا فقط مقدارهای فانکشن‌ها و برنامه‌هایی را می‌گیرد که روی خودش اجرا می‌شوند، رمزشده برای خودش، و آن‌ها را فقط در حافظه نگه می‌دارد.
• کلید تیم را می‌توان چرخاند؛ همهٔ مقدارها با کلید جدید دوباره رمزنگاری می‌شوند و نسخه‌ها و توکن‌ها دست نمی‌خورند.

در پلن رایگان، بیش از سهم رایگان ماه، خواندن و نوشتن تا ماه بعد پذیرفته نمی‌شود، مثل بقیهٔ سقف‌های پلن رایگان. GET /v1/secrets/projects حدهای پلن تیم را هم می‌دهد.

خواندن env.SECRETS و حالت متغیرها در فانکشن‌ها حساب نمی‌شود. قیمت‌ها و سهم رایگان هر پلن در صفحهٔ قیمت‌ها است؛ مصرف ماه جاری را cloudhost secrets usage یا GET /v1/secrets/usage نشان می‌دهد. متغیرهای محیطی خود پروژه‌ها رایگان می‌مانند.