things-api 0.17.0 → 0.19.0

package/deputy/src/main.swift

@@ -0,0 +1,133 @@
+/**
+ * things-deputy — the TCC permission broker for the things CLI.
+ *
+ * A deliberately dumb, launchd-supervised proxy: it executes read-only SQL
+ * against the Things database, runs osascript with fixed argument shapes, and
+ * reads files inside the Things group container — nothing else. All product
+ * logic (validation, guards, verification, audit) stays in the TypeScript
+ * library; the deputy exists solely so macOS TCC grants (Automation,
+ * Accessibility, group-container reads) attach to ONE stable signed identity
+ * instead of whichever agent harness happens to invoke the CLI this week.
+ *
+ * Security posture (docs/design/agent-daemon.md §β1):
+ * - UNIX socket + token file live in a 0700 state dir; socket and token are 0600.
+ * - Every connection is peer-checked (same-UID) and every request carries the token.
+ * - SQL runs on a SQLITE_OPEN_READONLY connection with ATTACH denied by an
+ *   authorizer — the connection cannot write and cannot reach other files.
+ * - osascript is invoked at a fixed absolute path with exactly two argv shapes
+ *   (`-e <script>` / `-l JavaScript -e <script>`); the client never supplies argv.
+ * - File reads are confined to the resolved Things group container subtree.
+ * - Every request lands in a local JSONL audit log (hashes, never content).
+ *
+ * The deputy never daemonizes itself: launchd (or a test harness) owns the
+ * process lifecycle. There is exactly one run mode — foreground.
+ */
+import Foundation
+
+let PROTOCOL_VERSION = 1
+let MAX_REQUEST_BYTES = 8 * 1024 * 1024
+let MAX_FILE_READ_BYTES = 64 * 1024 * 1024
+
+struct DeputyPaths {
+  let stateDir: String
+  var socket: String { stateDir + "/deputy.sock" }
+  var token: String { stateDir + "/token" }
+  var log: String { stateDir + "/deputy.log" }
+  var config: String { stateDir + "/deputy.json" }
+}
+
+/// Deputy-local overrides, read once at startup from `<state-dir>/deputy.json`.
+/// The state dir is 0700, so anything able to write this file already owns the
+/// user account; the overrides exist for tests and non-standard installs.
+struct DeputyConfig {
+  var osascriptPath: String?
+  var shortcutsPath: String?
+
+  static func load(path: String) -> DeputyConfig {
+    var cfg = DeputyConfig()
+    guard let data = FileManager.default.contents(atPath: path),
+      let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+    else { return cfg }
+    cfg.osascriptPath = obj["osascriptPath"] as? String
+    cfg.shortcutsPath = obj["shortcutsPath"] as? String
+    return cfg
+  }
+}
+
+func defaultStateDir() -> String {
+  let env = ProcessInfo.processInfo.environment
+  if let explicit = env["THINGS_API_STATE_DIR"], !explicit.isEmpty {
+    return explicit + "/deputy"
+  }
+  let base =
+    (env["XDG_STATE_HOME"]).flatMap { $0.isEmpty ? nil : $0 }
+    ?? NSHomeDirectory() + "/.local/state"
+  return base + "/things-api/deputy"
+}
+
+func loadOrCreateToken(path: String) -> String {
+  if let data = FileManager.default.contents(atPath: path) {
+    let tok = String(decoding: data, as: UTF8.self).trimmingCharacters(in: .whitespacesAndNewlines)
+    if !tok.isEmpty { return tok }
+  }
+  var bytes = [UInt8](repeating: 0, count: 32)
+  for i in 0..<bytes.count { bytes[i] = UInt8.random(in: 0...255) }
+  let tok = bytes.map { String(format: "%02x", $0) }.joined()
+  FileManager.default.createFile(
+    atPath: path, contents: Data(tok.utf8), attributes: [.posixPermissions: 0o600])
+  return tok
+}
+
+// --- entry ---
+
+var stateDirArg: String? = nil
+var argIter = CommandLine.arguments.dropFirst().makeIterator()
+while let arg = argIter.next() {
+  switch arg {
+  case "--state-dir":
+    stateDirArg = argIter.next()
+  case "--version":
+    print(DEPUTY_VERSION)
+    exit(0)
+  default:
+    FileHandle.standardError.write(Data("things-deputy: unknown argument \(arg)\n".utf8))
+    exit(2)
+  }
+}
+
+let paths = DeputyPaths(stateDir: stateDirArg ?? defaultStateDir())
+do {
+  try FileManager.default.createDirectory(
+    atPath: paths.stateDir, withIntermediateDirectories: true,
+    attributes: [.posixPermissions: 0o700])
+} catch {
+  FileHandle.standardError.write(
+    Data("things-deputy: cannot create state dir \(paths.stateDir): \(error)\n".utf8))
+  exit(1)
+}
+
+let config = DeputyConfig.load(path: paths.config)
+let token = loadOrCreateToken(path: paths.token)
+let server = Server(paths: paths, config: config, token: token)
+
+signal(SIGPIPE, SIG_IGN)
+signal(SIGTERM, SIG_IGN)
+signal(SIGINT, SIG_IGN)
+let termSource = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .main)
+let intSource = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
+for source in [termSource, intSource] {
+  source.setEventHandler {
+    // Graceful drain: stop accepting, let in-flight requests finish (bounded),
+    // then remove the socket and exit cleanly. An upgrade boots the old
+    // process out mid-flight, and a request in progress must not die with it.
+    server.drainAndShutdown()
+    exit(0)
+  }
+  source.resume()
+}
+
+// The accept loop runs on a background thread; the MAIN thread must sit in
+// dispatchMain() so the signal sources above (queued on .main) actually fire —
+// a main thread blocked in accept() would ignore SIGTERM forever.
+Thread.detachNewThread { server.run() }
+dispatchMain()

package/deputy/src/osascript.swift

@@ -0,0 +1,102 @@
+/**
+ * osascript execution with a hard timeout. The deputy owns the child process:
+ * a caller (or its whole harness) dying mid-request never orphans an
+ * osascript — the deputy's timer terminates it at the requested deadline
+ * (SIGTERM, then SIGKILL after a 2s grace). Argv shapes are fixed here; the
+ * client supplies only the script text, language, and timeout.
+ */
+import CryptoKit
+import Foundation
+
+private final class Flag {
+  private let lock = NSLock()
+  private var value = false
+  func set() {
+    lock.lock()
+    value = true
+    lock.unlock()
+  }
+  func get() -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return value
+  }
+}
+
+func runOsascript(script: String, lang: String, timeoutMs: Int, binPath: String, id: Any?)
+  -> [String: Any]
+{
+  runChildTool(
+    binPath: binPath,
+    args: lang == "javascript" ? ["-l", "JavaScript", "-e", script] : ["-e", script],
+    timeoutMs: timeoutMs, id: id)
+}
+
+/// Generic deadline-bounded child runner shared by the osascript and
+/// shortcuts verbs. Argv is always assembled deputy-side from a fixed shape.
+func runChildTool(binPath: String, args: [String], timeoutMs: Int, id: Any?) -> [String: Any] {
+  let process = Process()
+  process.executableURL = URL(fileURLWithPath: binPath)
+  process.arguments = args
+  let outPipe = Pipe()
+  let errPipe = Pipe()
+  process.standardOutput = outPipe
+  process.standardError = errPipe
+  process.standardInput = FileHandle.nullDevice
+
+  do {
+    try process.run()
+  } catch {
+    return [
+      "id": id ?? NSNull(), "ok": false,
+      "error": ["code": "internal", "message": "cannot launch \(binPath): \(error.localizedDescription)"],
+    ]
+  }
+
+  let timedOut = Flag()
+  let pid = process.processIdentifier
+  let killer = DispatchWorkItem {
+    timedOut.set()
+    process.terminate()
+    DispatchQueue.global().asyncAfter(deadline: .now() + 2.0) {
+      if process.isRunning { kill(pid, SIGKILL) }
+    }
+  }
+  DispatchQueue.global().asyncAfter(
+    deadline: .now() + .milliseconds(max(1, timeoutMs)), execute: killer)
+
+  // Drain both pipes off-thread so a chatty script never deadlocks the wait.
+  var outData = Data()
+  var errData = Data()
+  let group = DispatchGroup()
+  group.enter()
+  DispatchQueue.global().async {
+    outData = outPipe.fileHandleForReading.readDataToEndOfFile()
+    group.leave()
+  }
+  group.enter()
+  DispatchQueue.global().async {
+    errData = errPipe.fileHandleForReading.readDataToEndOfFile()
+    group.leave()
+  }
+  process.waitUntilExit()
+  killer.cancel()
+  group.wait()
+
+  var result: [String: Any] = [
+    "id": id ?? NSNull(),
+    "ok": true,
+    "exitCode": Int(process.terminationStatus),
+    "stdout": String(decoding: outData, as: UTF8.self),
+    "stderr": String(decoding: errData, as: UTF8.self),
+  ]
+  if process.terminationReason == .uncaughtSignal {
+    result["signal"] = Int(process.terminationStatus)
+  }
+  if timedOut.get() { result["timedOut"] = true }
+  return result
+}
+
+func sha256Hex(_ text: String) -> String {
+  SHA256.hash(data: Data(text.utf8)).map { String(format: "%02x", $0) }.joined()
+}

package/deputy/src/server.swift

@@ -0,0 +1,373 @@
+/**
+ * Socket server: accept loop, peer verification, JSON-lines framing, request
+ * dispatch, and the local JSONL audit log. One thread per connection;
+ * osascript/shortcuts execution is funneled through one serial queue.
+ *
+ * MUTATIONS ONLY: the deputy serves the automation verbs (osascript,
+ * shortcuts). File verbs (sql / read-file / locate) live exclusively on the
+ * sandboxed things-reader — the deputy's own container access would ride the
+ * per-process AppData consent class (a prompt per process instance, measured
+ * 2026-08-21), which is precisely the churn this pair exists to end.
+ */
+import Foundation
+
+/// How long a shutting-down deputy waits for requests already in flight. An
+/// upgrade (`things helpers setup` / `restart`) boots the old process out
+/// mid-flight; without a drain the in-flight request dies with it. launchd's
+/// own bootout wait, and the CLI's `launchctl` timeout, both clear this bound.
+let DRAIN_TIMEOUT_SECONDS: TimeInterval = 10
+
+final class Server {
+  let paths: DeputyPaths
+  let config: DeputyConfig
+  let token: String
+  let startedAt = Date()
+  private let osaQueue = DispatchQueue(label: "things-deputy.osa")
+  private let logQueue = DispatchQueue(label: "things-deputy.log")
+  private var listenFd: Int32 = -1
+  /// Requests between dispatch and their written response. Guarded by
+  /// `inflightCond`, which the drain waits on.
+  private let inflightCond = NSCondition()
+  private var inflight = 0
+
+  init(paths: DeputyPaths, config: DeputyConfig, token: String) {
+    self.paths = paths
+    self.config = config
+    self.token = token
+  }
+
+  func run() {
+    let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+    guard fd >= 0 else { fatalDie("socket() failed: errno \(errno)") }
+    listenFd = fd
+
+    let sockPath = paths.socket
+    guard sockPath.utf8.count <= 103 else {
+      fatalDie("socket path too long for sockaddr_un (\(sockPath.utf8.count) bytes): \(sockPath)")
+    }
+    unlink(sockPath)
+    var addr = sockaddr_un()
+    addr.sun_family = sa_family_t(AF_UNIX)
+    let pathCapacity = MemoryLayout.size(ofValue: addr.sun_path)
+    _ = withUnsafeMutablePointer(to: &addr.sun_path) { pathPtr in
+      sockPath.withCString { cstr in
+        strncpy(
+          UnsafeMutableRawPointer(pathPtr).assumingMemoryBound(to: CChar.self), cstr,
+          pathCapacity - 1)
+      }
+    }
+    let bindResult = withUnsafePointer(to: &addr) { ptr in
+      ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { sa in
+        bind(fd, sa, socklen_t(MemoryLayout<sockaddr_un>.size))
+      }
+    }
+    guard bindResult == 0 else { fatalDie("bind(\(sockPath)) failed: errno \(errno)") }
+    chmod(sockPath, 0o600)
+    guard listen(fd, 16) == 0 else { fatalDie("listen() failed: errno \(errno)") }
+
+    audit(["event": "started", "pid": Int(getpid()), "version": DEPUTY_VERSION])
+
+    while true {
+      let conn = accept(fd, nil, nil)
+      if conn < 0 {
+        if errno == EINTR { continue }
+        break
+      }
+      var uid: uid_t = 0
+      var gid: gid_t = 0
+      if getpeereid(conn, &uid, &gid) != 0 || uid != getuid() {
+        audit(["event": "rejected-peer", "uid": Int(uid)])
+        close(conn)
+        continue
+      }
+      let thread = Thread { [weak self] in self?.handleConnection(conn) }
+      thread.name = "things-deputy.conn"
+      thread.start()
+    }
+  }
+
+  /**
+   * Graceful drain, then teardown. Order matters:
+   *
+   * 1. unlink the socket path FIRST — a new client cannot even find us, which
+   *    is deterministic where waking a thread blocked in accept() is not.
+   * 2. close the listener so no further connection is accepted.
+   * 3. wait (bounded) for requests already dispatched to write their response.
+   * 4. flush the audit log and return; the caller exits 0.
+   *
+   * SIGKILL remains the hard stop — nothing here tries to survive it.
+   */
+  func drainAndShutdown(timeout: TimeInterval = DRAIN_TIMEOUT_SECONDS) {
+    unlink(paths.socket)
+    if listenFd >= 0 {
+      Darwin.shutdown(listenFd, SHUT_RDWR)
+      close(listenFd)
+      listenFd = -1
+    }
+    let deadline = Date().addingTimeInterval(timeout)
+    inflightCond.lock()
+    while inflight > 0 && Date() < deadline {
+      _ = inflightCond.wait(until: deadline)
+    }
+    let remaining = inflight
+    inflightCond.unlock()
+    audit(["event": "stopped", "drained": remaining == 0, "inflight": remaining])
+    // The audit log is written asynchronously; a barrier makes "stopped" the
+    // last thing on disk instead of a line lost to exit().
+    logQueue.sync {}
+  }
+
+  private func beginRequest() {
+    inflightCond.lock()
+    inflight += 1
+    inflightCond.unlock()
+  }
+
+  private func endRequest() {
+    inflightCond.lock()
+    inflight -= 1
+    if inflight == 0 { inflightCond.broadcast() }
+    inflightCond.unlock()
+  }
+
+  private func fatalDie(_ message: String) -> Never {
+    FileHandle.standardError.write(Data("things-deputy: \(message)\n".utf8))
+    exit(1)
+  }
+
+  // --- connection handling ---
+
+  private func handleConnection(_ conn: Int32) {
+    defer { close(conn) }
+    var peerPid: pid_t = 0
+    var pidLen = socklen_t(MemoryLayout<pid_t>.size)
+    _ = getsockopt(conn, SOL_LOCAL, LOCAL_PEERPID, &peerPid, &pidLen)
+
+    var buffer = Data()
+    var chunk = [UInt8](repeating: 0, count: 65536)
+    while true {
+      let n = read(conn, &chunk, chunk.count)
+      if n <= 0 { return }
+      buffer.append(contentsOf: chunk[0..<n])
+      if buffer.count > MAX_REQUEST_BYTES {
+        writeLine(conn, errorResponse(id: nil, code: "too-large", message: "request exceeds \(MAX_REQUEST_BYTES) bytes"))
+        return
+      }
+      while let nl = buffer.firstIndex(of: 0x0A) {
+        let line = buffer.subdata(in: buffer.startIndex..<nl)
+        buffer.removeSubrange(buffer.startIndex...nl)
+        // In flight from dispatch until the response is on the wire — that
+        // span is exactly what a drain must not cut short.
+        beginRequest()
+        let response = dispatch(line: line, peerPid: peerPid)
+        let written = writeLine(conn, response)
+        endRequest()
+        if !written { return }
+      }
+    }
+  }
+
+  @discardableResult
+  private func writeLine(_ conn: Int32, _ obj: [String: Any]) -> Bool {
+    guard var data = try? JSONSerialization.data(withJSONObject: obj) else { return false }
+    data.append(0x0A)
+    return data.withUnsafeBytes { raw in
+      var offset = 0
+      while offset < raw.count {
+        let n = write(conn, raw.baseAddress!.advanced(by: offset), raw.count - offset)
+        if n <= 0 { return false }
+        offset += n
+      }
+      return true
+    }
+  }
+
+  private func errorResponse(id: Any?, code: String, message: String) -> [String: Any] {
+    ["id": id ?? NSNull(), "ok": false, "error": ["code": code, "message": message]]
+  }
+
+  // --- dispatch ---
+
+  private func dispatch(line: Data, peerPid: pid_t) -> [String: Any] {
+    guard let obj = (try? JSONSerialization.jsonObject(with: line)) as? [String: Any] else {
+      return errorResponse(id: nil, code: "bad-request", message: "request is not a JSON object")
+    }
+    let id = obj["id"]
+    guard let v = obj["v"] as? Int, v == PROTOCOL_VERSION else {
+      return errorResponse(
+        id: id, code: "unsupported-protocol",
+        message: "deputy speaks protocol \(PROTOCOL_VERSION); restart or rebuild the deputy (things helpers restart)")
+    }
+    guard let reqToken = obj["token"] as? String, reqToken == token else {
+      audit(["event": "rejected-token", "peerPid": Int(peerPid)])
+      return errorResponse(id: id, code: "bad-token", message: "request token does not match the deputy token file")
+    }
+    guard let verb = obj["verb"] as? String else {
+      return errorResponse(id: id, code: "bad-request", message: "missing verb")
+    }
+
+    let started = Date()
+    var result: [String: Any]
+    var auditExtra: [String: Any] = [:]
+    switch verb {
+    case "hello":
+      result = handleHello(id: id)
+    case "prime-ax":
+      result = handlePrimeAx(id: id)
+    case "osascript":
+      guard let script = obj["script"] as? String else {
+        result = errorResponse(id: id, code: "bad-request", message: "osascript verb requires a script string")
+        break
+      }
+      let lang = obj["lang"] as? String ?? "applescript"
+      guard lang == "applescript" || lang == "javascript" else {
+        result = errorResponse(id: id, code: "bad-request", message: "lang must be applescript or javascript")
+        break
+      }
+      let timeoutMs = obj["timeoutMs"] as? Int ?? 30_000
+      if let guardError = scriptGuard(script) {
+        audit(["event": "rejected-script", "reason": guardError, "peerPid": Int(peerPid)])
+        result = errorResponse(id: id, code: "script-denied", message: guardError)
+        break
+      }
+      auditExtra["scriptSha256"] = sha256Hex(script)
+      auditExtra["scriptBytes"] = script.utf8.count
+      result = osaQueue.sync {
+        runOsascript(
+          script: script, lang: lang, timeoutMs: timeoutMs,
+          binPath: config.osascriptPath ?? "/usr/bin/osascript", id: id)
+      }
+    case "shortcuts":
+      let op = obj["op"] as? String
+      let timeoutMs = obj["timeoutMs"] as? Int ?? 30_000
+      let bin = config.shortcutsPath ?? "/usr/bin/shortcuts"
+      if op == "list" {
+        result = osaQueue.sync { runChildTool(binPath: bin, args: ["list"], timeoutMs: timeoutMs, id: id) }
+        break
+      }
+      guard op == "run", let name = obj["name"] as? String,
+        let inputPath = obj["inputPath"] as? String,
+        let outputPath = obj["outputPath"] as? String
+      else {
+        result = errorResponse(
+          id: id, code: "bad-request",
+          message: "shortcuts verb requires op=list, or op=run with name/inputPath/outputPath")
+        break
+      }
+      // The deputy only runs this library's bundled proxy shortcuts — it is a
+      // paired tool, not a general shortcut runner. (Same spirit as the
+      // osascript shell-execution lint: a same-user process could run
+      // arbitrary shortcuts itself; it just cannot do so AS the deputy.)
+      guard name.hasPrefix("things-proxy-"), !inputPath.hasPrefix("-"), !outputPath.hasPrefix("-")
+      else {
+        audit(["event": "rejected-shortcut", "name": name, "peerPid": Int(peerPid)])
+        result = errorResponse(
+          id: id, code: "shortcut-denied",
+          message: "the deputy only runs bundled things-proxy-* shortcuts")
+        break
+      }
+      auditExtra["shortcut"] = name
+      result = osaQueue.sync {
+        runChildTool(
+          binPath: bin,
+          args: ["run", name, "--input-path", inputPath, "--output-path", outputPath],
+          timeoutMs: timeoutMs, id: id)
+      }
+    case "sql", "read-file", "locate":
+      // File verbs live exclusively on the sandboxed things-reader.
+      result = errorResponse(
+        id: id, code: "unsupported-verb",
+        message: "the deputy serves automation verbs only — file access rides things-reader (things helpers setup)")
+    default:
+      result = errorResponse(id: id, code: "bad-request", message: "unknown verb \(verb)")
+    }
+
+    var entry: [String: Any] = [
+      "ts": iso8601(Date()),
+      "verb": verb,
+      "peerPid": Int(peerPid),
+      "ok": (result["ok"] as? Bool) ?? false,
+      "ms": Int(Date().timeIntervalSince(started) * 1000),
+    ]
+    for (k, v) in auditExtra { entry[k] = v }
+    audit(entry)
+    return result
+  }
+
+  /**
+   * Defense-in-depth lint, not a security boundary (a same-user process that
+   * can read the token can also run osascript itself — what the deputy adds is
+   * only its OWN TCC grants). The lint refuses the constructs that would turn
+   * "drive the Things GUI" into "run arbitrary shell": every legitimate script
+   * this library generates talks AppleScript/JXA to Things and System Events
+   * and never shells out.
+   */
+  private func scriptGuard(_ script: String) -> String? {
+    let lowered = script.lowercased()
+    for banned in ["do shell script", "do script"] {
+      if lowered.contains(banned) {
+        return "script rejected: contains \"\(banned)\" — the deputy only brokers GUI/AppleEvent scripts, never shell execution"
+      }
+    }
+    return nil
+  }
+
+  // --- verb handlers ---
+
+  /**
+   * The handshake, plus the deputy's own TCC standing — Accessibility trust
+   * and Automation permission for each target it drives. Every field here is
+   * PROMPT-FREE by construction (see tcc.swift), which is what lets a status
+   * report and the onboarding ceremony ask "is this leg already granted?"
+   * without raising a dialog at whoever happens to run `things` next.
+   */
+  private func handleHello(id: Any?) -> [String: Any] {
+    [
+      "id": id ?? NSNull(),
+      "ok": true,
+      "protocol": PROTOCOL_VERSION,
+      "deputyVersion": DEPUTY_VERSION,
+      "role": "deputy",
+      "pid": Int(getpid()),
+      "uptimeMs": Int(Date().timeIntervalSince(startedAt) * 1000),
+      "axTrusted": accessibilityTrusted(),
+      "automation": [
+        "things": automationStatus(bundleID: "com.culturedcode.ThingsMac"),
+        "systemEvents": automationStatus(bundleID: "com.apple.systemevents"),
+      ],
+    ]
+  }
+
+  /**
+   * Raise the Accessibility consent dialog for the deputy's own identity. The
+   * grant itself is a toggle in System Settings, so the answer can only arrive
+   * later — the caller polls `hello`'s axTrusted. Returns the state as of now.
+   */
+  private func handlePrimeAx(id: Any?) -> [String: Any] {
+    ["id": id ?? NSNull(), "ok": true, "axTrusted": primeAccessibility()]
+  }
+
+  // --- audit log ---
+
+  private func audit(_ entry: [String: Any]) {
+    var withTs = entry
+    if withTs["ts"] == nil { withTs["ts"] = iso8601(Date()) }
+    guard var data = try? JSONSerialization.data(withJSONObject: withTs) else { return }
+    data.append(0x0A)
+    let path = paths.log
+    logQueue.async {
+      if let handle = FileHandle(forWritingAtPath: path) {
+        handle.seekToEndOfFile()
+        handle.write(data)
+        try? handle.close()
+      } else {
+        FileManager.default.createFile(
+          atPath: path, contents: data, attributes: [.posixPermissions: 0o600])
+      }
+    }
+  }
+}
+
+func iso8601(_ date: Date) -> String {
+  ISO8601DateFormatter().string(from: date)
+}