# filosottile/age architecture

> Architecture diagram of the GitHub repository filosottile/age, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filosottile/age
- Repository: https://github.com/filosottile/age

## Overview

#### Purpose and Entry Points
`age` is a Go implementation of the age file-encryption format and a reusable library. Primary binaries are `age` for streaming encryption/decryption, `age-keygen` for key generation/conversion, and `age-inspect` for unauthenticated format metadata inspection. Entrypoints: `cmd/age/age.go`, `cmd/age-keygen/keygen.go`, and `cmd/age-inspect/inspect.go`.

#### Public Cryptographic API
The root package exposes recipient/identity abstractions and streaming encryption/decryption, separating callers from individual key mechanisms. Core API, parsing, and shared primitives are in `age.go`, `parse.go`, and `primitives.go`. Encryption wraps plaintext for one or more recipients; decryption tries supplied identities against encrypted header stanzas before exposing payload plaintext.

#### File Format and Streaming Boundary
The on-disk/wire format is implemented below the public API: header serialization/parsing and payload framing are in `internal/format/format.go`; authenticated chunked payload processing is in `internal/stream/stream.go`. This is the compatibility and security boundary for the age specification: callers provide `io.Reader`/`io.Writer`, allowing CLI pipelines without loading files into memory.

#### Native Recipient and Identity Types
Built-in key systems implement the public recipient/identity contracts: default X25519 keys in `x25519.go`, passphrase-based scrypt encryption in `scrypt.go`, and hybrid post-quantum ML-KEM/X25519 support in `pq.go`. Encoded key parsing relies on internal Bech32 support at `internal/bech32/bech32.go`. Multi-recipient encryption generates recipient-specific wrapped file keys while retaining one encrypted payload.

#### SSH and Tagged-Key Extensions
SSH public/private key interoperability is provided by `agessh/agessh.go` and `agessh/encrypted_keys.go`, including SSH key-file handling rather than agent integration. The `tag` package supplies tagged recipient/identity behavior in `tag/tag.go`; its companion test plugin demonstrates integration under `tag/internal/age-plugin-tagtest/plugin-tagtest.go`.

#### CLI Orchestration and User Interaction
The `age` CLI parses flags and key sources, resolves recipients/identities from arguments and files, invokes the root API, and owns filesystem/stdin/stdout behavior. Main orchestration and key-source handling reside in `cmd/age/age.go`, `cmd/age/parse.go`, and `cmd/age/encrypted_keys.go`. Terminal prompts and passphrase UX are separated into `cmd/age/tui.go` and shared terminal support in `internal/term/term.go`.

#### Plugin Protocol and Deployment Model
The plugin subsystem permits external recipient and identity implementations as subprocesses discoverable through `PATH`; client protocol logic is in `plugin/client.go`, `plugin/plugin.go`, and `plugin/encode.go`. Built-in plugin executables/examples include `cmd/age-plugin-batchpass/plugin-batchpass.go` and `extra/age-plugin-pq/plugin-pq.go`. The project targets supported Go runtimes (`go.mod`) and standard OS command-line environments; it has no server, database, or required network service. CI is GitHub Actions-based in `.github/workflows/build.yml` and `.github/workflows/interop.yml`.

Main entry points: [`age.go`](https://github.com/filosottile/age/blob/main/age.go) (Public crypto API), [`cmd/age/age.go`](https://github.com/filosottile/age/blob/main/cmd/age/age.go) (age CLI), [`plugin/client.go`](https://github.com/filosottile/age/blob/main/plugin/client.go) (Plugin protocol client), [`x25519.go`](https://github.com/filosottile/age/blob/main/x25519.go) (Native key types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_public_api["Public crypto API<br/>Go package<br/>[age.go]"]
  node_api_parsing["Key parsing &amp; primitives<br/>Go package<br/>[parse.go]"]
  node_format["Age file format<br/>internal package<br/>[format.go]"]
  node_stream["Authenticated stream<br/>internal package<br/>[stream.go]"]
  node_native_keys["Native key types<br/>Go implementations<br/>[x25519.go]"]
  node_bech32["Bech32 encoding<br/>internal package<br/>[bech32.go]"]
end

subgraph group_cli["Command-line tools"]
  node_age_cli{{"age CLI<br/>binary<br/>[age.go]"}}
  node_cli_key_sources["CLI key sources<br/>CLI layer<br/>[parse.go]"]
  node_cli_encrypted_keys["Encrypted key files<br/>CLI layer<br/>[encrypted_keys.go]"]
  node_terminal_ui["Terminal prompts<br/>CLI UI<br/>[tui.go]"]
  node_term["Terminal support<br/>internal package<br/>[term.go]"]
  node_keygen_cli{{"age-keygen<br/>binary<br/>[keygen.go]"}}
  node_inspect_cli{{"age-inspect<br/>binary<br/>[inspect.go]"}}
end

subgraph group_extensions["Extensions"]
  node_ssh["SSH key extension<br/>Go package<br/>[agessh.go]"]
  node_tag["Tagged keys<br/>Go package<br/>[tag.go]"]
  node_plugin_client["Plugin protocol client<br/>Go package<br/>[client.go]"]
  node_batchpass_plugin{{"Batchpass plugin<br/>plugin executable"}}
  node_pq_plugin{{"PQ plugin example<br/>plugin executable<br/>[plugin-pq.go]"}}
end

subgraph group_delivery["Build and compatibility"]
  node_go_runtime["Supported Go runtime<br/>runtime contract<br/>[go.mod]"]
  node_ci["CI build &amp; interop<br/>GitHub Actions<br/>[build.yml]"]
end

node_age_cli -->|"resolves keys"| node_cli_key_sources
node_age_cli -->|"loads key files"| node_cli_encrypted_keys
node_age_cli -->|"prompts"| node_terminal_ui
node_terminal_ui -->|"uses"| node_term
node_age_cli -->|"encrypts/decrypts"| node_public_api
node_keygen_cli -->|"creates keys"| node_native_keys
node_inspect_cli -->|"inspects headers"| node_format
node_public_api -->|"parses inputs"| node_api_parsing
node_public_api -->|"reads/writes headers"| node_format
node_public_api -->|"processes payload"| node_stream
node_public_api -->|"uses recipients/identities"| node_native_keys
node_native_keys -->|"encodes keys"| node_bech32
node_ssh -->|"implements contracts"| node_public_api
node_tag -->|"implements contracts"| node_public_api
node_plugin_client -->|"implements contracts"| node_public_api
node_plugin_client -.->|"launches via PATH"| node_batchpass_plugin
node_plugin_client -.->|"launches via PATH"| node_pq_plugin
node_go_runtime -.->|"builds"| node_public_api
node_ci -->|"validates"| node_go_runtime

click node_public_api "https://github.com/filosottile/age/blob/main/age.go"
click node_api_parsing "https://github.com/filosottile/age/blob/main/parse.go"
click node_format "https://github.com/filosottile/age/blob/main/internal/format/format.go"
click node_stream "https://github.com/filosottile/age/blob/main/internal/stream/stream.go"
click node_native_keys "https://github.com/filosottile/age/blob/main/x25519.go"
click node_bech32 "https://github.com/filosottile/age/blob/main/internal/bech32/bech32.go"
click node_age_cli "https://github.com/filosottile/age/blob/main/cmd/age/age.go"
click node_cli_key_sources "https://github.com/filosottile/age/blob/main/cmd/age/parse.go"
click node_cli_encrypted_keys "https://github.com/filosottile/age/blob/main/cmd/age/encrypted_keys.go"
click node_terminal_ui "https://github.com/filosottile/age/blob/main/cmd/age/tui.go"
click node_term "https://github.com/filosottile/age/blob/main/internal/term/term.go"
click node_keygen_cli "https://github.com/filosottile/age/blob/main/cmd/age-keygen/keygen.go"
click node_inspect_cli "https://github.com/filosottile/age/blob/main/cmd/age-inspect/inspect.go"
click node_ssh "https://github.com/filosottile/age/blob/main/agessh/agessh.go"
click node_tag "https://github.com/filosottile/age/blob/main/tag/tag.go"
click node_plugin_client "https://github.com/filosottile/age/blob/main/plugin/client.go"
click node_batchpass_plugin "https://github.com/filosottile/age/blob/main/cmd/age-plugin-batchpass/plugin-batchpass.go"
click node_pq_plugin "https://github.com/filosottile/age/blob/main/extra/age-plugin-pq/plugin-pq.go"
click node_go_runtime "https://github.com/filosottile/age/blob/main/go.mod"
click node_ci "https://github.com/filosottile/age/blob/main/.github/workflows/build.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_api_parsing,node_format,node_stream,node_native_keys,node_bech32 toneBlue
class node_age_cli,node_cli_key_sources,node_cli_encrypted_keys,node_terminal_ui,node_term,node_keygen_cli,node_inspect_cli toneAmber
class node_ssh,node_tag,node_plugin_client,node_batchpass_plugin,node_pq_plugin toneMint
class node_go_runtime,node_ci toneRose
```

## Components

### Core library

Public API, format, streaming, and built-in key systems.

- [Public crypto API](https://github.com/filosottile/age/blob/main/age.go): Go package · Recipient and identity contracts plus streaming encryption and decryption. · `age.go`
- [Key parsing & primitives](https://github.com/filosottile/age/blob/main/parse.go): Go package · `parse.go`
- [Age file format](https://github.com/filosottile/age/blob/main/internal/format/format.go): internal package · Header stanza serialization/parsing and payload framing. · `internal/format/format.go`
- [Authenticated stream](https://github.com/filosottile/age/blob/main/internal/stream/stream.go): internal package · Chunked authenticated payload encryption and decryption. · `internal/stream/stream.go`
- [Native key types](https://github.com/filosottile/age/blob/main/x25519.go): Go implementations · X25519, scrypt passphrase, and ML-KEM/X25519 recipients and identities. · `x25519.go`
- [Bech32 encoding](https://github.com/filosottile/age/blob/main/internal/bech32/bech32.go): internal package · `internal/bech32/bech32.go`

### Command-line tools

Streaming tools and terminal interaction.

- [age CLI](https://github.com/filosottile/age/blob/main/cmd/age/age.go): binary · Resolves key sources and streams files, stdin, and stdout through the public API. · `cmd/age/age.go`
- [CLI key sources](https://github.com/filosottile/age/blob/main/cmd/age/parse.go): CLI layer · `cmd/age/parse.go`
- [Encrypted key files](https://github.com/filosottile/age/blob/main/cmd/age/encrypted_keys.go): CLI layer · `cmd/age/encrypted_keys.go`
- [Terminal prompts](https://github.com/filosottile/age/blob/main/cmd/age/tui.go): CLI UI · Passphrase and interactive terminal UX. · `cmd/age/tui.go`
- [Terminal support](https://github.com/filosottile/age/blob/main/internal/term/term.go): internal package · `internal/term/term.go`
- [age-keygen](https://github.com/filosottile/age/blob/main/cmd/age-keygen/keygen.go): binary · Generates and converts keys. · `cmd/age-keygen/keygen.go`
- [age-inspect](https://github.com/filosottile/age/blob/main/cmd/age-inspect/inspect.go): binary · Reads unauthenticated format metadata. · `cmd/age-inspect/inspect.go`

### Extensions

SSH, tagged keys, and external plugin support.

- [SSH key extension](https://github.com/filosottile/age/blob/main/agessh/agessh.go): Go package · SSH public/private-key interoperability and encrypted SSH key-file handling. · `agessh/agessh.go`
- [Tagged keys](https://github.com/filosottile/age/blob/main/tag/tag.go): Go package · Tagged recipient and identity behavior. · `tag/tag.go`
- [Plugin protocol client](https://github.com/filosottile/age/blob/main/plugin/client.go): Go package · Discovers and communicates with recipient and identity subprocesses on PATH. · `plugin/client.go`
- [Batchpass plugin](https://github.com/filosottile/age/blob/main/cmd/age-plugin-batchpass/plugin-batchpass.go): plugin executable · `cmd/age-plugin-batchpass/plugin-batchpass.go`
- [PQ plugin example](https://github.com/filosottile/age/blob/main/extra/age-plugin-pq/plugin-pq.go): plugin executable · `extra/age-plugin-pq/plugin-pq.go`

### Build and compatibility

- [Supported Go runtime](https://github.com/filosottile/age/blob/main/go.mod): runtime contract · `go.mod`
- [CI build & interop](https://github.com/filosottile/age/blob/main/.github/workflows/build.yml): GitHub Actions · `.github/workflows/build.yml`

## Connections

- age CLI → CLI key sources: resolves keys
- age CLI → Encrypted key files: loads key files
- age CLI → Terminal prompts: prompts
- Terminal prompts → Terminal support: uses
- age CLI → Public crypto API: encrypts/decrypts
- age-keygen → Native key types: creates keys
- age-inspect → Age file format: inspects headers
- Public crypto API → Key parsing & primitives: parses inputs
- Public crypto API → Age file format: reads/writes headers
- Public crypto API → Authenticated stream: processes payload
- Public crypto API → Native key types: uses recipients/identities
- Native key types → Bech32 encoding: encodes keys
- SSH key extension → Public crypto API: implements contracts
- Tagged keys → Public crypto API: implements contracts
- Plugin protocol client → Public crypto API: implements contracts
- Plugin protocol client → Batchpass plugin: launches via PATH
- Plugin protocol client → PQ plugin example: launches via PATH
- Supported Go runtime → Public crypto API: builds
- CI build & interop → Supported Go runtime: validates
