Skip to content

RFC-HYOPS-INIT-1.0

Status: Stable (Public)
Version: 1.0

1. Abstract

This document defines the HybridOps Credential Initialization Protocol (hyops init <target>), covering credential collection, vault handling, runtime layout, evidence requirements, and exit codes. Target annexes extend normative behaviour.

2. Normative language

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

3. Terminology

  • Runtime Root — Base directory where HybridOps stores runtime material; defaults to ~/.hybridops.
  • Credential Pack — Target-specific set of fields required during init.
  • Vault — A single ansible-vault encrypted env file storing secrets.
  • Readiness Marker — A JSON document indicating successful initialisation.
  • Evidence — Non-secret execution records.

4. Command surface

hyops init <target>
  [--root <dir>]
  [--config <path>]
  [--vault-file <path>]
  [--vault-password-file <path> | --vault-password-command <cmd>]
  [--non-interactive]
  [--force]
  [--dry-run]

Norms:

  • <target> MUST be supported.
  • --root MUST redefine runtime root for the invocation.
  • --dry-run MUST NOT write credentials, readiness markers, or vault updates.
  • --non-interactive MUST suppress prompts.

5. Runtime layout

Default runtime root: ~/.hybridops.

Reserved directories:

  • config/ non-secret configuration
  • credentials/ sensitive credential files (mode 0600)
  • vault/ encrypted env bundles
  • meta/ readiness markers
  • logs/ redacted evidence
  • state/ driver-managed state

Targets MUST NOT write outside <root> unless documented in a target annex.

6. Input resolution

Resolution precedence:

  1. CLI flags
  2. Environment variables
  3. Config file
  4. Target defaults

Secrets MUST NOT be stored in config files.

7. Config template rule

If the resolved config path is missing:

  • a template MUST be created with placeholders and safe defaults
  • the command MUST exit with code 10
  • stdout MUST include remediation instructions

Existing configs MUST NOT be overwritten unless --force is provided.

8. Vault rules

  • When vault access is required by the target annex, exactly one password source MUST be provided:
  • --vault-password-file, or
  • --vault-password-command
  • If both password sources are given, --vault-password-file MUST take precedence.
  • Secrets MUST NOT appear in stdout, stderr, or evidence.
  • If vault persistence is required by the target annex and fails, init MUST fail.

9. Readiness marker

Path:

<root>/meta/<target>.ready.json

Minimum schema:

{
  "target": "<target>",
  "status": "ready",
  "run_id": "<run-id>",
  "paths": {
    "config": "...",
    "credentials": "...",
    "vault": "...",
    "evidence": "..."
  }
}

The readiness marker MUST NOT contain secrets.

10. Evidence rules

Evidence path:

<root>/logs/init/<target>/<run_id>/

Minimum evidence set:

  • meta.json containing non-secret run metadata and resolved non-secret paths
  • subprocess result records (where subprocesses are used) containing at minimum:
  • argv, rc, duration_ms
  • redacted stdout/stderr captures where applicable

Redaction rules:

  • secret values MUST be removed from evidence artefacts
  • token-like patterns SHOULD be masked
  • the redaction pattern set MAY evolve without a version bump

11. Exit codes

Stable exit codes:

  • 0 success
  • 2 operator error
  • 10 config template created
  • 20 target execution/bootstrap failure
  • 21 vault decrypt or persistence failure
  • 30 write failure

12. Stdout contract

On success, stdout MUST include:

target=<target> status=ready run_id=<run_id>
evidence: <path>
readiness: <path>
credentials: <path>  # if generated

Stdout MUST NOT contain secrets.

13. Supported targets

Target annexes:

14. Security considerations

  • Credential and vault files MUST be mode 0600.
  • Evidence MUST exclude secrets.
  • Vault operations MUST NOT print sensitive values.

15. Change control

Breaking changes include modifications to:

  • runtime layout semantics
  • input precedence
  • vault rules
  • exit codes
  • readiness marker schema
  • evidence minimum set

16. Sequence overview

Mermaid sequence diagram 
sequenceDiagram
    autonumber
    actor Operator
    participant Hyops as hyops init
    participant Config as Config File
    participant Vault as Vault (ansible-vault)
    participant Evidence as Evidence Folder
    participant Marker as Readiness Marker

    Operator->>Hyops: hyops init <target> [flags]
    Hyops->>Hyops: resolve inputs

    Hyops->>Config: check config file
    alt missing
        Config-->>Hyops: not found
        Hyops->>Config: write template
        Hyops->>Operator: exit 10
    else existing
        Config-->>Hyops: load
    end

    Hyops->>Vault: decrypt if required
    alt vault failure
        Hyops->>Operator: exit 21
    end

    Hyops->>Hyops: collect secrets
    Hyops->>Vault: persist secrets (if required)

    Hyops->>Evidence: write evidence (redacted)
    Hyops->>Marker: write readiness marker

    Hyops->>Operator: exit 0