Koschei (.ks)

Product direction

Koschei Lang is an independent programming language and library ecosystem for cybersecurity-centered general-purpose software development. Its own semantics, compiler, standard library and runtime define the product; Web3 and AI integrations are applications of the language. Self-contained distribution and surpassing Rust in security remain development goals requiring executed evidence.

Koschei Lang is sold and licensed separately from Koschei Sentinel and Koschei Web3 Hub. Interoperability may use explicit SDKs, adapters and versioned contracts, but it does not create shared pricing, entitlement or runtime authority. See the standalone product charter and product direction.

Source-available, not open source. Koschei Lang is free to download, use and modify for personal, non-commercial purposes. Commercial use needs a perpetual commercial license (see LICENSING.md). Redistribution of the toolchain is not permitted. See LICENSE.

Try it without installing: koschei.dev/play

A capability-secure programming language. An imported package cannot touch your disk, network, or environment unless you hand it a token.

Most supply-chain attacks work because a dependency inherits every permission the process has. Install a package, and it can read ~/.ssh, your .env, or open a socket — without asking. Koschei removes that ambient authority: side-effect access is a value that must be passed in, and the compiler rejects a program that reaches for authority it was never given.

Türkçe: README.tr.md

Quickstart

Needs Python 3.12 or newer. Go 1.24+ is optional and only needed for ks build.

git clone https://github.com/bugsbuny243/koschei-lang
cd koschei-lang
./install.sh                  # installs into ~/.koschei and links ~/.local/bin/ks
ks check examples/supply_chain/main.ks

A deliberately malicious package in examples/supply_chain/analytics.ks tries to read a secrets file and return it to the caller. The expected result is compile-time rejection:

fn track(event: String) -> String or Error {
    let secret = disk.read("/etc/app/secrets.env") or return Error("unreadable")
    return secret
}

Expected output:

KOSCHEI ERROR: KS2401 [line 6, column 18]: Required capability is unavailable
in this scope — A disk, network, environment, or process operation was
attempted without the corresponding capability token.
Hint: run 'ks --lang en explain KS2401' for details.

Exit code 1. The program never ran. The file was never opened. Nothing was sent anywhere.

This is not a runtime sandbox catching the call. disk does not exist inside track at all, so the attack fails at compile time.

Distribution and installation

Koschei is on PyPI:

pip install koschei-lang
ks version

From a clone, ./install.sh puts Koschei in its own virtual environment, and pip install . installs it into an environment you manage yourself.

Commercial license holders can also download a packaged release from the store on Polar.

Your first program:

ks new hello-koschei
cd hello-koschei
ks run .

ks new creates a zero-dependency project with a koschei.toml and src/main.ks. Commands accept a source file, a project directory, or a koschei.toml path.

Core ideas

• No ambient authority. Disk, network, environment, and process access require an explicit capability value. A function that was not passed one cannot perform the effect.
• Capabilities narrow, never widen. caps.disk is a root token that can only delegate; caps.disk.allow(path) produces a narrowed token that cannot re-widen (KS2403) and a root token cannot perform I/O directly (KS2402).
• No null. Values that may be absent are Option<T> (Some / None).
• Errors are values. Result<T, E> with a single or keyword in three forms: or return, or default, or { block }. An unhandled error value is a compile error (KS1401).
• Values are bounded. A String holds at most 16 MiB of UTF-8 and a List at most 1,048,576 items; an operation over the bound produces a KS3502 Error value at the same point in ks run and ks build (Value Budget v1).
• Program input is a capability too. caps.input.allow(65536) gives args() and a byte-bounded read_text() of standard input; ks run app.ks a b and the compiled ./app a b return the same texts and the same Error values (Program Input v1).
• Time and randomness are capabilities. caps.clock.allow(1000) reads a clock no finer than its resolution; caps.random.allow(64) draws at most 64 bytes from the operating system's secure source (Clock and Random v1).
• Learn it from tested docs. The language guide runs every example in CI; error codes and the Core Library reference are generated from the toolchain; examples/apps holds three complete programs.
• Immutable by default. Rebinding requires let mut.
• Every diagnostic is explainable. 33 error codes with a bilingual catalog; ks explain KS2401 prints the cause and a fix.

Example

fn fetch_data(net: NetCaps, url: String) -> String or Error {
    let response = net.get(url) or return Error("request failed")
    return response.text()
}

fn main(caps: SystemCaps) {
    let api_net = caps.net.allow("https://api.example.com")
    let response = fetch_data(api_net, "https://api.example.com/v1")
    println(response)
}

fetch_data can reach exactly one origin. It cannot touch the disk, read an environment variable, or start a process — not because it was audited and found not to, but because it holds no token that would let it.

The capability manifest

Because authority is explicit in the source, it can be summarized mechanically. ks caps reports everything a program is able to reach, across the whole module graph:

ks caps examples/app.ks
ks caps --json src/main.ks
ks caps --deny net src/main.ks   # exits 2 if the program can reach the network

For a pure program the manifest is empty, and that is a checkable fact rather than a claim in a code review:

KOSCHEI CAPABILITY MANIFEST: examples/app.ks

This program carries no side-effect capability.
No disk, network, environment, or process access — pure computation.

The --deny gate is designed for CI: a build fails if a dependency update silently adds reach.

Language features

Implemented today: functions with typed parameters, inferred generic functions, generic structs and enums, let / let mut, structs, List<T>, immutable Map<String, V> (get/set/keys/contains), for-in, if/else/while with Bool-only conditions, enums with exhaustive match, real Option<T> / Result<T, E>, full expression interpolation ("{items.length()}"), a daily standard library (String trim/split/join, List sort/filter/contains), and a module system where import risk binds risk.ks next to the importing file — no manifest, no build script, no config.

The Core Library is written in Koschei itself: import text and import list bind library modules shipped with the toolchain (text.starts_with, text.replace, text.lines, list.first, list.reverse, list.slice, …), checked and executed by the same pipeline as your own code. import secure adds domain-separated SHA3-256 digests from the audited host implementation, and the first library universe modules are Koschei too: the Marvel guardians captain_marvel, hela, strange and wanda. ks run executes the library and ks build compiles it from the same source; see Core Library v1 for the function list.

Toolchain

ks check src/main.ks          # types, modules, capability rules
ks run src/main.ks            # interpreter
ks build src/main.ks -o app   # current native build path
ks fmt --write src/           # canonical formatting
ks caps src/main.ks           # capability manifest
ks explain KS2401             # diagnostics, --lang tr for Turkish
ks check --json src/main.ks   # stable code/message/line/column for editors
ks mir src/main.ks            # sealed checked backend contract
ks lsp                        # zero-dependency language server
ks-mcp --allow-read ./data    # MCP server: agents run Koschei under a policy (docs/MCP_SERVER.md)
ks tokens / ks ast

Koschei's long-term canonical architecture is defined by Koschei semantics and verified execution contracts, not by the implementation language of temporary bootstrap/tooling layers. External adapters are non-authoritative interoperability mechanisms.

Editor support

editors/vscode contains the official zero-dependency LSP extension: .ks syntax highlighting, live diagnostics, formatting, hover, go-to-definition, document symbols, and completion. The server is available through ks lsp (with ks-lsp kept as a compatibility alias).

Tests

python -m unittest discover -s tests -v

The CI suite includes compiler/runtime tests, native/interpreter parity checks, repository documentation examples, committed golden outputs, capability-security regression tests, and deception-plane attack simulations.

Status

Koschei is pre-1.0 and under active development. Syntax, runtime contracts, licensing, distribution, and security architecture may change before the first production release. Do not put it in production yet.

Security boundaries currently enforced in the native path include capability denial, narrowed authority, path traversal/symlink escape protection, read-only enforcement, redirect-origin enforcement, call-depth bounds, opaque protected-source object identity, epoch-scoped alias rotation, decoy source views, and epoch-bound read grants. Security claims must continue to be backed by tests and evidence; the project does not claim that any software system is mathematically impossible to compromise.

The protected-source/deception architecture is being hardened through staged attack waves. Canonical source identity remains separate from physical source locators, and decoy views are non-deployable by construction.

Licensing and distribution

Koschei Lang is free for personal, non-commercial use. Commercial use needs a commercial license, paid once and valid without time limit, covering every version released within 12 months of purchase: Individual 49 USD, Team (up to 10 developers) 249 USD, Enterprise 999 USD. Programs written in Koschei, and the binaries ks build produces, belong to their authors. See LICENSING.md.

Users download Koschei from its store on Polar (polar.sh). python tools/polar_bundle_v1.py builds that download, dist/polar/koschei-lang-<version>.zip: the koschei package, the installer, the license, the customer README (distribution/polar/), the language guide, the references and the examples it runs.

Contributions

Bug reports are welcome through GitHub issues. Report vulnerabilities privately, as SECURITY.md describes. Code contributions are not accepted yet: contributor terms must be in place first so that ownership and commercial licensing stay unambiguous.

License

Koschei Lang License 1.0 — free for personal use; commercial use needs a perpetual commercial license. See LICENSE (Turkish: LICENSE.tr.md). Revisions previously released under the MIT License stay under the MIT License.