# Snigdha Amnesia: Architecture & Volatile Session Infrastructure

Distribution: Snigdha OS Decentralized
Milestone: Phase 2 — Amnesia Architecture & Volatile Session Infrastructure
Kernel Target: linux-hardened (x86_64)
Profile Engine: ArchISO baseline with Snigdha Security Extensions

# 1. Executive Architectural Summary

Snigdha Amnesia is the foundational operating-system-level security subsystem of Snigdha OS Decentralized. Its primary mandate is to enforce session ephemerality: normal operating system state modifications, application caches, user documents, shell histories, and system configurations are confined strictly to volatile, memory-backed storage and are discarded immediately when the machine shuts down.

Amnesia is not an ad-hoc collection of cleanup scripts executed upon logout. It is an end-to-end architecture integrated across the bootloader, Linux kernel parameters, initramfs image generation, OverlayFS mount architecture, systemd session and service lifecycles, and a dedicated low-level watchdog daemon.

flowchart TD
    subgraph BootStage["1. Bootloader & Kernel Configuration"]
        BL["GRUB / Syslinux / systemd-boot"] --> KP["Kernel Parameters:\ninit_on_free=1\ninit_on_alloc=1\npage_alloc.shuffle=1\nslab_nomerge\nsystemd.swap=0\nsystemd.gpt_auto=0\nzswap.enabled=0\ncow_spacesize=2G"]
    end

    subgraph InitramfsStage["2. Initramfs Early Boot & OverlayFS Setup"]
        KP --> RD["ArchISO Initramfs (mkinitcpio)"]
        RD --> RO["Read-Only System Image\n(/run/archiso/airootfs.erofs)"]
        RD --> CS["Volatile cowspace (tmpfs in RAM)\n(/run/archiso/cowspace)"]
        RO --> OFS["OverlayFS Root Mount (/)\nlowerdir: read-only airootfs\nupperdir: tmpfs /cowspace/upperdir\nworkdir: tmpfs /cowspace/workdir"]
        CS --> OFS
        RD --> POP["snigdha_amnesia_shutdown hook:\nPopulates /run/initramfs with /shutdown"]
    end

    subgraph RuntimeStage["3. Runtime Verification & Desktop Session"]
        OFS --> GRD["snigdha-amnesia-guard.service\n(Validates 8 core invariants before session start)"]
        GRD -->|FAIL| REC["Emergency Console / Halt\n(Fail-Closed Isolation)"]
        GRD -->|PASS| WD["snigdha-media-watchdog.service\n(mlockall + Netlink block monitor)"]
        GRD -->|PASS| UI["i3wm Desktop Session (snigdha)"]
    end

    subgraph ShutdownStage["4. Amnesic Shutdown & Memory Release"]
        UI -->|User Shutdown / Reboot| SD1["systemd shutdown transaction"]
        WD -->|Media Disconnection Event| ESD["Emergency Poweroff (-ff)"]
        SD1 --> SD2["snigdha-amnesia-shutdown.service\n(sync + echo 3 > /proc/sys/vm/drop_caches)"]
        SD2 --> PIV["systemd-shutdown pivot to /run/initramfs/shutdown"]
        ESD --> PIV
        PIV --> UMO["Unmount /oldroot (OverlayFS released)\nFreeing upperdir pages -> init_on_free zeros pages"]
        UMO --> DET["losetup -d (Detach loop devices)"]
        DET --> PWR["Direct kernel poweroff -f / reboot -f"]
    end

# 2. Component A — Volatile Root Filesystem

The operating system root filesystem (/) is mounted dynamically during early initramfs boot using Linux OverlayFS.

# 2.1 OverlayFS Architecture

       Read-Only System Image
      (/snigdha/x86_64/airootfs.erofs)
                  │
                  ▼
          [Loopback Device]
                  │
                  ▼
     ┌────────────────────────┐
     │ lowerdir (Read-Only)   │
     │ /run/archiso/airootfs  │
     └───────────┬────────────┘
                 │
                 ├──────────────────────────────────────┐
                 │                                      │
                 ▼                                      ▼
     ┌────────────────────────┐             ┌────────────────────────┐
     │ upperdir (Writable)    │             │ workdir (Metadata)     │
     │ /run/archiso/cowspace/ │             │ /run/archiso/cowspace/ │
     │  persistent_SNIGDHA... │             │  persistent_SNIGDHA... │
     │  /x86_64/upperdir      │             │  /x86_64/workdir       │
     └───────────┬────────────┘             └────────────────────────┘
                 │ (Backed by tmpfs in RAM)
                 ▼
     ┌────────────────────────┐
     │ Live Root Filesystem   │
     │ /                      │
     └────────────────────────┘

• Lower Layer (lowerdir): Backed by the immutable EROFS image (airootfs.erofs) mounted via a read-only loop device. Any modification attempt to files residing exclusively in the lower layer triggers copy-up into the upper layer.
• Upper Layer (upperdir): Resides in /run/archiso/cowspace/.../upperdir. Under Snigdha Amnesia, cowspace is mounted strictly on tmpfs. Session modifications are written to memory and never touch persistent physical storage.
• Work Directory (workdir): Required by Linux OverlayFS for atomic operations; resides on the same tmpfs instance as upperdir.
• Sizing Policy: The volatile upperdir size defaults to cow_spacesize=2G via bootloader configuration. This accommodates desktop application caches and temporary operations while running reliably on machines with 4 GB of RAM.

# 2.2 Fail-Closed Invariant Enforcement

Before the graphical desktop or login getty is started, snigdha-amnesia-guard.service inspects /proc/mounts:

1. Verifies root filesystem (/) is of type overlay.
2. Verifies lowerdir is read-only.
3. Verifies upperdir resides on a tmpfs filesystem. If any check fails, the guard blocks session startup, emits emergency diagnostics to /dev/console, and refuses to boot into graphical mode.

# 3. Component B — Ephemeral Session Storage

All standard system and user paths reside inside the volatile architecture:

# 4. Component C — Mandatory Swap Elimination

Disk-backed swap is strictly prohibited. In a privacy-focused distribution, swap partitions or swapfiles can silently flush memory pages (containing plaintext passwords, encryption keys, and application state) to unencrypted persistent host storage.

# 4.1 Multi-Layered Swap Elimination Matrix

1. Bootloader Kernel Arguments:
   • systemd.swap=0: Disables systemd swap unit generation.
   • systemd.gpt_auto=0: Disables GPT auto-discovery of swap and system partitions.
   • zswap.enabled=0: Disables the zswap compressed cache.
2. Systemd Target Masking:
   • /etc/systemd/system/swap.target is symlinked to /dev/null.
   • /etc/systemd/system-generators/systemd-gpt-auto-generator is masked to /dev/null.
3. Runtime Invariant Verification:
   • snigdha-amnesia-check queries /proc/swaps and swapon --show. If any swap device is detected, the check fails immediately.
4. Out-Of-Memory (OOM) Behavior:
   • When physical RAM is exhausted under extreme memory pressure, the Linux kernel OOM killer terminates processes rather than paging to disk. This is a deliberate, documented security-over-availability trade-off.

# 5. Component D — Internal Storage Protection

Snigdha OS Decentralized must not automatically mount, scan, index, or write to host computer storage devices.

• Automount Daemon Elimination: Neither udisks2 nor gvfs automounting daemons are installed or running.
• Storage Protection udev Rule (/etc/udev/rules.d/60-snigdha-storage.rules): Marks all block devices with ENV{UDISKS_AUTO}="0" and ENV{UDISKS_IGNORE}="1".
• Polkit Authorization Policy (/etc/polkit-1/rules.d/50-snigdha-storage.rules): Denies unprivileged users the ability to mount block devices without explicit administrator authorization.
• Sleep / Suspend Restrictions (/etc/systemd/sleep.conf.d/disable-sleep.conf): All suspend, hibernate, and hybrid sleep modes are disabled. Sleep targets (sleep.target, suspend.target, hibernate.target, hybrid-sleep.target, suspend-then-hibernate.target) are masked to /dev/null. This eliminates the risk of host media removal during suspend or writing memory to disk hibernation areas.
• Least Privilege: The live user snigdha is removed from group storage to eliminate raw access to SCSI block devices.

# 6. Component E — Per-Boot Ephemeral Identity

To prevent cross-session correlation:

• /etc/machine-id: Sealed in the image as uninitialized\n. During boot, systemd generates a transient 128-bit machine identifier in volatile storage. Each boot cycle produces a distinct ID.
• /var/lib/dbus/machine-id: Symlinked to /etc/machine-id.
• /var/lib/systemd/random-seed: Omitted from the filesystem image to avoid seed reuse across reboots. Entropy is gathered freshly at boot from kernel and CPU hardware RNG (RDRAND/RDSEED).
• SSH Host Keys: No private host keys exist in /etc/ssh/.

# 7. Component F — Kernel Memory-Residual Mitigation

• init_on_free=1: Configured across all bootloader entries. Instructs the Linux buddy and slab allocators to zero memory pages immediately upon release (free_pages(), kfree()). When processes terminate or files are unlinked from tmpfs, their memory content is overwritten with zeros.
• init_on_alloc=1: Enforced by default in linux-hardened (CONFIG_INIT_ON_ALLOC_DEFAULT_ON=y) and declared on cmdline.
• page_alloc.shuffle=1: Randomizes allocator page freelists on boot.
• slab_nomerge: Disables slab cache merging, maintaining strict boundaries between kernel object allocations.

# 8. Component G — Amnesic Shutdown Architecture

A normal Linux shutdown unmounts userspace filesystems but cannot release the root OverlayFS while running from it. Snigdha Amnesia implements a return-to-initramfs architecture:

1. Pre-Shutdown Service (snigdha-amnesia-shutdown.service):
   • Ordered After=final.target, Before=shutdown.target.
   • Executes sync.
   • Drops clean caches (echo 3 > /proc/sys/vm/drop_caches), triggering init_on_free=1 memory zeroing.
2. Initramfs Setup (snigdha_amnesia_shutdown Hook):
   • During early boot, run_cleanuphook() duplicates the minimal initramfs root into /run/initramfs (in RAM).
   • Installs /run/initramfs/shutdown.
3. systemd-shutdown Transition:
   • After all user processes and regular services stop, systemd-shutdown detects /run/initramfs/shutdown.
   • Executes pivot_root("/run/initramfs", "/run/initramfs/oldroot").
4. Final Initramfs Release (/shutdown):
   • Running from RAM at /, the script executes umount --recursive /oldroot.
   • Detaches loopback devices (losetup -d).
   • Releases cowspace (tmpfs), zeroing all freed session pages via init_on_free=1.
   • Invokes final poweroff -f or reboot -f.

# 9. Component H — Boot-Medium Removal Watchdog

When the live USB boot device is unexpectedly removed, the operating system must not continue executing in a corrupted state.

• Binary: /usr/bin/snigdha-media-watchdog (compiled C99 binary).
• Memory Locking: Calls mlockall(MCL_CURRENT | MCL_FUTURE) on startup. All program text, data, and stack pages are locked in physical RAM. No page faults or disk reads are required after media removal.
• Zero-Polling Netlink Listener: Opens a NETLINK_KOBJECT_UEVENT socket. Blocks with 0.0% CPU overhead until the kernel emits device events.
• Device Resolution: Resolves the device backing /run/archiso/bootmnt (e.g. sdb1) and tracks its parent whole-disk node (sdb). Unrelated USB devices (keyboards, mice, secondary flash drives) are ignored.
• Emergency Reaction: Upon detecting ACTION=remove matching the boot medium:
  1. Emits critical alert to /dev/kmsg and stderr.
  2. Spawns systemctl --force --force poweroff.
  3. If userspace execution hangs, invokes kernel syscall reboot(LINUX_REBOOT_CMD_POWER_OFF).

# 10. Component I — Runtime Guard & Diagnostics

# 10.1 snigdha-amnesia-check

Read-only CLI diagnostics tool evaluating the 8 core invariants:

snigdha-amnesia-check
snigdha-amnesia-check --json
snigdha-amnesia-check --fail-closed

# 10.2 snigdha-amnesia-guard.service

A systemd oneshot unit executing snigdha-amnesia-check --fail-closed before display-manager.service, graphical.target, and getty@tty1.service. If any critical invariant fails, autologin is aborted and the desktop session will not launch.

# 11. Security Boundaries & Architectural Limitations

1. Physical RAM Persistence (Cold-Boot Attacks):
   init_on_free=1 zeros memory when pages are freed. Un-freed kernel memory structures or data remaining in RAM until the instant of power loss can theoretically persist for seconds to minutes in cold DRAM cells. Complete physical RAM overwrite requires dedicated BIOS/UEFI wiping or specialized kexec payloads.
2. Network Traffic:
   Phase 2 does not anonymize network traffic. Network connections remain standard clearnet. Tor routing and DNS leak prevention are scheduled for Phase 3.
3. Encrypted Persistence:
   No persistent LUKS storage is active in Phase 2.