Secrets vault: store a secret for your plugin¶
Hosted Kino service
The vault lives at secrets.kinoverse.app and builds on Identity with a challenge
(apiVersion 15; the attestation for authors that are not Kino arrives with Kino 0.9.88). You need no
server of your own: you store a JSON from a web panel and your plugin reads it at runtime.
The vault keeps one JSON secret per repository —an API key, a config recipe, whatever your plugin needs to talk to its
source— without it living in the public repository. Only people who are in the Kino group get it; anyone else does not. The
secret is stored encrypted, and the only one who sees it in the clear is your plugin, on a member's device, at the moment of
use.
It helps when your plugin needs a value you do not want to publish (and that a copy should not be able to reuse), but you do not want —or cannot— run a server. If you already have your own server, you do not need it: do the Identity flow yourself.
Moderate secrets, not critical
The vault stops people who are not members and copies re-signed with another key, but not a determined forger (see
What it protects and what it doesn't). Keep moderate secrets in it —better than leaving them in the public
plugin.js— not keys that, leaked, do serious harm.
1. Store the secret (the panel)¶
Go to https://secrets.kinoverse.app with your GitHub account. You will see your repositories with the kino-plugin
topic that you own or admin; you pick one, paste the JSON and save it.
For a repository to show up and be storable, it needs:
- to be public and have the
kino-plugintopic (the panel signs in with thepublic_reposcope, so a private repository cannot be read to store); - a signed
kino-plugin.jsonon the default branch. From it the vault takes the secret's scope: the manifest'sid(thepluginId) and the author key's fingerprint (author), which your plugin will present when it reads.
When you save, the panel shows the two URLs your plugin uses (with a button to copy them):
Secret https://secrets.kinoverse.app/secrets/<owner>/<repo>
Challenge https://secrets.kinoverse.app/session/challenge
The secret is stored encrypted (never in the clear in the database or the repository). To rotate it, edit it in the panel: the next read returns the new value (see Rotation).
2. Read it from your plugin (with a challenge)¶
The read is the same pattern as Identity with a challenge, but against the vault: your plugin asks for a challenge, lets Kino sign and attest who is asking, and the vault returns the secret only if the person is in the group.
Send the token if your plugin is by a trusted author
If your plugin is signed with a tokenAuthors key (e.g. E04E), kino.identity gives you a bot-signed
token. Include it in the body (token: who.token): with it the vault reads your real Telegram id and checks your
membership live, so any group member can read. Without the token the vault falls back to a partial check (it only
recognises members it already knows), and a real member may get 403.
const VAULT = "https://secrets.kinoverse.app";
const REPO = "<owner>/<repo>"; // where you stored the secret
const PLUGIN_ID = "<your kino-plugin.json id>";
async function getRecipe() {
const cached = kino.storage.get("recipe");
if (cached) return cached; // cache it: every read spends quota (below)
// 1. A one-use challenge from the vault (no session, no token)
const { challenge } = await post(VAULT + "/session/challenge", {});
// 2. Kino signs the challenge with this device's key and attests who is asking
const who = await kino.identity.telegram({ challenge });
// 3. The vault verifies signature + author fingerprint + membership, and returns the secret
const { secret } = await post(VAULT + "/secrets/" + REPO, {
pluginId: PLUGIN_ID,
challenge,
id: who.id,
deviceKey: who.deviceKey,
signature: who.signature,
author: who.author || "",
codeHash: who.codeHash || "",
token: who.token, // recommended (trusted author): the vault then checks your membership live
});
kino.storage.set("recipe", secret, { ttlMs: 60 * 60 * 1000 }); // ~1 h
return secret;
}
id, deviceKey, signature, author and codeHash come straight from
kino.identity.telegram: you do not compute them. You only add the pluginId (your manifest's id)
and the challenge.
The body of POST /secrets/<owner>/<repo>:
| Field | What it is |
|---|---|
pluginId |
The id of your kino-plugin.json. Must be the one you registered when you stored it. |
challenge |
The one-use nonce POST /session/challenge gave you. |
id |
The person's pseudonym for your plugin (who.id). |
deviceKey |
The device's public key (who.deviceKey). |
signature |
The signature over the challenge (who.signature). |
author |
The fingerprint of the author key you signed the plugin with (who.author). It must match the one in the manifest you stored, and cannot be empty: an unsigned plugin cannot read. |
codeHash |
The code hash (who.codeHash). Advisory in this version; sign over it anyway, but it is not required. |
token |
Recommended. The kino.identity token (trusted authors, like E04E, get it). With it the vault reads your real Telegram id and checks your membership live → works for any group member. Without it, the vault only recognises members who already did a token login (partial coverage), and a real member may get 403. |
Response 200: { "secret": <your JSON> } —exactly what you stored in the panel.
3. When you can read it, and the quota¶
- Only inside a call the person started (what a
screen, ascreenEventor apanelActionruns), becausekino.identityonly answers there. Never from a timer, Home, search, play or a background job. See When you can call it. - 120 reads an hour per person. More, and the vault answers
429. Every read spends a challenge and a quota hit, so cache (in the example,kino.storagewith a ~1 h TTL) and read once per session, not on every request. - Always keep a way out if it fails: the person can switch identity off whenever they want, or not be a member. Do not keep a burned-in secret in the code as a fallback (that breaks the anti-copy); show that access is missing.
4. Rotation¶
The secret is stored with an upsert: when you edit it in the panel, the next read returns the new value (server-side it is immediate; plugin-side your cache bounds it). Rotating is just editing the panel. It is the strongest anti-copy lever: if you rotate the value, any copy that burned it in goes stale.
5. What it protects and what it doesn't¶
The author and the pluginId in the scope make it so that:
- a copy re-signed with another key presents a different
authorfingerprint → it does not match the stored one →403; - someone who is not in the group →
403.
But author and pluginId are public (they are in your public kino-plugin.json), and the signature is over the
deviceKey the device generates (with no root that ties it to the author). A determined forger who copies your public
author and pluginId and knows a real member's Telegram id can read. So:
- keep only moderate secrets (better than the public
plugin.js, not critical keys); - do not put a burned-in fallback in the code;
- rotate the secret when needed.
What it does give you, together: it stops scrapers and non-members, it stops honest re-signed forks, and rotation kills copies that burned in the value.
6. Errors¶
| Code | When |
|---|---|
200 |
Member and everything valid. { "secret": … }. |
404 |
No secret stored for that owner/repo yet. |
403 |
The person is not in the group, or the challenge/signature are not valid, or the author/pluginId do not match the stored scope. |
429 |
More than 120 reads in an hour for that person. Back off and use your cache. |
503 |
The vault could not decrypt (an operations problem). Retry later. |
Always detect typeof kino.identity === "object" and catch the errors: the read can fail because the person switched identity
off, is not a member, or the vault is rotating. Never break the screen over it.
Summary¶
- [ ] Your plugin declares
apiVersion15 and theidentitycapability, and is signed (Kino 0.9.88 or newer so an author that is not Kino gets the attestation). - [ ] The repository is public, with the
kino-plugintopic and a signedkino-plugin.json. - [ ] You stored the JSON at https://secrets.kinoverse.app (owner/admin of the repo).
- [ ] Your plugin reads with the flow above, caches (~1 h) and has no burned-in fallback.