bleam 0.0.8 → 0.0.10

package/templates/updates/README.md

@@ -0,0 +1,272 @@
+# Bleam Update Service
+
+This Worker is the local proof for issues #14 and #15. It resolves public OTA
+and platform manifests from a local R2 simulation and serves release artifacts
+through opaque Bleam download URLs.
+
+It has no deployment command, no Cloudflare account ID, no remote binding, no
+publisher endpoint, and no authentication. Running it cannot create or mutate
+remote Cloudflare resources.
+
+## Local Development
+
+The normal app workflow does not require a separate update-service command.
+`bleam dev` starts the packaged Worker automatically at
+`http://127.0.0.1:8787`, waits for `/v1/health`, and stops the Worker when the
+owning dev session exits. If a healthy Worker is already running, it is reused
+and left running.
+
+Local R2 state and Worker logs persist globally at:
+
+```txt
+~/Library/Caches/bleam/updates/state
+~/Library/Caches/bleam/updates/worker.log
+```
+
+Use Wrangler directly only while developing the update service itself.
+Wrangler 4.110.0 or newer is required:
+
+```sh
+wrangler dev --config services/updates/wrangler.jsonc --local \
+  --persist-to services/updates/.wrangler/state
+```
+
+This repository-local R2 data lives under `services/updates/.wrangler/state`
+and is ignored by Git. Seed repository-local artifacts with Wrangler, always
+passing both `--local` and the same `--persist-to` directory:
+
+```sh
+wrangler r2 object put bleam-updates-local/releases/com.example.notes/ota/0.0.10.json \
+  --file release.json \
+  --local \
+  --persist-to services/updates/.wrangler/state \
+  --config services/updates/wrangler.jsonc
+```
+
+Run the end-to-end local proof with:
+
+```sh
+sh services/updates/scripts/smoke.sh
+```
+
+The smoke script creates temporary OTA and platform ZIP artifacts, seeds a
+temporary local R2 state directory, starts Wrangler on `127.0.0.1:8791`, and
+verifies both resolver routes, opaque artifact downloads, response hashes and
+sizes, and a missing-release `404`.
+
+Run the real CLI publication proof with:
+
+```sh
+sh services/updates/scripts/ota-e2e.sh
+```
+
+This starts an isolated local Worker/R2 instance, creates a temporary Bleam
+project, runs `bleam publish ota`, resolves and downloads the published release,
+verifies its SHA-256, and extracts its `bundle/bundle.js` payload.
+
+Publish a signed full-app platform archive from a configured project with:
+
+```sh
+bleam publish platform --service-url http://127.0.0.1:8787
+```
+
+This runs the standalone Release build, packages the signed app as
+`bleam-macos-app-zip-v1`, validates the declared bytes and SHA-256 through the
+local service, and activates the stable `macos-arm64` resolver record.
+
+With a configured Apple development team, run the full standalone lifecycle:
+
+```sh
+sh services/updates/scripts/ota-installed-e2e.sh
+```
+
+This builds and launches an isolated signed app, confirms an OTA download and
+next-launch activation, publishes a hash-valid broken bundle, and confirms the
+following launch rejects it and returns to the embedded bundle. It also verifies
+the app's per-user helper remains registered with launchd after the app quits.
+Finally, it publishes the signed app as a platform release, verifies and caches
+it through the dedicated helper, applies Update and Relaunch, checks the rollback
+backup and replacement receipt, validates the installed app and helper
+signatures, and confirms a moved copy cannot self-update.
+
+Before a release, run the same lifecycle with clean-state preflight and cleanup
+assertions:
+
+```sh
+sh services/updates/scripts/platform-release-readiness.sh
+```
+
+This refuses existing state for the isolated test identity and verifies the app,
+preferences, caches, helper copy, LaunchAgent, launchd registration, and update
+receipts are absent again after the lifecycle. A release still requires this
+check on a separate clean Mac; the local harness cannot substitute for fresh
+hardware and user-account validation.
+
+## Public API
+
+```text
+GET /v1/apps/:bundleIdentifier/ota/:runtimeVersion
+GET /v1/apps/:bundleIdentifier/platform/macos-arm64
+GET /v1/downloads/:downloadId
+POST /v1/local/releases/ota
+POST /v1/local/releases/platform
+```
+
+The POST routes are accepted only on `localhost` and exist solely for local
+publishing development. They validate the release record, artifact byte size,
+and SHA-256 before writing the immutable artifact and activating its matching
+resolver record.
+
+`bundleIdentifier` is the Bleam app identity. A release manifest always binds
+it to the Apple `teamIdentifier`; the Worker validates both from the stored
+record before it responds.
+
+Resolver responses are `Cache-Control: no-store` because release activation
+and future rollout decisions must remain server-controlled. Download IDs are
+immutable, so artifact responses are cacheable and use one-year immutable
+caching. The R2 object key is present only in the internal download record.
+
+## Manifest Contract
+
+### Terminology
+
+- An **OTA update** replaces the app's JavaScript bundle and assets without
+  replacing the installed `.app`.
+- A **platform update** replaces the complete signed `.app`, including the
+  Bleam runtime, helper, native APIs, and native dependencies.
+- The **runtime version** identifies the native environment required by an OTA
+  release. Compatibility is an exact string match.
+- A **release manifest** describes one immutable artifact. A **resolver record**
+  selects the currently active release for an app, channel, and target.
+- A release is **staged** after its artifact has been downloaded, verified, and
+  extracted. It becomes active on the next cold launch.
+
+Both release forms use `schemaVersion: 1`, `channel: "stable"`, a unique
+`releaseId`, `bundleIdentifier`, `teamIdentifier`, `publishedAt`, and an
+artifact containing its format, opaque `downloadId`, exact byte size, lowercase
+SHA-256 digest, and the resolver-provided download URL.
+
+OTA releases add `bundleVersion` and an exact `runtimeVersion`:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "ota",
+  "bundleIdentifier": "com.example.notes",
+  "teamIdentifier": "ABCDE12345",
+  "channel": "stable",
+  "releaseId": "ota_release_01",
+  "bundleVersion": "1.2.0+4",
+  "runtimeVersion": "0.0.10",
+  "artifact": {
+    "format": "bleam-ota-zip-v1",
+    "downloadId": "ota_release_01",
+    "url": "http://127.0.0.1:8787/v1/downloads/ota_release_01",
+    "sizeBytes": 1843921,
+    "sha256": "b6d25f9f844da5e5d810501774e5949760a5a45f32e4d8f449905c61d6a8d58d"
+  },
+  "publishedAt": "2026-07-12T16:00:00Z"
+}
+```
+
+Platform releases add signed-app identity and target metadata:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "platform",
+  "bundleIdentifier": "com.example.notes",
+  "teamIdentifier": "ABCDE12345",
+  "channel": "stable",
+  "releaseId": "platform_release_01",
+  "appVersion": "1.3.0",
+  "buildNumber": "5",
+  "bleamPlatformVersion": "0.0.10",
+  "platformFingerprint": "82a09a48ea84e66a65615e30f0f62b7c10f2d5137f4eafa67ca44d90bd9c8823",
+  "redeploy": false,
+  "target": {
+    "os": "macos",
+    "architecture": "arm64",
+    "installLocation": "user-applications",
+    "minimumMacOSVersion": "13.4"
+  },
+  "artifact": {
+    "format": "bleam-macos-app-zip-v1",
+    "downloadId": "platform_release_01",
+    "url": "http://127.0.0.1:8787/v1/downloads/platform_release_01",
+    "sizeBytes": 182743921,
+    "sha256": "ab851b776c2656b3725a31882ca8a9bf0e64ae508703a32cd4f8400eb1bdc6ec"
+  },
+  "publishedAt": "2026-07-12T16:00:00Z"
+}
+```
+
+### Platform Feed And Archive
+
+The initial platform feed is the stable, Apple-silicon resolver at
+`GET /v1/apps/:bundleIdentifier/platform/macos-arm64`. It returns only releases
+targeting `macos`, `arm64`, and the `user-applications` install location. The
+helper must reject a release whose app version is not semantic, whose build
+number is not decimal, or whose minimum macOS version exceeds the current OS.
+
+`platformFingerprint` is a deterministic SHA-256 over Bleam runtime identity
+and supported signed bundle inputs. It excludes developer TypeScript and
+ordinary OTA assets. Local publication rejects an unchanged fingerprint unless
+the manifest records an explicit `redeploy: true`; redeployment does not bypass
+artifact or installed-app verification. Legacy manifests without a fingerprint
+remain readable only so their next normal publication can establish one.
+
+`bleam-macos-app-zip-v1` is a ZIP containing exactly one top-level `app/`
+directory and exactly one complete `.app` beneath it:
+
+```text
+app/<display name>.app/
+```
+
+The archive must not contain another top-level entry, multiple app bundles,
+absolute paths, or entries that escape `app/` through `..` or symlink traversal.
+The helper extracts into the app-specific cache, never directly into
+`~/Applications`, and treats the extracted bundle as untrusted until checkpoint
+verification of SHA-256, bundle ID, team ID, app/build versions, architecture,
+and code signature succeeds. The release ID and artifact download ID are
+immutable; changing app bytes requires a new release and download ID.
+
+The R2 layout is internal:
+
+```text
+releases/<bundleIdentifier>/ota/<runtimeVersion>.json
+releases/<bundleIdentifier>/platform/macos-arm64.json
+downloads/<downloadId>.json
+artifacts/<private release path>
+```
+
+## Verification And Recovery
+
+Publication validates the manifest schema, declared artifact byte size, and
+SHA-256 before activating a resolver record. The app repeats size and SHA-256
+verification after download and rejects mismatched artifacts before extraction.
+Both release types bind the artifact to a bundle identifier and Apple team
+identifier. OTA releases additionally require the app's exact runtime version.
+
+OTA bundles are cached under
+`~/Library/Caches/Bleam/OTA/<bundleIdentifier>/<releaseId>/`. The active release
+ID is stored separately from the bundle so an incomplete download cannot become
+active. A staged release is selected only on a later cold launch and is marked
+as attempted before React Native starts.
+
+Startup is confirmed when React Native reports either JavaScript loading on the
+bridge runtime or root content appearing on Fabric. If the app exits or the
+bundle fails before confirmation, the next launch rejects that release, clears
+its active and attempted state, and loads the embedded `main.jsbundle`. A
+rejected release is not selected again while it remains the resolver's active
+release.
+
+Platform artifacts are downloaded and applied by the per-app helper. It verifies
+the artifact hash, archive layout, bundle and team identity, app and build
+versions, Bleam runtime and platform fingerprint, arm64 architecture, code
+signature, and minimum macOS version before replacement. Hosted authentication,
+ownership, entitlement, and deployment remain separate follow-up work.
+
+Standalone builds configured with `BLEAM_UPDATE_SERVICE_URL` check the matching
+OTA resolver after React starts. A verified release is cached for the next cold
+launch and follows the activation and recovery behavior above.

package/templates/updates/src/index.ts

@@ -0,0 +1,385 @@
+import {
+  compareRuntimeVersions,
+  type DownloadRecord,
+  isBundleIdentifier,
+  isDownloadId,
+  isRuntimeVersion,
+  parseDownloadRecord,
+  parsePublishedRelease,
+  parseStoredRelease,
+  resolveRelease,
+  type StoredRelease,
+} from './schema'
+
+interface StoredObject {
+  body: ReadableStream<Uint8Array>
+  httpEtag: string
+  size: number
+  text(): Promise<string>
+}
+
+interface UpdatesBucket {
+  get(key: string): Promise<StoredObject | null>
+  put(
+    key: string,
+    value: string | ArrayBuffer,
+    options?: { httpMetadata?: { contentType: string } },
+  ): Promise<unknown>
+}
+
+interface Env {
+  UPDATES: UpdatesBucket
+}
+
+const jsonHeaders = {
+  'content-type': 'application/json; charset=utf-8',
+  'cache-control': 'no-store',
+}
+
+function json(value: unknown, status = 200, method = 'GET') {
+  return new Response(method === 'HEAD' ? null : JSON.stringify(value), {
+    status,
+    headers: jsonHeaders,
+  })
+}
+
+function error(code: string, status: number, method: string) {
+  return json({ error: { code } }, status, method)
+}
+
+function notFound(method: string) {
+  return error('not_found', 404, method)
+}
+
+function unavailable(method: string) {
+  return error('invalid_release', 500, method)
+}
+
+function methodNotAllowed() {
+  return new Response(null, {
+    status: 405,
+    headers: { allow: 'GET, HEAD' },
+  })
+}
+
+function isLocalRequest(request: Request) {
+  const hostname = new URL(request.url).hostname
+  return hostname === '127.0.0.1' || hostname === 'localhost'
+}
+
+function base64Bytes(value: string) {
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index)
+  }
+  return bytes
+}
+
+async function sha256(bytes: Uint8Array) {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    bytes.buffer.slice(
+      bytes.byteOffset,
+      bytes.byteOffset + bytes.byteLength,
+    ) as ArrayBuffer,
+  )
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('')
+}
+
+async function publishLocalRelease(
+  request: Request,
+  bucket: UpdatesBucket,
+  expectedKind: StoredRelease['kind'],
+) {
+  if (!isLocalRequest(request)) return notFound(request.method)
+
+  let input: Record<string, unknown>
+  try {
+    input = (await request.json()) as Record<string, unknown>
+  } catch {
+    return error('invalid_request', 400, request.method)
+  }
+
+  if (typeof input.artifactBase64 !== 'string') {
+    return error('invalid_request', 400, request.method)
+  }
+
+  try {
+    const release = parsePublishedRelease(input.release)
+    if (release.kind !== expectedKind) {
+      return error('invalid_request', 400, request.method)
+    }
+    const artifact = base64Bytes(input.artifactBase64)
+    if (artifact.byteLength !== release.artifact.sizeBytes) {
+      return error('invalid_request', 400, request.method)
+    }
+    if ((await sha256(artifact)) !== release.artifact.sha256) {
+      return error('invalid_request', 400, request.method)
+    }
+
+    const releaseKey =
+      release.kind === 'ota'
+        ? `releases/${release.bundleIdentifier}/ota/${release.runtimeVersion}.json`
+        : `releases/${release.bundleIdentifier}/platform/macos-arm64.json`
+    if (release.kind === 'platform') {
+      const currentValue = await readStoredJson(bucket, releaseKey)
+      const current = currentValue
+        ? parseStoredRelease(currentValue)
+        : undefined
+      const unchanged =
+        current?.kind === 'platform' &&
+        current.platformFingerprint !== undefined &&
+        current.platformFingerprint === release.platformFingerprint
+      if (
+        current?.kind === 'platform' &&
+        compareRuntimeVersions(
+          release.bleamPlatformVersion,
+          current.bleamPlatformVersion,
+        ) < 0
+      ) {
+        return error('platform_downgrade', 409, request.method)
+      }
+      if (unchanged && !release.redeploy) {
+        return error('platform_unchanged', 409, request.method)
+      }
+      if (!unchanged && release.redeploy) {
+        return error('redeploy_not_required', 400, request.method)
+      }
+    }
+
+    const artifactKey = `artifacts/${release.kind}/${release.artifact.downloadId}.zip`
+    const download: DownloadRecord = {
+      schemaVersion: 1,
+      downloadId: release.artifact.downloadId,
+      artifactKey,
+      contentType: 'application/zip',
+    }
+    await bucket.put(artifactKey, artifact.buffer, {
+      httpMetadata: { contentType: 'application/zip' },
+    })
+    await bucket.put(
+      `downloads/${download.downloadId}.json`,
+      JSON.stringify(download),
+      { httpMetadata: { contentType: 'application/json' } },
+    )
+    await bucket.put(releaseKey, JSON.stringify(release), {
+      httpMetadata: { contentType: 'application/json' },
+    })
+    return json(
+      resolveRelease(
+        release,
+        new URL(`/v1/downloads/${download.downloadId}`, request.url).toString(),
+      ),
+      201,
+    )
+  } catch {
+    return error('invalid_request', 400, request.method)
+  }
+}
+
+function decodedSegment(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return undefined
+  }
+}
+
+async function readStoredJson(bucket: UpdatesBucket, key: string) {
+  const object = await bucket.get(key)
+  if (!object) return undefined
+
+  try {
+    return JSON.parse(await object.text()) as unknown
+  } catch {
+    return undefined
+  }
+}
+
+function releaseResponse(
+  release: StoredRelease,
+  request: Request,
+  method: string,
+) {
+  const artifactUrl = new URL(
+    `/v1/downloads/${release.artifact.downloadId}`,
+    request.url,
+  ).toString()
+  return json(resolveRelease(release, artifactUrl), 200, method)
+}
+
+async function resolveOta(
+  bucket: UpdatesBucket,
+  request: Request,
+  bundleIdentifier: string,
+  runtimeVersion: string,
+  method: string,
+) {
+  if (
+    !isBundleIdentifier(bundleIdentifier) ||
+    !isRuntimeVersion(runtimeVersion)
+  ) {
+    return notFound(method)
+  }
+
+  const stored = await readStoredJson(
+    bucket,
+    `releases/${bundleIdentifier}/ota/${runtimeVersion}.json`,
+  )
+  if (!stored) return notFound(method)
+
+  try {
+    const release = parseStoredRelease(stored)
+    if (
+      release.kind !== 'ota' ||
+      release.bundleIdentifier !== bundleIdentifier ||
+      release.runtimeVersion !== runtimeVersion
+    ) {
+      return unavailable(method)
+    }
+    return releaseResponse(release, request, method)
+  } catch {
+    return unavailable(method)
+  }
+}
+
+async function resolvePlatform(
+  bucket: UpdatesBucket,
+  request: Request,
+  bundleIdentifier: string,
+  target: string,
+  method: string,
+) {
+  if (!isBundleIdentifier(bundleIdentifier) || target !== 'macos-arm64') {
+    return notFound(method)
+  }
+
+  const stored = await readStoredJson(
+    bucket,
+    `releases/${bundleIdentifier}/platform/${target}.json`,
+  )
+  if (!stored) return notFound(method)
+
+  try {
+    const release = parseStoredRelease(stored)
+    if (
+      release.kind !== 'platform' ||
+      release.bundleIdentifier !== bundleIdentifier ||
+      `${release.target.os}-${release.target.architecture}` !== target
+    ) {
+      return unavailable(method)
+    }
+    return releaseResponse(release, request, method)
+  } catch {
+    return unavailable(method)
+  }
+}
+
+async function downloadArtifact(
+  bucket: UpdatesBucket,
+  downloadId: string,
+  method: string,
+) {
+  if (!isDownloadId(downloadId)) return notFound(method)
+
+  const stored = await readStoredJson(bucket, `downloads/${downloadId}.json`)
+  if (!stored) return notFound(method)
+
+  let download: DownloadRecord
+  try {
+    download = parseDownloadRecord(stored)
+  } catch {
+    return unavailable(method)
+  }
+
+  if (download.downloadId !== downloadId) return unavailable(method)
+
+  const artifact = await bucket.get(download.artifactKey)
+  if (!artifact) return notFound(method)
+
+  const headers = new Headers({
+    'content-type': download.contentType,
+    'cache-control': 'public, max-age=31536000, immutable',
+    etag: artifact.httpEtag,
+    'content-length': String(artifact.size),
+  })
+  return new Response(method === 'HEAD' ? null : artifact.body, {
+    status: 200,
+    headers,
+  })
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+    if (request.method === 'GET' && url.pathname === '/v1/health') {
+      return json({ healthy: true })
+    }
+    if (
+      request.method === 'POST' &&
+      url.pathname === '/v1/local/releases/ota'
+    ) {
+      return publishLocalRelease(request, env.UPDATES, 'ota')
+    }
+    if (
+      request.method === 'POST' &&
+      url.pathname === '/v1/local/releases/platform'
+    ) {
+      return publishLocalRelease(request, env.UPDATES, 'platform')
+    }
+
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      return methodNotAllowed()
+    }
+
+    const path = url.pathname.split('/').filter(Boolean)
+    const method = request.method
+
+    if (
+      path.length === 5 &&
+      path[0] === 'v1' &&
+      path[1] === 'apps' &&
+      path[3] === 'ota'
+    ) {
+      const bundleIdentifier = decodedSegment(path[2])
+      const runtimeVersion = decodedSegment(path[4])
+      if (!bundleIdentifier || !runtimeVersion) return notFound(method)
+      return resolveOta(
+        env.UPDATES,
+        request,
+        bundleIdentifier,
+        runtimeVersion,
+        method,
+      )
+    }
+
+    if (
+      path.length === 5 &&
+      path[0] === 'v1' &&
+      path[1] === 'apps' &&
+      path[3] === 'platform'
+    ) {
+      const bundleIdentifier = decodedSegment(path[2])
+      const target = decodedSegment(path[4])
+      if (!bundleIdentifier || !target) return notFound(method)
+      return resolvePlatform(
+        env.UPDATES,
+        request,
+        bundleIdentifier,
+        target,
+        method,
+      )
+    }
+
+    if (path.length === 3 && path[0] === 'v1' && path[1] === 'downloads') {
+      const downloadId = decodedSegment(path[2])
+      if (!downloadId) return notFound(method)
+      return downloadArtifact(env.UPDATES, downloadId, method)
+    }
+
+    return notFound(method)
+  },
+}