# Vault reference contracts — typed pointers to secretumvault entries.
# Subsystems that need keys, credentials or signing material reference them
# by path inside vault rather than embedding the secret.

let _VaultPath = std.contract.from_validator (fun value =>
  if !(std.is_string value)
  then 'Error { message = "VaultPath must be a String" }
  else if std.string.length value == 0
  then 'Error { message = "VaultPath must be non-empty" }
  else if std.string.contains " " value
  then 'Error { message = "VaultPath must not contain whitespace" }
  else if !(std.string.contains "/" value)
  then 'Error { message = "VaultPath must contain '/'" }
  else 'Ok
) in

{
  # Path inside secretumvault. Validated as non-empty, no whitespace, contains '/'.
  VaultPath = _VaultPath,

  # Reference to a symmetric/asymmetric key stored in vault for encryption use.
  VaultKeyRef = {
    path       | String | doc "Vault path to the key entry (e.g. 'backup-manager/master-encryption-key')",
    algorithm  | [| 'aes_gcm_256, 'chacha20_poly1305, 'age_x25519, 'rsa_4096, 'ecdsa_p256, 'pq_kyber768 |] | default = 'age_x25519,
    derivation | {
      method | [| 'none, 'hkdf_sha256 |] | default = 'none,
      info   | String | doc "HKDF info parameter when derivation is hkdf_sha256" | default = "",
    } | default = { method = 'none, info = "" },
  },

  # Reference to credentials (S3 access keys, B2 keys, NKey seeds, etc.) stored in vault.
  VaultCredRef = {
    path | String | doc "Vault path to the credentials entry (e.g. 'backup-manager/destinations/hetzner-primary')",
    kind | [| 's3, 'b2, 'sftp, 'nkey, 'jwt, 'token, 'tls_cert_bundle, 'etcd_client |] | doc "Type of credential payload at the path",
  },

  # Reference to a Cedar policy bundle in vault (for RBAC across actors).
  VaultPolicyRef = {
    path | String | doc "Vault path to the Cedar policy entry",
  },
}