feat(scripts): add gateway/Command registration tooling

Add scripts/register/ — idempotent bash stages that provision the CERTInext
plugin into the AnyCA REST Gateway and Keyfactor Command, driven by
integration-manifest.json product_ids:

  01 gateway certificate profiles      (verified live)
  02 gateway CA configuration          (unverified)
  03 gateway claims                    (unverified)
  04 Command CA registration           (unverified; CA config — opt-in)
  05 Command template import           (unverified)
  06 enrollment patterns + template KeyRetention (verified live)
  00 orchestrator (runs 01-06, SKIP_NN=1 / DRY_RUN=1)

scripts/lib/command-auth.sh provides shared auth supporting three modes per
side (session cookie, bearer token, OAuth2 client_credentials). Session
cookies auto-route Command calls to /KeyfactorProxy (the Portal reverse proxy
that injects the bearer); /KeyfactorAPI rejects cookies. GATEWAY_BASE_PATH is
the gateway instance mount path (e.g. /certinext-0).

Stage 06 encodes the verified EnrollmentPatterns schema: Template as integer,
AllowedEnrollmentTypes (plural), required Policies:{}, TemplateDefault, role
NAME strings, update via PUT /{id}; template retention via partial PUT.

Includes scripts/register/README.md (auth, env contract, gotchas, schema) and
Makefile targets (register, register-profiles, ...). bash 3.2 / zsh safe.

Author: spbsoluble

Makefile

@@ -24,6 +24,8 @@ REPORT_DIR   := /tmp/certinext-coverage-report
         revoke-order \
         submit-csr \
         list-cas \
+        register register-profiles register-ca-config register-claims \
+        register-command-ca register-import register-enrollment \
         create-product \
         generate-order-igtf \
         generate-order-149-fresh \
@@ -299,6 +301,51 @@ submit-csr:
 list-cas:
 	@scripts/list-cas.sh
 
+# ---------------------------------------------------------------------------
+# register-* — provision profiles/templates into the AnyCA REST Gateway and
+# Keyfactor Command. These talk to Command/gateway (OAuth2 client_credentials),
+# NOT the CERTInext API — see scripts/lib/command-auth.sh for the env contract
+# (TOKEN_URL, OIDC_CLIENT_ID/SECRET, GATEWAY_HOST, COMMAND_HOST, ...).
+#
+#   make register                     # full provisioning (stages 01..06)
+#   make register DRY_RUN=1            # DRY_RUN forwards to every stage
+#   make register SKIP_03=1            # skip a stage by number
+#
+#   Per-stage (each idempotent; add DRY_RUN=1 for an offline preview):
+#     make register-profiles      # 01 gateway certificate profiles  [CHECK=1]
+#     make register-ca-config     # 02 gateway CAConnection + Templates
+#     make register-claims        # 03 gateway access claims (IAM)
+#     make register-command-ca    # 04 register CA in Command
+#     make register-import        # 05 import templates into Command  [CHECK=1]
+#     make register-enrollment    # 06 enrollment patterns + template KeyRetention
+#
+# Stages 01 and 06 are VERIFIED live; 02-05 are built from docs/reference
+# captures — validate against a live gateway/Command before relying on them.
+# Auth (cookie/token/OAuth), env vars, and gotchas: scripts/register/README.md.
+# NOTE: stage 04 (and stage 02's CA-connection PUT) touch the CA config, which
+# is fragile — leave it alone unless explicitly required.
+# ---------------------------------------------------------------------------
+register:
+	@scripts/register/00-register-all.sh
+
+register-profiles:
+	@scripts/register/01-gateway-profiles.sh
+
+register-ca-config:
+	@scripts/register/02-gateway-ca-config.sh
+
+register-claims:
+	@scripts/register/03-gateway-claims.sh
+
+register-command-ca:
+	@scripts/register/04-command-register-ca.sh
+
+register-import:
+	@scripts/register/05-command-import-templates.sh
+
+register-enrollment:
+	@scripts/register/06-command-enrollment-patterns.sh
+
 # ---------------------------------------------------------------------------
 # create-product — Create a custom product via API
 #

scripts/lib/command-auth.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# Shared OAuth2 + REST helpers for Keyfactor Command / AnyCA REST Gateway
+# *provisioning* scripts (scripts/register/*).
+#
+# This is distinct from certinext-auth.sh: that helper signs CERTInext API
+# requests (SHA256 authKey). This one talks to Command and the gateway admin
+# API using an OAuth2 client_credentials bearer token.
+#
+# Usage:
+#   . ~/.env_certinext
+#   . "$(dirname "$0")/lib/command-auth.sh"
+#   tok=$(gateway_token)
+#   gw_curl "$tok" GET /config/certificateprofile
+#
+# Required env (set in ~/.env_certinext or exported before sourcing):
+#   TOKEN_URL            OAuth token endpoint (Authentik), e.g.
+#                        https://auth.127.0.0.1.nip.io/application/o/token/
+#   OIDC_CLIENT_ID       client_credentials client id
+#   OIDC_CLIENT_SECRET   client_credentials client secret
+#   GATEWAY_HOST         gateway ingress host (no scheme)
+#   COMMAND_HOST         Command ingress host (no scheme)
+# Optional env (defaults shown):
+#   GATEWAY_SCHEME       https
+#   GATEWAY_BASE_PATH    /AnyGatewayREST   (gateway admin API prefix)
+#   GATEWAY_SCOPE        keyfactor-anyca-gateway
+#   COMMAND_SCHEME       https
+#   CURL_INSECURE        1  (pass -k; set 0 to verify TLS)
+#   CONFIGURATION_TENANT certinext-caplugin
+
+GATEWAY_SCHEME="${GATEWAY_SCHEME:-https}"
+# GATEWAY_BASE_PATH is the gateway *instance* mount path, NOT a fixed value.
+# On a multi-tenant AnyCA REST Gateway each instance lives under its own path
+# (e.g. /certinext-0). Discover it from the Portal/Swagger URL. The historical
+# default /AnyGatewayREST only applies to single-instance gateways.
+GATEWAY_BASE_PATH="${GATEWAY_BASE_PATH:-/AnyGatewayREST}"
+GATEWAY_SCOPE="${GATEWAY_SCOPE:-keyfactor-anyca-gateway}"
+COMMAND_SCHEME="${COMMAND_SCHEME:-https}"
+# Command API base path. A Portal *session cookie* (COMMAND_COOKIE) only works
+# against /KeyfactorProxy — the Portal's reverse proxy that injects the bearer
+# token server-side. Direct bearer/OAuth auth uses /KeyfactorAPI. When unset,
+# cmd_base() resolves it at call time from whether a cookie is set (so it works
+# regardless of env-var ordering). Set COMMAND_BASE_PATH to force either path.
+COMMAND_BASE_PATH="${COMMAND_BASE_PATH:-}"
+CONFIGURATION_TENANT="${CONFIGURATION_TENANT:-certinext-caplugin}"
+CURL_INSECURE="${CURL_INSECURE:-1}"
+
+_ca_require() {
+    local missing=0 v
+    for v in "$@"; do
+        if [ -z "${!v:-}" ]; then
+            echo "ERROR: required env var '$v' is not set" >&2
+            missing=1
+        fi
+    done
+    [ "$missing" -eq 0 ] || return 1
+}
+
+# Base curl flags shared by every call (bash 3.2 compatible — global array).
+CA_CURL_OPTS=(-sS)
+[ "$CURL_INSECURE" = "1" ] && CA_CURL_OPTS+=(-k)
+
+# oauth_token [scope] — fetch a client_credentials bearer token.
+# Echoes the raw access_token. Exits non-zero (and prints the body) on failure.
+oauth_token() {
+    _ca_require TOKEN_URL OIDC_CLIENT_ID OIDC_CLIENT_SECRET || return 1
+    local scope="${1:-}"
+    local -a form=(
+        --data-urlencode "grant_type=client_credentials"
+        --data-urlencode "client_id=${OIDC_CLIENT_ID}"
+        --data-urlencode "client_secret=${OIDC_CLIENT_SECRET}"
+    )
+    [ -n "$scope" ] && form+=(--data-urlencode "scope=${scope}")
+
+    local resp tok
+    resp=$(curl "${CA_CURL_OPTS[@]}" -X POST "$TOKEN_URL" \
+        -H "Content-Type: application/x-www-form-urlencoded" \
+        "${form[@]}") || { echo "ERROR: token request failed" >&2; return 1; }
+    tok=$(printf '%s' "$resp" | jq -r '.access_token // empty')
+    if [ -z "$tok" ]; then
+        echo "ERROR: no access_token in response:" >&2
+        printf '%s\n' "$resp" >&2
+        return 1
+    fi
+    printf '%s' "$tok"
+}
+
+# Auth resolution order (per side):
+#   1. A browser-session cookie (GATEWAY_COOKIE / COMMAND_COOKIE) — paste the
+#      full `cookie:` header value from devtools (Copy as cURL) when the UI uses
+#      OIDC session cookies instead of bearer tokens. The *_token fns return
+#      empty in this mode; gw_curl/cmd_curl send the Cookie header instead.
+#   2. An explicit pre-obtained bearer token (GATEWAY_TOKEN / COMMAND_TOKEN).
+#   3. OAuth2 client_credentials via oauth_token (needs OIDC_CLIENT_* + TOKEN_URL).
+gateway_token() {
+    if [ -n "${GATEWAY_COOKIE:-}" ]; then return 0; fi   # cookie mode
+    if [ -n "${GATEWAY_TOKEN:-}" ]; then printf '%s' "$GATEWAY_TOKEN"; return 0; fi
+    oauth_token "$GATEWAY_SCOPE"
+}
+command_token() {
+    if [ -n "${COMMAND_COOKIE:-}" ]; then return 0; fi   # cookie mode
+    if [ -n "${COMMAND_TOKEN:-}" ]; then printf '%s' "$COMMAND_TOKEN"; return 0; fi
+    oauth_token ""
+}
+
+gw_base() {
+    _ca_require GATEWAY_HOST || return 1
+    printf '%s://%s%s' "$GATEWAY_SCHEME" "$GATEWAY_HOST" "$GATEWAY_BASE_PATH"
+}
+cmd_base() {
+    _ca_require COMMAND_HOST || return 1
+    local bp="$COMMAND_BASE_PATH"
+    if [ -z "$bp" ]; then
+        if [ -n "${COMMAND_COOKIE:-}" ]; then bp="/KeyfactorProxy"; else bp="/KeyfactorAPI"; fi
+    fi
+    printf '%s://%s%s' "$COMMAND_SCHEME" "$COMMAND_HOST" "$bp"
+}
+
+# Display helpers for log headers: the base URL, or a clear "(unset)" note.
+gw_show()  { if [ -n "${GATEWAY_HOST:-}" ]; then gw_base; else printf '(GATEWAY_HOST unset)'; fi; }
+cmd_show() { if [ -n "${COMMAND_HOST:-}" ]; then cmd_base; else printf '(COMMAND_HOST unset)'; fi; }
+
+# gw_curl <token> <method> <path> [data] [extra curl args...]
+# Hits the gateway admin API. <path> is relative to GATEWAY_BASE_PATH
+# (e.g. /config/certificateprofile). Echoes the response body.
+gw_curl() {
+    local tok="$1" method="$2" path="$3" data="${4:-}"; shift; shift; shift
+    [ $# -gt 0 ] && shift || true
+    # In cookie mode, mimic the browser exactly (XMLHttpRequest + CSRF header).
+    local rw="APIClient"
+    [ -n "${GATEWAY_COOKIE:-}" ] && rw="XMLHttpRequest"
+    local -a args=("${CA_CURL_OPTS[@]}" -X "$method" "$(gw_base)$path"
+        -H "x-keyfactor-requested-with: $rw"
+        -H "Content-Type: application/json")
+    if [ -n "${GATEWAY_COOKIE:-}" ]; then
+        args+=(-H "Cookie: ${GATEWAY_COOKIE}" -H "x-requested-with: XMLHttpRequest")
+    fi
+    [ -n "$tok" ] && args+=(-H "Authorization: Bearer $tok")
+    [ -n "$data" ] && args+=(-d "$data")
+    args+=("$@")
+    curl "${args[@]}"
+}
+
+# cmd_curl <token> <method> <path> [data] [api-version] [extra curl args...]
+# Hits the Command KeyfactorAPI. <path> is relative to /KeyfactorAPI.
+cmd_curl() {
+    local tok="$1" method="$2" path="$3" data="${4:-}" ver="${5:-1}"
+    shift; shift; shift
+    [ $# -gt 0 ] && shift || true
+    [ $# -gt 0 ] && shift || true
+    local rw="APIClient"
+    [ -n "${COMMAND_COOKIE:-}" ] && rw="XMLHttpRequest"
+    local -a args=("${CA_CURL_OPTS[@]}" -X "$method" "$(cmd_base)$path"
+        -H "x-keyfactor-api-version: $ver"
+        -H "x-keyfactor-requested-with: $rw"
+        -H "Content-Type: application/json")
+    if [ -n "${COMMAND_COOKIE:-}" ]; then
+        args+=(-H "Cookie: ${COMMAND_COOKIE}" -H "x-requested-with: XMLHttpRequest")
+    fi
+    [ -n "$tok" ] && args+=(-H "Authorization: Bearer $tok")
+    [ -n "$data" ] && args+=(-d "$data")
+    args+=("$@")
+    curl "${args[@]}"
+}
+
+# manifest_product_ids [manifest-path] — emit product_ids one per line.
+manifest_product_ids() {
+    local manifest="${1:-$REPO_ROOT/integration-manifest.json}"
+    jq -r '.about.carest.product_ids[]' "$manifest"
+}

scripts/register/00-register-all.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Orchestrator — run the full gateway + Command registration in order.
+#
+# Each stage is an independent script and can be run on its own. This driver
+# runs them in sequence, skipping any stage whose script does not yet exist
+# (stages 02-06 are added incrementally) or whose SKIP_<NN> flag is set to 1.
+#
+#   make register
+#   SKIP_03=1 make register      # skip claims
+#   DRY_RUN=1 make register      # forwarded to every stage
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# stage number -> script basename
+STAGES=(
+    "01:01-gateway-profiles.sh"
+    "02:02-gateway-ca-config.sh"
+    "03:03-gateway-claims.sh"
+    "04:04-command-register-ca.sh"
+    "05:05-command-import-templates.sh"
+    "06:06-command-enrollment-patterns.sh"
+)
+
+for entry in "${STAGES[@]}"; do
+    num="${entry%%:*}"
+    script="${entry#*:}"
+    skip_var="SKIP_${num}"
+    path="$SCRIPT_DIR/$script"
+
+    if [ "${!skip_var:-0}" = "1" ]; then
+        echo ">> stage $num ($script): SKIPPED (${skip_var}=1)"
+        continue
+    fi
+    if [ ! -x "$path" ]; then
+        echo ">> stage $num ($script): not yet implemented — skipping"
+        continue
+    fi
+
+    echo ">> stage $num ($script): running"
+    "$path"
+    echo
+done
+
+echo ">> registration complete"

scripts/register/01-gateway-profiles.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Stage 01 — register AnyCA REST Gateway certificate profiles.
+#
+# Creates (or updates) one gateway certificate profile per CERTInext product,
+# driven by .about.carest.product_ids in integration-manifest.json. Idempotent:
+# existing profiles are PUT-updated, new ones are POSTed.
+#
+# Env: see scripts/lib/command-auth.sh for the OAuth/host contract.
+# Optional:
+#   KEY_ALGS_JSON   override the key_algs object (default: lab set below)
+#   MANIFEST        path to integration-manifest.json (default: repo root)
+#   CHECK           1 = after applying, diff result vs the captured reference
+#                       (docs/reference/gateway/certificate-profiles.json)
+#   DRY_RUN         1 = print intended actions, make no write calls
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+export REPO_ROOT
+
+# shellcheck disable=SC1090
+[ -f ~/.env_certinext ] && . ~/.env_certinext
+# shellcheck source=../lib/command-auth.sh
+. "$SCRIPT_DIR/../lib/command-auth.sh"
+
+MANIFEST="${MANIFEST:-$REPO_ROOT/integration-manifest.json}"
+DRY_RUN="${DRY_RUN:-0}"
+CHECK="${CHECK:-0}"
+
+# Lab default key algorithms — matches docs/reference/gateway/certificate-profiles.json.
+DEFAULT_KEY_ALGS_JSON='{
+  "rsa":     { "bit_lengths": [2048, 3072, 4096, 6144, 8192] },
+  "ecdsa":   { "curves": ["1.2.840.10045.3.1.7", "1.3.132.0.34", "1.3.132.0.35"] },
+  "ed25519": { "bit_lengths": [255] },
+  "ed448":   { "bit_lengths": [448] }
+}'
+KEY_ALGS_JSON="${KEY_ALGS_JSON:-$DEFAULT_KEY_ALGS_JSON}"
+
+if ! echo "$KEY_ALGS_JSON" | jq -e . >/dev/null 2>&1; then
+    echo "ERROR: KEY_ALGS_JSON is not valid JSON" >&2
+    exit 1
+fi
+
+echo "== Stage 01: gateway certificate profiles =="
+echo "   gateway : $(gw_show)"
+echo "   manifest: $MANIFEST"
+[ "$DRY_RUN" = "1" ] && echo "   DRY_RUN : no write calls will be made"
+
+PRODUCTS=()
+while IFS= read -r _p; do
+    [ -n "$_p" ] && PRODUCTS+=("$_p")
+done < <(manifest_product_ids "$MANIFEST")
+[ "${#PRODUCTS[@]}" -gt 0 ] || { echo "ERROR: no product_ids in manifest" >&2; exit 1; }
+echo "   products: ${#PRODUCTS[@]}"
+
+if [ "$DRY_RUN" = "1" ]; then
+    # Fully offline preview: no token, no listing.
+    echo "   (dry run) would upsert ${#PRODUCTS[@]} profiles with key_algs:"
+    echo "$KEY_ALGS_JSON" | jq -c .
+    for name in "${PRODUCTS[@]}"; do
+        printf '   [DRY ] %s\n' "$name"
+    done
+    echo "== done (dry run): no calls made =="
+    exit 0
+fi
+
+TOK="$(gateway_token)"
+
+# Snapshot existing profiles once: name -> id.
+EXISTING="$(gw_curl "$TOK" GET /config/certificateprofile)"
+if ! echo "$EXISTING" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    echo "ERROR: unexpected response listing certificate profiles:" >&2
+    printf '%s\n' "$EXISTING" >&2
+    exit 1
+fi
+
+created=0 updated=0
+for name in "${PRODUCTS[@]}"; do
+    existing_id="$(echo "$EXISTING" | jq -r --arg n "$name" \
+        '.[] | select(.name == $n) | .id' | head -n1)"
+
+    body="$(jq -n --arg name "$name" --argjson algs "$KEY_ALGS_JSON" \
+        '{name: $name, key_algs: $algs}')"
+
+    if [ -n "$existing_id" ] && [ "$existing_id" != "null" ]; then
+        body="$(echo "$body" | jq --argjson id "$existing_id" '. + {id: $id}')"
+        printf '   [PUT ] %-40s (id=%s)\n' "$name" "$existing_id"
+        if [ "$DRY_RUN" != "1" ]; then
+            resp="$(gw_curl "$TOK" PUT /config/certificateprofile "$body")"
+            echo "$resp" | jq -e 'has("error") or has("Message")' >/dev/null 2>&1 \
+                && { echo "       ! update failed: $resp" >&2; }
+        fi
+        updated=$((updated + 1))
+    else
+        printf '   [POST] %-40s (new)\n' "$name"
+        if [ "$DRY_RUN" != "1" ]; then
+            resp="$(gw_curl "$TOK" POST /config/certificateprofile "$body")"
+            echo "$resp" | jq -e 'has("error") or has("Message")' >/dev/null 2>&1 \
+                && { echo "       ! create failed: $resp" >&2; }
+        fi
+        created=$((created + 1))
+    fi
+done
+
+echo "== done: $created created, $updated updated =="
+
+if [ "$CHECK" = "1" ] && [ "$DRY_RUN" != "1" ]; then
+    ref="$REPO_ROOT/docs/reference/gateway/certificate-profiles.json"
+    echo "== CHECK: comparing live profile names vs $ref =="
+    live_names="$(gw_curl "$TOK" GET /config/certificateprofile | jq -r '[.[].name] | sort')"
+    # Reference only captured DV/OV (no EV); compare on the set the reference covers.
+    ref_names="$(jq -r '[.[].name] | sort' "$ref")"
+    missing="$(jq -n --argjson live "$live_names" --argjson ref "$ref_names" \
+        '$ref - $live')"
+    if [ "$(echo "$missing" | jq 'length')" -eq 0 ]; then
+        echo "   OK: all reference profiles present on the gateway"
+    else
+        echo "   MISSING reference profiles: $missing" >&2
+        exit 1
+    fi
+fi