Sync final env readiness check 23060aa

README.md

@@ -142,7 +142,7 @@ The browser UI and `GET /api/submission/gate` expose the same fail-closed final
 `scripts/live_env_handoff.py` creates a redacted B2/Genblaze credential handoff report so final proof setup can be checked without printing keys.
 `scripts/genblaze_contract_check.py` verifies the installed Genblaze/B2 SDK import and signature contract without reading environment variables or credential files, catching package/API drift before live keys are entered.
 `scripts/docker_smoke.py` verifies the Docker image builds, starts in local/mock mode, passes API smoke, and uses `.dockerignore` to keep local env files out of the build context.
-`scripts/final_env_wizard.py` creates a local git-ignored `.env.final.local` with 0600 permissions, can prefill non-secret B2/default values, reads existing local values as defaults, and uses hidden prompts for credential values.
+`scripts/final_env_wizard.py` creates a local git-ignored `.env.final.local` with 0600 permissions, can prefill non-secret B2/default values, reads existing local values as defaults, and uses hidden prompts for credential values. Its `--check-only` mode is a no-secret readiness preflight for git-ignore status, `.env.final.local` presence, chmod `0600`, missing or placeholder variable names, and B2 region derivation.
 `scripts/b2_key_scope_checklist.py` creates a no-secret B2 app-key scope checklist for the dedicated bucket, prefix, required upload capability, S3 SDK compatibility flag, forbidden permissions, and stop conditions before a key is created.
 `scripts/run_b2_live_proof.py` verifies the Backblaze B2 storage path independently with mock generation, so T020 can close before Genblaze credentials are ready.
 `scripts/devpost_form_kit.py` turns the safe packet into field-by-field Devpost copy with length checks, a strict final gate, and an in-app Devpost Kit through `GET /api/judge/devpost`.

docs/todo.md

@@ -49,3 +49,4 @@ python3 scripts/task.py doing T020 --note "Live B2 proof in progress"
 | T090 | Final closeout status is now available through `/api/judge/final-closeout`, a judge-mode UI panel/link, API smoke, and public Space HTML marker validation. |
 | T091 | Final closeout public sync now accepts both pre-final fail-closed and final-ready all-green states, validates the API against raw evidence, and keeps the UI next command visible. |
 | T092 | No-secret live credential handoff regenerated from `.env.final.local`; remaining local credential blockers are narrowed to `b2_key_id`, `b2_application_key`, and `genblaze_api_key`. |
+| T093 | Final env `--check-only` now performs no-secret readiness preflight for git-ignore, chmod `0600`, missing/placeholder names, B2 region derivation, and `B2_APP_KEY` alias handling. |

docs/verification.md

@@ -85,6 +85,8 @@ Use the CI result as public repo evidence for the non-secret local gate. It does
 
 Evidence files written by `scripts/api_smoke.py --evidence-out` are checked before writing and fail closed if they contain secret-like field names, bearer tokens, signed URL parameters, or GMI-style key values.
 
+`python scripts/final_env_wizard.py --check-only` is intentionally safe to run in CI and locally. In CI it proves the target env file is git-ignored; locally it also reports `.env.final.local` presence, chmod `0600`, missing required variable names, placeholder names, B2 region derivation, and `ready_for_live_entry` without printing credential values.
+
 The final sponsor proof has a preflight wrapper:
 
 ```bash

scripts/final_env_wizard.py

@@ -19,6 +19,7 @@ ROOT = Path(__file__).resolve().parents[1]
 DEFAULT_OUTPUT = ROOT / ".env.final.local"
 DEFAULT_B2_SETUP = ROOT / "docs" / "assets" / "b2-live-setup.json"
 SAFE_ENV_RE = re.compile(r"^[A-Za-z0-9_./:@%+=,-]+$")
+PLACEHOLDERS = {"", "placeholder", "change-me", "changeme", "todo", "tbd", "none", "null", "..."}
 
 NEXT_COMMANDS = [
     "python scripts/live_env_handoff.py --env-file .env.final.local --strict",
@@ -45,7 +46,13 @@ FIELDS = [
     EnvField("B2_REGION", "Backblaze B2 region", required=False),
     EnvField("B2_BUCKET", "Backblaze B2 bucket name"),
     EnvField("B2_KEY_ID", "Backblaze B2 application key id"),
-    EnvField("B2_APPLICATION_KEY", "Backblaze B2 application key", secret=True),
+    EnvField(
+        "B2_APPLICATION_KEY",
+        "Backblaze B2 application key",
+        secret=True,
+        aliases=("B2_APP_KEY",),
+        mirror_to=("B2_APP_KEY",),
+    ),
     EnvField("B2_PUBLIC_BASE_URL", "Optional B2 public base URL", required=False),
     EnvField(
         "GENBLAZE_API_KEY",
@@ -64,10 +71,19 @@ def normalize(value: str | None) -> str:
     return (value or "").strip()
 
 
+def has_real_value(value: str | None) -> bool:
+    normalized = normalize(value).strip('"').strip("'")
+    if normalized.lower() in PLACEHOLDERS:
+        return False
+    if normalized.startswith("<") and normalized.endswith(">"):
+        return False
+    return bool(normalized)
+
+
 def env_lookup(field: EnvField, environ: Mapping[str, str]) -> str:
     for name in (field.name, *field.aliases):
         value = normalize(environ.get(name))
-        if value:
+        if has_real_value(value):
             return value
     return ""
 
@@ -308,11 +324,34 @@ def target_is_git_ignored(root: Path, path: Path) -> bool:
 def build_check(root: Path = ROOT, output: Path = DEFAULT_OUTPUT) -> dict[str, object]:
     output = output.resolve()
     ignored = target_is_git_ignored(root, output)
+    env_file_present = output.exists()
+    values = parse_env_file(output) if env_file_present else {}
+    missing_required_names = [
+        field.name for field in FIELDS if field.required and not env_lookup(field, values)
+    ]
+    placeholder_names: list[str] = []
+    seen_placeholders: set[str] = set()
+    for field in FIELDS:
+        if not (field.required or field.secret):
+            continue
+        for name in (field.name, *field.aliases, *field.mirror_to):
+            if name in values and not has_real_value(values.get(name)) and name not in seen_placeholders:
+                placeholder_names.append(name)
+                seen_placeholders.add(name)
+    mode = output.stat().st_mode & 0o777 if env_file_present else None
+    mode_ok = mode == 0o600 if env_file_present else False
+    b2_endpoint = env_lookup(next(field for field in FIELDS if field.name == "B2_ENDPOINT_URL"), values)
+    b2_region_value = env_lookup(next(field for field in FIELDS if field.name == "B2_REGION"), values)
+    b2_region_derived = region_from_b2_endpoint(b2_endpoint)
+    b2_region_ok = bool(b2_region_value or b2_region_derived)
     return {
         "schema": "proofframe.final_env_wizard_check.v1",
         "ok": ignored,
         "output": str(output),
         "git_ignored": ignored,
+        "env_file_present": env_file_present,
+        "env_file_mode": oct(mode) if mode is not None else None,
+        "env_file_mode_ok": mode_ok,
         "required_fields": [field.name for field in FIELDS if field.required],
         "secret_fields": [
             name
@@ -320,6 +359,20 @@ def build_check(root: Path = ROOT, output: Path = DEFAULT_OUTPUT) -> dict[str, o
             if field.secret
             for name in (field.name, *field.mirror_to)
         ],
+        "present_required_names": [
+            field.name for field in FIELDS if field.required and env_lookup(field, values)
+        ],
+        "missing_required_names": missing_required_names,
+        "placeholder_names": placeholder_names,
+        "b2_region": {
+            "present": bool(b2_region_value),
+            "derived_from_endpoint": b2_region_derived,
+            "ok": b2_region_ok,
+        },
+        "ready_for_live_entry": bool(
+            ignored and env_file_present and mode_ok and not missing_required_names and b2_region_ok
+        ),
+        "next_commands": NEXT_COMMANDS,
         "policy": (
             "The wizard writes only to a git-ignored local env file and command output lists "
             "variable names only, never credential values."

tasks.json

@@ -209,6 +209,15 @@
       "done_criteria": "",
       "notes": "Generated docs/assets/live-credential-handoff.* from .env.final.local without printing values; non-secret B2 bucket/endpoint and backend modes are present, and remaining secret blockers are narrowed to b2_key_id, b2_application_key, and genblaze_api_key."
     },
+    {
+      "id": "T093",
+      "title": "Harden final env readiness preflight",
+      "phase": "P4 Submit",
+      "owner": "reviewer",
+      "status": "done",
+      "done_criteria": "",
+      "notes": "final_env_wizard.py --check-only now reports git-ignore status, .env.final.local presence, chmod 0600 status, missing required names, placeholder names, B2 region derivation, and ready_for_live_entry without printing credential values; B2_APP_KEY is accepted and mirrored as a B2_APPLICATION_KEY alias."
+    },
     {
       "id": "T030",
       "title": "Run browser smoke test",

tests/test_final_env_wizard.py

@@ -22,7 +22,10 @@ def test_final_env_wizard_check_requires_ignored_output(tmp_path):
 
     assert report["ok"] is True
     assert report["git_ignored"] is True
+    assert report["env_file_present"] is False
+    assert report["ready_for_live_entry"] is False
     assert "B2_APPLICATION_KEY" in report["secret_fields"]
+    assert "B2_APP_KEY" in report["secret_fields"]
     assert "GMI_API_KEY" in report["secret_fields"]
 
 
@@ -35,6 +38,78 @@ def test_final_env_wizard_check_fails_for_unignored_output(tmp_path):
     assert report["git_ignored"] is False
 
 
+def test_final_env_wizard_check_reports_existing_env_readiness_without_values(tmp_path):
+    (tmp_path / ".gitignore").write_text(".env.*\n!.env.final.example\n", encoding="utf-8")
+    env_path = tmp_path / ".env.final.local"
+    env_path.write_text(
+        "\n".join(
+            [
+                "PROOFFRAME_STORAGE_BACKEND=b2",
+                "PROOFFRAME_GENERATION_BACKEND=genblaze",
+                "B2_ENDPOINT_URL=https://s3.us-west-004.backblazeb2.com",
+                "B2_BUCKET=proofframe-demo-a6b4e49",
+                "B2_KEY_ID=least-privilege-key-id",
+                "B2_APP_KEY=secret-b2-key",
+                "GENBLAZE_API_KEY=secret-gmi-key",
+                "GENBLAZE_IMAGE_MODEL=seedream-5.0-lite",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    os.chmod(env_path, 0o600)
+
+    report = final_env_wizard.build_check(tmp_path, env_path)
+    serialized = json.dumps(report)
+
+    assert report["ok"] is True
+    assert report["env_file_present"] is True
+    assert report["env_file_mode_ok"] is True
+    assert report["missing_required_names"] == []
+    assert report["placeholder_names"] == []
+    assert report["b2_region"]["derived_from_endpoint"] == "us-west-004"
+    assert report["ready_for_live_entry"] is True
+    assert "secret-b2-key" not in serialized
+    assert "secret-gmi-key" not in serialized
+
+
+def test_final_env_wizard_check_reports_missing_and_placeholder_names(tmp_path):
+    (tmp_path / ".gitignore").write_text(".env.*\n!.env.final.example\n", encoding="utf-8")
+    env_path = tmp_path / ".env.final.local"
+    env_path.write_text(
+        "\n".join(
+            [
+                "PROOFFRAME_STORAGE_BACKEND=b2",
+                "PROOFFRAME_GENERATION_BACKEND=genblaze",
+                "B2_ENDPOINT_URL=s3.us-west-004.backblazeb2.com",
+                "B2_BUCKET=proofframe-demo-a6b4e49",
+                "B2_KEY_ID=todo",
+                "B2_APPLICATION_KEY=",
+                "GENBLAZE_API_KEY=<paste-key>",
+                "GENBLAZE_IMAGE_MODEL=seedream-5.0-lite",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    os.chmod(env_path, 0o644)
+
+    report = final_env_wizard.build_check(tmp_path, env_path)
+
+    assert report["env_file_mode_ok"] is False
+    assert report["missing_required_names"] == [
+        "B2_KEY_ID",
+        "B2_APPLICATION_KEY",
+        "GENBLAZE_API_KEY",
+    ]
+    assert set(report["placeholder_names"]) >= {
+        "B2_KEY_ID",
+        "B2_APPLICATION_KEY",
+        "GENBLAZE_API_KEY",
+    }
+    assert report["ready_for_live_entry"] is False
+
+
 def test_final_env_wizard_collects_from_env_and_mirrors_gmi_key():
     values = final_env_wizard.collect_values(
         from_env=True,
@@ -120,6 +195,7 @@ def test_final_env_wizard_collects_missing_values_only_and_mirrors_gmi_key(tmp_p
     assert filled_names == [
         "B2_KEY_ID",
         "B2_APPLICATION_KEY",
+        "B2_APP_KEY",
         "GENBLAZE_API_KEY",
         "GMI_API_KEY",
     ]