@hearthlog/native 0.0.0-stage → 0.1.1

package/src/site.ts

@@ -0,0 +1,268 @@
+/**
+ * Shared by the apple:* scripts: what makes one site's native app different from another's.
+ *
+ * Everything per-site comes from the tenant configuration (`tenants.json` or
+ * `tenants/<id>/tenant.json`, plus `deployment.json` for a site in its own account:
+ * title, accent, hostname, Access team) and the tenant's resign.local.json (your device,
+ * team and bundle prefix). Nothing here is deployed or sent anywhere; the apps open the
+ * already-deployed site. The Swift sources ship in this package (`swift/`); everything
+ * generated goes to the tenant's `.apple-build/`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { brandColor, brandTileSvg } from "@hearthlog/contracts/tenant/brand";
+import { themeVariablesFor } from "@hearthlog/contracts/tenant/theme";
+import { infrastructureFor, loadTenantConfig, REPOSITORY_ROOT } from "@hearthlog/tooling/tenants/tenant-config.js";
+
+/** The Swift sources of the apps: `Shared`, `macOS`, `iOS`, and `Tests`. */
+export const SWIFT_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../swift");
+/** Everything generated for the tenant: icons, the Mac apps, the iOS project, DerivedData. */
+export const BUILD_ROOT = path.join(REPOSITORY_ROOT, ".apple-build");
+/** The generated iOS project: `Stor.xcodeproj` and `Generated/` (Info.plist, build settings, icon). */
+export const PROJECT_ROOT = path.join(BUILD_ROOT, "project");
+export const SETTINGS_FILE = path.join(REPOSITORY_ROOT, "resign.local.json");
+
+const MARK_ON_TILE = "#fbf9fa";
+
+export class AppleError extends Error {}
+
+export interface AppleSettings {
+    /** iPhone name as shown in Finder or Xcode, or its UDID (only the iPhone scripts need it). */
+    device: string;
+    project: string;
+    scheme: string;
+    /** Site ids to keep installed; at most three fit a free Apple ID. */
+    sites: string[];
+    renewWithinDays: number;
+    /** Apple team id; found from your Apple Development certificate when left out. */
+    team: string;
+    /** Reverse-DNS prefix; each app is `<prefix>.<site id>`. Must be unique to you for a free team. */
+    bundlePrefix: string;
+}
+
+export interface AppleSite {
+    id: string;
+    title: string;
+    /** The site's origin (its workers.dev address or hostname), no trailing slash. */
+    origin: string;
+    host: string;
+    /** Cloudflare Access team host; its login opens in the sign-in window. */
+    accessHost: string;
+    accent: string;
+    /** The brand tile colour of the icons. */
+    tile: string;
+    bundleId: string;
+    version: string;
+    build: string;
+}
+
+export function run(command: string, args: string[], options: { input?: string; quiet?: boolean; cwd?: string } = {}): string {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd ?? REPOSITORY_ROOT,
+        encoding: "utf8",
+        input: options.input,
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: options.quiet ? ["pipe", "pipe", "pipe"] : ["pipe", "pipe", "inherit"],
+    });
+    if (result.error) throw new AppleError(`${command} could not start: ${result.error.message}`);
+    if (result.status !== 0) {
+        const detail = options.quiet ? `\n${result.stderr.trim()}` : "";
+        throw new AppleError(`${command} ${args[0] ?? ""} exited with ${result.status}${detail}`);
+    }
+    return result.stdout;
+}
+
+export function loadAppleSettings(options: { requireDevice: boolean }): AppleSettings {
+    let raw: Partial<AppleSettings> = {};
+    if (existsSync(SETTINGS_FILE)) {
+        raw = JSON.parse(readFileSync(SETTINGS_FILE, "utf8")) as Partial<AppleSettings>;
+    } else if (options.requireDevice) {
+        throw new AppleError(`Missing ${path.relative(REPOSITORY_ROOT, SETTINGS_FILE)}; copy resign.example.json from @hearthlog/native and set your device.`);
+    }
+    const settings: AppleSettings = {
+        device: raw.device ?? "",
+        project: raw.project ?? path.relative(REPOSITORY_ROOT, path.join(PROJECT_ROOT, "Stor.xcodeproj")),
+        scheme: raw.scheme ?? "Stor iOS",
+        sites: raw.sites ?? [],
+        renewWithinDays: raw.renewWithinDays ?? 2,
+        team: raw.team ?? "",
+        bundlePrefix: raw.bundlePrefix ?? "app.stor",
+    };
+    if (options.requireDevice) {
+        if (!settings.device) throw new AppleError("Set \"device\" to the iPhone's name or UDID.");
+        if (settings.sites.length === 0) throw new AppleError("List at least one site id in \"sites\".");
+        if (settings.sites.length > 3) throw new AppleError("A free Apple ID can keep at most three apps on a device.");
+    }
+    if (!/^[a-z0-9]+(\.[a-z0-9-]+)+$/i.test(settings.bundlePrefix)) {
+        throw new AppleError(`bundlePrefix "${settings.bundlePrefix}" must be reverse-DNS, like app.stor`);
+    }
+    return settings;
+}
+
+export async function loadAppleSite(id: string, settings: AppleSettings): Promise<AppleSite> {
+    const { infrastructure, sites } = await loadTenantConfig();
+    const site = sites.find((candidate) => candidate.id === id);
+    if (!site) throw new AppleError(`Unknown site id "${id}" (known: ${sites.map((candidate) => candidate.id).join(", ")})`);
+    const origin = site.hostname.replace(/\/+$/, "");
+    const accent = site.theme.accent;
+    return {
+        id: site.id,
+        title: site.title,
+        origin,
+        host: new URL(origin).host,
+        // A site in its own account trusts that account's Access team.
+        accessHost: new URL(infrastructureFor(site, infrastructure).accessTeamDomain).host,
+        accent: accent ?? "",
+        tile: brandColor(accent, themeVariablesFor(accent, "light")["--stor-action"]),
+        bundleId: `${settings.bundlePrefix}.${site.id}`,
+        version: (JSON.parse(readFileSync(path.join(REPOSITORY_ROOT, "package.json"), "utf8")) as { version: string }).version,
+        build: buildNumber(),
+    };
+}
+
+/** Commits on this branch: strictly rising, which is all an installed build number needs. */
+function buildNumber(): string {
+    try {
+        return run("git", ["rev-list", "--count", "HEAD"], { quiet: true }).trim() || "1";
+    } catch {
+        return "1";
+    }
+}
+
+// MARK: Info.plist
+
+type PlistValue = string | number | boolean | PlistValue[] | { [key: string]: PlistValue };
+
+function plistXml(value: PlistValue, indent = ""): string {
+    const escape = (text: string) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+    if (typeof value === "string") return `${indent}<string>${escape(value)}</string>`;
+    if (typeof value === "number") return `${indent}<integer>${value}</integer>`;
+    if (typeof value === "boolean") return `${indent}<${value}/>`;
+    if (Array.isArray(value)) {
+        if (value.length === 0) return `${indent}<array/>`;
+        return `${indent}<array>\n${value.map((item) => plistXml(item, `${indent}    `)).join("\n")}\n${indent}</array>`;
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) return `${indent}<dict/>`;
+    return `${indent}<dict>\n${entries
+        .map(([key, item]) => `${indent}    <key>${escape(key)}</key>\n${plistXml(item, `${indent}    `)}`)
+        .join("\n")}\n${indent}</dict>`;
+}
+
+export function plistDocument(entries: { [key: string]: PlistValue }): string {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+${plistXml(entries)}
+</plist>
+`;
+}
+
+function storSite(site: AppleSite): PlistValue {
+    return { id: site.id, title: site.title, origin: site.origin, accessHost: site.accessHost };
+}
+
+const CAMERA_USAGE = (site: AppleSite) => `${site.title} uses the camera to scan food barcodes.`;
+
+export function macInfoPlist(site: AppleSite, options: { executable: string; development: boolean; inspectable: boolean }): string {
+    return plistDocument({
+        CFBundleDevelopmentRegion: "en",
+        CFBundleExecutable: options.executable,
+        CFBundleIconFile: "AppIcon",
+        CFBundleIdentifier: site.bundleId,
+        CFBundleInfoDictionaryVersion: "6.0",
+        CFBundleName: site.title,
+        CFBundleDisplayName: site.title,
+        CFBundlePackageType: "APPL",
+        CFBundleShortVersionString: site.version,
+        CFBundleVersion: site.build,
+        LSApplicationCategoryType: "public.app-category.productivity",
+        LSMinimumSystemVersion: "14.0",
+        NSCameraUsageDescription: CAMERA_USAGE(site),
+        NSHighResolutionCapable: true,
+        NSPrincipalClass: "NSApplication",
+        StorSite: storSite(site),
+        StorInspectable: options.inspectable,
+        ...(options.development ? { StorDevelopmentOverrides: true } : {}),
+    });
+}
+
+/** Build settings come from Site.xcconfig; this file carries what is not a single setting. */
+export function iosInfoPlist(site: AppleSite): string {
+    return plistDocument({
+        CFBundleDevelopmentRegion: "en",
+        CFBundleDisplayName: site.title,
+        CFBundleExecutable: "$(EXECUTABLE_NAME)",
+        CFBundleIdentifier: "$(PRODUCT_BUNDLE_IDENTIFIER)",
+        CFBundleInfoDictionaryVersion: "6.0",
+        CFBundleName: "$(PRODUCT_NAME)",
+        CFBundlePackageType: "$(PRODUCT_BUNDLE_PACKAGE_TYPE)",
+        CFBundleShortVersionString: "$(MARKETING_VERSION)",
+        CFBundleVersion: "$(CURRENT_PROJECT_VERSION)",
+        ITSAppUsesNonExemptEncryption: false,
+        LSRequiresIPhoneOS: true,
+        NSCameraUsageDescription: CAMERA_USAGE(site),
+        StorSite: storSite(site),
+        UIApplicationSceneManifest: {
+            UIApplicationSupportsMultipleScenes: false,
+            UISceneConfigurations: {
+                UIWindowSceneSessionRoleApplication: [
+                    { UISceneConfigurationName: "Default Configuration", UISceneDelegateClassName: "StorSceneDelegate" },
+                ],
+            },
+        },
+        UILaunchScreen: {},
+        UIRequiredDeviceCapabilities: ["arm64"],
+        UISupportedInterfaceOrientations: ["UIInterfaceOrientationPortrait"],
+        "UISupportedInterfaceOrientations~ipad": [
+            "UIInterfaceOrientationPortrait",
+            "UIInterfaceOrientationPortraitUpsideDown",
+            "UIInterfaceOrientationLandscapeLeft",
+            "UIInterfaceOrientationLandscapeRight",
+        ],
+        // Service workers and script messages in WKWebView need the site's host listed here.
+        WKAppBoundDomains: [site.host],
+    });
+}
+
+// MARK: Icons
+
+export interface RenderedIcons {
+    /** Full-bleed tile, no transparency, as iOS wants. */
+    ios: string;
+    /** Rounded tile on the macOS icon grid, with its shadow. */
+    mac: string;
+}
+
+/** Renders the brand tile at 1024px for both platforms, using the Chromium Playwright already installs. */
+export async function renderIcons(site: AppleSite, directory: string): Promise<RenderedIcons> {
+    mkdirSync(directory, { recursive: true });
+    let chromium: typeof import("@playwright/test").chromium;
+    try {
+        ({ chromium } = await import("@playwright/test"));
+    } catch {
+        throw new AppleError("Rendering the icons needs Playwright: add @playwright/test to the devDependencies.");
+    }
+    const browser = await chromium.launch();
+    try {
+        const page = await browser.newPage({ viewport: { width: 1024, height: 1024 } });
+        const ios = path.join(directory, "icon-ios-1024.png");
+        const mac = path.join(directory, "icon-mac-1024.png");
+
+        const flat = brandTileSvg({ background: site.tile, fill: MARK_ON_TILE, scale: 0.62 }).replace("<svg ", '<svg width="1024" height="1024" ');
+        await page.setContent(`<body style="margin:0">${flat}</body>`);
+        writeFileSync(ios, await page.screenshot({ type: "png" }));
+
+        // macOS draws no mask of its own: the tile is 824px on a 1024px grid, with a soft shadow below it.
+        const tile = brandTileSvg({ background: site.tile, fill: MARK_ON_TILE, scale: 0.66, radius: 114 }).replace("<svg ", '<svg width="824" height="824" ');
+        await page.setContent(`<body style="margin:0;width:1024px;height:1024px;display:grid;place-items:center"><div style="filter:drop-shadow(0 10px 14px rgba(0,0,0,.28));line-height:0;margin-top:-6px">${tile}</div></body>`);
+        writeFileSync(mac, await page.screenshot({ type: "png", omitBackground: true }));
+        return { ios, mac };
+    } finally {
+        await browser.close();
+    }
+}

package/src/swift-checks.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env npx tsx
+/**
+ * Run the shell's Swift checks (swift/Tests). They cover the rules that decide access and what
+ * gets scheduled, need no Xcode, and compile in a few seconds with the Command Line Tools.
+ *
+ * Usage: hearthlog apple:test
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { SWIFT_DIRECTORY, run } from "./site.js";
+
+const directory = mkdtempSync(path.join(tmpdir(), "stor-apple-test-"));
+try {
+    const binary = path.join(directory, "checks");
+    const sdk = run("xcrun", ["--show-sdk-path"], { quiet: true }).trim();
+    run("swiftc", [
+        "-swift-version", "5",
+        "-target", `${process.arch === "arm64" ? "arm64" : "x86_64"}-apple-macos14.0`,
+        "-sdk", sdk,
+        "-o", binary,
+        ...["NavigationPolicy", "ShellMessage", "ReminderScheduler", "SiteConfig"].map((name) => path.join(SWIFT_DIRECTORY, "Shared", `${name}.swift`)),
+        path.join(SWIFT_DIRECTORY, "Tests", "main.swift"),
+    ]);
+    const result = spawnSync(binary, { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+} catch (error) {
+    console.error(`Failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+} finally {
+    rmSync(directory, { recursive: true, force: true });
+}

package/swift/Shared/NavigationPolicy.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// Decides what each navigation may do. The app's own origin loads in the web view; the
+/// Cloudflare Access login opens in the sign-in window; every other page opens in the
+/// default browser. Nothing else may load in a frame.
+struct NavigationPolicy: Equatable {
+    enum Decision: Equatable {
+        /// Load it here.
+        case allow
+        /// Hand it to the system (default browser, Mail, Phone).
+        case external
+        /// Open the Access login in the sign-in window.
+        case signIn
+        case cancel
+    }
+
+    let origin: URL
+    let accessHost: String?
+
+    func decide(_ url: URL?, isMainFrame: Bool) -> Decision {
+        guard let url, let scheme = url.scheme?.lowercased() else { return .cancel }
+        switch scheme {
+        case "about":
+            return url.absoluteString == "about:blank" ? .allow : .cancel
+        case "blob":
+            // blob:https://host/id belongs to the page that made it.
+            guard let inner = URL(string: String(url.absoluteString.dropFirst("blob:".count))) else { return .cancel }
+            return isOrigin(inner) ? .allow : .cancel
+        case "data":
+            return isMainFrame ? .cancel : .allow
+        case "http", "https":
+            if isOrigin(url) { return .allow }
+            let host = url.host?.lowercased()
+            // The app's own host over another scheme or port is never a link to follow.
+            if host == origin.host?.lowercased() { return .cancel }
+            if let accessHost, host == accessHost { return isMainFrame ? .signIn : .cancel }
+            return isMainFrame ? .external : .cancel
+        case "mailto", "tel", "sms":
+            return isMainFrame ? .external : .cancel
+        default:
+            return .cancel
+        }
+    }
+
+    /// The sign-in window is done once Access sends it back to the app (past `/cdn-cgi/`, which sets the cookie).
+    func finishesSignIn(_ url: URL?) -> Bool {
+        guard let url, isOrigin(url) else { return false }
+        return !url.path.hasPrefix("/cdn-cgi/")
+    }
+
+    /// The sign-in window may follow the login across identity providers, but only over https. The app's
+    /// own origin and the Access host also count over the app's scheme, which is http only in development.
+    func allowsSignIn(_ url: URL?) -> Bool {
+        guard let url, let scheme = url.scheme?.lowercased() else { return false }
+        if scheme == "about" { return url.absoluteString == "about:blank" }
+        if scheme == "https" || isOrigin(url) { return true }
+        return scheme == origin.scheme?.lowercased() && url.host?.lowercased() == accessHost
+    }
+
+    func isOrigin(_ url: URL) -> Bool {
+        guard let scheme = url.scheme?.lowercased(), scheme == origin.scheme?.lowercased(),
+              let host = url.host?.lowercased(), host == origin.host?.lowercased()
+        else { return false }
+        return (url.port ?? Self.defaultPort(scheme)) == (origin.port ?? Self.defaultPort(scheme))
+    }
+
+    private static func defaultPort(_ scheme: String) -> Int? {
+        scheme == "https" ? 443 : scheme == "http" ? 80 : nil
+    }
+}

package/swift/Shared/ReminderScheduler.swift

@@ -0,0 +1,65 @@
+import Foundation
+import UserNotifications
+
+/// Keeps the device's pending notifications equal to the page's latest reminder list.
+/// Only requests this scheduler made (identifier prefix `stor.reminder.`) are replaced.
+actor ReminderScheduler {
+    static let shared = ReminderScheduler()
+
+    private static let prefix = "stor.reminder."
+    /// iOS keeps at most 64 pending local notifications.
+    private static let limit = 60
+    private var applied: [Reminder]?
+
+    /// Asks for permission the first time; false if the person said no.
+    func authorize() async -> Bool {
+        let center = UNUserNotificationCenter.current()
+        switch await center.notificationSettings().authorizationStatus {
+        case .authorized, .provisional:
+            return true
+        case .notDetermined:
+            return (try? await center.requestAuthorization(options: [.alert, .sound, .badge])) ?? false
+        default:
+            return false
+        }
+    }
+
+    /// The reminders worth scheduling: still in the future, soonest first, no more than the device keeps.
+    nonisolated static func plan(_ reminders: [Reminder], now: Date) -> [Reminder] {
+        reminders
+            .compactMap { reminder in reminder.date.flatMap { $0 > now ? (reminder, $0) : nil } }
+            .sorted { $0.1 < $1.1 }
+            .prefix(limit)
+            .map(\.0)
+    }
+
+    func apply(_ reminders: [Reminder], now: Date = Date()) async {
+        let wanted = Self.plan(reminders, now: now)
+        guard wanted != applied else { return }
+
+        let center = UNUserNotificationCenter.current()
+        // Nothing to schedule is not a reason to ask for permission.
+        let allowed = wanted.isEmpty ? true : await authorize()
+        guard allowed else {
+            await removeAll(center)
+            applied = []
+            return
+        }
+        await removeAll(center)
+        for reminder in wanted {
+            let content = UNMutableNotificationContent()
+            content.title = reminder.title
+            content.body = reminder.body
+            content.sound = .default
+            content.userInfo = ["path": reminder.path]
+            let trigger = UNCalendarNotificationTrigger(dateMatching: reminder.at, repeats: false)
+            try? await center.add(UNNotificationRequest(identifier: Self.prefix + reminder.id, content: content, trigger: trigger))
+        }
+        applied = wanted
+    }
+
+    private func removeAll(_ center: UNUserNotificationCenter) async {
+        let ids = await center.pendingNotificationRequests().map(\.identifier).filter { $0.hasPrefix(Self.prefix) }
+        center.removePendingNotificationRequests(withIdentifiers: ids)
+    }
+}

package/swift/Shared/ShellMessage.swift

@@ -0,0 +1,118 @@
+import Foundation
+
+enum ShellKind: String {
+    case mac, ios
+}
+
+enum Appearance: String {
+    case light, dark, system
+}
+
+/// A notification the page wants scheduled. `at` is wall-clock time in the device's time zone.
+struct Reminder: Hashable {
+    var id: String
+    var title: String
+    var body: String
+    var at: DateComponents
+    var path: String
+
+    var date: Date? { Calendar.current.date(from: at) }
+}
+
+struct MenuEntry: Hashable {
+    var id: String
+    var title: String
+    var path: String
+    /// A section's sub-pages; the Mac Dock menu shows them as a submenu.
+    var children: [MenuEntry] = []
+}
+
+/// What the page tells the shell. Decoded from `{ type, body }` posted on the `stor` handler;
+/// anything malformed is dropped.
+enum ShellMessage: Equatable {
+    case appearance(preference: Appearance, resolved: Appearance, background: String?)
+    case badge(Int)
+    case reminders([Reminder])
+    case menu(destinations: [MenuEntry], actions: [MenuEntry])
+    /// Left edge of the first window control and its vertical centre, in points from the window's top left.
+    case lights(x: Double, y: Double)
+    case outbox(pending: Int)
+    case haptic(success: Bool)
+    /// Whether the pointer is over a background of the page (see `WindowDragScript`); a click there moves the window.
+    case backgroundHover(on: Bool)
+    /// What earlier pages sent from their own drag handler. The shell drags by itself now and ignores it.
+    case drag(clickCount: Int)
+
+    init?(_ message: Any) {
+        guard let envelope = message as? [String: Any],
+              let type = envelope["type"] as? String,
+              let body = envelope["body"] as? [String: Any]
+        else { return nil }
+
+        switch type {
+        case "appearance":
+            guard let preference = (body["preference"] as? String).flatMap(Appearance.init),
+                  let resolved = (body["resolved"] as? String).flatMap(Appearance.init)
+            else { return nil }
+            self = .appearance(preference: preference, resolved: resolved, background: body["background"] as? String)
+        case "badge":
+            guard let count = Self.int(body["count"]) else { return nil }
+            self = .badge(max(0, count))
+        case "reminders":
+            guard let items = body["items"] as? [[String: Any]] else { return nil }
+            self = .reminders(items.compactMap(Self.reminder))
+        case "menu":
+            guard let destinations = body["destinations"] as? [[String: Any]],
+                  let actions = body["actions"] as? [[String: Any]]
+            else { return nil }
+            self = .menu(destinations: destinations.compactMap(Self.entry), actions: actions.compactMap(Self.entry))
+        case "lights":
+            guard let x = Self.double(body["x"]), let y = Self.double(body["y"]), x.isFinite, y.isFinite else { return nil }
+            self = .lights(x: x, y: y)
+        case "outbox":
+            guard let pending = Self.int(body["pending"]) else { return nil }
+            self = .outbox(pending: max(0, pending))
+        case "haptic":
+            self = .haptic(success: (body["kind"] as? String) == "success")
+        case "backgroundHover":
+            self = .backgroundHover(on: (body["on"] as? Bool) ?? false)
+        case "drag":
+            self = .drag(clickCount: Self.int(body["clickCount"]) ?? 1)
+        default:
+            return nil
+        }
+    }
+
+    private static func int(_ value: Any?) -> Int? { (value as? NSNumber)?.intValue }
+    private static func double(_ value: Any?) -> Double? { (value as? NSNumber)?.doubleValue }
+
+    private static func entry(_ raw: [String: Any]) -> MenuEntry? {
+        guard let id = raw["id"] as? String, let title = raw["title"] as? String, let path = raw["path"] as? String,
+              isAppPath(path)
+        else { return nil }
+        let children = (raw["children"] as? [[String: Any]])?.compactMap(entry) ?? []
+        return MenuEntry(id: id, title: title, path: path, children: children)
+    }
+
+    private static func reminder(_ raw: [String: Any]) -> Reminder? {
+        guard let id = raw["id"] as? String, let title = raw["title"] as? String,
+              let body = raw["body"] as? String, let path = raw["path"] as? String, isAppPath(path),
+              let at = (raw["at"] as? String).flatMap(components)
+        else { return nil }
+        return Reminder(id: id, title: title, body: body, at: at, path: path)
+    }
+
+    /// `YYYY-MM-DDTHH:mm` as calendar components, without choosing a time zone.
+    static func components(_ text: String) -> DateComponents? {
+        let parts = text.split(whereSeparator: { "-T:".contains($0) }).compactMap { Int($0) }
+        guard parts.count == 5, (1...12).contains(parts[1]), (1...31).contains(parts[2]),
+              (0...23).contains(parts[3]), (0...59).contains(parts[4])
+        else { return nil }
+        return DateComponents(calendar: .current, timeZone: .current, year: parts[0], month: parts[1], day: parts[2], hour: parts[3], minute: parts[4])
+    }
+
+    /// An in-app route: absolute and never `//host`.
+    static func isAppPath(_ path: String) -> Bool {
+        path.hasPrefix("/") && !path.hasPrefix("//")
+    }
+}

package/swift/Shared/SiteConfig.swift

@@ -0,0 +1,47 @@
+import CryptoKit
+import Foundation
+
+/// The site an app build opens. `scripts/apple-site.ts` writes it into Info.plist as `StorSite`.
+struct SiteConfig: Equatable {
+    let id: String
+    let title: String
+    let origin: URL
+    /// Cloudflare Access team host; navigating there opens the sign-in window.
+    let accessHost: String?
+    /// A development build pointed at another origin keeps its own data store.
+    let isDevelopmentOrigin: Bool
+
+    var host: String { origin.host?.lowercased() ?? "" }
+
+    /// One persistent data store per site, so apps for different sites never share storage.
+    var dataStoreIdentifier: UUID {
+        let name = "app.stor.data-store.\(id)\(isDevelopmentOrigin ? ".development" : "")"
+        var bytes = Array(SHA256.hash(data: Data(name.utf8)).prefix(16))
+        bytes[6] = (bytes[6] & 0x0F) | 0x50
+        bytes[8] = (bytes[8] & 0x3F) | 0x80
+        return bytes.withUnsafeBytes { UUID(uuid: $0.load(as: uuid_t.self)) }
+    }
+
+    /// Reads `StorSite` from the bundle. A build without it is a build mistake, so this stops.
+    /// Builds made with `--dev` may point at another origin and Access host through `STOR_ORIGIN` and `STOR_ACCESS_HOST`.
+    static func load(bundle: Bundle = .main, environment: [String: String] = ProcessInfo.processInfo.environment) -> SiteConfig {
+        guard let info = bundle.object(forInfoDictionaryKey: "StorSite") as? [String: Any],
+              let id = info["id"] as? String,
+              let title = info["title"] as? String,
+              let originString = info["origin"] as? String,
+              let configured = URL(string: originString), configured.host != nil
+        else { fatalError("Info.plist has no valid StorSite. Build with pnpm apple:mac or pnpm apple:ios.") }
+
+        var origin = configured
+        var accessHost = (info["accessHost"] as? String)?.lowercased()
+        var isDevelopmentOrigin = false
+        if bundle.object(forInfoDictionaryKey: "StorDevelopmentOverrides") as? Bool == true {
+            if let override = environment["STOR_ORIGIN"].flatMap(URL.init(string:)), override.host != nil {
+                origin = override
+                isDevelopmentOrigin = true
+            }
+            if let override = environment["STOR_ACCESS_HOST"], !override.isEmpty { accessHost = override.lowercased() }
+        }
+        return SiteConfig(id: id, title: title, origin: origin, accessHost: accessHost, isDevelopmentOrigin: isDevelopmentOrigin)
+    }
+}