Trezor na přístupy

Přehled

Typ položky secret umožňuje vybírat od klientů citlivé údaje — hesla, API klíče, přístupy k hostingu, tokeny externích služeb — a držet je šifrované. Dešifrovaný text lze odhalit přesně jednou, a to jednou ze dvou cest: agent zavolá get_intake_results (přes MCP nebo GET /v1/intakes/:id/results), nebo vlastník účtu klikne na Zobrazit u položky v dashboardu (POST /v1/intakes/:id/items/:key/reveal). Obě cesty čerpají ze stejného jednorázového odhalení — kdo je první, dostane hodnotu, a druhá strana se dozví, že už byla odhalena.

Trezor na přístupy je k dispozici v tarifech Solo, Studio a Agency. Pokus zařadit položku typu secret na tarifu Free vrátí chybu plan_required.

Proč jsou přístupy jiné

Běžné položky (text, soubor, barva, URL) ukládají odeslané hodnoty do databáze v otevřené podobě. U necitlivého obsahu je to v pořádku.

Položky typu secret fungují jinak:

1. Klient vyplní na portálu zamaskované pole
2. Hodnota se přenese přes HTTPS a hned po přijetí se zašifruje přes libsodium sealed box veřejným klíčem BriefGate, ještě než se cokoli zapíše do databáze; v plaintextu se nikdy neukládá
3. V databázi je uložený jen ciphertext — plaintext existuje v paměti serveru jen po dobu zapečetění a pak znovu jen při jednorázovém odhalení; nikdy se nezapisuje na disk ani do logů
4. Privátní klíč existuje pouze v prostředí serveru, nikdy ne v databázi
5. Ani kompletní dump databáze hodnoty neodhalí

Privátní klíč je 32bajtový tajný klíč páru libsodium držený v prostředí serveru.

Zadání položky typu secret

Zařaďte ji do items[] při volání define_intake:

{
  "key": "wp_admin",
  "type": "secret",
  "label": "Přístupy do administrace WordPressu",
  "help": "Vaše uživatelské jméno a heslo. Šifrované při uložení, vývojáři se zobrazí jen jednou."
}

Na portálu klient uvidí:

• Zamaskované heslové pole s přepínačem zobrazit/skrýt
• Ikonu zámku
• Poznámku: „Šifrováno — zobrazí se pouze jednou vašemu dodavateli“

Po odeslání se hodnota přes portál nedá nijak získat zpět.

Průběh jednorázového odhalení

Krok 1. Odhalení lze vyvolat třemi způsoby:

• Agent zavolá get_intake_results (přes MCP, nebo GET /v1/intakes/:id/results s API klíčem, který má scope secrets:read nebo admin). Tím se jedním voláním odhalí všechny položky typu secret na daném sběru podkladů.
• Vlastník účtu klikne na Zobrazit u jedné položky v dashboardu, což zavolá POST /v1/intakes/:id/items/:key/reveal (jen s dashboardovou session, vyžaduje roli vlastníka). Tím se odhalí jedna položka.
• Vlastník účtu (nebo API klíč se scopem secrets:read/admin) stáhne ZIP sběru podkladů s include_secrets=true (GET /v1/intakes/:id/download). Tím se odhalí všechny dosud neodhalené položky typu secret a jejich hodnoty se zahrnou do podklady.pdf — viz Stažení všeho v ZIPu.

Všechny tři cesty čerpají ze stejného jednorázového odhalení uloženého u samotného přístupu: kdo je první, dostane dešifrovaný text, a ostatní se dozví, že už byl odhalen. Potvrzovací dialog v dashboardu to vlastníkovi řekne ještě před kliknutím na Zobrazit: „Credentials are shown once. After this it cannot be retrieved again — by you, or by an agent using an API key.“ (Přístupy se zobrazí jen jednou. Poté už je nelze znovu získat — ani vámi, ani agentem přes API klíč.)

Při prvním volání kteroukoli cestou obsahuje odpověď dešifrovaný text. Přes get_intake_results / GET /v1/intakes/:id/results vypadá záznam položky ve results takto:

{
  "wp_admin": {
    "value": "admin:MyPassword123",
    "one_time": true,
    "first_reveal": true,
    "expires_at": "2026-08-15T10:00:00Z"
  }
}

Přes dashboardové POST /v1/intakes/:id/items/:key/reveal je odpověď:

{
  "key": "wp_admin",
  "value": "admin:MyPassword123",
  "first_reveal": true,
  "expires_at": "2026-08-15T10:00:00Z"
}

Krok 2. Uložte si hodnotu do vlastního správce hesel. Jinou příležitost mít nebudete, ať už přišla kteroukoli cestou.

Myslí se to doslova: jakmile se hodnota jednou přečte, je pryč bez ohledu na to, který endpoint ji přečetl. Jediná úleva je úzká — stejný volající (stejný API klíč, nebo stejná dashboardová session vlastníka) může svoje vlastní volání zopakovat do pěti minut a dostane tutéž hodnotu, aby přerušené spojení mezi naší odpovědí a vaším procesem přístup nezničilo. Tahle lhůta se sleduje podle identity volajícího, takže si ji API klíč a dashboardové odhalení mezi sebou nesdílejí — pokud hodnotu odhalil agent přes API, vlastník o pár vteřin později kliknutím na Zobrazit dostane „už bylo odhaleno“, a naopak. Jakýkoli jiný volající, nebo tentýž volající později, nedostane nic.

Při dalším volání get_intake_results položka z results úplně vypadne (její hodnota je null) a meta vysvětlí proč:

{
  "wp_admin": {
    "secret_unavailable": true,
    "reason": "Already revealed — secrets are one-time and cannot be shown again.",
    "revealed_at": "2026-07-16T09:14:02Z"
  }
}

Další odhalení z dashboardu místo toho dostane:

{
  "key": "wp_admin",
  "value": null,
  "already_revealed": true,
  "revealed_at": "2026-07-16T09:14:02Z",
  "message": "This credential was already revealed. Secrets are shown once and cannot be shown again."
}

Když hodnotu ztratíte, cesta zpět je stejná jako když propadne: požádejte klienta přes request_revision, aby ji zadal znovu.

Když údaj propadne (30 dní po odeslání, na daném nasazení nastavitelné přes SECRETS_TTL_DAYS) dřív, než si ho vyzvednete:

Zavolejte request_revision(intake_id, "wp_admin", "Přístupy propadly, než jsme si je stihli vyzvednout. Prosím zadejte je znovu.") a klient je vyplní znovu.

API klíč použitý s get_intake_results potřebuje k odhalení hodnoty scope secrets:read nebo admin. Bez něj GET /v1/intakes/:id/results pořád uspěje — ostatní položky se vrátí normálně — ale každá položka typu secret vypadne z results a meta ji označí secret_unavailable: true, reason: "Scope 'secrets:read' or 'admin' required.".

Auditní stopa

Každé odhalení se zaznamená s údaji:

• Kdo — API klíč, který zavolal get_intake_results (actor_type: "api_key"), nebo vlastník účtu, který klikl na Zobrazit v dashboardu (actor_type: "user")
• IP adresa volajícího
• Časové razítko
• intake_id a item_key, vnořené v meta

Zobrazení auditního logu (jen s dashboardovou session, vlastník účtu — API klíč tenhle endpoint zavolat nemůže):

GET /v1/audit?action=secret.revealed

Filtrování na jeden sběr podkladů API nepodporuje — intake_id není podporovaný query parametr. Který sběr podkladů a položku daný záznam popisuje, poznáte z jeho meta.intake_id a meta.item_key, takže si to filtrujte sami na klientovi.

Do logu se jen přidává, nelze z něj mazat.

Automatická expirace

Přístupy propadají 30 dní po odeslání položky klientem.

Propadlý údaj má value: null a nedá se získat. Použijte request_revision a nechte klienta zadat ho znovu.

Doporučení pro agenty

Ukládejte okamžitě. Když get_intake_results vrátí položku s first_reveal: true, uložte hodnotu ještě než volání skončí. Přes API už nikdy dostupná nebude.

Ukládejte do správce hesel. Po odhalení dejte hodnotu do svého správce (1Password, Vault, AWS Secrets Manager a podobně). Nezapisujte ji do souboru, nelogujte ji a nedávejte ji do commitu.

Odhalenou hodnotu nikdy nelogujte. Ani na úrovni debug. Pokud váš logger zachytává proměnné, zamaskujte citlivé údaje dřív, než je předáte jakékoli logovací funkci.

Po použití nechte údaj vyměnit. Až přístup doslouží (třeba po nasazení webu), řekněte klientovi, že si ho může změnit. Zachycený údaj byl platný v době sběru; jeho výměna omezí dopad, kdyby se hodnota někde uložila nebezpečně.

Dostupnost