feat: add comprehensive air-gap and vendoring support

Add support for fully offline/air-gapped builds with:

## OCI Component Vendoring
- Add `digest` attribute to `wasm_component_from_oci` and `wkg_pull` for
  immutable, reproducible pulls via SHA256 digest
- Add `vendored_component` attribute for pre-downloaded local components
- Three modes: tag-based (default), digest-based (immutable), vendored (air-gap)

## WIT Dependency Vendoring
- Add `wit_package` repository rule for downloading WIT packages with
  checksum verification and offline mode support
- Add `vendored_wit_library` macro for local vendored WIT packages
- Add `wit_vendor_lock` for lock file generation
- Support `BAZEL_WASM_WIT_VENDOR_DIR` environment variable

## Component Checksum Registry
- Add `checksums/components/` directory for OCI component checksums
- Add `component_registry.bzl` API mirroring toolchain registry pattern
- Enables centralized security auditing for component downloads

## Environment Variables
- Document `BAZEL_WASM_OFFLINE`, `BAZEL_WASM_VENDOR_DIR`, `BAZEL_WASM_MIRROR`
- Document wkg-specific env vars (`WKG_CONFIG_FILE`, `WKG_REGISTRY_*`)
- Explain `--repo_env` and `--action_env` patterns for Bazel

## Documentation & Tests
- Add comprehensive air-gap-builds.md guide covering all strategies
- Add tests/airgap/ test suite for vendored component workflows

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: avrabe

checksums/BUILD.bazel

@@ -14,6 +14,13 @@ bzl_library(
     visibility = ["//visibility:public"],
 )
 
+# Component checksum registry API
+bzl_library(
+    name = "component_registry",
+    srcs = ["component_registry.bzl"],
+    visibility = ["//visibility:public"],
+)
+
 # Export all tool checksum files for consumption by toolchains
 # Note: tools/*.json files are exported from //checksums/tools package
 filegroup(
@@ -22,6 +29,13 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
+# Export all component checksum files for OCI components
+filegroup(
+    name = "all_component_checksums",
+    srcs = ["//checksums/components:all_json"],
+    visibility = ["//visibility:public"],
+)
+
 # Individual tool checksum files
 # These reference files from the //checksums/tools package
 filegroup(

checksums/component_registry.bzl

@@ -0,0 +1,143 @@
+"""Component Checksum Registry API
+
+This module provides a unified API for accessing OCI component checksums
+from JSON files, mirroring the toolchain registry pattern.
+
+The component registry enables:
+1. Reproducible builds with digest-based pulls
+2. Security auditing via centralized checksums
+3. Air-gap builds with pre-verified components
+
+Usage:
+    load("//checksums:component_registry.bzl", "component_registry")
+
+    # Get component digest for reproducible pulls
+    digest = component_registry.get_digest(ctx, "wasi-http-proxy", "0.2.6")
+
+    # Get full component info
+    info = component_registry.get_info(ctx, "wasi-http-proxy", "0.2.6")
+"""
+
+def _load_component_json(repository_ctx, component_name):
+    """Load component data from JSON file.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component (e.g., 'wasi-http-proxy')
+
+    Returns:
+        Dict: Component data from JSON file
+
+    Raises:
+        fail: If JSON file not found
+    """
+    json_file = repository_ctx.path(
+        Label("@rules_wasm_component//checksums/components:{}.json".format(component_name)),
+    )
+    if not json_file.exists:
+        fail("Component checksums not found: //checksums/components/{}.json\n".format(component_name) +
+             "Add the component to the registry or use vendored_component attribute.")
+
+    content = repository_ctx.read(json_file)
+    return json.decode(content)
+
+def _get_component_digest(repository_ctx, component_name, version):
+    """Get verified digest for a component version.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component (e.g., 'wasi-http-proxy')
+        version: Version string (e.g., '0.2.6')
+
+    Returns:
+        String: SHA256 digest in format 'sha256:abc123...', or None if not found
+    """
+    component_data = _load_component_json(repository_ctx, component_name)
+
+    versions = component_data.get("versions", {})
+    version_data = versions.get(version, {})
+
+    return version_data.get("digest")
+
+def _get_component_info(repository_ctx, component_name, version):
+    """Get complete component information for a version.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component
+        version: Version string
+
+    Returns:
+        Dict: Complete version information including digest, wit_world, etc.
+    """
+    component_data = _load_component_json(repository_ctx, component_name)
+
+    versions = component_data.get("versions", {})
+    return versions.get(version)
+
+def _get_latest_version(repository_ctx, component_name):
+    """Get latest available version for a component.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component
+
+    Returns:
+        String: Latest version, or None if component not found
+    """
+    component_data = _load_component_json(repository_ctx, component_name)
+    return component_data.get("latest_version")
+
+def _get_oci_repository(repository_ctx, component_name):
+    """Get OCI repository URL for a component.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component
+
+    Returns:
+        String: OCI repository URL (e.g., 'ghcr.io/bytecodealliance/wasi-http-proxy')
+    """
+    component_data = _load_component_json(repository_ctx, component_name)
+    return component_data.get("oci_repository")
+
+def _list_versions(repository_ctx, component_name):
+    """List all available versions for a component.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component
+
+    Returns:
+        List: List of version strings
+    """
+    component_data = _load_component_json(repository_ctx, component_name)
+    versions = component_data.get("versions", {})
+    return list(versions.keys())
+
+def _verify_digest(repository_ctx, component_name, version, actual_digest):
+    """Verify a component's digest against the registry.
+
+    Args:
+        repository_ctx: Repository context for file operations
+        component_name: Name of the component
+        version: Version string
+        actual_digest: The digest to verify
+
+    Returns:
+        Boolean: True if digest matches, False otherwise
+    """
+    expected = _get_component_digest(repository_ctx, component_name, version)
+    if not expected:
+        return False
+    return expected == actual_digest
+
+# Public API
+component_registry = struct(
+    get_digest = _get_component_digest,
+    get_info = _get_component_info,
+    get_latest_version = _get_latest_version,
+    get_oci_repository = _get_oci_repository,
+    list_versions = _list_versions,
+    verify_digest = _verify_digest,
+)

checksums/components/BUILD.bazel

@@ -0,0 +1,30 @@
+"""Component checksum registry for OCI components
+
+This directory contains checksum information for WASM components pulled from
+OCI registries. Use these checksums with the `digest` attribute in
+`wasm_component_from_oci` or `wkg_pull` for reproducible, verifiable builds.
+
+Adding a new component:
+1. Create <component-name>.json with version info and digest
+2. Add entry to registry.json
+3. Use: wkg oci pull <ref> --output /tmp/comp.wasm && shasum -a 256 /tmp/comp.wasm
+"""
+
+package(default_visibility = ["//visibility:public"])
+
+# Export all component checksum files
+filegroup(
+    name = "all_json",
+    srcs = glob(["*.json"]),
+)
+
+# Individual component checksum files
+filegroup(
+    name = "registry_index",
+    srcs = ["registry.json"],
+)
+
+filegroup(
+    name = "wasi_http_proxy_checksums",
+    srcs = ["wasi-http-proxy.json"],
+)

checksums/components/registry.json

@@ -0,0 +1,19 @@
+{
+  "description": "Component checksum registry for air-gap and reproducible builds",
+  "version": "1.0.0",
+  "last_updated": "2026-01-16T00:00:00Z",
+  "components": [
+    {
+      "name": "wasi-http-proxy",
+      "package_file": "wasi-http-proxy.json"
+    }
+  ],
+  "usage": {
+    "description": "Use these checksums with wasm_component_from_oci or wkg_pull rules",
+    "example": {
+      "rule": "wasm_component_from_oci",
+      "digest_field": "digest",
+      "format": "sha256:<hash>"
+    }
+  }
+}

checksums/components/wasi-http-proxy.json

@@ -0,0 +1,27 @@
+{
+  "component_name": "wasi-http-proxy",
+  "description": "WASI HTTP proxy component for handling HTTP requests",
+  "oci_repository": "ghcr.io/bytecodealliance/wasi-http-proxy",
+  "homepage": "https://github.com/bytecodealliance/wasmtime",
+  "latest_version": "0.2.6",
+  "last_checked": "2026-01-16T00:00:00Z",
+  "versions": {
+    "0.2.6": {
+      "release_date": "2025-10-01",
+      "digest": "sha256:placeholder_add_real_digest_here",
+      "size_bytes": 0,
+      "wit_world": "wasi:http/proxy@0.2.6",
+      "wasi_version": "0.2.6",
+      "notes": "Compatible with wasmtime 39.0.0+"
+    }
+  },
+  "security": {
+    "signing": "Unsigned",
+    "provenance": "None"
+  },
+  "notes": [
+    "Example component entry - replace with actual digest",
+    "Run: wkg oci pull <ref> --output /tmp/comp.wasm && shasum -a 256 /tmp/comp.wasm",
+    "Format digest as sha256:<hash>"
+  ]
+}