kotiko

Only the latest minor release gets fixes (SECURITY.md), and there is an upgrade path to it: the server updates with git pull and a restart, migrates its database itself after backing it up, and keeps the five newest backups for going back; the extension, loaded from source, is reloaded in place and keeps its settings (from the stores it updates automatically). Breaking changes are marked in commits and release notes, and before 1.0 an old HTTP API route keeps working for one more minor version. The upgrade guide, including the documented move from the project's earlier name: https://github.com/ScriptKittyOS/kotiko/blob/main/site/src/content/docs/server/updates.md

GitHub Issues, with forms for bugs, ideas, broken sites and wrong words: https://github.com/ScriptKittyOS/kotiko/issues

No vulnerability report from anyone outside the project has been resolved in the last 12 months, and no security advisory has been published. The one security fix so far (0.2.0, 2026-10-01, an authentication bypass through encoded paths) came from the project's own review and is named in the release notes. SECURITY.md promises reporters credit in the release notes unless they ask otherwise: https://github.com/ScriptKittyOS/kotiko/blob/main/SECURITY.md

SECURITY.md documents what happens after a report: acknowledgement within 7 days, triage with a CVSS v4.0 rating, a private fix in a GitHub draft security advisory, fix targets by severity (critical 7 days, high 30, medium 60), a CVE for medium and above, a patch release with a Security section, disclosure with the release or after 90 days, then a regression test and an assurance-case update. The security response lead named in MAINTAINERS.md runs it. https://github.com/ScriptKittyOS/kotiko/blob/main/SECURITY.md#what-happens-after-you-report

docs/CODING_STANDARDS.md names the style guide for each language: Elixir follows mix format and Credo, then the community Elixir Style Guide; JavaScript follows ESLint and the project's own style section; shell follows ShellCheck and the Google Shell Style Guide; HTML and CSS use the design tokens with no inline scripts. CONTRIBUTING.md requires contributions to follow it. https://github.com/ScriptKittyOS/kotiko/blob/main/docs/CODING_STANDARDS.md

CI enforces the coding standards on every pull request: mix format --check-formatted and Credo in strict mode for Elixir; for JavaScript, ESLint with @stylistic/eslint-plugin layout rules that match the code as written (indentation, quotes, semicolons, trailing commas, spacing) plus the stricter rules; ShellCheck for shell scripts. npm run lint:fix and mix format apply the layout. Prettier was measured and rejected because reformatting would push the extension popup past its size budget; the numbers are in the standards document. https://github.com/ScriptKittyOS/kotiko/blob/main/docs/CODING_STANDARDS.md

The project builds no native binaries. The server is Elixir compiled to BEAM bytecode by Mix, and the extension is JavaScript packed into a zip as is. The only native code (SQLite, in the exqlite dependency) is built by that dependency, not by the project.

Mix compiles the server with debug information (Elixir's default) and nothing strips it. The extension is shipped as source: the build copies the files unchanged into the zip, with no minification or bundling.

One Mix project builds the server (server/mix.exs) and one script packs the extension (scripts/build-extension.mjs); neither recurses into subdirectories with cross-dependencies.

Yes. scripts/build-extension.mjs builds both extension zips from the commit with entries sorted by path, the commit's timestamp, fixed permissions and a pinned pure-JavaScript deflate, so the bytes don't depend on the machine or time zone. The release workflow builds twice and fails if the zips differ, and building twice on 2026-10-06 gave identical SHA-256 hashes. How to check it yourself: https://github.com/ScriptKittyOS/kotiko/blob/main/docs/reproducible-builds.md

The server installs and uninstalls with one script: server/install-service.sh sets it up as a systemd user service and install-service.sh --uninstall removes exactly what it added, keeping the learner's words unless --delete-data is given. The extension is installed and removed through the browser's own extension manager (from source with Load unpacked today; from the Chrome Web Store and Firefox Add-ons from v1.0.0). https://github.com/ScriptKittyOS/kotiko/blob/main/site/src/content/docs/server/service.md

The server follows the XDG Base Directory convention: its default data folder is $XDG_DATA_HOME/kotiko (falling back to ~/.local/share/kotiko, and keeping an existing folder there), and install-service.sh writes its systemd user unit to $XDG_CONFIG_HOME/systemd/user. It installs nothing to system locations, so DESTDIR and PREFIX don't apply, as the script says. The extension is installed by the browser. https://github.com/ScriptKittyOS/kotiko/blob/main/docs/reference/configuration.md

CONTRIBUTING.md Setup installs everything needed to change and test Kotiko with each ecosystem's standard tools: mix deps.get and mix test for the server, npm ci and npm test for the extension, and npx playwright install chromium for the end-to-end tests. https://github.com/ScriptKittyOS/kotiko/blob/main/CONTRIBUTING.md#setup

Dependencies are declared and locked in each ecosystem's standard files: server/mix.exs with server/mix.lock (Hex), package.json with package-lock.json (npm, development tools only; the extension ships no npm code), and site/package.json with its lock file for the docs site. External services are listed in docs/ARCHITECTURE.md section 6, and the release workflow attaches a CycloneDX SBOM of the server to each release. https://github.com/ScriptKittyOS/kotiko/blob/main/server/mix.exs

Dependabot alerts and security updates are on, with weekly version updates for Mix, npm and GitHub Actions, and CI runs mix hex.audit and mix deps.audit on every pull request. The open alerts on 2026-10-06 are all in development-only npm tools, never shipped: shell-quote and postcss-selector-parser have fixes in an open pull request, and node-forge (pulled in by web-ext's Android debugging library, no patched version yet) is reached only when web-ext debugs on Android over adb, which Kotiko's scripts never do (they run web-ext lint and sign), so it is not exploitable here.

All third-party code comes through Hex and npm with lock files and is updated through Dependabot; nothing is vendored or forked into what ships (the extension zips contain only the project's own files and license texts). Data derived from CLDR and stopword lists is regenerated from pinned npm packages, and CI checks the copies match.

The extension uses Manifest V3 and current WebExtension APIs, and web-ext lint reports no deprecated API. The server runs on current Elixir and Erlang/OTP (CI tests the oldest supported, Elixir 1.15 on OTP 26, and the newest, 1.19 on OTP 28) and compiles with warnings as errors, so a deprecation warning fails the build.

GitHub Actions runs on every push to main and every pull request: the server tests on the oldest and newest supported Elixir, the extension's unit, DOM and background suites, the shared-spec checks, and Playwright end-to-end tests against the real server. Each job reports pass or fail on the pull request, and main accepts only pull requests whose 8 required checks pass. https://github.com/ScriptKittyOS/kotiko/actions/workflows/ci.yml

Measured with scripts/regression-audit.mjs on 2026-10-06: 11 of the 15 fix commits on main in the last six months changed a test in the same commit (73 %). CONTRIBUTING.md requires a regression test that fails without the fix with every bug fix.

Measured 2026-10-06 with FLOSS tools: the server's ExUnit suite (1000 tests and 2 properties) covers 87.8 % of lines (mix test --cover, Erlang's cover tool), and the extension's Node test suites cover 92.6 % of the lines of the extension code they load (node --test --experimental-test-coverage); three small extension files (120 lines) are not loaded by them. The end-to-end tests come on top. A coverage gate in CI is planned.

CONTRIBUTING.md, Tests: every pull request that adds or changes behaviour adds or updates automated tests in the same pull request, and major new functionality is not merged without tests. https://github.com/ScriptKittyOS/kotiko/blob/main/CONTRIBUTING.md#tests

The instructions for change proposals say it: CONTRIBUTING.md, Tests (https://github.com/ScriptKittyOS/kotiko/blob/main/CONTRIBUTING.md#tests), requires tests with every behaviour change and says major new functionality is not merged without them, and the pull request template's checklist asks for them.

Warnings are as strict as practical, and any warning fails CI on every pull request: the server compiles and runs its tests with --warnings-as-errors; Credo runs in strict mode (server/.credo.exs sets strict: true, so a plain mix credo reports the same); ESLint adds about 60 rules beyond its recommended set (among them eqeqeq, no-shadow, no-unused-vars for every argument, no-param-reassign, no-implicit-coercion, no-loop-func, prefer-const, no-var, no-eval) and treats unused disable directives as errors; web-ext lint, ShellCheck and Sobelow fail on findings too. The few rules not enabled, and why, are written down. https://github.com/ScriptKittyOS/kotiko/blob/main/docs/CODING_STANDARDS.md

The assurance case shows how each Saltzer and Schroeder principle is applied, with code and tests: deny by default (one authorization plug before routing, only /health open, constant-time token comparison), loopback bind by default, a Host allowlist against DNS rebinding, complete mediation tested over encoded paths and through a real socket, one message router in the extension that checks every sender, secrets kept where content scripts can't read them, and a small attack surface. Where a principle is applied only weakly (one token grants everything on the server), it says so. https://github.com/ScriptKittyOS/kotiko/blob/main/docs/security/assurance-case.md#4-secure-design-principles

No default security mechanism depends on a weak algorithm or mode: there is no SHA-1, MD4, MD5, RC4, DES, ECB or disabled certificate check in Kotiko's code. SHA-256 is used where a hash is needed (lookup cache keys, the PKCE challenge), and TLS is left to Erlang/OTP and the browser.

Kotiko fixes no cipher itself: TLS versions and cipher suites are negotiated by Erlang/OTP and the browser, which support several (AES-GCM, ChaCha20-Poly1305) and change with their updates. The only algorithm Kotiko names is SHA-256, for internal cache keys and for the PKCE S256 method that the OAuth standard defines.

Credentials are kept apart from the code and the other settings, and each can be replaced without changing either: every server secret (API_TOKEN, LLM_API_KEY, TELEGRAM_BOT_TOKEN, TRANSCRIBE_API_KEY) can be given as NAME_FILE=/path, the Docker secrets and systemd credentials convention, so a key is replaced by replacing a file and restarting. The API token can also be rotated with mix kotiko.token --rotate. Documented at https://github.com/ScriptKittyOS/kotiko/blob/main/docs/reference/configuration.md

Kotiko's own outbound traffic uses HTTPS by default: model providers, OpenRouter, Telegram and Wiktionary. The server listens on 127.0.0.1 by default, so its plain-HTTP API doesn't leave the computer unless the owner sets BIND to another address; then the server logs a warning at start (daily for a public address), and the extension warns under the address field when the token would cross a network unencrypted. A plain-HTTP model endpoint (such as a local Ollama) is used only when the user enters one.

TLS comes from Erlang/OTP (26 and newer, which offer TLS 1.2 and 1.3 by default) for the server's outbound requests and from the browser for the extension. Kotiko never sets or lowers the TLS version.

The server makes HTTPS requests with Req (Mint over Erlang/OTP ssl), which verifies the certificate chain and host name by default; Kotiko's code sets no verify option anywhere. The extension's requests go through the browser, which always verifies certificates.

Certificate verification happens in the TLS handshake, before any HTTP request is sent, so the Authorization header and API keys are sent only after the certificate is verified. Kotiko uses no cookies.

No release has been published yet, so there is nothing to sign today. The pipeline for the first one (v1.0.0) is in place and signs everything it publishes: the release manager signs the tag with their own SSH or GPG key; the workflow refuses a tag not signed by a key listed in .github/allowed_signers on main, builds the zips reproducibly, and publishes them with SHA256SUMS, a CycloneDX SBOM and Sigstore build-provenance attestations (keyless, so no signing key is stored on GitHub). How users verify: https://github.com/ScriptKittyOS/kotiko/blob/main/docs/verify.md

Every input from an untrusted source is checked against what is allowed, and refused otherwise: HTTP requests (Host allowlist, exactly one Bearer token, JSON only within size caps, then per-field rules such as text length, canonical language tags, UUID request ids, statuses from a fixed list and limits in range); model answers (the shared word spec: required fields, canonical tags, a script check, length and count caps); server answers in the extension; backup files (format, version, every word re-checked); the server address the user types; and every setting at start. The full table: https://github.com/ScriptKittyOS/kotiko/blob/main/docs/security/assurance-case.md#6-inputs-and-how-each-is-validated

Extension pages run under an explicit content security policy (script-src 'self'; object-src 'self') with no inline scripts, and ESLint forbids HTML string sinks (innerHTML, outerHTML, insertAdjacentHTML) so a bug can't turn word data into markup. The server checks the Host header against an allowlist before anything else (against DNS rebinding), caps request bodies, sends no CORS headers, marks answers no-store, binds to loopback by default, compares tokens in constant time, and filters secrets out of logs. Planned: X-Content-Type-Options and similar headers on server responses, and a sandboxed systemd unit. Evidence: https://github.com/ScriptKittyOS/kotiko/blob/main/extension/manifest.json and https://github.com/ScriptKittyOS/kotiko/blob/main/docs/security/assurance-case.md

docs/security/assurance-case.md: the top claim and its sub-claims mapped to arguments and evidence, the threat model (assets, attackers and what each can reach), the trust boundaries (diagram and table), how each secure design principle is applied, the CWE Top 25 and OWASP Top 10 weaknesses that apply and how each is countered, every input and how it is validated, and the residual risks. https://github.com/ScriptKittyOS/kotiko/blob/main/docs/security/assurance-case.md

Two security analysers look for common vulnerabilities on every pull request and push to main, and a finding fails the build: Sobelow for the Elixir server (injection, traversal, unsafe deserialization, atom exhaustion; every finding fails, false positives are skipped per function with a written reason) and CodeQL with the security-extended queries for JavaScript and the GitHub Actions workflows (a required check). For the extension, eslint-plugin-no-unsanitized and a ban on HTML string sinks cover DOM cross-site scripting. The policy says what blocks a merge or a release: https://github.com/ScriptKittyOS/kotiko/blob/main/docs/security/dependency-and-static-analysis-policy.md

Kotiko's code is Elixir and JavaScript, both memory-safe. The only memory-unsafe code is SQLite inside a dependency (exqlite), which the project does not write or build itself.