README

NyrA Mobile Bridge Worker

This Worker is the durable hosted replacement for the temporary local/tunnel mobile bridge. It exposes the same /api/nyra/* route contract already used by the Android and browser surfaces, so phones can keep using NyrA chat, provider status, app updates, realtime setup, audio fallback, and support-log upload after the development PC is offline.

Local Checks

npm run cloud:mobile-bridge:check
npm run test:cloud-mobile-bridge
npm run cloud:mobile-bridge:bootstrap -- --dry-run --skip-secrets --skip-deploy

Deploy Path

1. Create or confirm the Cloudflare account and route for the hosted bridge, for example https://bridge.porterlabz.com.
2. Run the bootstrap dry run and inspect docs/launch_command_center/MOBILE_BRIDGE_CLOUD_BOOTSTRAP.md.
3. Confirm the nyra-swarm-memory D1 database exists. The production SWARM_DB binding in wrangler.jsonc must point to it.
4. Run the full bootstrap after Wrangler is authenticated. It applies all D1 migrations before deploying:

npm run cloud:mobile-bridge:bootstrap -- --worker-url=https://bridge.porterlabz.com --write-state

1. Only the full bootstrap can update command-center deployment facts. Dry runs never write stable bridge values into command-center-state.json, even if --write-state is passed.
2. A full bootstrap runs post-deploy verification before writing state: /health, authenticated status, update metadata, APK HEAD, support-log upload/list/readback, and a live chat smoke must pass.
3. If secrets already exist in Cloudflare, use --skip-secrets and set only missing secrets manually.
4. Replace the production bucket_name values only if the deployed bucket names differ.
5. Save the deployed bridge URL in the command center and in Android build/runtime settings.
6. Run a phone self-test from Settings > Updates > Bridge self-test.

The bootstrap creates the support-log and Android-release R2 buckets when needed, uploads the current signed APK to R2, writes non-secret Worker vars for the current APK SHA/version, and can deploy the Worker. It never writes raw bridge/provider secrets to reports, dashboard state, configs, or source files.

Routing Learning Storage

SWARM_DB is a D1 binding for tenant-scoped adaptive routing outcomes. Each authenticated account gets an irreversible SHA-256 tenant identifier. NyrA retains up to seven days of task category, provider, model, success/failure, latency, token counts, and an outcome code so future Worker isolates can choose better routes from measured results.

The table does not store prompts, answers, transcripts, email addresses, screenshots, files, API keys, bridge tokens, or other user content. GET /api/nyra/status reports routingLearning.storage: d1, durable: true, and storesUserContent: false when durable learning is active. If D1 is unavailable, chat remains fail-open with isolated in-memory routing evidence and status reports the degraded storage state.

For a manual production migration and deploy:

npm run cloud:mobile-bridge:migrate
npm run cloud:mobile-bridge:deploy

Secret Setup

npx wrangler secret put NYRA_MOBILE_BRIDGE_TOKEN --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_OPENAI_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_ANTHROPIC_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_GEMINI_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_GROK_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_LICENSE_SIGNING_SECRET --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_ANDROID_DOWNLOAD_TICKET_SECRET --cwd cloud/mobile-bridge-worker --env production

Routes

• GET /health: public structural health check with storage/auth configuration only.
• GET /api/nyra/model-policy/v2: current public cacheable quality-gated routing policy without credentials or user data.
• GET /api/nyra/model-policy: legacy policy URL retained for older clients.
• GET /api/nyra/status: authenticated provider readiness and hosted bridge status.
• POST /api/nyra/tester/enroll: authenticated allowlisted internal-tester device enrollment.
• GET /api/nyra/update/latest: authenticated Android update metadata.
• POST /api/nyra/update/android/download-ticket: authenticated short-lived Android APK download ticket for paid/device-token installs.
• GET /api/nyra/update/android/apk: authenticated Android APK download. Streams from the ANDROID_RELEASES R2 bucket when NYRA_ANDROID_UPDATE_APK_R2_KEY is set, or redirects to an absolute NYRA_ANDROID_UPDATE_APK_URL.
• HEAD /api/nyra/update/android/apk: authenticated APK metadata probe for phone self-tests without downloading the APK.
• POST /api/nyra/chat: authenticated swarm chat with Captain/Crew council routing for deeper prompts.
• POST /api/nyra/cancel: compatibility route. Hosted Workers are stateless per request, so this acknowledges but cannot cancel a completed fetch after the HTTP request is gone.
• POST /api/nyra/transcribe-audio: authenticated OpenAI transcription fallback.
• POST /api/nyra/tts-audio: authenticated OpenAI text-to-speech fallback.
• POST /api/nyra/realtime-client-secret: authenticated OpenAI realtime ephemeral secret setup.
• POST /api/nyra/logs: authenticated redacted support diagnostics upload to R2.
• GET /api/nyra/logs and GET /api/nyra/logs/:id: authenticated support-log listing/readback for Codex debugging.

No-Go Rules

• Do not deploy with ALLOW_DEV_OPEN_API=true in production.
• Do not ship a production Android build with a shared bridge token as customer authentication. Paid/customer builds must use the billing device access token plus short-lived APK download tickets.
• Do not store raw chats, API keys, card data, passwords, screenshots, or unrestricted transcripts in support logs.
• Do not claim phone/computer control is production-ready until Android accessibility, screen capture, and high-impact consent gates pass on the final build.

Deployment Checklist

NyrA Mobile Bridge Deployment Checklist

Preflight

• cloud/mobile-bridge-worker/wrangler.jsonc has nodejs_compat, observability, production ALLOWED_ORIGIN, the SUPPORT_LOGS and ANDROID_RELEASES R2 bindings, and the SWARM_DB D1 binding.
• The nyra-swarm-memory D1 database exists and 0001_tenant_routing_outcomes.sql is present.
• ALLOW_DEV_OPEN_API is false in production.
• NYRA_MOBILE_BRIDGE_TOKEN is set through Wrangler secrets.
• NYRA_LICENSE_SIGNING_SECRET matches the billing worker so paid device access tokens can authenticate to the bridge.
• NYRA_ANDROID_DOWNLOAD_TICKET_SECRET is set through Wrangler secrets for short-lived APK installer links.
• Provider secrets are set through Wrangler secrets: OpenAI, Anthropic, Gemini, and Grok/xAI.
• Android update metadata vars are set if this Worker is the hosted update source.
• The Android APK is either uploaded to the ANDROID_RELEASES R2 bucket with NYRA_ANDROID_UPDATE_APK_R2_KEY, or NYRA_ANDROID_UPDATE_APK_URL is an absolute external HTTPS URL.

Commands

npm run cloud:mobile-bridge:bootstrap -- --dry-run --skip-secrets --skip-deploy
npm run cloud:mobile-bridge:check
npx wrangler r2 bucket create nyra-mobile-support-logs
npx wrangler r2 bucket create nyra-android-releases
npx wrangler secret put NYRA_MOBILE_BRIDGE_TOKEN --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_OPENAI_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_ANTHROPIC_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_GEMINI_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_GROK_API_KEY --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_LICENSE_SIGNING_SECRET --cwd cloud/mobile-bridge-worker --env production
npx wrangler secret put NYRA_ANDROID_DOWNLOAD_TICKET_SECRET --cwd cloud/mobile-bridge-worker --env production
npm run cloud:mobile-bridge:migrate
npm run cloud:mobile-bridge:deploy

After Cloudflare authentication is working and secrets are available in environment variables, the preferred one-command path is:

npm run cloud:mobile-bridge:bootstrap -- --worker-url=https://bridge.porterlabz.com --write-state

Use --skip-secrets only when the Cloudflare Worker secrets have already been set manually. The bootstrap report is written to docs/launch_command_center/MOBILE_BRIDGE_CLOUD_BOOTSTRAP.md and docs/launch_command_center/mobile-bridge-cloud-bootstrap.json.

Dry runs are plan-only and cannot write deployment facts into docs/launch_command_center/command-center-state.json, even when --write-state is passed.

Full bootstrap state writes require post-deploy verification: /health, authenticated status, update manifest, APK HEAD, support-log roundtrip, and chat smoke.

Post-Deploy Verification

• GET /health returns service: nyra-mobile-bridge-api.
• GET /health reports storage.swarmRoutingD1: true.
• GET /api/nyra/status rejects missing tokens.
• GET /api/nyra/status with X-NyrA-Bridge-Token shows provider readiness without returning secret values.
• GET /api/nyra/status with a signed paid device access token succeeds without X-NyrA-Bridge-Token.
• Authenticated status reports routingLearning.storage: d1, durable: true, scope: tenant, and storesUserContent: false.
• A chat outcome remains available to the same tenant in a fresh Worker isolate and is absent from a different tenant.
• POST /api/nyra/chat returns text and provider/model route metadata.
• GET /api/nyra/update/latest returns the alpha version, version code, SHA, and APK route or absolute APK URL.
• POST /api/nyra/update/android/download-ticket returns a short-lived APK URL for Android installer handoff.
• GET /api/nyra/update/android/apk downloads an APK or redirects to the configured absolute APK URL.
• HEAD /api/nyra/update/android/apk returns APK content metadata for phone self-tests without a full download.
• POST /api/nyra/logs, GET /api/nyra/logs, and GET /api/nyra/logs/:id round-trip a redacted diagnostics bundle through R2.
• Android Settings > Updates bridge self-test reaches the deployed URL.