================================================================================ FISP -- FILE INTERCHANGE SYSTEM PROTOCOL ================================================================================ Status: Experimental Draft Publisher: Binary & Bus, Sys. (bbsys.net, B2/) Publication date: 2026-11-20 Canonical URL: https://bbsys.net/doc/fisp/ Planned reference client: B2/FISPConnect Planned reference server: ferretd (fisp binary) ================================================================================ ABSTRACT ================================================================================ FISP (File Interchange System Protocol) is a read-only, self-hosted file interchange protocol. A FISP server exposes a directory of files over a simple text protocol on TCP. A FISP client connects to a server by address, retrieves a manifest of available files, and downloads them. FISP is deliberately small. It has no accounts, no database, no encryption, no discovery, and no server-declared identity. It is to file-sharing what Gopher was to hypertext: a small, decentralized alternative to heavyweight platforms. FISP is an open protocol. B2/FISPConnect is the planned reference client, but any conformant client may interoperate. The protocol name belongs to no one. THIS IS AN EXPERIMENTAL DRAFT OF FISP. This document defines the protocol as currently proposed. Future revisions may clarify, correct, or change this specification. Implementers MUST NOT assume wire compatibility between future revisions unless explicitly stated. The version string on the wire is simply FISP; this draft does not introduce version negotiation. See Appendix C for changes from an earlier draft and section 17 for change control. ================================================================================ 1. CONVENTIONS AND TERMINOLOGY ================================================================================ The key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119. Home directory The directory the server is pointed at (via --home). Contains the content root and optional configuration files. Content root /files/. The only directory whose contents are served. Sysop The person operating a FISP server. Peer The remote endpoint of a TCP connection, identified by its source IP address. IPv4-mapped IPv6 addresses (::ffff:a.b.c.d) are normalized to the IPv4 address. For connection limits and failed-key limits only (sections 4.5 and 10.4), an IPv6 peer is identified by its /64 prefix. Manifest The server's listing of available files. Control file Any file in / read by the server but never served. Currently: whitelist.txt, blacklist.txt, key.txt. Servable name A relative path that satisfies every rule in section 5.3. Only files with servable names are listed or served. Active A control file is active when it has at least one active line (section 8.2). Otherwise it is inactive. A NOTE ON EXAMPLES In this document, wire traffic is shown with arrows: -> bytes the client sends <- bytes the server sends These are bytes over a socket. They are never typed by a user at a terminal. The user interacts with a client (such as B2/FISPConnect); the client builds and sends these messages. Appendix B gives byte-exact examples using backslash escapes (\n for a line feed byte). ================================================================================ 2. TRANSPORT ================================================================================ - FISP runs over TCP. - The default port is 7070. - Protocol lines are UTF-8 text, terminated by \n. Servers MUST accept \r\n (and \n) on input and MUST emit \n on output. A single \r immediately before the terminating \n is part of the terminator, not of the line. - A request line is at most 8192 bytes including its terminator. A protocol line sent by a server (any line other than raw file bytes) is at most 16384 bytes including its terminator. - File bodies are raw bytes and are the only non-text data on the wire. - The protocol is request/response. The client sends a command line; the server responds with one or more lines (and, for downloads, raw bytes). - FISP is read-only. There are no write operations over the wire. - Unless otherwise stated, commands, field names, and response keywords are case-sensitive. Commands and response keywords MUST be uppercase where shown (HELLO, LIST, GET, RESUME, OK, MANIFEST, FILE, END, DENIED, ERROR, NOTFOUND, BUSY). Field names MUST be lowercase (name=, size=, date=, sha256=, desc=, key=, offset=, reason=). - Request lines that are not valid UTF-8 are bad requests (ERROR reason=bad_request), except that a peer denied by access lists always receives DENIED (section 4.4). ================================================================================ 3. CONNECTION LIFECYCLE ================================================================================ 1. The client opens a TCP connection to the server's address and port. 2. The client MUST send its first line, a HELLO, within 30 seconds of connecting; otherwise the server MUST close the connection. 3. The server responds with OK (proceed), DENIED, BUSY, or ERROR. After sending DENIED, BUSY, or ERROR in response to the first line, the server MUST close the connection. 4. After OK, the client may issue LIST, GET, and RESUME commands, in any order, any number of times. The server processes commands strictly in the order received, one at a time. Responses are never interleaved. Clients SHOULD wait for a complete response (through its END line, or the NOTFOUND/ERROR line) before sending the next command; a server MUST nonetheless handle pipelined commands correctly by queueing them. 5. Either side may close the connection at any time. Rules: - A command other than HELLO as the first line is handled by section 4.4 (ERROR reason=bad_request and close). - A HELLO after a successful HELLO receives ERROR reason=bad_request. The connection stays open. - IDLE TIMEOUT. A server MUST close a connection that has been idle for 5 minutes (the default; a Sysop MAY configure 1 to 60 minutes). A connection is idle when no command line is being received and no response is being sent. Time spent sending a response is not idle time. - TRANSFER STALL. A server MUST abort a response (by closing the connection) if it has been unable to write any bytes for 60 seconds. - A server MUST NOT send BUSY in response to any command other than the first line. ================================================================================ 4. HANDSHAKE ================================================================================ 4.1 REQUEST -> FISP HELLO [key=""] - Exactly one ASCII space separates FISP, HELLO, and the optional key field. Multiple spaces, tabs, or a missing space are ERROR reason=bad_request. - The HELLO command MUST be the first command on a connection. - If the server requires an access key (section 10.2), the client MUST include key="...". - If the server does not require a key, it ignores any key= field. A client SHOULD NOT send a key to a server unless it knows (or has been told by DENIED reason=bad_key) that one is required; see section 12.5. - The key value MUST be enclosed in "...". Unquoted values (for example, key=admin123) are ERROR reason=bad_request. - Escape sequences inside any quoted value: \" for a literal " and \\ for a literal \. A backslash followed by any other byte is malformed. All other bytes are literal. Quoted values MUST NOT contain control characters. 4.2 SUCCESS RESPONSE <- FISP OK The OK response carries no fields. (Reachability is not part of the protocol; see section 9. File counts are obtained from the Manifest.) 4.3 DENIAL RESPONSE <- FISP DENIED reason= Defined reasons: denied The peer is refused by the Sysop's access lists (not whitelisted, or blacklisted), or is temporarily locked out after repeated bad keys (section 10.4). The reason deliberately does not say which. bad_key The server requires a key; the client did not present one, or presented the wrong one. The server MUST close the connection after a DENIED. 4.4 ORDERING OF CHECKS For each new connection, the server reads the peer's first line (or up to 8192 bytes if no line terminator arrives) and then MUST evaluate, in this order: 1. If whitelist.txt is active: verify the peer is in it. On failure -> DENIED reason=denied. 2. If blacklist.txt is active: verify the peer is not in it. On failure -> DENIED reason=denied. 3. If the peer is locked out by the failed-key limiter (section 10.4) -> DENIED reason=denied. 4. If a connection limit (section 4.5) is exceeded -> BUSY. 5. Classify the first line: a. It is exactly the HELLO syntax of section 4.1: continue. b. Its second space-separated word is HELLO but its first word is not exactly FISP (for example FISP/2 HELLO, FISPX HELLO, FISP1.0 HELLO) -> ERROR reason=bad_version. c. Anything else (a malformed HELLO, a command before HELLO, an over-length line, invalid UTF-8) -> ERROR reason=bad_request. 6. If key.txt (or --key) is active: verify the client presented a matching key="...". On failure (missing key, wrong key, or key=""), record the failure (section 10.4), wait 1 second, then send DENIED reason=bad_key. 7. Otherwise -> OK. Steps 1 to 3 run before any parsing, so a refused peer learns nothing about the command grammar: whatever it sent, it receives DENIED. Every response other than OK is followed by close. The peer's identity is the TCP source IP address. A server MUST NOT accept a client-supplied IP as identity. 4.5 BUSY RESPONSE <- FISP BUSY Sent in place of any other response when a connection limit is exceeded. A server MUST enforce both: - a per-peer limit on concurrent connections (RECOMMENDED default: 8), and - a global limit on concurrent connections (RECOMMENDED default: 256). Both limits MUST be configurable. After sending BUSY the server MUST close the connection immediately. It does not hold the connection open. The client MAY reconnect (a new connection, not a retry on the old one) after a delay (RECOMMENDED: exponential backoff starting at 1 second, at most 3 attempts). 4.6 VERSION MISMATCH A first line whose second word is HELLO but whose first word is not exactly FISP MUST be rejected with: <- FISP ERROR reason=bad_version The connection MUST close. (See section 4.4, step 5b.) ================================================================================ 5. MANIFEST ================================================================================ 5.1 REQUEST -> LIST LIST takes no arguments. Any argument is ERROR reason=bad_request. LIST may be sent multiple times on the same connection. 5.2 RESPONSE <- FISP MANIFEST <- name="" size= [date=] [sha256=] desc="" <- ... <- END Fields: - name -- REQUIRED. Quoted (escaping as in section 4.1). A servable name (section 5.3): relative to the content root, uses / as the separator. - size -- REQUIRED. File size in bytes: decimal digits, no sign, no leading zeros (except the single digit 0), at most 9223372036854775807. - date -- OPTIONAL. Last-modified date in UTC, ISO 8601 YYYY-MM-DD, a valid calendar date. Servers MUST omit the field when the date is unknown. Servers MUST NOT emit placeholder dates. - sha256 -- OPTIONAL. 64 lowercase hexadecimal digits: the SHA-256 of the whole file. See section 6.3. - desc -- Servers MUST include it (possibly empty, desc=""). Quoted. Clients MUST tolerate its absence. - Servers MUST emit fields in the order shown. Clients MUST parse by field name and MUST NOT depend on field order. - Each entry is one line terminated by \n. The list terminates with a line containing exactly END. - The Manifest is flat: the recursive contents of the content root are listed, with relative paths as names. Directories are not listed as entries. - The order of entries is not significant; clients MUST NOT depend on it. Manifest failure handling: - A server that cannot begin a listing at all (for example, the content root has become unreadable) MUST respond FISP ERROR reason=list_failed (no name=) instead of the header line. A server SHOULD assemble the complete listing before sending the header so that this is always possible. - If a failure occurs after the header has been sent, the server MUST close the connection without sending END. - A client that does not receive END (because the connection closed, timed out, or a line was malformed) MUST treat the listing as failed and MUST NOT present it as complete. 5.3 SERVABLE NAMES A name is servable if and only if all of these hold: - Its total length is at most 4096 bytes, and each segment is 1 to 255 bytes. There are no empty segments (no "a//b", no trailing "/"), no segment equal to "." or "..", and it does not begin with "/". - It is valid UTF-8 (no overlong forms, no surrogates). It contains none of: the control characters U+0000 to U+001F, U+007F, and U+0080 to U+009F; and none of the bidirectional formatting characters U+202A to U+202E and U+2066 to U+2069. - It contains neither "\" (backslash) nor ":" (colon). - No segment begins or ends with a space, and no segment ends with ".". - No segment, compared case-insensitively and ignoring any extension after the first ".", is a reserved device name: CON, PRN, AUX, NUL, COM1 to COM9, LPT1 to LPT9. - No segment begins with "." (a hidden name), unless the Sysop has explicitly enabled serving hidden files (--serve-hidden, section 11.1). These rules apply on every platform, so that any client on any filesystem can store what it receives. A file whose name is not servable is omitted from the Manifest, and a GET for that name returns NOTFOUND. The server SHOULD log each omitted name (with control characters escaped) at startup and when LIST first encounters it, and `fisp check` MUST report them. Names are compared byte for byte; no Unicode normalization is applied, and names that differ only in case or normalization are distinct names. Clients MUST handle the resulting collisions (section 12.2). 5.4 RULES - Control files (whitelist.txt, blacklist.txt, key.txt) and any files outside the content root MUST NOT appear. - Sidecar files (section 5.6) MUST NOT appear. - Empty subdirectories are omitted. - Only regular files are listed and served. Directories, symlinks, FIFOs, sockets, device nodes, and any other non-regular file are omitted. GET for such a name returns NOTFOUND. - Symlinks MUST NOT be followed. A symlink at any path component, including or the content root, MUST NOT be followed by the server. - Unknown fields on a manifest line MUST be ignored by clients. A manifest line that does not begin with name= MUST be ignored by clients. These tolerance rules exist so that a buggy or privately annotated server cannot crash a client. They do not make FISP extensible: no field, line type, or command beyond those in this document is part of FISP (section 17). - A manifest line that a client cannot parse into a valid name and a valid size (section 12.1) MUST be skipped, not treated as downloadable. - Servers MUST NOT list the same name twice. 5.5 CONSISTENCY The Manifest lists every servable regular file as of the moment the listing began. A server MAY serve a listing assembled up to 5 seconds earlier (to bound the cost of repeated LIST calls); it MUST NOT serve a staler one. A server SHOULD allow at most about one LIST per second per connection. Servers MUST NOT omit servable files based on a size or count limit. If an implementation offers such a limit, it MUST be off by default and MUST log a warning when it is reached. GET (section 6) always acts on the live filesystem, not on any earlier listing. 5.6 DESCRIPTIONS A file's description is read from a sidecar file named .desc in the same directory. - A file is a sidecar if and only if its name ends in ".desc" and the same directory contains a servable regular file whose name is exactly that name without the trailing ".desc" (same case). Sidecars are never listed and never served (GET returns NOTFOUND). - A file ending in ".desc" with no matching base file (an orphan) is not a sidecar. It is listed and served like any other file, and the server SHOULD log it as an orphan and `fisp check` MUST report it. - A sidecar whose base name differs only by case is not a sidecar for that file. The discrepancy SHOULD be logged at startup, and `fisp check` MUST report it. - The description is the first line of the sidecar (at most 1024 bytes read), with any trailing \r removed. If it is not valid UTF-8, desc="" is used. Control characters and bidirectional formatting characters in it MUST be replaced by a space. - If no sidecar exists, desc="" is used. ================================================================================ 6. DOWNLOAD ================================================================================ 6.1 GET -> GET - The client MUST send the path exactly as it appeared (after unescaping) in the name= field of the Manifest, unquoted and unescaped. For example, if the Manifest contains name="path with spaces.txt", the client sends: GET path with spaces.txt - Exactly one ASCII space follows GET; the rest of the line (up to the terminator) is the path. - A client MAY request a path that was not in the most recent LIST response. GET is path-relative, not manifest-relative. The server resolves the path against the content root and applies section 5.3. 6.2 RESUME -> RESUME Requests the same file as GET, starting at a byte offset. - is decimal digits as for size (no sign, no leading zeros except the single digit 0), followed by exactly one space and the path. - If offset is greater than the file's current size, the server responds ERROR reason=bad_request name="". - If offset equals the current size, the server responds with a FILE header with size=0 and no body bytes (then the trailer). - The server responds as in section 6.3, with an additional offset= field, and sends only the bytes from offset to the end of the file. - Everything else in this section applies to RESUME as to GET. 6.3 SUCCESS RESPONSE <- FISP FILE name="" size= [offset=] [sha256=] <- <- \n <- END <- \n - The header line is followed immediately by exactly size raw bytes. The size field is the number of body bytes that follow (for RESUME, the number of bytes from offset to the end of the file at the moment of the header). - After the body, the server sends exactly the five bytes "\nEND\n" (a line feed, the letters E N D, and a line feed). There is always a line feed before END, even when the body itself ends with one or is empty. The trailer is not part of the body and does not count toward size. - name MUST be quoted per section 4.1. offset= appears only in response to RESUME. - The raw bytes are the file's content, unmodified. - sha256, if present, is the SHA-256 of the WHOLE file (even in response to RESUME), as 64 lowercase hexadecimal digits. A server MAY include it only when it has an up-to-date value (for example, cached by path, size, and modification time); it MUST NOT include a stale hash. - The server MUST open the file, then determine its size from the open file (not from the path), and send exactly that many bytes from the same open file. If the file grows meanwhile, the extra bytes are not sent. If the file shrinks or an I/O error occurs so that fewer than size bytes can be sent, the server MUST close the connection immediately, without padding and without sending the trailer. - The size in the FILE header is authoritative. If it differs from the size in the Manifest, the client SHOULD warn the user. Client rules: - The client reads exactly size bytes, then reads exactly five more bytes and verifies they are "\nEND\n". - If the connection closes or times out before the full body and trailer have been received, or the trailer does not match, the download failed. The client MUST NOT reuse the connection after a framing error, and MUST NOT present the data as a complete file. A client that supports resuming MAY keep the partial data in a clearly marked temporary file; otherwise it MUST delete it. - If sha256 is present, the client MUST verify the SHA-256 of the complete file once finished (for RESUME, over the whole assembled file) and MUST discard the file and report an error on mismatch. - For a zero-byte file, the server sends the FILE header with size=0, then the trailer "\nEND\n". The client reads zero bytes, then the five trailer bytes. 6.4 ERRORS <- FISP NOTFOUND name="" <- FISP ERROR reason=unreadable name="" - NOTFOUND -- no such servable file in the content root (including hidden names, sidecars, unservable names, directories, symlinks, and unsafe paths; see section 6.5). - ERROR -- the file exists but cannot be read (permissions or I/O error), detected before the header is sent. On NOTFOUND or ERROR, no file bytes and no trailer follow. The connection remains open. If the requested path contains bytes that cannot appear in a quoted value (control characters, invalid UTF-8), the server responds ERROR reason=bad_request WITHOUT name=, because it cannot safely echo the path. 6.5 PATH SAFETY - A server MUST respond NOTFOUND to any GET or RESUME path that is not a servable name (section 5.3): absolute, containing ".." or "." segments, empty segments, backslashes, colons, and so on. - The server MUST respond with NOTFOUND (not DENIED) for such paths, to avoid disclosing policy. - The server MUST NOT follow symlinks when serving. - The server MUST resolve and open paths without a race between checking and opening: it MUST traverse the path one component at a time relative to an open handle on the content root, refusing symlinks at every component (for example, openat with O_NOFOLLOW or the equivalent), and MUST confirm with the open file's own metadata that it is a regular file. - A GET with no argument is ERROR reason=bad_request. - A GET whose argument resolves to the content root itself (for example, GET . or GET /) is NOTFOUND. - Trailing slashes are not stripped. GET foo/ is not a servable name and returns NOTFOUND. ================================================================================ 7. ERRORS AND ROBUSTNESS ================================================================================ <- FISP ERROR reason= [name=""] Defined reasons: bad_request The request is malformed. Connection MAY stay open (except for first-line errors and over-length requests; see below). unknown_command The command is not recognized. Connection MAY stay open. bad_version The HELLO version prefix is not FISP. Connection MUST close. unreadable The requested file cannot be read. Only valid in response to GET or RESUME. list_failed The listing could not be produced. Only valid in response to LIST. No name=. - After a successful HELLO, a line whose first word is not a defined command receives ERROR reason=unknown_command. A server SHOULD close the connection after 20 consecutive error responses. - A malformed GET or RESUME (missing or invalid argument) receives ERROR reason=bad_request. - A request line is the sequence of bytes up to and including \n, at most 8192 bytes. If no \n is found within 8192 bytes, the server MUST respond ERROR reason=bad_request and close. - Any ERROR response to GET or RESUME MUST include name="" when the request contained a path that can be quoted (section 6.4), and MUST NOT include it otherwise. ERROR responses to HELLO and LIST MUST NOT include a name. - Clients MUST treat unknown ERROR reason= values as generic errors and MUST NOT crash. - Clients MUST treat any server line that does not match the grammar of Appendix A as a protocol error: close the connection and fail the operation. - First-line failures are governed by section 4.4: a peer that fails access control receives DENIED, not ERROR. ================================================================================ 8. HOME DIRECTORY AND CONTENT ROOT ================================================================================ 8.1 LAYOUT / |-- whitelist.txt (optional) |-- blacklist.txt (optional) |-- key.txt (optional) `-- files/ (content root, REQUIRED) `-- ... (arbitrary structure) - The content root is /files/. It MUST exist; if it does not, the server MUST refuse to start and report an error. - and /files MUST NOT be symlinks. The server MUST NOT follow a symlink to either directory. Symlinks inside the content root are governed by section 5.4. - whitelist.txt, blacklist.txt, and key.txt are read from /, not from the content root. They are therefore never served and never listed. - A file with one of those names inside the content root is an ordinary file and WILL be served. `fisp check` MUST warn about it (section 11.5). - The structure inside the content root is arbitrary and Sysop-defined. No folder name carries special meaning. - The folder name of and its location are arbitrary. The server is pointed at it with --home (or equivalent). Everything inside is addressed relative to , so the home directory is relocatable. 8.2 CONTROL FILE STATES A line of a control file is an ACTIVE LINE if it is not blank and not a comment. Blank means empty or only spaces and tabs. A comment is a line whose first non-space, non-tab character is #. (Lines end with \n or \r\n.) A control file is in exactly one state: absent it does not exist inactive it exists and has no active line active it exists and has at least one active line, and every active line is valid for that file invalid it cannot be read, or it has an active line that is not valid for that file (sections 10.1 and 10.2) Absent and inactive are equivalent (the mechanism is off). To turn a mechanism on, add active lines. To turn it off, empty the file or delete it. An invalid control file is never silently ignored: - At startup the server MUST refuse to start and report the file and line. - On reload (section 8.3) the server MUST keep the last valid configuration of that file and log an ERROR at least once a minute until the file is valid again. 8.3 RELOAD - The server MUST re-read control files when they change, and apply valid changes without a restart, within 10 seconds of the change. It MAY poll or use filesystem notifications. - To avoid acting on a half-written file, a changed file MUST be applied only after two consecutive reads at least 1 second apart return identical bytes. - Writers SHOULD replace control files atomically (write a temporary file in the same directory, then rename it over the original). `fisp key --rotate` does so. - When a reload makes access control weaker (whitelist.txt or key.txt going from active to inactive or absent), the server MUST log a WARN stating that access control has been weakened. - When a reload takes effect, section 10.5 governs existing connections. 8.4 EXAMPLE fisp/ |-- README.txt |-- whitelist.txt |-- blacklist.txt |-- key.txt `-- files/ |-- main/ | `-- notes.txt |-- pictures/ | `-- icecream.jpg `-- guest-info.txt (Note that README.txt sits in , beside the control files, not in files/. Only files/ is served. Name files carefully: filenames are public.) Manifest: FISP MANIFEST name="guest-info.txt" size=42 date=2026-10-17 desc="guest info" name="main/notes.txt" size=1204 date=2026-10-01 desc="meeting notes" name="pictures/icecream.jpg" size=88213 date=2026-09-30 desc="" END ================================================================================ 9. REACHABILITY AND ACCESS ================================================================================ 9.0 THE TWO PARTS OF ACCESSIBILITY A FISP server's accessibility has two independent parts, and only one of them is the protocol's business. REACHABILITY is whether a peer can open a TCP connection to the server at all. It is determined entirely by network configuration: port-forwarding, NAT, firewall rules, tunnels, bind addresses. The server cannot know or enforce its own reachability, and FISP carries no reachability information on the wire. ACCESS CONTROL is whether a peer that has reached the server is served. This is fully enforced by the server, via three optional mechanisms that compose (section 10). Because identity is the TCP source address, any NAT, reverse proxy, or tunnel in front of the server replaces the real client address with its own. Behind one, whitelist.txt, blacklist.txt, and per-peer limits cannot tell clients apart; use a key (section 10.2) instead of, or in addition to, IP lists. 9.1 COMMON CONFIGURATIONS Two independent axes describe a deployment's posture: Reach: lan (reachable only from a local network) world (reachable from the internet) Access: key (a key is required) open (no key required) The four combinations: Form Reach Access Who can connect --------------------------------------------------------------- lan-key lan key LAN peers with the key lan-open lan open any LAN peer world-key world key anyone worldwide with the key world-open world open anyone worldwide These names are informative. They describe the result of combining network configuration with access control. They are not protocol states, and clients cannot distinguish them. ================================================================================ 10. ACCESS CONTROL ================================================================================ 10.1 ACCESS LISTS whitelist.txt and blacklist.txt use the same format: - One IP address or CIDR range per line. - # begins a comment; the rest of the line is ignored. - Blank lines are ignored. - IPv4 and IPv6 are supported. IPv6 addresses may be written in any valid textual form (RFC 4291 / RFC 5952), case-insensitively; comparison is on the 128-bit value. IPv4-mapped IPv6 addresses (::ffff:192.168.1.1) match the corresponding IPv4 address. Zone indices (address%interface) are NOT supported. - Any active line that is not a valid address or CIDR range (including a line with a zone index) makes the file invalid (section 8.2). A server MUST NOT skip it silently. Example: # FISP whitelist 192.168.1.0/24 10.0.0.5 2001:db8::/32 Semantics: whitelist.txt blacklist.txt Effective access --------------------------------------------------------------- inactive inactive Any reachable peer active inactive Only whitelisted peers inactive active Any reachable peer, except blacklisted ones active active Whitelisted peers that are not also blacklisted --------------------------------------------------------------- Peer in both lists Denied (deny wins) Invariants: - Neither file can widen network reachability; they only narrow it. - There is no special treatment of 127.0.0.1 or ::1. Loopback peers are subject to the lists like any other peer. (A server bound only to a loopback address is reachable only from the local host regardless.) - An entry in blacklist.txt that falls inside an entry of whitelist.txt is a valid way to carve out a host or subrange; it requires no warning. 10.2 ACCESS KEYS A server MAY require a single server-wide access key. 10.2.1 WHERE THE KEY LIVES - The key is read from /key.txt, or from --key on the command line. If both are present, --key takes precedence for that run. - key.txt is a UTF-8 text file. Lines beginning with # (after optional spaces or tabs) are comments. The first active line is the key. Leading and trailing spaces and tabs (and a trailing \r) on that line are not part of the key. A second active line makes the file invalid (section 8.2). - A key MUST be 12 to 1024 bytes of UTF-8 after trimming, MUST NOT contain control characters, and MUST NOT begin with #. A key outside these limits makes key.txt (or --key) invalid. Servers refuse to start with it. - If key.txt is absent, or inactive, and --key is not given, the server runs with no key. - The server MUST NOT auto-generate a key. Only `fisp init` (which creates an empty key.txt if none exists) and `fisp key --rotate` (below) may write key.txt. `fisp serve` never writes to it. - key.txt is a control file: never served, never in the Manifest. - Keys are compared as raw UTF-8 bytes. No normalization is applied. - On POSIX systems, files created by fisp for key material MUST have mode 0600, and the server SHOULD log a WARN at startup (and on reload) if key.txt is readable by group or other. 10.2.2 BEHAVIOR - If a key is configured (key.txt active, or --key is given), every connection MUST present it in HELLO. On failure, DENIED reason=bad_key and close. - The server MUST compare keys in constant time with respect to their content and length: it SHOULD compare fixed-length digests (for example the SHA-256 of each key), not the raw keys. - If no key is configured, the server ignores any key= field and proceeds. In particular key="" is ignored. - Key changes take effect for new connections after reload (section 8.3) and affect existing connections as section 10.5 says. 10.2.3 VISIBILITY AND KEY MANAGEMENT - If the server prints a startup summary (section 11.2), the summary MUST say whether a key is configured and its source, and MUST NOT print the key value. - `fisp key --home ` prints the source and whether the key meets the requirements of section 10.2.1. It does not print the key. - `fisp key --rotate --home ` generates a fresh key of 128 random bits from the operating system's cryptographic random source, written as 32 lowercase hexadecimal characters; writes it atomically to key.txt with mode 0600; and prints it once to standard output. Standard output may be captured by terminals or logs. The Sysop is responsible for handling it accordingly. - --key on the command line is visible in process listings and shell history. The server MUST log a WARN at startup whenever --key is used, whether or not key.txt exists. 10.3 COMBINING MECHANISMS All three mechanisms may be used together. A peer is served only if it passes every active mechanism: - the whitelist, if active (peer must be listed), AND - the blacklist, if active (peer must not be listed), AND - the key, if active (HELLO must present it). The order of evaluation, and the response for each failure, is fixed by section 4.4: IP lists first (DENIED reason=denied), then the key (DENIED reason=bad_key). 10.4 FAILED KEY ATTEMPTS - The server MUST wait 1 second before sending DENIED reason=bad_key (section 4.4, step 6). - The server MUST count failed key attempts per peer. After 10 failures within 10 minutes, the server MUST refuse that peer for the next 10 minutes: during that time, step 3 of section 4.4 applies and the server responds DENIED reason=denied without evaluating any key. - Servers MAY use stricter limits. 10.5 EXISTING CONNECTIONS AFTER A CHANGE When a reload (section 8.3) takes effect, the server MUST, within 5 seconds, close every existing connection that it would not admit if it had connected now with the same HELLO. That includes peers newly excluded by the lists, and connections that presented a key that is no longer the configured key (or no key where one is now required). An in-progress transfer is aborted by closing the connection. A client treats it as an ordinary failed download. Connections that would still be admitted are unaffected. ================================================================================ 11. SERVER OPERATION (REFERENCE BEHAVIOR) ================================================================================ The following describes the reference server (ferretd, fisp serve). Other implementations MAY differ in CLI, but MUST behave identically on the wire and MUST implement the behavior of sections 3 through 10. 11.1 COMMAND-LINE INTERFACE fisp serve [--home ] [--port ] [--bind ] [--key ] [--serve-hidden] fisp init [--home ] fisp check [--home ] fisp key [--home ] [--rotate] Flag Default Meaning --------------------------------------------------------------- --home ./fisp Home directory (resolved to an absolute path; the server logs it) --port 7070 TCP port --bind 127.0.0.1 Listen address. Loopback by default; the Sysop must opt in to network exposure (0.0.0.0 for all IPv4 interfaces; :: for IPv6, usually dual-stack depending on the OS) --key none Transient access key; overrides key.txt; see section 10.2.3 --serve-hidden off Serve names with a segment beginning with "." --------------------------------------------------------------- A server started by a service manager SHOULD pass --home explicitly, because the default is relative to the working directory. 11.2 STARTUP SUMMARY (OPTIONAL) A server MAY print a summary at startup. If it does, the summary MUST include key status and source, MUST NOT include the key value, and MUST NOT claim that the server is or is not reachable from the internet or a LAN, which it cannot know. Example: FISP server starting Home: /home/pi/fisp Content root: /home/pi/fisp/files (4 files, 2 folders) Skipped: 0 names (see: fisp check) Listening on: 192.168.1.42:7070 Whitelist: present (3 entries) Blacklist: none Access key: present (/home/pi/fisp/key.txt, not echoed) Hidden files: not served Ready. Press Ctrl+C to stop. (A whitelist together with a key is a valid configuration; see section 10.3.) When bound to loopback only, the summary SHOULD say that only this machine can connect and name --bind. 11.3 LOGGING (RECOMMENDED) One line per connection and per GET or RESUME, including a full UTC timestamp (date and time with offset), the peer IP, outcome, and path. Example: [2026-10-17T10:42:01Z] 192.168.1.77 HELLO ok [2026-10-17T10:42:03Z] 192.168.1.77 GET guest-info.txt 42B [2026-10-17T10:43:12Z] 203.0.113.9 DENY denied - Key values MUST NOT appear in per-connection logs. - Any client-supplied text (requested paths, commands) MUST be logged with control characters, line feeds, and invalid UTF-8 bytes escaped (for example as \xNN), so that a client cannot forge log lines. - Logs contain peer addresses and requested paths. The Sysop is responsible for their retention and protection. Startup SHOULD also log: - whitelist.txt / blacklist.txt / key.txt changes (with entry counts) - unreadable files in the content root - unservable names omitted (section 5.3) - orphan or case-mismatched sidecars (section 5.6) - manifest limit reached (if a limit is configured) 11.4 PUBLIC-MODE WARNING (RECOMMENDED) If the server is bound to any address other than loopback and neither a key nor a whitelist is active, the server SHOULD log at startup: [WARN] this server has no key and no whitelist and is listening on a non-loopback address. Anyone who can reach this port can download everything in files/. Because the default bind is loopback, this warning does not fire on a default run. The server cannot detect internet reachability; do not suppress the warning on the grounds that "this is only a LAN". 11.5 fisp check Validates the home directory and prints what would be served. It reports every condition that would prevent `fisp serve` from starting (missing content root, an invalid control file, a key that does not meet section 10.2.1) and exits non-zero on them. Otherwise it exits 0, with warnings as appropriate. In addition, it MUST warn about: - files inside the content root named whitelist.txt, blacklist.txt, or key.txt, and files that commonly hold secrets (for example .env, id_rsa, id_ed25519, *.pem, *.key, *.pfx), which are public once placed there; - unservable names, orphan sidecars, and case-mismatched sidecars; - a key.txt readable by group or other (POSIX); - names that collide on a case-insensitive filesystem (section 5.3). Example output: $ fisp check --home ./fisp Home: /home/pi/fisp Content root: /home/pi/fisp/files (4 files, 2 folders) Configuration: whitelist: absent blacklist: absent key: present (required) Warnings: none Reminder: FISP reachability is determined by networking. The default bind address is 127.0.0.1 (this machine only). If you intend this server to be reachable from a network or the internet, set --bind and ensure port-forwarding or a tunnel is configured, and use a key. 11.6 fisp init Creates and /files/ if they do not exist. Creates empty control files (whitelist.txt, blacklist.txt, key.txt) with comment headers if they do not exist (key.txt with mode 0600 on POSIX). Does not overwrite existing files. Prints what was created. If already exists with content, is a no-op except for missing subdirectories and missing control files. ================================================================================ 12. CLIENT REQUIREMENTS ================================================================================ A server is not trusted. Everything it sends -- names, sizes, dates, descriptions, error text, framing -- is untrusted input. A conformant client MUST satisfy this section. 12.1 VALIDATING SERVER DATA - Before using a name from a manifest or FILE header in any way (display, comparison, filesystem), the client MUST verify it is a servable name under section 5.3, and skip the entry with a notice if it is not. (Clients cannot rely on servers to have enforced it.) - The client MUST verify size (and offset) have the syntax of section 5.2 and are at most 9223372036854775807, date (if present) is a valid calendar date, and sha256 (if present) is 64 lowercase hexadecimal digits. An entry that fails these checks MUST be skipped. - The client MUST verify that the name= in a FILE header equals the path it requested (after unescaping), and MUST treat a mismatch as a protocol error. - Protocol lines longer than 16384 bytes are protocol errors. 12.2 FILESYSTEM SAFETY - The client writes only beneath a download directory chosen by the user. The destination is that directory plus the validated relative name. Before writing, the client MUST ensure the resulting path, with any existing symlinks resolved, lies inside the download directory, and MUST refuse to write through an existing symlink. - The client MUST NOT overwrite an existing file unless the user has explicitly allowed it. - The client MUST detect name collisions -- among entries of one manifest and with existing files -- including collisions that arise only on case-insensitive or Unicode-normalizing filesystems (for example "A.txt" and "a.txt"), and MUST NOT let one silently overwrite another. - The client SHOULD write to a temporary file in the destination directory and rename it into place only after the download (and integrity check) has succeeded. - Downloaded files MUST NOT be given executable permissions. 12.3 RESOURCE LIMITS - Clients MUST stream file bodies to disk, never allocating memory in proportion to a server-declared size. - Clients MUST enforce limits on manifests: at most 100,000 entries and 64 MiB by default, user-configurable. A manifest exceeding the limits is treated as failed (partially processed entries are not presented as complete). - Clients MUST allow the user to set a maximum file size. They MUST, where the information is available, refuse a download whose declared size exceeds the free space at the destination. - Clients MUST apply timeouts: at most 15 seconds to establish a connection, and at most 60 seconds without receiving any bytes during any operation. 12.4 DISPLAY Before showing any server-supplied text (names, descriptions, error text) in a terminal or user interface, the client MUST strip or escape control characters and bidirectional formatting characters. 12.5 KEYS - A client MUST store each key together with the server address (host and port) it belongs to, and MUST NOT send a stored key to any other address. - A client SHOULD first connect without a key. If the server responds DENIED reason=bad_key, it asks the user for a key (or uses the one stored for that address) and reconnects with it. - A client SHOULD store keys with restricted permissions and SHOULD offer a way to supply a key other than a command-line argument (for example a prompt, a file, or the environment). - The key travels in plaintext (section 14). A client SHOULD tell the user so when they enter one. 12.6 RESUME AND INTEGRITY - A client that resumes with RESUME MUST confirm, before appending, that the remote file is unchanged since the partial download began, by comparing size, date, and sha256 where available. If it cannot tell, or they differ, it MUST restart the download from the beginning. - A client MUST verify sha256 when present (section 6.3). 12.7 BUSY A client that receives BUSY waits and reconnects (section 4.5). It does not retry on the same connection. ================================================================================ 13. CONFORMANCE ================================================================================ 13.1 CLIENT A FISP client is conformant if it: 1. Connects to a server on TCP port 7070 (or a specified port). 2. Sends HELLO and correctly interprets OK, DENIED (both reasons), ERROR, and BUSY (section 12.7). 3. Sends HELLO with no key= field when it has no key for that address, and HELLO key="" (with escaping) when it has one; never sends a key to a different address (section 12.5). 4. Sends LIST and parses the Manifest, ignoring unknown fields and lines that do not begin with name=, treating a missing END as a failed listing. 5. Does not depend on manifest entry order or field order. 6. Validates names, sizes, dates and hashes (section 12.1); skips invalid entries. 7. Sends GET (and, if it supports resume, RESUME) and receives exactly size bytes followed by the five-byte trailer "\nEND\n"; treats any mismatch, short read, or timeout as a failed download and does not reuse the connection. 8. Handles NOTFOUND, ERROR (including unknown reasons), and mid-transfer failure. 9. Handles multiple LIST calls, and GET for names not in the most recent Manifest. 10. Handles zero-byte files. 11. Verifies sha256 when present. 12. Observes the filesystem rules of section 12.2: no escape from the download directory, no silent overwrite, collision detection, no executable permission. 13. Observes the resource limits of section 12.3 and display rules of section 12.4. 13.2 SERVER A FISP server is conformant if it: 1. Closes connections that send no first line within 30 seconds. 2. Evaluates the first line in the order of section 4.4, responding OK, DENIED, BUSY, or ERROR accordingly, and closes after every response other than OK. 3. Responds DENIED to any peer refused by the lists or lockout, whatever the peer sent (including malformed or over-length first lines). 4. Classifies version and syntax errors per section 4.4 step 5. 5. Enforces per-peer and global connection limits (BUSY, then close). 6. Enforces the idle timeout and transfer stall timeout (section 3). 7. Accepts \r\n and emits \n; enforces the 8192-byte request line limit. 8. Serves the Manifest per section 5, listing only servable names, hiding control files, sidecars and hidden names, not following symlinks, with fields in the specified order and sizes in the specified syntax. 9. Serves GET and RESUME per section 6, with exact byte counts, the five-byte trailer, and abrupt close on a short read. 10. Rejects unsafe paths per section 6.5, with race-free opening. 11. Enforces access control per section 10, including combining all three mechanisms, constant-time (digest) key comparison, the 1-second failure delay, and the lockout. 12. Uses the peer's TCP source IP as identity, with no loopback exemption. 13. Treats invalid control files per section 8.2 (refuse to start; keep the last valid configuration on reload). 14. Reloads control files per section 8.3, and closes connections that are no longer admitted per section 10.5. 15. Escapes client-supplied text in logs (section 11.3). 13.3 INTEROPERABILITY Any conformant client SHOULD interoperate with any conformant server. Implementations are encouraged to use the byte-exact examples of Appendix B as test vectors. The executable reference conformance suite described in section 15 is planned and is not currently available. ================================================================================ 14. SECURITY CONSIDERATIONS ================================================================================ - NO ENCRYPTION. FISP is plaintext, including access keys. Anyone on the network path can read keys and files, and can alter downloads (unless sha256 is used and obtained through a trusted path, which FISP does not provide). Use on trusted networks or for non-sensitive files. - NO SERVER AUTHENTICATION. A client cannot verify that the address it reached is the server it intended. Never send a key to a server you do not control; clients enforce per-address keys (section 12.5). - THREAT MODEL. A FISP server exposes complete copies of files in files/ to any peer that passes access control, and reveals the names, sizes, dates, hashes and descriptions of those files. The only defenses are: (a) put only shareable files in files/, and (b) restrict who can connect, via networking, whitelist.txt, blacklist.txt, or key.txt. Path safety rules (section 6.5) are correctness properties -- they ensure the server serves files/ and nothing else -- not confidentiality mechanisms. - IDENTITY IS THE SOURCE IP. NAT, proxies, tunnels, and shared networks make IP-based access control coarse, and a tunnel or proxy in front of the server makes IP lists and per-peer limits meaningless (section 9.0). IPv6 hosts can change addresses within a /64 at will; per-address blacklisting does not stop them. - KEYS ARE SHARED. A single key cannot be revoked per person. Rotate it (section 10.2.3) to cut everyone off; section 10.5 closes their connections. - BRUTE FORCE. Keys are at least 12 bytes; `fisp key --rotate` produces 128 random bits; failures are delayed and locked out (section 10.4). A weak human-chosen key is still weak. - FAIL-SAFE CONFIGURATION. An unreadable or malformed control file is never ignored silently (section 8.2). An emptied key.txt or whitelist.txt, however, deliberately turns that mechanism off; a WARN is logged (section 8.3). Keep control files under restricted permissions and replace them atomically. - CONTENT ROOT IS A JAIL. Unservable names, absolute paths, and symlinks are rejected; files are opened without following symlinks and without a check/open race. - CONTROL FILES ARE OUTSIDE THE SERVED TREE and never listed. A file that merely has a control file's name inside files/ is just a file and is public. - DENIAL REASONS ARE MINIMAL. IP-list refusals share one reason (denied). bad_key necessarily reveals that a key is required. - OPEN SERVERS ARE PUBLIC. A server with no key and no access lists serves anyone reachable. This is appropriate for community archives and public file hosts; it is not appropriate for private data. The Sysop is responsible for the content served; a Sysop who receives complaints can blacklist addresses. - KEYS ARE SYSOP-PROVIDED. FISP does not generate keys at startup. - RESOURCE LIMITS ARE REQUIRED. Servers cap request line length, per-peer and global connection counts, idle time, and stalled transfers; clients cap manifests, sizes, and time (sections 3 and 12.3). - FILENAMES ARE PUBLIC. The Manifest reveals filenames to every peer that passes access control. Do not put sensitively named files in a shared folder unless you trust the access list. - PRIVACY OF LOGS. Logs record peer addresses and requested paths. - STARTER KIT HYGIENE. When using a starter kit, content belongs in the local files/ directory and should not be committed to its repository. ================================================================================ 15. REFERENCE ARTIFACTS ================================================================================ Planned reference client: B2/FISPConnect (also fispc on the command line) Planned reference server: ferretd (fisp binary) Planned starter kit: fisp/ -- intended for distribution through GitHub Releases Planned conformance suite: conformance/ -- intended to provide executable checks for section 13 and the vectors of Appendix B Specification source: this document, published at https://bbsys.net/doc/fisp/ When available, reference artifacts SHOULD conform to this text. Where a reference artifact and this text disagree, this text defines the current proposal; the artifact may need correction. ================================================================================ 16. OUT OF SCOPE ================================================================================ The following are explicitly excluded from this experimental draft of FISP. They are not currently specified. Future revisions may clarify or change the specification; implementers MUST NOT assume wire compatibility between revisions unless explicitly stated. Any items added by a future revision will be defined by that revision. - Uploads, deletes, or any write operations over the wire - Hierarchical browsing or paging (LIST ); the Manifest is flat - Transport encryption and server authentication - Server-declared names or identity, or reachability information - Discovery, directories, or central registries - Accounts, sessions, or per-user or per-path permissions - Compression or content negotiation - Version negotiation within FISP - Multi-file or parallel transfers on one connection ================================================================================ 17. CHANGE CONTROL ================================================================================ This document is an experimental draft defining FISP as currently proposed. Future revisions may clarify, correct, or change this specification. Implementers MUST NOT assume that future revisions will be wire-compatible unless explicitly stated. The current wire protocol identifies itself as FISP; this change-control text does not introduce version negotiation or change the wire protocol. Revisions and editorial errata may be published at the canonical URL. They may correct wording errors, typographical errors, and demonstrable contradictions, and may also change the specification. Each revision should identify its changes, including any changes that affect wire behavior. The tolerance rules of section 5.4 (ignoring unknown manifest fields and lines) and section 7 (generic handling of unknown error reasons) exist for robustness only. They do not define extension points. Implementations MUST identify themselves on the wire as FISP. They MUST NOT send FISP/1, FISP/2, or any other version-qualified prefix. ================================================================================ APPENDIX A -- GRAMMAR (ABNF, RFC 5234) ================================================================================ Semantic constraints stated in the text (servable names, numeric limits, maximum lengths) apply in addition to this grammar. Where the grammar and the text disagree, the text governs. LF = %x0A CR = %x0D EOL-IN = [CR] LF ; request terminator (servers accept) SP = %x20 DQUOTE = %x22 DIGIT = %x30-39 OCTET = %x00-FF ; --- quoted strings (names, descriptions, keys) --- quoted = DQUOTE *qchar DQUOTE qchar = qescape / qplain qescape = %x5C (DQUOTE / %x5C) qplain = %x20-21 / %x23-5B / %x5D-7E / nonascii nonascii = ; --- numbers --- size = "0" / (%x31-39 *DIGIT) ; <= 9223372036854775807 offset = size date = 4DIGIT "-" 2DIGIT "-" 2DIGIT ; valid calendar date hash = 64(DIGIT / %x61-66) ; lowercase hex token = 1*(%x61-7A / DIGIT / "_") ; --- requests (client to server) --- request = hello / list / get / resume hello = "FISP" SP "HELLO" [SP "key=" quoted] EOL-IN list = "LIST" EOL-IN get = "GET" SP path EOL-IN resume = "RESUME" SP offset SP path EOL-IN path = 1*(%x01-09 / %x0B-0C / %x0E-FF) ; raw, not escaped; ; a CR directly ; before LF belongs ; to EOL-IN ; --- responses (server to client) --- ok = "FISP" SP "OK" LF denied = "FISP" SP "DENIED" SP "reason=" ("denied" / "bad_key") LF busy = "FISP" SP "BUSY" LF error = "FISP" SP "ERROR" SP "reason=" token [SP "name=" quoted] LF notfound = "FISP" SP "NOTFOUND" SP "name=" quoted LF manifest = "FISP" SP "MANIFEST" LF *entry "END" LF entry = "name=" quoted SP "size=" size [SP "date=" date] [SP "sha256=" hash] SP "desc=" quoted LF file = "FISP" SP "FILE" SP "name=" quoted SP "size=" size [SP "offset=" offset] [SP "sha256=" hash] LF body trailer body = *OCTET ; exactly "size" octets trailer = LF "END" LF ; always the five bytes 0A 45 4E 44 0A ================================================================================ APPENDIX B -- BYTE-EXACT EXAMPLES ================================================================================ Notation: \n is the single byte 0x0A. Nothing else is implied: there are no extra bytes between the pieces shown on one line. B.1 Handshake, no key required -> FISP HELLO\n <- FISP OK\n B.2 Handshake, key required. The key is the 16 characters pa"ss\word-12345 (it contains a double quote and a backslash, so both are escaped on the wire): -> FISP HELLO key="pa\"ss\\word-12345"\n <- FISP OK\n B.3 Wrong key -> FISP HELLO key="nope"\n <- (after 1 second) FISP DENIED reason=bad_key\n (server closes the connection) B.4 Refused by access list (whatever the peer sent) -> GARBAGE\n <- FISP DENIED reason=denied\n (server closes the connection) B.5 Version mismatch and command before HELLO -> FISP/2 HELLO\n <- FISP ERROR reason=bad_version\n (server closes) -> LIST\n <- FISP ERROR reason=bad_request\n (server closes) B.6 Manifest -> LIST\n <- FISP MANIFEST\n <- name="guest-info.txt" size=42 date=2026-10-17 desc="guest info"\n <- name="main/notes.txt" size=1204 desc=""\n <- END\n B.7 File whose last byte is a line feed (6 bytes: hello then LF) -> GET a.txt\n <- FISP FILE name="a.txt" size=6\nhello\n\nEND\n That is: the header line; the 6 body bytes h e l l o \n ; the trailer \n E N D \n . B.8 File with no trailing line feed (3 bytes: abc) -> GET b.txt\n <- FISP FILE name="b.txt" size=3\nabc\nEND\n B.9 Zero-byte file -> GET empty.txt\n <- FISP FILE name="empty.txt" size=0\n\nEND\n B.10 Resume (file is 6 bytes, hello then LF; client has "he") -> RESUME 2 a.txt\n <- FISP FILE name="a.txt" size=4 offset=2\nllo\n\nEND\n B.11 Not found, unreadable, bad offset -> GET missing.txt\n <- FISP NOTFOUND name="missing.txt"\n -> GET locked.txt\n <- FISP ERROR reason=unreadable name="locked.txt"\n -> RESUME 99 a.txt\n <- FISP ERROR reason=bad_request name="a.txt"\n B.12 Unservable path -> GET ../secret\n <- FISP NOTFOUND name="../secret"\n B.13 Truncated transfer (what the client sees) <- FISP FILE name="big.bin" size=1000000\n + 400000 bytes, then the server closes the connection The client has not received size bytes plus the trailer: the download failed; the partial data is not a complete file. ================================================================================ APPENDIX C -- CHANGES FROM THE EARLIER DRAFT ================================================================================ This text supersedes earlier drafts. Implementations written to an earlier draft must be updated. Wire-incompatible changes: W1. FISP OK no longer carries files= or scope=. (The advisory count forced a full tree walk on every connection; scope had no defined use and could be falsified.) W2. File bodies are followed by the fixed five-byte trailer "\nEND\n". The earlier text did not say whether a line feed separated the body from END. W3. DENIED reasons are now denied and bad_key. not_whitelisted, blacklisted, and unexpected_key are gone. A server with no key ignores a key= field instead of denying it. W4. BUSY is followed by close; there is no retry on the same connection, and a global connection limit exists. W5. The first line of every connection is checked against the access lists before it is parsed. Malformed first lines from permitted peers get ERROR reason=bad_request; non-FISP first words with HELLO second get bad_version. This removes the earlier three-way conflict between sections 3, 4.6 and 7. W6. Overlapping GET is no longer an error. Commands are processed in order and responses are never interleaved. W7. New commands and fields: RESUME and offset=; optional sha256=; list_failed error; date= is omitted instead of 0000-00-00. W8. Servable-name rules (section 5.3) replace the open-ended name rules; non-servable files are omitted. Hidden names are not served by default. W9. Manifest lines must now always include desc= (possibly empty). A manifest line that cannot be parsed is skipped, not treated as downloadable. Behavioral and operational changes: O1. Whitelist and key may be combined (AND). The earlier refusal to start is removed. O2. The earlier contradiction on the order of the blacklist and key checks is resolved: lists first, key last. O3. Empty control files remain "off", but an unreadable or malformed file is never skipped silently (refuse to start; keep last valid configuration on reload). Reloads are mandatory, debounced, and logged when they weaken access control. O4. Existing connections are closed when a reload revokes them. O5. Default bind is 127.0.0.1. The loopback special case is removed. O6. Key rules: 12-byte minimum, trimmed, one key line; constant-time digest comparison; 1-second failure delay and lockout; rotation writes atomically with mode 0600 from a CSPRNG; --key always warns. O7. Race-free path opening; open-file sizes; abrupt close on short read; servers do not follow symlinks. O8. Sidecar rules are precise (only with a matching base file; orphans are listed and reported). O9. Idle, stall, per-peer, and global limits are required. O10. LIST responses may be up to 5 seconds old and are rate-limited. O11. fisp check warns about secrets and control-file names inside files/, orphan sidecars, and unservable names. The startup summary is optional and may not claim reachability. The banner example no longer shows a forbidden configuration. O12. Logs use full timestamps and escape client-supplied text. O13. Section 12 (client requirements) is new: validation, filesystem safety, collision handling, limits, display safety, key handling, resume and integrity. O14. Conformance lists cover the normative text. Appendix A (ABNF) and Appendix B (byte-exact examples) are new. O15. The change-control text describes an experimental draft that may be revised; implementers must not assume wire compatibility between revisions unless explicitly stated. The unknown-field and unknown-reason tolerance rules remain robustness rules, not extension points. ================================================================================ FISP is an open protocol. B2/FISPConnect is the planned reference client. The protocol name belongs to no one. Published by Binary & Bus, Sys. -- bbsys.net -- B2/ ================================================================================