amduat-api/ops/asl-auth-host-config-1.md

# ASL/AUTH-HOST-CONFIG/1 - Configuration Schema

Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2026-01-17
Tags: [ops, authority, config]

**Document ID:** `ASL/AUTH-HOST-CONFIG/1`
**Layer:** O2C - Authority host configuration

**Depends on (normative):**

* `ASL/AUTH-HOST/1`
* `ASL/HOST/1`

**Informative references:**

* `ENC-ASL-AUTH-HOST/1`

---

## 0. Conventions

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be
interpreted as in RFC 2119.

---

## 1. Purpose and Scope

This document defines the configuration schema for an ASL authority host.
Configuration is expressed as a single YAML file.

---

## 2. File Format

* UTF-8 YAML 1.2
* Root object with the fields defined below
* Unknown fields SHOULD be ignored with warning

---

## 3. Root Schema

```
host:
  name: string
  version: string
  mode: "rescue" | "admission" | "normal"

domains:
  <name>:
    id: string
    type: "courtesy" | "private" | "authority"
    description: string
    path: string
    snapshot_retention: duration
    allowed_operations: [read, write, append, seal, gc]
    courtesy_lease: duration

certificates:
  root_offline_path: string
  domain_authority_path: string
  sops_bundle_path: string

policy:
  hash_file: string
  description: string

logging:
  path: string
  level: "DEBUG" | "INFO" | "WARN" | "ERROR"

store:
  type: "posix" | "zfs"
  pools:
    - name: string
      mount_point: string
  enable_snapshotting: boolean
  snapshot_prefix: string

hooks:
  pre_start: string
  post_start: string
```

---

## 4. Semantics

* `host.mode` controls startup behavior.
* `domains` entries are keyed by stable names; `id` is the authoritative domain
  identifier.
* `courtesy_lease` is required for `type: courtesy` and MUST be omitted for
  `type: authority`.
* `store.type` selects the host backend. If `zfs`, each pool entry MUST be
  mounted before starting the host.

---

## 5. Example Configuration

```yaml
host:
  name: "asl-auth-host-01"
  version: "0.1"
  mode: "rescue"

domains:
  common:
    id: "00000000-0000-0000-0000-000000000001"
    type: "courtesy"
    description: "Shared courtesy domain"
    path: "/var/lib/asl/common"
    snapshot_retention: 30d
    allowed_operations: [read, write, append]
    courtesy_lease: 7d
  personal:
    id: "00000000-0000-0000-0000-000000000002"
    type: "private"
    description: "Private rescue domain"
    path: "/var/lib/asl/personal"
    snapshot_retention: 90d
    allowed_operations: [read, write, append, seal, gc]

certificates:
  root_offline_path: "/var/lib/asl/certs/root-offline"
  domain_authority_path: "/var/lib/asl/certs/domain-authority"
  sops_bundle_path: "/var/lib/asl/certs/sops"

policy:
  hash_file: "/etc/asl-auth-host/policy.hash"
  description: "Offline policy hash"

logging:
  path: "/var/log/asl-auth-host.log"
  level: "INFO"

store:
  type: "zfs"
  pools:
    - name: "common_pool"
      mount_point: "/var/lib/asl/common"
    - name: "personal_pool"
      mount_point: "/var/lib/asl/personal"
  enable_snapshotting: true
  snapshot_prefix: "asl_snap"

hooks:
  pre_start: "/bin/init-asl-host.sh"
  post_start: "/bin/helper-mount.sh"
```

---

## 6. Versioning

Backward-incompatible schema changes MUST bump the major version.