basic-ipfs 1.0.0__py3-none-any.whl

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.
basic_ipfs/cli.py ADDED
@@ -0,0 +1,301 @@
1
+ """Tiny CLI: `basic-ipfs <subcommand>`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import sys
8
+
9
+ from . import (
10
+ IPFSError,
11
+ __version__,
12
+ add,
13
+ add_folder,
14
+ announce,
15
+ compute_cid_locally,
16
+ connect_to_node,
17
+ connect_to_nodes,
18
+ create_private_network,
19
+ exists,
20
+ garbage_collection,
21
+ get,
22
+ get_all_pins,
23
+ get_private_network_key,
24
+ is_pinned,
25
+ join_private_network,
26
+ lockdown_mode,
27
+ my_node_multiaddress,
28
+ peers,
29
+ pin,
30
+ rotate_identity,
31
+ status,
32
+ unpin,
33
+ )
34
+
35
+
36
+ def _cmd_status(args: argparse.Namespace) -> int:
37
+ print(json.dumps(status(), indent=2))
38
+ return 0
39
+
40
+
41
+ def _cmd_pins(args: argparse.Namespace) -> int:
42
+ for cid in get_all_pins():
43
+ print(cid)
44
+ return 0
45
+
46
+
47
+ def _cmd_add(args: argparse.Namespace) -> int:
48
+ source: str | bytes = args.path
49
+ if args.path == "-":
50
+ source = sys.stdin.buffer.read()
51
+ cid = add(source)
52
+ print(cid)
53
+ return 0
54
+
55
+
56
+ def _cmd_announce(args: argparse.Namespace) -> int:
57
+ source: str | bytes = args.path
58
+ if args.path == "-":
59
+ source = sys.stdin.buffer.read()
60
+ cid = announce(source)
61
+ print(cid)
62
+ return 0
63
+
64
+
65
+ def _cmd_add_folder(args: argparse.Namespace) -> int:
66
+ cid = add_folder(args.path)
67
+ print(cid)
68
+ return 0
69
+
70
+
71
+ def _cmd_compute_cid_locally(args: argparse.Namespace) -> int:
72
+ source: str | bytes = args.path
73
+ if args.path == "-":
74
+ source = sys.stdin.buffer.read()
75
+ cid = compute_cid_locally(source)
76
+ print(cid)
77
+ return 0
78
+
79
+
80
+ def _cmd_get(args: argparse.Namespace) -> int:
81
+ if args.output:
82
+ get(args.cid, args.output)
83
+ print(f"Wrote {args.output}", file=sys.stderr)
84
+ else:
85
+ sys.stdout.buffer.write(get(args.cid))
86
+ return 0
87
+
88
+
89
+ def _cmd_pin(args: argparse.Namespace) -> int:
90
+ pin(args.cid)
91
+ for c in args.cid:
92
+ print(f"Pinned {c}")
93
+ return 0
94
+
95
+
96
+ def _cmd_unpin(args: argparse.Namespace) -> int:
97
+ unpin(args.cid)
98
+ for c in args.cid:
99
+ print(f"Unpinned {c}")
100
+ return 0
101
+
102
+
103
+ def _cmd_is_pinned(args: argparse.Namespace) -> int:
104
+ pinned = is_pinned(args.cid)
105
+ print("pinned" if pinned else "not pinned")
106
+ return 0 if pinned else 1
107
+
108
+
109
+ def _cmd_exists(args: argparse.Namespace) -> int:
110
+ found = exists(args.cid)
111
+ print("exists" if found else "not found")
112
+ return 0 if found else 1
113
+
114
+
115
+ def _cmd_gc(args: argparse.Namespace) -> int:
116
+ garbage_collection()
117
+ return 0
118
+
119
+
120
+ def _cmd_peers(args: argparse.Namespace) -> int:
121
+ for addr in peers():
122
+ print(addr)
123
+ return 0
124
+
125
+
126
+ def _cmd_connect_to_node(args: argparse.Namespace) -> int:
127
+ connect_to_node(args.addr)
128
+ print(f"Connected {args.addr}")
129
+ return 0
130
+
131
+
132
+ def _cmd_connect_to_nodes(args: argparse.Namespace) -> int:
133
+ connect_to_nodes(args.addr)
134
+ for a in args.addr:
135
+ print(f"Connected {a}")
136
+ return 0
137
+
138
+
139
+ def _cmd_create_private_network(args: argparse.Namespace) -> int:
140
+ key = create_private_network()
141
+ print(key)
142
+ print("swarm.key written. Share the key above with nodes that should join.", file=sys.stderr)
143
+ return 0
144
+
145
+
146
+ def _cmd_join_private_network(args: argparse.Namespace) -> int:
147
+ join_private_network(args.key)
148
+ print("swarm.key written.", file=sys.stderr)
149
+ return 0
150
+
151
+
152
+ def _cmd_network_key(args: argparse.Namespace) -> int:
153
+ key = get_private_network_key()
154
+ if key is None:
155
+ print("Not a private network (no swarm.key found).", file=sys.stderr)
156
+ return 1
157
+ print(key)
158
+ return 0
159
+
160
+
161
+ def _cmd_rotate_identity(args: argparse.Namespace) -> int:
162
+ new_id = rotate_identity(args.oldkey)
163
+ print(new_id)
164
+ print(f"Old key preserved as {args.oldkey!r}.", file=sys.stderr)
165
+ return 0
166
+
167
+
168
+ def _cmd_lockdown(args: argparse.Namespace) -> int:
169
+ lockdown_mode()
170
+ print("Lockdown applied. Node will not talk to public IPFS.", file=sys.stderr)
171
+ return 0
172
+
173
+
174
+ def _cmd_my_node_multiaddress(args: argparse.Namespace) -> int:
175
+ ipv4, ipv6 = my_node_multiaddress()
176
+ if ipv4:
177
+ print(f"IPv4: {ipv4}")
178
+ if ipv6:
179
+ print(f"IPv6: {ipv6}")
180
+ if not ipv4 and not ipv6:
181
+ print("No shareable addresses found", file=sys.stderr)
182
+ return 1
183
+ return 0
184
+
185
+
186
+ def _build_parser() -> argparse.ArgumentParser:
187
+ p = argparse.ArgumentParser(
188
+ prog="basic-ipfs",
189
+ description="Stupid-simple IPFS CLI. Runs a real Kubo node under the hood.",
190
+ )
191
+ p.add_argument("--version", action="version", version=f"basic-ipfs {__version__}")
192
+ sub = p.add_subparsers(dest="cmd", required=True)
193
+
194
+ s = sub.add_parser("status", help="Show node status")
195
+ s.set_defaults(func=_cmd_status)
196
+
197
+ ps = sub.add_parser("pins", help="List all pinned CIDs (one per line)")
198
+ ps.set_defaults(func=_cmd_pins)
199
+
200
+ a = sub.add_parser("add", help="Add a file (or stdin with '-') to IPFS and pin it")
201
+ a.add_argument("path", help="File path, or '-' to read bytes from stdin")
202
+ a.set_defaults(func=_cmd_add)
203
+
204
+ an = sub.add_parser("announce", help="Add a file to IPFS without pinning (may be GC'd)")
205
+ an.add_argument("path", help="File path, or '-' to read bytes from stdin")
206
+ an.set_defaults(func=_cmd_announce)
207
+
208
+ af = sub.add_parser("add-folder", help="Add a directory to IPFS recursively and pin it")
209
+ af.add_argument("path", help="Directory path")
210
+ af.set_defaults(func=_cmd_add_folder)
211
+
212
+ cl = sub.add_parser(
213
+ "compute-cid",
214
+ help="Print the CID a file would have, without storing or announcing anything",
215
+ )
216
+ cl.add_argument("path", help="File path, or '-' to read bytes from stdin")
217
+ cl.set_defaults(func=_cmd_compute_cid_locally)
218
+
219
+ g = sub.add_parser("get", help="Retrieve content by CID")
220
+ g.add_argument("cid")
221
+ g.add_argument("output", nargs="?", help="Output file path (default: stdout)")
222
+ g.set_defaults(func=_cmd_get)
223
+
224
+ pn = sub.add_parser("pin", help="Pin one or more CIDs")
225
+ pn.add_argument("cid", nargs="+")
226
+ pn.set_defaults(func=_cmd_pin)
227
+
228
+ up = sub.add_parser("unpin", help="Unpin one or more CIDs")
229
+ up.add_argument("cid", nargs="+")
230
+ up.set_defaults(func=_cmd_unpin)
231
+
232
+ ip = sub.add_parser("is-pinned", help="Check if a CID is pinned (exit 0=yes, 1=no)")
233
+ ip.add_argument("cid")
234
+ ip.set_defaults(func=_cmd_is_pinned)
235
+
236
+ ex = sub.add_parser("exists", help="Check if a CID is locally available (exit 0=yes, 1=no)")
237
+ ex.add_argument("cid")
238
+ ex.set_defaults(func=_cmd_exists)
239
+
240
+ gc = sub.add_parser("gc", help="Run garbage collection, freeing unpinned storage")
241
+ gc.set_defaults(func=_cmd_gc)
242
+
243
+ pr = sub.add_parser("peers", help="List connected peers (one multiaddr per line)")
244
+ pr.set_defaults(func=_cmd_peers)
245
+
246
+ cn = sub.add_parser("connect", help="Connect to a peer by multiaddr")
247
+ cn.add_argument("addr")
248
+ cn.set_defaults(func=_cmd_connect_to_node)
249
+
250
+ cns = sub.add_parser("connect-nodes", help="Connect to multiple peers by multiaddr")
251
+ cns.add_argument("addr", nargs="+")
252
+ cns.set_defaults(func=_cmd_connect_to_nodes)
253
+
254
+ ma = sub.add_parser("my-addr", help="Print this node's IPv4/IPv6 multiaddrs to share with others")
255
+ ma.set_defaults(func=_cmd_my_node_multiaddress)
256
+
257
+ cpn = sub.add_parser("create-private-network", help="Generate a swarm key and start a private network (run before start)")
258
+ cpn.set_defaults(func=_cmd_create_private_network)
259
+
260
+ jpn = sub.add_parser("join-private-network", help="Write a swarm key to join an existing private network (run before start)")
261
+ jpn.add_argument("key", help="64-char hex key from create-private-network")
262
+ jpn.set_defaults(func=_cmd_join_private_network)
263
+
264
+ nk = sub.add_parser("network-key", help="Print the current swarm key (share with new members)")
265
+ nk.set_defaults(func=_cmd_network_key)
266
+
267
+ ri = sub.add_parser(
268
+ "rotate-identity",
269
+ help="Generate a new peer ID. Daemon must be stopped. Pins are preserved.",
270
+ )
271
+ ri.add_argument(
272
+ "--oldkey", default="previous-self",
273
+ help="Keystore name to preserve the old key under (default: previous-self)",
274
+ )
275
+ ri.set_defaults(func=_cmd_rotate_identity)
276
+
277
+ ld = sub.add_parser(
278
+ "lockdown",
279
+ help="Disable DHT, bootstrap, gateway fetch, and non-loopback swarm. Daemon must be stopped.",
280
+ )
281
+ ld.set_defaults(func=_cmd_lockdown)
282
+
283
+ return p
284
+
285
+
286
+ def main(argv: list[str] | None = None) -> int:
287
+ parser = _build_parser()
288
+ args = parser.parse_args(argv)
289
+ try:
290
+ rc: int = args.func(args)
291
+ return rc
292
+ except IPFSError as exc:
293
+ print(f"error: {exc}", file=sys.stderr)
294
+ return 1
295
+ except (FileNotFoundError, NotADirectoryError, IsADirectoryError, TypeError) as exc:
296
+ print(f"error: {exc}", file=sys.stderr)
297
+ return 2
298
+
299
+
300
+ if __name__ == "__main__":
301
+ sys.exit(main())
@@ -0,0 +1,28 @@
1
+ """
2
+ Built-in SHA-512 checksums for Kubo binaries.
3
+
4
+ Why baked in: if dist.ipfs.tech is compromised, an attacker could swap both
5
+ the archive and its `.sha512` companion file. Verifying against a hash that
6
+ shipped inside the wheel — installed via signed PyPI metadata — closes that
7
+ gap. For unknown versions, we fall back to fetching the .sha512 alongside
8
+ the archive (with an INFO-level log noting the weaker check).
9
+
10
+ To populate a new version: ``python scripts/refresh_checksums.py <version>``
11
+ """
12
+
13
+ # {kubo_version: {platform_key: sha512_hex}}
14
+ CHECKSUMS: dict[str, dict[str, str]] = {
15
+ "v0.40.1": {
16
+ "linux-amd64": "86f9c07bca62d09839e53553df0f81bc306364b1467a459d52f3e4505cc948d196ed0c219c03c667cd681e057bb24bbfc0e0eebf4b83bc64a36a0e9923a60e05",
17
+ "linux-arm64": "07a52fb63c37ac687ad41bc949f60e16856387d5d33ecf452771b5d992fa4fe2e659f383d267de69cd9755aa5751847aab66247b5cdeeaad7a06b780ece51cb7",
18
+ "linux-riscv64": "49ebe239f38a01b25c02e87c1308ea8298cbe8119cf9bc6c1db3ac9b4340d3b3b2612cf94fd8c2182e9c7287d52f530ab53727cd78597a2398708547bf466aba",
19
+ "darwin-amd64": "b8becb9d8782a968e4489a60f62bfc2a1fb5638df01488051c2255e2ebc14a9f1666097ba1ceb50f8fe8ca8efc642726bca093f81195d327dd46c1444c0f39ad",
20
+ "darwin-arm64": "13b6d5dc04e661bfde6b8ba469bcf5b19d9d0062fe8ed50c7aadd8a078f500d0bceee4be7c9bfa476b48c4eb84c246ba083605ed1ed24d16b98e6cd0f09140bb",
21
+ "windows-amd64": "456f8938d7dc64fdd95ac7897af0f15249265bf2d742b6776b883c8534981f2e85e13b00f8d42fce908671e44fee08b810a8afa858f2e649e6fee9c174373591",
22
+ },
23
+ }
24
+
25
+
26
+ def known_checksum(version: str, platform_key: str) -> "str | None":
27
+ """Return the baked-in SHA-512 hex, or None if not in the table."""
28
+ return CHECKSUMS.get(version, {}).get(platform_key)
basic_ipfs/py.typed ADDED
File without changes
@@ -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,10 @@
1
+ basic_ipfs/__init__.py,sha256=EL-wqAAcP3dv4X1aqNiURL4MFpVPre33bIxykEKd1cs,86075
2
+ basic_ipfs/cli.py,sha256=zzQuSDpsUAd500IlKeOThtUYp7NjHjs_wGdLGCxOyPY,8744
3
+ basic_ipfs/kubo_checksums.py,sha256=c8f2jpMixkgbF8YISAaprN8EGgfe9pVh-4rNM4y0LWI,1755
4
+ basic_ipfs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ basic_ipfs-1.0.0.dist-info/licenses/LICENSE,sha256=PfvdxUCwIQnLbDg8z2dSH3kLVFNQ7w7PERPrL0TNctM,1069
6
+ basic_ipfs-1.0.0.dist-info/METADATA,sha256=S93pgFGPulHBYmWELBkWkqmNGhLq-E6NEKTJFn8B_SQ,14775
7
+ basic_ipfs-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
8
+ basic_ipfs-1.0.0.dist-info/entry_points.txt,sha256=UCOAhNoDrUlGG9oZye1lRSdvIW_vBca9_A3qkw2DY34,51
9
+ basic_ipfs-1.0.0.dist-info/top_level.txt,sha256=BqIY1qUn5_f8V3ysRHvMLkpeauTbHgCg2Qr5Fnxe2-Q,11
10
+ basic_ipfs-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+