/*
  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_mint.h - MINT: mint a fresh identity onto a blank thumbdrive
 * (FABRIC-3.md §F.8/§F.19), the last piece of the original Tripod
 * vision. Writes a real keypair, a Zuse-signed cert, and a minimal
 * working default personality -- everything RUNCAP (capsule_runcap.h)
 * and CERTVERIFY need at a later attach.
 */

#ifndef STARKERNEL_CAPSULE_MINT_H
#define STARKERNEL_CAPSULE_MINT_H

#ifdef __STARKERNEL__

#include <stdint.h>
#include "vm.h"

struct blkio_dev;

typedef enum {
    MINT_OK = 0,
    MINT_ERR_ALREADY_MINTED, /* dev already reads as a recognized home-blocks
                               * drive -- refuses rather than overwrite,
                               * mirroring WRITE(10)'s own blank-media
                               * posture (§F.8, decided 2026-08-28). */
    MINT_ERR_NO_ZUSE_CERT,   /* issuer_vm->zuse_cert_installed is 0 -- no
                               * key to sign the new cert with. */
    MINT_ERR_NO_ENTROPY,     /* virtio_rng not ready. */
    MINT_ERR_CERT_BUILD,     /* x509_build_user_cert() failed (shouldn't
                               * happen with fixed-size fields, but not
                               * assumed away). */
    MINT_ERR_WRITE_FAIL,     /* a devblock write failed partway through --
                               * the drive may be left partially minted. */
    MINT_ERR_INVALID_PROFILE, /* full_name/username missing or too long for
                               * user_identity_seed_t's fixed fields, or
                               * email/phone too long (both may be NULL/empty
                               * -- that's "null", not invalid). */
} MintResult;

/**
 * capsule_mint_identity - Mint a fresh identity onto dev.
 *
 * Layout written (devblock offsets from dev's own start; devblock 0 is
 * left alone, reserved for the block-subsystem's own generic header):
 *   devblock 1        homeblocks_sig_t            (HOMEBLOCKS_SIG_START_FBLOCK)
 *   devblock 2        DER cert, Zuse-signed        (cert_offset)
 *   devblock 3        user_identity_seed_t         (identity_src_offset)
 *   devblock 4        default personality source   (identity_src_offset+1)
 *
 * @param dev        Already-open block device for the target drive.
 * @param issuer_vm  The signing identity -- in practice always Hera's own
 *                   VM (Zuse's cert lives there, vm.h's zuse_cert_seed).
 * @param full_name  Required, NUL-terminated, fits user_identity_seed_t's
 *                   full_name field (§F.20).
 * @param username   Required, NUL-terminated, fits its username field.
 * @param email      NULL or empty string = null (field stays empty).
 * @param phone      NULL or empty string = null (field stays empty).
 * @return MINT_OK on success, an error code otherwise.
 */
MintResult capsule_mint_identity(struct blkio_dev *dev, VM *issuer_vm,
                                  const char *full_name, const char *username,
                                  const char *email, const char *phone);

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_CAPSULE_MINT_H */