things-api 0.17.0 → 0.19.0

package/deputy/src/sqlite.swift

@@ -0,0 +1,121 @@
+/**
+ * Read-only SQLite executor. Mirrors the library's WAL policy
+ * (docs/design/architecture.md §0): SQLITE_OPEN_READONLY, never immutable, a
+ * fresh WAL read snapshot per statement outside any transaction — the deputy
+ * never opens a transaction, so the CLI's verification poller sees fresh state
+ * on every poll exactly as it does with a local connection. An authorizer
+ * denies ATTACH so the read-only handle cannot be aimed at other files.
+ */
+import Foundation
+import SQLite3
+
+let SQLITE_TRANSIENT = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
+
+struct SqliteError: Error {
+  let message: String
+}
+
+final class SqliteReader {
+  private var handle: OpaquePointer?
+
+  init(path: String) throws {
+    var h: OpaquePointer?
+    let rc = sqlite3_open_v2(path, &h, SQLITE_OPEN_READONLY, nil)
+    guard rc == SQLITE_OK, let opened = h else {
+      let message = h.map { String(cString: sqlite3_errmsg($0)) } ?? "sqlite rc \(rc)"
+      sqlite3_close(h)
+      throw SqliteError(message: message)
+    }
+    handle = opened
+    sqlite3_busy_timeout(opened, 2000)
+    sqlite3_set_authorizer(
+      opened,
+      { _, action, _, _, _, _ in
+        action == SQLITE_ATTACH ? SQLITE_DENY : SQLITE_OK
+      }, nil)
+  }
+
+  deinit {
+    if let h = handle { sqlite3_close_v2(h) }
+  }
+
+  func query(sql: String, params: [Any]) throws -> [[String: Any]] {
+    guard let h = handle else { throw SqliteError(message: "connection closed") }
+    var stmt: OpaquePointer?
+    // The tail pointer aims into the C string handed to prepare, so it MUST be
+    // read inside withCString — Swift's implicit bridging buffer is deallocated
+    // the moment the call returns (a read-after-free otherwise).
+    var trailingStatement = false
+    let rc = sql.withCString { (cSql: UnsafePointer<CChar>) -> Int32 in
+      var tail: UnsafePointer<CChar>? = nil
+      let result = sqlite3_prepare_v2(h, cSql, -1, &stmt, &tail)
+      if let t = tail {
+        trailingStatement = !String(cString: t)
+          .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+      }
+      return result
+    }
+    guard rc == SQLITE_OK, let prepared = stmt else {
+      throw SqliteError(message: String(cString: sqlite3_errmsg(h)))
+    }
+    defer { sqlite3_finalize(prepared) }
+    if trailingStatement {
+      throw SqliteError(message: "only a single SQL statement is accepted per request")
+    }
+
+    for (index, param) in params.enumerated() {
+      let slot = Int32(index + 1)
+      let rc: Int32
+      switch param {
+      case is NSNull:
+        rc = sqlite3_bind_null(prepared, slot)
+      case let text as String:
+        rc = sqlite3_bind_text(prepared, slot, text, -1, SQLITE_TRANSIENT)
+      case let number as NSNumber:
+        if CFNumberIsFloatType(number) {
+          rc = sqlite3_bind_double(prepared, slot, number.doubleValue)
+        } else {
+          rc = sqlite3_bind_int64(prepared, slot, number.int64Value)
+        }
+      default:
+        throw SqliteError(message: "unsupported parameter type at index \(index)")
+      }
+      guard rc == SQLITE_OK else {
+        throw SqliteError(message: String(cString: sqlite3_errmsg(h)))
+      }
+    }
+
+    var rows: [[String: Any]] = []
+    let columnCount = sqlite3_column_count(prepared)
+    while true {
+      let rc = sqlite3_step(prepared)
+      if rc == SQLITE_DONE { break }
+      guard rc == SQLITE_ROW else {
+        throw SqliteError(message: String(cString: sqlite3_errmsg(h)))
+      }
+      var row: [String: Any] = [:]
+      for col in 0..<columnCount {
+        let name = String(cString: sqlite3_column_name(prepared, col))
+        switch sqlite3_column_type(prepared, col) {
+        case SQLITE_INTEGER:
+          row[name] = sqlite3_column_int64(prepared, col)
+        case SQLITE_FLOAT:
+          row[name] = sqlite3_column_double(prepared, col)
+        case SQLITE_TEXT:
+          row[name] = String(cString: sqlite3_column_text(prepared, col))
+        case SQLITE_BLOB:
+          let bytes = sqlite3_column_bytes(prepared, col)
+          let data =
+            bytes > 0
+            ? Data(bytes: sqlite3_column_blob(prepared, col), count: Int(bytes))
+            : Data()
+          row[name] = ["$b64": data.base64EncodedString()]
+        default:
+          row[name] = NSNull()
+        }
+      }
+      rows.append(row)
+    }
+    return rows
+  }
+}

package/deputy/src/tcc.swift

@@ -0,0 +1,58 @@
+/**
+ * Prompt-free TCC introspection, plus the one call that deliberately DOES
+ * prompt (Accessibility).
+ *
+ * The deputy is the process macOS attributes every AppleEvent and every
+ * Accessibility action to, so it — and only it — can answer "am I allowed to
+ * drive Things?" truthfully. Both answers ride the `hello` response, which
+ * makes `things helpers status` and the onboarding ceremony able to SKIP a leg
+ * that is already granted instead of re-firing a dialog at the user.
+ *
+ * `AEDeterminePermissionToAutomateTarget(…, askUserIfNeeded: false)` is the
+ * documented non-prompting probe: it answers from the existing TCC record and
+ * returns errAEEventWouldRequireUserConsent (-1744) when no record exists yet
+ * — reported here as "unknown", which is exactly the state the ceremony then
+ * resolves by sending a real (prompting) AppleEvent.
+ */
+import ApplicationServices
+import Foundation
+
+/// One target's Automation state: "granted" | "denied" | "not-running" | "unknown".
+func automationStatus(bundleID: String) -> String {
+  var target = AEAddressDesc()
+  let bytes = Array(bundleID.utf8)
+  let created = bytes.withUnsafeBufferPointer { buf in
+    AECreateDesc(typeApplicationBundleID, buf.baseAddress, buf.count, &target)
+  }
+  guard created == noErr else { return "unknown" }
+  defer { AEDisposeDesc(&target) }
+  // askUserIfNeeded: false — a status probe must never raise a dialog.
+  let status = AEDeterminePermissionToAutomateTarget(&target, typeWildCard, typeWildCard, false)
+  switch status {
+  case noErr:
+    return "granted"
+  case -1743:  // errAEEventNotPermitted — the user (or MDM) said no.
+    return "denied"
+  case -600:  // procNotFound — the target is not running, so TCC has no answer.
+    return "not-running"
+  default:
+    // -1744 errAEEventWouldRequireUserConsent lands here: never asked yet.
+    return "unknown"
+  }
+}
+
+/// Accessibility trust for THIS process, prompt-free.
+func accessibilityTrusted() -> Bool {
+  AXIsProcessTrusted()
+}
+
+/**
+ * Ask macOS to show the Accessibility prompt for this process. The dialog is
+ * fire-and-forget (it offers a Settings deep-link; the actual grant is a
+ * toggle the user flips in System Settings), so this returns the CURRENT trust
+ * state immediately rather than waiting for one that can only arrive later.
+ */
+func primeAccessibility() -> Bool {
+  let key = kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String
+  return AXIsProcessTrustedWithOptions([key: true] as CFDictionary)
+}

package/dist/audit/schema.d.ts

@@ -1,3 +1,4 @@
+import type { OccurrenceResolution } from "../write/verify/delta.ts";
 export interface AuditRecord {
     v: 1;
     ts: string;
@@ -41,13 +42,24 @@ export interface AuditRecord {
      * bumped) without a separate read. Absent on writes made without the flag.
      */
     preModDates?: Record<string, number | null>;
+    /**
+     * Template-target composite disclosure (ADDITIVE): which occurrence a
+     * `complete`/`cancel`/`update --exception` aimed at a repeating series
+     * actually wrote, and whether the composite minted it. Recorded on the
+     * composite's SUMMARY record only — the one record its `opId` keys — so an
+     * idempotency replay can hand the caller the same two uuids the original
+     * call returned without re-reading the database.
+     */
+    occurrence?: OccurrenceResolution;
     /** Normalized requested delta (params as given, post-normalization). */
     requested: Record<string, unknown>;
     /** Asserted-field subset of the pre-state (null when target didn't exist). */
     pre: Record<string, unknown> | null;
     /** Post-verify observation (best-effort on failure). */
     observed: Record<string, unknown> | null;
-    result: "intent" | "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop" | `blocked:${string}` | "unsupported";
+    result: "intent" | "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop"
+    /** A GUI drive stopped because the Things window was unreachable/unresponsive (#512). */
+     | "verify-failed:ui-unreachable" | `blocked:${string}` | "unsupported";
     verify: {
         attempts: number;
         elapsedMs: number;

package/dist/audit/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8EzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}

package/dist/capability.d.ts

@@ -0,0 +1,160 @@
+import { type HostAccessDeps, type HostApp } from "./host-access.ts";
+export { fdaGranted, type FdaVerdict, type HostApp, hostApp, hostDisplayName, tccDbPath, } from "./host-access.ts";
+/** The Things application's bundle identifier — the Automation grant's target. */
+export declare const THINGS_BUNDLE_ID = "com.culturedcode.ThingsMac";
+/** How reads may reach the live library, if at all. */
+export type ReadCapabilityMode = 
+/** A caller-supplied database path — outside the doctrine entirely (Article VI). */
+"explicit-db"
+/** Reads ride the sandboxed reader; the read itself is the capability check. */
+ | "helpers"
+/** The helpers are expected here but cannot serve — refuse, never fall back. */
+ | "helpers-unavailable"
+/** No helpers, but the host app holds Full Disk Access. */
+ | "direct-fda"
+/** A ceremony witnessed an app-data grant that is still live for this app instance. */
+ | "session-grant"
+/** Nothing can open the container — the caller must run a setup ceremony. */
+ | "none";
+/** How GUI-driving may be delivered, if at all (Article IV). */
+export type UiCapabilityMode = 
+/** The helper pair holds Accessibility + Automation→System Events. */
+"helpers"
+/** The lab's documented in-guest escape (see {@link UI_DIRECT_ESCAPE_ENV}). */
+ | "direct-escape"
+/** GUI-driving is switched off in config — nothing has been asked for yet. */
+ | "config-disabled"
+/** No deputy answers, so there is no identity that could hold the grants. */
+ | "helpers-missing"
+/** The deputy answers but the `--gui` tier is incomplete. */
+ | "tier-incomplete";
+/** How app automation may be delivered, if at all. */
+export type WriteCapabilityMode = 
+/** The deputy is onboarded; Apple Events are sent under the helper identity. */
+"deputy"
+/** macOS records an Automation grant for the host app against Things. */
+ | "direct-granted"
+/** macOS records a REFUSAL. It will not re-ask; the human must re-arm it. */
+ | "direct-denied"
+/** No record either way, or none readable — never resolved by prompting. */
+ | "direct-unknown";
+export interface Capability<Mode> {
+    mode: Mode;
+    /** One sentence of provenance, for `doctor` and for refusal copy. */
+    detail: string;
+    /**
+     * The remediation lines a refusal prints, in the order they should be
+     * offered. Empty when the capability is present.
+     */
+    remediation: string[];
+    /** The identity a direct-mode grant would attach to. */
+    host: HostApp;
+}
+export type ReadCapability = Capability<ReadCapabilityMode>;
+export type WriteCapability = Capability<WriteCapabilityMode>;
+export type UiCapability = Capability<UiCapabilityMode>;
+/** True when this verdict permits opening the live container. */
+export declare function readAllowed(capability: ReadCapability): boolean;
+/** True when this verdict permits driving the Things window. */
+export declare function uiAllowed(capability: UiCapability): boolean;
+/** True when app automation may be dispatched. */
+export declare function writeAllowed(capability: WriteCapability): boolean;
+/**
+ * Injection seams. Every one of these defaults to a real, prompt-free probe;
+ * tests replace them so no test ever touches the host's TCC state.
+ */
+export interface CapabilityDeps extends HostAccessDeps {
+    /** Are this process's database reads actually being served by the reader? */
+    helpersServing?: () => boolean;
+    /** Are the helpers expected on this machine (enabled, and installed under auto)? */
+    helpersExpected?: () => boolean;
+    /** Why the helpers are not serving, for the loud refusal. */
+    helpersReason?: () => string | null;
+    /** The deputy's `automation.things` standing, from its handshake. */
+    deputyAutomation?: () => string | undefined;
+    /**
+     * The deputy's GUI-driving standing, from the same handshake: whether it is
+     * Accessibility-trusted and where its Automation→System Events grant stands.
+     * `null` means no deputy answered at all.
+     */
+    deputyGuiStanding?: () => {
+        axTrusted: boolean | undefined;
+        systemEvents: string | undefined;
+    } | null;
+    /** Is GUI-driving switched on in config (`ui-enabled`)? */
+    uiEnabled?: () => boolean;
+    /**
+     * Read one Automation row out of TCC.db. Returns the raw `auth_value`, or
+     * null when there is no row / the file cannot be read.
+     */
+    automationAuthValue?: (client: string, target: string) => number | null;
+    /** Resolve a running app's display name from its bundle id (LaunchServices). */
+    lookupAppName?: (bundleId: string) => string | null;
+}
+/**
+ * Can this process read the live Things library, and on whose authority?
+ *
+ * Stateless: every call re-derives the verdict, because a grant can appear or
+ * vanish between one invocation and the next and a cached "yes" would be a
+ * stored onboarding flag by another name. The common case costs one `open(2)`.
+ */
+export declare function readCapability(options?: {
+    dbPath?: string;
+}, deps?: CapabilityDeps): ReadCapability;
+/** Thrown when a read is refused for want of capability (Article II). */
+export declare class ReadCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: ReadCapability;
+    constructor(capability: ReadCapability);
+}
+/**
+ * May this process drive Things over Apple Events, and on whose authority?
+ *
+ * The deputy wins when it is onboarded (its own handshake reports the grant it
+ * holds). Otherwise the host app's own Automation record is read out of TCC —
+ * granted, denied, or, when there is no record at all, `direct-unknown`. That
+ * last state is deliberately NOT resolved here: resolving it means sending a
+ * real Apple Event, which is what raises the dialog, and Article I reserves
+ * that for `things setup`.
+ */
+export declare function writeCapability(deps?: CapabilityDeps): WriteCapability;
+/** Thrown when app automation is refused for want of capability (Article II). */
+export declare class WriteCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: WriteCapability;
+    constructor(capability: WriteCapability);
+}
+/**
+ * The LAB's escape hatch, and deliberately not consumer surface. The VM lab and
+ * the guest e2e bundle drive the UI vector DIRECT — the in-guest Accessibility
+ * grant is held by the runner's own processes (the AXVM1 layer), there is no
+ * helper bundle in a disposable clone, and there is nobody to answer a dialog
+ * either. Setting this to `1` restores direct UI-vector availability for that
+ * one situation. It is documented in docs/lab/harness.md and exported by the
+ * lab's guest environment; nothing consumer-facing mentions it, and it does not
+ * bypass `ui.enabled` — a lab clone still sets that key explicitly.
+ */
+export declare const UI_DIRECT_ESCAPE_ENV = "THINGS_API_UI_DIRECT";
+/**
+ * May this process drive the Things WINDOW, and on whose authority?
+ *
+ * Article IV admits exactly one provenance: the helper pair. Accessibility on a
+ * general-purpose host app (a terminal, an agent harness, an MCP host) has a
+ * blast radius far beyond Things, churns with every host update, and has no
+ * sane story at all over ssh — so direct AX is unsupported, and a refusal here
+ * names the config knob and `things helpers setup --gui` rather than raising an
+ * Accessibility prompt against whatever happens to be running us.
+ *
+ * Every answer is prompt-free: the config key is a file read, and the deputy's
+ * `hello` carries `AXIsProcessTrusted()` plus its own `AEDeterminePermission`
+ * verdict for System Events.
+ */
+export declare function uiCapability(deps?: CapabilityDeps): UiCapability;
+/** Thrown when GUI-driving is refused for want of capability (Article IV). */
+export declare class UiCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: UiCapability;
+    constructor(capability: UiCapability);
+}
+/** Test seam: forget the one memo this module keeps (the host's display name). */
+export declare function resetCapabilityForTests(): void;