Assurance case
Last reviewed: 2026-10-05.
Why we believe Kotiko meets its security requirements, written as claims, the arguments for them, and the evidence (code and tests) behind each argument. It is for reviewers and future maintainers: read this before changing anything that takes input or crosses a trust boundary.
Paths are relative to this file. "In place" means the code on main does it today;
"planned (slice NN)" means a slice spec in slices/ will build
it and it is not true yet.
1. Top claim
Section titled “1. Top claim”Kotiko meets requirements.md in its supported configurations: the extension in a current Chrome, Edge, Brave or Firefox, and optionally the server run from source under the user's own account, listening on loopback or on a Tailscale address, or on another network the user chose after the startup warning.
Each "You can expect" line in the requirements is a sub-claim. The table maps each one to its argument and evidence.
| Sub-claim | Argument | Evidence |
|---|---|---|
Only /health answers without the token |
One plug runs before routing and allows exactly GET and HEAD /health (and the proof, which reveals nothing); everything else needs Bearer <token> or a request signed with it (Kotiko-HMAC), each compared in constant time. It matches on the raw path, so encoded spellings can't slip past; every route, v1 and 0.2, goes through it |
router.ex authorize/2; router_auth_test.exs "every method and path spelling is 401", "only GET and HEAD /health are open"; router_socket_test.exs "encoded and dotted paths need the token" (through a real socket); router_signed_test.exs "every route" |
/health says nothing else |
It returns name, version, API versions and database state only | health.ex report/1 |
| A strong token, kept private | 32 bytes from :crypto.strong_rand_bytes, written to a file made 0600 before the token goes in, then renamed into place; a chosen API_TOKEN under 24 characters stops the boot |
token.ex generate/1, save/2, check/3; token_test.exs "first boot makes a 43-character token in a 0600 file", "short or whitespace-only tokens are refused"; config.ex api_token/1 |
| Other accounts on the computer can't read the words | The BEAM can't set a mode on create, so files are created empty, made 0600, then filled: the database before SQLite opens it (SQLite gives -wal, -shm and -journal the database's mode, checked by a test), each backup before VACUUM INTO, the token and model cache through a private temporary file. A data folder the server makes is 0700. At every boot, before the Repo opens, make_private/1 tightens any of Kotiko's files others can open and the folder when it holds only Kotiko's files, and warns otherwise. Before that, check_safe/2 refuses to start when someone else could have planted a file Kotiko would trust: the folder or a Kotiko file owned by another uid, a Kotiko file that is a symlink, or a folder others can write in that also holds other files (B-02); api-token is read with lstat, open, fstat and compare, never through a link. run.sh sets umask 077 and the unit UMask=0077 |
private.ex read_own/3; data_dir.ex check_safe/2, make_private/1; private_test.exs; data_dir_test.exs; boot_test.exs (boots with umask 022 and checks the modes); scripts_test.exs |
| Listens on this computer unless told otherwise; warns when it doesn't | BIND defaults to 127.0.0.1, and a loopback BIND holds the port on ::1 too, so no other account can listen where a browser sends localhost (B-01); at boot the address is classified (loopback, Tailscale, LAN, all interfaces, public) and the last three log a warning; a public address repeats it daily |
config.ex @default_bind; exposure.ex classify/2; application.ex repeat_public_warning/2; listener.ex addresses/1; exposure_test.exs |
| Answers only to names it knows | A plug before routing allows localhost, IP literals, this machine's own name and ALLOWED_HOSTS; others get 421, with or without a token |
host_check.ex; host_check_test.exs; router_auth_test.exs "an unknown name gets 421 with or without a token, on every route" |
| Strangers can't make it do work | Body parsing is a plug after authorize; 64 KB cap, 1 MB for the batch route |
router.ex parse_body/2; router_auth_test.exs "are parsed only after auth", "over 64 KB are refused with 413"; router_v1_test.exs "takes at most 500 words, and bodies up to 1 MB" |
| Words go only where the user sent them | The only outbound hosts are LLM_URL, TRANSCRIBE_URL (both set by the owner), api.telegram.org when a bot token is set, and the Wiktionary endpoint with the word percent-encoded in the path; tests can't reach the network at all |
llm/client.ex; transcriber.ex; telegram.ex; pronounce.ex fetch_page; spec/wiktionary.json endpoint; no_network_test.exs |
| The bot obeys only listed IDs | Every update's sender ID is checked against ALLOWED_TELEGRAM_IDS before dispatch; with no list, the bot only replies with the sender's ID |
bot.ex handle/1; bot_test.exs "messages from people not in ALLOWED_TELEGRAM_IDS are ignored" |
| Keys and tokens stay out of logs | A primary :logger filter rewrites every event that contains a configured secret (the four secret settings and the values in LLM_URL's and TRANSCRIBE_URL's queries, E-03) or a key-shaped string; an event it can't read is dropped. Service addresses are logged without user name, password or query (?…) |
log/redact.ex; config.ex loggable_url/1, url_secrets/1; redact_test.exs; startup_summary_test.exs "a key in LLM_URL's or TRANSCRIBE_URL's query (E-03)" |
| Words stay out of logs at the default level | Lookup input and model answers are logged only with LOG_LOOKUPS=true, at debug; save failures log the field names, not the values |
llm.ex log_lookups?/0; router_v1.ex result_json/1; llm_test.exs "no path logs the input or a returned word at the default level" |
| Bad settings stop the server; secrets aren't echoed | Every variable is parsed by one function that returns a problem; any problem halts with status 78 and one message; secret problems are labelled "(value hidden)" | config.ex parse/2, secret_error/2; config_test.exs "a short API_TOKEN is refused without echoing it" |
| Text never becomes HTML in the extension | ESLint bans innerHTML, outerHTML and insertAdjacentHTML in extension/ and runs eslint-plugin-no-unsanitized; CI fails on any finding |
eslint.config.js; ci.yml npm run lint |
| Pages can't use the extension to change words | One message router checks each sender's kind (extension page or content script) against the handler's allowed list; content scripts may only sync, read sensitiveSites and mark one word never to swap (neverSwap); oauth.code is accepted only from the docs site's callback page (https://kotiko.org/connect/ with a code; the site's own test checks that page has no script), and only with the random state of the sign-in waiting, so a page that opens the callback with a code of its own neither reaches OpenRouter nor uses up the sign-in |
lib/messages.js senderKinds, createMessageRouter; background.js handler table; sync-libs.test.mjs "disallowed senders get forbidden"; local-mode.test.mjs "content scripts can't set, describe or remove secrets, change modes, write words or move them" |
| Pages can't change your settings, word list or add queue | Content scripts can write storage.local and storage.sync (Firefox can't stop them). The background keeps the real copy of every setting, of the pages' word list and of the add jobs in its IndexedDB, reads only that, and mirrors it to storage.local; a change it didn't make there is put back and an unknown key removed. Pages change settings with settings.set (pages only), checked against an allowlist of keys and shapes; content scripts may only add or remove one never-swap word. Chrome 140+ closes storage.sync to content scripts (setAccessLevel), and only then are changes there taken |
lib/settings.js createArea, edit; background.js area, adoptOnce, adoptSync, saveSettings; settings.test.mjs (one test per attack); settings.test.mjs; privacy.spec.mjs "settings, the add queue and the bases written from a content script are put back and never used" |
| The token never leaves the browser, and a server that doesn't hold it gets nothing it can use | The extension never sends the token (slice 54, D-01). It signs each request with it: HMAC-SHA256 over the method, the path and query, a timestamp, a random nonce, the server's boot id and the body's SHA-256 (Authorization: Kotiko-HMAC v2 ...). The server checks the MAC in constant time, refuses a request signed for another boot id (a new random one at each start, given with the proof and MAC'd for its nonce; security review E-01), a timestamp more than 120 s off either way and a nonce it has seen, and checks the body it reads against the signed hash; a failed signature counts like a wrong token (a stale_boot one, whose MAC matched, doesn't; the extension proves again and resends it once). It signs every answer to an accepted request (X-Kotiko-Server, HMAC over the nonce and status), and the extension uses no answer without that signature: it forgets the server's proof and sends nothing more until a new one. Before the first request to an address, and before any request that carries the learner's words or settings (anything but GET) when the last proof is over 30 s old, the server proves it holds the token (POST /api/v1/proof, HMAC of a fresh nonce, checked with WebCrypto); a missing or wrong proof means nothing is sent. The proof is also forgotten on server.connect, an address or token change and any connection error. The extension uses 127.0.0.1 for a typed localhost (B-01) |
lib/server-auth.js; background.js request, proveServer, askProof; request_auth.ex; router.ex check_signed/3, parse_body/2; router_signed_test.exs (the vectors, wrong MAC, stale time, replay, a request signed before a restart, tampered body, every route); server-auth.test.mjs (the same vectors); background.test.mjs "signed requests: the token never leaves the browser (D-01)" (with the stale_boot retry), "the server proves it holds the token before it gets it"; fullstack.spec.mjs "a request caught while the server was stopped" (reviewer E's replay after a restart, on the real server); loopback.spec.mjs "after the server stops and a listener takes its port, the listener gets no token and no word" |
| Key and token out of content scripts' reach | Secrets live in the extension origin's IndexedDB, which content scripts can't open; the upgrade moves an old token out of storage.local |
lib/store.js secrets; lib/local-mode.js migration step 6; local-mode.test.mjs "the key and the server token are in no storage area a content script can read" |
| Answers are checked before use | Server word lists pass validateWordsResponse (shape, types, lengths, counts); model answers pass the shared word spec in both runtimes, against the same fixtures |
lib/validate-words.js; lib/wordspec.js; word_spec.ex process/2; sync-libs.test.mjs "validateWordsResponse"; wordspec.test.mjs, word_spec_test.exs |
| No telemetry | The only network calls are to the user's server, the model provider, OpenRouter's key exchange (when the user signs in there), Telegram and Wiktionary, as listed above and in background.js and lib/llm/client.js |
Code reading; slice 28 writes the full data inventory (planned) |
2. Threat model
Section titled “2. Threat model”Assets
Section titled “Assets”- The learner's word list: it reveals which languages they study and, through the words, something about their life.
- Model API keys (
LLM_API_KEYon the server, provider keys in the extension): they cost money or quota. - The server token: it gives full control of the word list.
- The Telegram bot token: it lets someone act as the bot.
- Which pages a learner reads: the content script sees every page.
Attackers and what each can reach
Section titled “Attackers and what each can reach”| Attacker | Can reach | Main defences |
|---|---|---|
| A malicious web page | Its own DOM, which the content script reads and changes; HTTP requests from the browser to any address, including the server | Text-only DOM; no CORS headers, so it can't read server answers or send the Authorization header; Host check against DNS rebinding; the content script can't add or delete words |
| A script injected into a page | The same as the page; it can see swapped words | Same; nothing secret is put in the page; only text the learner sees is swapped, at most 500 concepts a page view; page-made events can't open the word card or switch Kotiko off |
| Someone on the same network | Plain-HTTP traffic when the server listens beyond loopback | Loopback by default; startup warnings; Tailscale or HTTPS advice |
| A malicious or broken model answer | The word pipeline on the server or in the extension | Schema and rule checks, length caps, script checks, text-only rendering |
| A Telegram user who isn't allowed | The bot's chat | Sender allowlist |
| Another user on the server machine | Files in the data folder, depending on permissions | Every file the server keeps there is 0600 (the database is created private before SQLite opens it, so -wal and -shm are too) and a folder it makes 0700; each start re-checks them; run.sh and the systemd unit use umask 077 |
| A compromised dependency or GitHub Action | The build, CI, and later the release | Lockfiles, actions pinned by commit SHA, Dependabot, OSV-Scanner over every lockfile in CI and before each release, mix hex.audit and mix deps.audit in CI, no runtime npm code in the extension |
| A malicious pull request | The code base | Required CI checks before merging (the main ruleset), with a read-only token; on a pull request the secret and dependency scans take their allowlists and check scripts from the base commit, so it can't switch them off (base-file.sh). Review by a maintainer who isn't the author is the aim but not enforced (section 7) |
3. Trust boundaries
Section titled “3. Trust boundaries” web page (untrusted DOM) │ DOM reads and text-node writes only ▼ content script ──runtime messages (sender checked)──▶ background ◀── extension pages │ reads words from storage.local │ (popup, dashboard, │ │ welcome) │ ┌──────────────────────────┤ │ │ HTTPS │ HTTP(S), each request and │ │ │ answer signed with the token │ ▼ ▼ │ model provider (answers your Kotiko server ── Host check, │ untrusted), Wiktionary token check, body cap │ │ │ ┌──────────────────────────┼─────────────────┐ │ ▼ HTTPS ▼ HTTPS ▼ file system │ model provider, Wiktionary Telegram (allowlisted data folder │ (answers untrusted) sender IDs) (kotiko.db, │ api-token: 0600) CI (GitHub Actions, read-only token) ──▶ stores, after a maintainer approves (slice 30)| Boundary | What crosses | Control | Evidence |
|---|---|---|---|
| Web page to content script | Page text and DOM events | Text nodes only, never HTML; pages in languages the learner doesn't read are left alone | eslint.config.js; content.js |
| Content script to background | Runtime messages | Sender kind per handler | lib/messages.js |
Content script to storage.local and storage.sync |
Writes the browser allows (Firefox can't forbid them) | Not trusted: the background acts only on its IndexedDB copy and puts the mirror back; storage.sync closed to content scripts where the browser can (Chrome 140+) |
lib/settings.js; background.js storage.onChanged listener |
| Extension pages to background | Runtime messages, including secrets | Allowed only from the extension's own URL; payload checks before handlers run | lib/messages.js checks; background.js |
| Extension to server | HTTP, each request signed with the token (never the token itself), each answer signed by the server | Signature check (MAC, time, nonce, body hash), Host check, body cap; the extension checks the server's proof and the signature on every answer, then the address and every response | router.ex; request_auth.ex; lib/server-auth.js; lib/url.js; lib/validate-words.js |
| Server or extension to model provider | The learner's typed text, the key | HTTPS to an address the owner set; answers parsed as JSON and checked by the word spec; deadline and attempt cap per lookup | llm.ex interpret/3; spec/models.json budgets; lib/llm/client.js |
| Server to Telegram | Updates in, messages out | HTTPS; sender allowlist | bot.ex; telegram.ex |
| Server to file system | The database, token, backups | kotiko.db and its -wal/-shm, api-token, models-cache.json 0600; backups/ 0700 with 0600 files; a data folder the server makes 0700, one that holds only Kotiko's files made 0700 at start (otherwise a warning); umask 077 in run.sh and the unit (UMask=0077) |
private.ex; data_dir.ex make_private/1; migrations.ex backup!/2; data_dir_test.exs; boot_test.exs |
| CI to stores | Release packages | The store jobs run in the release environment (created 2026-10-06): its required reviewer, the maintainer, approves each run, and only v* tags may deploy. A tag is built only if it is signed by a key in .github/allowed_signers on main, under its own name, and only the release manager can create one. The stores get the release's own zips, checked against SHA256SUMS |
slice 30; release.yml; verify-tag.sh |
4. Secure design principles
Section titled “4. Secure design principles”The eight principles of Saltzer and Schroeder, plus two the badge criteria add.
| Principle | How Kotiko applies it | Evidence |
|---|---|---|
| Economy of mechanism | One auth plug and one Host plug in front of every route; one message router in the extension; one place that parses settings; no bundler or runtime npm code in the extension, so what ships is what reviewers read | router.ex; lib/messages.js; config.ex; CONTRIBUTING.md "Rules that protect users" |
| Fail-safe defaults | Deny by default (only /health is open); loopback bind; a token is generated if none is set; a setting the server can't parse stops it; unknown message senders are refused |
authorize/2; @default_bind; token.ex resolve/2; Config.load!/0 |
| Complete mediation | The token check runs on every request before routing, on the raw path, and is tested over encoded and dotted spellings and through a real socket | router_auth_test.exs; router_socket_test.exs |
| Open design | The code is public; the token and keys are the only secrets | LICENSE |
| Separation of privilege | Weakly applied. One token grants everything on the server; there is no second factor. The bot needs both the bot token and an allowlisted sender ID. Per-user tokens are planned (slice 48) | bot.ex handle/1 |
| Least privilege | Content scripts may only ask for a sync and the sensitive-site list (and mark one word never to swap), and change no setting; secrets sit where content scripts can't read them; CI jobs get a read-only token. The extension asks for <all_urls> because it works on any page; a permission review is planned (slice 28 section 6); a sandboxed service unit is planned (slice 40) |
background.js; ci.yml permissions: contents: read; manifest.json |
| Least common mechanism | Each person runs their own server with their own data folder and bot; there is no shared service run by the project | DECISIONS.md 2026-10-02 (own bot, no hosted service) |
| Psychological acceptability | Plain-language startup warnings and error messages that name the fix; a pairing string so the token is pasted, not retyped; settings errors list every problem at once | exposure.ex; config.ex format_problems/3; mix kotiko.token |
| Limited attack surface | One port, loopback by default; a small route list; no CORS; the Telegram bot long-polls, so it needs no public URL or webhook | router.ex, router_v1.ex; bot.ex |
| Input validation with allowlists | Settings are checked against allowed forms (port range, host-name pattern, http(s) URLs, log levels, booleans); statuses, origins and pronunciation sources are checked against fixed lists; language tags are canonicalised against CLDR data; request ids must be UUIDs | config.ex; word_spec.ex validate_word/2, patch/1; router_v1.ex statuses/1, limit/1; add_requests.ex valid_id?/1 |
5. Common weaknesses countered
Section titled “5. Common weaknesses countered”From the CWE Top 25 and the OWASP Top 10, the entries that apply to a browser extension and a small JSON API.
| Weakness | Countermeasure | Status | Evidence |
|---|---|---|---|
| CWE-79 Cross-site scripting | The extension never parses strings as HTML; ESLint enforces it. The server returns JSON only | In place | eslint.config.js |
| CWE-89 SQL injection | Queries go through Ecto with bound parameters. The few raw statements use fixed table names or ? parameters; the one built string (VACUUM INTO a backup path the server chose) is quoted |
In place | words.ex; data_dir.ex sql_string/1 |
| CWE-78 OS command injection | The server runs no external commands (no System.cmd, Port.open or :os.cmd in server/lib). The shell scripts read only the owner's .env |
In place | server/lib/; ShellCheck in ci.yml |
| CWE-22 Path traversal | No file path comes from a request. The data folder comes from the owner's settings; backup names are built from the version and the time. Sobelow fails CI on any new file call with a path it can't rule out; each accepted one says why | In place | config.ex data_dir/4; migrations.ex; .sobelow-conf |
| CWE-306, CWE-862 Missing authentication or authorization | Deny by default; one token for everything (no roles yet, so no authorization levels to get wrong). The only open routes are /health and POST /api/v1/proof, which proves the server holds the token (HMAC of a client nonce) without revealing it |
In place; per-user authorization planned (slice 48) | authorize/2; token.ex proof/2; router_auth_test.exs; router_proof_test.exs |
| CWE-307 Excessive authentication attempts | After 10 wrong tokens or failed signatures from one address (an IPv6 /64) within a minute, that address gets 429 on every authenticated route until the minute ends; other addresses are unaffected; the lockout is logged once an hour per address. Proofs with a well-formed nonce and Content-Type: application/json are limited to 30 a minute per address; malformed ones are refused before they are counted, so a web page (which can't send JSON cross-site without CORS) can't use them up. Requests from this computer's own addresses (127.0.0.0/8, ::1, IPv4-mapped 127.x) without a forwarding header are exempt from both (slice 54, D-02): every local program and web page shares them, so a limit there would let any of them lock the extension out. Loopback requests with a forwarding header (Forwarded, Forwarded-For, X-Forwarded, any X-Forwarded-*, X-Original-Forwarded-For, X-Real-IP, X-Client-IP, X-Cluster-Client-IP, CF-Connecting-IP, True-Client-IP, Fastly-Client-IP, Via, Tailscale-User-*; security review E-02), which is how a reverse proxy on the same machine forwards remote clients, keep both limits, counted together per proxy address whatever client the header claims (it can be forged); the extension on this computer sends no such header, so a local program that adds one locks out only the proxied requests (the owner's other devices behind the proxy among them). With TRUSTED_PROXY_HEADER (validated at start) naming the header the proxy sets, each proxied client is counted by that header's address (rightmost X-Forwarded-For, last Forwarded for=, or the one X-Real-IP/CF-Connecting-IP), normalised like a peer, so a stranger locks out only themselves. A proxy that adds none of the listed headers makes its clients look local (unlimited); the reference says so. A generated token (256 random bits) can't be guessed; a proof lets someone test guesses offline, so a weak chosen token gets a warning at start |
In place | auth_throttle.ex; rate_limit.ex peer/1; router_throttle_test.exs "this computer's addresses are never locked out", "loopback requests with a forwarding header are limited together", "every forwarding header a proxy may add keeps the limit", "with TRUSTED_PROXY_HEADER, each proxied client is counted on its own"; rate_limit_test.exs "TRUSTED_PROXY_HEADER (E-02)"; router_proof_test.exs "31 malformed proofs", "this computer's addresses aren't limited", "proofs through a reverse proxy on this computer are limited together" |
| CWE-352 Cross-site request forgery | The credential (a Bearer token or a request signature) travels in a header, never a cookie; the server sends no CORS headers, so a page can't attach the header (that needs a preflight the server doesn't answer) |
In place | router_auth_test.exs "a CORS preflight gets no CORS headers" |
| CWE-918 Server-side request forgery | The server fetches only URLs the owner set (LLM_URL, TRANSCRIBE_URL) and fixed hosts (Telegram, Wiktionary with the word percent-encoded in the path). No request can choose a URL |
In place | config.ex; pronounce.ex |
| CWE-502 Unsafe deserialization | Nothing from the network becomes an Erlang term: requests and API answers are parsed as JSON, Wiktionary pages are read as text. One call reads back the lookup cache the server itself wrote to its own database, with Plug.Crypto.non_executable_binary_to_term/2 and :safe, so a changed row can neither create atoms nor carry a function; Sobelow checks for any other |
In place | llm/cache.ex decode/1; llm_test.exs ("a stored entry holding a function is a miss") |
| CWE-400 Resource exhaustion | Body caps (64 KB, 1 MB batch); at most 500 words per batch and 20,000 per list request; each lookup has a deadline and an attempt cap; refused Host names are logged at most once an hour per name, for at most 1,000 names an hour, then one summary line (log/limiter.ex). Wrong tokens and proofs are limited per address (CWE-307). There is no request rate limit for token holders |
In place, partly | router.ex; router_v1.ex @max_batch, @max_limit; spec/models.json; host_check.ex |
| CWE-20 Improper input validation | Settings validation; the shared word spec and its rules; response validation in the extension; server address validation | In place | Section 6 |
| CWE-798 Hard-coded credentials | No credentials in the code. CI's required secrets job runs gitleaks over the full history on every pull request and every push to main, and fails a pull request that adds a .env, key or token file; GitHub secret scanning and push protection are on |
In place | ci.yml job secrets; .gitleaks.toml; check-forbidden-files.mjs |
| CWE-532 Secrets in logs | The redaction filter; words only with LOG_LOOKUPS=true at debug |
In place | log/redact.ex; llm_test.exs |
| DNS rebinding | Host allowlist before routing | In place | host_check.ex |
| Supply chain | Lockfiles (mix.lock, package-lock.json); every GitHub Action pinned by commit SHA; Dependabot for mix, both npm lockfiles and Actions; OSV-Scanner over all three lockfiles on every pull request, weekly and before each release build; mix hex.audit and mix deps.audit in CI; no runtime npm code in the extension; required CI checks on every pull request, though not a second person's review (policy). Not yet: release attestations (slice 30) |
In place, partly | dependency-scan.yml; ci.yml; dependabot.yml; package.json |
6. Inputs and how each is validated
Section titled “6. Inputs and how each is validated”| Input | Where it enters | Rule | Location |
|---|---|---|---|
| HTTP method, path, headers | Every request | Host allowlist; exactly one Authorization header: Bearer compared in constant time, or Kotiko-HMAC v2 in exactly one form (time 1 to 12 digits, nonce 22 to 128 base64url, boot id 22 to 64 base64url, body hash 64 hex, MAC 43 base64url), its MAC compared in constant time, its boot id this start's, its time within 120 s either way, its nonce unseen; unknown routes 404 |
host_check.ex; router.ex |
| HTTP body | POST and PATCH routes |
JSON only, size cap, parsed after auth (a signed request's body read first, within the cap, and checked against its signed hash); then per-field checks: text 1 to 200 characters after normalisation, base languages (at most 4, canonical tags), client_request_id a UUID, word fields against the word spec and its caps, limit 1 to 20,000, status from a fixed list, if_updated_at an ISO 8601 time |
router_v1.ex; word_spec.ex prepare_input/1, validate_word/2, patch/1; spec/rules.json |
Legacy POST /api/words body |
0.2 extensions | Text must be a non-empty string; not run through the 200-character input check (the 64 KB body cap applies) | router.ex |
Environment (.env) |
Server start | One parser per variable; any problem stops the server | config.ex parse/2 |
| Data files | Server start | The token file must hold at least 24 characters; migrations back up before changing the database | token.ex; migrations.ex |
| Model answers | Server and extension lookups | JSON extracted, then the word spec: required fields, canonical language tags, script check against the text, length caps, at most 5 distinct words, forms checked against the meaning, stopwords | word_spec.ex process/2; lib/wordspec.js; spec/model-output.schema.json |
| Wiktionary pages | Pronunciation lookups | Only the IPA spans of the language's section are read, as text; the respelling written from them is checked like any pronunciation | pronounce.ex; lib/pronounce.js |
| Telegram updates | The bot | Sender ID against the allowlist; then the same lookup pipeline as the popup. Bot text is not run through the 200-character input check | bot.ex |
| Extension messages | The background | Sender kind, then the handler's payload check |
lib/messages.js; background.js |
Settings a page changes (settings.set, settings.restore) |
The background | Allowlist of keys; per-key shape and size (booleans, host and language-tag lists with caps, objects up to a byte cap, the four ui fields); a restore takes only what settingsPatch allows, never addresses or the service |
lib/settings.js edit; lib/backup.js settingsPatch |
storage.local and storage.sync as read back |
The background | Never trusted after the one-time adoption: compared with the IndexedDB copy and put back; storage.sync changes taken only where content scripts can't write there |
background.js adoptOnce, adoptSync |
| Server responses in the extension | Every request to the server | The server's signature on the status (X-Kotiko-Server) before anything else is read; then status, content type, JSON shape, word fields and counts |
lib/validate-words.js |
| The server address the learner types | Extension settings | http(s) only, no user info in the URL, https assumed for non-local names | lib/url.js |
| Pasted lists and dropped files | Bulk add | Parsed as text in the extension; each row then saved through the word checks | bulk/parse.js; a backup file is read by lib/backup.js read, which checks every word against the word spec before anything is restored |
| The page DOM | Content script | Read as text; only text nodes in languages the learner reads are changed | content.js, lib/matcher.js |
7. Residual risks and assumptions
Section titled “7. Residual risks and assumptions”These match "What you can't expect" in the requirements.
- Data at rest is not encrypted. Anyone who can read the browser profile or the data folder gets the words, keys and token. Assumption: the user's account and disk are theirs.
- A shared data folder stays shared. When
KOTIKO_DATA_DIRpoints at a folder that also holds other files, the server makes its own files private but leaves the folder's permissions alone and warns at every start; other accounts can then see the files' names and sizes, not their contents. A folder others can write in stops the start, since they could plant a token or a database link. On a disk that keeps no POSIX permissions (a Windows drive in WSL) nothing can be made private; the server warns about the files and refuses a folder that others can write in. - Plain HTTP beyond loopback exposes the words to the network, and a lookup service's key and the words looked up. The server's token isn't sent (requests are signed), and a request seen on the network can't be sent again. The server warns, and so do the extension's address fields for the server and for a lookup service; neither refuses.
- Someone at the server's address after it stops (slice 54, B-01 and D-01). If the
server stops (a crash, a restart, an update) and another account starts listening at its
port, that program never gets the token and can't answer for the server: its first
answer has no server signature, so the extension uses nothing from it, forgets the
proof, and sends nothing more until a proof it can't give. What it can get: the signed
requests already sent before that first answer came back. A
GET(a sync, a status read) shows it only which route was asked. A request that carries the learner's words or settings (an add, an edit, an import batch, a delete, the languages sent after a sync) goes out only within 30 s of a successful proof, so it gets such a body only if it took the port within 30 s of the last proof and before any other request found it out; then it reads that request's body (and each other one already in flight at that moment), never the token. It can't play any request to the server later: a nonce is accepted once while the server runs, a request's time must be within 120 s of the server's clock, and every request signs the boot id the server gave with its last proof, which each start replaces with a new random one, so a request caught while the server was stopped is refused (stale_boot) once it is back, whatever its time (security review E-01; before, a request stamped up to 120 s ahead of the server's clock was accepted after a restart, since the nonces it had seen were gone). - What a signature doesn't do. It authenticates; it doesn't encrypt. The server's signature covers the answer's status, not its body, so a program that sits between the extension and a running server (on a network without HTTPS, or a local listener that forwards to the server at an address the extension doesn't use) can read and change bodies; HTTPS (or Tailscale) is the answer there. A clock more than two minutes off the server's makes every request fail, with a message that says so.
- Weak chosen tokens on this computer. Requests from this computer without a forwarding header are exempt from the wrong-token lockout and the proof limit (D-02), so a program on the computer can try tokens without limit. Remote clients behind a reverse proxy on the computer are still limited (the proxy adds a forwarding header), but all together: one stranger's lockout refuses every proxied client, the owner's other devices included, for the rest of that minute. A proxy that forwards without any of those headers makes its clients look local and unlimited. A generated token (256 random bits) can't be guessed; a chosen one gets a warning at start (configuration.md).
- The model provider sees every lookup, under its own terms.
- Pages can see swapped words in their own DOM, and, since they know their own text,
which of their words the learner has a word for (security review A-01). Kotiko swaps
only text the learner can see (rendered; at least 10 % opaque counting every
ancestor's
opacityandfilter: opacity(); under noclip-path, mask orurl()filter, E-04; on screen or within a screen of it; not clipped away by an ancestor's overflow) and at most 500 distinct concepts, each in at most 3 languages, per page view (spec/rules.jsonmax_page_*). What's left: a page that shows text the learner can't make out (tiny, the color of the background, blurred or otherwise filtered withoutopacity(), under something else, or shown for one frame) still gets swaps within that cap; the cap is per page view, so a page that reloads itself or a site visited often can learn more of a long list over time. The word card opens only from the learner's own input on a swap drawn at least 10 % opaque, under no clip-path or mask, whose box isn't stretched far past its text, and from a pointer only within 4 px of that text (E-05), so a page can't stretch an invisible swap under the learner's pointer or click; one that keeps a swap under the pointer disguised another way (the background's color, under an element withpointer-events: none) can still have its card opened while the pointer rests there, and while a card is open,window.find()can match its text. Where Kotiko is paused, off or stepping back from a sensitive site it adds nothing to the page (A-03, C-04); where it swaps, the swaps and their stylesheet show it's installed. - A subverted content script (code running in Kotiko's content-script world) can't
change settings, the word list or the add queue (SCR-448), but it can still: add words
to the never-swap list one at a time (the word card's action lives in the page; the list
is in Settings); make other open pages act briefly on a value it wrote, until the
background puts it back, and keep doing so by writing in a loop (nothing is saved or
sent); in Firefox, write
storage.sync, which Kotiko then doesn't take, so base languages changed on another device don't follow there. It can read what content scripts read: words, settings and the add jobs' typed text. - One-time trust at upgrade. An install updating from a build before SCR-448 takes its
storage.localas it is, once; one from before slice 28 also takes its server address and the address of a local or "custom" lookup service. These were writable by content scripts then and can't be checked. An address for a hosted service, which no page shows a field for, is dropped. A store set up fromstorage.localis kept only on an update from 0.1 or 0.2 (onInstalled'spreviousVersion); on any other start it is dropped like a new install's, and a store born from "Delete everything" never readsstorage.localat all, even after the worker restarts (slice 54, A-06). There have been no releases, so only builds from source are affected. - One token, full access. Anyone with it can read, change and delete every word.
- Model answers are checked, not verified; a plausible wrong meaning can be saved.
- No rate limit for requests that carry the token or are signed with it (beyond the 50,000 signed requests the server remembers at once).
- Response hardening headers (
X-Content-Type-Optionsand similar) are not sent yet; only/healthsendscache-control: no-store. Planned (slice 01 section 7). - No enforced second review. The
mainruleset requires the CI checks but no approving review, so one maintainer account (or a stolen token with write access) can merge its own pull request, including changes to.github/allowed_signersand the workflows. Accepted while one maintainer does nearly all the work (CODE_REVIEW.md, step 2). The release tag and the store upload still need the release manager: only they can create av*tag, and thereleaseenvironment's reviewer approves each upload. A pull request can also change a workflow itself, and that change runs on the pull request; only review catches it. - No releases yet, so there are no signatures or attestations to verify; users run from source. The release pipeline that signs, attests and builds reproducibly is in place (slice 30); the first release is v1.0.0.
8. Maintenance
Section titled “8. Maintenance”- Same pull request. Any change that adds an input, adds an outbound destination, or crosses a trust boundary updates this file and requirements.md in the same pull request.
- Full review at each minor release and after every security report, by the security response lead; the "Last reviewed" date at the top changes then.
- After a vulnerability that crossed a trust boundary, the fix adds a regression test and a row or a correction here.
- A line moves from "planned" to "in place" only when the code is on
main, with its evidence linked.
