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

# ASL/AUTH-HOST-IMAGE/1 - Bootable Image and Overlay Layout

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

**Document ID:** `ASL/AUTH-HOST-IMAGE/1`
**Layer:** O2I - Authority host image profile

**Depends on (normative):**

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

**Informative references:**

* `ASL/AUTH-HOST-CONFIG/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 a bootable, offline authority host image. It specifies
base system requirements, overlay layout, and the boot workflow used to
initialize authority operations.

---

## 2. Base Image Requirements

The base OS MUST:

* Boot in offline mode by default
* Include minimal POSIX tooling
* Disable network services unless explicitly enabled

---

## 3. Overlay Layout

```
/overlay/
├── bin/
│   ├── asl-auth-host
│   ├── asl-rescue
│   └── init-asl-host.sh
│   └── sign_dam.sh
│   └── add_artifact.sh
├── etc/
│   └── asl-auth-host/
│       ├── config.yaml
│       └── policy.hash
├── var/
│   ├── lib/
│   │   └── asl/
│   │       ├── common/
│   │       ├── personal/
│   │       └── pools/
│   └── log/
│       └── asl-auth-host.log
└── usr/
    └── local/
        └── bin/
            └── asl-admin
```

The overlay MUST be merged into the ISO root at build time.

---

## 4. ISO Root Layout (Runtime)

```
/iso_root/
├── bin/
├── etc/
│   └── asl-auth-host/
├── var/
│   ├── lib/
│   │   └── asl/
│   └── log/
└── usr/local/bin/
```

---

## 5. Boot Workflow

1. Boot offline image.
2. Run `init-asl-host.sh` to mount storage pools and apply config.
3. Initialize or open domain stores per config.
4. Start the authority host service.
5. Enforce witness authority (DAM) before general userspace services start.

---

## 6. Persistence Strategy

Writable storage MUST be mounted separately from the read-only system image.
Examples:

* ZFS datasets mounted under `/var/lib/asl`
* External disk mounted at `/mnt` and bound to `/var/lib/asl`

---

## 7. Build Pipeline (Informative)

A typical pipeline:

1. Create minimal root via debootstrap or equivalent.
2. Merge overlay into ISO root.
3. Configure bootloader (isolinux or GRUB).
4. Build ISO with xorriso or equivalent.

---

## 8. Container Build Notes (Informative)

Building the ISO in a container is supported with the following constraints:

* ZFS pool creation typically requires host kernel support; create datasets at
  boot time instead.
* The ISO filesystem and overlay can be built entirely in a Debian container.
* Boot testing must occur on a VM or physical host.

Recommended packages in the build container:

```
debootstrap squashfs-tools xorriso genisoimage
```

---

## 9. Offline Debian Mirror Workflow (Informative)

To build offline images without network access, create a local Debian mirror
as an artifact and use it with `debootstrap`.

Example (online host):

```
debmirror \
  --arch=amd64 \
  --section=main \
  --dist=bullseye \
  --method=http \
  --host=deb.debian.org \
  --root=debian \
  /srv/debian-mirror
```

Offline build:

```
debootstrap --arch=amd64 bullseye /target/root file:///srv/debian-mirror
```

The mirror directory SHOULD be treated as immutable input for reproducibility.

---

## 10. Pre-Image Capture Workflow (Informative)

To preserve provenance of the ISO build, capture each build step as artifacts
and receipts before composing the final image.

Suggested workflow:

1. Initialize a temporary ASL store for build artifacts.
2. Wrap debootstrap and package installation in `asl-capture`.
3. Capture overlay binaries and scripts as artifacts.
4. Run the ISO build under `asl-capture` to produce a final ISO artifact.
5. Seed the ISO with the captured artifacts and receipts.
3. Optionally wrap build steps with `asl-capture` to record build provenance.
4. Add bootloader config.
5. Build ISO with `xorriso` or equivalent tool.

---

## 8. Versioning

Backward-incompatible image changes MUST bump the major version.