Metadata-Version: 2.4
Name: koschei-lang
Version: 0.10.0
Summary: Koschei: a capability-secure programming language. Code cannot touch the disk, network or environment unless it is handed a capability.
Author: Onur Sel
License-Expression: LicenseRef-Koschei-Lang-1.0
Project-URL: Homepage, https://koschei.dev
Project-URL: Playground, https://koschei.dev/play
Project-URL: Repository, https://github.com/bugsbuny243/koschei-lang
Project-URL: Issues, https://github.com/bugsbuny243/koschei-lang/issues
Keywords: programming-language,compiler,native-security-language,constitutional-security,capability-security,supply-chain-security,ai-security,mcp,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.tr.md
Dynamic: license-file

# Koschei (`.ks`)

<!-- mcp-name: io.github.bugsbuny243/koschei -->

## 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](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/PRODUCT_CHARTER_LANG_V1.md) and [product direction](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/PRODUCT_DIRECTION_2026-09-10.md).

> **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`](https://github.com/bugsbuny243/koschei-lang/blob/main/LICENSING.md)). Redistribution of the toolchain is not permitted. See [`LICENSE`](https://github.com/bugsbuny243/koschei-lang/blob/main/LICENSE).
>
> **Try it without installing:** [koschei.dev/play](https://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](https://github.com/bugsbuny243/koschei-lang/blob/main/README.tr.md)

---

## Quickstart

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

```bash
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:

<!-- verify: expect KS2401 -->
```ks
fn track(event: String) -> String or Error {
    let secret = disk.read("/etc/app/secrets.env") or return Error("unreadable")
    return secret
}
```

Expected output:

```text
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:

```bash
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:

```bash
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](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/VALUE_BUDGET_V1.md)).
- **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](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/PROGRAM_INPUT_V1.md)).
- **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](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/CLOCK_RANDOM_V1.md)).
- **Learn it from tested docs.** The [language guide](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/guide/LANGUAGE_GUIDE.en.md) runs every example in CI; [error codes](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/reference/ERROR_CODES.md) and the [Core Library reference](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/reference/CORE_LIBRARY.md) are generated from the toolchain; [`examples/apps`](https://github.com/bugsbuny243/koschei-lang/blob/main/examples/apps/README.md) 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

<!-- verify: compile — requires an external HTTPS origin at runtime -->
```ks
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:

```bash
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:

```text
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](https://github.com/bugsbuny243/koschei-lang/blob/main/docs/CORE_LIBRARY_V1.md) for the function list.

## Toolchain

```bash
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

```bash
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`](https://github.com/bugsbuny243/koschei-lang/blob/main/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`](https://github.com/bugsbuny243/koschei-lang/blob/main/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`](https://github.com/bugsbuny243/koschei-lang/blob/main/LICENSE) (Turkish: [`LICENSE.tr.md`](https://github.com/bugsbuny243/koschei-lang/blob/main/LICENSE.tr.md)). Revisions previously released under the MIT License stay under the MIT License.
