source-package.json — Message History Reader for iMessage and SMS

{
  "schema_version": 1,
  "runtimes": [
    {
      "name": "python",
      "versions": [
        "3.10"
      ]
    }
  ],
  "dependencies": [],
  "operations": [
    {
      "kind": "list",
      "description": "List conversations, participants, message counts and last dates from a read-only snapshot of the selected local Messages database. Entire database and regular sidecars are copied before filters, with a 128 MiB limit per input.",
      "target_restrictions": [
        "Only the user's own default database or the path selected with --db"
      ]
    },
    {
      "kind": "search",
      "description": "Search message text in a read-only snapshot, optionally filtering chats by participant, messages by sender, or by date bounds. Date/text filters apply during row iteration after the entire selected source has been copied.",
      "target_restrictions": [
        "Only the selected local database and caller-supplied search filters"
      ]
    },
    {
      "kind": "create",
      "description": "Export one selected chat to a new or empty local --out directory as messages.jsonl and transcript.txt after a matching dry-run digest is approved.",
      "target_restrictions": [
        "Only the exact --out directory selected by the caller and the two declared export files",
        "Create-only file opens refuse existing paths and symlinks; export requires --approve matching the current --dry-run digest"
      ]
    }
  ],
  "authorization": {
    "mode": "none",
    "scopes": [],
    "credential_requirements": []
  },
  "network": {
    "domains": [],
    "destinations": [
      "Local --out directory selected by the caller; no network destination or network request"
    ]
  },
  "safety": {
    "read_only_by_default": true,
    "dry_run_supported": true,
    "consequential_writes_require_authorization": true,
    "validation_controls": [
      "The database is copied with available -wal and -shm sidecars into a private temporary directory, then opened using SQLite mode=ro; the temporary copy is removed after use",
      "Export --dry-run creates no export files, still creates and removes the temporary database copy, and prints a digest binding the selected chat, destination and exact output content",
      "Live export refuses a missing or mismatched --approve digest and opens output files create-only without following symlinks",
      "Human-readable message and participant text is escaped onto one line; JSON retains JSON encoding",
      "Undecodable attributedBody values and refused symlink or irregular sidecars are listed as skipped and marked incomplete; exit status is 2 unless --allow-partial",
      "No environment configuration is required; standard-library tempfile honours TMPDIR, and Path.home/expanduser honour HOME for default and tilde paths",
      "macOS only with POSIX directory-descriptor and no-follow APIs; unsupported systems fail before I/O",
      "Selected absolute or relative paths reject parent traversal, percent-encoded forms, backslashes and symlink ancestors; source reads use pinned directory descriptors",
      "Each database or sidecar is limited to 128 MiB before and during copying; no stdin read; copies are sequential, not an atomic live snapshot",
      "Export digest binds resolved destination, parent and existing output device/inode identities, creation action, selected chat and rendered content; only selected destination may be created, never parents",
      "Export walks directories with O_DIRECTORY|O_NOFOLLOW, checks identities and writes relative to directory fd with O_CREAT|O_EXCL|O_NOFOLLOW; errors may leave partial output",
      "Malformed files/schema and text/sender/direction/identifiers are operational errors; invalid dates and unsupported bodies are explicitly skipped"
    ],
    "target_restrictions": [
      "Only the user's own default database or exact path selected with --db",
      "Only the --out directory selected by the caller for an approved single-chat export",
      "No network calls or telemetry",
      "Temporary copies are created in the standard-library temporary directory, honouring TMPDIR, and removed after each database read"
    ]
  },
  "tests": {
    "files": [
      "tests/test_message_history_reader.py",
      "tests/test_hygiene.py"
    ],
    "fixtures": "synthetic_only",
    "provenance": "creator",
    "evidence": [
      "Creator-authored standard-library unittest suite builds synthetic SQLite databases at test time and invokes the CLI as a subprocess",
      "Covers database snapshots, chats, search, timestamps, typedstream extraction, partial results, escaped output and approval-gated create-only export",
      "Hygiene test checks signatures, identity patterns and invisible characters",
      "Synthetic tests cover real parent symlink swaps, output inode swaps, no ancestor creation, path traversal, unsupported platforms, malformed input and bounded reads"
    ]
  }
}

License: MIT (read it).

Back to the listing