@intentius/terragucci 0.4.34 → 0.4.36

package/dist/terragucci.schema.json

@@ -93,6 +93,47 @@
       ],
       "description": "What counts as a waiting wave's approval: the mode, or a map with the mode and require_signed."
     },
+    "approval_rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "roots": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^[^\\s,;=']+$"
+            },
+            "description": "Root globs: a wave with a root one matches takes the rule."
+          },
+          "count": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "How many distinct people approve the wave's set digest. Default 1."
+          },
+          "roles": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$"
+            },
+            "description": "Each approver counted holds one of these roles in .chant/trust.json at base."
+          },
+          "not_author": {
+            "type": "boolean",
+            "description": "At least one approver counted is not the change's author."
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "roots"
+        ]
+      },
+      "description": "More approvers, or approvers with a role, for the waves whose roots a glob names."
+    },
     "apply": {
       "type": "object",
       "properties": {
@@ -1034,8 +1075,69 @@
           "type": "array",
           "minItems": 1,
           "items": {
-            "type": "string",
-            "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "roots": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "pattern": "^[^\\s,;=']+$"
+                    },
+                    "description": "Root globs: the entry covers a denial of a root one matches."
+                  },
+                  "who": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+                    },
+                    "description": "The forge identities or signers who may override such a denial."
+                  },
+                  "roles": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "pattern": "^[a-z][a-z0-9-]*$"
+                    },
+                    "description": "Roles in .chant/trust.json at base whose holders may override such a denial (approval: sealed)."
+                  },
+                  "rules": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "pattern": "^\\S+$"
+                    },
+                    "description": "Only an override of these rule ids, every one of them."
+                  }
+                },
+                "additionalProperties": false,
+                "required": [
+                  "roots"
+                ]
+              }
+            ]
+          }
+        },
+        "outcomes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "deny",
+              "hold",
+              "allow_unattended"
+            ]
           }
         }
       },
@@ -1348,6 +1450,11 @@
       "pattern": "^[a-z]{2}(-[a-z]+)+-\\d+$",
       "description": "The AWS region whose CloudTrail drift attribution reads."
     },
+    "audit_log_group": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9._\\-/#]{1,512}$",
+      "description": "The CloudWatch Logs group a CloudTrail trail delivers the state buckets' S3 data events to; terragucci audit reads it to name who wrote a state version no wave or migration recorded."
+    },
     "dashboards": {
       "anyOf": [
         {
@@ -1442,6 +1549,49 @@
       ],
       "description": "Roots each pull request gets a copy of."
     },
+    "secrets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "roots": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "\\S"
+            }
+          },
+          "from": {
+            "enum": [
+              "aws",
+              "gcp",
+              "azure"
+            ]
+          },
+          "values": {
+            "type": "object",
+            "minProperties": 1,
+            "propertyNames": {
+              "type": "string",
+              "pattern": "^(?!(?:[Gg][Ii][Tt][Hh][Uu][Bb]_|[Gg][Ii][Tt][Ee][Aa]_|[Ff][Oo][Rr][Gg][Ee][Jj][Oo]_|[Tt][Gg]_|[Tt][Ee][Rr][Rr][Aa][Gg][Uu][Cc][Cc][Ii]_|[Aa][Ww][Ss]_|[Aa][Rr][Mm]_|[Aa][Zz][Uu][Rr][Ee]_|[Gg][Oo][Oo][Gg][Ll][Ee]_|[Cc][Ll][Oo][Uu][Dd][Ss][Dd][Kk]_))(?!(?:TF_IN_AUTOMATION|TF_INPUT)$)[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "additionalProperties": {
+              "type": "string",
+              "pattern": "^[^\\s]+$"
+            }
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "roots",
+          "from",
+          "values"
+        ]
+      },
+      "description": "Values a root's binary gets from a cloud's secret store, fetched at job time with the root's own identity."
+    },
     "environments": {
       "type": "object",
       "minProperties": 1,
@@ -1776,6 +1926,47 @@
           ],
           "description": "What counts as a waiting wave's approval: the mode, or a map with the mode and require_signed."
         },
+        "approval_rules": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "roots": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "pattern": "^[^\\s,;=']+$"
+                },
+                "description": "Root globs: a wave with a root one matches takes the rule."
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "How many distinct people approve the wave's set digest. Default 1."
+              },
+              "roles": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9-]*$"
+                },
+                "description": "Each approver counted holds one of these roles in .chant/trust.json at base."
+              },
+              "not_author": {
+                "type": "boolean",
+                "description": "At least one approver counted is not the change's author."
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "roots"
+            ]
+          },
+          "description": "More approvers, or approvers with a role, for the waves whose roots a glob names."
+        },
         "apply": {
           "type": "object",
           "properties": {
@@ -2709,8 +2900,69 @@
               "type": "array",
               "minItems": 1,
               "items": {
-                "type": "string",
-                "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "roots": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "pattern": "^[^\\s,;=']+$"
+                        },
+                        "description": "Root globs: the entry covers a denial of a root one matches."
+                      },
+                      "who": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+                        },
+                        "description": "The forge identities or signers who may override such a denial."
+                      },
+                      "roles": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "pattern": "^[a-z][a-z0-9-]*$"
+                        },
+                        "description": "Roles in .chant/trust.json at base whose holders may override such a denial (approval: sealed)."
+                      },
+                      "rules": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "pattern": "^\\S+$"
+                        },
+                        "description": "Only an override of these rule ids, every one of them."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "required": [
+                      "roots"
+                    ]
+                  }
+                ]
+              }
+            },
+            "outcomes": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "enum": [
+                  "deny",
+                  "hold",
+                  "allow_unattended"
+                ]
               }
             }
           },
@@ -3023,6 +3275,11 @@
           "pattern": "^[a-z]{2}(-[a-z]+)+-\\d+$",
           "description": "The AWS region whose CloudTrail drift attribution reads."
         },
+        "audit_log_group": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._\\-/#]{1,512}$",
+          "description": "The CloudWatch Logs group a CloudTrail trail delivers the state buckets' S3 data events to; terragucci audit reads it to name who wrote a state version no wave or migration recorded."
+        },
         "dashboards": {
           "anyOf": [
             {
@@ -3117,6 +3374,49 @@
           ],
           "description": "Roots each pull request gets a copy of."
         },
+        "secrets": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "roots": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "pattern": "\\S"
+                }
+              },
+              "from": {
+                "enum": [
+                  "aws",
+                  "gcp",
+                  "azure"
+                ]
+              },
+              "values": {
+                "type": "object",
+                "minProperties": 1,
+                "propertyNames": {
+                  "type": "string",
+                  "pattern": "^(?!(?:[Gg][Ii][Tt][Hh][Uu][Bb]_|[Gg][Ii][Tt][Ee][Aa]_|[Ff][Oo][Rr][Gg][Ee][Jj][Oo]_|[Tt][Gg]_|[Tt][Ee][Rr][Rr][Aa][Gg][Uu][Cc][Cc][Ii]_|[Aa][Ww][Ss]_|[Aa][Rr][Mm]_|[Aa][Zz][Uu][Rr][Ee]_|[Gg][Oo][Oo][Gg][Ll][Ee]_|[Cc][Ll][Oo][Uu][Dd][Ss][Dd][Kk]_))(?!(?:TF_IN_AUTOMATION|TF_INPUT)$)[A-Za-z_][A-Za-z0-9_]*$"
+                },
+                "additionalProperties": {
+                  "type": "string",
+                  "pattern": "^[^\\s]+$"
+                }
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "roots",
+              "from",
+              "values"
+            ]
+          },
+          "description": "Values a root's binary gets from a cloud's secret store, fetched at job time with the root's own identity."
+        },
         "environments": {
           "type": "object",
           "minProperties": 1,

package/dist/types.d.ts

@@ -36,12 +36,49 @@ export interface ApprovalSettings {
 export declare function approvalModeOf(v: Approval | ApprovalSettings | undefined): Approval | undefined;
 /** Whether an `approval:` value refuses unsigned ledger approvals. */
 export declare function requireSignedOf(v: Approval | ApprovalSettings | undefined): boolean;
+/** The keys of a scoped `policy.override` entry. */
+export declare const OVERRIDE_ENTRY_KEYS: readonly ["roots", "who", "roles", "rules"];
+/**
+ * A scoped `policy.override` entry (./override.ts): `who` (forge identities
+ * or signers) and the holders of `roles` in `.chant/trust.json` at base may
+ * override a denial of a root a glob of `roots` matches, for any rule, or
+ * with `rules` only when every rule the override names is one of them.
+ */
+export interface OverrideEntry {
+    roots: string[];
+    who?: string[];
+    roles?: string[];
+    rules?: string[];
+}
+/** The keys of one `approval_rules` entry. */
+export declare const APPROVAL_RULE_KEYS: readonly ["roots", "count", "roles", "not_author"];
+/**
+ * One `approval_rules` entry (./approval-rules.ts): a wave with a root a glob
+ * of `roots` matches waits for `count` distinct approvers of its set digest
+ * (default 1), each holding one of `roles` in `.chant/trust.json` at base when
+ * `roles` is set, and with `not_author` at least one who is not the change's
+ * author. Read at base, like `approval:`.
+ */
+export interface ApprovalRuleSettings {
+    roots: string[];
+    count?: number;
+    roles?: string[];
+    not_author?: boolean;
+}
 /** Every stage runs on the forge's CI. */
 export declare const RUNTIMES: readonly ["forge"];
 export declare const DEPENDENTS: readonly ["follow", "plan"];
 /** What a pull request does with the dependents of a changed unit when terragrunt.dependents is unset. */
 export declare const DEFAULT_DEPENDENTS: Dependents;
 export declare const POLICY_ENGINES: readonly ["conftest", "opa"];
+/**
+ * What a policy rule can do to a root's wave (./report/policy.ts): `deny`
+ * fails the root, `hold` makes its wave wait for an approval whatever `gate`
+ * says, `allow_unattended` lets a wave whose every changing root it allows
+ * apply without one.
+ */
+export declare const POLICY_OUTCOMES: readonly ["deny", "hold", "allow_unattended"];
+export type PolicyOutcome = (typeof POLICY_OUTCOMES)[number];
 export declare const POLICY_INPUTS: readonly ["plan", "hcp"];
 /**
  * When a pull request takes its root locks (`locks:`). `apply` (the default):
@@ -177,10 +214,19 @@ export interface PolicySettings {
     input?: PolicyInput;
     /**
      * Who may override a denial: the forge identities or signers whose recorded
-     * override (`terragucci override`) lets `tf-apply` apply one denied plan.
-     * Read at base, like `approval:`. Unset, no override counts.
+     * override (`terragucci override`) lets `tf-apply` apply one denied plan,
+     * each for every root and rule, or scoped entries (OverrideEntry) for the
+     * roots a glob names. Read at base, like `approval:`. Unset, no override
+     * counts.
+     */
+    override?: (string | OverrideEntry)[];
+    /**
+     * The rule outcomes the policy has: `deny` always, and `hold` and
+     * `allow_unattended` when listed, read from `hold`, `hold_*`,
+     * `allow_unattended` and `allow_unattended_*` rules (engine `opa`). Read
+     * at base. Default `[deny]`.
      */
-    override?: string[];
+    outcomes?: PolicyOutcome[];
 }
 /**
  * The jobs' cloud identities over the forge's OIDC token. `plan_role` and
@@ -394,6 +440,8 @@ export interface ProjectSettings {
     gate?: GateName;
     /** What counts as a waiting wave's approval; see APPROVALS, or a map with the mode and `require_signed` (ApprovalSettings). Read from the config at base, never the applied commit's own. */
     approval?: Approval | ApprovalSettings;
+    /** More approvers, or approvers with a role, for the waves whose roots a glob names; see ApprovalRuleSettings. Read from the config at base. */
+    approval_rules?: ApprovalRuleSettings[];
     /** When a change applies; see ApplySettings. */
     apply?: ApplySettings;
     /** When a pull request takes its root locks; see LOCKS. */
@@ -507,6 +555,13 @@ export interface ProjectSettings {
      * every job its CI/CD variables already, so there the key changes nothing.
      */
     pass?: PassSettings;
+    /**
+     * Values fetched at job time from a cloud's secret store, by root glob,
+     * with the identity the root plans or applies with (./root-secrets.ts), and
+     * set in that root's binary environment alone. Read from the project's
+     * terragucci.yml by the stage.
+     */
+    secrets?: SecretSource[];
     /**
      * The secret holding `OTEL_EXPORTER_OTLP_HEADERS`, such as a collector's API
      * key, and `trace_url`: a link to a run's trace with `{trace_id}` in it
@@ -560,6 +615,13 @@ export interface ProjectSettings {
     decide?: DecideSettings;
     /** The AWS region whose CloudTrail drift attribution reads. Default: the region the aws CLI already uses. */
     audit_region?: string;
+    /**
+     * The CloudWatch Logs group a CloudTrail trail delivers the state buckets'
+     * S3 data events to, in `audit_region`: `terragucci audit` reads it to name
+     * who wrote a state version no wave or migration recorded. Read by the
+     * audit job where it runs; no project's jobs read it.
+     */
+    audit_log_group?: string;
     /** Dashboards and alert rules written next to the pipeline. Off unless set. */
     dashboards?: boolean | DashboardSettings;
     /**
@@ -666,6 +728,43 @@ export interface PassSettings {
     secrets?: string[];
     vars?: string[];
 }
+/** The clouds whose secret store `secrets` reads. */
+export declare const SECRET_STORES: readonly ["aws", "gcp", "azure"];
+export type SecretStore = (typeof SECRET_STORES)[number];
+/** The keys of one `secrets` entry. */
+export declare const SECRET_SOURCE_KEYS: string[];
+/**
+ * One `secrets` entry: the roots its globs match get each of `values`, an
+ * environment variable name mapped to where the value is in `from`'s secret
+ * store, with `#<key>` to take one key of a JSON secret:
+ *
+ *   aws    a Secrets Manager secret's name or ARN: `prod/app/db#password`
+ *   gcp    a Secret Manager secret, its version `latest` unless named:
+ *          `projects/<project>/secrets/<secret>[/versions/<version>]`
+ *   azure  a Key Vault secret, its current version unless named:
+ *          `<vault>/<secret>[/<version>]`, the vault a name or a host
+ */
+export interface SecretSource {
+    roots: string[];
+    from: SecretStore;
+    values: Record<string, string>;
+}
+/** Where a value is in each store, as `secrets` takes it. */
+export declare const SECRET_PATH: Record<SecretStore, string>;
+/** Names `secrets` refuses beside `pass`'s: the variables a root's binary takes its cloud identity from. */
+export declare const SECRET_IDENTITY_PREFIXES: string[];
+/** Why `secrets` is refused beside `waves.compose`: a composed run plans its roots in one binary environment. */
+export declare const SECRETS_COMPOSE = "a composed run plans and applies its roots in one run, and secrets sets each value in its own root's binary environment alone; leave waves.compose unset";
+/** Why `secrets` is refused beside `ephemeral`: a pull request's copies plan and apply without the store's values. */
+export declare const SECRETS_EPHEMERAL = "an ephemeral copy plans and applies without the values secrets fetches; leave ephemeral unset, or keep the copies' values in pass.secrets";
+/**
+ * The problems with `secrets`: a list of entries, each with root globs, a
+ * store and names mapped to paths in it. `whole` when `s` is a repo's own
+ * file: then a name `pass` or `env` sets too, a store whose cloud `oidc`
+ * does not configure, and the keys that plan or apply a root without its
+ * values are refused as well.
+ */
+export declare function secretsProblems(v: unknown, where: string, s: ProjectSettings, whole: boolean): string[];
 /** Whether `runner` is a map of stage to runner, rather than one runner. */
 export declare function runnerByStage(v: RunnerSettings): v is Partial<Record<RunnerStage | "default", RunnerSpec>>;
 export declare const JOB_LABEL: RegExp;
@@ -705,7 +804,7 @@ export declare const BUILT_IN: ResolvedSettings;
  * own clone URL and `rollouts` belongs to a single repo, so `defaults`
  * refuses both.
  */
-export declare const PROJECT_FILE_KEYS: readonly ["policy", "sources", "reports", "approval", "gate", "roots", "waves", "parallelism", "synth", "steps", "drift", "cost", "tips", "runtime", "telemetry", "respond", "review", "decide", "audit_region", "modules", "terragrunt", "token_env", "generate", "ephemeral", "environments"];
+export declare const PROJECT_FILE_KEYS: readonly ["policy", "sources", "reports", "approval", "approval_rules", "gate", "roots", "waves", "parallelism", "synth", "steps", "drift", "cost", "tips", "runtime", "telemetry", "respond", "review", "decide", "audit_region", "modules", "terragrunt", "token_env", "generate", "ephemeral", "environments", "secrets"];
 export declare class ConfigError extends Error {
     /** Every problem found, when the error is a validation failure. */
     readonly problems?: string[];
@@ -865,6 +964,12 @@ export declare const POINT_NAME: RegExp;
 export declare const APPLY_BRANCH: RegExp;
 /** Why `apply.branches` is refused with `apply.when: pull-request`. */
 export declare const BRANCHES_NOT_PR_APPLY = "apply.when: pull-request applies an open pull request into the default branch, and a push applies nothing, so no branch could apply its roots; leave apply.branches unset";
+/** A role name, as `.chant/trust.json` names one under `roles`. */
+export declare const TRUST_ROLE: RegExp;
+/** Why `roles` and `not_author` need a mode that proves who approved. */
+export declare const LEDGER_PROVES_NOBODY = "approval: ledger does not prove who wrote an approval, so it cannot tell a role or the author; set approval to sealed or pr-review";
+/** Why an override's role needs `approval: sealed`. */
+export declare const OVERRIDE_ROLE_NEEDS_SEALED = "an override names whoever wrote it, and only approval: sealed proves who that was, so a role cannot be checked; set approval to sealed, or name the people in who";
 /** Where a shared policy is fetched from: the git URL and the ref. */
 export interface PolicySource {
     url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/terragucci",
-  "version": "0.4.34",
+  "version": "0.4.36",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",