# Oska

Oska is a secure-by-default programming language designed for AI agents to write and humans to review. These terms describe its security model.

## Authority

**Capability**:
An unforgeable value that grants authority to perform one kind of effect, such as reading files, opening network connections, reading the clock, or generating random numbers. Holding a capability is the only way to perform its effect.
_Avoid_: permission, effect handler, token

**Ambient authority**:
Authority available to code without being explicitly handed to it, such as global state or unrestricted system calls. Oska has none.

**Root of authority**:
The program's entry point, `main`. The runtime grants `main` exactly the capabilities its signature declares, and every other capability in the program comes from those.
_Avoid_: root token, `Root`

**Attenuation**:
Producing a narrower capability from one you already hold, for example a directory capability from `Fs`. Attenuation never widens authority.
_Avoid_: derive, narrow, restrict (as nouns for the concept)

**Directory capability**:
A capability confined to one directory and everything beneath it, such as `DirRead`. All access to a directory goes through one.
_Avoid_: restricted Fs, sandboxed filesystem

**File capability**:
A capability confined to a single file, such as `FileRead`. Using it takes no path.

**Capability-bearing type**:
A type that is a capability or that contains one, directly or transitively. This includes containment through type arguments, as in `List<Stdout>`, and closures that capture a capability.

**Authority**:
For a function, the set of capabilities it can reach through its capability-bearing parameters. For a package, the union of the authority of its public functions, counted in built-in capability kinds. Which directory or file a capability is confined to is the caller's choice and is not part of a package's authority.

**Widening**:
A change after which a dependency's authority includes a capability kind it did not have, or a broader kind in place of a narrower one. A widening must be approved before the build accepts it.
_Avoid_: escalation, upgrade (for this concept)

**Pure function**:
A function with no capability-bearing parameters. It cannot perform effects, and it is deterministic.

**Pre-state value**:
A value in a postcondition captured with `old(...)` when the function is entered, before a mutating method changes its receiver.
_Avoid_: snapshot, previous value

**Program input**:
Data given to `main` that grants no authority, such as `Args`.
_Avoid_: calling it a capability

**Mutating method**:
A method that declares `var self`. It can change its receiver in place, and can only be called on a `var` binding.
_Avoid_: inout, mut ref

**Prelude**:
The built-in declarations, written in Oska, that every program can use without importing them, such as `Int`, `Option`, `Result`, and the built-in capabilities.
_Avoid_: stdlib (for this subset), builtins

**Checked program**:
A program the checker has accepted, with every name, method call, and conversion already resolved. The interpreter runs only checked programs.
_Avoid_: IR, compiled program

**Panic**:
A runtime failure that stops the current task and cannot be caught, such as integer overflow or an out-of-bounds index. A panic means the program has a bug; an `Err` returned from `main` does not.
_Avoid_: exception, crash

## Untrusted data

**Untrusted value**:
Text or bytes that came from outside the program, through a capability or a program input. Text operations keep a value untrusted. Converting it to a non-text or validated type makes it trusted.
_Avoid_: tainted, dirty, unsafe input

**Validator**:
A function that inspects an untrusted value and, only if the value passes its checks, returns a trusted value of a validated type, such as an `Email`.
_Avoid_: sanitizer

**Trust assertion**:
An explicit, audited point where code declares untrusted text trusted, normally inside a validator.
_Avoid_: untaint, sanitize, cast

**Audit site**:
A place in the source where code deliberately weakens a guarantee, such as a trust assertion or a secret exposure. Tooling lists every audit site for review.
_Avoid_: escape hatch (informal)

**Secret value**:
A value whose contents are never displayed, logged, or interpolated. The only way to read it is an explicit, auditable exposure.
_Avoid_: sensitive, private

**Secret integer**:
A secret value of a fixed-width unsigned integer type, such as `Secret<U32>`. Code may compute with it but never branch on it or index with it, so its value cannot affect timing.
_Avoid_: constant-time int, CtU32

**Sink**:
An API where data leaves the program or affects how it behaves, such as SQL queries, process execution, HTML output, filesystem paths, network hosts, or logs.

**Sink literal**:
A string literal tagged with the name of a sink, such as `sql"..."`. It provides the text for a structural position and can never interpolate values.
_Avoid_: tagged string, raw query

**Data position**:
An argument to a sink that is treated only as data. It accepts untrusted values. Examples are SQL parameters, escaped HTML text, and process arguments.

**Structural position**:
An argument to a sink that decides code, commands, paths, or destinations. It rejects untrusted values. Examples are SQL query text, a program name, `TrustedHtml`, an attenuation directory, and a network host.

## Packages

**Module**:
One source file. Its items are private unless marked `pub(pkg)` or `pub`.

**Package**:
A set of modules published together from one git repository and named by its URL. Its `pub` items are its API, and its authority is counted over that API alone.
_Avoid_: crate, library (for this concept)

**Manifest**:
The file in which a package states its identity, its direct dependencies, and the authority approved for each one.
_Avoid_: package file, config

**Lockfile**:
The record of the exact version, commit, content hash and computed authority of every package in the dependency graph.

**Direct dependency**:
A package named in the manifest. Only direct dependencies need authority approval.