repro-lambda 0.9.0__tar.gz → 0.10.0__tar.gz

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/.github/workflows/build.yml

@@ -7,6 +7,14 @@ on:
         type: string
         default: lambdas.toml
         description: Path to lambdas.toml in the caller repo.
+      repro_lambda_version:
+        type: string
+        required: false
+        default: "0.10.0" # bump by hand on release: the release token cannot edit workflow files
+        description: >-
+          Exact repro-lambda release run by uvx. Defaults to the release that shipped this
+          workflow, so a caller pinning `uses:` to a commit also pins the tool. Callers
+          that pin anything else (e.g. a pin job's dry run) must pass the same version.
       aws_dev_role_arn:
         type: string
         required: true
@@ -61,8 +69,8 @@ jobs:
     outputs:
       arches: ${{ steps.parse.outputs.arches }}
     steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v8.2.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       - id: parse
         shell: bash
         run: |
@@ -89,38 +97,68 @@ jobs:
     permissions:
       id-token: write
       contents: write
+    env:
+      # AWS, uploads and catalog commits run only for a push or a manual dispatch on the
+      # caller's default branch. Every other event (pull_request, pull_request_target,
+      # other branches, tags) gets no role: artifact keys are input hashes anyone with the
+      # source can compute and the buckets are first-write-wins.
+      TRUSTED: ${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
+      REPRO_LAMBDA_FROM: repro-lambda==${{ inputs.repro_lambda_version }}
     steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v8.2.0
+      # Validate before any step interpolates it (passed through env:, never inlined).
+      - name: Validate repro_lambda_version
+        env:
+          V: ${{ inputs.repro_lambda_version }}
+        run: |
+          [[ "$V" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::repro_lambda_version must be X.Y.Z, got '$V'"; exit 1; }
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       # Content-addressed source cache, scoped per-arch (a source's sha256 is its key, so a
       # re-pin changes the manifest hash -> fresh fetch; restore-keys reuses the prior cache).
       - name: Cache fetched sources
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: builds/.sources-cache
           key: repro-sources-${{ matrix.arch }}-${{ hashFiles(inputs.manifest_path) }}
           restore-keys: |
             repro-sources-${{ matrix.arch }}-
 
+      # Untrusted events never assume the dev role or write the artifact bucket (see
+      # TRUSTED). A pull request only runs the local reproducibility check below. Callers
+      # should also scope the role's OIDC trust to their default branch.
       - name: Configure AWS credentials (dev)
-        uses: aws-actions/configure-aws-credentials@v6
+        if: env.TRUSTED == 'true'
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           role-to-assume: ${{ inputs.aws_dev_role_arn }}
           aws-region: eu-west-1
 
       - name: Build (dev bucket)
+        if: env.TRUSTED == 'true'
         env:
           REPRO_LAMBDA_BUCKET: ${{ inputs.dev_bucket }}
           REPRO_LAMBDA_SOURCES_TOKEN: ${{ secrets.sources_token }}
-        run: uvx --from repro-lambda repro-lambda build --manifest "${{ inputs.manifest_path }}" --arch "${{ matrix.arch }}" --json-out "$RUNNER_TEMP/build-summary.json"
+        run: uvx --from "$REPRO_LAMBDA_FROM" repro-lambda build --manifest "${{ inputs.manifest_path }}" --arch "${{ matrix.arch }}" --reproduce-cache-hits --json-out "$RUNNER_TEMP/build-summary.json"
 
       # Render the dev build's content shas + a copy-paste promotion command per function
       # into the run's Step Summary (the build JSON is otherwise buried in step logs).
       # NB: the JSON lives in RUNNER_TEMP (outside the workspace), so hashFiles() can't guard
       # it - run on success() and skip inside the script if the file is somehow absent.
+      # The build JSON carries each artifact's zip_sha256 / code_sha256: bytes this run
+      # built, or rebuilt and matched (--reproduce-cache-hits), never a writer's record.
+      # A caller's pin job downloads it to pin those bytes, not just the input-hash key.
+      - name: Upload build summary (pin input)
+        if: env.TRUSTED == 'true'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: repro-lambda-build-summary-${{ matrix.arch }}
+          path: ${{ runner.temp }}/build-summary.json
+          if-no-files-found: error
+          retention-days: 7
+
       - name: Build summary (content shas + promote commands)
-        if: success()
+        if: success() && env.TRUSTED == 'true'
         env:
           SUMMARY_JSON: ${{ runner.temp }}/build-summary.json
           PROMOTION_REPO: ${{ inputs.promotion_repo }}
@@ -188,24 +226,24 @@ jobs:
 
       - name: Verify reproducible (PR only)
         if: github.event_name == 'pull_request'
-        run: uvx --from repro-lambda repro-lambda build --manifest "${{ inputs.manifest_path }}" --arch "${{ matrix.arch }}" --verify --dry-run
+        run: uvx --from "$REPRO_LAMBDA_FROM" repro-lambda build --manifest "${{ inputs.manifest_path }}" --arch "${{ matrix.arch }}" --verify --dry-run
 
       - name: Configure AWS credentials (prod)
-        if: github.ref == 'refs/heads/master' && inputs.aws_prod_role_arn != ''
-        uses: aws-actions/configure-aws-credentials@v6
+        if: env.TRUSTED == 'true' && inputs.aws_prod_role_arn != ''
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           role-to-assume: ${{ inputs.aws_prod_role_arn }}
           aws-region: eu-west-1
 
       - name: Build (prod bucket)
-        if: github.ref == 'refs/heads/master' && inputs.aws_prod_role_arn != ''
+        if: env.TRUSTED == 'true' && inputs.aws_prod_role_arn != ''
         env:
           REPRO_LAMBDA_BUCKET: ${{ inputs.prod_bucket }}
           REPRO_LAMBDA_SOURCES_TOKEN: ${{ secrets.sources_token }}
-        run: uvx --from repro-lambda repro-lambda build --manifest "${{ inputs.manifest_path }}" --arch "${{ matrix.arch }}"
+        run: uvx --from "$REPRO_LAMBDA_FROM" repro-lambda build --manifest "${{ inputs.manifest_path }}" --arch "${{ matrix.arch }}" --reproduce-cache-hits
 
-      - name: Commit catalog drift (master only, dev bot)
-        if: github.ref == 'refs/heads/master'
+      - name: Commit catalog drift (default branch only, dev bot)
+        if: env.TRUSTED == 'true'
         run: |
           if [[ -n "$(git status --porcelain builds/catalog.json)" ]]; then
             git config user.email "github-actions[bot]@users.noreply.github.com"

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/.github/workflows/promote.yml

@@ -10,6 +10,14 @@ on:
         type: string
         default: lambdas.toml
         description: Path to lambdas.toml in the caller repo.
+      repro_lambda_version:
+        type: string
+        required: false
+        default: "0.10.0" # bump by hand on release: the release token cannot edit workflow files
+        description: >-
+          Exact repro-lambda release run by uvx. Defaults to the release that shipped this
+          workflow, so a caller pinning `uses:` to a commit also pins the tool. Callers
+          that pin anything else (e.g. a pin job's dry run) must pass the same version.
       source_sha:
         type: string
         required: true
@@ -36,7 +44,14 @@ jobs:
     runs-on: ubuntu-24.04
     env:
       SOURCE_SHA: ${{ inputs.source_sha }}
+      REPRO_LAMBDA_FROM: repro-lambda==${{ inputs.repro_lambda_version }}
     steps:
+      # Validate before any step interpolates it (passed through env:, never inlined).
+      - name: Validate repro_lambda_version
+        env:
+          V: ${{ inputs.repro_lambda_version }}
+        run: |
+          [[ "$V" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::repro_lambda_version must be X.Y.Z, got '$V'"; exit 1; }
       # Validate source_sha BEFORE checkout to defend against script injection
       # via the inputs.source_sha expression (passed through env: + bash regex).
       - name: Validate source_sha shape (40-char hex)
@@ -46,7 +61,7 @@ jobs:
             exit 1
           fi
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ env.SOURCE_SHA }}
           fetch-depth: 0
@@ -59,10 +74,10 @@ jobs:
             exit 1
           fi
 
-      - uses: astral-sh/setup-uv@v8.2.0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Configure AWS credentials (prod promoter)
-        uses: aws-actions/configure-aws-credentials@v6
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           role-to-assume: ${{ inputs.promoter_role_arn }}
           aws-region: eu-west-1
@@ -72,4 +87,4 @@ jobs:
           REPRO_LAMBDA_DEV_BUCKET: ${{ inputs.dev_bucket }}
           REPRO_LAMBDA_PROD_BUCKET: ${{ inputs.prod_bucket }}
           MANIFEST_PATH: ${{ inputs.manifest_path }}
-        run: uvx --from repro-lambda repro-lambda promote --manifest "$MANIFEST_PATH"
+        run: uvx --from "$REPRO_LAMBDA_FROM" repro-lambda promote --manifest "$MANIFEST_PATH"

repro_lambda-0.10.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.10.0"
+}

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.10.0](https://github.com/antonbabenko/repro-lambda/compare/v0.9.1...v0.10.0) (2026-11-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* HASH_CONTRACT is 0.10.0, so every artifact gets a new key on its next build. `promote` now requires a trusted expected sha256 (`--expected-sha256` or the committed catalog) and `--allow-unrecorded` is removed. Trusted builds pass `--reproduce-cache-hits` and a pin-grade row needs a matching S3 ChecksumSHA256.
+
+### Features
+
+* verify artifact bytes against a recorded zip sha256 ([#26](https://github.com/antonbabenko/repro-lambda/issues/26)) ([f2166d6](https://github.com/antonbabenko/repro-lambda/commit/f2166d6b76d7cfdf6be6029439ead5feb58a053a))
+
+
+### Bug Fixes
+
+* **release:** stop release-please editing workflow files ([#27](https://github.com/antonbabenko/repro-lambda/issues/27)) ([ca7d18a](https://github.com/antonbabenko/repro-lambda/commit/ca7d18afb0ec512a810ad74d78bb4149812eb96d))
+
+## [0.9.1](https://github.com/antonbabenko/repro-lambda/compare/v0.9.0...v0.9.1) (2026-11-09)
+
+
+### Bug Fixes
+
+* **deps:** cap typer below 0.29 ([#24](https://github.com/antonbabenko/repro-lambda/issues/24)) ([2e535af](https://github.com/antonbabenko/repro-lambda/commit/2e535afb3bdb9e47c06f8ce32bd23185badcaa0f))
+
 ## [0.9.0](https://github.com/antonbabenko/repro-lambda/compare/v0.8.2...v0.9.0) (2026-10-30)
 
 

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: repro-lambda
-Version: 0.9.0
+Version: 0.10.0
 Summary: Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf.
 Project-URL: Homepage, https://github.com/antonbabenko/repro-lambda
 Project-URL: Repository, https://github.com/antonbabenko/repro-lambda
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
 Requires-Dist: boto3>=1.34
 Requires-Dist: repro-zipfile>=0.3.1
 Requires-Dist: tomlkit>=0.13
-Requires-Dist: typer>=0.12
+Requires-Dist: typer<0.29,>=0.12
 Provides-Extra: dev
 Requires-Dist: moto[s3]>=5; extra == 'dev'
 Requires-Dist: pre-commit>=3.7; extra == 'dev'

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/USAGE.md

@@ -20,8 +20,14 @@ on:
 
 jobs:
   build:
-    uses: antonbabenko/repro-lambda/.github/workflows/build.yml@v0
+    # The job that receives id-token: write gets a reusable workflow you cannot move
+    # under it: pin the commit of a release tag, and the matching tool version.
+    uses: antonbabenko/repro-lambda/.github/workflows/build.yml@<release commit sha> # v0.x.y
+    permissions:
+      contents: write
+      id-token: write
     with:
+      repro_lambda_version: 0.x.y
       manifest_path: lambdas.toml
       aws_dev_role_arn: arn:aws:iam::<dev-account-id>:role/gha-lambda-builder-dev
       dev_bucket: <dev-env>-my-lambda-artifacts
@@ -30,9 +36,13 @@ jobs:
       # prod_bucket: <prod-env>-my-lambda-artifacts
 ```
 
-Pin the reusable workflow with the sliding major tag `@v0` - it auto-moves to the
-latest backward-compatible 0.x release on every tag (switch to `@v1` once repro-lambda
-ships 1.0). The role ARNs are not secrets: the boundary is the OIDC trust policy plus
+Pin the reusable workflow to the commit of a release tag, not the sliding `@v0`:
+the job holds `id-token: write`, so whoever can move the tag chooses the code that
+assumes your role. The workflow skips AWS for every event except a push or manual
+dispatch on your default branch, and still scope the role's OIDC trust to
+`repo:<owner>/<repo>:ref:refs/heads/<default branch>`. It uploads the build JSON
+(`repro-lambda-build-summary-<arch>`), whose `zip_sha256` / `code_sha256` are what a
+pin job should record next to each key. The role ARNs are not secrets: the boundary is the OIDC trust policy plus
 the key-level bucket immutability, so they are plain inputs (only the account IDs,
 which are public), not stored secrets.
 
@@ -185,8 +195,14 @@ In CI, pass the token to the reusable `build.yml` as the `sources_token` secret:
 ```yaml
 jobs:
   build:
-    uses: antonbabenko/repro-lambda/.github/workflows/build.yml@v0
+    # The job that receives id-token: write gets a reusable workflow you cannot move
+    # under it: pin the commit of a release tag, and the matching tool version.
+    uses: antonbabenko/repro-lambda/.github/workflows/build.yml@<release commit sha> # v0.x.y
+    permissions:
+      contents: write
+      id-token: write
     with:
+      repro_lambda_version: 0.x.y
       manifest_path: lambdas.toml
       aws_dev_role_arn: arn:aws:iam::<account>:role/<dev-builder-role>
       dev_bucket: <dev-env>-my-lambda-artifacts
@@ -252,8 +268,22 @@ attributes (`source_path`, `build_in_docker`, `trigger_on_package_timestamp`,
   the bucket. Check the inline policy resources include both the bucket ARN and
   `${bucket_arn}/*`.
 - **`PreconditionFailed` on every upload**: the artifact already exists with
-  that sha. This is the expected cache-hit behavior; `repro-lambda` treats it
-  as success.
+  that sha. `repro-lambda` then downloads the existing object and accepts it only
+  if its bytes hash to the zip it just built.
+- **`ArtifactIntegrityError`**: an object under the content key does not hold the
+  bytes this source builds. Every upload records the zip's sha256 as object
+  metadata (`x-amz-meta-zip-sha256`) and as the S3 `ChecksumSHA256` in the same
+  first write. A cache hit hashes the object against that record; an object with
+  no record is rebuilt and compared byte for byte. The record is written by the
+  object's writer, so it only proves the bytes did not change after that write:
+  bind them with the `zip_sha256` / `code_sha256` the build JSON reports (pin it
+  next to the key). Pin only rows whose `zip_source` is `built` or `reproduced`;
+  `build --reproduce-cache-hits` (on by default in the reusable workflow's trusted
+  runs) rebuilds every cache hit so none is a bare `record`. `promote` checks the
+  artifact against `--expected-sha256` or the `zip_sha256` that `builds/catalog.json`
+  records for the key, and refuses without one. The key is an input hash anyone
+  with the source can compute, so treat this error as a possibly planted
+  artifact: find who wrote the object before doing anything else.
 - **AWS CLI multipart upload fails with 403**: bucket policy denies multipart
   parts. Pin the multipart threshold above your Lambda size cap:
   `aws configure set s3.multipart_threshold 300MB`.

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repro-lambda"
-version = "0.9.0"
+version = "0.10.0"
 description = "Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,7 +18,9 @@ classifiers = [
   "Topic :: Software Development :: Build Tools",
 ]
 dependencies = [
-  "typer>=0.12",
+  # shortcut: typer 0.29 imports pydantic, whose compiled core in the runner env
+  # cannot load in the container Python; lift once the container zip step stops importing the CLI.
+  "typer>=0.12,<0.29",
   "repro-zipfile>=0.3.1",
   "boto3>=1.34",
   "tomlkit>=0.13",

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/src/repro_lambda/__init__.py

@@ -1,3 +1,3 @@
 """repro-lambda — reproducible AWS Lambda packaging outside Terraform."""
 
-__version__ = "0.9.0"  # x-release-please-version
+__version__ = "0.10.0"  # x-release-please-version

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/src/repro_lambda/build.py

@@ -13,7 +13,13 @@ from repro_lambda.catalog import Catalog, CatalogEntry
 from repro_lambda.docker_runner import build_nodejs_lambda, build_python_lambda
 from repro_lambda.hasher import HASH_CONTRACT, compute_content_hash
 from repro_lambda.manifest import BuilderConfig, LambdaSpec, resolve_builder
-from repro_lambda.s3_uploader import S3Uploader, UploadResult
+from repro_lambda.s3_uploader import (
+    ArtifactIntegrityError,
+    S3Uploader,
+    UploadResult,
+    code_sha256,
+    sha256_hex,
+)
 from repro_lambda.source_stager import stage_source
 
 
@@ -28,6 +34,11 @@ class BuildOutcome:
     outcome: BuildResult
     sha256: str
     bucket_key: str
+    # sha256 of the zip bytes behind bucket_key. None for a dry run. This, not the key,
+    # is what a pin binds, and only when zip_source is "built" or "reproduced": a
+    # "record" value is the object writer's own claim (checked against the body only).
+    zip_sha256: str | None = None
+    zip_source: str | None = None  # "built" | "reproduced" | "record"
 
 
 def _bucket_for(spec: LambdaSpec, base_bucket: str) -> str:
@@ -103,8 +114,14 @@ def build_one(
     dry_run: bool = False,
     sources_token: str | None = None,
     sources_cache: Path | None = None,
+    reproduce_cache_hits: bool = False,
 ) -> BuildOutcome:
-    """Build one lambda end-to-end. Returns BuildOutcome with sha + cache verdict."""
+    """Build one lambda end-to-end. Returns BuildOutcome with sha + cache verdict.
+
+    ``reproduce_cache_hits`` rebuilds on every cache hit and fails unless the stored
+    bytes equal the rebuild, so the reported zip_sha256 is this run's own build. Set it
+    on the runs whose output gets pinned.
+    """
     builder = resolve_builder(builder, spec)
     target_bucket = _bucket_for(spec, bucket)
 
@@ -143,12 +160,26 @@ def build_one(
             return BuildOutcome(BuildResult.DRY_RUN, sha, bucket_key)
 
         uploader = S3Uploader(region=spec.region)
+        # The key is an input hash anyone can compute and the bucket is first-write-wins,
+        # so an existing object is never trusted by its key: its body must match the
+        # sha256 recorded at first write. With no record (a legacy or foreign object), or
+        # when the caller asks to reproduce cache hits, rebuild and compare below.
+        compare_sha: str | None = None
         if uploader.exists(bucket=target_bucket, key=bucket_key):
-            _record(catalog, spec, sha, source_commit, builder, built=False)
-            return BuildOutcome(BuildResult.CACHE_HIT, sha, bucket_key)
+            actual, recorded = uploader.read(bucket=target_bucket, key=bucket_key)
+            if recorded is not None and recorded != actual:
+                raise ArtifactIntegrityError(
+                    f"s3://{target_bucket}/{bucket_key}: body sha256 {actual} != "
+                    f"recorded sha256 {recorded}"
+                )
+            if recorded is not None and not reproduce_cache_hits:
+                _record(catalog, spec, sha, source_commit, builder, built=False)
+                return BuildOutcome(BuildResult.CACHE_HIT, sha, bucket_key, actual, "record")
+            compare_sha = actual
 
-        # Cache miss only: fetch + verify + extract declarative sources into the staged
-        # tree (post-filter; collides loudly with already-staged source/payload files).
+        # Cache miss (or an unrecorded object to compare): fetch + verify + extract
+        # declarative sources into the staged tree (post-filter; collides loudly with
+        # already-staged source/payload files).
         if spec.sources:
             from repro_lambda.sources import fetch_sources
 
@@ -181,10 +212,39 @@ def build_one(
                 node_version=node_ver,
             )
 
+        built_sha = sha256_hex(out_zip.read_bytes())
+        if compare_sha is not None:
+            if built_sha != compare_sha:
+                raise ArtifactIntegrityError(
+                    f"s3://{target_bucket}/{bucket_key}: existing body sha256 "
+                    f"{compare_sha} != rebuilt zip sha256 {built_sha}"
+                )
+            # A missing record cannot be backfilled: the bucket denies any overwrite.
+            _require_s3_checksum(uploader, target_bucket, bucket_key, built_sha)
+            _record(catalog, spec, sha, source_commit, builder, built=False, zip_sha256=built_sha)
+            return BuildOutcome(BuildResult.CACHE_HIT, sha, bucket_key, built_sha, "reproduced")
+
         result = uploader.upload(bucket=target_bucket, key=bucket_key, body_path=out_zip)
         assert result in {UploadResult.UPLOADED, UploadResult.ALREADY_PRESENT}
-        _record(catalog, spec, sha, source_commit, builder, built=True)
-        return BuildOutcome(BuildResult.BUILT_AND_UPLOADED, sha, bucket_key)
+        _require_s3_checksum(uploader, target_bucket, bucket_key, built_sha)
+        _record(catalog, spec, sha, source_commit, builder, built=True, zip_sha256=built_sha)
+        return BuildOutcome(BuildResult.BUILT_AND_UPLOADED, sha, bucket_key, built_sha, "built")
+
+
+def _require_s3_checksum(uploader: S3Uploader, bucket: str, key: str, zip_sha256: str) -> None:
+    """A pin-grade row must match the S3 ChecksumSHA256 the deploy-time checks read.
+
+    Promotion and the consumer's plan compare the pinned code_sha256 with the object's
+    S3 checksum, so an object without it (or with another) is refused here, at build
+    time, instead of failing a later plan.
+    """
+    got = uploader.s3_checksum(bucket=bucket, key=key)
+    want = code_sha256(zip_sha256)
+    if got != want:
+        raise ArtifactIntegrityError(
+            f"s3://{bucket}/{key}: S3 ChecksumSHA256 {got!r} != code_sha256 {want!r}; the "
+            f"object cannot be pinned (written without a checksum, or other bytes)"
+        )
 
 
 def _record(
@@ -195,6 +255,7 @@ def _record(
     builder: BuilderConfig,
     *,
     built: bool,
+    zip_sha256: str | None = None,
 ) -> None:
     if spec.package_manager == "npm":
         primary_image = builder.base_image_nodejs
@@ -213,5 +274,6 @@ def _record(
             builder_version=__version__ if built else f"hash-contract:{HASH_CONTRACT}",
             base_image_digest=primary_image.split("@", 1)[-1],
             built_at=datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            zip_sha256=zip_sha256,
         ),
     )

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/src/repro_lambda/catalog.py

@@ -20,6 +20,9 @@ class CatalogEntry:
     builder_version: str
     base_image_digest: str
     built_at: str  # ISO-8601 UTC, e.g. "2026-05-27T09:30:00Z"
+    # sha256 of the zip bytes, set only when this run built or reproduced them (never
+    # from an object's writer-set record). promote checks the artifact against it.
+    zip_sha256: str | None = None
 
 
 @dataclass
@@ -38,6 +41,9 @@ class Catalog:
             self.lambdas[logical_name] = LambdaCatalog(current=entry.sha256, history=[entry])
             return
         if lc.current == entry.sha256:
+            # Same artifact: keep its first entry, but learn the reproduced zip sha256.
+            if entry.zip_sha256 and lc.history and not lc.history[0].zip_sha256:
+                lc.history[0].zip_sha256 = entry.zip_sha256
             return
         lc.history.insert(0, entry)
         lc.current = entry.sha256
@@ -58,6 +64,15 @@ class Catalog:
         path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
 
 
+def zip_sha256_for(catalog: Catalog, logical_name: str, sha: str) -> str | None:
+    """The zip sha256 a build of this repo recorded for one artifact key, if any."""
+    lc = catalog.lambdas.get(logical_name)
+    for e in lc.history if lc else []:
+        if e.sha256 == sha and e.zip_sha256:
+            return e.zip_sha256
+    return None
+
+
 def load_catalog(path: Path) -> Catalog:
     if not path.exists():
         return Catalog(lambdas={})

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/src/repro_lambda/cli.py

@@ -77,6 +77,14 @@ def build(
             help="Also write the build summary JSON array to this file (for CI Step Summary).",
         ),
     ] = None,
+    reproduce_cache_hits: Annotated[
+        bool,
+        typer.Option(
+            "--reproduce-cache-hits",
+            help="Rebuild on every cache hit and fail unless the stored zip equals the "
+            "rebuild, so every reported zip_sha256 is this run's own build (pin runs).",
+        ),
+    ] = False,
 ) -> None:
     """Build one lambda (or all) per manifest and upload to S3."""
     import json
@@ -85,6 +93,7 @@ def build(
     from repro_lambda.catalog import load_catalog
     from repro_lambda.git_guard import DirtyWorktreeError, ensure_clean_worktree
     from repro_lambda.manifest import load_manifest
+    from repro_lambda.s3_uploader import code_sha256
 
     repo_root = manifest.parent.resolve()
     parsed = load_manifest(manifest)
@@ -149,6 +158,7 @@ def build(
             source_commit=source_commit,
             dry_run=dry_run,
             sources_token=sources_token,
+            reproduce_cache_hits=reproduce_cache_hits,
         )
         summary.append(
             {
@@ -156,6 +166,21 @@ def build(
                 "outcome": outcome.outcome.value,
                 "sha256": outcome.sha256,
                 "bucket_key": outcome.bucket_key,
+                # Region of the artifact bucket (us-east-1 = the -us-east-1 variant).
+                "region": spec.region,
+                # Bytes behind the key (built, or verified on a cache hit). Pin these:
+                # zip_sha256 is hex, code_sha256 the same digest in base64 (S3
+                # ChecksumSHA256 / Lambda CodeSha256). Absent on a dry run.
+                **(
+                    {
+                        "zip_sha256": outcome.zip_sha256,
+                        "code_sha256": code_sha256(outcome.zip_sha256),
+                        # Pin only "built" / "reproduced"; "record" is the writer's claim.
+                        "zip_source": outcome.zip_source,
+                    }
+                    if outcome.zip_sha256
+                    else {}
+                ),
             }
         )
 
@@ -215,6 +240,15 @@ def promote(
         ),
     ] = "",
     dry_run: Annotated[bool, typer.Option("--dry-run")] = False,
+    expected_sha256: Annotated[
+        str,
+        typer.Option(
+            "--expected-sha256",
+            help="64-hex sha256 the dev zip body must match (the pinned zip sha256). "
+            "Default: the zip_sha256 builds/catalog.json records for the promoted key; "
+            "promote refuses without one. Single lambda target only.",
+        ),
+    ] = "",
 ) -> None:
     """Copy built artifacts dev -> prod by content hash (no rebuild).
 
@@ -228,11 +262,14 @@ def promote(
 
     from repro_lambda.manifest import load_manifest
     from repro_lambda.promote import (
+        MissingExpectedShaError,
         MissingSourceArtifactError,
         UnknownShaError,
+        expected_from_catalog,
         promote_one,
         sha_from_catalog,
     )
+    from repro_lambda.s3_uploader import ArtifactIntegrityError
 
     repo_root = manifest.parent.resolve()
     parsed = load_manifest(manifest)
@@ -254,6 +291,17 @@ def promote(
             typer.echo(f"--sha must be 64 lowercase hex chars, got {sha!r}", err=True)
             raise typer.Exit(2)
 
+    if expected_sha256:
+        if target == "all" or len(selected) != 1:
+            typer.echo("--expected-sha256 requires a single lambda target (not 'all')", err=True)
+            raise typer.Exit(2)
+        if not re.fullmatch(r"[a-f0-9]{64}", expected_sha256):
+            typer.echo(
+                f"--expected-sha256 must be 64 lowercase hex chars, got {expected_sha256!r}",
+                err=True,
+            )
+            raise typer.Exit(2)
+
     if not dry_run and (not dev_bucket or not prod_bucket):
         typer.echo(
             "--dev-bucket and --prod-bucket (or REPRO_LAMBDA_DEV_BUCKET / "
@@ -273,8 +321,15 @@ def promote(
                 dev_bucket=dev_bucket,
                 prod_bucket=prod_bucket,
                 dry_run=dry_run,
+                expected_sha256=expected_sha256
+                or expected_from_catalog(catalog_path, spec.logical_name, resolved_sha),
             )
-        except (MissingSourceArtifactError, UnknownShaError) as e:
+        except (
+            MissingExpectedShaError,
+            MissingSourceArtifactError,
+            UnknownShaError,
+            ArtifactIntegrityError,
+        ) as e:
             typer.echo(str(e), err=True)
             raise typer.Exit(1) from e
         summary.append(

{repro_lambda-0.9.0 → repro_lambda-0.10.0}/src/repro_lambda/hasher.py

@@ -14,7 +14,11 @@ from repro_lambda.manifest import LambdaSpec, Source
 # the fingerprints in tests/test_hash_contract.py with it. Frozen at "0.8.0", the last
 # package version folded here, so keys minted by 0.8.0 stay valid; the packaging
 # modules did not change between 0.7.2 and 0.8.1.
-HASH_CONTRACT = "0.8.0"
+# "0.10.0": a deliberate re-key with unchanged bytes. Keys minted before 0.10 were
+# writable by any run the builder role trusted and carry no recorded zip sha256, so
+# every artifact is rebuilt under a fresh key, written once with its sha256 recorded,
+# and pinned with that sha256. Old keys are never reused.
+HASH_CONTRACT = "0.10.0"
 
 
 def _sha256_file(path: Path) -> str: