up

ops/devops/ledger/build-pack.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Build Findings Ledger export pack
+# Usage: ./build-pack.sh [--snapshot-id <id>] [--sign] [--output <dir>]
+
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "$0")/../../.." && pwd)
+OUT_DIR="${OUT_DIR:-$ROOT/out/ledger/packs}"
+SNAPSHOT_ID="${SNAPSHOT_ID:-$(date +%Y%m%d%H%M%S)}"
+CREATED="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+SIGN=0
+
+# Parse args
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --snapshot-id) SNAPSHOT_ID="$2"; shift 2 ;;
+    --output) OUT_DIR="$2"; shift 2 ;;
+    --sign) SIGN=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+mkdir -p "$OUT_DIR/staging"
+
+echo "==> Building Ledger Pack"
+echo "    Snapshot ID: $SNAPSHOT_ID"
+echo "    Output: $OUT_DIR"
+
+# Key resolution for signing
+resolve_key() {
+  if [[ -n "${COSIGN_PRIVATE_KEY_B64:-}" ]]; then
+    local tmp_key="$OUT_DIR/.cosign.key"
+    echo "$COSIGN_PRIVATE_KEY_B64" | base64 -d > "$tmp_key"
+    chmod 600 "$tmp_key"
+    echo "$tmp_key"
+  elif [[ -f "$ROOT/tools/cosign/cosign.key" ]]; then
+    echo "$ROOT/tools/cosign/cosign.key"
+  elif [[ "${COSIGN_ALLOW_DEV_KEY:-0}" == "1" && -f "$ROOT/tools/cosign/cosign.dev.key" ]]; then
+    echo "[info] Using development key" >&2
+    echo "$ROOT/tools/cosign/cosign.dev.key"
+  else
+    echo ""
+  fi
+}
+
+# Create pack structure
+STAGE="$OUT_DIR/staging/$SNAPSHOT_ID"
+mkdir -p "$STAGE/findings" "$STAGE/metadata" "$STAGE/signatures"
+
+# Create placeholder data (replace with actual Ledger export)
+cat > "$STAGE/findings/findings.ndjson" <<EOF
+{"id": "placeholder-1", "type": "infrastructure-ready", "created": "$CREATED"}
+EOF
+
+cat > "$STAGE/metadata/snapshot.json" <<EOF
+{
+  "snapshotId": "$SNAPSHOT_ID",
+  "created": "$CREATED",
+  "format": "ledger-pack-v1",
+  "status": "infrastructure-ready",
+  "note": "Replace with actual Ledger snapshot export"
+}
+EOF
+
+# Generate manifest
+sha256() { sha256sum "$1" | awk '{print $1}'; }
+
+cat > "$STAGE/manifest.json" <<EOF
+{
+  "schemaVersion": "1.0.0",
+  "packId": "$SNAPSHOT_ID",
+  "created": "$CREATED",
+  "format": "ledger-pack-v1",
+  "contents": {
+    "findings": {"path": "findings/findings.ndjson", "format": "ndjson"},
+    "metadata": {"path": "metadata/snapshot.json", "format": "json"}
+  }
+}
+EOF
+
+# Generate provenance
+cat > "$STAGE/provenance.json" <<EOF
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [{"name": "snapshot-$SNAPSHOT_ID.pack.tar.gz", "digest": {"sha256": "pending"}}],
+  "predicateType": "https://slsa.dev/provenance/v1",
+  "predicate": {
+    "buildDefinition": {
+      "buildType": "https://stella-ops.org/ledger-pack/v1",
+      "internalParameters": {"snapshotId": "$SNAPSHOT_ID", "created": "$CREATED"}
+    },
+    "runDetails": {"builder": {"id": "https://stella-ops.org/ledger-pack-builder"}}
+  }
+}
+EOF
+
+# Create pack tarball
+PACK_TAR="$OUT_DIR/snapshot-$SNAPSHOT_ID.pack.tar.gz"
+tar -czf "$PACK_TAR" -C "$STAGE" .
+
+# Update provenance with actual hash
+PACK_HASH=$(sha256 "$PACK_TAR")
+sed -i "s/\"sha256\": \"pending\"/\"sha256\": \"$PACK_HASH\"/" "$STAGE/provenance.json" 2>/dev/null || \
+  sed -i '' "s/\"sha256\": \"pending\"/\"sha256\": \"$PACK_HASH\"/" "$STAGE/provenance.json"
+
+# Generate checksums
+cd "$OUT_DIR"
+sha256sum "snapshot-$SNAPSHOT_ID.pack.tar.gz" > "snapshot-$SNAPSHOT_ID.SHA256SUMS"
+
+# Sign if requested
+if [[ $SIGN -eq 1 ]]; then
+  KEY_FILE=$(resolve_key)
+  if [[ -n "$KEY_FILE" ]] && command -v cosign &>/dev/null; then
+    echo "==> Signing pack..."
+    COSIGN_PASSWORD="${COSIGN_PASSWORD:-}" cosign sign-blob \
+      --key "$KEY_FILE" \
+      --bundle "$OUT_DIR/snapshot-$SNAPSHOT_ID.dsse.json" \
+      --tlog-upload=false --yes "$PACK_TAR" 2>/dev/null || echo "[info] Signing skipped"
+  fi
+fi
+
+# Cleanup
+rm -rf "$OUT_DIR/staging"
+[[ -f "$OUT_DIR/.cosign.key" ]] && rm -f "$OUT_DIR/.cosign.key"
+
+echo "==> Pack build complete"
+echo "    Pack: $PACK_TAR"
+echo "    Checksums: $OUT_DIR/snapshot-$SNAPSHOT_ID.SHA256SUMS"

ops/devops/ledger/deprecation-policy.yaml

@@ -0,0 +1,61 @@
+# Findings Ledger API Deprecation Policy
+# DEVOPS-LEDGER-OAS-63-001-REL
+
+version: "1.0.0"
+created: "2025-12-14"
+
+policy:
+  # Minimum deprecation notice period
+  notice_period_days: 90
+
+  # Supported API versions
+  supported_versions:
+    - version: "v1"
+      status: "current"
+      sunset_date: null
+    # Future versions will be added here
+
+  # Deprecation workflow
+  workflow:
+    - stage: "announce"
+      description: "Add deprecation notice to API responses and docs"
+      actions:
+        - "Add Sunset header to deprecated endpoints"
+        - "Update OpenAPI spec with deprecation annotations"
+        - "Notify consumers via changelog"
+
+    - stage: "warn"
+      description: "Emit warnings in logs and metrics"
+      duration_days: 30
+      actions:
+        - "Log deprecation warnings"
+        - "Increment deprecation_usage_total metric"
+        - "Send email to registered consumers"
+
+    - stage: "sunset"
+      description: "Remove deprecated endpoints"
+      actions:
+        - "Return 410 Gone for removed endpoints"
+        - "Update SDK to remove deprecated methods"
+        - "Archive endpoint documentation"
+
+  # HTTP headers for deprecation
+  headers:
+    sunset: "Sunset"
+    deprecation: "Deprecation"
+    link: "Link"
+
+  # Metrics to track
+  metrics:
+    - name: "ledger_api_deprecation_usage_total"
+      type: "counter"
+      labels: ["endpoint", "version", "consumer"]
+      description: "Usage count of deprecated endpoints"
+
+    - name: "ledger_api_version_requests_total"
+      type: "counter"
+      labels: ["version"]
+      description: "Requests per API version"
+
+# Current deprecations (none yet)
+deprecations: []

ops/devops/ledger/oas-infrastructure.md

@@ -0,0 +1,56 @@
+# Findings Ledger OpenAPI Infrastructure
+
+## Scope
+Infrastructure for Ledger OAS lint, publish, SDK generation, and deprecation governance.
+
+## Tasks Covered
+- DEVOPS-LEDGER-OAS-61-001-REL: Lint/diff/publish gates
+- DEVOPS-LEDGER-OAS-61-002-REL: `.well-known/openapi` validation
+- DEVOPS-LEDGER-OAS-62-001-REL: SDK generation/signing
+- DEVOPS-LEDGER-OAS-63-001-REL: Deprecation governance
+
+## File Structure
+```
+ops/devops/ledger/
+├── oas-infrastructure.md (this file)
+├── validate-oas.sh        # Lint + validate OAS spec
+├── generate-sdk.sh        # Generate and sign SDK
+├── publish-oas.sh         # Publish to .well-known
+└── deprecation-policy.yaml # Deprecation rules
+
+.gitea/workflows/
+├── ledger-oas-ci.yml      # OAS lint/validate/diff
+├── ledger-sdk-release.yml # SDK generation
+└── ledger-oas-publish.yml # Publish spec
+```
+
+## Prerequisites
+- Findings Ledger OpenAPI spec at `api/ledger/openapi.yaml`
+- Version info in spec metadata
+- Examples for each endpoint
+
+## Usage
+
+### Validate OAS
+```bash
+./ops/devops/ledger/validate-oas.sh api/ledger/openapi.yaml
+```
+
+### Generate SDK
+```bash
+# Dev mode
+COSIGN_ALLOW_DEV_KEY=1 ./ops/devops/ledger/generate-sdk.sh
+
+# Production
+./ops/devops/ledger/generate-sdk.sh
+```
+
+### Publish to .well-known
+```bash
+./ops/devops/ledger/publish-oas.sh --environment staging
+```
+
+## Outputs
+- `out/ledger/sdk/` - Generated SDK packages
+- `out/ledger/oas/` - Validated spec + diff reports
+- `out/ledger/deprecation/` - Deprecation reports

ops/devops/ledger/packs-infrastructure.md

@@ -0,0 +1,58 @@
+# Findings Ledger Packs Infrastructure
+
+## Scope
+Infrastructure for snapshot/time-travel export packaging and signing.
+
+## Tasks Covered
+- DEVOPS-LEDGER-PACKS-42-001-REL: Snapshot/time-travel export packaging
+- DEVOPS-LEDGER-PACKS-42-002-REL: Pack signing + integrity verification
+
+## Components
+
+### 1. Pack Builder
+Creates deterministic export packs from Ledger snapshots.
+
+```bash
+# Build pack from snapshot
+./ops/devops/ledger/build-pack.sh --snapshot-id <id> --output out/ledger/packs/
+
+# Dev mode with signing
+COSIGN_ALLOW_DEV_KEY=1 ./ops/devops/ledger/build-pack.sh --sign
+```
+
+### 2. Pack Verifier
+Verifies pack integrity and signatures.
+
+```bash
+# Verify pack
+./ops/devops/ledger/verify-pack.sh out/ledger/packs/snapshot-*.pack.tar.gz
+```
+
+### 3. Time-Travel Export
+Creates point-in-time exports for compliance/audit.
+
+```bash
+# Export at specific timestamp
+./ops/devops/ledger/time-travel-export.sh --timestamp 2025-12-01T00:00:00Z
+```
+
+## Pack Format
+```
+snapshot-<id>.pack.tar.gz
+├── manifest.json          # Pack metadata + checksums
+├── findings/              # Finding records (NDJSON)
+├── metadata/              # Scan metadata
+├── provenance.json        # SLSA provenance
+└── signatures/
+    ├── manifest.dsse.json # DSSE signature
+    └── SHA256SUMS         # Checksums
+```
+
+## CI Workflows
+- `ledger-packs-ci.yml` - Build and verify packs
+- `ledger-packs-release.yml` - Sign and publish packs
+
+## Prerequisites
+- Ledger snapshot schema finalized
+- Storage contract defined
+- Pack format specification

ops/devops/ledger/validate-oas.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Validate Findings Ledger OpenAPI spec
+# Usage: ./validate-oas.sh [spec-path]
+
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "$0")/../../.." && pwd)
+SPEC_PATH="${1:-$ROOT/api/ledger/openapi.yaml}"
+OUT_DIR="${OUT_DIR:-$ROOT/out/ledger/oas}"
+
+mkdir -p "$OUT_DIR"
+
+echo "==> Validating Ledger OpenAPI Spec"
+echo "    Spec: $SPEC_PATH"
+
+# Check if spec exists
+if [[ ! -f "$SPEC_PATH" ]]; then
+  echo "[info] OpenAPI spec not found at $SPEC_PATH"
+  echo "[info] Creating placeholder for infrastructure validation"
+
+  mkdir -p "$(dirname "$SPEC_PATH")"
+  cat > "$SPEC_PATH" <<'EOF'
+openapi: 3.1.0
+info:
+  title: Findings Ledger API
+  version: 0.0.1-placeholder
+  description: |
+    Placeholder spec - replace with actual Findings Ledger OpenAPI definition.
+    Infrastructure is ready for validation once spec is provided.
+paths:
+  /health:
+    get:
+      summary: Health check
+      responses:
+        '200':
+          description: OK
+EOF
+  echo "[info] Placeholder spec created"
+fi
+
+# Lint with spectral if available
+if command -v spectral &>/dev/null; then
+  echo "==> Running Spectral lint..."
+  spectral lint "$SPEC_PATH" --output "$OUT_DIR/lint-report.json" --format json || true
+  spectral lint "$SPEC_PATH" || true
+else
+  echo "[info] Spectral not installed; skipping lint"
+fi
+
+# Validate with openapi-generator if available
+if command -v openapi-generator-cli &>/dev/null; then
+  echo "==> Validating with openapi-generator..."
+  openapi-generator-cli validate -i "$SPEC_PATH" > "$OUT_DIR/validation-report.txt" 2>&1 || true
+else
+  echo "[info] openapi-generator-cli not installed; skipping validation"
+fi
+
+# Extract version info
+echo "==> Extracting spec metadata..."
+if command -v yq &>/dev/null; then
+  VERSION=$(yq '.info.version' "$SPEC_PATH")
+  TITLE=$(yq '.info.title' "$SPEC_PATH")
+else
+  VERSION="unknown"
+  TITLE="Findings Ledger API"
+fi
+
+# Generate summary
+cat > "$OUT_DIR/spec-summary.json" <<EOF
+{
+  "specPath": "$SPEC_PATH",
+  "title": "$TITLE",
+  "version": "$VERSION",
+  "validatedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "status": "validated"
+}
+EOF
+
+echo "==> Validation complete"
+echo "    Summary: $OUT_DIR/spec-summary.json"