Vault: the plugin's own secret¶
Available with Kino 0.9.90
vault is apiVersion 28 and arrives with Kino 0.9.90. An older version
refuses these plugins with "This plugin needs a newer version of Kino".
vault lets your plugin read its own sealed secret from the Kino secrets vault. It is a declarative capability (you
export nothing new), it requires identity and never stands alone. The idea: your plugin's secret
config (an API base, request‑signing keys, a token) lives in the vault, not in the code.
"capabilities": ["screen", "identity", "vault"]
The call¶
const secret = await kino.vault.get(); // no arguments; returns the JSON you registered for your plugin
Kino runs the whole exchange from the inside: it proves who the person is on Telegram and attests which signed plugin is
asking (the same machinery as identity: the per‑plugin pseudonym, the device‑key signature, your author
fingerprint and codeHash, and — for a tokenAuthors author — the gate token, with which the vault verifies group
membership live), and reads the secret the vault resolves for your (pluginId, author).
You never see the vault's address, the challenge, nor the pluginId/author it resolves by: Kino fills them from its own
install record, so a plugin can only ever read ITS OWN secret, and a copy re‑signed with a different key resolves a
different (missing) scope. There is no hardcoded fallback: a non‑member, or a re‑signed copy, gets nothing; and rotating
the secret in the vault kills copies that cached an old one.
Because the read is gated by who the person is exactly as identity is, vault rides on identity's consent and adds no
approval of its own — declare both capabilities; Kino even turns identity's switch on for the person on a screen call they
started, so there is nothing extra to approve. Your plugin does not declare the vault's host either: Kino makes the request, not you.
When, and the errors¶
Only inside a call the person started from screen, screenEvent or panelAction (never a timer tick, a job, Home or
search), 6 a minute. It rejects with:
permission_denied— not approved, or the call isn't an allowed one.not_member— the person isn't in the Kino group, or the copy's scope doesn't match.not_found— no secret is registered for your plugin yet.rate_limited/unavailable/not_available— transient (no Telegram validation on this device, or the vault couldn't be reached).
Cache the secret yourself (in kino.storage, ~1 h): each get() is a server round trip plus a live membership check.
A real‑life example¶
kinotvapp/kino-plugin-vault-demo — the smallest plugin that reads
its secret with kino.vault.get() and greets the person with kino.identity, handling every error state. One hand‑written,
heavily commented plugin.js. See also the example plugins.