basic-ipfs 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luke Profits
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,7 @@
1
+ include SECURITY.md
2
+
3
+ # Defensive — should never happen, but make absolutely sure the auto-downloaded
4
+ # Kubo binary doesn't get pulled into a sdist if a developer has run tests.
5
+ prune basic_ipfs/bin
6
+ global-exclude *.pyc
7
+ global-exclude __pycache__
@@ -0,0 +1,343 @@
1
+ Metadata-Version: 2.4
2
+ Name: basic-ipfs
3
+ Version: 1.0.0
4
+ Summary: An intentionally tiny IPFS library for Python. Auto-manages a real Kubo node.
5
+ Author: Luke Profits
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Luke Profits
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Homepage, https://github.com/lukeprofits/basic-ipfs
29
+ Classifier: Programming Language :: Python :: 3
30
+ Classifier: License :: OSI Approved :: MIT License
31
+ Classifier: Operating System :: OS Independent
32
+ Requires-Python: >=3.9
33
+ Description-Content-Type: text/markdown
34
+ License-File: LICENSE
35
+ Requires-Dist: requests>=2.28
36
+ Requires-Dist: platformdirs>=3.0
37
+ Provides-Extra: dev
38
+ Requires-Dist: pytest>=7; extra == "dev"
39
+ Requires-Dist: build>=1.0; extra == "dev"
40
+ Requires-Dist: mypy>=1.10; extra == "dev"
41
+ Requires-Dist: ruff>=0.5; extra == "dev"
42
+ Requires-Dist: types-requests; extra == "dev"
43
+ Dynamic: license-file
44
+
45
+ # basic-ipfs
46
+
47
+ An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under the hood.
48
+
49
+ ### Description
50
+
51
+ `basic-ipfs` does exactly five things:
52
+
53
+ - Add a file or bytes to [IPFS](https://ipfs.tech/) and pin it (returns a [CID](https://docs.ipfs.tech/concepts/content-addressing/))
54
+ - Announce a file or bytes to IPFS without pinning (returns a CID — content may be GC'd)
55
+ - Get content back by CID (as bytes, or written to disk)
56
+ - Pin one CID or a list of CIDs (so they never get garbage-collected)
57
+ - Unpin one CID or a list of CIDs (idempotent — safe to re-run)
58
+
59
+ It also runs and manages a real [Kubo](https://github.com/ipfs/kubo) node for you — auto-downloaded on first use, auto-shutdown on exit. No daemon to install, no config files to edit, no accounts. (See [Privacy](#privacy) below — the default daemon does join the public IPFS network.)
60
+
61
+ I made `basic-ipfs` because no other Python packages make it this simple. Every existing client assumes you already have an IPFS daemon running. This one just works.
62
+
63
+ If it does exactly what you need → great, use it. If it doesn't → don't use it. Simple as that.
64
+
65
+ ### Install
66
+
67
+ ```
68
+ pip install basic-ipfs
69
+ ```
70
+
71
+ First call downloads the Kubo binary (~115 MB, SHA-512 verified) into your per-user data directory (`~/.local/share/basic_ipfs/bin/<platform>/ipfs` on Linux; `platformdirs` picks the right path per OS) and starts it as a background subprocess. The daemon stops automatically when your program exits.
72
+
73
+ ### Usage
74
+
75
+ ```python
76
+ import basic_ipfs
77
+
78
+ # Add — pins content permanently so it's never garbage-collected
79
+ cid = basic_ipfs.add("photo.jpg")
80
+ cid = basic_ipfs.add(b"hello world")
81
+
82
+ # Pass provide=False to skip the public-DHT announce (content stays
83
+ # locally addressable, but its presence is not broadcast)
84
+ cid = basic_ipfs.add(b"private data", provide=False)
85
+
86
+ # Announce — adds to IPFS without pinning; content may be GC'd later
87
+ cid = basic_ipfs.announce("photo.jpg")
88
+ cid = basic_ipfs.announce(b"temporary data")
89
+
90
+ # Just compute the CID locally — does NOT store, pin, or announce anything.
91
+ # Useful for previewing the CID of content you have not yet decided to publish.
92
+ cid = basic_ipfs.compute_cid_locally(b"hello world")
93
+ cid = basic_ipfs.compute_cid_locally("photo.jpg")
94
+
95
+ # Get — returns bytes, or writes to disk if you pass an output path
96
+ data = basic_ipfs.get(cid)
97
+ basic_ipfs.get(cid, "copy.jpg")
98
+
99
+ # Pin — one CID, or a whole list (one HTTP round-trip per ~500 CIDs)
100
+ basic_ipfs.pin(cid)
101
+ basic_ipfs.pin([cid1, cid2, cid3, ...])
102
+
103
+ # Unpin — same shape, always idempotent
104
+ basic_ipfs.unpin(cid)
105
+ basic_ipfs.unpin([cid1, cid2, cid3, ...])
106
+
107
+ # List all pinned CIDs
108
+ cids = basic_ipfs.get_all_pins() # → ['Qm...', 'baf...', ...]
109
+
110
+ # Debug info
111
+ basic_ipfs.status() # {peer_id, agent_version, repo_size_bytes, pinned_cids, ...}
112
+ ```
113
+
114
+ That's the core API. There are also helpers for networking, private
115
+ networks, identity rotation, and lockdown — see [Privacy](#privacy).
116
+
117
+ Explicit lifecycle, if you want it (you usually don't — the daemon starts lazily on the first call and stops on process exit):
118
+
119
+ ```python
120
+ basic_ipfs.start()
121
+ basic_ipfs.stop()
122
+
123
+ with basic_ipfs.node():
124
+ basic_ipfs.add(b"hi")
125
+ ```
126
+
127
+ All failures raise `basic_ipfs.IPFSError`. Subclasses, all with actionable messages:
128
+
129
+ - `IPFSBinaryNotFound` — Kubo missing and auto-download failed (no network, disk full, unsupported platform).
130
+ - `IPFSDaemonTimeout` — daemon didn't reach a healthy state in 60 s.
131
+ - `IPFSOperationError` — an `/api/v0/...` call returned an error.
132
+ - `IPFSPortInUse` — `API_PORT` (default 5001) is bound by something that isn't ours. Set `basic_ipfs.API_PORT` to something free.
133
+ - `IPFSRepoLocked` — another Kubo daemon already owns the repo. One process per repo.
134
+ - `IPFSRepoCorrupt` — repo on disk failed a sanity check. Investigate; don't auto-delete.
135
+
136
+ ### CLI
137
+
138
+ Installing the package also adds a `basic-ipfs` command:
139
+
140
+ ```
141
+ basic-ipfs status
142
+ basic-ipfs add photo.jpg # prints the CID, pins content
143
+ basic-ipfs announce photo.jpg # prints the CID, no pin (may be GC'd)
144
+ basic-ipfs add-folder ./mydir # recursive add + pin
145
+ basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
146
+ basic-ipfs get <cid> [output-path] # stdout or file
147
+ basic-ipfs pin <cid> [<cid> ...]
148
+ basic-ipfs unpin <cid> [<cid> ...]
149
+ basic-ipfs is-pinned <cid> # exit 0 if pinned, 1 if not
150
+ basic-ipfs exists <cid> # exit 0 if locally available
151
+ basic-ipfs pins # list all pinned CIDs
152
+ basic-ipfs gc # run garbage collection
153
+
154
+ # Networking
155
+ basic-ipfs peers # list connected peers
156
+ basic-ipfs my-addr # this node's shareable multiaddrs
157
+ basic-ipfs connect <multiaddr> # dial a peer
158
+
159
+ # Privacy
160
+ basic-ipfs create-private-network # generate swarm key (run before first op)
161
+ basic-ipfs join-private-network <key> # join an existing private network
162
+ basic-ipfs network-key # print this node's swarm key
163
+ basic-ipfs rotate-identity # new peer ID; daemon must be stopped
164
+ basic-ipfs lockdown # disable DHT, bootstrap, gateway fetch
165
+ ```
166
+
167
+ ### Config
168
+
169
+ Override module variables **before** the first call if you want non-defaults:
170
+
171
+ ```python
172
+ import basic_ipfs
173
+
174
+ basic_ipfs.APP_NAME = "MyApp" # changes default repo location
175
+ basic_ipfs.REPO_PATH = "/mnt/data/ipfs" # or pin an exact path
176
+ basic_ipfs.KUBO_VERSION = "v0.40.1" # must be in kubo_checksums.py
177
+ basic_ipfs.API_PORT = 5099 # if 5001 is taken
178
+ basic_ipfs.GATEWAY_PORT = 8099 # if 8080 is taken (or running 2 nodes)
179
+ basic_ipfs.SWARM_ADDRESSES = ["/ip4/127.0.0.1/tcp/4001"] # loopback-only swarm
180
+ basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
181
+ ```
182
+
183
+ Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
184
+
185
+ ### Two-node example
186
+
187
+ Anything you `add()` on one machine can be `get()`-ed on another that knows
188
+ your peer address. Smallest possible demo:
189
+
190
+ ```python
191
+ # Node A
192
+ import basic_ipfs
193
+ basic_ipfs.start()
194
+ ipv4, _ = basic_ipfs.my_node_multiaddress()
195
+ print("share this with node B:", ipv4)
196
+ cid = basic_ipfs.add(b"hello from A")
197
+ print("share this CID:", cid)
198
+ input("press enter to stop…")
199
+ ```
200
+
201
+ ```python
202
+ # Node B
203
+ import basic_ipfs
204
+ basic_ipfs.start()
205
+ basic_ipfs.connect_to_node("<ipv4 from node A>")
206
+ print(basic_ipfs.get("<cid from node A>")) # → b"hello from A"
207
+ ```
208
+
209
+ For an isolated network where only your nodes can see each other, use
210
+ `create_private_network()` on the first node and `join_private_network(key)`
211
+ on the rest, both *before* `start()`. See [Privacy](#privacy) below.
212
+
213
+ ### Troubleshooting
214
+
215
+ **`IPFSPortInUse` on startup.** Something else is on port 5001 (often another
216
+ IPFS daemon you forgot about, or some unrelated dev service). Either stop it,
217
+ or pick a different port *before* the first call:
218
+
219
+ ```python
220
+ import basic_ipfs
221
+ basic_ipfs.API_PORT = 5099
222
+ ```
223
+
224
+ **`IPFSRepoLocked` on startup.** Another `basic-ipfs`-using process owns the
225
+ repo. Run only one process per repo — or set `basic_ipfs.REPO_PATH` to a
226
+ different path before starting.
227
+
228
+ **Auto-download fails (corporate proxy / firewall).** The downloader honors
229
+ the standard environment variables:
230
+
231
+ ```bash
232
+ HTTPS_PROXY=http://corp-proxy:3128 \
233
+ REQUESTS_CA_BUNDLE=/etc/ssl/corp-ca.pem \
234
+ python your_script.py
235
+ ```
236
+
237
+ If outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
238
+ `<user_data_dir>/basic_ipfs/bin/<platform>/ipfs` (or `ipfs.exe` on Windows)
239
+ and `basic-ipfs` will skip the download entirely. The bundled
240
+ `<site-packages>/basic_ipfs/bin/<platform>/ipfs` path is also honoured
241
+ for PyInstaller / Briefcase deploys. Supported platform strings:
242
+ `linux-amd64`, `linux-arm64`, `linux-riscv64`, `darwin-amd64`,
243
+ `darwin-arm64`, `windows-amd64`.
244
+
245
+ **Alpine / musl Linux.** Kubo upstream ships glibc binaries only.
246
+ `apk add gcompat` may be enough; otherwise place a musl-compatible
247
+ `ipfs` binary at the path above.
248
+
249
+ **32-bit ARM (Raspberry Pi 3 and older).** Kubo no longer publishes 32-bit
250
+ ARM builds. Run a 64-bit OS (e.g. Raspberry Pi OS 64-bit) on Pi 4/5.
251
+
252
+ **Slow first run.** Auto-download is ~115 MB. Subsequent starts are fast
253
+ (daemon comes up in ~1–3 s). The binary lives in `platformdirs.user_data_dir("basic_ipfs")`
254
+ so it survives reinstalls. To wipe it, delete that directory.
255
+
256
+ **Want to inspect the daemon log.** It's at
257
+ `<repo>/basic_ipfs_daemon.log` (rotated at 5 MB, one `.old` kept).
258
+
259
+ ### Security
260
+
261
+ Auto-download is verified against an SHA-512 hash baked into the wheel
262
+ (`basic_ipfs/kubo_checksums.py`) using a constant-time compare. Versions
263
+ not in the table are refused — fetching a digest from the same origin as
264
+ the archive adds no real protection, so the install is fail-closed. The
265
+ download also pins its redirect target to `*.ipfs.tech` at every hop in
266
+ the chain (not just the final URL).
267
+
268
+ Two trust assumptions worth knowing before deploying on a shared host:
269
+
270
+ - **The local Kubo HTTP API on `127.0.0.1:5001` is unauthenticated.**
271
+ Any process running as the same user can drive the full Kubo API,
272
+ including `key/*` and `config`. Single-user dev boxes are fine;
273
+ multi-tenant hosts need additional hardening (`API.Authorizations`).
274
+ - **`connect_to_node(multiaddr)` forwards its argument verbatim.** If
275
+ your code feeds untrusted input into it, the daemon becomes an SSRF
276
+ probe.
277
+
278
+ See [`SECURITY.md`](SECURITY.md) for the full threat model and how to
279
+ verify the binary manually.
280
+
281
+ ### Privacy
282
+
283
+ **By default, the daemon joins the public IPFS network.** That has real
284
+ consequences you should understand before publishing anything sensitive:
285
+
286
+ - **CIDs are advertised.** `add()` announces the content's CID to the
287
+ public DHT. Anyone monitoring the DHT (and crawlers do) can record that
288
+ your node holds that CID. Pass `provide=False` to skip the announce —
289
+ the content is still addressable, but its presence is not broadcast.
290
+ - **`get()` is observable.** Fetching an unknown CID dials peers and may
291
+ fall back to public gateways operated by third parties (Protocol Labs,
292
+ Cloudflare). Those parties learn what you asked for.
293
+ - **Peer ID is persistent.** The repo is created once and reused, so all
294
+ your IPFS activity over time is linkable to one stable peer ID.
295
+ - **Bootstrap nodes are third parties.** The daemon dials Kubo's stock
296
+ bootstrap list on startup (Protocol Labs / Cloudflare hosts).
297
+ - **Swarm port is exposed.** Kubo listens on `0.0.0.0:4001` for inbound
298
+ peers; on a multi-tenant or hostile LAN, treat that port like any other
299
+ public service.
300
+
301
+ For non-public data, you have three escape hatches — pick what fits:
302
+
303
+ ```python
304
+ import basic_ipfs
305
+
306
+ # 1. Per-call: skip the DHT announce on a single add()
307
+ cid = basic_ipfs.add(b"private", provide=False)
308
+
309
+ # 2. Private network: only peers with the same 256-bit swarm key can
310
+ # connect. Run BEFORE start() / the first IPFS operation.
311
+ key = basic_ipfs.create_private_network()
312
+ # share key + multiaddr with peers via a trusted channel
313
+
314
+ # 3. Lockdown: disable the public DHT, bootstrap dialing, gateway
315
+ # fetch, and pin the swarm listener to loopback. Right starting
316
+ # point for encrypted-content stores or air-gapped pipelines.
317
+ basic_ipfs.lockdown_mode()
318
+
319
+ # Bonus: rotate the libp2p keypair to sever peer-ID linkability with
320
+ # prior runs (daemon must be stopped first; pins are preserved).
321
+ new_peer_id = basic_ipfs.rotate_identity()
322
+ ```
323
+
324
+ A private network refuses connections from any peer without the matching
325
+ swarm key, so the DHT/bootstrap concerns above do not apply. See
326
+ [`SECURITY.md`](SECURITY.md) for the full threat model.
327
+
328
+ ### How it works
329
+
330
+ `basic-ipfs` bundles the reference IPFS implementation — [Kubo](https://github.com/ipfs/kubo), the Go daemon maintained by Protocol Labs — and runs it as a subprocess. Your Python calls are translated into HTTP requests to Kubo's local `/api/v0` endpoint.
331
+
332
+ - **Auto-download:** the Kubo binary fetches from `dist.ipfs.tech` on first use, checksum-verified, and cached. The Python wheel itself stays tiny (~28 KB, `py3-none-any`) because it ships no binaries.
333
+ - **Content is immutable:** a CID is a hash of the content. The same bytes always produce the same CID, anywhere in the world.
334
+ - **Pinning is persistence:** Kubo garbage-collects unpinned content. `pin()` marks content permanent. `unpin()` undoes that.
335
+ - **PyInstaller / Briefcase friendly:** respects `sys._MEIPASS`, so bundled apps find the binary correctly.
336
+
337
+ ### Contributing
338
+
339
+ If you want to add functionality, open a PR. I'll merge it if it keeps the library simple and matches the existing patterns.
340
+
341
+ ### License
342
+
343
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,299 @@
1
+ # basic-ipfs
2
+
3
+ An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under the hood.
4
+
5
+ ### Description
6
+
7
+ `basic-ipfs` does exactly five things:
8
+
9
+ - Add a file or bytes to [IPFS](https://ipfs.tech/) and pin it (returns a [CID](https://docs.ipfs.tech/concepts/content-addressing/))
10
+ - Announce a file or bytes to IPFS without pinning (returns a CID — content may be GC'd)
11
+ - Get content back by CID (as bytes, or written to disk)
12
+ - Pin one CID or a list of CIDs (so they never get garbage-collected)
13
+ - Unpin one CID or a list of CIDs (idempotent — safe to re-run)
14
+
15
+ It also runs and manages a real [Kubo](https://github.com/ipfs/kubo) node for you — auto-downloaded on first use, auto-shutdown on exit. No daemon to install, no config files to edit, no accounts. (See [Privacy](#privacy) below — the default daemon does join the public IPFS network.)
16
+
17
+ I made `basic-ipfs` because no other Python packages make it this simple. Every existing client assumes you already have an IPFS daemon running. This one just works.
18
+
19
+ If it does exactly what you need → great, use it. If it doesn't → don't use it. Simple as that.
20
+
21
+ ### Install
22
+
23
+ ```
24
+ pip install basic-ipfs
25
+ ```
26
+
27
+ First call downloads the Kubo binary (~115 MB, SHA-512 verified) into your per-user data directory (`~/.local/share/basic_ipfs/bin/<platform>/ipfs` on Linux; `platformdirs` picks the right path per OS) and starts it as a background subprocess. The daemon stops automatically when your program exits.
28
+
29
+ ### Usage
30
+
31
+ ```python
32
+ import basic_ipfs
33
+
34
+ # Add — pins content permanently so it's never garbage-collected
35
+ cid = basic_ipfs.add("photo.jpg")
36
+ cid = basic_ipfs.add(b"hello world")
37
+
38
+ # Pass provide=False to skip the public-DHT announce (content stays
39
+ # locally addressable, but its presence is not broadcast)
40
+ cid = basic_ipfs.add(b"private data", provide=False)
41
+
42
+ # Announce — adds to IPFS without pinning; content may be GC'd later
43
+ cid = basic_ipfs.announce("photo.jpg")
44
+ cid = basic_ipfs.announce(b"temporary data")
45
+
46
+ # Just compute the CID locally — does NOT store, pin, or announce anything.
47
+ # Useful for previewing the CID of content you have not yet decided to publish.
48
+ cid = basic_ipfs.compute_cid_locally(b"hello world")
49
+ cid = basic_ipfs.compute_cid_locally("photo.jpg")
50
+
51
+ # Get — returns bytes, or writes to disk if you pass an output path
52
+ data = basic_ipfs.get(cid)
53
+ basic_ipfs.get(cid, "copy.jpg")
54
+
55
+ # Pin — one CID, or a whole list (one HTTP round-trip per ~500 CIDs)
56
+ basic_ipfs.pin(cid)
57
+ basic_ipfs.pin([cid1, cid2, cid3, ...])
58
+
59
+ # Unpin — same shape, always idempotent
60
+ basic_ipfs.unpin(cid)
61
+ basic_ipfs.unpin([cid1, cid2, cid3, ...])
62
+
63
+ # List all pinned CIDs
64
+ cids = basic_ipfs.get_all_pins() # → ['Qm...', 'baf...', ...]
65
+
66
+ # Debug info
67
+ basic_ipfs.status() # {peer_id, agent_version, repo_size_bytes, pinned_cids, ...}
68
+ ```
69
+
70
+ That's the core API. There are also helpers for networking, private
71
+ networks, identity rotation, and lockdown — see [Privacy](#privacy).
72
+
73
+ Explicit lifecycle, if you want it (you usually don't — the daemon starts lazily on the first call and stops on process exit):
74
+
75
+ ```python
76
+ basic_ipfs.start()
77
+ basic_ipfs.stop()
78
+
79
+ with basic_ipfs.node():
80
+ basic_ipfs.add(b"hi")
81
+ ```
82
+
83
+ All failures raise `basic_ipfs.IPFSError`. Subclasses, all with actionable messages:
84
+
85
+ - `IPFSBinaryNotFound` — Kubo missing and auto-download failed (no network, disk full, unsupported platform).
86
+ - `IPFSDaemonTimeout` — daemon didn't reach a healthy state in 60 s.
87
+ - `IPFSOperationError` — an `/api/v0/...` call returned an error.
88
+ - `IPFSPortInUse` — `API_PORT` (default 5001) is bound by something that isn't ours. Set `basic_ipfs.API_PORT` to something free.
89
+ - `IPFSRepoLocked` — another Kubo daemon already owns the repo. One process per repo.
90
+ - `IPFSRepoCorrupt` — repo on disk failed a sanity check. Investigate; don't auto-delete.
91
+
92
+ ### CLI
93
+
94
+ Installing the package also adds a `basic-ipfs` command:
95
+
96
+ ```
97
+ basic-ipfs status
98
+ basic-ipfs add photo.jpg # prints the CID, pins content
99
+ basic-ipfs announce photo.jpg # prints the CID, no pin (may be GC'd)
100
+ basic-ipfs add-folder ./mydir # recursive add + pin
101
+ basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
102
+ basic-ipfs get <cid> [output-path] # stdout or file
103
+ basic-ipfs pin <cid> [<cid> ...]
104
+ basic-ipfs unpin <cid> [<cid> ...]
105
+ basic-ipfs is-pinned <cid> # exit 0 if pinned, 1 if not
106
+ basic-ipfs exists <cid> # exit 0 if locally available
107
+ basic-ipfs pins # list all pinned CIDs
108
+ basic-ipfs gc # run garbage collection
109
+
110
+ # Networking
111
+ basic-ipfs peers # list connected peers
112
+ basic-ipfs my-addr # this node's shareable multiaddrs
113
+ basic-ipfs connect <multiaddr> # dial a peer
114
+
115
+ # Privacy
116
+ basic-ipfs create-private-network # generate swarm key (run before first op)
117
+ basic-ipfs join-private-network <key> # join an existing private network
118
+ basic-ipfs network-key # print this node's swarm key
119
+ basic-ipfs rotate-identity # new peer ID; daemon must be stopped
120
+ basic-ipfs lockdown # disable DHT, bootstrap, gateway fetch
121
+ ```
122
+
123
+ ### Config
124
+
125
+ Override module variables **before** the first call if you want non-defaults:
126
+
127
+ ```python
128
+ import basic_ipfs
129
+
130
+ basic_ipfs.APP_NAME = "MyApp" # changes default repo location
131
+ basic_ipfs.REPO_PATH = "/mnt/data/ipfs" # or pin an exact path
132
+ basic_ipfs.KUBO_VERSION = "v0.40.1" # must be in kubo_checksums.py
133
+ basic_ipfs.API_PORT = 5099 # if 5001 is taken
134
+ basic_ipfs.GATEWAY_PORT = 8099 # if 8080 is taken (or running 2 nodes)
135
+ basic_ipfs.SWARM_ADDRESSES = ["/ip4/127.0.0.1/tcp/4001"] # loopback-only swarm
136
+ basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
137
+ ```
138
+
139
+ Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
140
+
141
+ ### Two-node example
142
+
143
+ Anything you `add()` on one machine can be `get()`-ed on another that knows
144
+ your peer address. Smallest possible demo:
145
+
146
+ ```python
147
+ # Node A
148
+ import basic_ipfs
149
+ basic_ipfs.start()
150
+ ipv4, _ = basic_ipfs.my_node_multiaddress()
151
+ print("share this with node B:", ipv4)
152
+ cid = basic_ipfs.add(b"hello from A")
153
+ print("share this CID:", cid)
154
+ input("press enter to stop…")
155
+ ```
156
+
157
+ ```python
158
+ # Node B
159
+ import basic_ipfs
160
+ basic_ipfs.start()
161
+ basic_ipfs.connect_to_node("<ipv4 from node A>")
162
+ print(basic_ipfs.get("<cid from node A>")) # → b"hello from A"
163
+ ```
164
+
165
+ For an isolated network where only your nodes can see each other, use
166
+ `create_private_network()` on the first node and `join_private_network(key)`
167
+ on the rest, both *before* `start()`. See [Privacy](#privacy) below.
168
+
169
+ ### Troubleshooting
170
+
171
+ **`IPFSPortInUse` on startup.** Something else is on port 5001 (often another
172
+ IPFS daemon you forgot about, or some unrelated dev service). Either stop it,
173
+ or pick a different port *before* the first call:
174
+
175
+ ```python
176
+ import basic_ipfs
177
+ basic_ipfs.API_PORT = 5099
178
+ ```
179
+
180
+ **`IPFSRepoLocked` on startup.** Another `basic-ipfs`-using process owns the
181
+ repo. Run only one process per repo — or set `basic_ipfs.REPO_PATH` to a
182
+ different path before starting.
183
+
184
+ **Auto-download fails (corporate proxy / firewall).** The downloader honors
185
+ the standard environment variables:
186
+
187
+ ```bash
188
+ HTTPS_PROXY=http://corp-proxy:3128 \
189
+ REQUESTS_CA_BUNDLE=/etc/ssl/corp-ca.pem \
190
+ python your_script.py
191
+ ```
192
+
193
+ If outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
194
+ `<user_data_dir>/basic_ipfs/bin/<platform>/ipfs` (or `ipfs.exe` on Windows)
195
+ and `basic-ipfs` will skip the download entirely. The bundled
196
+ `<site-packages>/basic_ipfs/bin/<platform>/ipfs` path is also honoured
197
+ for PyInstaller / Briefcase deploys. Supported platform strings:
198
+ `linux-amd64`, `linux-arm64`, `linux-riscv64`, `darwin-amd64`,
199
+ `darwin-arm64`, `windows-amd64`.
200
+
201
+ **Alpine / musl Linux.** Kubo upstream ships glibc binaries only.
202
+ `apk add gcompat` may be enough; otherwise place a musl-compatible
203
+ `ipfs` binary at the path above.
204
+
205
+ **32-bit ARM (Raspberry Pi 3 and older).** Kubo no longer publishes 32-bit
206
+ ARM builds. Run a 64-bit OS (e.g. Raspberry Pi OS 64-bit) on Pi 4/5.
207
+
208
+ **Slow first run.** Auto-download is ~115 MB. Subsequent starts are fast
209
+ (daemon comes up in ~1–3 s). The binary lives in `platformdirs.user_data_dir("basic_ipfs")`
210
+ so it survives reinstalls. To wipe it, delete that directory.
211
+
212
+ **Want to inspect the daemon log.** It's at
213
+ `<repo>/basic_ipfs_daemon.log` (rotated at 5 MB, one `.old` kept).
214
+
215
+ ### Security
216
+
217
+ Auto-download is verified against an SHA-512 hash baked into the wheel
218
+ (`basic_ipfs/kubo_checksums.py`) using a constant-time compare. Versions
219
+ not in the table are refused — fetching a digest from the same origin as
220
+ the archive adds no real protection, so the install is fail-closed. The
221
+ download also pins its redirect target to `*.ipfs.tech` at every hop in
222
+ the chain (not just the final URL).
223
+
224
+ Two trust assumptions worth knowing before deploying on a shared host:
225
+
226
+ - **The local Kubo HTTP API on `127.0.0.1:5001` is unauthenticated.**
227
+ Any process running as the same user can drive the full Kubo API,
228
+ including `key/*` and `config`. Single-user dev boxes are fine;
229
+ multi-tenant hosts need additional hardening (`API.Authorizations`).
230
+ - **`connect_to_node(multiaddr)` forwards its argument verbatim.** If
231
+ your code feeds untrusted input into it, the daemon becomes an SSRF
232
+ probe.
233
+
234
+ See [`SECURITY.md`](SECURITY.md) for the full threat model and how to
235
+ verify the binary manually.
236
+
237
+ ### Privacy
238
+
239
+ **By default, the daemon joins the public IPFS network.** That has real
240
+ consequences you should understand before publishing anything sensitive:
241
+
242
+ - **CIDs are advertised.** `add()` announces the content's CID to the
243
+ public DHT. Anyone monitoring the DHT (and crawlers do) can record that
244
+ your node holds that CID. Pass `provide=False` to skip the announce —
245
+ the content is still addressable, but its presence is not broadcast.
246
+ - **`get()` is observable.** Fetching an unknown CID dials peers and may
247
+ fall back to public gateways operated by third parties (Protocol Labs,
248
+ Cloudflare). Those parties learn what you asked for.
249
+ - **Peer ID is persistent.** The repo is created once and reused, so all
250
+ your IPFS activity over time is linkable to one stable peer ID.
251
+ - **Bootstrap nodes are third parties.** The daemon dials Kubo's stock
252
+ bootstrap list on startup (Protocol Labs / Cloudflare hosts).
253
+ - **Swarm port is exposed.** Kubo listens on `0.0.0.0:4001` for inbound
254
+ peers; on a multi-tenant or hostile LAN, treat that port like any other
255
+ public service.
256
+
257
+ For non-public data, you have three escape hatches — pick what fits:
258
+
259
+ ```python
260
+ import basic_ipfs
261
+
262
+ # 1. Per-call: skip the DHT announce on a single add()
263
+ cid = basic_ipfs.add(b"private", provide=False)
264
+
265
+ # 2. Private network: only peers with the same 256-bit swarm key can
266
+ # connect. Run BEFORE start() / the first IPFS operation.
267
+ key = basic_ipfs.create_private_network()
268
+ # share key + multiaddr with peers via a trusted channel
269
+
270
+ # 3. Lockdown: disable the public DHT, bootstrap dialing, gateway
271
+ # fetch, and pin the swarm listener to loopback. Right starting
272
+ # point for encrypted-content stores or air-gapped pipelines.
273
+ basic_ipfs.lockdown_mode()
274
+
275
+ # Bonus: rotate the libp2p keypair to sever peer-ID linkability with
276
+ # prior runs (daemon must be stopped first; pins are preserved).
277
+ new_peer_id = basic_ipfs.rotate_identity()
278
+ ```
279
+
280
+ A private network refuses connections from any peer without the matching
281
+ swarm key, so the DHT/bootstrap concerns above do not apply. See
282
+ [`SECURITY.md`](SECURITY.md) for the full threat model.
283
+
284
+ ### How it works
285
+
286
+ `basic-ipfs` bundles the reference IPFS implementation — [Kubo](https://github.com/ipfs/kubo), the Go daemon maintained by Protocol Labs — and runs it as a subprocess. Your Python calls are translated into HTTP requests to Kubo's local `/api/v0` endpoint.
287
+
288
+ - **Auto-download:** the Kubo binary fetches from `dist.ipfs.tech` on first use, checksum-verified, and cached. The Python wheel itself stays tiny (~28 KB, `py3-none-any`) because it ships no binaries.
289
+ - **Content is immutable:** a CID is a hash of the content. The same bytes always produce the same CID, anywhere in the world.
290
+ - **Pinning is persistence:** Kubo garbage-collects unpinned content. `pin()` marks content permanent. `unpin()` undoes that.
291
+ - **PyInstaller / Briefcase friendly:** respects `sys._MEIPASS`, so bundled apps find the binary correctly.
292
+
293
+ ### Contributing
294
+
295
+ If you want to add functionality, open a PR. I'll merge it if it keeps the library simple and matches the existing patterns.
296
+
297
+ ### License
298
+
299
+ MIT. See [LICENSE](LICENSE).