Peergos curriculum: independent text review (Phase 1d)
Reviewed 2026-10-22 against the Video Curriculum Guide and the live sources: peergos.org (home), book.peergos.org (every page listed in the brief, plus features/social.html and features/sharing.html, which two findings needed), the blog posts "2025 - What a year!" and "Security audit 2024", and the GitHub README. Every page was fetched as raw text and grepped for the exact phrases quoted below. There is no implementation to run.
Length was estimated with the guide's formula (2.3 words per second, plus 0.7 s per line and 1.5 s per beat). All 24 units land inside their own target and inside 45 to 65 s; the two shortest are units 17 and 19 at about 45 s.
Unit | Beats | Lines | Words | Estimate | Target |
|---|---|---|---|---|---|
1 | 5 | 15 | 103 | 63 s | 55-65 |
2 | 5 | 12 | 106 | 62 s | 55-65 |
3 | 5 | 12 | 98 | 59 s | 50-60 |
4 | 5 | 9 | 88 | 52 s | 50-60 |
5 | 5 | 12 | 98 | 59 s | 50-60 |
6 | 5 | 11 | 97 | 57 s | 50-60 |
7 | 5 | 11 | 81 | 50 s | 45-55 |
8 | 5 | 13 | 88 | 55 s | 50-60 |
9 | 5 | 12 | 94 | 57 s | 50-60 |
10 | 5 | 10 | 94 | 55 s | 50-60 |
11 | 5 | 12 | 75 | 49 s | 45-55 |
12 | 5 | 11 | 82 | 51 s | 45-55 |
13 | 5 | 14 | 103 | 62 s | 55-65 |
14 | 5 | 10 | 79 | 49 s | 45-55 |
15 | 5 | 10 | 89 | 53 s | 50-60 |
16 | 5 | 9 | 80 | 49 s | 45-55 |
17 | 5 | 9 | 72 | 45 s | 45-55 |
18 | 5 | 10 | 89 | 53 s | 50-60 |
19 | 5 | 10 | 71 | 45 s | 45-55 |
20 | 5 | 12 | 88 | 54 s | 50-60 |
21 | 5 | 10 | 97 | 57 s | 50-60 |
22 | 5 | 10 | 77 | 48 s | 45-55 |
23 | 5 | 10 | 78 | 48 s | 45-55 |
24 | 5 | 12 | 92 | 56 s | 50-60 |
Finding ids: W wrong, O overstated, N unsupported by the recorded sources, X cross-unit inconsistency, M omission that produces a wrong model, S structure and style (not an accuracy class; listed so the tally is honest).
Summary
Sixteen units go back to 1b, eight pass. The curriculum's storage half (units 3 to 9) is largely right and well ordered. The faults cluster in three places: the sharing mechanism (units 10, 18, 19, which disagree with each other and with the book about where the post-quantum seal sits and what travels in a follow request), the block access token (unit 13 calls the secret a signature, which contradicts unit 9), and three security claims the book itself qualifies and the scripts do not (the app and website sandbox, the server-side view, and friends-reading-the-same-file). Five findings are plainly wrong, and three of those are in the recorded source statements, so the author read a page and wrote down something the page does not say. The guide's lesson from Anytwo applies again: the reviewer could only check what was recorded, and two of the most useful pages (features/sharing, features/social) were not recorded at all.
Per-unit review
Each unit answers the guide's seven questions in order: (1) one idea, (2) every beat serves it, (3) metaphor carried and spoken, (4) assumptions covered earlier, (5) misconception addressed, (6) length, (7) claims true to source. Then a verdict.
Unit 1: a server you do not have to trust
Yes: Peergos hides contents, names, sizes, folders and contacts from its server, and anyone can run one.
Yes. Beat 5 is a table of contents, which a framing unit may carry.
Card says "None; a framing unit." The guide asks for one per unit; a framing unit without one is a defensible exception, noted and not counted.
Nothing assumed.
Yes, beat 2.
63 s, inside 55-65.
All four claims are on the home page ("Encrypting the contents is the easy half", "run the whole thing yourself, for nothing, and still share with everyone else", "0 investors", "100% open source, server included") and the 2025 post ("non-profit funded directly by the people who use it").
Verdict: pass.
Unit 2: your password never leaves your device
Yes: scrypt on the device turns the password into a login key pair and a symmetric key, and the server only ever stores a bundle it cannot open.
Yes.
"A sealed bundle the server stores but cannot open" is spoken ("a sealed bundle", "The server stored the bundle. It never had the key.").
No. Four terms arrive here undefined: "key pair", "symmetric key", "home server" (defined in unit 16) and "capability" (defined in unit 9). The audience is builders, but the guide's rule is that dependencies are on ideas, and the Anytwo lesson is to say what an account is before the first key pair. See S1.
Yes, beat 1.
62 s, inside 55-65. Screen at beat 5 shows the bundle, the key, and three contents: five things (S3).
W1 (wrong). Beat 1: "You log in with a username and a password. Neither one is sent anywhere." The username is sent. The login page says "The public salt and encrypted login data are stored on your home server", so the client must name the user to get the salt and the bundle, and the PKI lookup of the home server is by username (architecture/pki.html: getChain(String username)). The README's own phrasing is the right one: "Your password never leaves your machine." Fix: "You log in with a username and a password. The password is never sent anywhere." M6 (omission, low). The script never says where the public salt comes from; a viewer will assume it is local. One clause in beat 2: "a public salt your home server keeps". Everything else matches security/login.html word for word: scrypt on password, username and salt; "login keypair and a symmetric key"; login data "contains your identity keypair, social keypair, and the root capability to your filesystem".
Verdict: back to 1b. Fix beat 1 (W1), add the salt's origin (M6), and open with one line that says what a key pair and a symmetric key are, or add that line to unit 1.
Unit 3: blocks are found by their hash
Yes: storage is content-addressed, so the client can check every block and any node will do.
Yes.
Card: "Asking for a block by its fingerprint." The word "fingerprint" is never spoken; the script says "named by its hash". Either speak it once or change the card (S2).
Yes (unit 1). "Node" and "server" are used interchangeably from here on without a word on it; low.
Yes, beat 4.
59 s, inside 50-60.
True to architecture/immutable.html: "allows anyone authorised to retrieve cipher text from its hash through any Peergos node"; "Every hash and signature is checked client side during reads and writes"; "local harddisk or any S3 compatible object storage without loss of privacy". Beat 2's "Any Peergos node can serve it, if you are allowed to have it" does square with BATs, because security/bats.html says "any instance that retrieves such a block (after being authorised) can continue to serve it up and enforce the same access control", but the series never says that sentence anywhere (see M2 under unit 13).
Verdict: pass, with the metaphor spoken or dropped.
Unit 4: a file is chunks, each with its own key
Yes: chunk, pad, encrypt each chunk under a random key.
Yes.
"Cutting a file into slices and sealing each separately": "cut into pieces" is spoken; "sealed" appears only on screen. Acceptable.
No: beat 5 and the check question use "read capability" five units before unit 9 defines capability (S1).
Yes, beat 4.
52 s, inside 50-60.
O1 (overstated). Beat 2: "So the exact size is not written anywhere." The size is written, encrypted. security/meta.html: "All of the metadata for a given file is encrypted ... This includes ... the filesize". Fix: "So the server never learns the exact size." S6. Beat 3 names "Salsa twenty with Poly thirteen oh five, from TweetNaCl". True (security/encryption.html: "salsa20+poly1305 (from TweetNaCl)") but it is a technical term that is not the thing being taught and is never defined. Cut it or keep it as a half-line the viewer can ignore. The per-chunk random key is supported by dev/upload.html ("Encrypt the padded 5 MiB file section with a random symmetric key"), and "not linkable unless you have a read capability" is on the encryption page. 5 MiB and 4 KiB match both pages.
Verdict: back to 1b for the one-word fix in beat 2; otherwise sound.
Unit 5: the server sees a bag of blobs under random labels
Yes: the server holds a flat map from random labels to blobs, so the folder shape is invisible.
Yes.
"A bag with no shape" is spoken ("The bag has none"); the break is spoken as "The shape lives inside the ciphertext, where the server cannot see it".
Yes (unit 4).
Yes, beat 4.
59 s, inside 50-60.
X1 (cross-unit, also overstated). Beat 5: "The whole bag has one root hash. Everything you own hangs from it." architecture/champ.html: "All the data under a given writing keypair has its own merkle-champ." There is one root per writing key pair, and unit 7 beat 3 says exactly that ("That key gets its own pointer and its own bag of blobs"). Unit 5 as written teaches a single root for the account, which unit 7 then contradicts. Fix beat 5: "A bag has one root hash. Everything in it hangs from that one hash." Leave "everything you own" out. N1 (unsupported, benign). Beat 2: "Change one entry, and only the path to the root changes." True of any merkle trie, but on no recorded page; the champ page says only that the structure is "explained in the next section". Keep or cut; if kept, record a source. A nuance for the check question: dev/upload.html says later chunks of a file sit "under a random 32 byte label for initial chunks, or sha256(stream secret + previous label)", so the labels are unrelated to the server, not unrelated in fact. The script's "different label" is fine; the screen's "unrelated labels" and the check question's expected answer should say "unrelated as far as the server can tell". The pointer actually targets a WriterData whose tree field links the champ root (architecture/writer.html); the parking list already defers this, and the simplification is acceptable.
Verdict: back to 1b for beat 5 (X1).
Unit 6: a pointer is a signed arrow from a key to a root
Yes: the only mutable thing is a signed, sequence-numbered pointer per writing key.
Yes.
"A signed arrow that only moves forward": "arrow" is never spoken, only drawn. "only goes up" carries the forward motion. Speak "arrow" once or change the card (S2).
No. Beat 1 opens with "each writing key has a pointer" and the writing key is taught in unit 7. Either swap units 6 and 7 (7 depends on nothing in 6 except "pointer", which it could introduce as "its own pointer, a signed arrow to its root"; in practice swapping is awkward) or give unit 6 a first line: "Every write you make is signed by a writing key pair."
Yes, beat 4.
57 s, inside 50-60. Screen at beat 2 is a card plus four fields (S3, borderline).
True to architecture/mutable.html: "a pair of hashes (previous, current) and a monotonically increasing sequence number"; "the server can reject invalid updates"; "clients can cache the most recent version of a pointer to defend against being served stale older versions"; the home node "responsible for synchronising their writes and publishing the latest root hashes". Beat 5's "One node is the home of each pointer" is per user on the page, which amounts to the same thing. One nuance under unit 20.
Verdict: back to 1b only for the dependency (define the writing key before using it); the content passes.
Unit 7: a writer key owns a subtree
Yes.
Yes.
"Cutting a branch onto its own key": "cut" is on screen, not spoken; the script says "give the folder its own new key pair". Low (S2).
Yes (unit 6, once 6 is fixed).
Yes, beat 2.
50 s, inside 45-55.
All on architecture/writer.html and security/cryptree.html: "randomly generated writing key pair which controls writes to their filesystem"; "new writing key pairs for any subtree, for example when granting write access"; "that item is moved to a new writing key pair"; "a given writing key can be quota controlled, to prevent users to which you've granted write access ... from filling your data store". Own champ per writing key is on the champ page.
Verdict: pass.
Unit 8: the cryptree
Yes.
Yes.
"A key that opens every door beneath it": "read everything beneath it" is spoken; "door" is not. Acceptable.
Yes.
Yes, beat 5.
55 s, inside 50-60.
Beats 1 to 4 are on security/cryptree.html almost verbatim ("a tree of symmetric keys, where the holder of one key can decrypt all the descendant keys"; siblings hidden "or even their names"; "Write access is independently controlled by a similar, but simpler cryptree"; "operates independently"). N2 (unsupported). Beat 5: "To share a folder, you hand over its key. Nothing is re-encrypted. Nothing is copied." No page says this. For read sharing it follows from the model. For write sharing the same page says the item "is moved to a new writing key pair", and features/sharing.html (not recorded) says sharing is "achieved cryptographically with capabilities and lazy re-encryption". Fix: "To share a folder for reading, you hand over its key. The data stays where it is." Drop "Nothing is re-encrypted."
Verdict: pass with beat 5 narrowed to read sharing.
Unit 9: a capability is the address and the key together
Yes.
Yes.
"A small card" is spoken.
Mostly. "Token" is introduced here with an inline definition ("a token the server wants before it releases the blob") four units before unit 13 teaches it; acceptable.
Yes, beat 5.
57 s, inside 50-60. S3. The visual language says "A capability is a card with up to four fields", but the script names five fields by beat 3 (owner key, writer key, label, block token, read key) and six with the write key. If the card accumulates, beat 3 shows six things. Fix: draw the card as two regions, "where" and "how", and light one region per beat.
Fields match security/capabilities.html ("The owner is a public key ... The writer is a public key for the mutable pointer. The map key is 32 bytes ... the BAT is 32 bytes which are used to control access to the ciphertext by the server"). Three grades match ("Mirror, Read and Write"; mirror "retrieve the raw ciphertext", read "decrypt and read", write "modify"). N10 (unsupported, low). Beat 4: "A write capability adds the signing key." The capabilities page says "The read and write keys are 256 bit symmetric keys"; the cryptree page says updates are "signed by a corresponding writing key pair". The book is inconsistent with itself. Say "adds the write key" and let unit 8 carry the signing-key model. Beat 5 ("needs no account ... Whoever holds the card can use it") is supported by features/secret.html ("Anyone with a (Javascript enabled) web browser can view such a link") and by the capability model.
Verdict: back to 1b for the screen (six fields on a four-field card) and the "signing key" wording.
Unit 10: sharing seals the card to a friend's key
One idea, but it is attached to the wrong mechanism.
Beats serve the idea as stated.
"Two locks on one seal" is spoken ("the seal uses two locks"). The break is not spoken. The visual-language section says the break "a card can be used by whoever holds it, so sealing it is what makes sharing private" is said in unit 10. It is not; unit 9 beat 5 says the first half and nothing says the second.
Yes (unit 9).
Yes, beat 5.
55 s, inside 50-60.
W5 (wrong mechanism; also X). Beat 1: "To share with a friend, you seal the capability to their public key. Only their secret key can open it." The book puts the asymmetric hybrid on the follow request, not on each share. security/encryption.html: "Sharing files with other users is done through follow requests. Follow requests are asymmetrically encrypted with a hybrid of X25519 and MLKEM." dev/follow.html: once friends, "you can grant read or write access to any file or folder by adding a read or write capability in their directory in your space." features/sharing.html: "achieved cryptographically with capabilities and lazy re-encryption." So the one asymmetric step hands the friend the capability to a shared folder; every later share is a capability written into that folder under cryptree keys the friend already holds. Unit 19 beat 2 has this right ("What you share with them goes in it"), unit 8 beat 5 says sharing is handing over a key, and unit 10 says it is an asymmetric seal per share. Three units, three models. Fix unit 10's idea: "The one asymmetric step in sharing is sealing a folder's capability to a friend's key, and that seal is a hybrid of X25519 and ML-KEM-1024." Beat 1 becomes: "Sharing starts with one sealed message: the capability to a folder you made for that friend. Everything you share later goes into that folder." Then beats 2 to 5 stand. Unit 18 should say the request is the thing sealed this way (M4). N3 (unsupported, benign). Beat 4: "What you share today stays sealed if one of them falls." That is the definition of a hybrid, not a sentence on any recorded page. Keep. Beat 3's names match the home page ("X25519 and MLKEM-1024") and beat 5 matches security/quantum.html ("hashing and symmetric encryption, neither of which are significantly weakened by a quantum computer").
Verdict: back to 1b. Re-anchor the unit on the follow request (W5) and speak the break.
Unit 11: taking access back means new keys
Yes.
Yes.
"Changing the lock after lending a key": "lock" is never spoken; "the folder gets a new key" is. Speak "lock" once (S2).
Yes (unit 8). It would be stronger after unit 13, because the book's one explicit revocation sentence is about BATs; see M5.
Yes, beat 1.
49 s, inside 45-55.
N7 (unsupported recorded statement). The recorded cryptree statement ends "revocation is by re-keying and copying". security/cryptree.html does not mention revocation at all. The pages that do: security/bats.html ("When someone's access to a file or directory is revoked, the BATs are also changed, making it impossible to retrieve the new ciphertext even with previous access"), features/apps.html ("it stops working when the folder's keys change: when the user unshares the folder, or any folder above it, with anyone"), and features/sharing.html ("Access can be revoked at any time whilst maintaining access to anyone else the item is shared with ... with capabilities and lazy re-encryption"). Record these three. With those sources, beats 2 and 4 are supported (keys change on unshare, including folders above; new ciphertext is unreadable with old access). O9 (overstated). Beat 3: "Re-keying means new ciphertext. The old blobs are replaced, not just hidden." No page says old blobs are replaced, and "lazy re-encryption" says the opposite of eager rewriting. Fix: "New writes get new ciphertext. The old blobs are not rewritten; the old key simply opens nothing new." M5 (omission, low). Two true and useful sentences are missing: other people the item is shared with keep their access (sharing page), and the block tokens change too so the former friend cannot even fetch the new blobs (BATs page; only sayable if unit 11 follows unit 13).
Verdict: back to 1b. Record the real sources, fix beat 3, consider moving after unit 13.
Unit 12: a secret link keeps the key after the hash sign
Yes.
Yes.
"The part of the address the postman never reads" is not spoken at all (S2). The script's "Browsers never send that part to a server" is the content; add "like a note the postman never reads" or drop the card's metaphor.
Yes (unit 9).
Yes, beat 2.
51 s, inside 45-55.
Beats 1 to 3 match features/secret.html ("The password (the fragment of the URL) is then used to decrypt the link to get the capability"; "the host applies any expiry or n-use restrictions before returning the encrypted link"; "the key material isn't sent to the server"). Beat 1's "is the key" is a small simplification: the fragment is a password that scrypt turns into the key ("LINKDECRYPTIONPASSWORD", "scrypt hashes"); "is the secret" would be exact. O7 (overstated by misattribution). Beat 4 introduces the optional extra password ("It can also need a password", which the home page lists: "Give a link an expiry, a password, a fixed number of uses"), and beat 5 then says "The password lock is built to take a hundred years to brute force. With a million GPUs." The book's sentence is about the encryption every link carries, keyed from the fragment: "The password based encryption on each link is designed to take 100 years to brute force if you have 1,000,000 GPUs, each of which can do 1M scrypt hashes per second." A viewer will hear beat 5 as a property of the optional password. The script also drops the "1M scrypt hashes per second" qualifier that makes the number mean something. Fix beat 5: "The fragment is a password too. Its lock is built to take a hundred years to break, with a million GPUs each doing a million guesses a second."
Verdict: back to 1b for beat 5's attribution and the number's qualifier.
Unit 13: even the raw blobs need a ticket
Yes, but see question 2.
Beat 5 (the two kinds) is a second thing to remember rather than a second idea; it can stay.
"A ticket that cannot be lent": "cannot be lent" is spoken; "ticket" is only drawn. Say it once; it is the book's own analogy.
Yes (unit 4). "Mirror" is introduced here in passing ("so another server can copy everything you own") and that is enough for units 14 and 17.
Yes, beat 1.
62 s, inside 55-65.
W2 (wrong; also X with unit 9). Beat 3: "The token is a signature. Time limited. It names the block, and it is tied to the asking node's key. It cannot be lent." security/bats.html separates two things: the auth string sent with a request, which "is an S3 V4 signature, which is time-limited, includes the CID, and is tied to the requesting node's public key", and the token, which is the secret it is made from: "Such a secret key would grant the holder access to the block, so we call it a Block Access Token or BAT for short, and each is 32 bytes long." The BAT is the 32-byte secret that lives in the capability (unit 9 beat 3). The script calls the secret a signature and says it cannot be lent, while unit 9 beat 5 says "Whoever holds the card can use it", and the card holds the BAT. Both cannot be true, and the book's version is: the token can be handed on; the signed request made from it cannot. Fix beat 3: "The token is a secret. From it your node signs each request. Time limited, naming the block, tied to your node's key. That signed request cannot be lent." O2 (overstated). Beat 2: "Peergos pairs every block with a block access token." The page says "an optional auth string paired with every CID" and "we also need to support raw blocks that do not have a BAT (either legacy blocks or ones specifically made public)". Fix: "pairs your blocks with". M2 (omission). The series never says the sentence that reconciles unit 3's "Any Peergos node can serve it" with tokens: "any instance that retrieves such a block (after being authorised) can continue to serve it up and enforce the same access control, thus maintaining the autoscaling properties in a privacy-preserving way." Without it, a viewer who holds units 3 and 13 together has no way to see how a second node could check a token for a block it did not create. Add one line to beat 2 or beat 5. Beat 1's "Sizes, timing, which blocks go together" adds "timing", which the page does not list; it does say the server "cannot link the different blocks of a file to deduce the padded size". Low; folded into N4. Beat 4 and beat 5 are on the page ("Each 5 MiB chunk of a file or directory has its own unique BAT"; "One is inline - and specific to that block only. The other is a user wide 'mirror' BAT ... for when a user wants to mirror all their data on another instance, or migrate").
Verdict: back to 1b for W2, O2 and M2.
Unit 14: what the server can still see
Yes.
Yes.
"A short list beside the server" is a screen description, not a physical metaphor; acceptable for a list unit.
Yes.
Yes, beat 1.
49 s, inside 45-55. S3. Screen at beat 4 crosses out five things ("names, sizes, folders, thumbnails, who you share with"). Split across two beats or cut one.
M1 (omission that produces a wrong model) and N4 (unsupported). security/threats.html lists exactly two things a home server can see: "total space used (rounded up due to padding before encryption)" and "total number of secret links and any expiry, use limit and use count". The script keeps the first, drops the second, and adds two the page does not list: "Which writer keys exist, and when writes happen." Writer keys and timing are visible by construction (architecture/mutable.html: pointers are keyed by writer public key; every request has a time), but the page the unit cites as its source does not say so, and the recorded statement for this page does say "secret link metadata", which the script then leaves out. The net effect is a viewer who believes the server cannot see how many secret links they have or how often they are used, which the book says it can. Fix beat 3: "How many secret links you have, and their expiry and use counts. And, by construction, which writer keys exist and when they write." Or drop the by-construction items. Beat 2's "Storage has to be paid for, so that number is honest" is editorial (S8); say "rounded up by the padding" instead, which is what the page says. Beat 4's hidden list and beat 5's Tor line match the threats page and security/meta.html ("The metadata around access patterns will be hidden by hosting files behind a tor hidden service once Tor is integrated").
Verdict: back to 1b for M1 and the five-item screen.
Unit 15: usernames live in one append-only log
Yes.
Yes.
"A ledger copied to everyone": "ledger" is not spoken ("log" is); low (S2).
Yes (unit 2's identity key). "Key transparency log" is used in beat 5 as a comparison and never defined (S1); the audience probably knows it, but the guide's rule applies.
Yes, beat 1.
53 s, inside 50-60.
Beats 1 to 4 match architecture/pki.html ("names taken on a first come first served basis. This needs consensus"), dev/signup.html ("a signed username claim including an expiry, and the ipfs node id of the storage server ... Send this claim to the pki node for confirmation"), architecture/physical.html ("mirrored on every node") and security/pki.html ("Mirrors reject updates that are not append-only, so the pki cannot tamper with the mappings"). O8 (overstated, low). Beat 5: "It works like a key transparency log." The page says the effect "is similar to certificate or key transparency logs" and then draws the contrast: "key transparency logs are not normally used as the source of truth, but only checked retrospectively ... So this gives much stronger guarantees." Also "without every mirror noticing" is weaker than the page's "Mirrors reject". Fix: "Mirrors do not just notice a rewrite, they refuse it. Like a key transparency log, but used as the source of truth."
Verdict: pass with beat 5 tightened.
Unit 16: your home server is where your pointers live
Yes.
Yes.
"A home with a forwarding address": "home server" is spoken; "forwarding" is not (S2).
"Follow requests" (beat 1) are used two units before unit 18 defines them (S1). One clause: "the requests other users send you".
Beat 4 addresses it, but see X2.
49 s, inside 45-55.
Beats 1, 2 and 5 match architecture/physical.html ("at least one Peergos server (which includes an instance of IPFS). This server stores their data, their mutable pointers and any pending follow requests"), dev/upload.html ("can be done through any Peergos server") and features/self.html. O3 (overstated). Beat 3: "The server in the middle cannot read it." dev/proxy.html says the request goes "through an end to end encrypted stream through the ipfs network to the destination node", and the stream is opened by "the http p2p proxy exposed locally on the ipfs gateway" of the server you are talking to. That server is the stream's origin and sees the request it forwards. The encryption protects against the network, not against the proxying server. What makes it safe is unit 3 and unit 6: the write is ciphertext and a signed pointer, so there is nothing for the middle server to read. The check question ("What can the server in the middle read of a proxied write?") expects "nothing"; the true answer is "the same ciphertext and signed pointer any server sees". Fix beat 3: "A write is forwarded to your home node over an encrypted peer to peer stream. What travels is ciphertext and a signed pointer, so the server that forwards it learns nothing it could use." X2 (cross-unit). Beat 4: "There is no central server anywhere." Unit 15 beat 3, one unit earlier: "one node, the PKI node, confirms each claim." The README also says "There is a pki node which ensures unique usernames". features/p2p.html says "There is no central surveillance point" and "no central dns name or TLS certificate authority", which is the claim to make. Fix: "No central server stores your data or watches it move."
Verdict: back to 1b for O3 and X2.
Unit 17: moving home takes your identity with you
One idea, with beat 5 (mirroring) as the continuous form of the copy step. Borderline but it serves.
Yes.
"Moving house and keeping your name": "To move", "home", "The name ... yours" carry it.
Yes.
Yes, beat 4.
45 s, at the bottom of 45-55; it lands.
Matches features/migration.html ("mirror all your data locally, and then update the PKI so this is your new home server"; "no one you've shared with needs to do anything"), features/secret.html ("all pre-existing secret links will continue to work") and features/mirror.html ("continuously mirror the user's data"). O10 (overstated, low). Beat 5: "If your home goes down, the mirror has everything." Only if login data was mirrored too; the mirror page has that as a separate step ("Mirror your login data on this server"). Say "the mirror has your data" or "has everything, login data included, if you asked it to".
Verdict: pass with beat 5 softened.
Unit 18: a follow request reveals only who it is for
Yes.
Yes.
"An envelope with only the recipient's name on the outside": "envelope" is not spoken (S2); "sealed" and "The only thing in the clear is who it is for" carry it.
Yes (units 10 and 16).
Yes, beat 2.
53 s, inside 50-60.
Beats 1, 2, 3 and 5 match architecture/follow.html ("no unencrypted data visible to the network, or server, apart from the target user"; stored on the recipient's server, "not actually stored in ipfs itself"), security/social.html ("sent encrypted from a random single use keypair"; "stores the capability in their own storage, symmetrically encrypted and deletes the follow request from their server") and dev/follow.html ("Using a random keypair ensures that noone but the target friend can see who sent the request"). W4 (wrong direction). Beat 4: "Accepting means handing back a capability to a shared folder." The capability travels in the request, from sender to recipient, and accepting keeps it; handing one back is a separate act the page calls reciprocating. dev/follow.html: "Create a directory /our-name/shared/friend-name. Encrypt a read capability for that directory using a random key pair to the target's following key ... The target can then either allow and reciprocate (full bi-directional friendship), allow (you are following them), reciprocate (they are following you) or deny." And on receipt: "you add the capability in the request to a file in your home dir ... before deleting the follow request". The recorded statement ("acceptance grants 'a read capability to a shared directory'") is a misreading of this. Fix beat 4: "The request carries a capability to a folder the sender made for you. Accept, and you keep it. Send one back, and you are friends both ways." (The book's pages disagree with each other about which way "following" points; the script should not assert more than the dev page does.) M4 (omission). This is where the X25519 + ML-KEM-1024 seal lives (security/encryption.html, quoted under W5), and the unit never says so. One clause in beat 1: "sealed to their public key, with the same two locks as any share".
Verdict: back to 1b for W4 and M4.
Unit 19: the social graph is folders
Yes.
Beat 5 does not serve it; it is wrong (W3).
"A friendship is a folder" is spoken.
Yes.
Yes, beat 4.
45 s, at the bottom of the range, and thin: after W3 is cut it needs a beat.
Beat 1 is supported by security/threats.html ("your friend or followers list" hidden) and security/pki.html ("Users also store the keys of their friends in their own filesystem"). Beat 2 by dev/follow.html. N5 (unsupported by recorded sources). Beat 3: "Your social feed is just those folders, read together. New files in them are new posts." No recorded page describes the feed. features/social.html (not in the brief, fetched for this review) says "Files your friends share with you appear in your newsfeed." That supports the second sentence; "just those folders, read together" is still a guess. Record the page and say what it says. W3 (wrong; also X with unit 14). Beat 5: "Two friends open the same file. The server cannot tell they are friends." security/meta.html: "The metadata around access patterns will be hidden by hosting files behind a tor hidden service once Tor is integrated. This will ensure that when one user reads a file shared with them by a friend this access does not leak to the network the fact that they are friends." Today it can leak; unit 14 beat 5 says so ("Access patterns are the open item"). The recorded statement ("two friends accessing a shared file do not disclose 'the fact that they are friends'") drops the "once Tor is integrated". Fix: either cut beat 5 or invert it: "Two friends open the same file. Today, that pair of reads is the one thing that could give them away. Hiding it is the Tor work." Beat 4's "The server sees sealed cards move" is a metaphor, but it implies the server watches a transfer between two users. A share is a write into your own space (dev/follow.html: "adding a read or write capability in their directory in your space"). Say that: "The server sees you write to your own space. It does not learn who follows whom." Low.
Verdict: back to 1b for W3 and N5.
Unit 20: trust nothing you did not verify
Borderline two ideas: beats 1 to 3 are "a server can only store, serve or refuse"; beats 4 and 5 are "where the remaining trust goes, at three levels". Beat 4 opens with "And one more thing", which is the guide's "also" test. The card frames both as the edge of one claim, and the unit lands in 54 s, so it can stay as one if beat 4's opener is cut and the three levels are stated as "three ways to get a real client" rather than a new topic (S4).
See above.
"Checking the seal on everything that arrives": "seal" not spoken; "checks the hash ... the signature" is (S2).
Yes.
Yes, beat 3.
54 s, inside 50-60.
Beats 1, 2 and 4 match security/trust.html ("verifies the hash of every block read from or written to a Peergos server ... verify the signature of every signed piece of data ... once you have obtained a trustworthy copy of a Peergos client you do not need to trust a server"). N6 (unsupported). Beat 3: "Availability is the trust that remains." The recorded statement attributes "remaining trust: availability" to the trust page, which does not say it; the README comes closest ("A User must have at least one Peergos instance storing their data for it to be available"). Reasonable; record the README line. Note too that "can only store and serve" is a little strong: architecture/mutable.html defends against stale roots by client caching, so a server can still serve an old root to a client that has never seen a newer one. One clause if wanted; otherwise leave. Beat 5 matches security/threats.html (casual: web over TLS; slightly paranoid: "download and run the Peergos application and access the web interface through their browser over localhost"; more paranoid: "download the Peergos application (or otherwise obtain a signed copy), or build it from source" and use the native UI). S5. The screen labels the middle user "local build" while the script says "run a local copy"; the page's middle case is a downloaded app, not a build. Change the label.
Verdict: pass with beat 4's opener cut, the screen label fixed, and the availability source recorded.
Unit 21: apps run in their own origin with no permissions
Yes: the sandbox.
Yes.
"A room with one door and a doorman" is never spoken (S2). "go through a service worker to the main Peergos tab, which checks them" is the content; say "one door, and a doorman" on beat 3 or change the card.
Yes (unit 9). "Service worker" and "origin" are undefined technical terms; the audience knows them (S1, low). The screen at beat 2 says "in its own process", which the script does not say (S5).
Beat 3 addresses it, but overstates (O4).
57 s, inside 50-60.
Beats 1, 2 and the first half of 4 match features/apps.html ("plain HTML/Javascript/CSS packaged in a folder"; "a unique hostname (sha256(app path).$peergos-domain)"; "isolated from the main peergos domain in a separate OS process, and from other apps"; "By default, an app has no permissions and can only read its own assets"). Beat 5's first sentence matches "Running an app also doesn't reveal its assets to the server". O4a (overstated security claim). Beat 3: "It cannot reach the network." Beat 5: "An app cannot track you, because it cannot phone home." The page says the app domain "cannot make any external requests which could be used to exfilrate data [0]" and footnote [0] reads: "This is currently not true until browsers implement webrtc CSP which blocks any webrtc connections ... So only install apps from authors you trust for now, unless they don't require any permissions which is safe." The script states as finished a guarantee the source says is not yet true. Fix beat 3: "It is locked down so it cannot make outside requests. One browser gap, WebRTC, is still open, so for now install only apps you trust." Beat 5's "cannot phone home" then needs "once browsers close that gap" or should be cut. O5 (overstated). Beat 4: "Anything more, you grant in a dialog, and can revoke." The page: "Most permissions are declared in the app's manifest, but access to folders in the user's drive is granted at runtime instead: the app asks, the user chooses a folder and approves it in a dialog, and they can revoke it at any time." Fix: "Other permissions are declared in its manifest. Access to one of your folders you grant in a dialog, and can revoke."
Verdict: back to 1b for O4a and O5.
Unit 22: a private website is a folder
Yes.
Yes.
"A website that is just a folder" is spoken.
Yes (unit 21).
Yes, beat 3.
48 s, inside 45-55.
Beats 2, 3 and 5 match features/private-web.html ("viewed using a built-in browser app. This browser isolates websites from different owners using different sub domains"; "share websites privately with friends ... the same way you share any file or folder ... via a secret link"; "link to any other websites in Peergos ... by the human readable path"). N9 (unsupported, low). Beat 1: "Put an index page in it, and it is one." The private-website page does not mention an index page; the apps page requires index.html for apps. Probably true; record or soften. O4b (overstated security claim). Beat 4: "No information can leave the page. Third party tracking is impossible. Fingerprinting learns nothing." The page: "external communication is impossible [0] ... 3rd party tracking is impossible ... 1st party tracking is also not easy (and can be made impossible) ... browser fingerprinting is irrelevant for such websites because no information can be exfiltrated!" with the same footnote: "[0] This is currently not true until browsers implement the webrtc CSP". Same fix as unit 21: state the lockdown and name the WebRTC gap once. Since unit 21 already carries it, unit 22 can say "with the same one gap".
Verdict: back to 1b for O4b.
Unit 23: sync copies only the changed chunks
Yes, with beat 5 (concurrency) as a near-second idea (S4, low).
Yes.
"Two folders kept equal by sending only the differences" is spoken.
Yes (unit 4).
Yes, beat 2.
48 s, inside 45-55.
Beats 1 to 4 match features/sync.html ("bi-directional syncing between a local folder and a peergos folder ... including deletes (optional)"; "If a large file changes it only copies the changed chunks"; "Syncing local deletes ... Syncing remote deletes"; "the same link to sync on multiple different devices at the same time") and the 2025 post ("A full-featured Android app ... bi-directional sync"). Beat 4's "all holding one copy" reads oddly; "each holding a copy" (S9). O6 (overstated; wrong mechanism). Beat 5: "Two devices change things at once? Since twenty twenty five, concurrent modification is handled automatically in most cases." Screen: "two edits at once, merged." The 2025 post: "We now have automatic concurrent modification handling in most circumstances. Previously, if you uploaded a file whilst editing a totally unrelated file, then saving the changes would result in a concurrent modification exception from the server. Now we handle these automatically if there isn't a genuine conflict, i.e. a concurrent change to the same file or dir." So what is handled is two unrelated writes racing on the same pointer; a real conflict on the same file is not handled, nothing is merged, and the post files this under the filesystem ("Towards a CRDT"), not the sync engine. Fix: "Two devices write different files at once? Since 2025 that no longer fails. The same file changed in two places is still a real conflict." Change the screen from "merged" to "both land".
Verdict: back to 1b for O6.
Unit 24: where Peergos stands
Yes: a status unit.
Yes.
"A year in numbers" is not physical; acceptable for a status unit.
Yes.
Yes, beat 1.
56 s, inside 50-60. Screen at beat 3 is a badge with four numbers (S3, borderline).
Every number is on its page: "20 releases, more than double last year's 8"; "Native desktop apps (Windows, macOS, Linux)", "A full-featured Android app"; "50-150x Faster folder loading" (script says "up to a hundred and fifty", correct); "0 extreme, high or elevated risk vulnerabilities ... 2 moderate, and 6 low risk issues found, and all of these are fixed now" by Radically Open Security; "tripled our number of paying customers"; "2026 will be about polish, usability, iOS and deeper OS integration". One small omission: the audit post calls it "our 2nd security audit" and the home page names both firms ("Radically Open Security and Cure53"); "A second security audit, in 2024" costs one word and is more accurate.
Verdict: pass.
Series-wide findings
S1. Terms used before they are defined. Key pair, symmetric key, capability and home server (unit 2); read capability (unit 4); writing key (unit 6); follow requests (unit 16); key transparency log (unit 15); service worker and origin (unit 21). No unit says what a key pair or a signature is. The audience may know, but the guide's rule is dependencies on ideas, and the Anytwo series paid for skipping this. One line in unit 1 or the top of unit 2 ("An account is a few key pairs: a public half that names you, a secret half that signs or opens, and none of them live on a server") would cover most of it.
S2. Card metaphors the script never speaks. Units 3 (fingerprint), 6 (arrow), 7 (cut branch), 11 (lock), 12 (postman), 15 (ledger), 16 (forwarding address), 18 (envelope), 20 (seal), 21 (room and doorman). Unit 10's break is claimed as spoken and is not. The guide's rule is explicit: a card's metaphor must be spoken. Either say each one once, on the beat whose screen draws it, or change the card to what the script does say.
S3. Screens with more than four things. Unit 2 beat 5 (bundle, key, three contents); unit 9 beats 2 to 3 if the card accumulates (five, then six fields, on a card the visual language says has "up to four"); unit 14 beat 4 (five crossed-out items); borderline: unit 6 beat 2 (card plus four fields), unit 24 beat 3 (badge plus four numbers).
S4. Two ideas. Unit 20 (server trust, then three levels of client trust, joined by "And one more thing"). Borderline: unit 17 (migration plus mirroring), unit 23 (sync plus concurrency). None needs splitting if the second part is kept to one beat and its opener is not an "also".
S5. Screen labels the narration does not say. Unit 20 beat 5 "local build" (script: "run a local copy"; page: a downloaded app); unit 21 beat 2 "in its own process".
S6 to S9. Unit 4 beat 3 cipher name drop; unit 14 beat 2 "so that number is honest"; unit 23 beat 4 "all holding one copy"; unit 12 drops a number's qualifier (under O7).
Length. Nothing is too long. Units 17 and 19 sit at 45 s; 17 lands, 19 will not once beat 5 is cut and needs a beat that says what the feed is (from features/social.html).
Units the audience could not follow from earlier units alone. Unit 6 (writing key before unit 7). Unit 2 (key pair, symmetric key, capability, home server). Everything else is ordered correctly.
Recorded source statements that misstate their page. Three: cryptree "revocation is by re-keying and copying" (N7, page silent); follow requests "acceptance grants a read capability" (W4, the capability is in the request); metadata "two friends accessing a shared file do not disclose the fact that they are friends" (W3, the page says this will hold once Tor is integrated). Two pages the series needs are not recorded at all: features/sharing.html and features/social.html.
Recommended changes, most important first
Re-anchor sharing on the follow request (units 10, 18, 8, 19). The hybrid X25519 + ML-KEM-1024 seal is on the follow request, which carries the capability to a per-friend shared folder; later shares are capabilities written into that folder. Rewrite unit 10's idea and beat 1 (W5), make unit 18 say the request is the sealed thing and that accepting keeps the capability that came in it (W4, M4), narrow unit 8 beat 5 to read sharing (N2), and make unit 19 beat 4 say a share is a write to your own space. Record features/sharing.html and features/social.html.
Fix the block access token (unit 13). The token is a 32-byte secret in the capability; the signed request made from it is what is time-limited, names the block, is tied to the node's key and cannot be lent (W2). Say that a node which fetched a block with a valid token can serve it on and enforce the same token (M2); this is what makes unit 3's "any node can serve it" true. Change "every block" to "your blocks" (O2).
Correct the two friends-reading claims (units 19 and 14). Cut or invert unit 19 beat 5 (W3); it contradicts unit 14 beat 5 and the metadata page. Fix the recorded statement.
Carry the book's own caveat on the sandbox (units 21 and 22). State the lockdown and name the WebRTC gap once, with the page's advice to install only trusted apps for now (O4a, O4b). Fix "grant in a dialog" to manifest-declared permissions plus a dialog for folder access (O5).
List what the server sees as the threats page lists it (unit 14). Add secret-link count, expiry and use counts; mark writer keys and timing as by construction or drop them (M1, N4). Split the five-item screen.
Fix the login unit (unit 2). The password never leaves the device; the username does (W1). Say the salt comes from the home server (M6). Add one line defining key pair and symmetric key here or in unit 1 (S1), and cut the beat 5 screen to four things.
One root per writing key (unit 5 beat 5), so it stops contradicting unit 7 (X1).
Define the writing key before unit 6 uses it (one opening line or a swap of 6 and 7).
Proxying and "no central server" (unit 16). The forwarding server sees ciphertext and a signed pointer, which is why it does not matter (O3); say "no central server stores or watches your data" rather than "anywhere", since unit 15 just taught the PKI node (X2). Fix the check question's expected answer.
Sync concurrency (unit 23 beat 5). Unrelated writes no longer fail; same-file conflicts are still conflicts; nothing is merged (O6).
Secret-link password (unit 12 beat 5). Attach the hundred-year figure to the fragment's own encryption and restore "a million scrypt hashes per second" (O7).
Revocation (unit 11). Record the BATs, apps and sharing pages as the sources (N7); replace "The old blobs are replaced" with lazy re-encryption's actual promise (O9); optionally move after unit 13 and add that tokens change and other sharers keep access (M5).
Speak every card metaphor or change the card (S2, ten units plus unit 10's break).
Capability card layout (unit 9). Two regions, "where" and "how", lit one at a time; say "write key" not "signing key" (N10).
Small wording fixes. Unit 4 "not written anywhere" to "the server never learns" (O1); unit 15 beat 5 (O8); unit 17 beat 5 (O10); unit 20 beat 4 opener and the "local build" label (S4, S5); unit 24 "second audit"; record the README availability line for unit 20 (N6); unit 22 index page (N9); cut or keep the cipher name in unit 4 (S6).
Tally
Class | Count | Ids |
|---|---|---|
Wrong | 5 | W1 (username sent), W2 (BAT is a signature), W3 (friends reading same file), W4 (accept hands back a capability), W5 (seal on every share) |
Overstated | 12 | O1, O2, O3, O4a, O4b, O5, O6, O7, O8, O9, O10, and N4's "timing" folded in |
Unsupported by recorded sources | 9 | N1, N2, N3, N4, N5, N6, N7, N9, N10 |
Cross-unit inconsistency | 2 standalone, 3 more inside W2, W3, W5 | X1 (one root), X2 (no central server) |
Omission producing a wrong model | 4 | M1 (secret-link metadata), M2 (nodes re-serve with the same token), M4 (seal lives in the follow request), M5 (revocation leftovers), plus M6 (salt origin, low) |
Structure and style | 9 groups | S1 terms before definition (9 terms), S2 unspoken metaphors (10 units + 1 break), S3 crowded screens (3 clear, 2 borderline), S4 two ideas (1 clear, 2 borderline), S5 unspoken labels (2), S6 to S9 wording (4) |
Accuracy findings: 32 (5 wrong, 12 overstated, 9 unsupported, 2 cross-unit, 4 omissions). Verdicts: 8 pass (units 1, 3, 7, 8, 15, 17, 20, 24), 16 back to 1b (units 2, 4, 5, 6, 9, 10, 11, 12, 13, 14, 16, 18, 19, 21, 22, 23). Length: all 24 inside target; none too short to land once unit 19 gets a replacement beat.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime