Offline-First Resilience & Security

Modern software often leaks sensitive financial and personal numbers to remote servers under the guise of cloud synchronization or AI autocomplete.

Kalc is engineered with a strict privacy-first and offline-first ethos: your calculations belong exclusively to you, on your Mac.

---

Local-First Architecture & Privacy

• Optional Cloud AI: When enabled, only the active line and locally extracted value spans are sent through Kalc Cloud to TypeSafe.ai. The surrounding document, tab names, workspace variable values, and previous results are not sent.

---

100% Offline Computational Core

Every core calculation subsystem in Kalc executes entirely on your Mac's CPU:

• Mathematical, Scientific & Transcendental Functions: Pure local execution.
• Date, Calendar & Timezone Conversions: Evaluated against macOS system timezone databases.
• Dimensional Unit Conversions: Computed via UnitCatalog with static physical ratios.
• Developer Functions & Cryptographic Hashes: Executed on-device via Apple's native CryptoKit.

You can take your MacBook on an airplane, work in remote off-grid locations, or run Kalc inside air-gapped corporate environments without losing calculation capabilities.

---

Opt-In Formula Assistant & Data Minimization

For users who enable the optional Cloud AI Assistant in Settings > Cloud AI:

• Strictly Opt-In: Disabled by default. Native calculation syntax evaluates locally without any cloud request.
• Minimal Transmission: The active line and locally extracted value spans are sent through Kalc Cloud. Surrounding document text, tab names, previous results, and workspace variable values are excluded.
• Gateway Processing: The schema-v3 Cloudflare Worker validates typed JEV questions and answers, applies rate limits and device quota accounting, then calls TypeSafe.ai with server-side credentials. The macOS app has no provider key or direct provider endpoint.
• Local Formula Gate: Proposed formulas must pass local parser and preview validation and require explicit user action before insertion. Plugin execution is deferred until acceptance.
• No-Store Responses: The AI route sets Cache-Control: no-store; request content is excluded from AI event logs and D1 history stores request metadata only.
• Metadata Boundary: D1 keeps only request ID, device-scoped quota/history metadata, model, token counts, charge, decision mode, status, and timestamps. The active line, extracted values, JEV questions/state, formulas, and provider response content are not stored in AI history or telemetry. A stable device ID is retained for quota and history scoping.
• Quota Exhaustion: The gateway checks allowance before inference and charges only successful, validated responses. An exhausted allowance returns 402 AI_CREDIT_EXHAUSTED; local calculations continue to work and the current allowance remains visible in Settings.
• Cloudflare Data Use: Cloudflare's current Workers AI data usage policy says Workers AI customer content is not used to train models or improve Cloudflare or third-party services without explicit consent. Kalc does not use a Cloudflare storage service for AI request content.
• Zero Client Footprint: Kalc downloads zero neural weights to user hardware.

---

Offline Currency Store & Background Refresh

While currency exchange rates fluctuate continuously, Kalc ensures that an internet outage never interrupts your workflow:

1. Bundled Currency Baseline: Kalc ships with a pre-compiled local store of exchange rates for 170+ ISO currencies and major cryptocurrencies (BTC, ETH, SOL).
2. Offline-First Fallback: If your Mac is offline, Kalc calculates conversions seamlessly using the latest available cached rates.
3. Staleness Tracking: The header bar displays a live freshness badge:
   • Live: Rates refreshed recently.
   • 2h ago: Time elapsed since last update.
   • Offline: Operating in disconnected mode using local cached baselines.
4. Customizable Refresh Cadence: In Preferences > Rates & Daemon, you can configure the background update interval (e.g., every 6 hours, 24 hours, or manual refresh only).

---

Localhost-Only Daemon Binding (127.0.0.1)

The embedded calculation daemon (KalcDaemon) provides a headless HTTP REST API (POST /calculate) for integrations with Raycast, Alfred, and local terminal scripts.

To guarantee local security:

• Strict Loopback Binding: The daemon binds exclusively to IPv4 loopback 127.0.0.1:15055.
• No Remote Network Exposure: The service rejects external interface bindings (0.0.0.0 or local network IPs). Devices on your local Wi-Fi cannot access or invoke your calculation daemon.
• No Cross-Origin Exploitation: Rejects foreign origins and runs without elevated permissions.

---

Sandboxed JavaScriptCore Extension Engine

To prevent malicious or poorly written third-party plugins from compromising your system:

• Isolated JSContext: Extensions execute inside Apple's native JavaScriptCore runtime.
• No Filesystem Access: Plugins cannot read, write, or scan files on your disk.
• No Process Execution: Plugins cannot invoke shell commands, spawn child processes, or run binaries.
• No Outbound Sockets: Plugins cannot open raw network connections or exfiltrate document text.
• Controlled Bridge: Plugins communicate exclusively through the declarative kalc JS API to register custom functions, units, and templates.

---

Zero External Package Dependencies

The entire Kalc codebase compiles without pulling a single third-party Swift package, CocoaPod, or dynamic library. It depends strictly on Apple's standard system frameworks:

├── Foundation        (Decimals, strings, dates, regex, formatting)
├── AppKit            (Windows, views, layout, menus, dialogs)
├── TextKit 2         (Line fragments, text storage, baseline rendering)
├── Carbon            (HIToolbox system-wide global hotkeys)
├── Network           (Network.framework loopback HTTP socket)
├── CryptoKit         (MD5, SHA-1, SHA-256 cryptographic digests)
├── JavaScriptCore    (Secure extension sandboxing)
└── Testing           (Modern Swift Testing automated test harness)

By eliminating external dependencies, Kalc eliminates software supply-chain vulnerabilities, library bloat, and deprecation churn.