[hedge-mustafa]

Why

Mobile apps built with halvorai_ingest_flutter sign events on the phone, with a key each install makes for itself. The app never holds an API key. The customer's backend has two jobs:

• register each install's public key
• forward its signed batches to HalvorAI unchanged

This PR adds that backend half: items SDK-1 to SDK-3 in the Flutter backend requirements. The API-side items are separate. The same change is going into the other server SDK (halvorAI/ingest-python) so both behave the same.

App ──public key──▶ customer backend ──POST /v1/sources──▶ HalvorAI      (once per install)
App ──signed batch──▶ customer backend ──byte for byte──▶ HalvorAI /v1/events

What's added: @halvorai/ingest/device (0.4.0)

• registerDeviceSource:
  • Accepts only the public half of an Ed25519 key, and refuses a key with d.
  • Sends only kty, crv and x to POST /v1/sources, and returns the src_ id.
  • If HalvorAI doesn't register the key, the answer is 502, so the app retries.
• forwardEnvelopes:
  • Checks the batch shape, at most 100 envelopes and at most 1 MB.
  • Checks that each event's owner.id is the signed-in user, and that its environment matches the API key.
  • Posts the original body to POST /v1/events byte for byte. It's parsed only for the checks, because re-serializing could change bytes the device signed.
  • Returns HalvorAI's status and body unchanged; the app reads its per-event results from them.
• deviceRoutes: both as Fetch API handlers (Request → Response) for Next.js route handlers, Hono, Bun and Workers. The README also shows an Express version, using express.raw() so the body is never re-serialized.

Refusals use HalvorAI's error format ({"error":{"code","message"}}), so the Flutter SDK reports the code as serverCode. The status tells the app what to do:

Status	Code	The app
400	invalid_request	drops the batch
413	payload_too_large	splits the batch
422	owner_mismatch, environment_mismatch	drops the batch
502	upstream_error (HalvorAI unreachable)	retries
401 / 403	(the customer's own session check)	keeps the batch on disk, retries later

init now registers its source through the same code (src/sources.ts). Its messages are unchanged, except that a network failure now reads POST /v1/sources failed: <reason>.

Tested

• npm run typecheck, npm test (251 tests, 22 new), npm run build and npm run smoke (imports @halvorai/ingest/device from the packed tarball).

• End to end with the Dart SDK. A local backend built from these helpers sat in front of a fake HalvorAI, which verifies every forwarded signature against the key registered for its source. The client was halvorai_ingest (Dart), doing exactly what the Flutter package does: registering per the provisioning contract and delivering through ForwardingTransport. Results:

  • Registration returns a src_ id; a private key is refused with 400.
  • Three signed events are forwarded and all three signatures verify upstream (the fake rejects a tampered event).
  • Events naming another owner are refused, 422 owner_mismatch.
  • Without a session the app gets 401 and keeps the events on disk.

  The same run passes against the other SDK's helpers.

Not in this PR

• API side:
  • registration idempotent per public key (the app may retry with the same key after a lost response)
  • kind: "device" and paging for many sources
  • DELETE /v1/sources/{id}
  • a restricted key scope
• revokeDeviceSource (SDK-5): waits for that DELETE endpoint.
• Optional signature check before forwarding: HalvorAI checks signatures anyway.
• The fix-list items: the card number next to other digits, the CVC, and the environment and unconfirmed rules. They aren't needed for Flutter to work, and are a separate change.

Please don't merge until it has been reviewed.

🤖 Generated with Claude Code

[hedge-urk]

Forwarding interoperability bug — preserve bodyless HTTP responses.

In src/device/handlers.ts, deviceRoutes.forward always does new Response(result.body, {status: result.status, ...}). forwardEnvelopes can legitimately return a 204 from HalvorAI with body: '' (and likewise 205). In the Fetch API, new Response('', { status: 204 }) throws TypeError: Invalid response status code 204; these statuses require a null body, not an empty string. That turns a successful upstream delivery into an exception/500 seen by the app, potentially causing retries and duplicate observations rather than preserving the original response as promised.

Please use null for statuses that prohibit a body (204, 205, 304), preserve the response status, and add a deviceRoutes.forward regression test for a 204 response. I verified the 204 case with Node's native Response constructor.

[hedge-mustafa]

Fixed in 476f5fc. deviceRoutes.forward now uses a null body for 204, 205 and 304 and keeps the status. Added regression tests for a bodyless 204 and 205 from HalvorAI; both failed before the fix.

[hedge-urk]

gtg