Basic EvenHub store compatibility

This commit is contained in:
James Babcock committed 2026-08-16 20:59:42 -07:00
1 parent dfcce49756
commit cde29cc4d0
5 files changed
+619 -6

No files matched your search

+327
View File
@@ -0,0 +1,327 @@
/**
* Client for the private storefront endpoints used by the official Even app.
*
* This is intentionally separate from the EvenHub JS compatibility bridge:
* it only discovers and downloads public .ehpk packages. Authentication is
* the same signed-header scheme used by the firmware API.
*/
import {
evenHubEmailSetting,
evenHubOpenUdidSetting,
evenHubPasswordSetting,
} from "../../ui/dashboard-settings";
declare const android: any;
const API_HOST = "https://api.evenrealities.com";
const SIGN_KEY = "a7964f42c39200cfa25c258b7a311b106e20232173667e543c34ced91d63b404";
const REQUEST_TIMEOUT_MS = 30_000;
export type EvenHubStoreApp = {
id: number;
packageId: string;
name: string;
creatorName: string;
tagline: string;
description: string;
categories: string[];
installCount: number;
likeCount: number;
firstPublishedAt: string;
};
export type EvenHubStorePage = {
apps: EvenHubStoreApp[];
total: number;
page: number;
pageSize: number;
};
type ApiEnvelope = {
code?: number;
msg?: string;
data?: unknown;
};
type DownloadMetadata = {
url?: unknown;
size?: unknown;
public_key?: unknown;
};
export function isEvenHubStoreConfigured(): boolean {
return Boolean(
evenHubEmailSetting.get().trim() &&
evenHubPasswordSetting.get() &&
evenHubOpenUdidSetting.get().trim(),
);
}
export class EvenHubApiClient {
private token = "";
private loginPromise: Promise<string> | null = null;
async listApps(page = 1, category = ""): Promise<EvenHubStorePage> {
const query: Record<string, string | number> = { page, page_size: 40 };
if (category) query.category = category;
const data = await this.authenticatedRequest("GET", "/v2/evenhub/leaderboard", { query });
const root = asRecord(data);
const list = Array.isArray(root.list) ? root.list : [];
return {
apps: list.map(parseStoreApp).filter((app): app is EvenHubStoreApp => app !== null),
total: finiteNumber(root.total),
page: finiteNumber(root.page) || page,
pageSize: finiteNumber(root.page_size) || 40,
};
}
async getAppDetail(packageId: string): Promise<Record<string, unknown>> {
const data = await this.authenticatedRequest("GET", "/v2/evenhub/app/detail", {
query: { package_id: packageId, branch_name: "public" },
});
return asRecord(data);
}
/** Resolve the signed download URL, then fetch and sanity-check its EHPK. */
async downloadApp(packageId: string): Promise<Uint8Array> {
const data = await this.authenticatedRequest("POST", "/v2/evenhub/app/download", {
body: { package_id: packageId, branch: "public" },
});
const metadata = asRecord(data) as DownloadMetadata;
const url = typeof metadata.url === "string" ? metadata.url : "";
if (!url.startsWith("https://")) throw new Error("EvenHub returned no package download URL.");
const response = await fetchWithTimeout(url, {}, 60_000);
if (!response.ok) throw new Error(`EvenHub package download failed (HTTP ${response.status}).`);
const bytes = new Uint8Array(await response.arrayBuffer());
const expectedSize = finiteNumber(metadata.size);
if (expectedSize > 0 && bytes.length !== expectedSize) {
throw new Error(`EvenHub package was truncated (${bytes.length} of ${expectedSize} bytes).`);
}
if (bytes.length < 20 || bytes[0] !== 0x45 || bytes[1] !== 0x48 || bytes[2] !== 0x50 || bytes[3] !== 0x4b) {
throw new Error("EvenHub download is not an EHPK package.");
}
return bytes;
}
clearSession(): void {
this.token = "";
this.loginPromise = null;
}
private async authenticatedRequest(
method: "GET" | "POST",
path: string,
options: { query?: Record<string, string | number>; body?: Record<string, unknown> } = {},
): Promise<unknown> {
let token = await this.ensureLogin();
let response = await this.request(method, path, { ...options, token, commonVersion: 3 });
if (response.httpStatus === 401) {
this.clearSession();
token = await this.ensureLogin();
response = await this.request(method, path, { ...options, token, commonVersion: 3 });
}
return unwrap(response.envelope, response.httpStatus, path);
}
private ensureLogin(): Promise<string> {
if (this.token) return Promise.resolve(this.token);
if (!isEvenHubStoreConfigured()) {
return Promise.reject(new Error("Set the EvenHub email, password, and phone openUdid in Settings > EvenHub."));
}
if (!this.loginPromise) {
this.loginPromise = this.login().finally(() => {
this.loginPromise = null;
});
}
return this.loginPromise;
}
private async login(): Promise<string> {
const response = await this.request("POST", "/v2/g/login", {
commonVersion: 1,
body: { email: evenHubEmailSetting.get().trim(), passwd: evenHubPasswordSetting.get() },
});
const data = asRecord(unwrap(response.envelope, response.httpStatus, "/v2/g/login"));
const token = typeof data.token === "string" ? data.token : "";
if (!token) throw new Error("Even login succeeded without returning a session token.");
this.token = token;
return token;
}
private async request(
method: "GET" | "POST",
path: string,
options: {
commonVersion: 1 | 3;
query?: Record<string, string | number>;
body?: Record<string, unknown>;
token?: string;
},
): Promise<{ httpStatus: number; envelope: ApiEnvelope }> {
const common = buildCommon(options.commonVersion);
const query = encodePairs(options.query ?? {});
const body = options.body ? JSON.stringify(options.body) : "";
const token = options.token ?? "";
const headers: Record<string, string> = {
common,
sign: hmacSign(signingParts(method, path, common, query, token, body)),
"Content-Type": "application/json",
};
if (token) headers.token = token;
const response = await fetchWithTimeout(`${API_HOST}${path}${query ? `?${query}` : ""}`, {
method,
headers,
body: body || undefined,
});
let envelope: ApiEnvelope = {};
try {
envelope = (await response.json()) as ApiEnvelope;
} catch {
// unwrap() below will turn this into a useful status-only error.
}
return { httpStatus: response.status, envelope };
}
}
export const evenHubApi = new EvenHubApiClient();
/** Exported for deterministic unit/probe comparison without exposing secrets. */
export function signingParts(
method: string,
path: string,
common: string,
query = "",
token = "",
body = "",
): string {
const parts = [method.toUpperCase(), path, common];
if (query) parts.push(normalizeQuery(query));
if (token) parts.push(token);
if (body) parts.push(body);
return parts.sort().join("\n");
}
function buildCommon(version: 1 | 3): string {
const fields: Record<string, string | number> = {
platform: "16",
package: "com.even.sg",
versionName: "2.2.6",
build: "114",
brand: "Google",
model: "Pixel 7a",
osVersion: "16",
carrier: "",
mcc: "310",
mnc: "260",
buildTime: "26060821",
appId: "1001",
v: version,
openUdid: evenHubOpenUdidSetting.get().trim(),
os: "1",
sn: "",
verL: "",
verR: "",
ringSn: "",
ringVer: "",
channel: "googlePlay",
sttLanguage: "",
sysLanguage: "US",
ts: new Date().toISOString(),
language: "en",
tzName: "America/Los_Angeles",
dateFmt: "yyyy/MM/dd",
timeFmt: "24",
unit: "metrics",
region: "US",
};
// `common` field order matches the official client; unlike queries it must
// not be sorted because the raw serialized value participates in signing.
return Object.entries(fields).map(([key, value]) => `${formEncode(key)}=${formEncode(String(value))}`).join("&");
}
function encodePairs(values: Record<string, string | number>): string {
return Object.entries(values)
.sort(([a], [b]) => a.localeCompare(b))
.map(([key, value]) => `${formEncode(key)}=${formEncode(String(value))}`)
.join("&");
}
function normalizeQuery(query: string): string {
return query
.split("&")
.filter(Boolean)
.sort((a, b) => a.split("=", 1)[0]!.localeCompare(b.split("=", 1)[0]!))
.join("&");
}
function formEncode(value: string): string {
return encodeURIComponent(value).replace(/%20/g, "+");
}
function hmacSign(message: string): string {
if (!global.isAndroid) throw new Error("The EvenHub storefront is currently available only on Android.");
const charset = java.nio.charset.StandardCharsets.UTF_8;
const key = new javax.crypto.spec.SecretKeySpec(new java.lang.String(SIGN_KEY).getBytes(charset), "HmacSHA256");
const mac = javax.crypto.Mac.getInstance("HmacSHA256");
mac.init(key);
const digest = mac.doFinal(new java.lang.String(message).getBytes(charset));
return String(android.util.Base64.encodeToString(digest, android.util.Base64.NO_WRAP));
}
async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs = REQUEST_TIMEOUT_MS): Promise<Response> {
let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
const timeout = new Promise<never>((_resolve, reject) => {
timeoutHandle = setTimeout(() => reject(new Error("EvenHub request timed out.")), timeoutMs);
});
try {
return await Promise.race([fetch(url, init), timeout]);
} finally {
if (timeoutHandle) clearTimeout(timeoutHandle);
}
}
function unwrap(envelope: ApiEnvelope, httpStatus: number, path: string): unknown {
if (httpStatus === 401) {
throw new Error("Even rejected the login session or phone openUdid. Check Settings > EvenHub.");
}
if (httpStatus < 200 || httpStatus >= 300) {
throw new Error(`EvenHub request failed (HTTP ${httpStatus}, ${path}).`);
}
if (envelope.code !== 0) {
const detail = typeof envelope.msg === "string" && envelope.msg ? `: ${envelope.msg}` : "";
throw new Error(`EvenHub API error ${envelope.code ?? "unknown"}${detail}`);
}
return envelope.data;
}
function parseStoreApp(value: unknown): EvenHubStoreApp | null {
const item = asRecord(value);
const packageId = stringValue(item.package_id);
if (!packageId) return null;
return {
id: finiteNumber(item.id),
packageId,
name: stringValue(item.name) || packageId,
creatorName: stringValue(item.creator_name),
tagline: stringValue(item.tagline),
description: stringValue(item.description),
categories: Array.isArray(item.category) ? item.category.map(stringValue).filter(Boolean) : [],
installCount: finiteNumber(item.install_count),
likeCount: finiteNumber(item.like_count),
firstPublishedAt: stringValue(item.first_published_at),
};
}
function asRecord(value: unknown): Record<string, any> {
return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, any>) : {};
}
function stringValue(value: unknown): string {
return typeof value === "string" ? value : value == null ? "" : String(value);
}
function finiteNumber(value: unknown): number {
const number = Number(value);
return Number.isFinite(number) ? number : 0;
}
+30 -6
View File
@@ -19,8 +19,12 @@ import {
import { parseEhpk, parseManifest, utf8Decode } from "./ehpk";
import { EvenHubSession } from "./session";
import { createEvenHubWindow } from "./evenhub-window";
import { EvenHubStoreLayer } from "./store-layer";
import { createInProcessWindow, type InProcessWindow } from "../../ui/shell/in-process-window";
const EVENHUB_WINDOW_ID = "evenhub:app";
const EVENHUB_STORE_WINDOW_ID = "evenhub:store";
const EVENHUB_STORE_SURFACE_ID = "window:evenhub:store";
let activeSession: EvenHubSession | null = null;
@@ -77,17 +81,37 @@ const evenhubApp: AppDefinition = {
appId: "evenhub",
title: "EvenHub",
icon: "package",
// Launching happens by opening an .ehpk in Files; the grid entry would
// have nothing to open.
showInLauncher: false,
launch: async (ctx) => {
const existing = shell.getWindows().find((window) => window.appId === "evenhub");
const existing = shell.getWindows().find((window) => window.windowId === EVENHUB_STORE_WINDOW_ID);
if (existing) {
shell.focusWindow(existing.windowId);
ctx.requestShellRender();
} else {
ctx.appendLog("EvenHub apps launch from .ehpk files in the Files app");
return;
}
let created: InProcessWindow | null = null;
const store = new EvenHubStoreLayer({
openPackage: (path) => openEvenHubPackage(ctx, path),
openSettings: () => ctx.launchApp("settings", { section: "EvenHub" }),
appendLog: ctx.appendLog,
});
await ctx.launchInProcessApp(EVENHUB_STORE_WINDOW_ID, EVENHUB_STORE_SURFACE_ID, (options) => {
created = createInProcessWindow({
appId: "evenhub",
windowId: EVENHUB_STORE_WINDOW_ID,
title: "EvenHub",
iconLetter: "EH",
icon: "package",
closeable: true,
menuItems: () => (created?.stack.isAtBase() ? store.buildMenuItems() : []),
actions: options.actions,
baseLayer: store,
submitFrame: options.submitFrame,
setSurfaceVisible: options.setSurfaceVisible,
removeSurface: options.removeSurface,
onClosed: options.onClosed,
});
return created;
});
},
};
+213
View File
@@ -0,0 +1,213 @@
import { getDefaultSmallFont } from "../../graphics/bdffont";
import { GrayImage } from "../../graphics/image";
import { truncateText } from "../../graphics/textwrap";
import { clamp } from "../../util/numeric-util";
import { GESTURE_CLICK, GESTURE_DOUBLE_CLICK, GESTURE_SCROLL } from "../../ui/gestures";
import { type DashboardInputEvent, type Layer, type LayerContext } from "../../ui/layers";
import {
drawListScrollbar,
drawSelectionHighlight,
scrollToKeepSelectionVisible,
type MenuItem,
} from "../../ui/menu";
import { shell } from "../../ui/shell/shell";
import { appFilesDirPath, writeBinaryFile } from "../../native/file-access";
import { evenHubApi, isEvenHubStoreConfigured, type EvenHubStoreApp } from "./even-api";
const HEADER_HEIGHT = 34;
const FOOTER_HEIGHT = 22;
const ROW_HEIGHT = 30;
const LIST_X = 18;
export type EvenHubStoreLayerOptions = {
openPackage: (path: string) => Promise<void> | void;
openSettings: () => Promise<void> | void;
appendLog: (message: string) => void;
};
/** Browse the public EvenHub leaderboard and download one package to run. */
export class EvenHubStoreLayer implements Layer {
private apps: EvenHubStoreApp[] = [];
private selectedIndex = 0;
private scrollRow = 0;
private total = 0;
private nextPage = 1;
private started = false;
private loading = false;
private downloadingPackageId = "";
private status = "";
constructor(private readonly options: EvenHubStoreLayerOptions) {}
paint(ctx: LayerContext): GrayImage {
if (!this.started) {
this.started = true;
void this.reload(ctx);
}
const font = getDefaultSmallFont();
const { width, height } = ctx.stack.getBaseSize();
const image = new GrayImage(width, height, 0);
image.drawText(font, LIST_X, 8, "EvenHub", 220);
const subtitle = !isEvenHubStoreConfigured()
? "Set account details in Settings > EvenHub"
: this.status || (this.total ? `${this.apps.length} of ${this.total} public apps` : "Public apps");
image.drawText(font, LIST_X, 22, truncateText(font, subtitle, width - LIST_X * 2), 125);
if (this.apps.length === 0) {
const message = this.loading ? "Loading apps..." : this.status || "No apps returned.";
image.drawText(font, LIST_X, HEADER_HEIGHT + 28, truncateText(font, message, width - LIST_X * 2), 190);
} else {
this.selectedIndex = clamp(this.selectedIndex, 0, this.apps.length - 1);
const visibleRows = Math.max(1, Math.floor((height - HEADER_HEIGHT - FOOTER_HEIGHT) / ROW_HEIGHT));
this.scrollRow = scrollToKeepSelectionVisible(
this.scrollRow,
this.selectedIndex,
visibleRows,
this.apps.length,
);
const last = Math.min(this.apps.length, this.scrollRow + visibleRows);
for (let index = this.scrollRow; index < last; index++) {
const app = this.apps[index]!;
const y = HEADER_HEIGHT + (index - this.scrollRow) * ROW_HEIGHT;
const selected = index === this.selectedIndex;
if (selected) {
drawSelectionHighlight(image, LIST_X - 6, y, width - LIST_X * 2 + 12, ROW_HEIGHT - 2, ctx.stack.isFocused(), 5);
}
const pending = app.packageId === this.downloadingPackageId;
const title = pending ? `${app.name} (downloading...)` : app.name;
image.drawText(font, LIST_X, y + 2, truncateText(font, title, width - LIST_X * 2), pending ? 255 : 215);
const detail = app.tagline || `${app.creatorName} · ${formatCount(app.installCount)} installs`;
image.drawText(font, LIST_X, y + 16, truncateText(font, detail, width - LIST_X * 2), 115);
}
if (this.apps.length > visibleRows) {
drawListScrollbar(image, width - 5, HEADER_HEIGHT, visibleRows * ROW_HEIGHT - 3, this.scrollRow, visibleRows, this.apps.length);
}
}
const hint = !isEvenHubStoreConfigured()
? `${GESTURE_CLICK} settings ${GESTURE_DOUBLE_CLICK} back`
: `${GESTURE_SCROLL} select ${GESTURE_CLICK} download & run ${GESTURE_DOUBLE_CLICK} back`;
image.drawText(font, LIST_X, height - 16, truncateText(font, hint, width - LIST_X * 2), 105);
return image;
}
async handleInput(event: DashboardInputEvent, ctx: LayerContext): Promise<void> {
switch (event.type) {
case "scroll-up":
this.selectedIndex = Math.max(0, this.selectedIndex - 1);
return;
case "scroll-down":
this.selectedIndex = Math.min(Math.max(0, this.apps.length - 1), this.selectedIndex + 1);
if (this.selectedIndex >= this.apps.length - 4 && this.apps.length < this.total) {
void this.loadNextPage(ctx);
}
return;
case "click":
if (!isEvenHubStoreConfigured()) {
await this.options.openSettings();
return;
}
if (!this.loading && !this.downloadingPackageId) {
const app = this.apps[this.selectedIndex];
if (app) await this.downloadAndRun(app, ctx);
}
return;
case "double-click":
shell.yieldFocusToSidebar();
return;
default:
return;
}
}
buildMenuItems(): MenuItem[] {
return [
{
label: "Refresh",
onSelect: (ctx) => {
ctx.stack.pop();
void this.reload(ctx);
},
},
{
label: "EvenHub settings",
onSelect: (ctx) => {
ctx.stack.pop();
void this.options.openSettings();
},
},
];
}
private async reload(ctx: LayerContext): Promise<void> {
if (this.loading) return;
evenHubApi.clearSession();
this.apps = [];
this.total = 0;
this.nextPage = 1;
this.selectedIndex = 0;
this.scrollRow = 0;
this.status = "";
if (!isEvenHubStoreConfigured()) {
ctx.actions.requestRender();
return;
}
await this.loadNextPage(ctx);
}
private async loadNextPage(ctx: LayerContext): Promise<void> {
if (this.loading || (this.total > 0 && this.apps.length >= this.total)) return;
this.loading = true;
this.status = this.apps.length ? "Loading more apps..." : "Loading apps...";
ctx.actions.requestRender();
try {
const page = await evenHubApi.listApps(this.nextPage);
const seen = new Set(this.apps.map((app) => app.packageId));
this.apps.push(...page.apps.filter((app) => !seen.has(app.packageId)));
this.total = page.total;
this.nextPage = page.page + 1;
this.status = "";
} catch (error) {
this.status = cleanError(error);
this.options.appendLog(`evenhub store: ${this.status}`);
} finally {
this.loading = false;
ctx.actions.requestRender();
}
}
private async downloadAndRun(app: EvenHubStoreApp, ctx: LayerContext): Promise<void> {
this.downloadingPackageId = app.packageId;
this.status = `Downloading ${app.name}...`;
ctx.actions.requestRender();
try {
const bytes = await evenHubApi.downloadApp(app.packageId);
const safeId = app.packageId.replace(/[^A-Za-z0-9._-]/g, "_");
const path = `${appFilesDirPath()}/evenhub-downloads/${safeId}.ehpk`;
if (!writeBinaryFile(path, bytes)) throw new Error("Could not save the downloaded EHPK package.");
this.options.appendLog(`evenhub store: downloaded ${app.packageId} (${bytes.length} bytes)`);
this.status = `Launching ${app.name}...`;
ctx.actions.requestRender();
await this.options.openPackage(path);
this.status = "";
} catch (error) {
this.status = cleanError(error);
this.options.appendLog(`evenhub store: ${this.status}`);
} finally {
this.downloadingPackageId = "";
ctx.actions.requestRender();
}
}
}
function cleanError(error: unknown): string {
return String((error as Error)?.message ?? error).replace(/[\x00-\x1f]+/g, " ").replace(/\s+/g, " ").trim();
}
function formatCount(value: number): string {
if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}m`;
if (value >= 1000) return `${(value / 1000).toFixed(value >= 10_000 ? 0 : 1)}k`;
return String(value);
}
+38
View File
@@ -497,6 +497,44 @@ export const mapboxApiKeySetting = new ConfigSettingString({
description: "Mapbox public token (pk. prefix), used by the Navigate app for maps, geocoding, and directions.",
});
export const evenHubEmailSetting = new ConfigSettingString({
id: "evenhub-email",
label: "Even account email",
storageKey: "integrations.evenhub.email",
defaultValue: "",
editorTitle: "Even Realities account email",
glassesEditTitle: "Edit Even email",
normalize: (value) => (value ?? "").replace(/[\x00-\x1f]+/g, "").trim(),
formatValue: emptySettingDisplay,
description: "Email for the Even account used to browse and download public EvenHub apps.",
});
export const evenHubPasswordSetting = new ConfigSettingString({
id: "evenhub-password",
label: "Even account password",
storageKey: "integrations.evenhub.password",
defaultValue: "",
editorTitle: "Even Realities account password",
glassesEditTitle: "Edit Even password",
normalize: (value) => (value ?? "").replace(/[\x00-\x1f]+/g, ""),
formatValue: (value) => (value ? "(set)" : "(not set)"),
description:
"Password used to mint a short-lived Even API session. Faceclaw stores it in the same private settings store as other API credentials and never logs it.",
});
export const evenHubOpenUdidSetting = new ConfigSettingString({
id: "evenhub-openudid",
label: "Even phone openUdid",
storageKey: "integrations.evenhub.openUdid",
defaultValue: "",
editorTitle: "Official Even app Android openUdid",
glassesEditTitle: "Edit Even openUdid",
normalize: (value) => (value ?? "").replace(/[^A-Za-z0-9_-]+/g, "").trim(),
formatValue: maskToken,
description:
"Android ID already bound to this account by the official Even app. The private API rejects a valid login token when this value is missing or belongs to another app/device.",
});
/**
* Staging buffer for the Terminal app's "Add connection" flow: the worker
* asks the shell to open the phone text editor on this setting, the user
+11
View File
@@ -26,6 +26,9 @@ import {
assistantSkipConfirmationSetting,
batteryDisplayModeSetting,
brightnessSetting,
evenHubEmailSetting,
evenHubOpenUdidSetting,
evenHubPasswordSetting,
elevenLabsApiKeySetting,
mapboxApiKeySetting,
openAiApiKeySetting,
@@ -131,6 +134,14 @@ function settingsSections(): SettingsSection[] {
textSettingMenuItem(roamApiTokenSetting),
],
},
{
label: "EvenHub",
items: [
textSettingMenuItem(evenHubEmailSetting),
textSettingMenuItem(evenHubPasswordSetting),
textSettingMenuItem(evenHubOpenUdidSetting),
],
},
{
label: "Developer",
items: [