Security remediation: credentials hygiene, HTTP safety, output safety, typed errors, test suite

Addresses several classes of defects in the existing codebase. None of
these changes alter the public CLI surface beyond removing the
--password flag.

Credentials & logging
- Load the OAuth client secret from SIMPLIFI_CLIENT_SECRET instead of
  embedding it in source. Missing env var raises a clear RuntimeError.
- Remove --password CLI argument. Password is resolved from
  SIMPLIFI_PASSWORD or, on a TTY, prompted via getpass.getpass().
- MFA code is now read via getpass.getpass() rather than input(), so it
  does not echo or enter readline history.
- The bearer token, refresh token, MFA channel (a masked but still
  user-identifying string), and Simplifi user id are no longer logged
  at any level.

HTTP hygiene & SSRF
- Every requests call passes timeout=30. No more indefinite hangs.
- Pagination follows an upstream-supplied nextLink: that value is now
  validated to be either a relative path or an absolute URL on
  https://services.quicken.com/ before the bearer token is sent.
- The get_datasets query-string used the variable name 'limit' as a
  dict key instead of the string literal 'limit', so the limit was
  never actually sent. Fixed.
- Every JSON decode is wrapped: malformed bodies raise a typed
  SimplifiAPIError instead of bubbling a raw JSONDecodeError.

Typed exception hierarchy
- New simplifiapi.exceptions module defines SimplifiAPIError and an
  AuthenticationError subclass.
- Client methods raise these instead of returning None / False on
  failure (verify_token now raises on failure and installs the bearer
  header on success).
- The CLI main() catches SimplifiAPIError at the boundary and
  SystemExits with a one-line message — no Python traceback that could
  echo URL params or partial headers.

Output safety
- --filename runs through os.path.basename so '../../tmp/evil' cannot
  escape CWD.
- CSV cells whose first character is = + - or @ are prefixed with a
  single quote (formula-injection escape).
- JSON output is opened 'w' with utf-8 encoding (was 'w+', no encoding,
  which mangled non-ASCII on Windows cp1252 locales).

Quality cleanups
- Collapse four near-identical resource getters
  (get_accounts/transactions/tags/categories) into _get_resource.
- Library is logging-pure: __init__ attaches only a NullHandler; real
  log config lives in cli.main's _configure_logging() and honours
  LOG_LEVEL.
- Migrate project metadata to pyproject.toml [project] (PEP 621),
  drop the broken 'name = setuptools' setup.cfg metadata block.
- Pin runtime deps: requests>=2.31,<3, pandas>=2,<3, configargparse>=1.7,<2.
- Add .env.example template for SIMPLIFI_CLIENT_SECRET and
  SIMPLIFI_PASSWORD.

Tests
- New pytest + responses suite covering the cases above (auth happy
  path, MFA, pagination key, SSRF rejection, timeout presence,
  CSV formula escape, --filename basename strip, JSON-decode safety,
  typed exception boundary). 33 tests; coverage configured to fail
  under 80% (currently 91%).

README is rewritten to document the trust model, the new CLI surface,
the typed-exception API, and a development setup.

Author: mikesmith-stack

.env.example

@@ -0,0 +1,37 @@
+# .env.example — copy to .env and fill in real values.
+#
+# `.env` is excluded by .gitignore; this file (.env.example) is committed
+# as a template. NEVER commit a populated .env.
+#
+# Usage:
+#     cp .env.example .env
+#     # edit .env with real values
+#     set -a && source .env && set +a   # POSIX shells
+#     # or on Windows PowerShell: Get-Content .env | ForEach-Object { ... }
+#     # then run:
+#     python -m simplifiapi --email you@example.com --accounts
+
+# ---------------------------------------------------------------------------
+# SIMPLIFI_CLIENT_SECRET (required)
+# ---------------------------------------------------------------------------
+# The OAuth client secret used by the embedded `acme_web` client when calling
+# https://services.quicken.com/oauth/token. In upstream rijn/simplifiapi this
+# value was hardcoded in the source; this fork removed the literal and reads
+# it from this env var at call time (see Phase 1, AUDIT.md finding C1).
+#
+# Trust model: Quicken cannot revoke this secret per-user. Anyone with the
+# value can impersonate the `acme_web` OAuth client. Treat it like a
+# moderately-sensitive shared secret. See README.md > Security & Trust Model.
+SIMPLIFI_CLIENT_SECRET=replace-me-with-the-real-oauth-client-secret
+
+# ---------------------------------------------------------------------------
+# SIMPLIFI_PASSWORD (optional — used only when --token is not supplied)
+# ---------------------------------------------------------------------------
+# Your Quicken Simplifi account password. Used by `Client.get_token` to
+# authenticate. If unset and the tool needs to authenticate, it will fall
+# back to `getpass.getpass()` and prompt interactively (only when stdin is
+# a TTY). See Phase 1, AUDIT.md finding C2.
+#
+# NEVER put this on the command line — `--password` was removed in Phase 1
+# precisely because argv leaks via `ps`, shell history, and syslog.
+SIMPLIFI_PASSWORD=replace-me-with-your-simplifi-password

.gitignore

@@ -158,3 +158,11 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# simplifiapi CLI output — these contain real account/transaction data.
+# The CLI writes <filename>_<resource>.{json,csv} (default filename: 'output').
+# Never commit these.
+/output_*.json
+/output_*.csv
+/test_*.json
+/test_*.csv

README.md

@@ -1,62 +1,157 @@
 # simplifiapi
-An unofficial API for Quicken Simplifi
+
+An unofficial CLI and Python library for extracting your own Quicken Simplifi data — accounts, transactions, tags, and categories — to JSON or CSV.
+
+## Security & Trust Model
+
+This is an **unofficial** client for Quicken Simplifi. Before running it against your real account, understand the trust model:
+
+- **OAuth client secret comes from your environment.** The OAuth client secret is no longer embedded in source. You must set `SIMPLIFI_CLIENT_SECRET` in your environment before invoking the CLI or the `Client` class. If it is unset, the tool fails loudly rather than silently proceeding.
+- **Your Simplifi account password is never accepted on argv.** The `--password` CLI flag has been removed (it leaked via `ps`, shell history, and syslog). Provide your password by either setting `SIMPLIFI_PASSWORD` in your environment, or by letting the CLI prompt you via `getpass.getpass()` when run interactively. Non-interactive runs with no env var exit with a clear error.
+- **MFA codes are read via `getpass.getpass()`** — they do not echo to the terminal and do not enter readline history.
+- **The bearer token, refresh token, and Simplifi user id are never logged** at any level.
+- **HTTP calls are timeout-bounded and host-guarded.** Every request carries a 30-second timeout. The `nextLink` value returned by Quicken during pagination is validated: it must be either a relative path or an absolute URL on `https://services.quicken.com/`. Anything else is rejected before the bearer token is sent.
+- **`--filename` cannot escape the working directory.** Any path components in the value are stripped via `os.path.basename` before opening the output file.
+- **CSV output is formula-injection-safe.** Cells whose stringified value starts with `=`, `+`, `-`, or `@` are prefixed with a single quote before writing.
+- **The OAuth `clientSecret` cannot be rotated per-user.** Because this is an unofficial client, Quicken does not own a per-user relationship for the OAuth `clientSecret` and cannot revoke it for an individual user. Anyone running this client is implicitly accepting that the secret is shared across every user of the project. If the secret leaks, every user is affected — Quicken's only remediation would be invalidating the secret for the entire client, breaking the tool for everyone.
+- **Run in an isolated environment.** Treat `SIMPLIFI_CLIENT_SECRET` and `SIMPLIFI_PASSWORD` as sensitive. Prefer a dedicated shell, container, or VM where those env vars do not bleed into your normal development environment or any background process that snapshots `/proc/<pid>/environ`. Export them via a sourced `.env` file you do not commit, not by typing them at a prompt that lands in shell history.
+
+A starter `.env.example` is shipped at the repo root. Copy it to `.env` and fill in your values; do not commit `.env`.
 
 ## Install
 
-PyPI is temporarily down. Install with pip from GitHub directly
+Install from a clone of this repo:
 
 ```shell
-pip3 install git+https://github.com/rijn/simplifiapi
+# from a clone of this repo
+pip install .
+
+# or, in editable mode for local development
+pip install -e .
+
+# or, with dev/test extras (pytest + responses)
+pip install -e '.[dev]'
 ```
 
+Pinned runtime dependencies (from `pyproject.toml`): `requests>=2.31,<3`, `pandas>=2,<3`, `configargparse>=1.7,<2`. Python 3.9+.
+
 ## CLI
 
-This package provides a command-line tool that could access and save data to local files.
+The package installs a `simplifiapi` entry point that extracts data from your Simplifi account to local files.
+
+```shell
+usage: simplifiapi [-h] [--email [EMAIL]] [--token [TOKEN]] [--accounts]
+                   [--transactions] [--tags] [--categories]
+                   [--filename FILENAME] [--format {json,csv}]
+
+simplifiapi — extract Quicken Simplifi data to JSON or CSV. Requires the
+SIMPLIFI_CLIENT_SECRET environment variable to be set (the OAuth client secret
+is no longer embedded in source — see README.md > Security & Trust Model).
+
+options:
+  -h, --help           show this help message and exit
+  --email [EMAIL]      The e-mail address for your Quicken Simplifi account
+  --token [TOKEN]      Use existing token to bypass MFA check
+  --accounts           Retrieve accounts
+  --transactions       Retrieve transactions
+  --tags               Retrieve tags
+  --categories         Retrieve categories
+  --filename FILENAME  Write results to file with this prefix (path
+                       components stripped — see Security & Trust Model)
+  --format {json,csv}  The format used to return data.
+```
+
+### Examples
 
 ```shell
-usage: simplifiapi [-h] [--email [EMAIL]] [--password [PASSWORD]] [--token [TOKEN]] [--accounts] [--transactions] [--tags] [--categories] [--filename FILENAME] [--format {json,csv}]
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --email [EMAIL]       The e-mail address for your Quicken Simplifi account
-  --password [PASSWORD]
-                        The password for your Quicken Simplifi account
-  --token [TOKEN]       Use existing token to bypass MFA check
-  --accounts            Retrieve accounts
-  --transactions        Retrieve transactions
-  --tags                Retrieve tags
-  --categories          Retrieve categories
-  --filename FILENAME   Write results to file this prefix
-  --format {json,csv}   The format used to return data.
-
-examples:
-> simplifiapi --token="..." --transactions
-> simplifiapi --token="..." --transactions --filename=20231125 --format=csv
+# Interactive login: getpass prompts for password (and MFA code if challenged).
+SIMPLIFI_CLIENT_SECRET=... simplifiapi --email=you@example.com --transactions
+
+# Non-interactive: password from env, scrape to CSV with a date prefix.
+SIMPLIFI_CLIENT_SECRET=... SIMPLIFI_PASSWORD=... \
+    simplifiapi --email=you@example.com --transactions --filename=20251125 --format=csv
+
+# Reuse an existing bearer token (skip OAuth + MFA).
+SIMPLIFI_CLIENT_SECRET=... simplifiapi --token="..." --accounts --transactions
 ```
 
+Output files are written to the current working directory as `{filename}_{resource}.{format}` (e.g. `output_transactions.csv`). Any path separators or `..` segments in `--filename` are stripped before the file is opened.
+
+### Exit codes & errors
+
+The CLI catches `SimplifiAPIError` (and its `AuthenticationError` subclass) at the boundary and exits with a one-line `simplifiapi: <message>` instead of a Python traceback. Missing `SIMPLIFI_CLIENT_SECRET` is treated as a developer-environment error and fails loudly with a `RuntimeError` so it is not silently miscategorised as an auth failure.
+
+### Logging
+
+Set `LOG_LEVEL=DEBUG` to see the per-request pagination log. Bearer tokens, refresh tokens, MFA channels, and user IDs are never logged.
+
 ## Python API
 
-The `Client` class allows accessing from python script and making custom analysis.
+The `Client` class lets you call the same endpoints from your own scripts. Importing the package is logging-pure — it attaches only a `NullHandler` to the `simplifiapi` logger and does not touch root-level logging.
 
 ```python
+import os
+from simplifiapi import AuthenticationError, SimplifiAPIError
 from simplifiapi.client import Client
 
+# SIMPLIFI_CLIENT_SECRET must be set in the environment before calling get_token.
+# When calling Client directly, your code passes `password=` explicitly —
+# resolve it however you want (getpass, keyring, etc.), just don't read it
+# from sys.argv.
+os.environ["SIMPLIFI_CLIENT_SECRET"] = "<your-client-secret>"
+
 client = Client()
 
-# Provide either token or email/password
-token = "..."
-token = client.get_token(email=options.email, password=options.password)
+try:
+    # Option A: full OAuth + (optional) MFA flow.
+    token = client.get_token(email="you@example.com", password="<resolved-via-env-or-getpass>")
+
+    # Option B: reuse an existing bearer token instead of get_token.
+    # token = "..."
+
+    # verify_token raises AuthenticationError on a bad token and installs the
+    # bearer header on the session on success. It does not return a value.
+    client.verify_token(token)
+
+    # Datasets own transactions and accounts.
+    datasets = client.get_datasets()
+    if not datasets:
+        raise SystemExit("No datasets found for this account")
+    dataset_id = datasets[0]["id"]
+
+    # All four getters return list[dict] of fully-unpaginated resources.
+    transactions = client.get_transactions(dataset_id)
+    accounts     = client.get_accounts(dataset_id)
+    tags         = client.get_tags(dataset_id)
+    categories   = client.get_categories(dataset_id)
+except AuthenticationError as exc:
+    # OAuth / token-verify failure. Typed subclass of SimplifiAPIError.
+    raise SystemExit(f"auth failed: {exc}")
+except SimplifiAPIError as exc:
+    # Pagination, JSON-decode, or unsafe nextLink rejection.
+    raise SystemExit(f"api error: {exc}")
+```
+
+### Exception hierarchy
+
+Both exception types are re-exported from the package root:
 
-assert client.verify_token(token)
+- `SimplifiAPIError` — base class for all boundary errors raised by `Client` (bad HTTP status on a resource fetch, invalid JSON in a response, refusal to follow an unsafe `nextLink`).
+- `AuthenticationError` (subclass of `SimplifiAPIError`) — OAuth authorize/token failure, MFA mismatch, or `verify_token` failure.
 
-# Datasets own transactions and accounts
-datasets = client.get_datasets()
-datasetId = datasets[0]["id"]
+`RuntimeError` is raised separately when `SIMPLIFI_CLIENT_SECRET` is missing; it is intentionally not a `SimplifiAPIError` so the CLI does not catch and prettify it.
 
-# Access transactions
-transactions = client.get_transactions(datasetId)
+## Development
+
+```shell
+pip install -e '.[dev]'
+pytest                       # run the test suite
+pytest --cov                 # with coverage (gate is fail_under=80)
+pytest -k unit               # only unit-marked tests
 ```
 
+The test suite uses `pytest` + the `responses` library to mock the Quicken HTTP surface. Tests live under [tests/](tests/).
+
 ## Thanks
 
-This library is heavily inspired by [mintapi](https://github.com/mintapi/mintapi).
+This library is heavily inspired by [mintapi](https://github.com/mintapi/mintapi).

pyproject.toml

@@ -1,3 +1,70 @@
 [build-system]
-requires = ["setuptools"]
+requires = ["setuptools>=68"]
 build-backend = "setuptools.build_meta"
+
+[project]
+name = "simplifiapi"
+version = "0.1.0"
+description = "An unofficial CLI and Python library for extracting Quicken Simplifi accounts, transactions, tags, and categories to JSON or CSV."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "simplifiapi fork maintainers" }
+]
+keywords = ["simplifi", "quicken", "finance", "cli", "extraction"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "requests>=2.31,<3",
+    "pandas>=2,<3",
+    "configargparse>=1.7,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/rijn/simplifiapi"
+Source = "https://github.com/rijn/simplifiapi"
+Issues = "https://github.com/rijn/simplifiapi/issues"
+
+[project.scripts]
+simplifiapi = "simplifiapi.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7,<9",
+    "pytest-cov>=4,<6",
+    "responses>=0.23,<1",
+]
+
+[tool.setuptools.packages.find]
+include = ["simplifiapi*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "unit: unit tests with mocked HTTP",
+]
+
+[tool.coverage.run]
+source = ["simplifiapi"]
+branch = false
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = false

setup.cfg

@@ -1,18 +1,3 @@
-[metadata]
-name = setuptools
-version = 0.0.1
-
-[options]
-install_requires =
-    configargparse
-    pandas
-    requests
-packages = find:
-
-[options.entry_points]
-console_scripts =
-    simplifiapi = simplifiapi.cli:main
-
-[options.packages.find]
-exclude =
-    tests
+# Project metadata has been migrated to pyproject.toml [project] (PEP 621).
+# This file is intentionally left empty; do not re-add `[metadata]`, `[options]`,
+# or `[options.entry_points]` here — they belong in pyproject.toml.

simplifiapi/__init__.py

@@ -1,3 +1,19 @@
+"""simplifiapi — Quicken Simplifi extraction CLI (security-remediated fork).
+
+Importing this package attaches a no-op log handler to the
+``simplifiapi`` logger (the stdlib library idiom) so that library use
+without a configured root logger does not emit "No handlers could be
+found" warnings. It
+deliberately does not configure log levels or attach any other handler
+— that is the host application's job (and is done by
+``simplifiapi.cli.main`` for the CLI entry point). See
+``simplifiapi/cli.py::main`` for runtime log configuration.
+"""
+
 import logging
 
-logging.getLogger("simplifiapi").setLevel(logging.INFO)
+from simplifiapi.exceptions import AuthenticationError, SimplifiAPIError
+
+logging.getLogger("simplifiapi").addHandler(logging.NullHandler())
+
+__all__ = ["AuthenticationError", "SimplifiAPIError"]

simplifiapi/__main__.py

@@ -1,8 +1,10 @@
-from simplifiapi.cli import main
+"""Entry point for `python -m simplifiapi`.
 
-import logging
+All logging configuration lives in ``simplifiapi.cli.main``. This module
+is a thin delegating shim.
+"""
 
-logging.getLogger("simplifiapi").setLevel(logging.INFO)
+from simplifiapi.cli import main
 
 if __name__ == "__main__":
     main()