agentleFS
hushh-labshushh-labs/hushh-research/.agents/skills/client-env-parity/SKILL.md

client-env-parity

Skill40 starsChanged 4 days agoApache-2.0View on GitHub

Prevents a client credential from existing in Secret Manager yet never reaching the app that needs it, and prevents an API key from rejecting an origin the app really runs at. Use BEFORE shipping any iOS/TestFlight/App Store or web build, when adding or changing any NEXT_PUBLIC_* value, when adding a build lane, when a feature works on web but not in the app (or the reverse), and whenever a map, embed, analytics tag, or third-party widget renders as a blank box, a placeholder, or a static fallback with no error in the console.

  • Reads credentials
  • Sends data out

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    The value reaches the build: Every NEXT_PUBLIC_* is baked in at build time.

    line 13
  2. Distinctive:

    Always pass the complete desired set or you will silently drop the origins you meant to keep.

    line 85
  3. Distinctive:

    After widening a key, confirm it is still restricted:

    line 87
  4. Very specific:

    Use .agents/skills/mobile-native/SKILL.md for the selected-profile build, native Firebase sync, and bundled backend/project verification.

    line 129
  5. Distinctive:

    Do not report a client credential as fixed on the strength of the secret existing.

    line 148

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Client env parity

A credential that exists is not a credential that shipped.

Two independent things must both be true before a client credential works. Each fails silently on its own. Both failed at once on 2026-08-11, which is why this skill exists.

  1. The value reaches the build. Every NEXT_PUBLIC_* is baked in at build time. Each lane copies its own explicit list, so a value can be perfect in Secret Manager and simply absent from one lane's build.
  2. The key accepts the origin. A referrer-restricted key must list every origin the app actually runs at — and the app runs at more origins than the hosted domain.

Neither failure throws. The client reads "", or the provider returns a refusal the UI already has a fallback for, and the feature degrades into something that looks merely plain. A blank map is not an error state anyone reports.


Run both checks

.agents/skills/client-env-parity/check.sh                       # value reaches every lane
.agents/skills/client-env-parity/check-key-origins.sh hushh-pda-uat   # key accepts every origin

Both exit non-zero on a gap and print exactly what is missing. check.sh is offline and fast — put it in front of any release. check-key-origins.sh is read-only and needs gcloud; it never modifies a key.

Verified to catch the real bug: run check.sh against main at 34eb56b02d6734b0ecfa8455f009f0f66db7eac3 and it reports all three genuine gaps that shipped. A guard that cannot fail is not a guard — re-prove it this way after editing it.


The lanes, and why parity is not automatic

LaneFileHow it passes values
webdeploy/frontend.cloudbuild.yaml--build-arg NEXT_PUBLIC_X=… + availableSecrets
ios-testflight.github/workflows/ship-ios-testflight.ymlput NEXT_PUBLIC_X "$VAL" → .env.local
ios-appstore.github/workflows/release-ios-appstore.ymlput NEXT_PUBLIC_X "$VAL" → .env.local

There is no shared list. Adding a value to the web lane does not add it to the iOS lanes. check.sh compares required-client-env.tsv against all three.

When you add a client credential, add a row to required-client-env.tsv. That row — not good intentions — is what makes the check protect it. Keep local-only and test-only vars out; a noisy check gets ignored, which is precisely how the original bug survived.


Origins this app runs at

From hushh-webapp/capacitor.config.ts:

ios:    { scheme: "App" }          // webview origin: App://localhost
server: { iosScheme: "App",
          androidScheme: "https" } // webview origin: https://localhost

So a browser key restricted to the hosted domain alone is rejected inside the app with RefererNotAllowedMapError. The required list:

OriginWhere it comes from
https://<hosted-host>/*the real site
http://localhost:3000/*npm run dev
App://localhost/*iOS app webview — the one everyone forgets
capacitor://localhost/*Capacitor's default if iosScheme is ever removed
https://localhost/*Android app webview
http://localhost/*Capacitor fallback

Scheme matching is case-insensitive — app://, App://, and APP:// all match a single entry. Verified against Google directly, not assumed.

gcloud services api-keys update replaces the restriction lists; it does not append. Always pass the complete desired set or you will silently drop the origins you meant to keep.

After widening a key, confirm it is still restricted:

curl -s -X POST "https://places.googleapis.com/v1/places:searchNearby" \
  -H "X-Goog-Api-Key: $KEY" -H "Referer: https://evil.example.com/" \
  -H "Content-Type: application/json" -H "X-Goog-FieldMask: places.id" \
  -d '{"includedTypes":["cafe"],"maxResultCount":1,"locationRestriction":{"circle":{"center":{"latitude":19.076,"longitude":72.877},"radius":500}}}'
# must return 403 "Requests from referer ... are blocked"

Widening is not the same as opening. Prove the difference.


One key is rarely enough

A Capacitor app draws maps two different ways, and they need different keys:

SurfaceRendererKey
"Your Map" immersive — on native@capacitor/google-maps native SDKNEXT_PUBLIC_GOOGLE_MAPS_IOS_API_KEY
Onboarding location picker, LiveMap — on native@capacitor/google-maps native SDKNEXT_PUBLIC_GOOGLE_MAPS_IOS_API_KEY
Either surface — on web (browser tab, npm run dev)Maps JS in the pageNEXT_PUBLIC_GOOGLE_MAPS_BROWSER_API_KEY

"It is the iPhone app, so the iOS key covers it" is the wrong instinct and cost this incident — but so is "the onboarding picker is Maps JS, so it always wants the browser key": that was true until the picker was moved onto the native SDK too, precisely because the browser JS SDK is rejected inside the App:// WKWebView. Both map surfaces now key off isNative(), not off which surface they are — read hushh-webapp/lib/one-location/maps-config.ts and the isNative() branch in location-picker-map.tsx / location-immersive-map.tsx before assuming which key a surface uses, rather than trusting this table's surface names alone.

Restrict each key to only the services its surface calls. The browser key needs maps-backend (Maps JS), places (the picker's Place.searchNearby nearest-place lookup — this key deliberately has no classic Geocoding API), and routes.


Verifying a native build for real

A green workflow does not prove the intended configuration landed in the app. Use .agents/skills/mobile-native/SKILL.md for the selected-profile build, native Firebase sync, and bundled backend/project verification. Reuse the existing native environment resolver; do not manually copy another lane's Firebase file or pass credential values through command arguments.

The run-ios-sim compatibility entrypoint launches in the background and verifies the built backend before installation. Select APP_RUNTIME_PROFILE=dev for private-branch dev validation; its historical default is UAT.

For authenticated screens, follow .agents/skills/reviewer-app-testing/SKILL.md. The canonical reviewer harness can perform authorized authentication and continuity checks while keeping credentials in memory. Build/launch proof, authenticated journeys and actual provider success remain separate evidence.


What "verified" means here

Do not report a client credential as fixed on the strength of the secret existing. Show:

  • the value is present in each lane that needs it (check.sh);
  • the key accepts each origin and service (check-key-origins.sh);
  • the key still rejects an unknown origin (the 403 above);
  • the selected native configuration is verified in the built bundle;
  • for a native change, that the next build is what carries it — Capacitor has no over-the-air update, so a merged fix reaches a tester only through a new build.

Related: run-ios-sim, mobile-bug-log, safe-changes, hushh-research-ship.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.