/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  Licensed under the StarForth License, Version 1.0
*/

/**
 * capsule_zuse_boot.h - Thumbdrive-resident Zuse genesis/attach
 * (FABRIC-3.md §F.20/§F.21). Replaces kernel_main.c's old one-shot
 * block-fence mint-or-load: Zuse's own identity now lives only on her
 * own minted thumbdrive, never system-resident. Since USB attach
 * detection only happens inside the idle loop (sk_repl_idle(), not at
 * a fixed point in the boot sequence), this runs per-attach from there
 * instead of once at boot.
 */

#ifndef STARKERNEL_CAPSULE_ZUSE_BOOT_H
#define STARKERNEL_CAPSULE_ZUSE_BOOT_H

#ifdef __STARKERNEL__

#include "starkernel/homeblocks_sig.h"
#include "vm.h"

struct blkio_dev;

/**
 * capsule_zuse_boot_try_attach - Try to genesis-mint or authenticate
 * Zuse from a just-attached drive.
 *
 * No-op if mama_vm->zuse_cert_installed is already 1 (Zuse already has a
 * real identity this boot, from an earlier attach). Otherwise:
 *   - No genesis marker yet in the fence, drive reads HOMEBLOCKS_SIG_BLANK:
 *     mint Zuse's own identity onto it (capsule_mint_identity(), genesis
 *     mode), record the pubkey in the fence, install the cert, and
 *     re-run ACL-ZUSE-BOOT (zuse.4th) so zuse_session activates exactly
 *     like it always has for a same-boot-installed cert.
 *   - Genesis marker present, drive reads HOMEBLOCKS_SIG_OK: read its
 *     own user_identity_seed_t, compare pubkey against the marker: if it
 *     matches, install the cert and re-run ACL-ZUSE-BOOT the same way.
 *     If it doesn't match, this is some other identity's drive -- no-op
 *     here, that's a regular attach for BINDSTEP to handle later.
 *   - Anything else (foreign/corrupt media, no marker and non-blank
 *     drive): no-op.
 *
 * @param dev     The just-attached, already-open block device.
 * @param sig_rc  homeblocks_sig_check()'s own result for this attach.
 * @param sig     The checked homeblocks_sig_t (only meaningful if
 *                sig_rc == HOMEBLOCKS_SIG_OK; may be NULL otherwise).
 * @param mama_vm Hera's own VM (zuse_cert_seed/installed/session live
 *                here; also the target of the ACL-ZUSE-BOOT re-run).
 */
void capsule_zuse_boot_try_attach(struct blkio_dev *dev,
                                   homeblocks_sig_result_t sig_rc,
                                   const homeblocks_sig_t *sig,
                                   VM *mama_vm);

/**
 * capsule_zuse_boot_logout - End Zuse's session when her own attached
 * drive detaches (FABRIC-3.md §I.8, re-scoped 2026-09-04: no identity is
 * different here -- Zuse logs out on device removal exactly like a
 * WIREBIND user does, not via a Stadium-patron TTL. She has no separate
 * VM or blocks of her own, so unlike capsule_wirebind_eject()/
 * _unclean_detach() there is no flush step to skip on the abrupt path --
 * one function covers both the graceful (EJECT) and abrupt (hot-unplug)
 * call sites identically.
 *
 * No-op if the currently-tracked attached device isn't Zuse's own
 * (nothing to do -- some other identity's drive is what's leaving, or
 * nothing is attached at all). Clears mama_vm->zuse_session only --
 * zuse_cert_installed and the cert itself stay put, permanently, per
 * vm_zuse_cert_install()'s own one-way design; re-attaching her own
 * drive re-authenticates via capsule_zuse_boot_try_attach() without
 * re-minting anything.
 *
 * @param mama_vm Hera's own VM (zuse_session lives here).
 */
void capsule_zuse_boot_logout(VM *mama_vm);

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_CAPSULE_ZUSE_BOOT_H */