Auth

The Auth modules define Kit's object-capability authority tokens. Programs receive root authority from the runtime, derive narrower tokens, and pass those tokens to functions that need file, network, environment, process, entropy, or concurrency access.

Unforgeable Authorities

Authority constructors are protected outside test blocks, including through imported package code. Application code should derive authority from env.root with Auth.* helpers instead of constructing tokens directly.

Authority Hierarchy

RootAuth
  +-- FileAuth
  |     +-- FileReadAuth
  |     +-- FileWriteAuth
  +-- NetAuth
  |     +-- TCPAuth
  |     |     +-- TCPConnectAuth
  |     |     +-- TCPListenAuth
  |     +-- UDPAuth
  |     +-- DNSAuth
  +-- EnvAuth
  +-- ProcessAuth
  +-- EntropyAuth
  +-- ConcurrencyAuth
        +-- ActorAuth
        +-- ChannelAuth
        +-- ParallelAuth

Auth.Root

RootAuth

type RootAuth

Root authority represents complete system access and is the source for all narrower authorities.

Auth.File

file-auth

RootAuth -> FileAuth

Derives general file authority from root authority.

import Auth.File.{file-auth, file-read-auth}

main = fn(env: Env) =>
  file = file-auth env.root
  read = file-read-auth file

file-read-auth / file-write-auth

FileAuth -> FileReadAuth / FileAuth -> FileWriteAuth

Derives read-only or write-only file authority from general file authority.

Auth.Net

net-auth

RootAuth -> NetAuth

Derives general network authority from root authority.

tcp-auth / udp-auth / dns-auth

NetAuth -> TCPAuth / NetAuth -> UDPAuth / NetAuth -> DNSAuth

Derives protocol-specific network authority. TCPAuth can be further narrowed with tcp-connect-auth or tcp-listen-auth.

Auth.Env

env-auth

RootAuth -> EnvAuth

Derives authority to read process environment variables.

Auth.Process

process-auth

RootAuth -> ProcessAuth

Derives authority to spawn and manage external processes.

Auth.Entropy

entropy-auth

RootAuth -> EntropyAuth

Derives authority for nondeterministic operations such as random number generation and UUID generation.

Auth.Concurrency

concurrency-auth

RootAuth -> ConcurrencyAuth

Derives full concurrency authority from root authority.

actor-auth / channel-auth / parallel-auth

ConcurrencyAuth -> ActorAuth / ConcurrencyAuth -> ChannelAuth / ConcurrencyAuth -> ParallelAuth

Derives narrower authority for actors, channels, or parallel execution.

Scoped Evidence

Use using when a guarded operation should see an already named capability as lexical evidence without adding a throwaway bare expression. It is compile-time-only evidence: it does not pass hidden arguments, install ambient authority, import names, run enter/exit hooks, or imply cleanup.

import Auth.Entropy.{EntropyAuth, entropy-auth}

main = fn(env: Env) =>
  auth: EntropyAuth = entropy-auth env.root
  value = using auth =>
    Math.random
  value

using accepts one or more direct identifiers whose types are known capability types. Evidence is borrowed, so a using scope does not count as consumption for @linear or @relevant values.

Testing

Test blocks may construct mock authority tokens directly so capability-aware wrappers can be tested without granting real process-wide authority. Outside tests, direct constructors are rejected; use the derivation helpers above and pass the resulting tokens explicitly.